@nanobpm/urban 0.93.1 → 0.94.1

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

@@ -2,6 +2,10 @@ import type { AppApi, RuntimeContext } from "../context.ts";
 import type { EngineClient } from "../host.ts";
 import { type Route } from "../router.ts";
 import { type CancelInstanceResult } from "./cancel.ts";
+/** The app-wide dataGrid layout (`surfaces.pages.gridLayout`, nano-ide#572). */
+export type GridLayout = "auto" | "cards";
+/** Narrow an untyped manifest value to a declared {@link GridLayout}; anything else is undefined (→ `"auto"`). */
+export declare function parseGridLayout(value: unknown): GridLayout | undefined;
 /** The subset of the datasource gateway the page runtime needs. */
 export interface PagesDataSource {
     query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
@@ -14,6 +18,12 @@ export interface PagesOptions {
     pagesDir?: string;
     /** The page served at `/`. Default `home`. */
     homePage?: string;
+    /**
+     * How every `dataGrid` lays out (nano-ide#572). `"auto"` (default): a table, flipping to the card
+     * list below the mobile breakpoint. `"cards"`: the card list at every width — for apps whose
+     * fixed-max-width shell would otherwise clip wide grids.
+     */
+    gridLayout?: GridLayout;
     /** Max rows a `dataGrid` fetch returns. Default 200. */
     rowLimit?: number;
     /** The injected default datasource name (the alias apps bind to). Default `app`. */

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

@@ -33,6 +33,10 @@ import { completeUserTaskResponse, resolveFormResponse } from "./forms.js";
 import { quoteIdent } from "./gateway.js";
 import { RENDERER_JS } from "./runtime.gen.js";
 import { isSqlIdentifier } from "../read-model.js";
+/** Narrow an untyped manifest value to a declared {@link GridLayout}; anything else is undefined (→ `"auto"`). */
+export function parseGridLayout(value) {
+    return value === "auto" || value === "cards" ? value : undefined;
+}
 /** A JavaScript-body response (the renderer module served at the fingerprinted
  * `/app/runtime.<hash>.js`, and its `/app/runtime.js` back-compat route). */
 function javascript(body, status = 200, extraHeaders) {
@@ -177,7 +181,7 @@ export function createPagesRoutes(opts, deps) {
         return p;
     };
     const routes = [];
-    const shell = html(rendererShell(homePage, opts.apiDocsPath));
+    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
@@ -567,6 +571,7 @@ export function mountPages(ctx, app) {
     const opts = {
         pagesDir: typeof decl.pagesDir === "string" ? decl.pagesDir : undefined,
         homePage: typeof decl.homePage === "string" ? decl.homePage : undefined,
+        gridLayout: parseGridLayout(decl.gridLayout),
         rowLimit: typeof decl.rowLimit === "number" ? decl.rowLimit : undefined,
         sourceName: typeof decl.sourceName === "string" ? decl.sourceName : undefined,
         // Link the shell's "API docs" badge to the app's Swagger UI when it declares an `api`
@@ -599,7 +604,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) {
+function rendererShell(homePage, apiDocsPath, gridLayout) {
     // 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).
@@ -625,7 +630,7 @@ function rendererShell(homePage, apiDocsPath) {
   <title>Urban App</title>
   <style>${RENDERER_CSS}</style>
 </head>
-<body>${apiDocsBadge}
+<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>
@@ -633,7 +638,7 @@ function rendererShell(homePage, apiDocsPath) {
 </html>`;
 }
 // The app's stylesheet resolves every colour through the Nano console's
-// semantic `--nano-*` token contract (see the Magikcraft/nano-bpm repo's
+// semantic `--nano-*` token contract (see the nanobpm/nano-bpm repo's
 // `console/src/theme/tokens.css` — MIRROR: keep the palettes below in sync). When the app is embedded in the
 // console it inherits nothing across the iframe boundary, so the console
 // postMessages its resolved tokens + appearance and the runtime lays them onto
@@ -647,6 +652,73 @@ function rendererShell(homePage, apiDocsPath) {
 // stacking) AND the runtime's `matchMedia` mode-switch (which only Tier-2's
 // optional page-level `mobile` layout variant needs), so the two can never
 // drift apart on where "narrow" begins.
+/**
+ * The dataGrid → card-list rules (#268), in ONE place. They are emitted twice from this single source:
+ * unscoped inside the mobile `@media` block (every app, narrow viewports) and scoped to
+ * `[data-grid-layout="cards"]` at top level (apps that opt into cards at every width, nano-ide#572).
+ * `scope` is prefixed onto every selector of every rule, so the two copies can never drift.
+ */
+function gridCardRules(scope) {
+    const css = `
+  /* dataGrid → card list. Once cells are display:block the fixed colgroup width
+     is irrelevant, so a wide table stops overflowing the phone. table-layout is
+     reset to auto so the block cells size to content. */
+  table.pc-grid { table-layout:auto; }
+  table.pc-grid, table.pc-grid tbody, table.pc-grid tr, table.pc-grid td { display:block; width:auto; }
+  table.pc-grid colgroup, table.pc-grid thead { display:none; }
+  table.pc-grid tr { border:1px solid var(--nano-edge); border-radius:.6rem; padding:.55rem .75rem; margin:.6rem 0; background:var(--nano-panel); }
+  table.pc-grid td { border-bottom:0; padding:.15rem 0; display:flex; gap:.75rem; justify-content:space-between; align-items:baseline; }
+  /* label:value — the column header (data-label) prefixes the value as a muted
+     caption on the same line. Suppressed for the title, chip, actions and any
+     colspan (group/empty/error) cells below. */
+  table.pc-grid td[data-label]::before { content:attr(data-label); color:var(--nano-text-muted); font-size:.72rem; font-weight:600; text-transform:uppercase; letter-spacing:.03em; flex:0 0 auto; }
+  /* The derived (or mobile:{priority:"primary"}-hinted) card title leads the
+     card: larger, full width, no label caption. */
+  table.pc-grid td.pc-mcell-primary { display:block; font-size:1rem; font-weight:650; padding-top:.15rem; }
+  table.pc-grid td.pc-mcell-primary::before { content:none; }
+  /* A badge column becomes a left-aligned status chip with no caption. */
+  table.pc-grid td.pc-mcell-chip { justify-content:flex-start; }
+  table.pc-grid td.pc-mcell-chip::before { content:none; }
+  /* An empty badge cell (row value blank) still carries the chip class but has no
+     child content; without this it renders as a blank flex row (padding/gap) that
+     leaves a stray empty line in the card. Collapse those empty chip cells (#268). */
+  table.pc-grid td.pc-mcell-chip:empty { display:none; }
+  /* Low-value (mobile:{priority:"hidden"}) columns drop off the card until the
+     row's "More" toggle opens them; on desktop they render as normal columns. */
+  table.pc-grid td.pc-mcell-hidden { display:none; }
+  table.pc-grid tr.pc-open td.pc-mcell-hidden { display:flex; }
+  .pc-mcard-toggle { display:block; padding:.3rem 0 0; }
+  .pc-mcard-toggle .pc-more { width:100%; margin-right:0; }
+  /* Row actions stack full-width under the card body. */
+  table.pc-grid td.pc-row-actions { display:flex; flex-wrap:wrap; gap:.4rem; text-align:left; padding-top:.45rem; white-space:normal; }
+  table.pc-grid td.pc-row-actions::before { content:none; }
+  table.pc-grid td.pc-row-actions .pc-btn { flex:1 1 auto; margin-right:0; }
+  /* Group-header + empty/error rows span the full card width with no caption. */
+  table.pc-grid td[colspan] { display:block; }
+  table.pc-grid td[colspan]::before { content:none; }
+  .pc-group-header td { padding:0; }
+`;
+    if (scope === "")
+        return css.replace(/^\n/, "");
+    // The scoped copy drops the comments (they document the mobile copy) and scopes each rule line.
+    return css
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => {
+        const brace = line.indexOf("{");
+        if (brace < 0)
+            return line;
+        const selectors = line
+            .slice(0, brace)
+            .split(",")
+            .map((sel) => `${scope} ${sel.trim()}`)
+            .join(", ");
+        return `  ${selectors} ${line.slice(brace)}`;
+    })
+        .join("\n")
+        .concat("\n");
+}
 const MOBILE_MAX_WIDTH = "640px";
 const RENDERER_CSS = `
 :root {
@@ -896,44 +968,7 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
    matchMedia. */
 @media (max-width:${MOBILE_MAX_WIDTH}) {
   body { padding:1rem; }
-  /* dataGrid → card list. Once cells are display:block the fixed colgroup width
-     is irrelevant, so a wide table stops overflowing the phone. table-layout is
-     reset to auto so the block cells size to content. */
-  table.pc-grid { table-layout:auto; }
-  table.pc-grid, table.pc-grid tbody, table.pc-grid tr, table.pc-grid td { display:block; width:auto; }
-  table.pc-grid colgroup, table.pc-grid thead { display:none; }
-  table.pc-grid tr { border:1px solid var(--nano-edge); border-radius:.6rem; padding:.55rem .75rem; margin:.6rem 0; background:var(--nano-panel); }
-  table.pc-grid td { border-bottom:0; padding:.15rem 0; display:flex; gap:.75rem; justify-content:space-between; align-items:baseline; }
-  /* label:value — the column header (data-label) prefixes the value as a muted
-     caption on the same line. Suppressed for the title, chip, actions and any
-     colspan (group/empty/error) cells below. */
-  table.pc-grid td[data-label]::before { content:attr(data-label); color:var(--nano-text-muted); font-size:.72rem; font-weight:600; text-transform:uppercase; letter-spacing:.03em; flex:0 0 auto; }
-  /* The derived (or mobile:{priority:"primary"}-hinted) card title leads the
-     card: larger, full width, no label caption. */
-  table.pc-grid td.pc-mcell-primary { display:block; font-size:1rem; font-weight:650; padding-top:.15rem; }
-  table.pc-grid td.pc-mcell-primary::before { content:none; }
-  /* A badge column becomes a left-aligned status chip with no caption. */
-  table.pc-grid td.pc-mcell-chip { justify-content:flex-start; }
-  table.pc-grid td.pc-mcell-chip::before { content:none; }
-  /* An empty badge cell (row value blank) still carries the chip class but has no
-     child content; without this it renders as a blank flex row (padding/gap) that
-     leaves a stray empty line in the card. Collapse those empty chip cells (#268). */
-  table.pc-grid td.pc-mcell-chip:empty { display:none; }
-  /* Low-value (mobile:{priority:"hidden"}) columns drop off the card until the
-     row's "More" toggle opens them; on desktop they render as normal columns. */
-  table.pc-grid td.pc-mcell-hidden { display:none; }
-  table.pc-grid tr.pc-open td.pc-mcell-hidden { display:flex; }
-  .pc-mcard-toggle { display:block; padding:.3rem 0 0; }
-  .pc-mcard-toggle .pc-more { width:100%; margin-right:0; }
-  /* Row actions stack full-width under the card body. */
-  table.pc-grid td.pc-row-actions { display:flex; flex-wrap:wrap; gap:.4rem; text-align:left; padding-top:.45rem; white-space:normal; }
-  table.pc-grid td.pc-row-actions::before { content:none; }
-  table.pc-grid td.pc-row-actions .pc-btn { flex:1 1 auto; margin-right:0; }
-  /* Group-header + empty/error rows span the full card width with no caption. */
-  table.pc-grid td[colspan] { display:block; }
-  table.pc-grid td[colspan]::before { content:none; }
-  .pc-group-header td { padding:0; }
-  /* Nav → horizontally-scrollable bar (bar) / inline stack (rail). The bar keeps
+${gridCardRules("")}  /* Nav → horizontally-scrollable bar (bar) / inline stack (rail). The bar keeps
      its normal top-of-flow position and scrolls sideways when the pages overflow;
      an opt-in sticky bar stays pinned to the top via the desktop .pc-sticky rule
      (top:0). A rail drops its fixed side column and flows inline. */
@@ -951,7 +986,8 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
   .pc-modal-actions { flex-direction:column; }
   .pc-modal-actions .pc-btn { width:100%; }
 }
-`;
+/* App-wide card layout (nano-ide#572): the same card rules, at every width. */
+${gridCardRules('[data-grid-layout="cards"]')}`;
 // The schema-driven browser renderer (ADR 0042 §3). Plain ES module string served at
 // /app/runtime.js — it does NOT ship Craft.js (authoring is console-side only). It
 // fetches the home page's page.json and renders text / actionForm / dataGrid / prose

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.93.1",
+	"version": "0.94.1",
 	"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",
@@ -104,7 +104,7 @@
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"@nanobpm/agentic": "^0.14.0",
-		"@nanobpm/nano-app-schema": "^0.9.0",
+		"@nanobpm/nano-app-schema": "^0.11.0",
 		"@nanobpm/nano-sdk": "^1.2.5",
 		"@nanobpm/workflow": "^0.14.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",

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 PagesDataSource, type PagesDeps } from "./pages.ts";
+import { createPagesRoutes, type GridLayout, type PagesDataSource, type PagesDeps, parseGridLayout } from "./pages.ts";
 
 function req(
   method: string,
@@ -2072,3 +2072,54 @@ test("the pages shell embeds the shared form-js renderer (NanoFormJs) for engine
   assert.match(res.body ?? "", /NanoFormJs/, "the shell exposes the shared renderer as a global");
   assert.match(res.body ?? "", /function renderForm/, "the shared renderer is embedded, not forked");
 });
+
+// nano-ide#572 — an app-wide opt-in (`surfaces.pages.gridLayout: "cards"`) renders every dataGrid as
+// the card list at ANY viewport width, not just below the mobile breakpoint.
+async function shellFor(gridLayout?: GridLayout): Promise<HttpResponse> {
+  const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app", gridLayout }, {
+    db: fakeDb(),
+    engine: fakeEngine().engine,
+    readPage: async () => "{}",
+  });
+  return await makeRouter(routes)(req("GET", "/"));
+}
+
+test("#572: gridLayout \"cards\" stamps the shell so dataGrids render as cards at every width", async () => {
+  const html = (await shellFor("cards")).body ?? "";
+  assert.match(html, /<body data-grid-layout="cards">/);
+});
+
+test("#572: the default (and \"auto\") keep today's table-on-desktop layout", async () => {
+  for (const layout of [undefined, "auto"] as const) {
+    const html = (await shellFor(layout)).body ?? "";
+    assert.match(html, /<body data-grid-layout="auto">/);
+  }
+});
+
+test("#572: the always-cards rules are DERIVED from the mobile card rules — identical, just scoped", async () => {
+  const html = (await shellFor("cards")).body ?? "";
+  const media = (html.match(/@media \(max-width:640px\) \{[\s\S]*?\n\}/) ?? [""])[0];
+  const gridRules = (css: string) =>
+    css
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => /(pc-grid|pc-mcard-toggle|pc-group-header)[^{]*\{/.test(l) && !l.startsWith("/*"));
+  const mobile = gridRules(media);
+  assert.ok(mobile.length > 5, "the mobile block carries the card rules");
+  const scoped = gridRules(html).filter((l) => l.startsWith('[data-grid-layout="cards"]'));
+  const unscoped = scoped.map((l) => l.replace(/\[data-grid-layout="cards"\] /g, ""));
+  assert.deepEqual(unscoped, mobile, "every card rule appears once, scoped to the cards layout, byte-identical");
+  // Every selector in a comma list is scoped, so no rule leaks onto the "auto" layout.
+  for (const l of scoped) {
+    const selectors = l.slice(0, l.indexOf("{")).split(",");
+    for (const s of selectors) assert.match(s.trim(), /^\[data-grid-layout="cards"\] /, `unscoped selector in: ${l}`);
+  }
+});
+
+test("#572: parseGridLayout accepts only the declared layouts (anything else is the \"auto\" default)", () => {
+  assert.equal(parseGridLayout("cards"), "cards");
+  assert.equal(parseGridLayout("auto"), "auto");
+  assert.equal(parseGridLayout(undefined), undefined);
+  assert.equal(parseGridLayout("grid"), undefined);
+  assert.equal(parseGridLayout(1), undefined);
+});

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

@@ -37,6 +37,14 @@ import { quoteIdent } from "./gateway.ts";
 import { RENDERER_JS } from "./runtime.gen.ts";
 import { isSqlIdentifier } from "../read-model.ts";
 
+/** The app-wide dataGrid layout (`surfaces.pages.gridLayout`, nano-ide#572). */
+export type GridLayout = "auto" | "cards";
+
+/** Narrow an untyped manifest value to a declared {@link GridLayout}; anything else is undefined (→ `"auto"`). */
+export function parseGridLayout(value: unknown): GridLayout | undefined {
+  return value === "auto" || value === "cards" ? value : undefined;
+}
+
 /** The subset of the datasource gateway the page runtime needs. */
 export interface PagesDataSource {
   query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
@@ -48,6 +56,12 @@ export interface PagesOptions {
   pagesDir?: string;
   /** The page served at `/`. Default `home`. */
   homePage?: string;
+  /**
+   * How every `dataGrid` lays out (nano-ide#572). `"auto"` (default): a table, flipping to the card
+   * list below the mobile breakpoint. `"cards"`: the card list at every width — for apps whose
+   * fixed-max-width shell would otherwise clip wide grids.
+   */
+  gridLayout?: GridLayout;
   /** Max rows a `dataGrid` fetch returns. Default 200. */
   rowLimit?: number;
   /** The injected default datasource name (the alias apps bind to). Default `app`. */
@@ -248,7 +262,7 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   };
 
   const routes: Route[] = [];
-  const shell = html(rendererShell(homePage, opts.apiDocsPath));
+  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
@@ -630,6 +644,7 @@ export function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle {
   const opts: PagesOptions = {
     pagesDir: typeof decl.pagesDir === "string" ? decl.pagesDir : undefined,
     homePage: typeof decl.homePage === "string" ? decl.homePage : undefined,
+    gridLayout: parseGridLayout(decl.gridLayout),
     rowLimit: typeof decl.rowLimit === "number" ? decl.rowLimit : undefined,
     sourceName: typeof decl.sourceName === "string" ? decl.sourceName : undefined,
     // Link the shell's "API docs" badge to the app's Swagger UI when it declares an `api`
@@ -664,7 +679,7 @@ 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): string {
+function rendererShell(homePage: string, apiDocsPath: string | undefined, gridLayout: GridLayout): 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).
@@ -691,7 +706,7 @@ function rendererShell(homePage: string, apiDocsPath?: string): string {
   <title>Urban App</title>
   <style>${RENDERER_CSS}</style>
 </head>
-<body>${apiDocsBadge}
+<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>
@@ -700,7 +715,7 @@ function rendererShell(homePage: string, apiDocsPath?: string): string {
 }
 
 // The app's stylesheet resolves every colour through the Nano console's
-// semantic `--nano-*` token contract (see the Magikcraft/nano-bpm repo's
+// semantic `--nano-*` token contract (see the nanobpm/nano-bpm repo's
 // `console/src/theme/tokens.css` — MIRROR: keep the palettes below in sync). When the app is embedded in the
 // console it inherits nothing across the iframe boundary, so the console
 // postMessages its resolved tokens + appearance and the runtime lays them onto
@@ -714,6 +729,72 @@ function rendererShell(homePage: string, apiDocsPath?: string): string {
 // stacking) AND the runtime's `matchMedia` mode-switch (which only Tier-2's
 // optional page-level `mobile` layout variant needs), so the two can never
 // drift apart on where "narrow" begins.
+/**
+ * The dataGrid → card-list rules (#268), in ONE place. They are emitted twice from this single source:
+ * unscoped inside the mobile `@media` block (every app, narrow viewports) and scoped to
+ * `[data-grid-layout="cards"]` at top level (apps that opt into cards at every width, nano-ide#572).
+ * `scope` is prefixed onto every selector of every rule, so the two copies can never drift.
+ */
+function gridCardRules(scope: string): string {
+  const css = `
+  /* dataGrid → card list. Once cells are display:block the fixed colgroup width
+     is irrelevant, so a wide table stops overflowing the phone. table-layout is
+     reset to auto so the block cells size to content. */
+  table.pc-grid { table-layout:auto; }
+  table.pc-grid, table.pc-grid tbody, table.pc-grid tr, table.pc-grid td { display:block; width:auto; }
+  table.pc-grid colgroup, table.pc-grid thead { display:none; }
+  table.pc-grid tr { border:1px solid var(--nano-edge); border-radius:.6rem; padding:.55rem .75rem; margin:.6rem 0; background:var(--nano-panel); }
+  table.pc-grid td { border-bottom:0; padding:.15rem 0; display:flex; gap:.75rem; justify-content:space-between; align-items:baseline; }
+  /* label:value — the column header (data-label) prefixes the value as a muted
+     caption on the same line. Suppressed for the title, chip, actions and any
+     colspan (group/empty/error) cells below. */
+  table.pc-grid td[data-label]::before { content:attr(data-label); color:var(--nano-text-muted); font-size:.72rem; font-weight:600; text-transform:uppercase; letter-spacing:.03em; flex:0 0 auto; }
+  /* The derived (or mobile:{priority:"primary"}-hinted) card title leads the
+     card: larger, full width, no label caption. */
+  table.pc-grid td.pc-mcell-primary { display:block; font-size:1rem; font-weight:650; padding-top:.15rem; }
+  table.pc-grid td.pc-mcell-primary::before { content:none; }
+  /* A badge column becomes a left-aligned status chip with no caption. */
+  table.pc-grid td.pc-mcell-chip { justify-content:flex-start; }
+  table.pc-grid td.pc-mcell-chip::before { content:none; }
+  /* An empty badge cell (row value blank) still carries the chip class but has no
+     child content; without this it renders as a blank flex row (padding/gap) that
+     leaves a stray empty line in the card. Collapse those empty chip cells (#268). */
+  table.pc-grid td.pc-mcell-chip:empty { display:none; }
+  /* Low-value (mobile:{priority:"hidden"}) columns drop off the card until the
+     row's "More" toggle opens them; on desktop they render as normal columns. */
+  table.pc-grid td.pc-mcell-hidden { display:none; }
+  table.pc-grid tr.pc-open td.pc-mcell-hidden { display:flex; }
+  .pc-mcard-toggle { display:block; padding:.3rem 0 0; }
+  .pc-mcard-toggle .pc-more { width:100%; margin-right:0; }
+  /* Row actions stack full-width under the card body. */
+  table.pc-grid td.pc-row-actions { display:flex; flex-wrap:wrap; gap:.4rem; text-align:left; padding-top:.45rem; white-space:normal; }
+  table.pc-grid td.pc-row-actions::before { content:none; }
+  table.pc-grid td.pc-row-actions .pc-btn { flex:1 1 auto; margin-right:0; }
+  /* Group-header + empty/error rows span the full card width with no caption. */
+  table.pc-grid td[colspan] { display:block; }
+  table.pc-grid td[colspan]::before { content:none; }
+  .pc-group-header td { padding:0; }
+`;
+  if (scope === "") return css.replace(/^\n/, "");
+  // The scoped copy drops the comments (they document the mobile copy) and scopes each rule line.
+  return css
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .split("\n")
+    .filter((line) => line.trim() !== "")
+    .map((line) => {
+      const brace = line.indexOf("{");
+      if (brace < 0) return line;
+      const selectors = line
+        .slice(0, brace)
+        .split(",")
+        .map((sel) => `${scope} ${sel.trim()}`)
+        .join(", ");
+      return `  ${selectors} ${line.slice(brace)}`;
+    })
+    .join("\n")
+    .concat("\n");
+}
+
 const MOBILE_MAX_WIDTH = "640px";
 
 const RENDERER_CSS = `
@@ -964,44 +1045,7 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
    matchMedia. */
 @media (max-width:${MOBILE_MAX_WIDTH}) {
   body { padding:1rem; }
-  /* dataGrid → card list. Once cells are display:block the fixed colgroup width
-     is irrelevant, so a wide table stops overflowing the phone. table-layout is
-     reset to auto so the block cells size to content. */
-  table.pc-grid { table-layout:auto; }
-  table.pc-grid, table.pc-grid tbody, table.pc-grid tr, table.pc-grid td { display:block; width:auto; }
-  table.pc-grid colgroup, table.pc-grid thead { display:none; }
-  table.pc-grid tr { border:1px solid var(--nano-edge); border-radius:.6rem; padding:.55rem .75rem; margin:.6rem 0; background:var(--nano-panel); }
-  table.pc-grid td { border-bottom:0; padding:.15rem 0; display:flex; gap:.75rem; justify-content:space-between; align-items:baseline; }
-  /* label:value — the column header (data-label) prefixes the value as a muted
-     caption on the same line. Suppressed for the title, chip, actions and any
-     colspan (group/empty/error) cells below. */
-  table.pc-grid td[data-label]::before { content:attr(data-label); color:var(--nano-text-muted); font-size:.72rem; font-weight:600; text-transform:uppercase; letter-spacing:.03em; flex:0 0 auto; }
-  /* The derived (or mobile:{priority:"primary"}-hinted) card title leads the
-     card: larger, full width, no label caption. */
-  table.pc-grid td.pc-mcell-primary { display:block; font-size:1rem; font-weight:650; padding-top:.15rem; }
-  table.pc-grid td.pc-mcell-primary::before { content:none; }
-  /* A badge column becomes a left-aligned status chip with no caption. */
-  table.pc-grid td.pc-mcell-chip { justify-content:flex-start; }
-  table.pc-grid td.pc-mcell-chip::before { content:none; }
-  /* An empty badge cell (row value blank) still carries the chip class but has no
-     child content; without this it renders as a blank flex row (padding/gap) that
-     leaves a stray empty line in the card. Collapse those empty chip cells (#268). */
-  table.pc-grid td.pc-mcell-chip:empty { display:none; }
-  /* Low-value (mobile:{priority:"hidden"}) columns drop off the card until the
-     row's "More" toggle opens them; on desktop they render as normal columns. */
-  table.pc-grid td.pc-mcell-hidden { display:none; }
-  table.pc-grid tr.pc-open td.pc-mcell-hidden { display:flex; }
-  .pc-mcard-toggle { display:block; padding:.3rem 0 0; }
-  .pc-mcard-toggle .pc-more { width:100%; margin-right:0; }
-  /* Row actions stack full-width under the card body. */
-  table.pc-grid td.pc-row-actions { display:flex; flex-wrap:wrap; gap:.4rem; text-align:left; padding-top:.45rem; white-space:normal; }
-  table.pc-grid td.pc-row-actions::before { content:none; }
-  table.pc-grid td.pc-row-actions .pc-btn { flex:1 1 auto; margin-right:0; }
-  /* Group-header + empty/error rows span the full card width with no caption. */
-  table.pc-grid td[colspan] { display:block; }
-  table.pc-grid td[colspan]::before { content:none; }
-  .pc-group-header td { padding:0; }
-  /* Nav → horizontally-scrollable bar (bar) / inline stack (rail). The bar keeps
+${gridCardRules("")}  /* Nav → horizontally-scrollable bar (bar) / inline stack (rail). The bar keeps
      its normal top-of-flow position and scrolls sideways when the pages overflow;
      an opt-in sticky bar stays pinned to the top via the desktop .pc-sticky rule
      (top:0). A rail drops its fixed side column and flows inline. */
@@ -1019,7 +1063,8 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
   .pc-modal-actions { flex-direction:column; }
   .pc-modal-actions .pc-btn { width:100%; }
 }
-`;
+/* App-wide card layout (nano-ide#572): the same card rules, at every width. */
+${gridCardRules('[data-grid-layout="cards"]')}`;
 
 // The schema-driven browser renderer (ADR 0042 §3). Plain ES module string served at
 // /app/runtime.js — it does NOT ship Craft.js (authoring is console-side only). It

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

@@ -721,3 +721,39 @@ test("threads an injected scheduler into the instance-tracking reconciler loop",
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+// nano-ide#572 — the app-wide dataGrid card layout is opt-in via `surfaces.pages.gridLayout` in the
+// MANIFEST. These drive the full manifest→shell wiring (createUrbanApp → mountSurfaces → mountPages)
+// end-to-end, so a regression in that bridge — e.g. the reflective `"gridLayout" in decl` read or the
+// `parseGridLayout` fallback — is caught here even though the focused pages.test.ts tests inject the
+// option directly into createPagesRoutes (which bypasses the manifest read).
+async function shellGridLayout(pages: Record<string, unknown>): Promise<string> {
+  const dir = await makeFixture({ surfaces: { pages: { enabled: true, ...pages } } });
+  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();
+    const m = body.match(/<body data-grid-layout="([^"]*)">/);
+    assert.ok(m, `shell body carries a data-grid-layout attribute: ${body.slice(0, 200)}`);
+    return m[1];
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+test('#572: surfaces.pages.gridLayout "cards" reaches the shell body attribute through the manifest', async () => {
+  assert.equal(await shellGridLayout({ gridLayout: "cards" }), "cards");
+});
+
+test('#572: an omitted surfaces.pages.gridLayout falls back to the "auto" layout', async () => {
+  assert.equal(await shellGridLayout({}), "auto");
+});
+
+test('#572: an invalid surfaces.pages.gridLayout falls back to the "auto" layout', async () => {
+  assert.equal(await shellGridLayout({ gridLayout: "grid" }), "auto");
+});