@nanobpm/urban 0.27.0 → 0.28.0

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

@@ -23,6 +23,12 @@ export interface PagesDeps {
     engine: EngineClient;
     /** Read a page file; injectable for tests. */
     readPage(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"`.
+     * Optional; when absent the index is empty. Injectable for tests.
+     */
+    listPages?(): Promise<string[]>;
 }
 /**
  * Build the page-runtime routes over an injected datasource + engine. Pure over its deps

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

@@ -34,7 +34,7 @@ export function createPagesRoutes(opts, deps) {
     const rowLimitRaw = opts.rowLimit ?? 200;
     const rowLimit = Number.isFinite(rowLimitRaw) ? Math.max(0, Math.floor(rowLimitRaw)) : 200;
     const sourceName = opts.sourceName ?? "app";
-    const { db, engine, readPage } = deps;
+    const { db, engine, readPage, listPages } = deps;
     // 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
     // refreshes grids repeatedly — re-introspecting on every `/app/data` hit would be a hot
@@ -75,6 +75,36 @@ export function createPagesRoutes(opts, deps) {
         source: "surface:pages",
         handler: () => javascript(RENDERER_JS),
     });
+    // ── GET /app/pages (index of available pages) ───────────────────────────
+    // 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
+    // appears by id) and a `home` flag. Registered as an exact path so it never
+    // shadows the `/app/pages/<id>` prefix route below.
+    routes.push({
+        method: "GET",
+        path: "/app/pages",
+        source: "surface:pages",
+        handler: async () => {
+            const ids = listPages ? await listPages().catch(() => []) : [];
+            const pages = [];
+            for (const id of ids) {
+                if (!/^[A-Za-z0-9_-]+$/.test(id))
+                    continue;
+                let title = id;
+                try {
+                    const doc = JSON.parse(await readPage(`${pagesDir}/${id}.page.json`));
+                    if (isRecord(doc) && typeof doc.title === "string" && doc.title)
+                        title = doc.title;
+                }
+                catch {
+                    // Unreadable or non-JSON page: still list it by id.
+                }
+                pages.push({ id, title, home: id === homePage });
+            }
+            return json({ pages, home: homePage });
+        },
+    });
     // ── GET /app/pages/<id> ─────────────────────────────────────────────────
     routes.push({
         method: "GET",
@@ -297,6 +327,13 @@ export function mountPages(ctx, app) {
         db: app.data.open(sourceName),
         engine: app.engine,
         readPage: (p) => ctx.host.readTextFile(p),
+        listPages: async () => {
+            const dir = opts.pagesDir ?? "pages";
+            const names = await ctx.host.listDir(dir).catch(() => []);
+            return names
+                .filter((n) => n.endsWith(".page.json"))
+                .map((n) => n.slice(0, -".page.json".length));
+        },
     });
     ctx.host.log("info", "pages surface mounted", { source: sourceName, home: opts.homePage ?? "home" });
     return {
@@ -400,6 +437,22 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-collapse-header { display:flex; align-items:center; gap:.5rem; width:100%; margin:0 0 .75rem; padding:0; background:transparent; border:0; color:inherit; font:inherit; font-size:1rem; font-weight:600; cursor:pointer; text-align:left; }
 .pc-chevron-inline { color:var(--nano-text-faint); font-size:.75rem; width:1em; }
 .pc-card-body[hidden] { display:none; }
+/* Multi-page navigation: a horizontal menu bar or a vertical side rail. */
+.pc-layout { display:flex; gap:1.5rem; align-items:flex-start; }
+.pc-rail-wrap { flex:0 0 12rem; position:sticky; top:1rem; align-self:flex-start; }
+.pc-main-col { flex:1 1 auto; min-width:0; }
+.pc-nav-title { font-weight:650; }
+.pc-bar { display:flex; align-items:center; gap:.6rem; flex-wrap:wrap; border-bottom:1px solid var(--nano-edge); padding-bottom:.6rem; margin-bottom:1.25rem; }
+.pc-bar .pc-nav-title { margin-right:.5rem; }
+.pc-bar .pc-nav-items { display:flex; gap:.25rem; flex-wrap:wrap; }
+.pc-rail { display:flex; flex-direction:column; gap:.5rem; }
+.pc-rail .pc-nav-title { margin-bottom:.25rem; padding:0 .7rem; }
+.pc-rail .pc-nav-items { display:flex; flex-direction:column; gap:.15rem; }
+.pc-nav-link { display:flex; align-items:center; gap:.4rem; padding:.4rem .7rem; border-radius:.4rem; color:var(--nano-text-muted); text-decoration:none; font-size:.9rem; }
+.pc-nav-link:hover { background:var(--nano-hover); color:var(--nano-text); }
+.pc-nav-link.active { background:var(--nano-accent); color:var(--nano-on-accent); }
+.pc-nav-icon { line-height:1; }
+.pc-nav-empty { color:var(--nano-text-faint); font-size:.85rem; padding:.4rem .7rem; }
 `;
 // The schema-driven browser renderer (ADR 0042 §3). Plain ES module string served at
 // /app/runtime.js — it does NOT ship Craft.js (authoring is console-side only). It
@@ -409,6 +462,37 @@ const RENDERER_JS = String.raw `
 const root = document.getElementById("page");
 const HOME = root.dataset.home || "home";
 
+// ── Multi-page routing (hash-based, reverse-proxy safe) ──────────────────
+// Pages are selected by the URL fragment (#/<page>) so navigation never hits
+// the server and works identically at the origin root and under the Nano
+// console's /console/app-view/<name>/ path-prefixed proxy (the hash is never
+// sent upstream). An empty/invalid hash falls back to the home page. Only a
+// safe id charset is accepted so the fragment can't smuggle a path/URL.
+const PAGE_ID = /^[A-Za-z0-9_-]+$/;
+function safePageId(value) {
+  return typeof value === "string" && PAGE_ID.test(value);
+}
+function currentPage() {
+  try {
+    const raw = decodeURIComponent((location.hash || "").replace(/^#\/?/, ""));
+    return safePageId(raw) ? raw : HOME;
+  } catch (e) {
+    return HOME;
+  }
+}
+let CURRENT = currentPage();
+
+// Per-render teardown. Each dataGrid registers its poll interval + pc:refresh
+// listener here; navigating to another page runs every disposer before the new
+// page renders, so a switched-away grid stops polling (otherwise every visited
+// page would leave a live setInterval fetching forever).
+const disposers = [];
+function teardown() {
+  while (disposers.length) {
+    try { disposers.pop()(); } catch (e) { /* best-effort cleanup */ }
+  }
+}
+
 // Theme bridge for the Nano console embed. The app runs in a sandboxed,
 // same-origin iframe, so the console's --nano-* custom properties and its
 // data-appearance never cascade in. Instead the console postMessages its
@@ -857,15 +941,71 @@ function renderDataGrid(node) {
     }
   }
   document.addEventListener("pc:refresh", refresh);
+  disposers.push(() => document.removeEventListener("pc:refresh", refresh));
   // Skip the automatic poll while the user is typing in the grid — an explicit pc:refresh
   // (e.g. after submitting an answer) still runs — so rows never shift under an in-progress
-  // answer and the detail input keeps focus across ticks.
-  if (p.refreshMs && p.refreshMs > 0) setInterval(() => { if (!editingInGrid()) refresh(); }, p.refreshMs);
+  // answer and the detail input keeps focus across ticks. The interval is registered as a
+  // disposer so a page switch (hashchange → renderPage → teardown) stops it.
+  if (p.refreshMs && p.refreshMs > 0) {
+    const timer = setInterval(() => { if (!editingInGrid()) refresh(); }, p.refreshMs);
+    disposers.push(() => clearInterval(timer));
+  }
   refresh();
   return card;
 }
 
-const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid };
+// 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.
+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;
+  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 {
+    attrs.href = item.href; attrs.target = "_blank"; attrs.rel = "noopener noreferrer";
+  }
+  const kids = [];
+  if (item.icon != null) kids.push(el("span", { class: "pc-nav-icon" }, String(item.icon)));
+  kids.push(el("span", { class: "pc-nav-label" }, String(item.label != null ? item.label : (item.page || item.href))));
+  return el("a", attrs, ...kids);
+}
+function fillNav(list, items) {
+  list.replaceChildren();
+  let n = 0;
+  for (const item of items || []) {
+    if (!item || typeof item !== "object") continue;
+    const a = navLink(item);
+    if (a) { list.append(a); n++; }
+  }
+  if (!n) list.append(el("span", { class: "pc-nav-empty" }, "No pages"));
+}
+function renderNav(node) {
+  const p = node.props || {};
+  const rail = p.variant === "rail";
+  const nav = el("nav", { class: rail ? "pc-nav pc-rail" : "pc-nav pc-bar" });
+  if (p.title != null) nav.append(el("div", { class: "pc-nav-title" }, String(p.title)));
+  const list = el("div", { class: "pc-nav-items" });
+  nav.append(list);
+  const items = p.items;
+  if (Array.isArray(items)) {
+    fillNav(list, items);
+  } else {
+    // "auto" (or unspecified): enumerate every page and link to each.
+    getJSON("/app/pages")
+      .then((res) => fillNav(list, (res.pages || []).map((pg) => ({ label: pg.title || pg.id, page: pg.id }))))
+      .catch(() => list.append(el("span", { class: "pc-nav-empty" }, "No pages")));
+  }
+  return nav;
+}
+
+const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid, nav: renderNav };
 
 // 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,
@@ -920,7 +1060,7 @@ function makeCollapsible(node, card) {
     chevron,
     el("span", { class: "pc-collapse-title" }, titleText),
   );
-  const storageKey = "pc:collapsed:" + HOME + ":" + (node.id || titleText);
+  const storageKey = "pc:collapsed:" + CURRENT + ":" + (node.id || titleText);
   let collapsed = readCollapsed(storageKey, !!props.defaultCollapsed);
   function apply() {
     body.hidden = collapsed;
@@ -937,16 +1077,30 @@ function makeCollapsible(node, card) {
   return container;
 }
 
-async function main() {
+// Render the page named by the current hash route. A rail nav is lifted into a
+// left <aside> and the rest of the nodes flow into a content column; otherwise
+// (bar nav or none) nodes render in document order. Re-runs on every hashchange,
+// tearing down the previous page's grid polls first.
+async function renderPage() {
+  teardown();
+  CURRENT = currentPage();
   try {
-    const doc = await getJSON("/app/pages/" + encodeURIComponent(HOME));
-    if (doc.title) document.title = doc.title;
-    root.replaceChildren(
-      ...(doc.nodes || []).map((n) => makeCollapsible(n, (RENDERERS[n.type] || (() => el("div")))(n))),
-    );
+    const doc = await getJSON("/app/pages/" + encodeURIComponent(CURRENT));
+    document.title = (doc && doc.title) || "Urban App";
+    const nodes = (doc && doc.nodes) || [];
+    const built = nodes.map((n) => ({ n, node: makeCollapsible(n, (RENDERERS[n.type] || (() => el("div")))(n)) }));
+    const rail = built.find((b) => b.n.type === "nav" && b.n.props && b.n.props.variant === "rail");
+    if (rail) {
+      const col = el("div", { class: "pc-main-col" });
+      for (const b of built) if (b !== rail) col.append(b.node);
+      root.replaceChildren(el("div", { class: "pc-layout" }, el("aside", { class: "pc-rail-wrap" }, rail.node), col));
+    } else {
+      root.replaceChildren(...built.map((b) => b.node));
+    }
   } catch (e) {
-    root.replaceChildren(el("p", { class: "pc-msg err" }, "Failed to load page: " + String(e.message || e)));
+    root.replaceChildren(el("p", { class: "pc-msg err" }, "Failed to load page: " + String((e && e.message) || e)));
   }
 }
-main();
+window.addEventListener("hashchange", renderPage);
+renderPage();
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.27.0",
+  "version": "0.28.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/core/modules/pages.test.ts

@@ -65,12 +65,14 @@ function build(dbOverrides: Partial<PagesDataSource> = {}) {
   const db = fakeDb(dbOverrides);
   const readPage = async (path: string) => {
     if (path === "pages/home.page.json") return JSON.stringify({ title: "Home", nodes: [] });
+    if (path === "pages/epic.page.json") return JSON.stringify({ title: "Epic Coordination", nodes: [] });
     throw new Error("not found");
   };
   const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app" }, {
     db,
     engine,
     readPage,
+    listPages: async () => ["home", "epic"],
   });
   const router = makeRouter(routes);
   return { router, calls };
@@ -212,8 +214,9 @@ test("renderer makes collapsible nodes persist their state across sessions", asy
   assert.match(js, /if \(!props\.collapsible\) return card;/);
   // Seed from defaultCollapsed the first time, then from persisted state.
   assert.match(js, /readCollapsed\(storageKey, !!props\.defaultCollapsed\)/);
-  // Namespaced, per-node storage key.
-  assert.match(js, /"pc:collapsed:" \+ HOME \+ ":" \+ \(node\.id/);
+  // Namespaced, per-node storage key — keyed by the *current* page id so two
+  // pages that reuse a node id don't share collapse state across navigation.
+  assert.match(js, /"pc:collapsed:" \+ CURRENT \+ ":" \+ \(node\.id/);
   // Persist on toggle.
   assert.match(js, /writeCollapsed\(storageKey, collapsed\)/);
   // Every storage access is wrapped so a throwing localStorage can't break the UI.
@@ -239,6 +242,77 @@ test("GET /app/pages/<id> returns the page json, 404 for unknown", async () => {
   assert.equal(miss.status, 404);
 });
 
+test("GET /app/pages indexes the available pages with titles + home flag", async () => {
+  const res = await dispatch("GET", "/app/pages");
+  assert.equal(res.status, 200);
+  const body = JSON.parse(res.body ?? "{}");
+  assert.equal(body.home, "home");
+  const byId = Object.fromEntries((body.pages ?? []).map((p: { id: string }) => [p.id, p]));
+  assert.deepEqual(byId.home, { id: "home", title: "Home", home: true });
+  assert.deepEqual(byId.epic, { id: "epic", title: "Epic Coordination", home: false });
+  // The exact index path must not be shadowed by the /app/pages/<id> prefix route.
+  assert.equal((await dispatch("GET", "/app/pages/epic")).status, 200);
+});
+
+test("GET /app/pages is empty (not an error) when listing is unavailable", async () => {
+  // listPages is optional — without it the index is an empty list, not a 500.
+  const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app" }, {
+    db: fakeDb(),
+    engine: fakeEngine().engine,
+    readPage: async () => "{}",
+  });
+  const res = await makeRouter(routes)(req("GET", "/app/pages"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(JSON.parse(res.body ?? "{}"), { pages: [], home: "home" });
+});
+
+test("the renderer routes between pages by hash and tears down grid polls", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A page is chosen by the URL fragment (#/<page>), validated to a safe id, and
+  // re-rendered on hashchange — proxy-safe because the hash never hits the server.
+  assert.match(js, /const PAGE_ID = \/\^\[A-Za-z0-9_-/);
+  assert.match(js, /function safePageId\(value\)/);
+  assert.match(js, /function currentPage\(\)/);
+  assert.match(js, /try \{\s*const raw = decodeURIComponent/s);
+  assert.match(js, /catch \(e\) \{\s*return HOME;/s);
+  assert.match(js, /location\.hash/);
+  assert.match(js, /window\.addEventListener\("hashchange", renderPage\)/);
+  assert.match(js, /async function renderPage\(\)/);
+  // Navigation runs every registered disposer first, so a switched-away grid's
+  // poll interval + pc:refresh listener are removed rather than leaking forever.
+  assert.match(js, /const disposers = \[\]/);
+  assert.match(js, /function teardown\(\)/);
+  assert.match(js, /disposers\.push\(\(\) => document\.removeEventListener\("pc:refresh", refresh\)\)/);
+  assert.match(js, /disposers\.push\(\(\) => clearInterval\(timer\)\)/);
+});
+
+test("the renderer ships a nav node (menu bar / rail) with in-app + external links", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // nav is a first-class node type.
+  assert.match(js, /nav: renderNav/);
+  assert.match(js, /function renderNav\(node\)/);
+  // "rail" variant renders a side rail; anything else is a horizontal bar.
+  assert.match(js, /p\.variant === "rail"/);
+  assert.match(js, /"pc-nav pc-rail"/);
+  assert.match(js, /"pc-nav pc-bar"/);
+  // A page item becomes an in-app hash link, active-highlighted on the current page.
+  assert.match(js, /const isPage = safePageId\(item\.page\)/);
+  assert.match(js, /attrs\.href = "#\/" \+ encodeURIComponent\(item\.page\)/);
+  assert.match(js, /item\.page === CURRENT/);
+  assert.match(js, /aria-current/);
+  // An external item is an http(s)-only, hardened new-tab link.
+  assert.match(js, /\^https\?:\\\/\\\//);
+  assert.match(js, /attrs\.rel = "noopener noreferrer"/);
+  // items:"auto" (or omitted) enumerates every page from the index endpoint.
+  assert.match(js, /getJSON\("\/app\/pages"\)/);
+  // A rail is lifted into a left <aside>; the rest flow into a content column.
+  assert.match(js, /pc-rail-wrap/);
+  assert.match(js, /pc-layout/);
+  assert.match(js, /pc-main-col/);
+});
+
 test("GET /app/data/<source>/<table> returns rows", async () => {
   const res = await dispatch("GET", "/app/data/app/orders");
   assert.equal(res.status, 200);

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

@@ -43,6 +43,12 @@ export interface PagesDeps {
   engine: EngineClient;
   /** Read a page file; injectable for tests. */
   readPage(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"`.
+   * Optional; when absent the index is empty. Injectable for tests.
+   */
+  listPages?(): Promise<string[]>;
 }
 
 /** A JavaScript-body response (the renderer module served at /app/runtime.js). */
@@ -64,7 +70,7 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   const rowLimitRaw = opts.rowLimit ?? 200;
   const rowLimit = Number.isFinite(rowLimitRaw) ? Math.max(0, Math.floor(rowLimitRaw)) : 200;
   const sourceName = opts.sourceName ?? "app";
-  const { db, engine, readPage } = deps;
+  const { db, engine, readPage, listPages } = deps;
 
   // 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
@@ -113,6 +119,34 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
     handler: () => javascript(RENDERER_JS),
   });
 
+  // ── GET /app/pages (index of available pages) ───────────────────────────
+  // 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
+  // appears by id) and a `home` flag. Registered as an exact path so it never
+  // shadows the `/app/pages/<id>` prefix route below.
+  routes.push({
+    method: "GET",
+    path: "/app/pages",
+    source: "surface:pages",
+    handler: async () => {
+      const ids = listPages ? await listPages().catch(() => []) : [];
+      const pages: { id: string; title: string; home: boolean }[] = [];
+      for (const id of ids) {
+        if (!/^[A-Za-z0-9_-]+$/.test(id)) continue;
+        let title = id;
+        try {
+          const doc = JSON.parse(await readPage(`${pagesDir}/${id}.page.json`));
+          if (isRecord(doc) && typeof doc.title === "string" && doc.title) title = doc.title;
+        } catch {
+          // Unreadable or non-JSON page: still list it by id.
+        }
+        pages.push({ id, title, home: id === homePage });
+      }
+      return json({ pages, home: homePage });
+    },
+  });
+
   // ── GET /app/pages/<id> ─────────────────────────────────────────────────
   routes.push({
     method: "GET",
@@ -324,6 +358,13 @@ export function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle {
     db: app.data.open(sourceName),
     engine: app.engine,
     readPage: (p) => ctx.host.readTextFile(p),
+    listPages: async () => {
+      const dir = opts.pagesDir ?? "pages";
+      const names = await ctx.host.listDir(dir).catch(() => []);
+      return names
+        .filter((n) => n.endsWith(".page.json"))
+        .map((n) => n.slice(0, -".page.json".length));
+    },
   });
   ctx.host.log("info", "pages surface mounted", { source: sourceName, home: opts.homePage ?? "home" });
   return {
@@ -430,6 +471,22 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-collapse-header { display:flex; align-items:center; gap:.5rem; width:100%; margin:0 0 .75rem; padding:0; background:transparent; border:0; color:inherit; font:inherit; font-size:1rem; font-weight:600; cursor:pointer; text-align:left; }
 .pc-chevron-inline { color:var(--nano-text-faint); font-size:.75rem; width:1em; }
 .pc-card-body[hidden] { display:none; }
+/* Multi-page navigation: a horizontal menu bar or a vertical side rail. */
+.pc-layout { display:flex; gap:1.5rem; align-items:flex-start; }
+.pc-rail-wrap { flex:0 0 12rem; position:sticky; top:1rem; align-self:flex-start; }
+.pc-main-col { flex:1 1 auto; min-width:0; }
+.pc-nav-title { font-weight:650; }
+.pc-bar { display:flex; align-items:center; gap:.6rem; flex-wrap:wrap; border-bottom:1px solid var(--nano-edge); padding-bottom:.6rem; margin-bottom:1.25rem; }
+.pc-bar .pc-nav-title { margin-right:.5rem; }
+.pc-bar .pc-nav-items { display:flex; gap:.25rem; flex-wrap:wrap; }
+.pc-rail { display:flex; flex-direction:column; gap:.5rem; }
+.pc-rail .pc-nav-title { margin-bottom:.25rem; padding:0 .7rem; }
+.pc-rail .pc-nav-items { display:flex; flex-direction:column; gap:.15rem; }
+.pc-nav-link { display:flex; align-items:center; gap:.4rem; padding:.4rem .7rem; border-radius:.4rem; color:var(--nano-text-muted); text-decoration:none; font-size:.9rem; }
+.pc-nav-link:hover { background:var(--nano-hover); color:var(--nano-text); }
+.pc-nav-link.active { background:var(--nano-accent); color:var(--nano-on-accent); }
+.pc-nav-icon { line-height:1; }
+.pc-nav-empty { color:var(--nano-text-faint); font-size:.85rem; padding:.4rem .7rem; }
 `;
 
 // The schema-driven browser renderer (ADR 0042 §3). Plain ES module string served at
@@ -440,6 +497,37 @@ const RENDERER_JS = String.raw`
 const root = document.getElementById("page");
 const HOME = root.dataset.home || "home";
 
+// ── Multi-page routing (hash-based, reverse-proxy safe) ──────────────────
+// Pages are selected by the URL fragment (#/<page>) so navigation never hits
+// the server and works identically at the origin root and under the Nano
+// console's /console/app-view/<name>/ path-prefixed proxy (the hash is never
+// sent upstream). An empty/invalid hash falls back to the home page. Only a
+// safe id charset is accepted so the fragment can't smuggle a path/URL.
+const PAGE_ID = /^[A-Za-z0-9_-]+$/;
+function safePageId(value) {
+  return typeof value === "string" && PAGE_ID.test(value);
+}
+function currentPage() {
+  try {
+    const raw = decodeURIComponent((location.hash || "").replace(/^#\/?/, ""));
+    return safePageId(raw) ? raw : HOME;
+  } catch (e) {
+    return HOME;
+  }
+}
+let CURRENT = currentPage();
+
+// Per-render teardown. Each dataGrid registers its poll interval + pc:refresh
+// listener here; navigating to another page runs every disposer before the new
+// page renders, so a switched-away grid stops polling (otherwise every visited
+// page would leave a live setInterval fetching forever).
+const disposers = [];
+function teardown() {
+  while (disposers.length) {
+    try { disposers.pop()(); } catch (e) { /* best-effort cleanup */ }
+  }
+}
+
 // Theme bridge for the Nano console embed. The app runs in a sandboxed,
 // same-origin iframe, so the console's --nano-* custom properties and its
 // data-appearance never cascade in. Instead the console postMessages its
@@ -888,15 +976,71 @@ function renderDataGrid(node) {
     }
   }
   document.addEventListener("pc:refresh", refresh);
+  disposers.push(() => document.removeEventListener("pc:refresh", refresh));
   // Skip the automatic poll while the user is typing in the grid — an explicit pc:refresh
   // (e.g. after submitting an answer) still runs — so rows never shift under an in-progress
-  // answer and the detail input keeps focus across ticks.
-  if (p.refreshMs && p.refreshMs > 0) setInterval(() => { if (!editingInGrid()) refresh(); }, p.refreshMs);
+  // answer and the detail input keeps focus across ticks. The interval is registered as a
+  // disposer so a page switch (hashchange → renderPage → teardown) stops it.
+  if (p.refreshMs && p.refreshMs > 0) {
+    const timer = setInterval(() => { if (!editingInGrid()) refresh(); }, p.refreshMs);
+    disposers.push(() => clearInterval(timer));
+  }
   refresh();
   return card;
 }
 
-const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid };
+// 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.
+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;
+  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 {
+    attrs.href = item.href; attrs.target = "_blank"; attrs.rel = "noopener noreferrer";
+  }
+  const kids = [];
+  if (item.icon != null) kids.push(el("span", { class: "pc-nav-icon" }, String(item.icon)));
+  kids.push(el("span", { class: "pc-nav-label" }, String(item.label != null ? item.label : (item.page || item.href))));
+  return el("a", attrs, ...kids);
+}
+function fillNav(list, items) {
+  list.replaceChildren();
+  let n = 0;
+  for (const item of items || []) {
+    if (!item || typeof item !== "object") continue;
+    const a = navLink(item);
+    if (a) { list.append(a); n++; }
+  }
+  if (!n) list.append(el("span", { class: "pc-nav-empty" }, "No pages"));
+}
+function renderNav(node) {
+  const p = node.props || {};
+  const rail = p.variant === "rail";
+  const nav = el("nav", { class: rail ? "pc-nav pc-rail" : "pc-nav pc-bar" });
+  if (p.title != null) nav.append(el("div", { class: "pc-nav-title" }, String(p.title)));
+  const list = el("div", { class: "pc-nav-items" });
+  nav.append(list);
+  const items = p.items;
+  if (Array.isArray(items)) {
+    fillNav(list, items);
+  } else {
+    // "auto" (or unspecified): enumerate every page and link to each.
+    getJSON("/app/pages")
+      .then((res) => fillNav(list, (res.pages || []).map((pg) => ({ label: pg.title || pg.id, page: pg.id }))))
+      .catch(() => list.append(el("span", { class: "pc-nav-empty" }, "No pages")));
+  }
+  return nav;
+}
+
+const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid, nav: renderNav };
 
 // 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,
@@ -951,7 +1095,7 @@ function makeCollapsible(node, card) {
     chevron,
     el("span", { class: "pc-collapse-title" }, titleText),
   );
-  const storageKey = "pc:collapsed:" + HOME + ":" + (node.id || titleText);
+  const storageKey = "pc:collapsed:" + CURRENT + ":" + (node.id || titleText);
   let collapsed = readCollapsed(storageKey, !!props.defaultCollapsed);
   function apply() {
     body.hidden = collapsed;
@@ -968,16 +1112,30 @@ function makeCollapsible(node, card) {
   return container;
 }
 
-async function main() {
+// Render the page named by the current hash route. A rail nav is lifted into a
+// left <aside> and the rest of the nodes flow into a content column; otherwise
+// (bar nav or none) nodes render in document order. Re-runs on every hashchange,
+// tearing down the previous page's grid polls first.
+async function renderPage() {
+  teardown();
+  CURRENT = currentPage();
   try {
-    const doc = await getJSON("/app/pages/" + encodeURIComponent(HOME));
-    if (doc.title) document.title = doc.title;
-    root.replaceChildren(
-      ...(doc.nodes || []).map((n) => makeCollapsible(n, (RENDERERS[n.type] || (() => el("div")))(n))),
-    );
+    const doc = await getJSON("/app/pages/" + encodeURIComponent(CURRENT));
+    document.title = (doc && doc.title) || "Urban App";
+    const nodes = (doc && doc.nodes) || [];
+    const built = nodes.map((n) => ({ n, node: makeCollapsible(n, (RENDERERS[n.type] || (() => el("div")))(n)) }));
+    const rail = built.find((b) => b.n.type === "nav" && b.n.props && b.n.props.variant === "rail");
+    if (rail) {
+      const col = el("div", { class: "pc-main-col" });
+      for (const b of built) if (b !== rail) col.append(b.node);
+      root.replaceChildren(el("div", { class: "pc-layout" }, el("aside", { class: "pc-rail-wrap" }, rail.node), col));
+    } else {
+      root.replaceChildren(...built.map((b) => b.node));
+    }
   } catch (e) {
-    root.replaceChildren(el("p", { class: "pc-msg err" }, "Failed to load page: " + String(e.message || e)));
+    root.replaceChildren(el("p", { class: "pc-msg err" }, "Failed to load page: " + String((e && e.message) || e)));
   }
 }
-main();
+window.addEventListener("hashchange", renderPage);
+renderPage();
 `;