@nanobpm/urban 0.94.2 → 0.95.0

package/dist/runtime/adapters/deno.js

@@ -94,6 +94,36 @@ export function createDenoHost(opts = {}) {
                 return false;
             }
         },
+        async statFile(p) {
+            // Classify with a bare `stat` FIRST, then only open a *regular file* to confirm it is
+            // readable. The order matters: a read-only open of a FIFO (named pipe) blocks indefinitely
+            // waiting for a writer, so opening before the type check would hang every shell request on
+            // a FIFO sitting at this conventional asset path. A plain `stat` never blocks, so it safely
+            // rejects non-regular entries (directory, FIFO, socket, device) up front. The subsequent
+            // open/stat still answers the real serving condition — a file `stat` reports as regular can
+            // be unreadable (ACLs / permissions), and the shell must not link an asset that then 404s.
+            // Missing path → `null`; non-regular → `isFile: false`; unreadable → `null`.
+            try {
+                const meta = await Deno.stat(abs(p));
+                if (!meta.isFile)
+                    return { isFile: false };
+            }
+            catch {
+                return null;
+            }
+            let file;
+            try {
+                file = await Deno.open(abs(p), { read: true });
+                const s = await file.stat();
+                return { isFile: s.isFile };
+            }
+            catch {
+                return null;
+            }
+            finally {
+                file?.close();
+            }
+        },
         openSqlite(path) {
             const db = new DatabaseSync(abs(path));
             return wrapSqlite(db);

package/dist/runtime/adapters/node.js

@@ -8,7 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { readFile, readdir, stat } from "node:fs/promises";
+import { open, readFile, readdir, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { watch as fsWatch } from "node:fs";
 import { createServer } from "node:http";
@@ -133,6 +133,36 @@ export function createNodeHost(opts = {}) {
                 return false;
             }
         },
+        async statFile(p) {
+            // Classify with a bare `stat` FIRST, then only open a *regular file* to confirm it is
+            // readable. The order matters: a read-only open of a FIFO (named pipe) blocks indefinitely
+            // waiting for a writer, so opening before the type check would hang every shell request on
+            // a FIFO sitting at this conventional asset path. A plain `stat` never blocks, so it safely
+            // rejects non-regular entries (directory, FIFO, socket, device) up front. The subsequent
+            // handle open/stat still answers the real serving condition — a file `stat` reports as
+            // regular can be unreadable (ACLs / permissions), and the shell must not link an asset that
+            // then 404s. Missing path → `null`; non-regular → `isFile: false`; unreadable → `null`.
+            try {
+                const meta = await stat(abs(p));
+                if (!meta.isFile())
+                    return { isFile: false };
+            }
+            catch {
+                return null;
+            }
+            let handle;
+            try {
+                handle = await open(abs(p), "r");
+                const s = await handle.stat();
+                return { isFile: s.isFile() };
+            }
+            catch {
+                return null;
+            }
+            finally {
+                await handle?.close();
+            }
+        },
         openSqlite(path) {
             const db = new DatabaseSync(abs(path));
             return wrapNodeSqlite(db);

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

@@ -80,6 +80,27 @@ export interface HostContext {
     listSubdirs?(dir: string): Promise<string[]>;
     /** True if the path exists (file or directory). */
     exists(path: string): Promise<boolean>;
+    /**
+     * Probe a path as a READABLE REGULAR FILE without reading its bytes: `{ isFile }` when it
+     * can be opened for reading, or `null` when it is absent or unreadable. The pages surface
+     * uses this to probe the app-owned `app.css`/`app.js` convention on the per-request shell
+     * hot path: `exists` is too broad (true for a DIRECTORY, which the shell would then link and
+     * the browser would 404 on), and probing via `readTextFile` reads and allocates a
+     * potentially large file just to answer "is it there?". A bare metadata `stat` is not
+     * enough either — it can succeed for a regular file that `readTextFile` cannot open (ACLs /
+     * permissions), so the shell would link an asset that then 404s on serving. Implementations
+     * therefore OPEN the file for reading (consuming no bytes) and stat the open handle, so this
+     * answers the same success condition as serving.
+     *
+     * OPTIONAL: `HostContext` is a public, externally-implementable seam (re-exported from
+     * `runtime/index.ts`, documented in the README as a supported custom-host extension point),
+     * so a new required member would be source-breaking. The pages surface falls back to a
+     * read-based probe when a host does not provide it; the built-in adapters do, as an
+     * allocation-free optimization on the hot path.
+     */
+    statFile?(path: string): Promise<{
+        isFile: boolean;
+    } | null>;
     /** Open (creating if needed) a SQLite database at a filesystem path. */
     openSqlite(path: string): SqliteDb;
     /**

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

@@ -50,6 +50,21 @@ export interface PagesDeps {
      * Injectable for tests. Rejects (→ 404) when the file is missing.
      */
     readAsset?(path: string): Promise<string>;
+    /**
+     * Probe whether a static asset exists as a READABLE REGULAR FILE at an app-root-relative
+     * path, WITHOUT reading its bytes. The per-request shell build uses this for the app-owned
+     * `app.css`/`app.js` convention (#578): those files can be large and the shell is revalidated
+     * on every load, so probing via a full `readAsset` would put an avoidable read + allocation
+     * on the HTML hot path (and read the file twice — once here, once when the browser fetches
+     * it). Must answer the same question the `readAsset` fallback answers — "would serving this
+     * path succeed?" — so a directory (or unreadable entry) at the path is a NO. `mountPages`
+     * wires this to the optional `HostContext.statFile` (which opens the file for reading to
+     * confirm a readable regular file — never `HostContext.exists`, which is true for directories
+     * too, and a `pages/app.css/` DIRECTORY would link an asset the browser then 404s on).
+     * Optional; falls back to a read-based probe when absent.
+     * Injectable for tests.
+     */
+    existsAsset?(path: string): Promise<boolean>;
     /**
      * List the available page ids (the `*.page.json` basenames under `pagesDir`),
      * powering the `/app/pages` index endpoint and a `nav` node's `items: "auto"`.
@@ -64,6 +79,7 @@ export interface PagesDeps {
      */
     cancel?(processInstanceKey: string): Promise<CancelInstanceResult>;
 }
+export declare const APP_ASSETS: readonly ["app.css", "app.js"];
 /**
  * Build the page-runtime routes over an injected datasource + engine. Pure over its deps
  * so it is unit-testable without a real host/server (see pages.test.ts).
@@ -80,3 +96,4 @@ export interface PagesHandle {
  * Returns no routes when the surface is disabled or absent.
  */
 export declare function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle;
+export declare const RUNTIME_JS_PATH: string;

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

@@ -46,6 +46,12 @@ function javascript(body, status = 200, extraHeaders) {
         body,
     };
 }
+// App-owned shell customisation by convention (nano-ide#578): an app MAY ship `pagesDir/app.css`
+// (linked AFTER the built-in renderer CSS, so its rules win — themes, restyling) and/or
+// `pagesDir/app.js` (an ES module loaded after the runtime — e.g. a theme picker). Each is served
+// as a root sidecar and referenced from the shell ONLY when the file exists, so apps without them
+// see no change and no 404.
+export const APP_ASSETS = ["app.css", "app.js"];
 // 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
@@ -58,7 +64,7 @@ function javascript(body, status = 200, extraHeaders) {
 // `./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"];
+const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css", ...APP_ASSETS];
 // 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.
@@ -151,6 +157,9 @@ export function createPagesRoutes(opts, deps) {
     // 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;
+    // Existence probe for the app-owned shell assets (#578): a dedicated `existsAsset` when the
+    // host offers one (a metadata stat — no file bytes cross the seam), else a read-based probe.
+    const existsAsset = deps.existsAsset ?? ((path) => readAsset(path).then(() => true, () => false));
     // 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
@@ -181,15 +190,24 @@ export function createPagesRoutes(opts, deps) {
         return p;
     };
     const routes = [];
-    const shell = html(rendererShell(homePage, opts.apiDocsPath, opts.gridLayout ?? "auto"));
     // The shell must never be pinned by the browser: it carries the *current* fingerprinted
     // runtime URL, so a stale shell would keep pointing at an old module hash. `no-cache` forces
     // a revalidation on every load; the shell body is tiny, and the expensive module it references
     // is what gets the long-lived immutable caching (via its content-hashed URL).
-    shell.headers = { ...shell.headers, "cache-control": "no-cache" };
+    // Built per request: it probes for the app-owned `app.css`/`app.js` (#578) so adding or removing
+    // one takes effect without a restart.
+    const shell = async () => {
+        const [appCss, appJs] = await Promise.all([
+            existsAsset(`${pagesDir}/app.css`),
+            existsAsset(`${pagesDir}/app.js`),
+        ]);
+        const res = html(rendererShell(homePage, opts.apiDocsPath, opts.gridLayout ?? "auto", { appCss, appJs }));
+        res.headers = { ...res.headers, "cache-control": "no-cache" };
+        return res;
+    };
     // ── the renderer shell + module ─────────────────────────────────────────
-    routes.push({ method: "GET", path: "/", source: "surface:pages", handler: () => shell });
-    routes.push({ method: "GET", path: "/index.html", source: "surface:pages", handler: () => shell });
+    routes.push({ method: "GET", path: "/", source: "surface:pages", handler: shell });
+    routes.push({ method: "GET", path: "/index.html", source: "surface:pages", handler: shell });
     // The fingerprinted module URL (referenced by the shell): unique per content, so cache it hard.
     routes.push({
         method: "GET",
@@ -216,11 +234,22 @@ export function createPagesRoutes(opts, deps) {
     // 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) {
+        // The app-owned `app.css`/`app.js` are MUTABLE at stable URLs — the whole point of the
+        // convention is that an edit (or a remove/re-add) takes effect without a restart, and the
+        // shell re-probes on every load. Serve them `no-cache` (like `/app/runtime.js`) so a
+        // browser/intermediary must revalidate instead of replaying a heuristically-cached 200/404.
+        // The other sidecars are deploy-time fixtures, so they keep the generic response.
+        const mutable = APP_ASSETS.some((a) => a === name);
         routes.push({
             method: "GET",
             path: `/${name}`,
             source: "surface:pages",
-            handler: () => serveAsset(readAsset, `${pagesDir}/${name}`),
+            handler: async () => {
+                const res = await serveAsset(readAsset, `${pagesDir}/${name}`);
+                if (mutable)
+                    res.headers = { ...res.headers, "cache-control": "no-cache" };
+                return res;
+            },
         });
     }
     // The `dist/` tree the sidecars' import-maps reference (`../dist/cockpit/index.js` →
@@ -580,12 +609,24 @@ export function mountPages(ctx, app) {
     };
     const sourceName = opts.sourceName ?? "app";
     const bindings = ctx.manifest.instanceTracking ?? [];
+    // Probe "would serving this app-owned asset succeed?" — a READABLE REGULAR FILE, not the
+    // broader `HostContext.exists` (which is true for directories too, and a `pages/app.css/`
+    // DIRECTORY would link an asset the browser then 404s on). `statFile` is an OPTIONAL public
+    // host capability (a custom host need not implement it), and it opens the file for reading so
+    // no bytes cross the seam on the per-request shell hot path. Only wire the optimized probe
+    // when the host provides it; otherwise `createPagesRoutes` falls back to a read-based probe
+    // that answers the identical question.
+    const statFile = ctx.host.statFile?.bind(ctx.host);
+    const existsAsset = statFile
+        ? async (p) => (await statFile(p))?.isFile === true
+        : undefined;
     const routes = createPagesRoutes(opts, {
         db: app.data.open(sourceName),
         engine: app.engine,
         cancel: (key) => cancelInstanceReconciling(app, bindings, key),
         readPage: (p) => ctx.host.readTextFile(p),
         readAsset: (p) => ctx.host.readTextFile(p),
+        existsAsset,
         listPages: async () => {
             const dir = opts.pagesDir ?? "pages";
             const names = await ctx.host.listDir(dir).catch(() => []);
@@ -604,7 +645,7 @@ export function mountPages(ctx, app) {
 function escapeAttr(s) {
     return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function rendererShell(homePage, apiDocsPath, gridLayout) {
+function rendererShell(homePage, apiDocsPath, gridLayout, app = { appCss: false, appJs: false }) {
     // A persistent "API docs" badge (spec-first apps get their Swagger UI linked from their own
     // UI for free). `target="_blank"` + hardened `rel` so the docs open without giving the docs
     // tab a handle back to this window (reverse-tabnabbing).
@@ -628,12 +669,12 @@ function rendererShell(homePage, apiDocsPath, gridLayout) {
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Urban App</title>
-  <style>${RENDERER_CSS}</style>
+  <style>${RENDERER_CSS}</style>${app.appCss ? '\n  <link rel="stylesheet" href="./app.css" />' : ""}
 </head>
 <body data-grid-layout="${gridLayout}">${apiDocsBadge}
   <main id="page" data-home="${escapeAttr(homePage)}"><p class="pc-empty">Loading…</p></main>
   <script>${FORMJS_JS}</script>
-  <script type="module" src=".${RUNTIME_JS_PATH}"></script>
+  <script type="module" src=".${RUNTIME_JS_PATH}"></script>${app.appJs ? '\n  <script type="module" src="./app.js"></script>' : ""}
 </body>
 </html>`;
 }
@@ -1015,5 +1056,8 @@ function fnv1aHex(s) {
 // other page action) do nothing after an upgrade until a hard refresh. Because the URL is unique
 // per content, the response itself is served `immutable` with a one-year max-age.
 const RUNTIME_JS_HASH = fnv1aHex(RENDERER_JS);
-const RUNTIME_JS_PATH = `/app/runtime.${RUNTIME_JS_HASH}.js`;
+// Exported so tests can locate the actual fingerprinted runtime <script> tag in the shell
+// (asserting against the bare word "runtime" is unsound — it also appears in the embedded
+// renderer CSS, so such a test passes even if the app script were moved before the runtime).
+export const RUNTIME_JS_PATH = `/app/runtime.${RUNTIME_JS_HASH}.js`;
 const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.94.2",
+	"version": "0.95.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/adapters/deno.ts

@@ -45,12 +45,17 @@ interface DenoHttpServer {
 interface DenoFsWatcher extends AsyncIterable<{ kind: string; paths: string[] }> {
   close(): void;
 }
+interface DenoFsFile {
+  stat(): Promise<{ isFile: boolean }>;
+  close(): void;
+}
 interface DenoGlobal {
   env: { get(name: string): string | undefined };
   cwd(): string;
   readTextFile(path: string): Promise<string>;
   readDir(path: string): AsyncIterable<{ name: string; isFile: boolean; isDirectory: boolean }>;
-  stat(path: string): Promise<unknown>;
+  stat(path: string): Promise<{ isFile: boolean }>;
+  open(path: string, options?: { read?: boolean }): Promise<DenoFsFile>;
   watchFs(paths: string | string[], options?: { recursive?: boolean }): DenoFsWatcher;
   serve(
     opts: { port: number; hostname?: string; onListen?: (a: { port: number }) => void },
@@ -124,6 +129,32 @@ export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
         return false;
       }
     },
+    async statFile(p) {
+      // Classify with a bare `stat` FIRST, then only open a *regular file* to confirm it is
+      // readable. The order matters: a read-only open of a FIFO (named pipe) blocks indefinitely
+      // waiting for a writer, so opening before the type check would hang every shell request on
+      // a FIFO sitting at this conventional asset path. A plain `stat` never blocks, so it safely
+      // rejects non-regular entries (directory, FIFO, socket, device) up front. The subsequent
+      // open/stat still answers the real serving condition — a file `stat` reports as regular can
+      // be unreadable (ACLs / permissions), and the shell must not link an asset that then 404s.
+      // Missing path → `null`; non-regular → `isFile: false`; unreadable → `null`.
+      try {
+        const meta = await Deno.stat(abs(p));
+        if (!meta.isFile) return { isFile: false };
+      } catch {
+        return null;
+      }
+      let file: DenoFsFile | undefined;
+      try {
+        file = await Deno.open(abs(p), { read: true });
+        const s = await file.stat();
+        return { isFile: s.isFile };
+      } catch {
+        return null;
+      } finally {
+        file?.close();
+      }
+    },
     openSqlite(path) {
       const db = new DatabaseSync(abs(path));
       return wrapSqlite(db);

package/src/runtime/adapters/node.test.ts

@@ -1,9 +1,18 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import * as http from "node:http";
+import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFile, fork } from "node:child_process";
+import { promisify } from "node:util";
 import { createNodeHost } from "./node.ts";
+import { isDeno } from "./detect.ts";
 import type { HttpServer } from "../core/host.ts";
 
+const execFileAsync = promisify(execFile);
+const nodeImportsTs = Number(process.versions.node.split(".")[0]) >= 22;
+
 // Issue #235: the node adapter must bind the interface it is handed so the manifest's
 // `network.bind` setting actually controls off-box reachability. We assert the *listen host*
 // the socket bound to for each setting by reading the native server's address.
@@ -65,3 +74,147 @@ test("serveHttp rejects when the port is already in use (does not hang)", async
     await first.stop();
   }
 });
+
+// PR #579: `statFile` is the shell's readable-regular-file probe for app assets (pages/app.css,
+// pages/app.js). It MUST classify the entry's type with a non-blocking `stat` BEFORE opening the
+// path for reading: a POSIX read-only open of a FIFO waits forever for a writer, so probing a FIFO
+// at the asset path would hang every shell request. This guards that a special-file entry returns
+// a non-regular verdict promptly instead of blocking. (POSIX-only: `mkfifo` isn't on Windows.)
+const hasMkfifo = process.platform !== "win32";
+// A blocked read-only `open` of a FIFO sits in libuv and CANNOT be cancelled from within the
+// process: `Promise.race` against a timeout would leave the losing probe running, and unlinking
+// the FIFO does not release it — the suite process would never exit, so the regression would not
+// actually fail fast. Run the probe in a killable CHILD process instead: the parent races the
+// child's verdict message against a timeout and SIGKILLs the child on timeout, so a blocking-open
+// regression fails this test fast (child startup + a ~2s probe budget) instead of wedging the runner.
+//
+// Two separate budgets, deliberately: the child first strip-types `node.ts` and its transitive
+// imports on a cold `--experimental-strip-types` start, which is HUNDREDS of ms and — crucially —
+// load-sensitive (observed >2s under the full parallel suite, #579). If a single timeout covered
+// both startup AND the `statFile` call, that cold-start cost would contaminate the probe budget and
+// the test would fail spuriously under load. So the child emits a `ready` message AFTER its imports
+// resolve; the parent only arms the (short) probe timeout once ready. Startup gets its own generous,
+// load-insensitive guard, and the probe budget then measures ONLY `statFile` — the blocking-open
+// regression (which manifests inside `statFile`, after `ready`) still fails fast.
+//
+// Node-only: the child is forked from `process.execPath` with Node-only flags
+// (`--experimental-strip-types`, `--input-type=module`). Under Deno, `child_process.fork` spawns
+// the DENO binary, which wraps the `--eval` source in a CJS shim (`$deno$eval.mts` →
+// `runInThisContext`) — the ESM `import` in the probe source is then a SyntaxError and the child
+// dies before `ready`. The probe is a guard for the NODE host adapter's blocking-open regression,
+// and the node-based suite (`npm test`, run by the `build` CI job) exercises it on every PR; the
+// Deno job runs this same file, so it must skip there rather than fail on the runtime mismatch.
+const PROBE_STARTUP_TIMEOUT_MS = 30_000;
+type FifoReadyMsg = { ready: true };
+type FifoVerdictMsg = { verdict: { isFile: boolean } | null };
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+function isFifoReadyMsg(value: unknown): value is FifoReadyMsg {
+  return isRecord(value) && value.ready === true;
+}
+function isFifoVerdictMsg(value: unknown): value is FifoVerdictMsg {
+  if (!isRecord(value) || !("verdict" in value)) return false;
+  const verdict = value.verdict;
+  if (verdict === null) return true;
+  return isRecord(verdict) && typeof verdict.isFile === "boolean";
+}
+function probeInChild(cwd: string, asset: string, probeTimeoutMs: number): Promise<FifoVerdictMsg | "timeout"> {
+  // `node --eval` places the first user argument at process.argv[1] (argv[0] is the node
+  // binary), so cwd is argv[1] and the asset path is argv[2] — NOT [2]/[3]. `ready` is sent once
+  // the host module is imported and built, BEFORE the (possibly blocking) `statFile` probe.
+  const source = `import { createNodeHost } from ${JSON.stringify(new URL("./node.ts", import.meta.url).href)};
+const host = createNodeHost({ cwd: process.argv[1], log: () => {} });
+process.send({ ready: true });
+const verdict = await host.statFile(process.argv[2]);
+process.send({ verdict });
+process.exit(0);`;
+  return new Promise((resolve, reject) => {
+    const child = fork(
+      "--input-type=module",
+      ["--experimental-strip-types", "--no-warnings", "--eval", source, cwd, asset],
+      { stdio: ["ignore", "ignore", "inherit", "ipc"] },
+    );
+    let probeTimer: ReturnType<typeof setTimeout> | undefined;
+    // Generous, load-insensitive guard: the child must finish importing and emit `ready` within
+    // this. A startup slower than 30s means a genuine hang in module load, not the FIFO probe.
+    const startupTimer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("probe child did not become ready (startup) in time"));
+    }, PROBE_STARTUP_TIMEOUT_MS);
+    const clearTimers = () => {
+      clearTimeout(startupTimer);
+      if (probeTimer !== undefined) clearTimeout(probeTimer);
+    };
+    child.on("message", (msg: unknown) => {
+      if (isFifoReadyMsg(msg)) {
+        // Startup done — now time ONLY the statFile call. A blocking-open regression blocks here
+        // and this short budget SIGKILLs the child, failing the test fast.
+        clearTimeout(startupTimer);
+        probeTimer = setTimeout(() => {
+          child.kill("SIGKILL");
+          resolve("timeout");
+        }, probeTimeoutMs);
+        return;
+      }
+      clearTimers();
+      child.disconnect();
+      if (isFifoVerdictMsg(msg)) resolve(msg);
+      else reject(new Error(`unexpected probe message: ${JSON.stringify(msg)}`));
+    });
+    child.once("error", (err) => {
+      clearTimers();
+      reject(err);
+    });
+    // Fail fast with the real cause when the child dies without messaging (e.g. a
+    // syntax/runtime crash during module load) instead of waiting out the startup
+    // timeout and reporting a misleading "did not become ready".
+    child.once("exit", (code, signal) => {
+      clearTimers();
+      reject(
+        new Error(
+          `probe child exited before reporting (code=${String(code)}, signal=${String(signal)})`,
+        ),
+      );
+    });
+  });
+}
+test(
+  "statFile classifies a FIFO as non-regular without blocking (does not hang)",
+  { skip: !hasMkfifo || !nodeImportsTs || isDeno() },
+  async () => {
+    const dir = await mkdtemp(join(tmpdir(), "urban-fifo-"));
+    try {
+      const fifo = join(dir, "app.css");
+      await execFileAsync("mkfifo", [fifo]);
+      const msg = await probeInChild(dir, "app.css", 2000);
+      assert.notEqual(msg, "timeout", "statFile must not block on a FIFO");
+      // Require a POSITIVE non-regular verdict. Accepting `null` (the probe-error path) would
+      // let the test pass vacuously without ever probing the FIFO — e.g. if the child crashed
+      // or read the wrong argv index and statFile swallowed the resulting path error.
+      assert.ok(
+        msg !== "timeout" && msg.verdict !== null && msg.verdict.isFile === false,
+        `a FIFO must positively probe as a non-regular file (got ${JSON.stringify(msg)})`,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  },
+);
+
+// Companion to the FIFO guard: a real regular file still probes as `isFile: true`, and a directory
+// at the asset path probes as non-regular — the two verdicts `mountPages` relies on to link only
+// genuinely servable assets.
+test("statFile reports a regular file as isFile and a directory as non-regular", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "urban-stat-"));
+  try {
+    await writeFile(join(dir, "app.js"), "export {};");
+    await mkdir(join(dir, "app.css"), { recursive: true });
+    const host = createNodeHost({ cwd: dir, log: () => {} });
+    assert.deepEqual(await host.statFile!("app.js"), { isFile: true });
+    assert.deepEqual(await host.statFile!("app.css"), { isFile: false });
+    assert.equal(await host.statFile!("missing.css"), null);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/adapters/node.ts

@@ -1,7 +1,7 @@
 // Node adapter — implements HostContext against `node:*`. This is one of only two files
 // (with deno.ts) allowed to touch a concrete runtime.
 
-import { readFile, readdir, stat } from "node:fs/promises";
+import { open, readFile, readdir, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { watch as fsWatch, type FSWatcher } from "node:fs";
 import { createServer } from "node:http";
@@ -154,6 +154,32 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
         return false;
       }
     },
+    async statFile(p) {
+      // Classify with a bare `stat` FIRST, then only open a *regular file* to confirm it is
+      // readable. The order matters: a read-only open of a FIFO (named pipe) blocks indefinitely
+      // waiting for a writer, so opening before the type check would hang every shell request on
+      // a FIFO sitting at this conventional asset path. A plain `stat` never blocks, so it safely
+      // rejects non-regular entries (directory, FIFO, socket, device) up front. The subsequent
+      // handle open/stat still answers the real serving condition — a file `stat` reports as
+      // regular can be unreadable (ACLs / permissions), and the shell must not link an asset that
+      // then 404s. Missing path → `null`; non-regular → `isFile: false`; unreadable → `null`.
+      try {
+        const meta = await stat(abs(p));
+        if (!meta.isFile()) return { isFile: false };
+      } catch {
+        return null;
+      }
+      let handle: Awaited<ReturnType<typeof open>> | undefined;
+      try {
+        handle = await open(abs(p), "r");
+        const s = await handle.stat();
+        return { isFile: s.isFile() };
+      } catch {
+        return null;
+      } finally {
+        await handle?.close();
+      }
+    },
     openSqlite(path) {
       const db = new DatabaseSync(abs(path));
       return wrapNodeSqlite(db);

package/src/runtime/core/glob.test.ts

@@ -16,6 +16,12 @@ function fakeHost(files: Record<string, string[]>): HostContext {
       const name = slash >= 0 ? p.slice(slash + 1) : p;
       return (files[dir] ?? []).includes(name);
     },
+    statFile: async (p) => {
+      const slash = p.lastIndexOf("/");
+      const dir = slash >= 0 ? p.slice(0, slash) : "";
+      const name = slash >= 0 ? p.slice(slash + 1) : p;
+      return (files[dir] ?? []).includes(name) ? { isFile: true } : null;
+    },
     openSqlite: () => {
       throw new Error("n/a");
     },

package/src/runtime/core/host.ts

@@ -101,6 +101,25 @@ export interface HostContext {
   listSubdirs?(dir: string): Promise<string[]>;
   /** True if the path exists (file or directory). */
   exists(path: string): Promise<boolean>;
+  /**
+   * Probe a path as a READABLE REGULAR FILE without reading its bytes: `{ isFile }` when it
+   * can be opened for reading, or `null` when it is absent or unreadable. The pages surface
+   * uses this to probe the app-owned `app.css`/`app.js` convention on the per-request shell
+   * hot path: `exists` is too broad (true for a DIRECTORY, which the shell would then link and
+   * the browser would 404 on), and probing via `readTextFile` reads and allocates a
+   * potentially large file just to answer "is it there?". A bare metadata `stat` is not
+   * enough either — it can succeed for a regular file that `readTextFile` cannot open (ACLs /
+   * permissions), so the shell would link an asset that then 404s on serving. Implementations
+   * therefore OPEN the file for reading (consuming no bytes) and stat the open handle, so this
+   * answers the same success condition as serving.
+   *
+   * OPTIONAL: `HostContext` is a public, externally-implementable seam (re-exported from
+   * `runtime/index.ts`, documented in the README as a supported custom-host extension point),
+   * so a new required member would be source-breaking. The pages surface falls back to a
+   * read-based probe when a host does not provide it; the built-in adapters do, as an
+   * allocation-free optimization on the hot path.
+   */
+  statFile?(path: string): Promise<{ isFile: boolean } | null>;
   /** Open (creating if needed) a SQLite database at a filesystem path. */
   openSqlite(path: string): SqliteDb;
   /**

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

@@ -82,6 +82,7 @@ function build(
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },
@@ -262,6 +263,7 @@ test("a rejected import is evicted from the cache so a later load can succeed",
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

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

@@ -47,6 +47,7 @@ function ctxWithFiles(files: Record<string, string>): RuntimeContext {
     },
     listDir: async () => [],
     exists: async (p: string) => p in files,
+    statFile: async (p: string) => (p in files ? { isFile: true } : null),
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

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

@@ -115,6 +115,7 @@ function build(
     readTextFile: async () => specText,
     listDir: async () => [],
     exists: async (p: string) => existsSet.has(p),
+    statFile: async (p: string) => (existsSet.has(p) ? { isFile: true } : null),
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },
@@ -645,6 +646,7 @@ test("a failed initial spec load is retried, not cached as a permanent 500", asy
     },
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

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

@@ -67,6 +67,7 @@ function makeCtx(
     env: (name) => opts.env?.[name],
     log: (level: string, msg: string) => logs.push({ level, msg }),
     exists: async (p: string) => p in files,
+    statFile: async (p: string) => (p in files ? { isFile: true } : null),
     readTextFile: async (p: string) => {
       if (!(p in files)) throw new Error(`ENOENT ${p}`);
       return files[p];

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

@@ -98,6 +98,7 @@ test("applyMigrations joins each migration file onto its dir without reintroduci
     env: () => undefined,
     now: () => 0,
     exists: async () => true,
+    statFile: async () => ({ isFile: true }),
     listDir: async () => ["002_b.sql", "001_a.sql"],
     readTextFile: async (path: string) => {
       readPaths.push(path);

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

@@ -144,6 +144,7 @@ function buildHarness(opts: {
     },
     listDir: async () => [],
     exists: async (p: string) => (p === BRIEF_PATH ? briefExists : false),
+    statFile: async (p: string) => (p === BRIEF_PATH && briefExists ? { isFile: true } : null),
     openSqlite: () => {
       throw new Error("sqlite not used in this harness");
     },

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

@@ -6,7 +6,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { EngineClient, HttpRequest, HttpResponse } from "../host.ts";
 import { makeRouter } from "../router.ts";
-import { createPagesRoutes, type GridLayout, type PagesDataSource, type PagesDeps, parseGridLayout } from "./pages.ts";
+import { createPagesRoutes, type GridLayout, type PagesDataSource, type PagesDeps, parseGridLayout, RUNTIME_JS_PATH } from "./pages.ts";
 
 function req(
   method: string,
@@ -2123,3 +2123,138 @@ test("#572: parseGridLayout accepts only the declared layouts (anything else is
   assert.equal(parseGridLayout("grid"), undefined);
   assert.equal(parseGridLayout(1), undefined);
 });
+
+// nano-ide#578 — an app MAY ship `pages/app.css` / `pages/app.js`; the shell links them only when present.
+function appAssetRoutes(files: Record<string, string>) {
+  return makeRouter(
+    createPagesRoutes(
+      { pagesDir: "pages", homePage: "home", sourceName: "app" },
+      {
+        db: fakeDb(),
+        engine: fakeEngine().engine,
+        readPage: async () => "{}",
+        readAsset: async (p) => {
+          const body = files[p];
+          if (body === undefined) throw new Error(`ENOENT ${p}`);
+          return body;
+        },
+      },
+    ),
+  );
+}
+
+test("#578: no app.css/app.js → the shell references neither (no 404 noise)", async () => {
+  const body = (await appAssetRoutes({})(req("GET", "/"))).body ?? "";
+  assert.doesNotMatch(body, /app\.css/);
+  assert.doesNotMatch(body, /app\.js/);
+});
+
+test("#578: app.css is linked AFTER the built-in CSS, and app.js loads after the runtime", async () => {
+  const router = appAssetRoutes({ "pages/app.css": "body{color:red}", "pages/app.js": "export {};" });
+  const body = (await router(req("GET", "/"))).body ?? "";
+  const css = body.indexOf('<link rel="stylesheet" href="./app.css" />');
+  assert.ok(css > body.indexOf("</style>"), "app.css must follow the renderer <style> so its rules win");
+  // Compare against the actual fingerprinted runtime <script> tag — the bare word "runtime"
+  // also appears in the embedded renderer CSS, so a substring match would pass even if the
+  // app script were moved before the runtime module.
+  const runtimeTag = `<script type="module" src=".${RUNTIME_JS_PATH}"></script>`;
+  const runtimeAt = body.indexOf(runtimeTag);
+  assert.ok(runtimeAt >= 0, "the shell references the fingerprinted runtime module");
+  const js = body.indexOf('<script type="module" src="./app.js"></script>');
+  assert.ok(js > runtimeAt, "app.js must load after the runtime module");
+  const cssRes = await router(req("GET", "/app.css"));
+  assert.equal(cssRes.status, 200);
+  assert.equal(cssRes.body, "body{color:red}");
+  assert.match(String(cssRes.headers?.["content-type"]), /text\/css/);
+  // Mutable at a stable URL: the browser must revalidate on every load so an edit (or a
+  // remove/re-add) takes effect without a restart — same policy as `/app/runtime.js`.
+  assert.equal(cssRes.headers?.["cache-control"], "no-cache");
+  const jsRes = await router(req("GET", "/app.js"));
+  assert.equal(jsRes.status, 200);
+  assert.match(String(jsRes.headers?.["content-type"]), /javascript/);
+  assert.equal(jsRes.headers?.["cache-control"], "no-cache");
+  // A missing app asset 404s no-cache too, so a cached 404 can't mask a later re-add.
+  const missing = await appAssetRoutes({})(req("GET", "/app.css"));
+  assert.equal(missing.status, 404);
+  assert.equal(missing.headers?.["cache-control"], "no-cache");
+});
+
+test("#578: only the present asset is referenced", async () => {
+  const body = (await appAssetRoutes({ "pages/app.css": "x" })(req("GET", "/"))).body ?? "";
+  assert.match(body, /href="\.\/app\.css"/);
+  assert.doesNotMatch(body, /src="\.\/app\.js"/);
+});
+
+test("#578: the shell probes existence WITHOUT reading the assets when the host offers an exists seam", async () => {
+  const files: Record<string, string> = { "pages/app.js": "export {};" };
+  const reads: string[] = [];
+  const probes: string[] = [];
+  const router = makeRouter(
+    createPagesRoutes(
+      { pagesDir: "pages", homePage: "home", sourceName: "app" },
+      {
+        db: fakeDb(),
+        engine: fakeEngine().engine,
+        readPage: async () => "{}",
+        readAsset: async (p) => {
+          reads.push(p);
+          const body = files[p];
+          if (body === undefined) throw new Error(`ENOENT ${p}`);
+          return body;
+        },
+        existsAsset: async (p) => {
+          probes.push(p);
+          return p in files;
+        },
+      },
+    ),
+  );
+  const body = (await router(req("GET", "/"))).body ?? "";
+  assert.match(body, /src="\.\/app\.js"/, "a present app.js is linked");
+  assert.doesNotMatch(body, /href="\.\/app\.css"/, "an absent app.css is not");
+  assert.deepEqual([...probes].sort(), ["pages/app.css", "pages/app.js"], "both assets are probed per shell request");
+  assert.deepEqual(reads, [], "no asset bytes are read to build the shell");
+
+  // Per-request, NOT memoized (#578 no-restart): swap which asset exists and re-request. A shell
+  // that cached the first probe result would keep linking app.js (and omit app.css); a genuine
+  // per-request probe must reflect the removal/addition AND re-probe BOTH paths on the next load.
+  probes.length = 0;
+  delete files["pages/app.js"];
+  files["pages/app.css"] = "body{color:red}";
+  const body2 = (await router(req("GET", "/"))).body ?? "";
+  assert.match(body2, /href="\.\/app\.css"/, "a newly-added app.css is linked on the next request");
+  assert.doesNotMatch(body2, /src="\.\/app\.js"/, "a removed app.js is dropped on the next request");
+  assert.deepEqual(
+    [...probes].sort(),
+    ["pages/app.css", "pages/app.js"],
+    "both assets are re-probed on the second request (no memoization)",
+  );
+  assert.deepEqual(reads, [], "still no asset bytes are read to build the shell");
+});
+
+test("#578: a DIRECTORY at an asset path is not linked (the probe is file-only, like serving)", async () => {
+  // `HostContext.exists` is true for files AND directories; the probe contract must answer
+  // "would serving this path succeed?" — a `pages/app.css/` directory 404s when read, so the
+  // shell must not link it. The injected probe here is exactly what `mountPages` builds from
+  // `HostContext.statFile` (`(await statFile(p))?.isFile === true`).
+  const files: Record<string, string> = { "pages/app.js": "export {};" };
+  const dirs = new Set(["pages/app.css"]);
+  const router = makeRouter(
+    createPagesRoutes(
+      { pagesDir: "pages", homePage: "home", sourceName: "app" },
+      {
+        db: fakeDb(),
+        engine: fakeEngine().engine,
+        readPage: async () => "{}",
+        readAsset: async (p) => {
+          if (dirs.has(p)) throw new Error(`EISDIR ${p}`);
+          throw new Error(`ENOENT ${p}`);
+        },
+        existsAsset: async (p) => !dirs.has(p) && p in files,
+      },
+    ),
+  );
+  const body = (await router(req("GET", "/"))).body ?? "";
+  assert.doesNotMatch(body, /href="\.\/app\.css"/, "a directory named app.css is not linked");
+  assert.match(body, /src="\.\/app\.js"/, "a real app.js file still is");
+});

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

@@ -27,7 +27,7 @@
 
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage, isRecord } from "../guards.ts";
-import type { EngineClient } from "../host.ts";
+import type { EngineClient, HttpResponse } from "../host.ts";
 import { html, json, type Route } from "../router.ts";
 import { cancelInstanceReconciling, type CancelInstanceResult } from "./cancel.ts";
 import { apiDocsPath } from "./api.ts";
@@ -89,6 +89,21 @@ export interface PagesDeps {
    * Injectable for tests. Rejects (→ 404) when the file is missing.
    */
   readAsset?(path: string): Promise<string>;
+  /**
+   * Probe whether a static asset exists as a READABLE REGULAR FILE at an app-root-relative
+   * path, WITHOUT reading its bytes. The per-request shell build uses this for the app-owned
+   * `app.css`/`app.js` convention (#578): those files can be large and the shell is revalidated
+   * on every load, so probing via a full `readAsset` would put an avoidable read + allocation
+   * on the HTML hot path (and read the file twice — once here, once when the browser fetches
+   * it). Must answer the same question the `readAsset` fallback answers — "would serving this
+   * path succeed?" — so a directory (or unreadable entry) at the path is a NO. `mountPages`
+   * wires this to the optional `HostContext.statFile` (which opens the file for reading to
+   * confirm a readable regular file — never `HostContext.exists`, which is true for directories
+   * too, and a `pages/app.css/` DIRECTORY would link an asset the browser then 404s on).
+   * Optional; falls back to a read-based probe when absent.
+   * Injectable for tests.
+   */
+  existsAsset?(path: string): Promise<boolean>;
   /**
    * List the available page ids (the `*.page.json` basenames under `pagesDir`),
    * powering the `/app/pages` index endpoint and a `nav` node's `items: "auto"`.
@@ -118,6 +133,13 @@ function javascript(
   };
 }
 
+// App-owned shell customisation by convention (nano-ide#578): an app MAY ship `pagesDir/app.css`
+// (linked AFTER the built-in renderer CSS, so its rules win — themes, restyling) and/or
+// `pagesDir/app.js` (an ES module loaded after the runtime — e.g. a theme picker). Each is served
+// as a root sidecar and referenced from the shell ONLY when the file exists, so apps without them
+// see no change and no 404.
+export const APP_ASSETS = ["app.css", "app.js"] as const;
+
 // 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
@@ -130,7 +152,7 @@ function javascript(
 // `./board/embed.html`, …) — those are served by the nested prefix route below (#442);
 // this flat set stays as the single-appView back-compat case (#420). The `dist/` tree the
 // import-map references is served separately under the `/dist/` prefix below.
-const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css"] as const;
+const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css", ...APP_ASSETS] 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`
@@ -226,6 +248,9 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   // 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;
+  // Existence probe for the app-owned shell assets (#578): a dedicated `existsAsset` when the
+  // host offers one (a metadata stat — no file bytes cross the seam), else a read-based probe.
+  const existsAsset = deps.existsAsset ?? ((path: string) => readAsset(path).then(() => true, () => false));
 
   // 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
@@ -262,16 +287,25 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   };
 
   const routes: Route[] = [];
-  const shell = html(rendererShell(homePage, opts.apiDocsPath, opts.gridLayout ?? "auto"));
   // The shell must never be pinned by the browser: it carries the *current* fingerprinted
   // runtime URL, so a stale shell would keep pointing at an old module hash. `no-cache` forces
   // a revalidation on every load; the shell body is tiny, and the expensive module it references
   // is what gets the long-lived immutable caching (via its content-hashed URL).
-  shell.headers = { ...shell.headers, "cache-control": "no-cache" };
+  // Built per request: it probes for the app-owned `app.css`/`app.js` (#578) so adding or removing
+  // one takes effect without a restart.
+  const shell = async (): Promise<HttpResponse> => {
+    const [appCss, appJs] = await Promise.all([
+      existsAsset(`${pagesDir}/app.css`),
+      existsAsset(`${pagesDir}/app.js`),
+    ]);
+    const res = html(rendererShell(homePage, opts.apiDocsPath, opts.gridLayout ?? "auto", { appCss, appJs }));
+    res.headers = { ...res.headers, "cache-control": "no-cache" };
+    return res;
+  };
 
   // ── the renderer shell + module ─────────────────────────────────────────
-  routes.push({ method: "GET", path: "/", source: "surface:pages", handler: () => shell });
-  routes.push({ method: "GET", path: "/index.html", source: "surface:pages", handler: () => shell });
+  routes.push({ method: "GET", path: "/", source: "surface:pages", handler: shell });
+  routes.push({ method: "GET", path: "/index.html", source: "surface:pages", handler: shell });
   // The fingerprinted module URL (referenced by the shell): unique per content, so cache it hard.
   routes.push({
     method: "GET",
@@ -299,11 +333,21 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   // 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) {
+    // The app-owned `app.css`/`app.js` are MUTABLE at stable URLs — the whole point of the
+    // convention is that an edit (or a remove/re-add) takes effect without a restart, and the
+    // shell re-probes on every load. Serve them `no-cache` (like `/app/runtime.js`) so a
+    // browser/intermediary must revalidate instead of replaying a heuristically-cached 200/404.
+    // The other sidecars are deploy-time fixtures, so they keep the generic response.
+    const mutable = APP_ASSETS.some((a) => a === name);
     routes.push({
       method: "GET",
       path: `/${name}`,
       source: "surface:pages",
-      handler: () => serveAsset(readAsset, `${pagesDir}/${name}`),
+      handler: async () => {
+        const res = await serveAsset(readAsset, `${pagesDir}/${name}`);
+        if (mutable) res.headers = { ...res.headers, "cache-control": "no-cache" };
+        return res;
+      },
     });
   }
   // The `dist/` tree the sidecars' import-maps reference (`../dist/cockpit/index.js` →
@@ -653,12 +697,24 @@ export function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle {
   };
   const sourceName = opts.sourceName ?? "app";
   const bindings = ctx.manifest.instanceTracking ?? [];
+  // Probe "would serving this app-owned asset succeed?" — a READABLE REGULAR FILE, not the
+  // broader `HostContext.exists` (which is true for directories too, and a `pages/app.css/`
+  // DIRECTORY would link an asset the browser then 404s on). `statFile` is an OPTIONAL public
+  // host capability (a custom host need not implement it), and it opens the file for reading so
+  // no bytes cross the seam on the per-request shell hot path. Only wire the optimized probe
+  // when the host provides it; otherwise `createPagesRoutes` falls back to a read-based probe
+  // that answers the identical question.
+  const statFile = ctx.host.statFile?.bind(ctx.host);
+  const existsAsset = statFile
+    ? async (p: string) => (await statFile(p))?.isFile === true
+    : undefined;
   const routes = createPagesRoutes(opts, {
     db: app.data.open(sourceName),
     engine: app.engine,
     cancel: (key) => cancelInstanceReconciling(app, bindings, key),
     readPage: (p) => ctx.host.readTextFile(p),
     readAsset: (p) => ctx.host.readTextFile(p),
+    existsAsset,
     listPages: async () => {
       const dir = opts.pagesDir ?? "pages";
       const names = await ctx.host.listDir(dir).catch(() => []);
@@ -679,7 +735,12 @@ function escapeAttr(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-function rendererShell(homePage: string, apiDocsPath: string | undefined, gridLayout: GridLayout): string {
+function rendererShell(
+  homePage: string,
+  apiDocsPath: string | undefined,
+  gridLayout: GridLayout,
+  app: { appCss: boolean; appJs: boolean } = { appCss: false, appJs: false },
+): string {
   // A persistent "API docs" badge (spec-first apps get their Swagger UI linked from their own
   // UI for free). `target="_blank"` + hardened `rel` so the docs open without giving the docs
   // tab a handle back to this window (reverse-tabnabbing).
@@ -704,12 +765,12 @@ function rendererShell(homePage: string, apiDocsPath: string | undefined, gridLa
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Urban App</title>
-  <style>${RENDERER_CSS}</style>
+  <style>${RENDERER_CSS}</style>${app.appCss ? '\n  <link rel="stylesheet" href="./app.css" />' : ""}
 </head>
 <body data-grid-layout="${gridLayout}">${apiDocsBadge}
   <main id="page" data-home="${escapeAttr(homePage)}"><p class="pc-empty">Loading…</p></main>
   <script>${FORMJS_JS}</script>
-  <script type="module" src=".${RUNTIME_JS_PATH}"></script>
+  <script type="module" src=".${RUNTIME_JS_PATH}"></script>${app.appJs ? '\n  <script type="module" src="./app.js"></script>' : ""}
 </body>
 </html>`;
 }
@@ -1095,5 +1156,8 @@ function fnv1aHex(s: string): string {
 // other page action) do nothing after an upgrade until a hard refresh. Because the URL is unique
 // per content, the response itself is served `immutable` with a one-year max-age.
 const RUNTIME_JS_HASH = fnv1aHex(RENDERER_JS);
-const RUNTIME_JS_PATH = `/app/runtime.${RUNTIME_JS_HASH}.js`;
+// Exported so tests can locate the actual fingerprinted runtime <script> tag in the shell
+// (asserting against the bare word "runtime" is unsound — it also appears in the embedded
+// renderer CSS, so such a test passes even if the app script were moved before the runtime).
+export const RUNTIME_JS_PATH = `/app/runtime.${RUNTIME_JS_HASH}.js`;
 const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";

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

@@ -16,6 +16,7 @@ function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurf
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

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

@@ -80,6 +80,7 @@ function fakeCtx(triggers: Trigger[]): { ctx: RuntimeContext; hostLogs: Array<{
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

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

@@ -68,6 +68,7 @@ function makeCtx(
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

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

@@ -757,3 +757,30 @@ test('#572: an omitted surfaces.pages.gridLayout falls back to the "auto" layout
 test('#572: an invalid surfaces.pages.gridLayout falls back to the "auto" layout', async () => {
   assert.equal(await shellGridLayout({ gridLayout: "grid" }), "auto");
 });
+
+// #578: app-owned `pages/app.css`/`pages/app.js` by convention, driven end-to-end through the real
+// node host (createUrbanApp → mountPages → HostContext.statFile), not an injected `existsAsset`.
+// This guards the production wiring the focused pages.test.ts probe tests can't: that `mountPages`
+// forwards the host's file-only probe (so a DIRECTORY at an asset path is NOT linked — it would
+// 404 on serving) and that a real regular file IS linked.
+test("#578: the shell links a real pages/app.js file but not a pages/app.css DIRECTORY (real host)", async () => {
+  const dir = await makeFixture({ surfaces: { pages: { enabled: true } } });
+  // A regular file at pages/app.js (should be linked) and a DIRECTORY at pages/app.css (should not).
+  await mkdir(join(dir, "pages"), { recursive: true });
+  await writeFile(join(dir, "pages", "app.js"), "export {};");
+  await mkdir(join(dir, "pages", "app.css"), { recursive: true });
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+  try {
+    const res = await fetch(`http://localhost:${app.httpPort!}/`);
+    assert.equal(res.status, 200);
+    const body = await res.text();
+    assert.match(body, /src="\.\/app\.js"/, "a real app.js file is linked");
+    assert.doesNotMatch(body, /href="\.\/app\.css"/, "a DIRECTORY named app.css is not linked");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/devserver.test.ts

@@ -205,6 +205,7 @@ function fakeHost(): { host: HostContext; fire: (p: string) => void; closed: ()
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },