@nocoo/basalt 2.1.7 → 2.2.0

package/ai/INTEGRATION.md

@@ -51,7 +51,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.
 
@@ -365,25 +365,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-3 md:pb-3">
+      <ContentIsland mobileSurface="edge-to-edge">
+        <div className="mx-auto max-w-prose px-4 py-3 md:p-0">{content}</div>
+      </ContentIsland>
+    </div>
+  </AppMain>
+</AppShell>
+```
+
+The wrapper intentionally has **no mobile `px-2` / `pb-2`**. 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`.
 
-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.
+**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.
+
+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,7 +415,7 @@ 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`
@@ -403,7 +427,7 @@ Do not wrap those regions in another full-viewport column. Do not set `h-screen`
 ### Expanded tree
 
 ```
-Sidebar                          ← collapsed={false}; owns 260px and h-screen
+Sidebar                          ← collapsed={false}; owns 260px and bounded height
 ├── SidebarHeader                ← h-14 px-3 already
 │   └── brand row                ← flex, items-center, justify-between, w-full
 │                                 (no extra horizontal padding)
@@ -579,9 +603,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.
+
+`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.
 
-`AppHeader` `leading` is the menu button on mobile only (`Button variant="ghost" size="icon" className="h-8 w-8"`).
+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.
 
 Local hook (not in the package):
 
@@ -619,12 +645,6 @@ export function AppFrame() {
     setMobileOpen(false);
   }, [location.pathname]);
 
-  useEffect(() => {
-    document.body.style.overflow = mobileOpen ? "hidden" : "";
-    return () => {
-      document.body.style.overflow = "";
-    };
-  }, [mobileOpen]);
 
   return (
     <AppShell>
@@ -674,7 +694,7 @@ 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
 
@@ -775,7 +795,7 @@ 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.
 
@@ -982,7 +1002,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
 
@@ -1774,3 +1794,21 @@ 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();
+  }}
+/>
+```

package/ai/RECIPES.md

@@ -1,6 +1,6 @@
 # Application recipes
 
-These complete modules, included in v2.1.0, use only public Basalt imports and React.
+These complete modules use only public Basalt imports and React. AppFrame, Login and Resources are available since v2.1.0; MobileLayout requires v2.2.0.
 
 Load exactly one CSS mode at the application entry: import `@nocoo/basalt/styles/standalone` for a build without Tailwind, or configure the Tailwind source scan and import `@nocoo/basalt/styles/tailwind` as described in INTEGRATION.md. In Next, import CSS in the root layout and import these modules through a `use client` boundary. Mount ThemeProvider once per application; the standalone recipes include their own root provider. Root pages should set body margin to zero.
 
@@ -159,3 +159,48 @@ export default function ResourcesRecipe() {
   </main></ThemeProvider>;
 }
 ```
+
+## Mobile layouts
+
+Use `responsive` for mobile root scrolling and desktop island scrolling; `document` keeps root scrolling at every width, while `workspace` remains bounded everywhere. Select this per layout, not by user-agent. Place the compact sticky header inside the edge-to-edge island for a single immersive row. Keep a normal PageHeader in a desktop-only wrapper when it adds context. The outer wrapper must not retain mobile `px-2 pb-2`; the island cannot remove its parent's spacing.
+
+This complete recipe compiles from the installed package. Supply content and actions from the application; there are no routing, article, account or network assumptions. The consumer owns a zero-margin body and viewport metadata (`width=device-width, initial-scale=1, viewport-fit=cover`). Do not lock body scrolling or add height/overflow constraints to intermediate wrappers. The shell handles safe areas; the sticky header paints the notch gap without charging the initial top inset twice. Bottom safe area follows the last content, not a fixed footer strip.
+
+```tsx compile:recipe-mobile-layout
+import { AppHeader } from "@nocoo/basalt/components/app-header";
+import { AppMain, AppShell, AppSkipLink } from "@nocoo/basalt/components/app-shell";
+import { Button } from "@nocoo/basalt/components/button";
+import { Popover, PopoverContent, PopoverTrigger } from "@nocoo/basalt/components/popover";
+import { ContentIsland } from "@nocoo/basalt/components/sidebar";
+import { ThemeProvider } from "@nocoo/basalt/providers/theme";
+
+export default function MobileLayoutRecipe() {
+  return <ThemeProvider><AppShell layout="responsive">
+    <AppSkipLink>Skip to content</AppSkipLink>
+    <AppMain>
+      <ContentIsland mobileSurface="edge-to-edge">
+        <AppHeader sticky density="compact" title="Field notes" actions={
+          <Popover><PopoverTrigger asChild><Button variant="ghost">Options</Button></PopoverTrigger>
+            <PopoverContent aria-label="Options"><p>Application-owned reading preferences.</p></PopoverContent>
+          </Popover>
+        } />
+        <article style={{ maxWidth: "65ch", marginInline: "auto", padding: "1rem", lineHeight: 1.7 }}>
+          {Array.from({ length: 24 }, (_, index) => <section key={index}>
+            <h2>Observation {index + 1}</h2>
+            <p>The shell leaves the document in charge on a narrow screen. Content grows naturally, the header stays reachable, and the final paragraph remains above the trailing safe area.</p>
+          </section>)}
+          <p>End of notes.</p>
+        </article>
+      </ContentIsland>
+    </AppMain>
+  </AppShell></ThemeProvider>;
+}
+```
+
+### List/detail and form boundaries
+
+- Full-page examples: [reader](https://basaltui.com/examples/reader), [list/detail](https://basaltui.com/examples/list-detail), [workspace/form](https://basaltui.com/examples/workspace). Open them outside another AppShell; do not nest viewport shells.
+- Use `ResponsiveMasterDetail` inside a `ContentIsland` with `className="md:overflow-hidden"`, and give the composition `className="md:h-full"`. Its desktop panes scroll independently; below 768px only the visible pane participates in document layout. The application owns selection. Built-in back navigation restores focus to the opening item, with a region fallback if it no longer exists.
+- Keep `mobileSurface="inset"` for regular forms. Use native labels, appropriate input types and at least 44px controls; 16px input text avoids the common small-text zoom problem without disabling user zoom. Browser scrolling brings focused fields into view; never reposition the viewport with innerHeight.
+- Modal `Sheet`/overlay `Sidebar` owns focus trapping, Escape, focus restoration and background scroll locking. Do not add a second manual body lock. An expanded Sidebar inside a Sheet stays bounded and owns the portal's safe-area padding once.
+- Automated Chromium/WebKit evidence covers geometry, document/pane scroll owners, resize, focus and overlays. Real iPhone Safari toolbar collapse, notch behavior during toolbar transitions, and software keyboard reachability require a physical-device check; desktop WebKit is not that proof.

package/ai/USAGE.md

@@ -1,6 +1,6 @@
 # Basalt AI & Machine Usage Guide
 
-This document describes how AI code assistants, automated agents, and developers can consume `@nocoo/basalt` (v2.1.7).
+This document describes how AI code assistants, automated agents, and developers can consume `@nocoo/basalt` (v2.2.0).
 
 ---
 
@@ -94,6 +94,6 @@ export function App() {
 
 ## 6. Application recipes and palette preferences
 
-Read [RECIPES.md](RECIPES.md) for complete AppFrame, Login, and Resources modules. Each module is compiled and exercised from the installed tarball in standalone, Tailwind, and Next.js consumers. These recipes keep authentication, routing, data and network requests in the application.
+Read [RECIPES.md](RECIPES.md) for complete AppFrame, Login, Resources, and MobileLayout modules. Each module is compiled and exercised from the installed tarball in standalone, Tailwind, and Next.js consumers. These recipes keep authentication, routing, data and network requests in the application.
 
 Read [INTEGRATION.md#accent-provider](INTEGRATION.md#accent-provider) for the twelve control accents, optional `paletteOverrides`, and the fixed five-color chart cycle matching the classic candy swatches with its existing gray retained. Check [COMPATIBILITY.md](COMPATIBILITY.md) before migrating old color indices or stored IDs. The catalog at https://basaltui.com/palette provides an application-owned editor with localStorage persistence.

package/ai/registry.json

@@ -1,6 +1,6 @@
 {
 	"packageName": "@nocoo/basalt",
-	"packageVersion": "2.1.7",
+	"packageVersion": "2.2.0",
 	"totalModules": 122,
 	"totalSymbols": 741,
 	"totalValues": 395,
@@ -7070,7 +7070,7 @@
 			"importPath": "@nocoo/basalt/components/app-header",
 			"subpath": "./components/app-header",
 			"sourceFile": "packages/basalt/src/components/app-header.tsx",
-			"sourceHash": "80acd367d8bdc9bf",
+			"sourceHash": "e03e115cf4b8f4a1",
 			"rootAvailable": false,
 			"maturity": "ready",
 			"kind": "framework-chrome",
@@ -7096,7 +7096,7 @@
 			"importPath": "@nocoo/basalt/components/app-shell",
 			"subpath": "./components/app-shell",
 			"sourceFile": "packages/basalt/src/components/app-shell.tsx",
-			"sourceHash": "f581b2af0175670b",
+			"sourceHash": "360ded256b2b5947",
 			"rootAvailable": false,
 			"maturity": "ready",
 			"kind": "framework-chrome",
@@ -8126,7 +8126,7 @@
 			"importPath": "@nocoo/basalt/components/button",
 			"subpath": "./components/button",
 			"sourceFile": "packages/basalt/src/components/button.tsx",
-			"sourceHash": "1b6293380c63e14c",
+			"sourceHash": "fd3e84a54d2f6f61",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"kind": "catalog-component",
@@ -10360,7 +10360,7 @@
 			"importPath": "@nocoo/basalt/components/confirm-dialog",
 			"subpath": "./components/confirm-dialog",
 			"sourceFile": "packages/basalt/src/components/confirm-dialog.tsx",
-			"sourceHash": "b184b69c8d5ee916",
+			"sourceHash": "cafdd27c6800d3cd",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"kind": "catalog-component",
@@ -10443,6 +10443,12 @@
 									"required": true,
 									"description": "Called when the dialog requests to open or close."
 								},
+								{
+									"name": "onCloseAutoFocus",
+									"type": "(event: Event) => void",
+									"required": false,
+									"description": "Runs after the close focus trap releases. Prevent default to focus a replacement control."
+								},
 								{
 									"name": "onConfirm",
 									"type": "() => void | Promise<void>",
@@ -10551,6 +10557,12 @@
 							"required": true,
 							"description": "Called when the dialog requests to open or close."
 						},
+						{
+							"name": "onCloseAutoFocus",
+							"type": "(event: Event) => void",
+							"required": false,
+							"description": "Runs after the close focus trap releases. Prevent default to focus a replacement control."
+						},
 						{
 							"name": "onConfirm",
 							"type": "() => void | Promise<void>",
@@ -20358,7 +20370,7 @@
 			"importPath": "@nocoo/basalt/components/responsive-master-detail",
 			"subpath": "./components/responsive-master-detail",
 			"sourceFile": "packages/basalt/src/components/responsive-master-detail.tsx",
-			"sourceHash": "c7e06934d2c2e706",
+			"sourceHash": "43d5629efcdfbbbf",
 			"rootAvailable": false,
 			"maturity": "ready",
 			"kind": "catalog-component",
@@ -21476,7 +21488,7 @@
 			"importPath": "@nocoo/basalt/components/sheet",
 			"subpath": "./components/sheet",
 			"sourceFile": "packages/basalt/src/components/sheet.tsx",
-			"sourceHash": "1fd48fe8aa7559fa",
+			"sourceHash": "49cf6f015335f773",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"kind": "catalog-component",
@@ -21940,7 +21952,7 @@
 			"importPath": "@nocoo/basalt/components/sidebar",
 			"subpath": "./components/sidebar",
 			"sourceFile": "packages/basalt/src/components/sidebar.tsx",
-			"sourceHash": "5ee61278f01f173c",
+			"sourceHash": "89fb8df61f17524a",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"kind": "catalog-component",
@@ -22366,7 +22378,15 @@
 						},
 						{
 							"name": "ContentIsland",
-							"props": []
+							"props": [
+								{
+									"name": "mobileSurface",
+									"type": "\"edge-to-edge\" | \"inset\"",
+									"required": false,
+									"default": "\"inset\"",
+									"description": "Mobile surface treatment; desktop remains an inset L1 island."
+								}
+							]
 						},
 						{
 							"name": "useSidebar()",
@@ -22633,7 +22653,15 @@
 				},
 				{
 					"name": "ContentIsland",
-					"props": []
+					"props": [
+						{
+							"name": "mobileSurface",
+							"type": "\"edge-to-edge\" | \"inset\"",
+							"required": false,
+							"default": "\"inset\"",
+							"description": "Mobile surface treatment; desktop remains an inset L1 island."
+						}
+					]
 				},
 				{
 					"name": "useSidebar()",
@@ -25878,7 +25906,7 @@
 			"importPath": "@nocoo/basalt/components/toggle",
 			"subpath": "./components/toggle",
 			"sourceFile": "packages/basalt/src/components/toggle.tsx",
-			"sourceHash": "632d36c606c7d7e0",
+			"sourceHash": "c507d31badda1b2d",
 			"rootAvailable": false,
 			"maturity": "ready",
 			"kind": "catalog-component",
@@ -26016,7 +26044,7 @@
 			"importPath": "@nocoo/basalt/components/toggle-group",
 			"subpath": "./components/toggle-group",
 			"sourceFile": "packages/basalt/src/components/toggle-group.tsx",
-			"sourceHash": "c25d112b708484f6",
+			"sourceHash": "d213fc765fff2b03",
 			"rootAvailable": false,
 			"maturity": "ready",
 			"kind": "catalog-component",
@@ -26482,7 +26510,7 @@
 			"importPath": "@nocoo/basalt/components/tooltip",
 			"subpath": "./components/tooltip",
 			"sourceFile": "packages/basalt/src/components/tooltip.tsx",
-			"sourceHash": "62accdd15ce33330",
+			"sourceHash": "ad4e479b428769f8",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"kind": "catalog-component",
@@ -27636,7 +27664,7 @@
 			"exportName": "Button",
 			"importPath": "@nocoo/basalt/components/button",
 			"sourceFile": "packages/basalt/src/components/button.tsx",
-			"sourceHash": "1b6293380c63e14c",
+			"sourceHash": "fd3e84a54d2f6f61",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"packageDoc": "ai/registry.json#button",
@@ -27695,7 +27723,7 @@
 			"exportName": "LinkButton",
 			"importPath": "@nocoo/basalt/components/button",
 			"sourceFile": "packages/basalt/src/components/button.tsx",
-			"sourceHash": "1b6293380c63e14c",
+			"sourceHash": "fd3e84a54d2f6f61",
 			"rootAvailable": false,
 			"maturity": "ready",
 			"packageDoc": "ai/registry.json#link-button",
@@ -27915,7 +27943,7 @@
 			"exportName": "Tooltip",
 			"importPath": "@nocoo/basalt/components/tooltip",
 			"sourceFile": "packages/basalt/src/components/tooltip.tsx",
-			"sourceHash": "62accdd15ce33330",
+			"sourceHash": "ad4e479b428769f8",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"packageDoc": "ai/registry.json#tooltip",
@@ -29385,7 +29413,7 @@
 			"exportName": "Toggle",
 			"importPath": "@nocoo/basalt/components/toggle",
 			"sourceFile": "packages/basalt/src/components/toggle.tsx",
-			"sourceHash": "632d36c606c7d7e0",
+			"sourceHash": "c507d31badda1b2d",
 			"rootAvailable": false,
 			"maturity": "ready",
 			"packageDoc": "ai/registry.json#toggle",
@@ -29443,7 +29471,7 @@
 			"exportName": "ToggleGroup",
 			"importPath": "@nocoo/basalt/components/toggle-group",
 			"sourceFile": "packages/basalt/src/components/toggle-group.tsx",
-			"sourceHash": "c25d112b708484f6",
+			"sourceHash": "d213fc765fff2b03",
 			"rootAvailable": false,
 			"maturity": "ready",
 			"packageDoc": "ai/registry.json#toggle-group",
@@ -31228,7 +31256,7 @@
 			"exportName": "ConfirmDialog",
 			"importPath": "@nocoo/basalt/components/confirm-dialog",
 			"sourceFile": "packages/basalt/src/components/confirm-dialog.tsx",
-			"sourceHash": "b184b69c8d5ee916",
+			"sourceHash": "cafdd27c6800d3cd",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"packageDoc": "ai/registry.json#confirm-dialog",
@@ -31248,6 +31276,12 @@
 							"required": true,
 							"description": "Called when the dialog requests to open or close."
 						},
+						{
+							"name": "onCloseAutoFocus",
+							"type": "(event: Event) => void",
+							"required": false,
+							"description": "Runs after the close focus trap releases. Prevent default to focus a replacement control."
+						},
 						{
 							"name": "onConfirm",
 							"type": "() => void | Promise<void>",
@@ -32374,7 +32408,7 @@
 			"exportName": "Sheet",
 			"importPath": "@nocoo/basalt/components/sheet",
 			"sourceFile": "packages/basalt/src/components/sheet.tsx",
-			"sourceHash": "1fd48fe8aa7559fa",
+			"sourceHash": "49cf6f015335f773",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"packageDoc": "ai/registry.json#sheet",
@@ -33904,7 +33938,7 @@
 			"exportName": "Sidebar",
 			"importPath": "@nocoo/basalt/components/sidebar",
 			"sourceFile": "packages/basalt/src/components/sidebar.tsx",
-			"sourceHash": "5ee61278f01f173c",
+			"sourceHash": "89fb8df61f17524a",
 			"rootAvailable": true,
 			"maturity": "ready",
 			"packageDoc": "ai/registry.json#sidebar",
@@ -34099,7 +34133,15 @@
 				},
 				{
 					"name": "ContentIsland",
-					"props": []
+					"props": [
+						{
+							"name": "mobileSurface",
+							"type": "\"edge-to-edge\" | \"inset\"",
+							"required": false,
+							"default": "\"inset\"",
+							"description": "Mobile surface treatment; desktop remains an inset L1 island."
+						}
+					]
 				},
 				{
 					"name": "useSidebar()",
@@ -35821,7 +35863,7 @@
 			"exportName": "ResponsiveMasterDetail",
 			"importPath": "@nocoo/basalt/components/responsive-master-detail",
 			"sourceFile": "packages/basalt/src/components/responsive-master-detail.tsx",
-			"sourceHash": "c7e06934d2c2e706",
+			"sourceHash": "43d5629efcdfbbbf",
 			"rootAvailable": false,
 			"maturity": "ready",
 			"packageDoc": "ai/registry.json#responsive-master-detail",