@nanobpm/urban 0.77.0 → 0.77.2

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

@@ -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
@@ -45,7 +46,10 @@ function javascript(body, status = 200, extraHeaders) {
 // 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"];
 // The app `dist/` directory (app-root sibling of the pages dir) the sidecar import-maps
@@ -485,6 +489,45 @@ export function createPagesRoutes(opts, deps) {
             }
         },
     });
+    // ── 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;
 }
 /**

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/dist/toolkit/derivers/api.js

@@ -17,6 +17,48 @@ export const API_BINDINGS_TS = "operations.ts";
  *  `tsc` (ADR 0059). The runtime dispatches through this map instead of per-op path imports. */
 export const API_CONTROLLER_TS = "controller.ts";
 export { DEFAULT_OPERATIONS_DIR };
+/** Order two import source specifiers the way Biome's `organizeImports` assist does, so the
+ *  controller emits its delegate imports in Biome's canonical order and the generated file passes
+ *  `biome check` without a post-generation import sort. Biome's collation is, per character:
+ *  digit-runs compared numerically (`item2` before `item10`), letters compared case-insensitively
+ *  as the primary key, and — when two characters are the same letter differing only in case — the
+ *  uppercase one sorts first as an immediate tiebreak (`getAgentInstructions` before
+ *  `getAgenticRegistry` before `getAgentSkill`). */
+function naturalCompare(a, b) {
+    const tokens = (s) => s.match(/\d+|\D/g) ?? [];
+    const isDigitRun = (t) => t.charCodeAt(0) >= 48 && t.charCodeAt(0) <= 57;
+    const ax = tokens(a);
+    const bx = tokens(b);
+    const n = Math.min(ax.length, bx.length);
+    for (let i = 0; i < n; i++) {
+        const ca = ax[i];
+        const cb = bx[i];
+        if (ca === undefined || cb === undefined)
+            break;
+        if (isDigitRun(ca) && isDigitRun(cb)) {
+            // Compare digit runs by numeric value *without* floating-point loss: strip leading zeros,
+            // then a longer run is the larger number, else compare the equal-length digits lexically.
+            // (`Number(ca) - Number(cb)` collapses 17+-digit runs to the same IEEE-754 value and yields
+            //  `NaN` beyond `Number.MAX_SAFE_INTEGER`, both of which break the total order `sort` needs.)
+            const na = ca.replace(/^0+/, "");
+            const nb = cb.replace(/^0+/, "");
+            if (na.length !== nb.length)
+                return na.length < nb.length ? -1 : 1;
+            if (na !== nb)
+                return na < nb ? -1 : 1;
+            if (ca !== cb)
+                return ca < cb ? -1 : 1; // equal value, differing leading zeros
+        }
+        else if (ca !== cb) {
+            const la = ca.toLowerCase();
+            const lb = cb.toLowerCase();
+            if (la !== lb)
+                return la < lb ? -1 : 1; // case-insensitive primary key
+            return ca < cb ? -1 : 1; // same letter, different case → uppercase (lower code point) first
+        }
+    }
+    return ax.length - bx.length;
+}
 /** A TS identifier form of an operationId (used for the per-op type names). */
 function typeStem(operationId) {
     const cleaned = operationId.replace(/[^A-Za-z0-9]+/g, " ").trim();
@@ -139,7 +181,7 @@ function objectToTs(schema, depth) {
 function paramsTs(op, where, ejected) {
     const ps = op.parameters.filter((p) => p.in === where);
     if (ps.length === 0)
-        return "{}";
+        return "Record<string, never>";
     const rawWire = where === "query" ? "string | string[]" : "string";
     const fields = ps.map((p) => {
         // Coerced to the schema type (number/boolean/array/enum/…); optionality is carried by the `?`
@@ -188,8 +230,7 @@ export function emitApiBindings(doc, surfaceEject = false) {
         "// The endpoint type map: each operationId maps to its typed request (coerced path/query params\n" +
         "// + JSON body) and response (a union of every documented JSON response body), derived from the\n" +
         "// spec. Do not edit — regenerated from\n" +
-        "// the spec; erased to plain JS at compile.\n" +
-        "// eslint-disable\n\n";
+        "// the spec; erased to plain JS at compile.\n\n";
     const componentDecls = Object.entries(components)
         .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
         .map(([name, schema]) => `export type ${typeStem(name)} = ${schemaToTs(schema)};`)
@@ -242,13 +283,19 @@ export function emitApiBindings(doc, surfaceEject = false) {
         return `  ${JSON.stringify(op.operationId)}: { request: ${stem}Request; response: ${stem}Response };`;
     })
         .join("\n");
+    // With generated `.ts` now linted in the scaffold, an empty operation set must NOT emit an empty
+    // `interface ApiOperations {}` (`suspicious/noEmptyInterface`); fall back to the same non-empty-safe
+    // `Record<never, never>` used elsewhere (its `keyof` is `never`, matching `ApiOperationId = never`).
+    const apiOperations = ops.length > 0
+        ? `export interface ApiOperations {\n${mapEntries}\n}\n`
+        : `export type ApiOperations = Record<never, never>;\n`;
     return (header +
         (componentDecls ? `${componentDecls}\n\n` : "") +
         (opDecls ? `${opDecls}\n\n` : "") +
         `/** Every declared operationId (ADR 0058): the delegate key set. */\n` +
         `export type ApiOperationId = ${idUnion};\n\n` +
         `/** Request/response contract per operationId. */\n` +
-        `export interface ApiOperations {\n${mapEntries}\n}\n`);
+        apiOperations);
 }
 /** Emit `operations.ts`: the typed `defineOperation` wrapper, keyed by operationId (mirrors the
  *  generated typed `defineWorker`). Written verbatim (it never changes with the spec) — it only
@@ -257,10 +304,9 @@ export function emitApiBindingsRuntime() {
     return ("// AUTO-GENERATED by @nanobpm/urban (ADR 0058): the typed `defineOperation`.\n" +
         "// Re-exports the operation SDK and overrides `defineOperation` with an operationId-keyed\n" +
         "// signature (the delegate's validated request + result typed from the spec). Erased to a\n" +
-        "// pass-through at runtime. Do not edit.\n" +
-        "// eslint-disable\n\n" +
-        `import { defineOperation as defineOperationRaw } from "@nanobpm/urban";\n` +
+        "// pass-through at runtime. Do not edit.\n\n" +
         `import type { OperationHandler } from "@nanobpm/urban";\n` +
+        `import { defineOperation as defineOperationRaw } from "@nanobpm/urban";\n` +
         `import type { ApiOperationId, ApiOperations } from "./${API_BINDINGS_DTS}";\n\n` +
         `type ReqFor<K extends ApiOperationId> = ApiOperations[K]["request"];\n` +
         `type ResFor<K extends ApiOperationId> = ApiOperations[K]["response"];\n\n` +
@@ -303,17 +349,22 @@ export function emitApiController(doc, operationsDir = DEFAULT_OPERATIONS_DIR) {
         "// registry. Statically imports every operation delegate and asserts the complete, correctly-\n" +
         "// typed set via `satisfies` — a missing, mismatched, or orphan delegate fails `tsc`. The\n" +
         "// runtime dispatches through this map, so endpoints cannot drift from the spec. Do not edit —\n" +
-        "// regenerated from the spec.\n" +
-        "// eslint-disable\n\n";
-    const typeImports = `import type { OperationHandler } from "@nanobpm/urban";\n` +
-        `import type { ApiOperationId, ApiOperations } from "./${API_BINDINGS_DTS}";\n`;
+        "// regenerated from the spec.\n\n";
+    // Emit imports in Biome's canonical `organizeImports` order so the generated file is lint-clean
+    // without a post-gen fixup: the bare package import first, then the delegate imports sorted by
+    // source specifier (Biome's natural, numeric-aware collation), then the relative `./api-io.d.ts`
+    // type import last. Alias bindings (`op<i>`) stay tied to the original index so the `operations`
+    // map below still resolves each operationId to its delegate regardless of import line order.
     const delegateImports = ops
-        .map((op, i) => `import op${i} from ${JSON.stringify(`../${dir}/${op.operationId}.ts`)};`)
+        .map((op, i) => ({ i, spec: `../${dir}/${op.operationId}.ts` }))
+        .sort((a, b) => naturalCompare(a.spec, b.spec))
+        .map(({ i, spec }) => `import op${i} from ${JSON.stringify(spec)};`)
         .join("\n");
     const mapEntries = ops.map((op, i) => `  ${JSON.stringify(op.operationId)}: op${i},`).join("\n");
     return (header +
-        typeImports +
+        `import type { OperationHandler } from "@nanobpm/urban";\n` +
         (delegateImports ? `${delegateImports}\n` : "") +
+        `import type { ApiOperationId, ApiOperations } from "./${API_BINDINGS_DTS}";\n` +
         `\n` +
         `type ReqFor<K extends ApiOperationId> = ApiOperations[K]["request"];\n` +
         `type ResFor<K extends ApiOperationId> = ApiOperations[K]["response"];\n\n` +

package/dist/toolkit/derivers/domain.js

@@ -83,10 +83,9 @@ function tableInterface(t) {
  */
 export function emitDomainDts(tables) {
     const header = "// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\n" +
-        "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n" +
-        "// eslint-disable\n";
+        "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n";
     if (tables.length === 0) {
-        return `${header}\nexport interface DomainTables {}\n`;
+        return `${header}\nexport type DomainTables = Record<never, never>;\n`;
     }
     const interfaces = tables.map(tableInterface).join("\n\n");
     const map = tables
@@ -113,15 +112,14 @@ export function emitDomainDtsForSources(sources, defaultSource) {
         return emitDomainDts(sources[0]?.tables ?? []);
     }
     const header = "// AUTO-GENERATED by nanobpmn from the datasource schemas (ADR 0029 §4.1/§6).\n" +
-        "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n" +
-        "// eslint-disable\n";
+        "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n";
     const interfaces = sources
         .flatMap((s) => s.tables.map((t) => tableInterfaceNamed(prefixedInterfaceName(s.source, t.name), t)))
         .join("\n\n");
     const sourceMap = sources
         .map((s) => {
         if (s.tables.length === 0)
-            return `  ${JSON.stringify(s.source)}: {};`;
+            return `  ${JSON.stringify(s.source)}: Record<never, never>;`;
         const tableMap = s.tables
             .map((t) => `    ${JSON.stringify(t.name)}: ${prefixedInterfaceName(s.source, t.name)};`)
             .join("\n");
@@ -181,7 +179,7 @@ export function emitDomainTypeRegistry(types) {
             return `    ${key}${opt}: ${fieldTsType(field, ids)};`;
         })
             .join("\n");
-        const body = fields.length > 0 ? `{\n${fields}\n  }` : "{}";
+        const body = fields.length > 0 ? `{\n${fields}\n  }` : "Record<never, never>";
         return `  ${JSON.stringify(id)}: ${body};`;
     })
         .join("\n");
@@ -233,8 +231,7 @@ export function emitDomainBindings(sources, defaultSource) {
     const header = "// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1/§6).\n" +
         "// The typed data-object layer: `openDomain()` → one `Table<T>` per table, so\n" +
         "// workers manipulate typed rows instead of hand-writing SQL. Do not edit —\n" +
-        "// regenerated from the live tables. Erased to plain JS at `deno compile`.\n" +
-        "// eslint-disable\n";
+        "// regenerated from the live tables. Erased to plain JS at `deno compile`.\n";
     const multi = sources.length > 1;
     const def = defaultSource && sources.some((s) => s.source === defaultSource)
         ? defaultSource
@@ -279,7 +276,7 @@ export function emitDomainBindings(sources, defaultSource) {
         (binds ? `${binds}\n` : "") +
         `    close: () => raw.close(),\n  };\n}`;
     return `${header}\n` +
-        `import { openDataSource, type DataSource, type Table } from "./data-sdk.ts";\n` +
+        `import { type DataSource, openDataSource, type Table } from "./data-sdk.ts";\n` +
         importTypes +
         `\n${domainIface}\n\n${openFn}\n\nexport type { Table };\n`;
 }
@@ -323,13 +320,14 @@ function emitKeyedDomainBindings(header, sources, def) {
         `export async function openDomain<K extends DomainSource = ${JSON.stringify(def)}>(\n` +
         `  source?: K,\n` +
         `): Promise<Domain<DomainSources[K]>> {\n` +
-        `  const key = (source ?? DEFAULT_SOURCE) as string;\n` +
+        `  const key = source ?? DEFAULT_SOURCE;\n` +
         `  const raw = await openDataSource(key);\n` +
         `  const db: Record<string, unknown> = { raw, close: () => raw.close() };\n` +
         `  for (const t of DOMAIN_TABLES[key] ?? []) db[t.name] = raw.table(t.name, t.pk);\n` +
+        `  // biome-ignore lint/plugin: the per-source table set is bound dynamically from DOMAIN_TABLES; the Domain<M> shape can't be expressed statically over the runtime loop.\n` +
         `  return db as Domain<DomainSources[K]>;\n}`;
     return `${header}\n` +
-        `import { openDataSource, type DataSource, type Table } from "./data-sdk.ts";\n` +
+        `import { type DataSource, openDataSource, type Table } from "./data-sdk.ts";\n` +
         `import type { DomainSources } from "./${DOMAIN_DTS}";\n\n` +
         `${runtimeMap}\n\n${types}\n\n${openFn}\n\nexport type { Table };\n`;
 }

package/dist/toolkit/derivers/messages.js

@@ -79,15 +79,14 @@ export function emitMessageBindings(messages, declaredTypeIds) {
         "// The bridge from a `bpmn:message`'s data envelope to the message type system:\n" +
         "// each named message maps to the TS type of its payload, so the typed\n" +
         "// `publishMessage` types a call by its message name. Do not edit — regenerated\n" +
-        "// from the model. Erased to plain JS at compile.\n" +
-        "// eslint-disable\n";
+        "// from the model. Erased to plain JS at compile.\n";
     const needsRegistry = payloads.length > 0;
     const importTypes = needsRegistry
         ? `import type { DomainTypes } from "./${DOMAIN_DTS}";\n`
         : "";
     const payloadsIface = payloads.length > 0
         ? `export interface MessagePayloads {\n${payloads.join("\n")}\n}\n`
-        : `export interface MessagePayloads {}\n`;
+        : `export type MessagePayloads = Record<never, never>;\n`;
     return `${header}\n` +
         importTypes +
         `\n/** Untyped fallback payload for a message that declares no envelope type. */\n` +
@@ -149,11 +148,10 @@ export function emitMessageBindingsRuntime() {
     return "// AUTO-GENERATED by nanobpmn (ADR 0040 slice 2): the typed `publishMessage`.\n" +
         "// Re-exports the worker SDK's `publishMessage` and overrides it with a\n" +
         "// messageName-keyed typed signature (variables typed from the message's declared\n" +
-        "// envelope). Erased to a pass-through at runtime. Do not edit.\n" +
-        "// eslint-disable\n\n" +
-        `import { publishMessage as publishMessageRaw } from "./worker-sdk.ts";\n` +
+        "// envelope). Erased to a pass-through at runtime. Do not edit.\n\n" +
+        `import type { MessageName, MessagePayloads, MessageVars } from "./${MESSAGE_BINDINGS_DTS}";\n` +
         `import type { PublishMessageOptions, PublishMessageResult } from "./worker-sdk.ts";\n` +
-        `import type { MessageName, MessagePayloads, MessageVars } from "./${MESSAGE_BINDINGS_DTS}";\n\n` +
+        `import { publishMessage as publishMessageRaw } from "./worker-sdk.ts";\n\n` +
         `export type { PublishMessageOptions, PublishMessageResult } from "./worker-sdk.ts";\n\n` +
         `type PayloadFor<K extends MessageName> = K extends keyof MessagePayloads ? MessagePayloads[K] : MessageVars;\n\n` +
         `/**\n` +
@@ -166,6 +164,7 @@ export function emitMessageBindingsRuntime() {
         `  name: K,\n` +
         `  opts?: PublishMessageOptions<PayloadFor<K> & object>,\n` +
         `): Promise<PublishMessageResult> {\n` +
+        `  // biome-ignore lint/plugin: generic-to-raw erasure at the message-SDK boundary; the wire stays untyped JSON (ADR 0040 slice 2).\n` +
         `  return publishMessageRaw(name, opts as unknown as PublishMessageOptions);\n` +
         `}\n`;
 }

package/dist/toolkit/derivers/meta.js

@@ -67,23 +67,25 @@ export function emitMeta(metas) {
     const header = "// AUTO-GENERATED by nanobpmn from the process model (ADR 0040 §5): the typed\n" +
         "// model-metadata accessor. Each `nano:meta` key/value the models declare becomes\n" +
         "// a checked `AppMeta` property, so `meta(key)` is typed and app-wide queryable\n" +
-        "// without a second store. Do not edit — regenerated from the model.\n" +
-        "// eslint-disable\n\n";
+        "// without a second store. Do not edit — regenerated from the model.\n\n";
     const iface = keys.length > 0
         ? `export interface AppMeta {\n${keys.map((k) => `  ${propKey(k)}: string;`).join("\n")}\n}\n`
-        : `export interface AppMeta {}\n`;
+        : `export type AppMeta = Record<never, never>;\n`;
+    // Dot-access satisfies Biome's `useLiteralKeys`, but `__proto__` must stay a computed key: dot
+    // access would trip `noProto` and (off a null-prototype dict) change semantics.
+    const assignTarget = (k) => isIdent(k) && k !== "__proto__" ? `m.${k}` : `m[${JSON.stringify(k)}]`;
     const constDecl = keys.length > 0
         ? `export const appMeta: AppMeta = (() => {\n` +
-            `  const m: Record<string, string> = Object.create(null);\n` +
-            keys.map((k) => `  m[${JSON.stringify(k)}] = ${JSON.stringify(folded[k])};`).join("\n") +
-            `\n  return m as AppMeta;\n})();\n`
-        : `export const appMeta: AppMeta = Object.create(null) as AppMeta;\n`;
+            `  const m: AppMeta = Object.create(null);\n` +
+            keys.map((k) => `  ${assignTarget(k)} = ${JSON.stringify(folded[k])};`).join("\n") +
+            `\n  return m;\n})();\n`
+        : `export const appMeta: AppMeta = Object.create(null);\n`;
     const accessor = `\n/** Read a model-level metadata value. A declared key is typed; a dynamic key\n` +
         ` * returns \`string | undefined\`. */\n` +
         `export function meta<K extends keyof AppMeta>(key: K): AppMeta[K];\n` +
         `export function meta(key: string): string | undefined;\n` +
         `export function meta(key: string): string | undefined {\n` +
-        `  return (appMeta as Record<string, string>)[key];\n` +
+        `  return Reflect.get(appMeta, key);\n` +
         `}\n`;
     return `${header}/** Every model-level metadata key the App's models declare (ADR 0040 §5). */\n` +
         iface + "\n" + constDecl + accessor;

package/dist/toolkit/derivers/worker-io.js

@@ -143,21 +143,20 @@ export function emitWorkerBindings(workers, declaredTypeIds) {
         "// The bridge from the process model to the worker type system: each declared\n" +
         "// worker's `taskType` maps to the TS type of its input payload (`job.variables`)\n" +
         "// and result, so the typed `defineWorker` types a handler by its job type. Do\n" +
-        "// not edit — regenerated from the manifest. Erased to plain JS at compile.\n" +
-        "// eslint-disable\n";
+        "// not edit — regenerated from the manifest. Erased to plain JS at compile.\n";
     const needsRegistry = inputs.length > 0 || outputs.length > 0;
     const importTypes = needsRegistry
         ? `import type { DomainTypes } from "./${DOMAIN_DTS}";\n`
         : "";
     const inputsIface = inputs.length > 0
         ? `export interface WorkerInputs {\n${inputs.join("\n")}\n}\n`
-        : `export interface WorkerInputs {}\n`;
+        : `export type WorkerInputs = Record<never, never>;\n`;
     const outputsIface = outputs.length > 0
         ? `export interface WorkerOutputs {\n${outputs.join("\n")}\n}\n`
-        : `export interface WorkerOutputs {}\n`;
+        : `export type WorkerOutputs = Record<never, never>;\n`;
     const headersIface = headers.length > 0
         ? `export interface WorkerHeaders {\n${headers.join("\n")}\n}\n`
-        : `export interface WorkerHeaders {}\n`;
+        : `export type WorkerHeaders = Record<never, never>;\n`;
     return `${header}\n` +
         importTypes +
         `\n/** Untyped fallback for a job whose worker declares no input/output type. */\n` +
@@ -315,11 +314,10 @@ export function emitWorkerBindingsRuntime() {
         "// Re-exports the worker SDK and overrides `defineWorker` with a taskType-keyed\n" +
         "// typed signature (job.variables, job.customHeaders + result typed from the\n" +
         "// worker's declared input/output/header contract). Erased to a pass-through at\n" +
-        "// runtime. Do not edit.\n" +
-        "// eslint-disable\n\n" +
-        `import { defineWorker as defineWorkerRaw } from "./worker-sdk.ts";\n` +
+        "// runtime. Do not edit.\n\n" +
+        `import type { WorkerHdrs, WorkerHeaders, WorkerInputs, WorkerOutputs, WorkerTaskType, WorkerVars } from "./${WORKER_BINDINGS_DTS}";\n` +
         `import type { WorkerOptions } from "./worker-sdk.ts";\n` +
-        `import type { WorkerInputs, WorkerOutputs, WorkerHeaders, WorkerTaskType, WorkerVars, WorkerHdrs } from "./${WORKER_BINDINGS_DTS}";\n\n` +
+        `import { defineWorker as defineWorkerRaw } from "./worker-sdk.ts";\n\n` +
         `export * from "./worker-sdk.ts";\n\n` +
         `type InFor<K extends WorkerTaskType> = K extends keyof WorkerInputs ? WorkerInputs[K] : WorkerVars;\n` +
         `type OutFor<K extends WorkerTaskType> = K extends keyof WorkerOutputs ? WorkerOutputs[K] : WorkerVars;\n` +
@@ -334,6 +332,7 @@ export function emitWorkerBindingsRuntime() {
         `export function defineWorker<K extends WorkerTaskType>(\n` +
         `  opts: { type: K } & WorkerOptions<InFor<K> & object, OutFor<K> & object, HdrFor<K> & object>,\n` +
         `): void {\n` +
+        `  // biome-ignore lint/plugin: generic-to-raw erasure at the worker-SDK boundary; the wire stays untyped JSON (ADR 0033 §3).\n` +
         `  defineWorkerRaw(opts as unknown as WorkerOptions);\n` +
         `}\n`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.77.0",
+	"version": "0.77.2",
 	"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",
@@ -103,7 +103,7 @@
 		"@nanobpm/nano-sdk": "^1.2.5",
 		"@nanobpm/workflow": "^0.14.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
-		"create-urban-app": "^0.15.0",
+		"create-urban-app": "^0.15.1",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {

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 });
+});