@nocoo/basalt 2.1.8 → 3.0.0

package/ai/INTEGRATION.md

@@ -1,5 +1,7 @@
 # Basalt application chrome
 
+Design tokens, component categories, intrinsic sizing and motion rules are authoritative in [DESIGN.md](DESIGN.md). Follow that contract for library code and examples.
+
 This is the one-pass setup for a Basalt app. An MVP is **login + shell + one page**. After that, product work is arranging `LayerCard` on the island. Do not invent a second header, a second rail, or a second title above the content heading.
 
 The library owns the rail, the main column, collapse motion, the island, the page heading, and region rules. The app owns navigation data, brand, version, identity, and page bodies.
@@ -43,7 +45,7 @@ AppShell                          ← dashboard and catalog routes
 ├── Sidebar                       ← product title + version + nav
 └── AppMain                       ← id="main-content"
     ├── AppHeader                 ← crumbs + current page | top-right
-    └── island wrap               ← px-2 pb-2 md:px-3 md:pb-3
+    └── island wrap               ← px-basalt-space-lg pb-basalt-space-lg md:px-basalt-space-lg md:pb-basalt-space-lg
         └── ContentIsland
             ├── PageHeader        ← title + subtitle | create / short filters
             │                     ← optional own-row complex filters
@@ -51,7 +53,7 @@ AppShell                          ← dashboard and catalog routes
             └── LayerCard…        ← all later product UI
 ```
 
-`AppHeader.title` is the current page in the top bar (`h1`, `text-sm`). `PageHeader.title` is the content heading (`h1`, `text-2xl`). They may use the same words. They are different roles. Do not put an icon + page name above `PageHeader` — that duplicates the bar.
+`AppHeader.title` is the current page in the top bar (`h1`, `text-sm`). `PageHeader.title` is the content heading (`h1`, `text-2xl`). They may use the same words in regular workspaces. Mobile immersive layouts instead use one compact AppHeader and a desktop-only PageHeader wrapper; see §6. They are different roles. Do not put an icon + page name above `PageHeader` — that duplicates the bar.
 
 The landing page and its prerendered HTML share `LandingContent`. Load the site stylesheet from `index.html` so it also works without JavaScript. Scope marketing CSS to `.landing` and crawl summaries to `[data-crawl-page]`; do not set global `header`, `main`, or `footer` dimensions. Keep document scrolling available on `html`, `body`, and `#root`. `AppShell` contains the dashboard viewport, and `ContentIsland` owns its independent scroll. Give both a positioning context (`relative`) so absolutely positioned content, including screen-reader labels, stays inside the correct scroll boundary.
 
@@ -291,7 +293,7 @@ function PreferencesControls() {
   const { accent, setAccent } = useAccent();
 
   return (
-    <div className="flex flex-wrap items-center gap-2">
+    <div className="flex flex-wrap items-center gap-basalt-space-lg">
       <span className="text-sm font-medium">Theme: {theme}</span>
       <Button
         variant="outline"
@@ -300,7 +302,7 @@ function PreferencesControls() {
       >
         Toggle {theme === "dark" ? "Light" : "Dark"}
       </Button>
-      <span className="text-sm font-medium ml-2">Accent: {accent}</span>
+      <span className="text-sm font-medium ml-basalt-space-lg">Accent: {accent}</span>
       <Button
         variant="outline"
         size="sm"
@@ -332,7 +334,7 @@ export function HostPreferencesApp() {
         accent={accent}
         onAccentChange={setAccent}
       >
-        <div className="p-4 border rounded-lg space-y-3">
+        <div className="p-basalt-space-lg border rounded-lg space-y-basalt-space-lg">
           <p className="text-xs text-basalt-muted-foreground">
             Host owns document root DOM and persistence. Basalt contexts operate safely without side-effects.
           </p>
@@ -365,25 +367,49 @@ Icons: `lucide-react`, `strokeWidth={1.5}`, nav size `h-4 w-4 shrink-0`.
 <a id="root-geometry"></a>
 ## 6. Root geometry
 
-`AppShell` is a full-viewport flex row: `h-screen w-full overflow-hidden bg-basalt-background`.
+`AppShell` owns the viewport and safe area; `AppMain` and `ContentIsland` derive their scroll behavior from it. Choose deliberately:
 
-```
-AppShell                         ← flex row, h-screen, overflow hidden
-├── AppSkipLink                  ← first child
-├── Sidebar                      ← the rail (in-flow, not fixed)
-└── AppMain                      ← flex-1 min-w-0 column, overflow hidden
-    ├── AppHeader                ← h-14
-    └── island wrap              ← flex-1 min-h-0, px-2 pb-2 md:px-3 md:pb-3
-        └── ContentIsland        ← page outlet
-```
+| `layout` | Below 768px | 768px and above |
+| --- | --- | --- |
+| `workspace` (default) | Bounded panes | Bounded panes |
+| `responsive` | Natural document scrolling | Bounded panes |
+| `document` | Natural document scrolling | Natural document scrolling |
+
+Bounded shells use border-box `height/max-height: 100dvh`. Document shells use `min-height: 100dvh`, automatic height, visible overflow and ordinary root scrolling. Main and island release their height/overflow constraints together; no UA detection, innerHeight workaround, fixed reader viewport or nested mobile scroller is needed. Desktop workspaces keep the island as the vertical scroll owner.
 
 ### AppShell, AppMain, AppSkipLink API & Contracts
 
-- **`AppShell`**: Viewport root container. Inherits standard `HTMLAttributes<HTMLDivElement>`. Renders a full-viewport flex row (`h-screen w-full overflow-hidden bg-basalt-background`). Does not forward ref.
-- **`AppMain`**: Primary content container. Inherits standard `HTMLAttributes<HTMLElement>`. Defaults `id="main-content"` as the skip-link landmark target, which can be overridden by props via `{...props}`. Recommended to keep `"main-content"` matching `AppSkipLink`. Renders a vertical column with `h-full min-w-0 flex-1 flex-col overflow-hidden`. Does not forward ref.
-- **`AppSkipLink`**: Accessibility skip target. Inherits standard `AnchorHTMLAttributes<HTMLAnchorElement>`. Defaults `href="#main-content"`. Renders screen-reader-only element that transitions into absolute focus overlay on keyboard navigation (`sr-only focus:not-sr-only focus:absolute ...`). Does not forward ref.
+- **`AppShell`** accepts `layout?: "workspace" | "responsive" | "document"` and native div attributes. It is the sole safe-area owner of the normal document tree: CSS `env(safe-area-inset-*)` padding is included in its border-box. In document mode bottom padding is trailing content, never a fixed reserved strip. Do not subtract these insets again from main/island height.
+- **`AppMain`** renders the main landmark with `id="main-content"` and `tabIndex={-1}` by default. Native main attributes may override these. It has `min-width: 0` and a flexible column layout; its height and overflow follow the shell.
+- **`AppSkipLink`** points to `#main-content` unless `href` is supplied. Provide visible link text; keep it first in the shell.
+- **`ContentIsland`** (from `components/sidebar`) accepts `mobileSurface?: "inset" | "edge-to-edge"` (default `inset`). Both are L1 surface roots. Edge-to-edge removes mobile padding, radius, ring and shadow; desktop padding/radius remain. The application supplies readable inner content padding, not another painted card.
+- All four accept native attributes and `className`; they do not forward refs. Avoid overriding their height/overflow contract. Put specialized bounded desktop panes inside the island with `md:` constraints only.
+
+```tsx excerpt:responsive-shell
+<AppShell layout="responsive">
+  <AppSkipLink>Skip to content</AppSkipLink>
+  <AppMain>
+    <AppHeader title="Field notes" actions={actions} />
+    <div className="flex min-h-0 min-w-0 flex-1 flex-col md:px-basalt-space-lg md:pb-basalt-space-lg">
+      <ContentIsland mobileSurface="edge-to-edge">
+        <div className="mx-auto max-w-prose px-basalt-space-lg py-basalt-space-lg md:p-0">{content}</div>
+      </ContentIsland>
+    </div>
+  </AppMain>
+</AppShell>
+```
+
+The wrapper intentionally has **no mobile `px-basalt-space-lg` / `pb-basalt-space-lg`**. ContentIsland cannot remove spacing owned by its parent. Remove consumer `h-screen`, `h-full`, `overflow-hidden`, fixed heights and body scroll locks from the document path; all intermediate wrappers must be natural-height columns. Do not target private descendants to undo the library.
+
+The consumer owns `viewport` metadata: `width=device-width, initial-scale=1, viewport-fit=cover`. Do not disable zoom. The library never edits document metadata or body styles for layout. Floating modal navigation has a separate portal tree: `Sheet` or overlay `Sidebar` owns modal scroll locking/focus; the Sidebar within it remains bounded and applies that portal's safe-area padding once. Do not add a manual body overflow effect.
+
+A desktop Sidebar stays bounded even beside a document: its own navigation may scroll, but the long main content belongs to the document. Hide the desktop rail on mobile and use the same navigation inside an expanded Sidebar in a Sheet. Do not mount duplicate focusable navigation. Single-column reading needs no Sidebar at all.
+
+`AppHeader` adds `sticky?: boolean` (default false) and `density?: "comfortable" | "compact"` (default comfortable). Compact is 52px, with at least 44px controls inside the leading/actions slots (not breadcrumb/title links); comfortable remains 56px. `sticky` uses the current scroll owner and an opaque L1 background. Place it directly inside AppMain or as the first child of ContentIsland; do not put it in a short wrapper that limits its sticky travel. The shell exposes `--basalt-safe-top` and resolves `--basalt-sticky-top` to that inset for document scrolling, or zero for bounded panes. The sticky row offsets below the notch and paints the gap with a pseudo-element. Initial inset is still paid only once by the shell, not added again to header height. Do not add safe-area padding to the header. A bounded header outside the island is already stationary and does not need `sticky`.
+
+**Single-header immersion is an explicit application layout.** On mobile, use one compact `AppHeader` with title, back/navigation and essential actions; omit the duplicated `PageHeader` (or put it in a `hidden md:block` wrapper). Keep the normal desktop PageHeader hierarchy for workspaces. Content section headings still belong in the document. Use existing DropdownMenu/Popover for secondary actions and 44px minimum touch targets; never invent reader-specific routing or actions in the library.
 
-The island wrap is the only extra layout div in the main column. Pages render **inside** `ContentIsland`. Pages do not set `h-screen`, side padding, or a second card around the island.
+Copyable complete recipes: [mobile layouts](packages/basalt/ai/RECIPES.md#mobile-layouts). Live full-page examples: `/examples/reader`, `/examples/list-detail`, `/examples/workspace`. Desktop bounded panes, mobile root scrolling, form focus and modal restoration are separate checks. Automated WebKit checks CSS, scrolling and focus, **not physical iPhone Safari toolbar collapse or the software keyboard**; verify those manually on device.
 
 ---
 
@@ -391,48 +417,33 @@ The island wrap is the only extra layout div in the main column. Pages render **
 
 `Sidebar` **is** the column. It already has:
 
-- `h-screen`, `flex-col`, `shrink-0`, `sticky top-0`
+- shell-derived bounded height (standalone `100dvh`), `flex-col`, `shrink-0`, sticky positioning at the shell-owned safe top
 - expanded width **260px** (inline `width`)
 - collapsed width **68px**
-- collapse animation `transition-all duration-300 ease-in-out`
+- collapse animation `transition-[width] duration-basalt-normal ease-basalt` (disabled for reduced motion)
 
 Children of `Sidebar` are **regions only**: header, search, nav, footer. They fill that column. `SidebarNav` is `flex-1 min-h-0 overflow-y-auto`, so the footer stays at the bottom.
 
 Do not wrap those regions in another full-viewport column. Do not set `h-screen`, `w-[260px]`, or `w-[68px]` on an inner element. Width and height stay on `Sidebar`.
 
-### Expanded tree
+### Shared navigation geometry
 
-```
-Sidebar                          ← collapsed={false}; owns 260px and h-screen
-├── SidebarHeader                ← h-14 px-3 already
-│   └── brand row                ← flex, items-center, justify-between, w-full
-│                                 (no extra horizontal padding)
-├── search wrap                  ← px-3 pb-1 only
-│   └── SidebarSearch
-├── SidebarNav                   ← pt-1; flex-1
-│   ├── SidebarPartition         ← label; already px-6
-│   └── item stack               ← flex flex-col gap-0.5 px-3
-│       └── SidebarItem          ← already px-3 py-2.5
-└── SidebarFooter                ← px-4 py-3 already
-    └── SidebarUser
-```
-
-`SidebarHeader` already pads horizontally. Brand, version pill, and collapse control go **directly** in it. The version string is read from the app `package.json` at build time. Never hardcode it.
+`SidebarNav` and `NavigationMenuList` own one `--basalt-space-nav-inset` (8px) boundary and `--basalt-space-nav-gap` (2px) between rows. Sidebar groups do not add another horizontal inset. Top-level items, group items, editable/folder rows and horizontal navigation links reuse the existing row roles: 8px horizontal, 6px vertical, 8px icon gap, 22px line box and a 34px reference height. Header, search wrapper and footer share the same navigation inset. Do not add caller-owned `px-basalt-space-lg`, `pt-basalt-space-sm` or item-stack padding to compensate for missing package geometry.
 
-Nav labels use `SidebarPartition`. The item stack is **one** `px-3` column (the same gutter `SidebarGroup` uses). `SidebarItem` already has its own `px-3`. That is the whole horizontal rhythm: partition at 24px, item content at 24px.
+Use `SidebarNav` for vertical lists, including standalone lists of `EditableNavItem` / `FolderNavItem`; `NavigationMenuList` owns horizontal/vertical Radix navigation. Both compose the existing list-local hover adapter. One background moves with transform between enabled rows, follows keyboard focus and returns to selection on pointer leave. Nested lists own separate highlights. Hidden, disabled and actively renamed rows are excluded. Geometry reads are batched per animation frame, same-row pointer motion causes no updates, and reduced motion disables transitions. Navigation state, routes and rename operations remain application-owned; the adapter is View-only.
 
-Collapsible sections use `SidebarGroup` instead of Partition + stack. `SidebarGroup` already includes the item gutter. Do not add another `px-3` around it.
+`SidebarHeader` and `SidebarFooter` already pad horizontally. Brand, version pill, and collapse control go directly in the header. The version string is read from the app `package.json` at build time. Never hardcode it. `SidebarPartition` aligns with row text. `SidebarGroup` adds only section spacing, never a second item gutter.
 
 ```tsx excerpt:sidebar-expanded-structure
 <Sidebar collapsed={collapsed}>
   <SidebarHeader>
     <div className="flex w-full items-center justify-between">
-      <div className="flex min-w-0 items-center gap-3">
+      <div className="flex min-w-0 items-center gap-basalt-space-lg">
         <BasaltMark className="h-5 w-5 shrink-0" />
         <span className="truncate text-lg font-semibold text-basalt-foreground md:text-xl">
           Acme
         </span>
-        <span className="shrink-0 rounded-md bg-basalt-secondary px-1.5 py-0.5 text-[10px] leading-none font-medium text-basalt-muted-foreground">
+        <span className="shrink-0 rounded-md bg-basalt-secondary px-basalt-space-md py-basalt-space-xs text-[10px] leading-none font-medium text-basalt-muted-foreground">
           v{version}
         </span>
       </div>
@@ -447,14 +458,14 @@ Collapsible sections use `SidebarGroup` instead of Partition + stack. `SidebarGr
       </Button>
     </div>
   </SidebarHeader>
-  <div className="px-3 pb-1">
+  <div className="px-basalt-nav-inset">
     <SidebarSearch onClick={() => setSearchOpen(true)}>Search</SidebarSearch>
   </div>
-  <SidebarNav className="pt-1">
+  <SidebarNav>
     {groups.map((group) => (
       <div key={group.label}>
         <SidebarPartition>{group.label}</SidebarPartition>
-        <div className="flex flex-col gap-0.5 px-3">
+        <div className="flex flex-col gap-basalt-nav-gap">
           {group.items.map((item) => (
             <SidebarItem
               key={item.href}
@@ -475,56 +486,48 @@ Collapsible sections use `SidebarGroup` instead of Partition + stack. `SidebarGr
 </Sidebar>
 ```
 
+SidebarPartition marks a major section; SidebarGroup is a smaller uppercase, semibold disclosure label with additional group spacing. Group labels do not participate in the destination hover layer. Do not restyle them as ordinary SidebarItem rows or add per-page indentation repairs.
+
 ### Collapsed tree
 
 Pass `collapsed` on `Sidebar`. The element becomes 68px. Children are icon-sized and centered. Still no inner width/height wrapper.
 
-```
-Sidebar                          ← collapsed; owns 68px
-├── SidebarHeader                ← justify-center px-0
-├── collapse Button              ← ghost icon, mb-1
-├── search SidebarIconItem       ← mb-2; tooltip
-├── SidebarNav                   ← w-full items-center gap-1 pt-1
-│   └── SidebarIconItem          ← h-10 w-10; tooltip
-└── SidebarFooter                ← flex w-full justify-center px-0
-```
+The 68px rail uses `--basalt-size-rail`. Header and footer center their content automatically; SidebarIconItem uses the shared 34px control size. The navigation region centers its icon rows on that same rail axis without caller margin overrides. Render icon-only content with an accessible name and tooltip when collapsed; the library does not hide arbitrary application text. Keep a brand mark's expanded inset consistent with the collapsed axis instead of adding collapse-only offsets.
 
 ```tsx excerpt:sidebar-collapsed-structure
 <Sidebar collapsed={collapsed}>
-  <SidebarHeader className="justify-center px-0">
+  <SidebarHeader>
     <BasaltMark className="h-5 w-5" />
   </SidebarHeader>
   <Button
     variant="ghost"
     size="icon"
-    className="mb-1 self-center"
+    className="mb-basalt-space-sm self-center"
     onClick={onToggle}
     aria-label="Expand sidebar"
   >
     <PanelLeft aria-hidden="true" />
   </Button>
-  <Tooltip delayDuration={0}>
-    <TooltipTrigger asChild>
-      <SidebarIconItem
-        className="mb-2 self-center"
-        onClick={() => setSearchOpen(true)}
-        aria-label="Search (⌘K)"
-      >
-        <Search className="h-4 w-4" strokeWidth={1.5} aria-hidden="true" />
-      </SidebarIconItem>
-    </TooltipTrigger>
-    <TooltipContent side="right" sideOffset={8}>
-      Search (⌘K)
-    </TooltipContent>
-  </Tooltip>
-  <SidebarNav className="w-full items-center gap-1 pt-1">
+  <SidebarNav>
+    <Tooltip delayDuration={0}>
+      <TooltipTrigger asChild>
+        <SidebarIconItem
+          onClick={() => setSearchOpen(true)}
+          aria-label="Search (⌘K)"
+        >
+          <Search className="h-4 w-4" strokeWidth={1.5} aria-hidden="true" />
+        </SidebarIconItem>
+      </TooltipTrigger>
+      <TooltipContent side="right" sideOffset={8}>
+        Search (⌘K)
+      </TooltipContent>
+    </Tooltip>
     {items.map((item) => (
       <Tooltip key={item.href} delayDuration={0}>
         <TooltipTrigger asChild>
           <SidebarIconItem
             active={active(item.href)}
             aria-label={item.label}
-            className="self-center"
             onClick={() => navigate(item.href)}
           >
             <item.icon className="h-4 w-4" strokeWidth={1.5} />
@@ -536,7 +539,7 @@ Sidebar                          ← collapsed; owns 68px
       </Tooltip>
     ))}
   </SidebarNav>
-  <SidebarFooter className="flex w-full justify-center px-0">
+  <SidebarFooter>
     <Tooltip delayDuration={0}>
       <TooltipTrigger asChild>
         <span className="inline-flex">{avatar}</span>
@@ -579,9 +582,11 @@ Breakpoint: `768px`. Below that, the in-flow rail is omitted. The same sidebar c
 </Sheet>
 ```
 
-`SheetContent` is already `h-full`. `Sidebar` still owns the 260px column inside it. Close the sheet on pathname change. While open, set `document.body.style.overflow = "hidden"` and clear it on close.
+`SheetContent` bounds its Sidebar to the available height. Sidebar owns the 260px column and the portal safe area. Close the sheet on pathname change. Radix Sheet owns modal scroll locking and focus restoration; do not set body overflow separately.
+
+Sheets slide from their declared edge in 350ms and return in 250ms, while the backdrop fades and blurs to 6px. DropdownMenu, Select, ContextMenu, MenuBar, Popover, HoverCard and Tooltip scale from their trigger origin and fade in/out in 200/150ms. Shared motion tokens live in the package stylesheet; both CSS entrypoints include them. Reduced motion disables these animations. Keep content mounted through Radix's closing state; do not conditionally remove the root before its exit completes.
 
-`AppHeader` `leading` is the menu button on mobile only (`Button variant="ghost" size="icon" className="h-8 w-8"`).
+`AppHeader` `leading` is the menu button on mobile only. Use `density="compact"` with `Button variant="ghost" size="icon"`; compact header controls have a 44px minimum target.
 
 Header actions use a stable hand cursor and compact 12px `TooltipContent`. `Button`, `LinkButton`, `Toggle`, and `ToggleGroupItem` keep their full rectangular pointer target with a transparent `::before`, including rounded corners. Wrap the actual button or link in `TooltipTrigger asChild` so the trigger retains one focusable hit target. `Toggle` and `ToggleGroupItem` selection styling follows `aria-pressed` / `aria-checked`, independently of the tooltip's `data-state`. Icon-only links must include a screen-reader label inside the link as well as an accessible name.
 
@@ -621,12 +626,6 @@ export function AppFrame() {
     setMobileOpen(false);
   }, [location.pathname]);
 
-  useEffect(() => {
-    document.body.style.overflow = mobileOpen ? "hidden" : "";
-    return () => {
-      document.body.style.overflow = "";
-    };
-  }, [mobileOpen]);
 
   return (
     <AppShell>
@@ -663,7 +662,7 @@ export function AppFrame() {
           title={title}
           actions={<ThemeToggle aria-label={`Toggle theme (now ${theme})`} />}
         />
-        <div className="flex min-h-0 flex-1 flex-col px-2 pb-2 md:px-3 md:pb-3">
+        <div className="flex min-h-0 flex-1 flex-col px-basalt-space-lg pb-basalt-space-lg md:px-basalt-space-lg md:pb-basalt-space-lg">
           <ContentIsland>
             <Outlet />
           </ContentIsland>
@@ -676,14 +675,14 @@ export function AppFrame() {
 
 <a id="appheader-and-breadcrumbs"></a>
 
-`AppHeader` is `h-14`, matching `SidebarHeader`.
+`AppHeader` defaults to `h-14`, matching `SidebarHeader`; `density="compact"` uses a 52px row with 44px minimum targets. `sticky` keeps it visible within the current scroll owner; see §6 for safe-area positioning.
 
 ### AppHeader API & Contracts
 
 `AppHeader` inherits root `header` attributes (`HTMLAttributes<HTMLElement>`).
 
 - **`title?: string`**: Current page title rendered inside an `h1` (`truncate text-sm font-normal text-basalt-foreground`). (Source type intersection is `HTMLAttributes<HTMLElement> & { title?: ReactNode }`, which narrows valid `title` values to `string | undefined`). Do not also put the current page title in `breadcrumbs`.
-- **`breadcrumbs?: { href?: string; label: ReactNode }[]`**: Ancestor breadcrumb hierarchy displayed before the current page title (ancestors only). Separated by ChevronRight.
+- **`breadcrumbs?: { href?: string; label: ReactNode }[]`**: Breadcrumb hierarchy separated by ChevronRight. Supply ancestors with `title`, or a complete path ending in a nonlinked current item and omit `title`. No trailing separator is rendered without a title.
 - **`leading?: ReactNode`**: Optional slot before breadcrumbs, typically the mobile hamburger drawer trigger.
 - **`actions?: ReactNode`**: Top-right framework controls (`ThemeToggle`, account dropdown, etc.). This slot is reserved for framework controls, **not** the page-level create button.
 - **Native & Ref Boundary**: Inherits native `HTMLAttributes<HTMLElement>`, but does not forward ref.
@@ -696,56 +695,29 @@ Product title and version live in `SidebarHeader`, not in `AppHeader`. Read the
 
 Login is **not** inside `AppShell`. It is a centered badge on the full viewport.
 
-Shape: ISO ID card, `aspect-[54/86]`, `w-72`, `rounded-2xl`, `bg-basalt-card`, layered shadow, hairline ring. Primary strip on top, mark and actions in the body, status strip pinned to the bottom.
+Shape: a fixed badge width, `rounded-basalt-lg`, `bg-basalt-card` and a hairline ring. Three bands: the primary strip on top, the body holding the mark and actions, and the status footer at the bottom. The body grows with its content, so a sign-in form fits without a fixed aspect ratio.
 
 ```tsx excerpt:login-badge-page
 export function LoginPage() {
   return (
-    <div className="relative flex min-h-screen items-center justify-center overflow-hidden bg-basalt-background p-4">
-      <div className="flex flex-col items-center">
-        <div
-          data-basalt-surface-root=""
-          className="relative flex aspect-[54/86] w-72 flex-col overflow-hidden rounded-2xl bg-basalt-card ring-1 ring-black/[0.08] dark:ring-white/[0.06]"
-          style={{
-            boxShadow: [
-              "0 1px 2px rgba(0,0,0,0.06)",
-              "0 4px 8px rgba(0,0,0,0.04)",
-              "0 12px 24px rgba(0,0,0,0.06)",
-              "0 24px 48px rgba(0,0,0,0.04)",
-              "0 0 0 0.5px rgba(0,0,0,0.02)",
-              "0 0 60px rgba(0,0,0,0.03)",
-            ].join(", "),
-          }}
-        >
-          <div className="bg-basalt-primary px-5 py-4">
-            <div className="flex items-center justify-between">
-              <div className="h-4 w-8 rounded-full bg-basalt-background/80" />
-              <div className="flex items-center gap-2">
-                <BasaltMark className="h-4 w-4 text-basalt-primary-foreground" />
-                <span className="text-sm font-semibold text-basalt-primary-foreground">
-                  Acme
-                </span>
-              </div>
-              <span className="text-[10px] font-medium tracking-widest text-basalt-primary-foreground/60 uppercase">
-                Visitor
-              </span>
-            </div>
-          </div>
-          <div className="flex flex-1 flex-col items-center px-6 pt-6 pb-14">
-            <div className="flex h-24 w-24 items-center justify-center overflow-hidden rounded-full bg-basalt-secondary p-2.5 ring-1 ring-basalt-border">
-              <BasaltMark className="h-10 w-10 text-basalt-muted-foreground" />
-            </div>
-            <p className="mt-5 text-lg font-semibold text-basalt-foreground">Welcome</p>
-            <p className="mt-1 text-xs text-basalt-muted-foreground">Sign in to continue</p>
-            <div className="mt-5 h-px w-full bg-basalt-border" />
-            <div className="flex-1" />
-            <Button variant="secondary" className="w-full rounded-xl py-3">
-              Continue
-            </Button>
-          </div>
-          <div className="absolute right-0 bottom-0 left-0 flex items-center justify-center border-t border-basalt-border bg-basalt-secondary/50 py-2.5">
-            <span className="text-[10px] text-basalt-muted-foreground">Secure sign-in</span>
-          </div>
+    <div className="basalt-ui relative flex min-h-dvh items-center justify-center bg-basalt-background p-basalt-space-lg">
+      <div
+        data-basalt-surface-root=""
+        className="flex w-72 max-w-full flex-col overflow-hidden rounded-basalt-lg bg-basalt-card ring-1 ring-basalt-border"
+      >
+        <div className="flex items-center justify-between gap-basalt-space-lg bg-basalt-primary px-basalt-space-lg py-basalt-space-lg">
+          <span className="text-basalt-base font-semibold text-basalt-primary-foreground">Acme</span>
+          <span className="text-basalt-xs font-medium uppercase tracking-widest text-basalt-primary-foreground/80">
+            Visitor
+          </span>
+        </div>
+        <div className="flex flex-1 flex-col items-center gap-basalt-space-lg px-basalt-space-lg py-basalt-space-lg">
+          <p className="text-basalt-xl font-semibold text-basalt-foreground">Welcome</p>
+          <p className="text-basalt-sm text-basalt-muted-foreground">Sign in to continue</p>
+          <Button className="w-full">Continue</Button>
+        </div>
+        <div className="border-t border-basalt-border px-basalt-space-lg py-basalt-space-lg">
+          <p className="text-basalt-xs text-basalt-muted-foreground">Secure sign-in</p>
         </div>
       </div>
     </div>
@@ -777,15 +749,17 @@ Boot and route gates use `LoadingScreen` — a centered mark and a 6rem shimmer
 
 ## 13. First page
 
-When skip link, rail (260 / 68, 300ms), header `h-14`, and island are in place, add routes as `Outlet` pages. Application pages inside the island start with `PageHeader`. The shell file does not grow with page UI.
+When skip link, rail (260 / 68, 300ms), header `h-14`, and island are in place, add routes as `Outlet` pages. Regular application pages inside the island start with `PageHeader`. Mobile immersive layouts may use a single `AppHeader` instead, with `PageHeader` shown only on desktop; see the root geometry contract. The shell file does not grow with page UI.
 
-Standalone login, loading, error, and landing pages use their own first-screen structure: `/login` preserves the visitor-badge composition, `/loading` is a named loading status, and `/404` and `/static-page` have independent headings. Library reference pages use their document heading and section navigation. These are deliberate layout exceptions, not alternate application-page templates.
+Standalone login, loading, error, and landing pages use their own first-screen structure: `/login` preserves the visitor-badge composition, `/loading` is a named loading status, and `/404` and `/static-page` have independent headings. These are deliberate layout exceptions, not alternate application-page templates. Library reference pages, category overviews and source viewers are normal island pages: they use the same heading template, with document sections below it.
 
-The showcase site's library index and dashboard examples use the app-local `ShowcaseHeader` with the landing page's paired day/night mountain imagery fading into the content island. Headings and actions align with the page's content grid; the landscape reaches the island's top edge and scrolls with it. The library has a more spacious opening, dashboards use the compact variant, and reference headings carry a quieter version. The original logo remains in the navigation. This site-specific treatment does not change the package's `PageHeader` or application layout recipe.
+The showcase's routes under `DashboardLayout` use the app-local `ShowcasePage`: one PageHeader and a shared section gap, with no repeated island padding, painted shell or nested main/viewport. Every catalog route keeps that shared scale: 30px titles and 24px page and document-section separation, whether it is an application page, a library index, a category guide, documentation or a source viewer. Catalog pages do not override the shared scale or its document rhythm; `PageHeader` keeps its `size` choices for consumers, where dashboards select `size="lg"` for 30px titles and ordinary application pages keep the `md` default. Header height follows content, never a scenic banner or negative inset. The original logo remains in navigation; mountain artwork belongs only to the independent landing. See [DESIGN.md](DESIGN.md#page-composition).
+
+The catalog's app-local `RouteScrollReset` wraps each leaf page inside its Suspense boundary. Once the route content is committed, a changed pathname resets ContentIsland and document scrolling immediately, including Back/Forward navigation. Valid URL fragments instead use the chapter anchor with the measured sticky-directory inset. Same-page query changes and local controls preserve scroll. The shared sidebar is not remounted or scrolled. Routing policy belongs to the app, never to the Basalt package.
 
 The `/forms`, `/settings`, `/data`, and `/chat` examples demonstrate local state and simulated requests, including failure/retry and cancellation. Their viewmodels own data and timers; Views own native FormData, focus, and responsive layout. Replace the local service adapter when integrating a backend. Theme selection uses the shared provider; local profile, uploads, and chat changes do not update a real account.
 
-`PageHeader` is flush on `ContentIsland`. Do not wrap it in another card. Do not put an icon row above the heading.
+`PageHeader` is flush on `ContentIsland`. The island owns 16px mobile insets, 24px tablet insets, and 32px horizontal / 24px vertical desktop insets. Do not wrap the header in another card or add page padding. `PageHeader.size` is `"md" | "lg" | "xl"` (default `"md"`); larger headings use 16/24px descriptions, all title/description pairs use an 8px gap. `SectionRule variant="heading"` gives reading sections a 20px sentence-case title without the compact dashed rule. Controls and card slots keep their compact geometry.
 
 ### Create and filters
 
@@ -806,7 +780,7 @@ import { PageHeader } from "@nocoo/basalt/components/page-header";
 
 export default function ProjectsPage() {
   return (
-    <div className="space-y-8">
+    <div className="space-y-basalt-layout-lg">
       <PageHeader
         title="Projects"
         description="Active work in this workspace."
@@ -836,7 +810,7 @@ import { SectionRule } from "@nocoo/basalt/components/section-rule";
 
 export default function ProjectsPage() {
   return (
-    <div className="space-y-8">
+    <div className="space-y-basalt-layout-lg">
       <PageHeader
         title="Projects"
         description="Active work in this workspace."
@@ -855,7 +829,7 @@ export default function ProjectsPage() {
         }
       />
       <SectionRule title="Overview" hint="Live totals for the current workspace.">
-        <div className="grid grid-cols-2 gap-4">
+        <div className="grid grid-cols-2 gap-basalt-layout">
           <LayerCard>
             <p className="text-xs text-basalt-muted-foreground">Projects</p>
             <p className="text-2xl font-semibold">24</p>
@@ -954,7 +928,9 @@ Place cards with Grid or flex. Those classes do not paint. A grid of `LayerCard`
 
 Input, Select, secondary / outline Button use `bg-basalt-control` (`--basalt-control-fill` from the current surface) plus border. Do not override with `bg-card`, `bg-basalt-card`, or `bg-basalt-background`.
 
-`Table` sets `data-basalt-table`. Zebra, hover, and selected paint on `td`, from `--basalt-zebra-fill` / `--basalt-control-fill`.
+`Table` sets `data-basalt-table`. Zebra, hover, and selected paint on `td`, from `--basalt-zebra-fill`, `--basalt-hover` and `--basalt-selected`. Selection adds no decorative side bar or frame; semantic add/remove diff tints are preserved.
+
+Neutral selected states use the brighter `--basalt-selected` surface, readable `--basalt-selected-foreground` and navigation font weight, without decorative side bars or selected borders. Never use `accent` or `muted` to signal selection. Existing semantic checkmarks and tab underlines remain; do not add a decorative frame at the white ceiling. A moving hover layer must not erase the selected row. Sidebar, navigation menus, editable navigation and ChatInbox share this behavior and inset keyboard focus; neutral Button variants also honor `aria-pressed` and `aria-current`. Segments and tabs retain their existing measured indicator motion. Primary/destructive actions, check/radio/switch glyphs and semantic diffs keep their semantic colors. See [DESIGN.md](DESIGN.md#selection-and-navigation-hierarchy).
 
 `DescriptionList` is layout and type only. It is not a surface.
 
@@ -984,7 +960,7 @@ import { LayerCard } from "@nocoo/basalt/components/layer-card";
 
 ## 15. PageHeader and SectionRule
 
-`PageHeader` and `SectionRule` are the only page-level chrome inside the island. Import them from granular paths. They are not on the root barrel. Do not wrap the title in an island.
+`PageHeader` and `SectionRule` provide regular page-level chrome inside the island. A mobile immersive composition may use a single sticky AppHeader inside the island instead (§6). Import them from granular paths. They are not on the root barrel. Do not wrap the title in an island.
 
 ### PageHeader
 
@@ -1072,7 +1048,7 @@ export function ProfileForm() {
         <Switch name="notifications" defaultChecked />
       </Field>
 
-      <div className="flex gap-2 mt-4">
+      <div className="flex gap-basalt-space-lg mt-basalt-space-lg">
         <Button type="reset" variant="secondary">Reset</Button>
         <Button type="submit" variant="default">Save Changes</Button>
       </div>
@@ -1161,7 +1137,7 @@ export function EmptyActionExample() {
   const [created, setCreated] = useState(false);
 
   return (
-    <LayerCard className="max-w-md p-6">
+    <LayerCard className="max-w-md">
       {created ? (
         <p className="text-sm text-basalt-foreground">Project created successfully.</p>
       ) : (
@@ -1227,7 +1203,7 @@ export function ProjectSettingsForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-basalt-space-lg">
       <Field
         label="Project Name"
         hint="Unique name for your project workspace"
@@ -1265,12 +1241,12 @@ export function ProjectSettingsForm() {
       />
 
       {submittedData && (
-        <div data-testid="submission-output" className="text-sm font-mono p-2 border rounded">
+        <div data-testid="submission-output" className="text-sm font-mono p-basalt-space-lg border rounded">
           Submitted: {JSON.stringify(submittedData)}
         </div>
       )}
 
-      <div className="flex gap-2">
+      <div className="flex gap-basalt-space-lg">
         <Button
           type="button"
           variant="secondary"
@@ -1469,6 +1445,7 @@ Basalt charts are composed of responsive frame, legend, and tooltip subsystem pr
 ### StatCard & StatGrid (`@nocoo/basalt/charts/stat-card`)
 
 - **`StatCard`**: High-level KPI and telemetry presentation card supporting incremental interactive slots and status state transitions.
+  - **Composition**: One `LayerCard` surface with shared card insets, an unboxed title icon, tabular display value, comparison text and supporting content in that order. It has no header divider or fixed content height. Long labels and values wrap; actions remain accessible. Use a compact `LineChart`/`BarChart` child with `className="h-basalt-16 w-full"` and a visible time-window caption for trend cards. Keep bar baselines at zero and disclose nonzero line scales. Do not stretch plots with `flex-1`, repeat card padding or recreate the header in application CSS.
   - **Props (`StatCardProps`)**:
     - `value: string | number` (required): Core metric value. Formatted via `toLocaleString()` if numeric. Overridden when `status` is provided.
     - `title?: string` / `label?: string` (optional): Heading text (`title` takes precedence over `label`).
@@ -1495,6 +1472,8 @@ Basalt charts are composed of responsive frame, legend, and tooltip subsystem pr
 
 Basalt cartesian charts (`LineChart`, `AreaChart`, `BarChart`, `StackedBarChart`, `GroupedBarChart`, `Charts`, `Timeseries`, `CustomChart`, `Sparkline`, and `SlotBarChart`) support arbitrary, type-safe data keys beyond the legacy `y`, `y2`, and `y3` series convention:
 
+`Sparkline` renders compact, rounded bars with alternating full/muted intensity (decorative, not another data dimension). A single series defaults to chart green; explicit series colors and multi-series palette order are preserved. Its default plot is 112 by 20px, without axes, legends, tooltips or entrance animation. Null values remain gaps and negative values retain their baseline. Pair it with `Meter` for table cells: Meter uses 17 slots, redistributes red/yellow/green across the filled portion, and shows the numeric value inline. Colors do not imply domain-specific risk thresholds. Values clamp to 0..100 and non-finite readings announce unavailable. `BatteryMeter` remains the separate device-charge control.
+
 - **Generic Data Binding**:
   - `data: TData[]`: Generic record where `TData extends { x: string | number }`. Caller datasets can contain any number of arbitrary metric keys (e.g., `edgeCache`, `p95US`, `workersCPU`), nullable numbers (`number | null`), and optional numeric properties (`number | undefined`).
   - `series?: Array<ChartSeriesDescriptor<K>>`: Strongly-typed array of series descriptors. Series keys `K` are automatically constrained to `LineChartNumericKeys<TData>` (excluding coordinate `x` and rejecting non-numeric fields such as strings, booleans, or typos). Arbitrary keys require explicit series; omitted or empty series retain each chart's legacy `y`, `y2`, and `y3` series fallback. Note that TypeScript type inference does not automatically enumerate object keys at runtime.
@@ -1527,7 +1506,7 @@ export function StandaloneViteApp() {
 
   return (
     <ThemeProvider>
-      <div className="min-h-screen bg-basalt-background text-basalt-foreground p-6 space-y-6">
+      <div className="min-h-screen bg-basalt-background text-basalt-foreground p-basalt-space-lg space-y-basalt-space-lg">
         <PageHeader
           title="Standalone Workspace"
           description="Rendered with @nocoo/basalt/styles/standalone without Tailwind preflight"
@@ -1538,7 +1517,7 @@ export function StandaloneViteApp() {
             <span className="font-semibold text-basalt-foreground">Project Search</span>
           </LayerCard.Header>
           <LayerCard.Body>
-            <div className="flex gap-3 max-w-md">
+            <div className="flex gap-basalt-space-lg max-w-md">
               <Input
                 value={query}
                 onChange={(e) => setQuery(e.target.value)}
@@ -1615,7 +1594,7 @@ export default function NextClientDashboardPage() {
 
   return (
     <ThemeProvider>
-      <div className="p-6 space-y-4">
+      <div className="p-basalt-space-lg space-y-basalt-space-lg">
         <div className="flex justify-between items-center">
           <h2 className="text-xl font-bold text-basalt-foreground">Next.js Client Dashboard</h2>
           <ThemeToggle aria-label="Toggle theme mode" />
@@ -1628,7 +1607,7 @@ export default function NextClientDashboardPage() {
               onChange={(e) => setMetricName(e.target.value)}
               aria-label="Metric Name"
             />
-            <div className="mt-4">
+            <div className="mt-basalt-space-lg">
               <Button variant="outline" onClick={() => setMetricName("Default Metric")}>
                 Reset Metric
               </Button>
@@ -1688,12 +1667,12 @@ export function RoutedNavigationSection() {
   return (
     <MemoryRouter initialEntries={["/dashboard"]}>
       <LinkProvider render={ReactRouterLinkAdapter}>
-        <nav className="flex gap-4 p-4 border-b border-basalt-border">
+        <nav className="flex gap-basalt-space-lg p-basalt-space-lg border-b border-basalt-border">
           <NavigationItem href="/dashboard">Dashboard</NavigationItem>
           <NavigationItem href="/settings">Settings</NavigationItem>
           <NavigationItem href="https://docs.hexly.ai">External Docs</NavigationItem>
         </nav>
-        <div className="p-4">
+        <div className="p-basalt-space-lg">
           <Routes>
             <Route path="/dashboard" element={<DashboardPage />} />
             <Route path="/settings" element={<SettingsPage />} />
@@ -1749,7 +1728,7 @@ export function UserPreferencesForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit} onReset={handleReset} className="space-y-4 max-w-sm">
+    <form onSubmit={handleSubmit} onReset={handleReset} className="space-y-basalt-space-lg max-w-sm">
       <Field label="Username" hint="Public profile handle">
         <Input name="username" defaultValue="johndoe" required />
       </Field>
@@ -1764,7 +1743,7 @@ export function UserPreferencesForm() {
         </div>
       )}
 
-      <div className="flex gap-2">
+      <div className="flex gap-basalt-space-lg">
         <Button type="reset" variant="secondary">
           Reset
         </Button>
@@ -1776,3 +1755,111 @@ export function UserPreferencesForm() {
   );
 }
 ```
+
+### Confirmation focus after responsive replacement
+
+`ConfirmDialog.onCloseAutoFocus` receives the same cancelable event as `AlertDialogContent.onCloseAutoFocus`. It runs after the close focus trap releases. Call `event.preventDefault()` and focus the currently mounted action when a responsive layout replaced the original opener. Without prevention, ConfirmDialog restores the connected explicit trigger or captured opener as usual. Do not race that lifecycle with a close-state effect or timeout.
+
+```tsx excerpt:confirmation-focus-replacement
+<ConfirmDialog
+  open={confirmOpen}
+  onOpenChange={setConfirmOpen}
+  title="Remove item?"
+  description="This action cannot be undone."
+  onConfirm={removeItem}
+  onCloseAutoFocus={(event) => {
+    event.preventDefault();
+    currentActionRef.current?.focus();
+  }}
+/>
+```
+
+## Agent feedback
+
+`Thinking`, `ApprovalCard`, and `ToolChips` are granular component imports under `@nocoo/basalt/components/`. They use Basalt tokens, existing disclosures and controls, and reduced-motion-safe entrance/expand animations. The package's `models/agent-feedback.ts` defines data semantics; private `viewmodels/` own UI state, timers, answer validation and submission locking. Views import the ViewModels; ViewModels never import Views or DOM modules. Private model/ViewModel paths are not public package exports.
+
+- `Thinking` takes stable step IDs, caller-owned statuses (`pending`, `running`, `complete`, `error`), labels and optional plain-text details. `variant` is `steps`, `reasoning`, `search` or `coding`. Disclosure can be controlled or use `defaultOpen`. It never fabricates progress or exposes hidden model reasoning; display only trace data that the application intentionally supplies.
+- `ApprovalCard` takes questions with stable question/option IDs, `single`/`multiple` choice, optional custom text and `required` (true by default). Single choice may move forward after 240ms; the last question always requires explicit Submit. Optional questions may be skipped. `onSubmit` receives a sanitized answer snapshot and may return a promise; pending submission locks controls, failure keeps answers for retry, and no work is executed by the library. Remount with a new React key when replacing an approval request. Backend authorization and validation remain mandatory.
+- `ToolChips` takes caller-owned tool steps and optional file diffs. It summarizes completion, expands individual plain-text outputs, and opens file previews in accessible popovers. It does not execute commands or parse arbitrary HTML.
+- Catalog examples simulate progress in application ViewModels. Their copyable snippets include those demo ViewModels, rather than importing private catalog paths.
+
+### Dense controls and moving list highlights
+
+Button (including icon buttons), Input, SelectTrigger, InputGroup and their composing controls default to 34px high. Explicit `sm`/`lg` sizes remain available; InputArea remains multiline. Compact application headers retain their 44px minimum touch targets. ApprovalCard uses 16px horizontal / 12px vertical panel padding and compact option spacing; ToolChips uses 14px row text and 16px glyphs with 34px reference rows.
+
+Select, DropdownMenu, ContextMenuPanel, MenuBarContent, Combobox/Autocomplete, MultiSelect, ApprovalCard and ToolChips use one list-local hover layer. Its private DOM adapter batches reads in requestAnimationFrame, measures only when row/focus/selection/size changes, and updates CSS variables without a React state render. Position animates with transform, not top/left layout; reduced motion removes transitions. Disabled/hidden rows are excluded, keyboard focus takes priority, and observers/listeners are released with the mounted list. CommandPalette's list shrinks with its viewport so all rows remain reachable even inside short frames.
+
+Loader uses eight perimeter cells with an empty center, moving clockwise continuously. Label, shimmer and delayed elapsed-time controls are unchanged.
+
+## Dimension tokens
+
+Basalt geometry no longer depends on a host's Tailwind `--spacing`. Both CSS entrypoints expose the same `--basalt-space-*` and `--basalt-size-*` variables. Override semantic roles on a shared ancestor; portaled overlays inherit from their portal ancestor, so application-wide settings belong on `:root`. Theme switches do not reset dimensions.
+
+| Role | Token | Default |
+| --- | --- | --- |
+| Small / default / large control | `--basalt-size-control-sm`, `--basalt-size-control`, `--basalt-size-control-lg` | 28 / 34 / 40px |
+| Compact / standard / display icon | `--basalt-size-icon-sm`, `--basalt-size-icon`, `--basalt-size-icon-lg` | 12 / 14 / 16px |
+| Nested action | `--basalt-size-control-inset` | 28px |
+| Minimum touch target | `--basalt-size-touch` | 44px |
+| Menu option | `--basalt-size-menu-row`, `--basalt-space-menu-inset`, `--basalt-space-menu-x`, `--basalt-space-menu-y` | 34px / 8px / 8px / 6px |
+| Card padding | `--basalt-space-card-sm`, `--basalt-space-card`, `--basalt-space-card-lg`, `--basalt-space-card-xl` | 12 / 16 / 24 / 32px; default 16px |
+| Layout spacing | `--basalt-space-layout-sm`, `--basalt-space-layout`, `--basalt-space-layout-lg`, `--basalt-space-layout-xl` | 12 / 16 / 24 / 32px; grids 16px, page sections 24px |
+| Field label gap | `--basalt-space-field-gap` | 8px |
+| Textarea minimum height | `--basalt-size-textarea-sm`, `--basalt-size-textarea`, `--basalt-size-textarea-lg` | 64 / 80 / 96px |
+| Table row / horizontal / vertical inset | `--basalt-size-table-row`, `--basalt-space-table-x`, `--basalt-space-table-y` | 36 / 8 / 6px |
+
+Defaults use rem and unitless line-height, preserving browser font-size preferences. [DESIGN.md](DESIGN.md) defines compact 2/4/6/8px control spacing, separate 12/16/24/32px card and layout spacing, and natural 22/34/46px inline/action/banner categories. The size tokens describe reference geometry, not fixed text-control heights. Use the semantic spacing role for the boundary being laid out; numbered geometry tokens are not padding alternatives. LayerCard accepts `padding="sm|md|lg|xl"` for unstructured content; Grid accepts `gap="sm|md|lg|xl"`. Both default to `md`; 32px `xl` is opt-in. ContentIsland owns a 16px mobile, 24px tablet, and 32px horizontal / 24px vertical desktop inset. Examples must use component size props rather than fixed-height overrides. Textareas, avatars and panels retain content-specific geometry.
+
+### Compact record tables
+
+DataTable uses 13px single-line content, 36px minimum rows, tokenized horizontal/vertical insets and a native horizontally scrollable region. A column's `width` is also its minimum width; the browser must not squeeze names/dates into accidental multi-line rows. Use `column.wrap: true` for actual prose fields, or an explicitly sized inner `truncate` element with a title for long record names and URLs. `maxHeight` bounds the existing scroll region, with sticky opaque headers that stay inside it. Sorting uses a fixed 12px icon slot and retains `aria-sort`; row selection uses the shared Checkbox rather than an unstyled native checkbox. Rich `headerContent` composes icons and labels without changing the plain accessible sort name. Empty/loading/error content remains readable and wraps independently of data-cell defaults.
+
+### Recommendations
+
+`RecommendationCard` (`components/recommendation-card`) accepts stable-ID options with a label, plain-text description, confidence (`high`, `review`, `none`) and optional action label/disabled state. Alternatives expand with the existing disclosure and shared hover layer; choosing one changes the recommendation, never executes it. `onAccept` runs only after the explicit action. Promise rejection preserves the selection and shows retry feedback; pending acceptance locks controls and successful acceptance cannot be repeated for the current option. Remount with a new key for a new recommendation request. The application must perform authorization and persist any real action. Private model/ViewModel modules own confidence metadata and state, without View or DOM imports.
+
+### Retrieved context
+
+`ContextCards` (`components/context-cards`) displays caller-owned chunks with stable IDs, title, text, character count and source metadata. The optional total count cannot be smaller than the displayed count; omitted character counts are computed from Unicode code points. Sources without a destination remain non-interactive labels. Only clean root-relative or HTTP(S) URLs without credentials become external links; other schemes and ambiguous URLs are shown as labels, never executed. Loading, empty and retryable error states are explicit. Entrance staggering is CSS-only, capped at 240ms and disabled for reduced motion; no timer delays access to the source links. Source retrieval and authorization belong to the app.
+
+### Proposed tabular changes
+
+`DiffTable` (`components/diff-table`) renders caller-owned text/number rows marked `add`, `remove` or `unchanged`. Changed rows start included and can be toggled by clicking the row or its keyboard-operable Checkbox. Add/remove labels and glyphs carry the meaning independently of tint. `onApply` receives a detached snapshot of only selected changed rows; no data is mutated internally. Pending actions lock selection and duplicate submission; rejection preserves selection with retry feedback. Remount with a new key for a new proposal. Real writes, access checks and validation stay in the application.
+
+### Record numbering and identity
+
+Set `DataTable.rowNumbers` to show an additional `#` column. Numbers follow current sorted/filtered display order and continue from the resolved page offset, including server pagination. They never replace stable row IDs or selection keys. `AvatarInitials` on `components/avatar` reuses the circular Avatar surface with deterministic semantic colors and the first two word initials; `colorKey` keeps color stable across renames and `initials` supports application abbreviations. `size="sm"` is 24px for compact records. Keep the full name as its accessible label.
+
+## AI conversation primitives
+
+`ChatComposer` now uses the his.fm native `field-sizing: content` pattern: one line initially, a maximum of five line-heights plus token padding, then internal vertical scrolling. No per-keystroke JS height measurement is used. Enter sends, Shift+Enter inserts a newline, and IME composition (including keyCode 229) never submits. Controlled `value`/`onValueChange` keep thread-specific drafts application-owned; async `onSend` errors preserve the draft. Attachment metadata and file selection callbacks never upload files themselves. `PromptBar` composes the same composer with application-owned model, reasoning and web-search controls. Stop remains an explicit callback; no microphone permission is requested.
+
+`ChatMessage` provides user/assistant layout, trace/result slots, copy, feedback, edit and regenerate actions. `ChatMarkdown` uses the maintained `marked` lexer but renders React nodes, never raw HTML. It supports prose, lists, code, GFM tables and validated links. HTML is plain text; Markdown images become links rather than making unprompted remote requests. Business conversations, persistence, generation and approvals stay outside these views. The `marked` dependency is imported only by granular chat-content entrypoints, not the root barrel. Entity references are decoded with `entities` before link validation; code and raw HTML remain literal. `ChatMarkdown.streaming` reveals newly appended prose words with a short CSS blur/opacity animation. Existing words keep stable keys, no per-word timers are allocated, and reduced motion removes the effect. Copy confirmations belong to the exact copied content, so updated messages and code do not retain a stale success state.
+
+### Conversation workspace example
+
+The catalog `/chat` route composes these public controls in a session-only workspace. `src/models/chat.ts` owns the pure conversation reducer and deterministic response fixtures; `useChatViewModel` owns the cancellable simulation clock. Views own only DOM scrolling, focus and overlay presentation. Threads keep independent drafts, models, reasoning/search settings and attachment names. Switching threads stops the current reply. Edit/resend and regeneration replace the downstream transcript rather than duplicating user messages. Approval pauses the clock until an explicit decision; decline produces a read-only explanation. Message history, feedback and draft data disappear on reload.
+
+All model names, progress summaries, searches and tool outputs on this route are local examples, not real AI or hidden chain-of-thought. File selection validates a maximum of three image/text/PDF files of 10 MB each and retains metadata only: it never reads or uploads file contents. Diff acceptance and recommendation actions only prepare a follow-up draft. The library does not supply authentication, conversation persistence, model transport, voice recording or server authorization. Connect those through application ViewModels and validate every real tool action on the server.
+
+### Composite alignment
+
+Use one padding owner per boundary: `--basalt-space-panel-x/y` (16/12px) for composite card/header/body/footer sections, `--basalt-space-row-x/y/gap` (8/6/8px) for selectable rows, and `--basalt-space-content-gap` (8px) between related controls inside a composite. Page section gaps instead use `--basalt-space-layout-lg` (24px). `--basalt-space-row-content` derives the detail inset from row padding + a 16px icon slot + the row gap. Selectable action rows use the 22px `--basalt-line-row`, producing 34px single-line rows and growing by full lines when content wraps. Status icons occupy a first-line-height slot, not an arbitrary top margin. Body prose and code keep the 20px body line-height. Ordinary controls use 34px; inline message actions use the 34px `--basalt-size-action` target and 14px glyphs. Align visible glyphs with prose without removing their pointer target.
+
+Thinking and ToolChips share row padding; disclosures rotate only their own chevron, never content icons. Approval, recommendation, retrieved context and diff sections share panel insets rather than adding another padding layer. ChatComposer owns its field inset, not an outer painted/padded card; the application owns placement in the page. ChatMessage `sources` renders a compact disclosure beside actions and a flat source list, with the same validated URL policy as ContextCards. Use ContextCards only for actual retrieved text chunks, not as a citation footer. No additional remote images are loaded.
+
+The standalone build generates every Tailwind utility once in canonical order. Do not append handwritten copies of `.p-0`, `.bg-transparent` or other native utilities after generated axis/state rules: a later shorthand can silently erase semantic padding. Browser acceptance measures actual computed insets in both CSS entrypoints, under foreign host spacing and semantic overrides.
+
+Public Radio, Checkbox, Switch and SegmentControl group roots establish the scoped `.basalt-ui` reset. Fieldsets and legends have no browser-default padding/margin inside that boundary; standalone and Tailwind consumers must have identical group insets. Host form groups outside Basalt remain untouched.
+
+Native form legends do not participate in a fieldset's flex gap. Radio, Checkbox and Switch legends therefore own `margin-bottom: var(--basalt-space-field-gap)` (8px) independently of the group's row layout. Do not replace the semantic legend or add wrapper divs to simulate this spacing. Override the existing field-gap token when a different group density is required.
+
+### Code panels
+
+`CodeBlock` and `CodeHighlighted` share one compact code panel: optional `title`, a decorative `icon` (default file-code glyph, `null` to hide), `copyable` (true by default) and `lineNumbers` (false by default). Plain CodeBlock takes string children; CodeHighlighted takes `code` and reuses the lightweight built-in tokenizer. The root now forwards HTMLDivElement attributes and `className`; its inner named, keyboard-focusable pre owns scrolling. Do not pass rendered React children or assume the root is a pre. Use `copyable={false}` without a title for headerless output. Existing `max-h-*` classes constrain the panel while the source region scrolls; the header remains visible.
+
+For edge-attached content, use `attached` rather than overriding border, radius or padding classes. It removes the outer frame except the top separator and keeps code-owned insets. Do not wrap attached code in LayerCard.Body. The standard full-width disclosure is `Collapsible asChild` around a LayerCard, with `LayerCard.Header asChild` around CollapsibleTrigger and `CollapsibleContent unstyled` around a Body or self-inset code/table. Header owns the full hit target and aligned 16/12px insets; Collapsible owns only interaction and motion. See [container boundary ownership](DESIGN.md#container-boundary-ownership), also used by the catalog's navigation and example panels.
+
+Code panels contain horizontal overscroll only. Vertical wheel/touch scrolling chains to the page: natural-height examples do not trap it, and explicitly height-constrained panels hand it off at their top/bottom edge. No JavaScript wheel interception or axis conversion is used. Horizontal gestures and focused Left/Right arrow keys still scroll long source lines without moving the header.
+
+Panel insets use the shared 16/12px roles. Code content uses the shared small font token (.75rem, 12px reference) on a 20px line box; titles remain 13px and the copy target is 34px. Inline Code and Chat Markdown code spans use the same small font tier. Source lines retain empty and trailing lines, with horizontal scrolling rather than breaking tokens. The hidden, non-selectable line-number gutter uses CSS-generated text, so numbers never enter clipboard output or assistive reading. Copy uses the exact original source (including CRLF), prevents concurrent writes, reports permission/API failure and permits retry; feedback belongs to that source revision. No source text is interpreted as HTML or executed. Private model/ViewModel modules own tokenization and copy state; browser clipboard access remains in the View. Chat Markdown fences compose this same panel rather than maintaining a second toolbar implementation. This is not a language parser or a text-diff viewer.