From 641f6d13d16d341f6476fab8ab0c2cafa00f3ca3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 16 Oct 2026 14:50:49 +0000
Subject: [PATCH 1/3] feat(components): page regions lay blocks on a 12-column
 grid with kind-derived spans; the page description sits under its title

A region's blocks take a span derived from their kind (metric tiles 3,
charts 6, everything else 12), folded by breakpoint. When a titled
page:header owns the page title, it draws the page description under the
title instead of the page drawing it above. The Studio page designer's
block card shows the derived span, read from the same table.

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvsorV5JuG3fpRuUjWRHir
---
 .../src/views/metadata-admin/i18n.ts          |  2 +
 .../previews/PageBlockCanvas.tsx              | 36 +++++++-
 packages/components/src/index.ts              |  6 ++
 .../src/renderers/layout/containers.tsx       | 11 +++
 .../src/renderers/layout/page-block-span.ts   | 88 +++++++++++++++++++
 .../layout/page-description-context.ts        | 23 +++++
 .../components/src/renderers/layout/page.tsx  | 56 +++++++++---
 7 files changed, 206 insertions(+), 16 deletions(-)
 create mode 100644 packages/components/src/renderers/layout/page-block-span.ts
 create mode 100644 packages/components/src/renderers/layout/page-description-context.ts

diff --git a/packages/app-shell/src/views/metadata-admin/i18n.ts b/packages/app-shell/src/views/metadata-admin/i18n.ts
index fa6889ace7..d5590dfe33 100644
--- a/packages/app-shell/src/views/metadata-admin/i18n.ts
+++ b/packages/app-shell/src/views/metadata-admin/i18n.ts
@@ -1789,6 +1789,7 @@ const ENGINE_STRINGS_EN: Record<string, string> = {
     'Inherited from the default page — add a block to override this slot.',
   'engine.pageBlockCanvas.regionEmpty': 'Empty region — drop a block here or use the add button below.',
   'engine.pageBlockCanvas.select': 'Select {label}',
+  'engine.pageBlockCanvas.span': 'Spans {span} of 12 columns on a wide screen',
   'engine.pageBlockCanvas.groupEmpty': 'Empty — add a block.',
   'engine.pageBlockCanvas.searchTypes': 'Search block type…',
   'engine.pageBlockCanvas.noMatch': 'No matching types.',
@@ -5220,6 +5221,7 @@ const ENGINE_STRINGS_ZH: Record<string, string> = {
   'engine.pageBlockCanvas.slotInherited': '继承自默认页面 —— 添加一个区块即可覆盖此插槽。',
   'engine.pageBlockCanvas.regionEmpty': '空区域 —— 将区块拖放到这里，或使用下方的添加按钮。',
   'engine.pageBlockCanvas.select': '选择 {label}',
+  'engine.pageBlockCanvas.span': '宽屏下占 12 列中的 {span} 列',
   'engine.pageBlockCanvas.groupEmpty': '空 —— 添加一个区块。',
   'engine.pageBlockCanvas.searchTypes': '搜索区块类型…',
   'engine.pageBlockCanvas.noMatch': '没有匹配的类型。',
diff --git a/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.tsx b/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.tsx
index b4c81421ca..e436a841ca 100644
--- a/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.tsx
+++ b/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.tsx
@@ -20,6 +20,9 @@ import {
   Badge,
   Button,
   cn,
+  isPageRailRegion,
+  pageBlockSpan,
+  type PageBlockSpan,
   Popover,
   PopoverContent,
   PopoverTrigger,
@@ -491,6 +494,7 @@ export function PageBlockCanvas({
             baseIdOf={(compIdx) => selectionId(shape, regionIdx, compIdx, region.name)}
             onSelectId={(sid, lbl) => onSelectionChange?.({ kind: 'block', id: sid, label: lbl })}
             onAddNested={addNestedBlock}
+            template={(draft as { template?: unknown }).template}
             locale={locale}
           />
         ))}
@@ -521,6 +525,7 @@ function RegionSection({
   onRenameLabel,
   onSelectId,
   onAddNested,
+  template,
   locale,
 }: {
   region: Region;
@@ -540,9 +545,16 @@ function RegionSection({
   baseIdOf: (compIdx: number) => string;
   onSelectId: (id: string, label: string) => void;
   onAddNested: (baseId: string, pathSuffix: string, type: BlockTypeId) => void;
+  /** The page's `template`, which decides whether this region is a rail. */
+  template?: unknown;
   locale?: string;
 }) {
   const comps = Array.isArray(region.components) ? region.components : [];
+  // The span each block takes in the page's region grid (objectui#12624), read
+  // from the page renderer's own table so the card cannot disagree with the
+  // page. Only a `regions` page lays its blocks on that grid: a `children` page
+  // stacks them, so its cards show no span.
+  const rail = isPageRailRegion(region.name, template);
   const [active, setActive] = React.useState(false);
 
   const handleDragOver = (e: React.DragEvent) => {
@@ -606,6 +618,7 @@ function RegionSection({
                   onClick={() => onSelectBlock(compIdx, blk)}
                   onMoveBlock={onMoveBlock}
                   onRenameLabel={(v) => onRenameLabel(regionIdx, compIdx, v)}
+                  span={shape === 'regions' ? pageBlockSpan(blk.type, rail) : undefined}
                   locale={locale}
                 />
                 <NestedChildren
@@ -642,6 +655,7 @@ function BlockRow({
   onClick,
   onMoveBlock,
   onRenameLabel,
+  span,
   locale,
 }: {
   block: Block;
@@ -657,9 +671,21 @@ function BlockRow({
       | { region: number; appendEnd: true },
   ) => void;
   onRenameLabel: (nextLabel: string) => void;
+  /** The block's derived span in the region grid; read-only, nothing edits it. */
+  span?: PageBlockSpan;
   locale?: string;
 }) {
   const typeStr = String(block.type ?? '');
+  const spanBadge = span !== undefined && (
+    <Badge
+      variant="outline"
+      className="text-[10px] shrink-0 font-mono"
+      data-block-span={span}
+      title={tFormat('engine.pageBlockCanvas.span', locale, { span })}
+    >
+      {span}/12
+    </Badge>
+  );
   // DISPLAY meta, not the palette catalogue. `BLOCK_TYPE_META` answers "what may
   // an author drag in"; a node already in the page may be a spelling the palette
   // does not offer yet the app renders fine — the `record:discussion` /
@@ -792,9 +818,12 @@ function BlockRow({
                 <code className="text-[10px] text-muted-foreground/70 font-mono truncate">#{block.id}</code>
               )}
             </div>
-            <Badge variant="outline" className={cn('text-[10px] shrink-0 font-mono', tone.badge)}>
-              {typeStr}
-            </Badge>
+            <div className="flex items-center gap-1 shrink-0">
+              {spanBadge}
+              <Badge variant="outline" className={cn('text-[10px] shrink-0 font-mono', tone.badge)}>
+                {typeStr}
+              </Badge>
+            </div>
           </button>
         ) : (
           <>
@@ -819,6 +848,7 @@ function BlockRow({
               )}
             >
               {draggable && <GripVertical className="h-3.5 w-3.5 text-muted-foreground/60" aria-hidden="true" />}
+              {spanBadge}
               <Badge variant="outline" className={cn('text-[10px] font-mono shadow-sm bg-background/90 backdrop-blur', tone.badge)}>
                 {typeStr}
               </Badge>
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
index 7d28d07b65..6a79610dad 100644
--- a/packages/components/src/index.ts
+++ b/packages/components/src/index.ts
@@ -69,6 +69,12 @@ export { hasDeclaredVisibilityGate } from './renderers/action/visibility-gate';
 // package, so the direction costs nothing new.
 export { isCustomRowActionVisible } from './renderers/complex/data-table';
 
+// The span a page block takes in its region's 12-column grid, derived from the
+// block's kind (objectui#12624). Exported so the Studio page designer's block
+// card shows the span the page renderer draws, from this one table, not a copy.
+export { pageBlockSpan, isPageRailRegion, PAGE_BLOCK_SPANS } from './renderers/layout/page-block-span';
+export type { PageBlockSpan } from './renderers/layout/page-block-span';
+
 // THE icon-name seam (objectui#5935) — `name -> LucideIcon | null`, one
 // tokeniser and one rename map for the whole repo.
 //
diff --git a/packages/components/src/renderers/layout/containers.tsx b/packages/components/src/renderers/layout/containers.tsx
index aa445f5794..a66c18352a 100644
--- a/packages/components/src/renderers/layout/containers.tsx
+++ b/packages/components/src/renderers/layout/containers.tsx
@@ -57,6 +57,7 @@ import {
   AvatarImage,
 } from '../../ui';
 import { RecordTitleChip } from '../../custom/RecordTitleChip';
+import { PageDescriptionContext } from './page-description-context';
 import { isFileIdToken } from '@objectstack/spec/data';
 import { readActionEntryParamValues } from '../action/static-params';
 import { useObjectLabel, useSafeFieldLabel, useObjectTranslation, useSafeTranslate, createSafeTranslation, pickLocalized, useDisplayLocale } from '@object-ui/i18n';
@@ -1545,6 +1546,10 @@ const PageHeaderRenderer: React.FC<any> = ({ schema, className, ...props }) => {
   // both so a `{ properties: { title } }` schema is rendered correctly.
   const titleSrc = schema?.title ?? schema?.properties?.title;
   const subtitleSrc = schema?.subtitle ?? schema?.properties?.subtitle;
+  // The page's `description`, handed down when this header owns the page's
+  // title (objectui#12624): drawn under the title and subtitle, the order the
+  // console page header uses, instead of above the title by the page.
+  const pageDescription = React.useContext(PageDescriptionContext);
   const headerObjectSchema: any = (ctx as any)?.objectSchema;
   const headerObjectName: string | undefined = ctx?.objectName || headerObjectSchema?.name;
   const explicitTitle = interpolate(
@@ -2607,6 +2612,9 @@ const PageHeaderRenderer: React.FC<any> = ({ schema, className, ...props }) => {
           {subtitle && (
             <p className="text-sm text-muted-foreground mt-1">{subtitle}</p>
           )}
+          {explicitTitle && pageDescription && (
+            <p className="text-sm text-muted-foreground mt-1" data-page-description="">{pageDescription}</p>
+          )}
         </div>
         {renderHeaderTail(<div data-page-actions-slot className="shrink-0" />)}
       </header>
@@ -2627,6 +2635,9 @@ const PageHeaderRenderer: React.FC<any> = ({ schema, className, ...props }) => {
             <h1 className="text-2xl font-semibold tracking-tight">{explicitTitle}</h1>
           )}
           {subtitle && <p className="text-sm text-muted-foreground">{subtitle}</p>}
+          {explicitTitle && pageDescription && (
+            <p className="text-sm text-muted-foreground" data-page-description="">{pageDescription}</p>
+          )}
         </div>
         {renderHeaderTail(<div data-page-actions-slot />)}
       </div>
diff --git a/packages/components/src/renderers/layout/page-block-span.ts b/packages/components/src/renderers/layout/page-block-span.ts
new file mode 100644
index 0000000000..5baddd435a
--- /dev/null
+++ b/packages/components/src/renderers/layout/page-block-span.ts
@@ -0,0 +1,88 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * How wide a page block sits in its region's 12-column block grid
+ * (objectui#12624).
+ *
+ * The width is DERIVED from the block's kind, never authored:
+ * `@objectstack/spec`'s `PageComponentSchema` declares no `span`, and on
+ * `PageRegionSchema` `span` is only a refused alias of `width`. So this file
+ * adds no key an author can write; it names, once, which registered block
+ * types are metric tiles (3 of 12) and which are charts (6 of 12). Every other
+ * type, a type this table does not name included, spans the full 12.
+ *
+ * The keys are the registry keys the blocks are registered under (the bare
+ * key where the registration keeps one, and the namespaced key). The page
+ * renderer (`RegionContent` in `./page.tsx`) and the Studio page designer's
+ * block card (app-shell `PageBlockCanvas`) both read this table, so the span
+ * the designer shows is the span the page draws.
+ */
+export type PageBlockSpan = 3 | 6 | 12;
+
+const TILE = 3;
+const CHART = 6;
+
+/** Registered block type → its span, for the types narrower than 12. */
+export const PAGE_BLOCK_SPANS: ReadonlyMap<string, 3 | 6> = new Map<string, 3 | 6>([
+  // Metric / stat tiles — one number each.
+  ['element:number', TILE],
+  ['statistic', TILE],
+  ['ui:statistic', TILE],
+  ['object-metric', TILE],
+  ['plugin-dashboard:object-metric', TILE],
+  ['plugin-dashboard:metric', TILE],
+  ['plugin-dashboard:metric-card', TILE],
+  // Charts.
+  ['chart', CHART],
+  ['view:chart', CHART],
+  ['plugin-charts:chart', CHART],
+  ['object-chart', CHART],
+  ['plugin-charts:object-chart', CHART],
+  ['bar-chart', CHART],
+  ['plugin-charts:bar-chart', CHART],
+  ['chart:bar', CHART],
+  ['plugin-charts:chart:bar', CHART],
+]);
+
+/**
+ * The span a block of this type takes; a type the table does not name takes
+ * 12. A block in a `rail` region (below) takes 12 whatever its kind: a rail is
+ * a narrow column, where a fold by viewport width would squeeze a tile to a
+ * sliver.
+ */
+export function pageBlockSpan(type: unknown, rail = false): PageBlockSpan {
+  if (rail) return 12;
+  return (typeof type === 'string' && PAGE_BLOCK_SPANS.get(type)) || 12;
+}
+
+/**
+ * Is this region a rail — the narrow `sidebar` / `aside` column beside `main`?
+ * Both are on every layout that places those slots beside `main` (no
+ * template, `default`, `full-width`, `three-column`); `header-sidebar-main`
+ * places only `sidebar` there (an `aside` joins `main`'s column); the
+ * `dashboard` template makes every region but `header` / `footer` a grid cell,
+ * so it has none. The page renderer passes the same answer structurally, by
+ * the slot it places a region in.
+ */
+export function isPageRailRegion(regionName: unknown, template?: unknown): boolean {
+  if (template === 'dashboard') return false;
+  const name = typeof regionName === 'string' ? regionName.toLowerCase() : '';
+  return name === 'sidebar' || (name === 'aside' && template !== 'header-sidebar-main');
+}
+
+/**
+ * The span folded by breakpoint: as declared from `xl` (1280px) up; between
+ * `md` (768px) and `xl` tiles take 6 and charts 12; under `md` every block
+ * takes 12. LITERAL class strings so Tailwind's scanner emits them.
+ */
+export const PAGE_BLOCK_SPAN_CLASS: Readonly<Record<PageBlockSpan, string>> = {
+  3: 'col-span-12 md:col-span-6 xl:col-span-3',
+  6: 'col-span-12 xl:col-span-6',
+  12: 'col-span-12',
+};
diff --git a/packages/components/src/renderers/layout/page-description-context.ts b/packages/components/src/renderers/layout/page-description-context.ts
new file mode 100644
index 0000000000..281051f0e4
--- /dev/null
+++ b/packages/components/src/renderers/layout/page-description-context.ts
@@ -0,0 +1,23 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+
+/**
+ * The page `description` a titled `page:header` draws under its title
+ * (objectui#12624).
+ *
+ * When an authored `page:header` owns the page's `h1`, the page renderer no
+ * longer draws the description in its own heading block, which sat ABOVE the
+ * regions and so above the title. It hands the description down here instead,
+ * and the header draws it after the title, the order the console page header
+ * uses. Every page renderer provides a value (null when it draws the
+ * description itself), so a page nested in another never reads the outer
+ * page's description.
+ */
+export const PageDescriptionContext = React.createContext<React.ReactNode>(null);
diff --git a/packages/components/src/renderers/layout/page.tsx b/packages/components/src/renderers/layout/page.tsx
index b2b9417532..7af5235428 100644
--- a/packages/components/src/renderers/layout/page.tsx
+++ b/packages/components/src/renderers/layout/page.tsx
@@ -30,6 +30,8 @@ import { compile, manifestFromConfigs, type Diagnostic } from '@object-ui/sdui-p
 import { ReactKindPage } from './react-page';
 import { PRINT_PAGE_ATTRIBUTE, PRINT_RUNNING_ATTRIBUTE, buildPagePrintStylesheet, isPagePrintDeclaration } from './page-print';
 import { cn } from '../../lib/utils';
+import { pageBlockSpan, PAGE_BLOCK_SPAN_CLASS } from './page-block-span';
+import { PageDescriptionContext } from './page-description-context';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -194,21 +196,42 @@ function pageHeaderOwnsTitle(schema: PageNodeSchema): boolean {
 // RegionContent — renders all components inside a single region
 // ---------------------------------------------------------------------------
 
+/**
+ * A region lays its blocks out on a 12-column grid (objectui#12624). Each
+ * block's span comes from its kind (`./page-block-span`): metric tiles 3,
+ * charts 6, everything else 12, folded by breakpoint, so four tiles share a
+ * row on a wide screen instead of stacking as four full-width stripes. Every
+ * template places its regions through this one component, so each gets the
+ * grid. A `rail` region (sidebar / aside) is a narrow column, where a fold by
+ * viewport width would squeeze a tile to a sliver, so its blocks stay full
+ * width. The cell is `empty:hidden`, so a block that renders nothing (hidden)
+ * leaves no gap.
+ */
 const RegionContent: React.FC<{
   region: PageNodeRegion;
   className?: string;
-}> = ({ region, className }) => {
+  rail?: boolean;
+}> = ({ region, className, rail }) => {
   const components = region.components || [];
   if (components.length === 0) return null;
 
   return (
     <div
-      className={cn('space-y-4', region.className, className)}
+      className={cn('grid grid-cols-12 gap-4', region.className, className)}
       data-region={region.name}
     >
-      {components.map((node: SchemaNode, idx: number) => (
-        <SchemaRenderer key={(node as any)?.id || `${region.name}-${idx}`} schema={toRenderableSchema(node)} />
-      ))}
+      {components.map((node: SchemaNode, idx: number) => {
+        const span = pageBlockSpan((node as { type?: unknown })?.type, rail);
+        return (
+          <div
+            key={(node as any)?.id || `${region.name}-${idx}`}
+            className={cn('min-w-0 empty:hidden', PAGE_BLOCK_SPAN_CLASS[span])}
+            data-block-span={span}
+          >
+            <SchemaRenderer schema={toRenderableSchema(node)} />
+          </div>
+        );
+      })}
     </div>
   );
 };
@@ -316,7 +339,7 @@ const RegionLayout: React.FC<{
         <div className="flex flex-col md:flex-row flex-1 gap-6">
           {sidebar && (
             <aside className={cn('md:shrink-0', getSidebarWidthClass(sidebar.width as string || 'small'))}>
-              <RegionContent region={sidebar} />
+              <RegionContent region={sidebar} rail />
             </aside>
           )}
 
@@ -329,7 +352,7 @@ const RegionLayout: React.FC<{
 
           {aside && (
             <aside className={cn('md:shrink-0', getSidebarWidthClass(aside.width as string || 'small'), aside.className)}>
-              <RegionContent region={aside} />
+              <RegionContent region={aside} rail />
             </aside>
           )}
         </div>
@@ -389,7 +412,7 @@ const HeaderSidebarMainTemplate: React.FC<{ schema: PageNodeSchema }> = ({ schem
         <div className="flex flex-col md:flex-row flex-1 gap-6">
           {sidebar && (
             <aside className={cn('md:shrink-0', getSidebarWidthClass(sidebar.width as string || 'medium'))}>
-              <RegionContent region={sidebar} />
+              <RegionContent region={sidebar} rail />
             </aside>
           )}
           <div className="flex-1 min-w-0 space-y-6">
@@ -425,7 +448,7 @@ const ThreeColumnTemplate: React.FC<{ schema: PageNodeSchema }> = ({ schema }) =
         <div className="flex flex-col md:flex-row flex-1 gap-6">
           {sidebar && (
             <aside className={cn('md:shrink-0', getSidebarWidthClass(sidebar.width as string || 'small'))}>
-              <RegionContent region={sidebar} />
+              <RegionContent region={sidebar} rail />
             </aside>
           )}
           <div className="flex-1 min-w-0 space-y-6">
@@ -436,7 +459,7 @@ const ThreeColumnTemplate: React.FC<{ schema: PageNodeSchema }> = ({ schema }) =
           </div>
           {aside && (
             <aside className={cn('md:shrink-0', getSidebarWidthClass(aside.width as string || 'small'), aside.className)}>
-              <RegionContent region={aside} />
+              <RegionContent region={aside} rail />
             </aside>
           )}
         </div>
@@ -762,6 +785,11 @@ export const PageRenderer: React.FC<{
   // The description is the page's own prose, not a duplicate of the header's
   // `subtitle`, so delegating the heading does not delete it.
   const showPageDescription = !!schema.description && pageType !== 'record';
+  // When the header owns the title, it draws the description too, under the
+  // title (objectui#12624). Drawn here it sat above the regions, so above the
+  // title the header draws inside them.
+  const headerDrawsDescription = showPageDescription && headerOwnsTitle;
+  const drawDescriptionHere = showPageDescription && !headerDrawsDescription;
 
   const pageContent = (
     <div
@@ -788,21 +816,23 @@ export const PageRenderer: React.FC<{
             `title` is the objectui spelling; the spec's PageNodeSchema declares
             `label` (required), so dual-read it — mirrors the fallback
             DashboardRenderer already uses (framework#1878 §3 recheck). */}
-        {(showPageTitle || showPageDescription) && (
+        {(showPageTitle || drawDescriptionHere) && (
           <div className="space-y-2">
             {showPageTitle && (
               <h1 className="text-3xl font-bold tracking-tight text-foreground">
                 {pageTitle}
               </h1>
             )}
-            {showPageDescription && (
+            {drawDescriptionHere && (
               <p className="text-muted-foreground">{schema.description}</p>
             )}
           </div>
         )}
 
         {/* Page body — type-specific layout */}
-        {layoutElement}
+        <PageDescriptionContext.Provider value={headerDrawsDescription ? schema.description : null}>
+          {layoutElement}
+        </PageDescriptionContext.Provider>
       </div>
     </div>
   );

From f36cb9b40bfc1765ea40e0f5819cf70fabd27fe0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 16 Oct 2026 14:59:30 +0000
Subject: [PATCH 2/3] test(components): pin the region block grid, the
 description order and the designer span; docs and changeset

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvsorV5JuG3fpRuUjWRHir
---
 .changeset/12624-page-block-grid.md           |  12 +
 content/docs/components/layout/page.mdx       |  22 ++
 content/docs/layout/page-header.mdx           |   3 +
 .../PageBlockCanvas.blockSpan-12624.test.tsx  |  85 ++++++
 .../__tests__/page-block-grid-12624.test.tsx  | 243 ++++++++++++++++++
 5 files changed, 365 insertions(+)
 create mode 100644 .changeset/12624-page-block-grid.md
 create mode 100644 packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.blockSpan-12624.test.tsx
 create mode 100644 packages/components/src/__tests__/page-block-grid-12624.test.tsx

diff --git a/.changeset/12624-page-block-grid.md b/.changeset/12624-page-block-grid.md
new file mode 100644
index 0000000000..0983729b80
--- /dev/null
+++ b/.changeset/12624-page-block-grid.md
@@ -0,0 +1,12 @@
+---
+'@object-ui/components': minor
+'@object-ui/app-shell': minor
+---
+
+App pages lay a region's blocks out on a 12-column grid, and the page description sits under its title (objectui#12624).
+
+- **Block grid.** A page region's blocks used to stack one per row, so four metric tiles drew four full-width stripes. They now sit on a 12-column grid. A block's span comes from its kind, not from a key on the block: metric tiles (`element:number`, `statistic`, `object-metric` and the dashboard metric widgets) span 3, charts (`chart`, `object-chart`, `bar-chart`) span 6, and every other block spans 12. From 1280px up the spans apply as named; from 768px to 1279px tiles span 6 and charts 12; under 768px every block spans 12. So four tiles share one row at 1280px and take two rows at 1024px. A `sidebar` or `aside` region beside `main` keeps its blocks full width. On the `dashboard` template each region is still a cell of the region grid and lays its own blocks out the same way.
+- **Description under the title.** When a titled `page:header` owns the page's heading, the page drew its `description` above the regions, so above the title. The header now draws it under the title and subtitle. The page still has one `h1`.
+- **Studio page designer.** Each block card in a region shows the span the page gives it, read-only (`3/12`, `6/12`, `12/12`).
+
+Nothing an author writes is added: there is no `span` key, and `@objectstack/spec` declares none. `@object-ui/components` adds `pageBlockSpan`, `isPageRailRegion`, `PAGE_BLOCK_SPANS` and the `PageBlockSpan` type to its entry, so the designer reads the renderer's table instead of a copy. The designer's new string lives in its own string tables (en and zh).
diff --git a/content/docs/components/layout/page.mdx b/content/docs/components/layout/page.mdx
index 077dfcdfb6..0407acceea 100644
--- a/content/docs/components/layout/page.mdx
+++ b/content/docs/components/layout/page.mdx
@@ -20,6 +20,28 @@ heading. A page with no `pageType` is a `record` page, which draws neither: its
 The [layout guide's Content Width](/docs/guide/layout#content-width) section covers the width
 each type sets.
 
+When a titled `page:header` takes over the heading, it also draws the page's `description`,
+under its title and subtitle, so the description never sits above the title.
+
+## Region Block Grid
+
+A page's `regions` lay their blocks out on a 12-column grid. A block's width comes from its
+kind, not from a key on the block: a metric tile (`element:number`, `object-metric`,
+`statistic`) spans 3 columns, a chart (`chart`, `object-chart`) spans 6, and every other block
+spans all 12. The spans fold by screen width:
+
+| Screen width | Metric tile | Chart | Other blocks |
+|---|---|---|---|
+| 1280px and wider | 3 | 6 | 12 |
+| 768px to 1279px | 6 | 12 | 12 |
+| under 768px | 12 | 12 | 12 |
+
+So four metric tiles share one row on a wide screen and take two rows on a 1024px one. A
+`sidebar` or `aside` region beside `main` is a narrow column, so its blocks always span 12.
+On the `dashboard` template each region is a cell of the page's region grid and lays its
+own blocks out the same way. A page's `children` (no `regions`) stack one block per row.
+Studio's page designer shows each block's span on its card.
+
 ## Schema
 
 ```ts
diff --git a/content/docs/layout/page-header.mdx b/content/docs/layout/page-header.mdx
index 76101d4ed1..095f39dfcf 100644
--- a/content/docs/layout/page-header.mdx
+++ b/content/docs/layout/page-header.mdx
@@ -191,6 +191,9 @@ The renderer picks one of two layouts when it renders:
 
 - **Bare heading** — no record in scope, or `recordChrome: false`. The title and subtitle
   stack on the left, the action row sits on the right.
+
+When the header's title is the page's heading, the page's own `description` is drawn as a
+third line, under the title and subtitle.
 - **Record chip** — a record page (a record context with its object schema) with the record
   chrome on. The title renders as the record chip: the heading, the object's label, the
   copy-id button and the follow star, with the record's picture beside the heading when the
diff --git a/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.blockSpan-12624.test.tsx b/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.blockSpan-12624.test.tsx
new file mode 100644
index 0000000000..93505752e7
--- /dev/null
+++ b/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.blockSpan-12624.test.tsx
@@ -0,0 +1,85 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The page designer's block card shows the span the block takes in its
+ * region's 12-column grid (objectui#12624), read-only, from the page
+ * renderer's own table in `@object-ui/components` — so the card and the page
+ * cannot disagree.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import { ComponentRegistry } from '@object-ui/core';
+import { PAGE_BLOCK_SPANS } from '@object-ui/components';
+// Module scope, not a hook: the registrations the span table names
+// (AGENTS.md §测试纪律).
+import '@object-ui/plugin-dashboard';
+import '@object-ui/plugin-charts';
+import { PageBlockCanvas } from './PageBlockCanvas';
+
+afterEach(cleanup);
+
+function spanBadges(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll('[data-block-span]')).map(
+    (el) => el.getAttribute('data-block-span') ?? '',
+  );
+}
+
+describe('PageBlockCanvas — the block card shows its derived span (objectui#12624)', () => {
+  it('a metric tile reads 3/12, a chart 6/12 and a block the table does not name 12/12', () => {
+    const { container } = render(
+      <PageBlockCanvas
+        draft={{
+          name: 'home',
+          type: 'home',
+          regions: [
+            {
+              name: 'main',
+              components: [
+                { type: 'object-metric', id: 'revenue' },
+                { type: 'object-chart', id: 'trend' },
+                { type: 'element:text', id: 'note' },
+              ],
+            },
+          ],
+        }}
+      />,
+    );
+    expect(spanBadges(container)).toEqual(['3', '6', '12']);
+    const badge = container.querySelector('[data-block-span="3"]')!;
+    expect(badge.textContent).toBe('3/12');
+    // Read-only: the badge is not a control.
+    expect(badge.closest('input, select, [role="spinbutton"]')).toBeNull();
+  });
+
+  it('a block in a rail region reads 12/12, as the page draws it', () => {
+    const { container } = render(
+      <PageBlockCanvas
+        draft={{
+          name: 'home',
+          type: 'home',
+          template: 'three-column',
+          regions: [
+            { name: 'sidebar', components: [{ type: 'object-metric', id: 'a' }] },
+            { name: 'main', components: [{ type: 'object-metric', id: 'b' }] },
+          ],
+        }}
+      />,
+    );
+    expect(spanBadges(container)).toEqual(['12', '3']);
+  });
+
+  it('a `children` page stacks its blocks, so its cards show no span', () => {
+    const { container } = render(
+      <PageBlockCanvas draft={{ name: 'home', type: 'home', children: [{ type: 'object-metric', id: 'a' }] }} />,
+    );
+    expect(container.querySelector('[data-block-span]')).toBeNull();
+  });
+
+  it('every type the span table names is a registered block type', () => {
+    const unregistered = [...PAGE_BLOCK_SPANS.keys()].filter(
+      (type) => !ComponentRegistry.has(type) && !ComponentRegistry.hasLazy(type),
+    );
+    expect(unregistered).toEqual([]);
+  });
+});
diff --git a/packages/components/src/__tests__/page-block-grid-12624.test.tsx b/packages/components/src/__tests__/page-block-grid-12624.test.tsx
new file mode 100644
index 0000000000..6871ef3f96
--- /dev/null
+++ b/packages/components/src/__tests__/page-block-grid-12624.test.tsx
@@ -0,0 +1,243 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * App pages lay a region's blocks on a 12-column grid, and the page
+ * description sits under its title (objectui#12624).
+ *
+ * The span is derived from the block's kind (`page-block-span.ts`) and folded
+ * by breakpoint with Tailwind's `md` (768px) and `xl` (1280px) variants. A
+ * DOM test has no stylesheet, so the row arithmetic below reads the span the
+ * cell's REAL classes give at a viewport width, by the breakpoint rule those
+ * variants compile to (`min-width`); the browser screenshots on the pull
+ * request show the same classes laid out.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { ActionProvider, SchemaRenderer } from '@object-ui/react';
+// Module scope, not a hook: registers PageRenderer, `page:header` and
+// `statistic` (AGENTS.md §测试纪律).
+import '../renderers';
+import { pageBlockSpan, isPageRailRegion, PAGE_BLOCK_SPANS } from '../renderers/layout/page-block-span';
+
+/** Tailwind's default breakpoints the span classes use. */
+const BREAKPOINTS: Array<[prefix: string, minWidth: number]> = [
+  ['xl:', 1280],
+  ['lg:', 1024],
+  ['md:', 768],
+  ['sm:', 640],
+  ['', 0],
+];
+
+/** The `col-span-N` a cell's classes resolve to at a viewport width. */
+function activeSpan(cell: Element, width: number): number {
+  const classes = Array.from(cell.classList);
+  for (const [prefix, min] of BREAKPOINTS) {
+    if (width < min) continue;
+    const hit = classes.find((c) => c.startsWith(`${prefix}col-span-`) && !c.slice(prefix.length).includes(':'));
+    if (hit) return Number(hit.slice(`${prefix}col-span-`.length));
+  }
+  throw new Error(`no col-span class on ${cell.outerHTML}`);
+}
+
+/** How many grid rows the cells fill at a width, packing spans into 12. */
+function rowsAt(cells: Element[], width: number): number {
+  let rows = 0;
+  let used = 12;
+  for (const cell of cells) {
+    const span = activeSpan(cell, width);
+    if (used + span > 12) {
+      rows += 1;
+      used = 0;
+    }
+    used += span;
+  }
+  return rows;
+}
+
+function tile(id: string) {
+  return { type: 'statistic', id, label: id, value: 1 } as any;
+}
+
+function renderPage(schema: any) {
+  return render(
+    <ActionProvider>
+      <SchemaRenderer schema={schema} />
+    </ActionProvider>,
+  );
+}
+
+function regionCells(container: HTMLElement, name: string): Element[] {
+  const region = container.querySelector(`[data-region="${name}"]`);
+  expect(region).not.toBeNull();
+  return Array.from(region!.children);
+}
+
+describe('a region lays its blocks on a 12-column grid (objectui#12624)', () => {
+  const kpiPage = {
+    type: 'app',
+    pageType: 'app',
+    name: 'kpi_page',
+    label: 'Sales Dashboard',
+    regions: [{ name: 'main', components: [tile('revenue'), tile('won'), tile('pipeline'), tile('leads')] }],
+  } as any;
+
+  it('four metric tiles fill one row at 1280px and two rows at 1024px', () => {
+    const { container } = renderPage(kpiPage);
+    const region = container.querySelector('[data-region="main"]')!;
+    expect(region.classList.contains('grid')).toBe(true);
+    expect(region.classList.contains('grid-cols-12')).toBe(true);
+
+    const cells = regionCells(container, 'main');
+    expect(cells).toHaveLength(4);
+    for (const cell of cells) expect(cell.getAttribute('data-block-span')).toBe('3');
+
+    expect(rowsAt(cells, 1280)).toBe(1);
+    expect(rowsAt(cells, 1024)).toBe(2);
+    // Under 768px every block takes the full width.
+    expect(rowsAt(cells, 390)).toBe(4);
+  });
+
+  it('a block whose kind the table does not name takes 12', () => {
+    expect(PAGE_BLOCK_SPANS.has('element:text')).toBe(false);
+    expect(pageBlockSpan('element:text')).toBe(12);
+    expect(pageBlockSpan('no-such-block')).toBe(12);
+    expect(pageBlockSpan(undefined)).toBe(12);
+
+    const { container } = renderPage({
+      ...kpiPage,
+      regions: [{ name: 'main', components: [{ type: 'element:text', properties: { content: 'Hello' } }, tile('won')] }],
+    });
+    const [text, metric] = regionCells(container, 'main');
+    expect(text.getAttribute('data-block-span')).toBe('12');
+    expect(activeSpan(text, 1280)).toBe(12);
+    expect(activeSpan(metric, 1280)).toBe(3);
+  });
+
+  it('a chart takes 6 from 1280px and 12 below', () => {
+    expect(pageBlockSpan('object-chart')).toBe(6);
+    const { container } = renderPage({
+      ...kpiPage,
+      regions: [{ name: 'main', components: [{ type: 'chart', id: 'c1' }, { type: 'chart', id: 'c2' }] }],
+    });
+    const cells = regionCells(container, 'main');
+    expect(cells.map((c) => c.getAttribute('data-block-span'))).toEqual(['6', '6']);
+    expect(rowsAt(cells, 1280)).toBe(1);
+    expect(rowsAt(cells, 1024)).toBe(2);
+  });
+
+  it('a rail region (sidebar / aside) keeps every block full width', () => {
+    const { container } = renderPage({
+      ...kpiPage,
+      template: 'three-column',
+      regions: [
+        { name: 'sidebar', components: [tile('a')] },
+        { name: 'main', components: [tile('b')] },
+        { name: 'aside', components: [tile('c')] },
+      ],
+    });
+    expect(regionCells(container, 'sidebar')[0].getAttribute('data-block-span')).toBe('12');
+    expect(regionCells(container, 'aside')[0].getAttribute('data-block-span')).toBe('12');
+    expect(regionCells(container, 'main')[0].getAttribute('data-block-span')).toBe('3');
+    // The designer's rail answer agrees with the slots the renderer placed.
+    expect(isPageRailRegion('sidebar', 'three-column')).toBe(true);
+    expect(isPageRailRegion('aside', 'three-column')).toBe(true);
+    expect(isPageRailRegion('main', 'three-column')).toBe(false);
+  });
+
+  it('on the dashboard template each region is a grid cell that holds its own block grid', () => {
+    const { container } = renderPage({
+      ...kpiPage,
+      template: 'dashboard',
+      regions: [
+        { name: 'sidebar', components: [tile('a'), tile('b')] },
+        { name: 'main', components: [tile('c')] },
+      ],
+    });
+    const cellsGrid = container.querySelector('[data-template="dashboard"] .md\\:grid-cols-2')!;
+    expect(cellsGrid).not.toBeNull();
+    const regions = Array.from(cellsGrid.children);
+    expect(regions.map((r) => r.getAttribute('data-region'))).toEqual(['sidebar', 'main']);
+    for (const r of regions) expect(r.classList.contains('grid-cols-12')).toBe(true);
+    // No rail on this template: the sidebar's tiles keep their kind's span.
+    expect(regionCells(container, 'sidebar')[0].getAttribute('data-block-span')).toBe('3');
+    expect(isPageRailRegion('sidebar', 'dashboard')).toBe(false);
+  });
+
+  it('a hidden block leaves an empty cell that the grid does not draw', () => {
+    const { container } = renderPage({
+      ...kpiPage,
+      regions: [{ name: 'main', components: [{ ...tile('gone'), hidden: true }, tile('kept')] }],
+    });
+    const [gone] = regionCells(container, 'main');
+    expect(gone.childNodes).toHaveLength(0);
+    expect(gone.classList.contains('empty:hidden')).toBe(true);
+  });
+});
+
+describe('the page description sits under its title (objectui#12624)', () => {
+  const DESCRIPTION = 'Sales team home page with key metrics';
+
+  function headerPage() {
+    return {
+      type: 'app',
+      pageType: 'app',
+      name: 'sales_home_page',
+      label: 'Sales Home',
+      description: DESCRIPTION,
+      regions: [
+        {
+          name: 'header',
+          components: [{ type: 'page:header', properties: { title: 'Sales Dashboard', subtitle: 'Welcome back' } }],
+        },
+        { name: 'main', components: [tile('revenue')] },
+      ],
+    } as any;
+  }
+
+  it('a titled page:header draws the description after the title, with one h1', () => {
+    renderPage(headerPage());
+    const h1s = screen.getAllByRole('heading', { level: 1 });
+    expect(h1s).toHaveLength(1);
+    expect(h1s[0].textContent).toBe('Sales Dashboard');
+
+    const descriptions = screen.getAllByText(DESCRIPTION);
+    expect(descriptions).toHaveLength(1);
+    // After the title in document order, and inside the header.
+    expect(h1s[0].compareDocumentPosition(descriptions[0]) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(descriptions[0].closest('header')).not.toBeNull();
+    // After the header's own subtitle too.
+    const subtitle = screen.getByText('Welcome back');
+    expect(subtitle.compareDocumentPosition(descriptions[0]) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+
+  it('LIVE CONTROL — with no page:header, the page draws its own title, then the description', () => {
+    const schema = headerPage();
+    schema.regions = [{ name: 'main', components: [tile('revenue')] }];
+    renderPage(schema);
+    const h1 = screen.getByRole('heading', { level: 1 });
+    expect(h1.textContent).toBe('Sales Home');
+    const description = screen.getByText(DESCRIPTION);
+    expect(h1.compareDocumentPosition(description) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(description.closest('header')).toBeNull();
+  });
+
+  it('a page nested in a page does not inherit the outer description', () => {
+    const outer = headerPage();
+    outer.regions[1].components = [
+      {
+        type: 'app',
+        pageType: 'app',
+        name: 'inner',
+        label: 'Inner',
+        regions: [{ name: 'header', components: [{ type: 'page:header', properties: { title: 'Inner title' } }] }],
+      },
+    ];
+    renderPage(outer);
+    expect(screen.getAllByText(DESCRIPTION)).toHaveLength(1);
+  });
+});

From 32052540efc43c221ac5bdd6f07c88105dbc67af Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 16 Oct 2026 16:09:38 +0000
Subject: [PATCH 3/3] feat(components): page:card and page:section lay their
 children on the page block grid

The same kind-derived spans and breakpoint fold as region blocks, through
one shared PageBlockGrid; a rail region keeps nested tiles full width. The
designer's nested child cards of a page:card / page:section show their span.

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvsorV5JuG3fpRuUjWRHir
---
 .changeset/12624-page-block-grid.md           |  3 +-
 content/docs/components/layout/page.mdx       |  6 +-
 .../PageBlockCanvas.blockSpan-12624.test.tsx  | 32 ++++++++
 .../previews/PageBlockCanvas.tsx              | 35 ++++++---
 .../__tests__/page-block-grid-12624.test.tsx  | 78 +++++++++++++++++++
 .../src/renderers/layout/containers.tsx       | 10 ++-
 .../src/renderers/layout/page-block-grid.tsx  | 71 +++++++++++++++++
 .../components/src/renderers/layout/page.tsx  | 32 +++-----
 8 files changed, 231 insertions(+), 36 deletions(-)
 create mode 100644 packages/components/src/renderers/layout/page-block-grid.tsx

diff --git a/.changeset/12624-page-block-grid.md b/.changeset/12624-page-block-grid.md
index 0983729b80..7b694fcffe 100644
--- a/.changeset/12624-page-block-grid.md
+++ b/.changeset/12624-page-block-grid.md
@@ -6,7 +6,8 @@
 App pages lay a region's blocks out on a 12-column grid, and the page description sits under its title (objectui#12624).
 
 - **Block grid.** A page region's blocks used to stack one per row, so four metric tiles drew four full-width stripes. They now sit on a 12-column grid. A block's span comes from its kind, not from a key on the block: metric tiles (`element:number`, `statistic`, `object-metric` and the dashboard metric widgets) span 3, charts (`chart`, `object-chart`, `bar-chart`) span 6, and every other block spans 12. From 1280px up the spans apply as named; from 768px to 1279px tiles span 6 and charts 12; under 768px every block spans 12. So four tiles share one row at 1280px and take two rows at 1024px. A `sidebar` or `aside` region beside `main` keeps its blocks full width. On the `dashboard` template each region is still a cell of the region grid and lays its own blocks out the same way.
+- **Container grid.** A `page:card` or `page:section` lays its list of children on the same grid. The container is one block of its region and spans 12. Its children take their kind's span and fold the same way, so a card holding four `object-metric` tiles (a Sales Home KPI card) shows them in one row at 1280px and two rows at 1024px. Children that are not tiles still stack full width. Inside a rail region they stay full width too.
 - **Description under the title.** When a titled `page:header` owns the page's heading, the page drew its `description` above the regions, so above the title. The header now draws it under the title and subtitle. The page still has one `h1`.
-- **Studio page designer.** Each block card in a region shows the span the page gives it, read-only (`3/12`, `6/12`, `12/12`).
+- **Studio page designer.** Each block card in a region, and each child card of a `page:card` or `page:section`, shows the span the page gives it, read-only (`3/12`, `6/12`, `12/12`).
 
 Nothing an author writes is added: there is no `span` key, and `@objectstack/spec` declares none. `@object-ui/components` adds `pageBlockSpan`, `isPageRailRegion`, `PAGE_BLOCK_SPANS` and the `PageBlockSpan` type to its entry, so the designer reads the renderer's table instead of a copy. The designer's new string lives in its own string tables (en and zh).
diff --git a/content/docs/components/layout/page.mdx b/content/docs/components/layout/page.mdx
index 0407acceea..35b94ce246 100644
--- a/content/docs/components/layout/page.mdx
+++ b/content/docs/components/layout/page.mdx
@@ -40,7 +40,11 @@ So four metric tiles share one row on a wide screen and take two rows on a 1024p
 `sidebar` or `aside` region beside `main` is a narrow column, so its blocks always span 12.
 On the `dashboard` template each region is a cell of the page's region grid and lays its
 own blocks out the same way. A page's `children` (no `regions`) stack one block per row.
-Studio's page designer shows each block's span on its card.
+
+A `page:card` or `page:section` lays its children on the same grid. The container spans 12
+in its region, and its children take their own kind's span, so a card holding four metric
+tiles shows them in one row on a wide screen. Studio's page designer shows each block's
+span on its card, and on the child cards of a `page:card` or `page:section`.
 
 ## Schema
 
diff --git a/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.blockSpan-12624.test.tsx b/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.blockSpan-12624.test.tsx
index 93505752e7..49f04ccfed 100644
--- a/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.blockSpan-12624.test.tsx
+++ b/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.blockSpan-12624.test.tsx
@@ -76,6 +76,38 @@ describe('PageBlockCanvas — the block card shows its derived span (objectui#12
     expect(container.querySelector('[data-block-span]')).toBeNull();
   });
 
+  it('the children of a page:card show the span the card lays them out at', () => {
+    const { container } = render(
+      <PageBlockCanvas
+        draft={{
+          name: 'home',
+          type: 'home',
+          regions: [
+            {
+              name: 'main',
+              components: [
+                {
+                  type: 'page:card',
+                  id: 'kpis',
+                  properties: {
+                    title: 'Key Performance Indicators',
+                    children: [
+                      { type: 'object-metric', id: 'a' },
+                      { type: 'object-metric', id: 'b' },
+                      { type: 'element:text', id: 'c' },
+                    ],
+                  },
+                },
+              ],
+            },
+          ],
+        }}
+      />,
+    );
+    // The card itself (12), then its three children.
+    expect(spanBadges(container)).toEqual(['12', '3', '3', '12']);
+  });
+
   it('every type the span table names is a registered block type', () => {
     const unregistered = [...PAGE_BLOCK_SPANS.keys()].filter(
       (type) => !ComponentRegistry.has(type) && !ComponentRegistry.hasLazy(type),
diff --git a/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.tsx b/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.tsx
index e436a841ca..b39f9d41b3 100644
--- a/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.tsx
+++ b/packages/app-shell/src/views/metadata-admin/previews/PageBlockCanvas.tsx
@@ -628,6 +628,7 @@ function RegionSection({
                   readOnly={readOnly}
                   onSelectId={onSelectId}
                   onAddNested={onAddNested}
+                  rail={rail}
                   locale={locale}
                 />
               </React.Fragment>
@@ -646,6 +647,20 @@ function RegionSection({
 
 /* ─────────────── Block row ─────────────── */
 
+/** A block's derived span in the page block grid, read-only (objectui#12624). */
+function SpanBadge({ span, locale }: { span: PageBlockSpan; locale?: string }) {
+  return (
+    <Badge
+      variant="outline"
+      className="text-[10px] shrink-0 font-mono bg-background/90"
+      data-block-span={span}
+      title={tFormat('engine.pageBlockCanvas.span', locale, { span })}
+    >
+      {span}/12
+    </Badge>
+  );
+}
+
 function BlockRow({
   block,
   regionIdx,
@@ -676,16 +691,7 @@ function BlockRow({
   locale?: string;
 }) {
   const typeStr = String(block.type ?? '');
-  const spanBadge = span !== undefined && (
-    <Badge
-      variant="outline"
-      className="text-[10px] shrink-0 font-mono"
-      data-block-span={span}
-      title={tFormat('engine.pageBlockCanvas.span', locale, { span })}
-    >
-      {span}/12
-    </Badge>
-  );
+  const spanBadge = span !== undefined && <SpanBadge span={span} locale={locale} />;
   // DISPLAY meta, not the palette catalogue. `BLOCK_TYPE_META` answers "what may
   // an author drag in"; a node already in the page may be a spelling the palette
   // does not offer yet the app renders fine — the `record:discussion` /
@@ -872,6 +878,7 @@ function NestedChildren({
   readOnly,
   onSelectId,
   onAddNested,
+  rail = false,
   locale,
 }: {
   block: Block;
@@ -880,10 +887,15 @@ function NestedChildren({
   readOnly: boolean;
   onSelectId: (id: string, label: string) => void;
   onAddNested: (baseId: string, pathSuffix: string, type: BlockTypeId) => void;
+  /** The block sits in a rail region, where every block spans 12. */
+  rail?: boolean;
   locale?: string;
 }) {
   const groups = childGroups(block, locale);
   if (groups.length === 0) return null;
+  // `page:card` and `page:section` lay their children on the page block grid
+  // at runtime (objectui#12624), so their child cards show the span too.
+  const showsSpan = block?.type === 'page:card' || block?.type === 'page:section';
   // A grid lays its children in N columns at runtime — mirror that here so the
   // design canvas matches the preview (other containers stack in one column).
   const gridCols =
@@ -924,10 +936,11 @@ function NestedChildren({
                     />
                     <div
                       className={cn(
-                        'pointer-events-none absolute right-1.5 top-1.5 z-20 transition-opacity',
+                        'pointer-events-none absolute right-1.5 top-1.5 z-20 flex items-center gap-1 transition-opacity',
                         childSelected ? 'opacity-100' : 'opacity-0 group-hover:opacity-100',
                       )}
                     >
+                      {showsSpan && <SpanBadge span={pageBlockSpan(child?.type, rail)} locale={locale} />}
                       <Badge variant="outline" className={cn('text-[10px] font-mono shadow-sm bg-background/90 backdrop-blur', resolveBlockTone(typeStr).badge)}>
                         {typeStr}
                       </Badge>
diff --git a/packages/components/src/__tests__/page-block-grid-12624.test.tsx b/packages/components/src/__tests__/page-block-grid-12624.test.tsx
index 6871ef3f96..bb7a486683 100644
--- a/packages/components/src/__tests__/page-block-grid-12624.test.tsx
+++ b/packages/components/src/__tests__/page-block-grid-12624.test.tsx
@@ -179,6 +179,84 @@ describe('a region lays its blocks on a 12-column grid (objectui#12624)', () =>
   });
 });
 
+describe('page:card and page:section lay their children on the same grid (objectui#12624)', () => {
+  const metric = (id: string) => ({ type: 'object-metric', id, properties: { objectName: 'opportunity' } });
+  const four = () => [metric('revenue'), metric('won'), metric('pipeline'), metric('leads')];
+
+  function pageWith(container: Record<string, unknown>, regionName = 'main', template?: string) {
+    return {
+      type: 'app',
+      pageType: 'app',
+      name: 'sales_home_page',
+      label: 'Sales Home',
+      ...(template ? { template } : {}),
+      regions: [{ name: regionName, components: [container] }],
+    } as any;
+  }
+
+  /** The cells of the block grid a container draws its children on. */
+  function containerCells(container: HTMLElement, selector: string): Element[] {
+    const host = container.querySelector(selector);
+    expect(host).not.toBeNull();
+    const grid = host!.querySelector('.grid-cols-12');
+    expect(grid).not.toBeNull();
+    return Array.from(grid!.children);
+  }
+
+  it('a page:card holding four object-metric tiles (the HotCRM Sales Home shape) fills one row at 1280px and two at 1024px', () => {
+    const { container } = renderPage(
+      pageWith({ type: 'page:card', id: 'kpis', properties: { title: 'Key Performance Indicators', children: four() } }),
+    );
+    // The card itself is one region block, spanning 12 by its own kind.
+    const [cardCell] = regionCells(container, 'main');
+    expect(cardCell.getAttribute('data-block-span')).toBe('12');
+
+    const cells = Array.from(cardCell.querySelector('.grid-cols-12')!.children);
+    expect(cells).toHaveLength(4);
+    for (const cell of cells) expect(cell.getAttribute('data-block-span')).toBe('3');
+    expect(rowsAt(cells, 1280)).toBe(1);
+    expect(rowsAt(cells, 1024)).toBe(2);
+    expect(rowsAt(cells, 390)).toBe(4);
+  });
+
+  it('a page:section does the same', () => {
+    const { container } = renderPage(pageWith({ type: 'page:section', id: 'kpis', properties: { children: four() } }));
+    const cells = containerCells(container, 'section');
+    expect(cells.map((c) => c.getAttribute('data-block-span'))).toEqual(['3', '3', '3', '3']);
+    expect(rowsAt(cells, 1280)).toBe(1);
+    expect(rowsAt(cells, 1024)).toBe(2);
+  });
+
+  it('a container whose children are not tiles still stacks them full width', () => {
+    const { container } = renderPage(
+      pageWith({
+        type: 'page:card',
+        id: 'notes',
+        properties: {
+          title: 'Notes',
+          children: [
+            { type: 'element:text', properties: { content: 'one' } },
+            { type: 'element:text', properties: { content: 'two' } },
+          ],
+        },
+      }),
+    );
+    const [cardCell] = regionCells(container, 'main');
+    const cells = Array.from(cardCell.querySelector('.grid-cols-12')!.children);
+    expect(cells.map((c) => c.getAttribute('data-block-span'))).toEqual(['12', '12']);
+    expect(rowsAt(cells, 1280)).toBe(2);
+  });
+
+  it('a container in a rail region keeps its tiles full width', () => {
+    const { container } = renderPage(
+      pageWith({ type: 'page:card', id: 'kpis', properties: { title: 'KPIs', children: four() } }, 'sidebar', 'three-column'),
+    );
+    const [cardCell] = regionCells(container, 'sidebar');
+    const cells = Array.from(cardCell.querySelector('.grid-cols-12')!.children);
+    expect(cells.map((c) => c.getAttribute('data-block-span'))).toEqual(['12', '12', '12', '12']);
+  });
+});
+
 describe('the page description sits under its title (objectui#12624)', () => {
   const DESCRIPTION = 'Sales team home page with key metrics';
 
diff --git a/packages/components/src/renderers/layout/containers.tsx b/packages/components/src/renderers/layout/containers.tsx
index a66c18352a..276d213efe 100644
--- a/packages/components/src/renderers/layout/containers.tsx
+++ b/packages/components/src/renderers/layout/containers.tsx
@@ -58,6 +58,7 @@ import {
 } from '../../ui';
 import { RecordTitleChip } from '../../custom/RecordTitleChip';
 import { PageDescriptionContext } from './page-description-context';
+import { renderBlockChildren } from './page-block-grid';
 import { isFileIdToken } from '@objectstack/spec/data';
 import { readActionEntryParamValues } from '../action/static-params';
 import { useObjectLabel, useSafeFieldLabel, useObjectTranslation, useSafeTranslate, createSafeTranslation, pickLocalized, useDisplayLocale } from '@object-ui/i18n';
@@ -1078,8 +1079,11 @@ const PageCardRenderer: React.FC<any> = ({ schema, className, ...props }) => {
           TypeScript census could not see these two while the runtime probe
           could. `renderNodeSlot` invokes the wrapper only when the slot has
           content, so the chrome disappears with it. */}
+      {/* A list of children lays out on the page block grid, the way a
+          region's blocks do (objectui#12624): four metric tiles in a card
+          share a row on a wide screen. */}
       {renderNodeSlot(body, (node) => (
-        <CardContent>{renderChildren(node)}</CardContent>
+        <CardContent>{renderBlockChildren(node, renderChildren)}</CardContent>
       ))}
       {renderNodeSlot(footer, (node) => (
         <CardFooter className="flex justify-between">{renderChildren(node)}</CardFooter>
@@ -1238,6 +1242,8 @@ const PageSectionRenderer: React.FC<any> = ({ schema, className, ...props }) =>
       className={cn('space-y-4', className)}
       {...designer}
     >
+      {/* A list of children lays out on the page block grid, as in
+          `page:card` above (objectui#12624). */}
       {/*
         ⚠️ `body` KEPT on all three thin containers, and the ground is the
         SPEC'S OWN — ⛔ not the "they never published it" argument an earlier
@@ -1272,7 +1278,7 @@ const PageSectionRenderer: React.FC<any> = ({ schema, className, ...props }) =>
         `toMajor: 17` and `retiredFromLoadPath: true` and this repo installs spec
         17.4.0, so the live ground there is unreplayed stored rows.
       */}
-      {renderChildren(schema?.children || schema?.body)}
+      {renderBlockChildren(schema?.children || schema?.body, renderChildren)}
     </section>
   );
 };
diff --git a/packages/components/src/renderers/layout/page-block-grid.tsx b/packages/components/src/renderers/layout/page-block-grid.tsx
new file mode 100644
index 0000000000..3e04180f56
--- /dev/null
+++ b/packages/components/src/renderers/layout/page-block-grid.tsx
@@ -0,0 +1,71 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+import { SchemaRenderer } from '@object-ui/react';
+import { cn } from '../../lib/utils';
+import { pageBlockSpan, PAGE_BLOCK_SPAN_CLASS } from './page-block-span';
+
+/**
+ * Is this block list inside a rail region (sidebar / aside)? A rail is a
+ * narrow column, so every block in it, at any depth, spans 12. The region
+ * renderer provides it; the container grids below read it.
+ */
+const PageBlockRailContext = React.createContext(false);
+
+/**
+ * Lays a list of page blocks on the 12-column block grid (objectui#12624):
+ * each block takes the span its kind gets from `./page-block-span`, folded by
+ * breakpoint. One component for every block list that folds this way: a
+ * region's blocks (`RegionContent` in `./page.tsx`) and the children of
+ * `page:card` / `page:section` (`./containers.tsx`), so a container in a
+ * region spans 12 by its own kind and its children fold like region blocks.
+ * A cell is `empty:hidden`, so a block that renders nothing leaves no gap.
+ */
+export const PageBlockGrid: React.FC<{
+  nodes: readonly unknown[];
+  className?: string;
+  /** Marks the list as a rail's: every block in it, nested ones too, spans 12. */
+  rail?: boolean;
+  /** Key prefix for blocks with no `id`. */
+  keyPrefix?: string;
+  /** Maps a node to the schema `SchemaRenderer` renders (identity by default). */
+  toSchema?: (node: unknown) => unknown;
+  attributes?: Record<string, string | undefined>;
+}> = ({ nodes, className, rail, keyPrefix = 'block', toSchema, attributes }) => {
+  const inRail = React.useContext(PageBlockRailContext);
+  const isRail = !!rail || inRail;
+  const grid = (
+    <div className={cn('grid grid-cols-12 gap-4', className)} {...attributes}>
+      {nodes.map((node, idx) => {
+        const n = node as { id?: unknown; type?: unknown } | null;
+        const span = pageBlockSpan(n?.type, isRail);
+        return (
+          <div
+            key={typeof n?.id === 'string' && n.id ? n.id : `${keyPrefix}-${idx}`}
+            className={cn('min-w-0 empty:hidden', PAGE_BLOCK_SPAN_CLASS[span])}
+            data-block-span={span}
+          >
+            <SchemaRenderer schema={(toSchema ? toSchema(node) : node) as React.ComponentProps<typeof SchemaRenderer>['schema']} />
+          </div>
+        );
+      })}
+    </div>
+  );
+  return rail && !inRail ? <PageBlockRailContext.Provider value>{grid}</PageBlockRailContext.Provider> : grid;
+};
+
+/**
+ * A container's child slot as a block grid: a list goes on the grid, while a
+ * bare node or text renders as it did (`renderChildren`), since there is
+ * nothing to lay out beside it.
+ */
+export function renderBlockChildren(children: unknown, render: (c: unknown) => React.ReactNode): React.ReactNode {
+  if (Array.isArray(children) && children.length > 0) return <PageBlockGrid nodes={children} />;
+  return render(children);
+}
diff --git a/packages/components/src/renderers/layout/page.tsx b/packages/components/src/renderers/layout/page.tsx
index 7af5235428..ec3696fcac 100644
--- a/packages/components/src/renderers/layout/page.tsx
+++ b/packages/components/src/renderers/layout/page.tsx
@@ -30,7 +30,7 @@ import { compile, manifestFromConfigs, type Diagnostic } from '@object-ui/sdui-p
 import { ReactKindPage } from './react-page';
 import { PRINT_PAGE_ATTRIBUTE, PRINT_RUNNING_ATTRIBUTE, buildPagePrintStylesheet, isPagePrintDeclaration } from './page-print';
 import { cn } from '../../lib/utils';
-import { pageBlockSpan, PAGE_BLOCK_SPAN_CLASS } from './page-block-span';
+import { PageBlockGrid } from './page-block-grid';
 import { PageDescriptionContext } from './page-description-context';
 
 // ---------------------------------------------------------------------------
@@ -203,9 +203,8 @@ function pageHeaderOwnsTitle(schema: PageNodeSchema): boolean {
  * row on a wide screen instead of stacking as four full-width stripes. Every
  * template places its regions through this one component, so each gets the
  * grid. A `rail` region (sidebar / aside) is a narrow column, where a fold by
- * viewport width would squeeze a tile to a sliver, so its blocks stay full
- * width. The cell is `empty:hidden`, so a block that renders nothing (hidden)
- * leaves no gap.
+ * viewport width would squeeze a tile to a sliver, so its blocks, and the
+ * blocks inside its containers, stay full width (`./page-block-grid`).
  */
 const RegionContent: React.FC<{
   region: PageNodeRegion;
@@ -216,23 +215,14 @@ const RegionContent: React.FC<{
   if (components.length === 0) return null;
 
   return (
-    <div
-      className={cn('grid grid-cols-12 gap-4', region.className, className)}
-      data-region={region.name}
-    >
-      {components.map((node: SchemaNode, idx: number) => {
-        const span = pageBlockSpan((node as { type?: unknown })?.type, rail);
-        return (
-          <div
-            key={(node as any)?.id || `${region.name}-${idx}`}
-            className={cn('min-w-0 empty:hidden', PAGE_BLOCK_SPAN_CLASS[span])}
-            data-block-span={span}
-          >
-            <SchemaRenderer schema={toRenderableSchema(node)} />
-          </div>
-        );
-      })}
-    </div>
+    <PageBlockGrid
+      nodes={components}
+      className={cn(region.className, className)}
+      rail={rail}
+      keyPrefix={region.name}
+      toSchema={(node) => toRenderableSchema(node as SchemaNode)}
+      attributes={{ 'data-region': region.name }}
+    />
   );
 };