@satinhq/kit 0.1.0-beta.3 → 0.1.0-beta.4

package/dist/root/mountSatin.js

@@ -1,8 +1,8 @@
 import { flushSync } from 'react-dom';
 import { createRoot } from 'react-dom/client';
-import { launchErrorLayer } from '../app/launchScreen.js';
+import { prelaunchController, showLaunchFailure } from '../app/launchScreenRuntime.js';
 /** Mount once from the app entry point, after resolving its initial screen.
- * The first commit runs in this task so installed WebKit cannot defer it behind
+ * After managed styles load, the first commit runs synchronously so WebKit cannot defer it behind
  * its launch presentation. Later updates retain React's normal scheduling.
  * Do not call from a component or an effect, or suspend the initial screen.
  */
@@ -17,9 +17,29 @@ export function mountSatin(container, content, options) {
                 reportError(error);
         },
     });
-    performance.mark('satin-mount-start');
-    flushSync(() => root.render(content));
-    performance.mark('satin-mount-committed');
+    let disposed = false;
+    const unmount = root.unmount.bind(root);
+    root.unmount = () => {
+        disposed = true;
+        unmount();
+    };
+    const commit = () => {
+        if (disposed)
+            return;
+        performance.mark('satin-mount-start');
+        flushSync(() => root.render(content));
+        performance.mark('satin-mount-committed');
+    };
+    // A glass renderer cannot measure or present an unstyled React tree. The
+    // independent head environment owns this wait, including any load failure.
+    if (document.querySelector('link[data-satin-style]')) {
+        void prelaunchController().stylesReady().then(commit, error => {
+            if (!disposed)
+                showLaunchFailure(error instanceof Error ? error.message : String(error));
+        });
+    }
+    else
+        commit();
     return root;
 }
 /** An uncaught render or effect error unmounts the whole app. Without this the launch cover
@@ -27,34 +47,5 @@ export function mountSatin(container, content, options) {
  * above the launch cover, with the same presentation as a failed launch. */
 export function showAppFailure(error) {
     performance.mark('satin-app-failed');
-    document.querySelector('[data-satin-app-failure]')?.remove();
-    const panel = document.createElement('div');
-    panel.dataset.satinRole = 'chrome';
-    panel.dataset.satinLaunchError = 'true';
-    panel.dataset.satinAppFailure = 'true';
-    panel.setAttribute('role', 'alert');
-    panel.style.zIndex = String(launchErrorLayer);
-    const message = document.createElement('div');
-    message.className = 'satin-launch-error-message';
-    const title = document.createElement('h1');
-    title.textContent = 'App Failed to Start';
-    const detail = document.createElement('pre');
-    detail.style.whiteSpace = 'pre-wrap';
-    detail.style.overflowWrap = 'anywhere';
-    detail.textContent = error instanceof Error ? error.message : String(error);
-    const reload = document.createElement('button');
-    reload.type = 'button';
-    reload.textContent = 'Reload';
-    reload.addEventListener('click', () => window.location.reload());
-    message.append(title, detail, reload);
-    const icon = document.querySelector('#satin-launch-screen .satin-launch-icon img');
-    if (icon?.src) {
-        const image = document.createElement('img');
-        image.className = 'satin-launch-error-icon';
-        image.src = icon.src;
-        image.alt = '';
-        panel.append(image);
-    }
-    panel.append(message);
-    document.body.append(panel);
+    showLaunchFailure(error instanceof Error ? error.message : String(error), 'App Failed to Start');
 }

package/dist/root/runtimeContext.d.ts

@@ -22,5 +22,6 @@ export declare function useSatinLayoutRuntime(): Omit<SatinRuntime, 'metrics'> &
 export declare function useSatinRuntime(): SatinRuntime;
 /** Classes follow the layout viewport; keyboard occlusion and zoom do not select panes. */
 export declare function useLayoutClass(): LayoutClass;
-/** Register app-managed unsaved state while it exists. Native inputs are checked automatically. */
+/** Tells Satin the app has unsaved work while `unsaved` is true, so a pending app update waits
+ * instead of reloading over it. Edits in text fields are detected without this hook. */
 export declare function useUnsavedChanges(unsaved: boolean): void;

package/dist/root/runtimeContext.js

@@ -19,7 +19,8 @@ export function useSatinRuntime() {
 export function useLayoutClass() {
     return useSatinLayoutRuntime().layoutClass;
 }
-/** Register app-managed unsaved state while it exists. Native inputs are checked automatically. */
+/** Tells Satin the app has unsaved work while `unsaved` is true, so a pending app update waits
+ * instead of reloading over it. Edits in text fields are detected without this hook. */
 export function useUnsavedChanges(unsaved) {
     const { registerUnsavedChanges } = useSatinLayoutRuntime();
     useEffect(() => {

package/dist/safe-area/Overlay.d.ts

@@ -1,9 +1,10 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
 import type { ContentAlignment } from '../content/content.js';
-/** `overlay(alignment:content:)`: children determine the frame; content respects its safe area. */
+/** The layered `content` and its alignment. The children set the frame. */
 export type OverlayProps = Omit<HTMLAttributes<HTMLDivElement>, 'content'> & Readonly<{
     alignment?: ContentAlignment;
     content: ReactNode;
 }>;
-/** An overlay in SafeAreaInset shares its reduced safe area and keyboard carrier with the composer. */
+/** Layers `content` over its children without changing their frame. Inside a `SafeAreaInset`, the
+ * overlay keeps to the reduced safe area and moves with the keyboard, like the composer. */
 export declare function Overlay({ alignment, content, children, ...props }: OverlayProps): import("react").JSX.Element;

package/dist/safe-area/Overlay.js

@@ -4,7 +4,8 @@ import { BottomInsetContext } from './SafeAreaInset.js';
 // Overlay content is already inside the parent's reduced safe area. Its descendants consume
 // only their own local insets and inherit the parent's keyboard transform.
 const CONTENT_SCOPE = { consumed: true };
-/** An overlay in SafeAreaInset shares its reduced safe area and keyboard carrier with the composer. */
+/** Layers `content` over its children without changing their frame. Inside a `SafeAreaInset`, the
+ * overlay keeps to the reduced safe area and moves with the keyboard, like the composer. */
 export function Overlay({ alignment = 'center', content, children, ...props }) {
     const { geometry, consumed } = useContext(BottomInsetContext);
     const layer = useRef(null);

package/dist/safe-area/SafeAreaInset.d.ts

@@ -5,21 +5,25 @@ export declare const BottomInsetContext: import("react").Context<{
     consumed: boolean;
     geometry?: ReturnType<typeof createBottomInsetGeometry>;
 }>;
-/** `VerticalEdge`/`HorizontalEdge`: `leading` and `trailing` follow the layout direction. */
+/** The edge a `SafeAreaInset` accessory sits on. `leading` and `trailing` follow the layout
+ * direction. */
 export type SafeAreaInsetEdge = 'top' | 'bottom' | 'leading' | 'trailing';
 /** The edge, the accessory (`content`) and its spacing; `children` is the content it insets. */
 export type SafeAreaInsetProps = Omit<HTMLAttributes<HTMLDivElement>, 'content'> & Readonly<{
     edge: SafeAreaInsetEdge;
     content: ReactNode;
+    /** Room between the content and the accessory, in points. Defaults to the system spacing,
+     * 8 pt. */
     spacing?: number;
 }>;
 /**
- * `safeAreaInset(edge:spacing:content:)`. The accessory takes room from the content's safe
- * area on its edge; a scroll view inside still spans the whole frame and scrolls under it.
+ * Pins an accessory, such as a composer or a filter bar, to one edge of its content. The
+ * accessory takes room from the content's safe area on its edge; a scroll view inside still
+ * spans the whole frame and scrolls under it.
  *
- * Bottom: content can scroll under the accessory; its terminal anchor clears it.
- * The accessory's height reaches the content's scroll inset in the same frame it changes (CSS
- * `--satin-inset-accessory-height`, written by its resize observer), so a composer that grows by
- * a line keeps the newest message above it with no frame between.
+ * At the bottom, content scrolls under the accessory and its last item stays clear of it. When
+ * the accessory resizes, the scroll inset changes in the same frame (through
+ * `--satin-inset-accessory-height`), so a composer that grows by a line keeps the newest message
+ * in view.
  */
 export declare function SafeAreaInset({ edge, content, spacing, children, ...props }: SafeAreaInsetProps): import("react").JSX.Element;

package/dist/safe-area/SafeAreaInset.js

@@ -10,13 +10,14 @@ export const BottomInsetContext = createContext({ consumed: false });
 const SYSTEM_INSET_SPACING_PX = 8;
 const ACCESSORY_INSET_SCOPE = { consumed: true };
 /**
- * `safeAreaInset(edge:spacing:content:)`. The accessory takes room from the content's safe
- * area on its edge; a scroll view inside still spans the whole frame and scrolls under it.
+ * Pins an accessory, such as a composer or a filter bar, to one edge of its content. The
+ * accessory takes room from the content's safe area on its edge; a scroll view inside still
+ * spans the whole frame and scrolls under it.
  *
- * Bottom: content can scroll under the accessory; its terminal anchor clears it.
- * The accessory's height reaches the content's scroll inset in the same frame it changes (CSS
- * `--satin-inset-accessory-height`, written by its resize observer), so a composer that grows by
- * a line keeps the newest message above it with no frame between.
+ * At the bottom, content scrolls under the accessory and its last item stays clear of it. When
+ * the accessory resizes, the scroll inset changes in the same frame (through
+ * `--satin-inset-accessory-height`), so a composer that grows by a line keeps the newest message
+ * in view.
  */
 export function SafeAreaInset({ edge, content, spacing = SYSTEM_INSET_SPACING_PX, children, ...props }) {
     if (edge !== 'bottom')

package/dist/safe-area/context.d.ts

@@ -1,12 +1,12 @@
-/** `Edge`. `leading` and `trailing` follow the layout direction. */
+/** A logical edge. `leading` and `trailing` follow the layout direction. */
 export type Edge = 'top' | 'bottom' | 'leading' | 'trailing';
-/** `EdgeInsets` in points, by layout direction. */
+/** Optional lengths per logical edge, in points. */
 export type EdgeLengths = Readonly<Partial<Record<Edge, number>>>;
 export type Lengths = Readonly<Record<Edge, number>>;
 export declare const NO_LENGTHS: Lengths;
 /** Safe-area padding the enclosing modifiers add to the next scroll view's content, per edge. */
 export declare const SafeAreaPaddingContext: import("react").Context<Readonly<Record<Edge, number>>>;
-/** `contentMargins(for: .scrollContent)` in effect for every scroll view below, per edge. */
+/** The content margins in effect for every scroll view below, per edge. */
 export declare const ContentMarginsContext: import("react").Context<Readonly<Partial<Record<Edge, number>>>>;
 /** The safe-area regions and edges an enclosing `IgnoresSafeArea` gives up. */
 export declare const IgnoresSafeAreaContext: import("react").Context<{

package/dist/safe-area/context.js

@@ -2,7 +2,7 @@ import { createContext } from 'react';
 export const NO_LENGTHS = { top: 0, bottom: 0, leading: 0, trailing: 0 };
 /** Safe-area padding the enclosing modifiers add to the next scroll view's content, per edge. */
 export const SafeAreaPaddingContext = createContext(NO_LENGTHS);
-/** `contentMargins(for: .scrollContent)` in effect for every scroll view below, per edge. */
+/** The content margins in effect for every scroll view below, per edge. */
 export const ContentMarginsContext = createContext({});
 /** The safe-area regions and edges an enclosing `IgnoresSafeArea` gives up. */
 export const IgnoresSafeAreaContext = createContext({ container: new Set(), keyboard: false });

package/dist/safe-area/displayCorners.d.ts

@@ -15,7 +15,9 @@ export type DisplayCornerMetrics = Readonly<{
 export declare function resolveDisplayCornerMetrics(display: DisplayGeometry): DisplayCornerMetrics;
 /** Framework token for the screen containing this app. Display Zoom and unknown models fall back to zero. */
 export declare function readDisplayCornerMetrics(): DisplayCornerMetrics;
-/** Updates after rotation, window moves and DPR changes announced by a resize. */
+/** The corner radius of the device screen in points, or 0 when the model is unknown. It updates
+ * after rotation, window moves and pixel-ratio changes that fire a resize. */
 export declare function useDisplayCornerRadius(): number;
-/** Radius for a shape inset equally from a rounded container. Insets consume, never invert, corners. */
+/** The corner radius for a shape inset evenly inside a rounded container, so the two corners stay
+ * concentric. The result never goes below 0; a negative or non-finite argument throws. */
 export declare function concentricRadius(containerRadius: number, inset: number): number;

package/dist/safe-area/displayCorners.js

@@ -44,7 +44,8 @@ export function readDisplayCornerMetrics() {
         scale: window.devicePixelRatio,
     });
 }
-/** Updates after rotation, window moves and DPR changes announced by a resize. */
+/** The corner radius of the device screen in points, or 0 when the model is unknown. It updates
+ * after rotation, window moves and pixel-ratio changes that fire a resize. */
 export function useDisplayCornerRadius() {
     const [radius, setRadius] = useState(() => readDisplayCornerMetrics().radius);
     useLayoutEffect(() => {
@@ -59,7 +60,8 @@ export function useDisplayCornerRadius() {
     }, []);
     return radius;
 }
-/** Radius for a shape inset equally from a rounded container. Insets consume, never invert, corners. */
+/** The corner radius for a shape inset evenly inside a rounded container, so the two corners stay
+ * concentric. The result never goes below 0; a negative or non-finite argument throws. */
 export function concentricRadius(containerRadius, inset) {
     if (!Number.isFinite(containerRadius) ||
         containerRadius < 0 ||

package/dist/safe-area/modifiers.d.ts

@@ -4,22 +4,23 @@ import { type HTMLAttributes, type ReactNode } from 'react';
 export type { Edge, EdgeLengths } from './context.js';
 /** A logical edge, an axis pair or all edges. */
 export type EdgeSetMember = Edge | 'horizontal' | 'vertical' | 'all';
-/** `Edge.Set`: one member or several. */
+/** One edge group or a list of them. */
 export type EdgeSet = EdgeSetMember | readonly EdgeSetMember[];
-/** The content and standard DOM attributes of a layout modifier wrapper. */
+/** The children and plain div attributes every layout wrapper takes. */
 export type LayoutModifierProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & Readonly<{
     children?: ReactNode;
 }>;
 /** Which edges to pad, and by how much. */
 export type SafeAreaPaddingProps = LayoutModifierProps & Readonly<{
-    /** Edges to pad. Defaults to all edges, as `safeAreaPadding()`. */
+    /** Edges to pad. Defaults to all edges. */
     edges?: EdgeSet;
     /** Points. Defaults to the system padding, 16 pt. */
     length?: number;
-    /** `safeAreaPadding(_ insets: EdgeInsets)`; overrides `edges` and `length`. */
+    /** A length per edge. Overrides `edges` and `length`. */
     insets?: EdgeLengths;
 }>;
-/** Adds to the content safe area. Scroll views keep their frame and inset content; other content is padded. Nested padding adds up. */
+/** Grows the safe area of the content inside it. Scroll views keep their frame and inset their
+ * content; other content is padded. Nested padding adds up. */
 export declare function SafeAreaPadding({ edges, length, insets, children, ...props }: SafeAreaPaddingProps): import("react").JSX.Element;
 /** Which edges get a margin, how much, and whether it applies to content or indicators. */
 export type ContentMarginsProps = LayoutModifierProps & Readonly<{
@@ -27,26 +28,29 @@ export type ContentMarginsProps = LayoutModifierProps & Readonly<{
     /** Points. */
     length: number;
     /**
-     * `ContentMarginPlacement`. `scrollContent` (and `automatic`) margins the content;
+     * What the margin applies to. `scrollContent` (and `automatic`) margins the content;
      * `scrollIndicators` only moves the indicator, which Satin draws in the screen frame and does
      * not inset, so it has no effect yet.
      */
     placement?: 'automatic' | 'scrollContent' | 'scrollIndicators';
 }>;
-/** Sets margins for descendant scroll views. Lists use horizontal layout margins; the innermost value for each edge wins. */
+/** Sets content margins for every scroll view inside it. A `List` takes a horizontal margin as its
+ * layout margin. The innermost value for each edge wins. */
 export declare function ContentMargins({ edges, length, placement, children, ...props }: ContentMarginsProps): import("react").JSX.Element;
 /** A `SafeAreaInset` limited to the top or bottom edge, with no spacing. */
 export type SafeAreaBarProps = Omit<SafeAreaInsetProps, 'edge' | 'spacing'> & Readonly<{
     edge: 'top' | 'bottom';
 }>;
-/** Places a top or bottom safe-area inset with no spacing and its own scroll-edge material. */
+/** A bar on the top or bottom edge that content scrolls under. It is a `SafeAreaInset` with no
+ * spacing and its own scroll-edge blur. */
 export declare function SafeAreaBar({ edge, ...props }: SafeAreaBarProps): import("react").JSX.Element;
 /** Which safe-area regions and edges the content ignores. */
 export type IgnoresSafeAreaProps = LayoutModifierProps & Readonly<{
-    /** `SafeAreaRegions`. Defaults to `'all'`. */
+    /** `container` (the bars and screen edges), `keyboard`, or `all`, the default. */
     regions?: 'all' | 'container' | 'keyboard';
     /** Defaults to all edges. */
     edges?: EdgeSet;
 }>;
-/** Extends content through selected safe-area edges. Container edges and keyboard avoidance can be controlled independently. */
+/** Lets content extend through the safe area on the chosen edges, for full-bleed backgrounds and
+ * media. The container edges and keyboard avoidance can be ignored separately. */
 export declare function IgnoresSafeArea({ regions, edges, children, ...props }: IgnoresSafeAreaProps): import("react").JSX.Element;

package/dist/safe-area/modifiers.js

@@ -29,7 +29,8 @@ function lengthsOf(edges, length, insets) {
         trailing: set.has('trailing') ? amount : 0,
     };
 }
-/** Adds to the content safe area. Scroll views keep their frame and inset content; other content is padded. Nested padding adds up. */
+/** Grows the safe area of the content inside it. Scroll views keep their frame and inset their
+ * content; other content is padded. Nested padding adds up. */
 export function SafeAreaPadding({ edges, length, insets, children, ...props }) {
     const parent = useContext(SafeAreaPaddingContext);
     const own = lengthsOf(edges, length, insets);
@@ -47,7 +48,8 @@ export function SafeAreaPadding({ edges, length, insets, children, ...props }) {
             ['--satin-padding-trailing']: `${own.trailing}px`,
         }, "data-satin-safe-area-padding": "true", children: _jsx(SafeAreaPaddingContext, { value: total, children: children }) }));
 }
-/** Sets margins for descendant scroll views. Lists use horizontal layout margins; the innermost value for each edge wins. */
+/** Sets content margins for every scroll view inside it. A `List` takes a horizontal margin as its
+ * layout margin. The innermost value for each edge wins. */
 export function ContentMargins({ edges = 'all', length, placement = 'automatic', children, ...props }) {
     const parent = useContext(ContentMarginsContext);
     const set = edgesOf(edges);
@@ -57,11 +59,13 @@ export function ContentMargins({ edges = 'all', length, placement = 'automatic',
             margins[edge] = length;
     return (_jsx("div", { ...props, "data-satin-content-margins": "true", children: _jsx(ContentMarginsContext, { value: margins, children: children }) }));
 }
-/** Places a top or bottom safe-area inset with no spacing and its own scroll-edge material. */
+/** A bar on the top or bottom edge that content scrolls under. It is a `SafeAreaInset` with no
+ * spacing and its own scroll-edge blur. */
 export function SafeAreaBar({ edge, ...props }) {
     return _jsx(SafeAreaInset, { ...props, edge: edge, spacing: 0, "data-satin-safe-area-bar": edge });
 }
-/** Extends content through selected safe-area edges. Container edges and keyboard avoidance can be controlled independently. */
+/** Lets content extend through the safe area on the chosen edges, for full-bleed backgrounds and
+ * media. The container edges and keyboard avoidance can be ignored separately. */
 export function IgnoresSafeArea({ regions = 'all', edges = 'all', children, ...props }) {
     const parent = useContext(IgnoresSafeAreaContext);
     const set = edgesOf(edges);

package/dist/scroll/ScrollSurface.js

@@ -15,9 +15,10 @@ import { TabActivityContext, TabRegistrationContext } from '../tabs/context.js';
 import { SearchDrawer } from '../search/SearchDrawer.js';
 import { ContentAdmission } from '../image/ContentAdmission.js';
 import { SearchToolbarField } from '../search/SearchToolbarField.js';
+import { readDeviceIdiom } from '../layout/deviceIdiom.js';
 import { resolveSearchPlacement } from '../search/searchPlacement.js';
 import { Children, createContext, forwardRef, isValidElement, useCallback, useContext, useImperativeHandle, useLayoutEffect, useRef, useState, useSyncExternalStore, } from 'react';
-import { ScreenContext, SystemScrollRegistryContext, useScreenScrollRegistry, } from '../navigation/navigationContext.js';
+import { NavigationPaneContext, ScreenContext, SystemScrollRegistryContext, useScreenScrollRegistry, } from '../navigation/navigationContext.js';
 import { readScrollOffset } from './registry.js';
 import { installScrollPressOwnership } from './pressOwnership.js';
 /** Inside another scroll surface: never the screen's primary scroll view. */
@@ -151,8 +152,11 @@ export const ScrollSurface = forwardRef(function ScrollSurface({ axis = 'vertica
         ? (listNavigation?.searchable ?? chrome.searchable)
         : undefined;
     const tabbed = useContext(TabRegistrationContext) !== null;
+    const searchPane = useContext(NavigationPaneContext);
     const searchPlacement = searchable
         ? resolveSearchPlacement(searchable.placement, {
+            idiom: readDeviceIdiom(),
+            pane: searchPane,
             compact: chrome.horizontalSizeClass === 'compact',
             bottomBarItems: chrome.hasBottomBar === true,
             searchToolbarItem: chrome.searchToolbarItem !== undefined,

package/dist/scroll/ScrollTarget.d.ts

@@ -1,6 +1,6 @@
 import { type HTMLAttributes } from 'react';
 export declare const ScrollTargetContext: import("react").Context<((id: string, element: HTMLDivElement | null) => void) | null>;
-/** A stable identity in a vertical ScrollView's normal-flow target layout. */
+/** Marks content a vertical `ScrollView` can scroll to by `id`. */
 export declare function ScrollTarget({ id, ...props }: HTMLAttributes<HTMLDivElement> & {
     id: string;
 }): import("react").JSX.Element;

package/dist/scroll/ScrollTarget.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext } from 'react';
 export const ScrollTargetContext = createContext(null);
-/** A stable identity in a vertical ScrollView's normal-flow target layout. */
+/** Marks content a vertical `ScrollView` can scroll to by `id`. */
 export function ScrollTarget({ id, ...props }) {
     const register = useContext(ScrollTargetContext);
     if (!register)

package/dist/scroll/edgePolicy.d.ts

@@ -1,8 +1,8 @@
-/** `Edge`: a logical edge of a scroll view. */
+/** A logical edge of a scroll view. */
 export type ScrollEdge = 'top' | 'bottom' | 'leading' | 'trailing';
 /** One or more scroll edges, or all edges. */
 export type ScrollEdgeSelection = ScrollEdge | 'all' | readonly ScrollEdge[];
-/** `ScrollEdgeEffectStyle`: the requested edge material treatment. */
+/** The material under bars at a scroll view's edge: `soft`, `hard` or `automatic`. */
 export type ScrollEdgeEffectStyle = 'soft' | 'hard' | 'automatic';
 /** Whether to hide scroll edge material, optionally for specific edges. */
 export type ScrollEdgeEffectHidden = boolean | {

package/dist/scroll/position.d.ts

@@ -1,4 +1,4 @@
-/** `UnitPoint`: the vertical alignment of a scroll target. */
+/** Where a scroll target lines up in the viewport: `top`, `center` or `bottom`. */
 export type ScrollAnchor = 'top' | 'center' | 'bottom';
 /** Vertical scroll geometry: the current viewport and content offset in points. */
 export type VerticalScrollGeometry = Readonly<{
@@ -7,13 +7,15 @@ export type VerticalScrollGeometry = Readonly<{
     containerHeight: number;
     distanceToBottom: number;
 }>;
-/** `ScrollPosition`: a target identity and the callback that receives its changes. */
+/** A controlled scroll position: the id of the target in view, its anchor and the callback that
+ * receives changes. */
 export type ScrollPositionBinding = Readonly<{
     id: string | null;
     anchor?: ScrollAnchor;
     onChange(id: string | null): void;
 }>;
-/** A scroll target binding, anchor and geometry observation policy. */
+/** The scroll view's position options: where it starts, whether it keeps visible content in
+ * place, a controlled position and a geometry callback. */
 export type ScrollPositionOptions = Readonly<{
     defaultScrollAnchor?: 'top' | 'bottom';
     maintainVisibleContentPosition?: boolean;

package/dist/scroll/types.d.ts

@@ -6,7 +6,7 @@ export type ScrollOffset = Readonly<{
     y: number;
 }>;
 export type ScrollSnapshot = ReadonlyMap<string, ScrollOffset>;
-/** Options for restoring a named scroll surface to its top. */
+/** Options for `scrollToTop`: whether to animate. */
 export type ScrollToTopOptions = Readonly<{
     animated?: boolean;
 }>;

package/dist/search/PadSearchDrawer.d.ts

@@ -0,0 +1,7 @@
+import { type RefObject } from 'react';
+import type { Searchable } from './searchable.js';
+/** A column-owned field. Its host stays in this scroll surface, never a sibling pane. */
+export declare function PadSearchDrawer({ configuration, scroller, }: {
+    configuration: Searchable;
+    scroller: RefObject<HTMLDivElement | null>;
+}): import("react").JSX.Element;

package/dist/search/PadSearchDrawer.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { SearchToolbarField } from './SearchToolbarField.js';
+/** A column-owned field. Its host stays in this scroll surface, never a sibling pane. */
+export function PadSearchDrawer({ configuration, scroller, }) {
+    const [host, setHost] = useState(null);
+    return (_jsx("div", { ref: setHost, "data-satin-search-pad-drawer": "", "data-satin-search-toolbar-host": "", children: host && (_jsx(SearchToolbarField, { configuration: configuration, scroller: scroller, host: host, navigation: true, drawer: true })) }));
+}

package/dist/search/PadSearchPresentationContext.d.ts

@@ -0,0 +1,6 @@
+/** Internal coordination between a retained search destination and its owning tab bar. */
+export declare const PadSearchPresentationContext: import("react").Context<{
+    owner: string | null;
+    setOwner: (owner: string | null) => void;
+} | null>;
+export declare const PadSearchTabContext: import("react").Context<string | null>;

package/dist/search/PadSearchPresentationContext.js

@@ -0,0 +1,4 @@
+import { createContext } from 'react';
+/** Internal coordination between a retained search destination and its owning tab bar. */
+export const PadSearchPresentationContext = createContext(null);
+export const PadSearchTabContext = createContext(null);

package/dist/search/SearchDrawer.d.ts

@@ -10,7 +10,7 @@ import { type Searchable } from './searchable.js';
  * visual state of each part (FLIP), on the native springs (searchMotion.ts). A retarget mid-way
  * starts from where everything is on screen, keeping the field's velocity.
  */
-export declare function SearchDrawer({ configuration, scroller, }: {
+export declare function SearchDrawer(props: {
     configuration: Searchable;
     scroller: RefObject<HTMLDivElement | null>;
 }): import("react").JSX.Element;

package/dist/search/SearchDrawer.js

@@ -1,4 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { readDeviceIdiom } from '../layout/deviceIdiom.js';
+import { PadSearchDrawer } from './PadSearchDrawer.js';
 import { NavigationSearchRow, navigationSearchRowOf } from '../navigation/NavigationSearchRow.js';
 import { animateElement } from '../motion/animate.js';
 import { beginSearchBackdrop, endSearchBackdrop, refreshSearchBackdrop } from './searchBackdrop.js';
@@ -28,7 +30,10 @@ const TITLE_SELECTOR = ':scope > :is([data-satin-list-title], [data-satin-scroll
  * visual state of each part (FLIP), on the native springs (searchMotion.ts). A retarget mid-way
  * starts from where everything is on screen, keeping the field's velocity.
  */
-export function SearchDrawer({ configuration, scroller, }) {
+export function SearchDrawer(props) {
+    return readDeviceIdiom() === 'pad' ? (_jsx(PadSearchDrawer, { ...props })) : (_jsx(PhoneSearchDrawer, { ...props }));
+}
+function PhoneSearchDrawer({ configuration, scroller, }) {
     validateSearchPresentation(configuration);
     const liquid = useContext(MaterialEffectContext);
     const navigator = useContext(NavigatorContext);

package/dist/search/SearchSuggestionsPopover.d.ts

@@ -0,0 +1,6 @@
+import { type RefObject, type ReactNode } from 'react';
+/** Suggestions belong to their field, including when it lives in a split column. */
+export declare function SearchSuggestionsPopover({ anchor, children, }: {
+    anchor: RefObject<HTMLElement | null>;
+    children: ReactNode;
+}): import("react").ReactPortal | null;

package/dist/search/SearchSuggestionsPopover.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { GlassBackground } from '../glass/GlassEffect.js';
+import { useSafeAreaMetrics } from '../safe-area/useSafeAreaMetrics.js';
+import { useLayoutEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+/** Suggestions belong to their field, including when it lives in a split column. */
+export function SearchSuggestionsPopover({ anchor, children, }) {
+    const metrics = useSafeAreaMetrics();
+    const [frame, setFrame] = useState();
+    useLayoutEffect(() => {
+        const element = anchor.current;
+        if (!element)
+            return;
+        const update = () => {
+            const rect = element.getBoundingClientRect();
+            const next = { left: Math.max(8, rect.left - 10), top: rect.bottom + 6, width: rect.width };
+            setFrame(previous => previous &&
+                previous.left === next.left &&
+                previous.top === next.top &&
+                previous.width === next.width
+                ? previous
+                : next);
+        };
+        update();
+        const observer = new ResizeObserver(update);
+        observer.observe(element);
+        window.addEventListener('resize', update);
+        document.addEventListener('scroll', update, true);
+        return () => {
+            observer.disconnect();
+            window.removeEventListener('resize', update);
+            document.removeEventListener('scroll', update, true);
+        };
+    }, [anchor]);
+    if (!frame)
+        return null;
+    return createPortal(_jsxs("div", { "data-satin-search-popover": "", style: {
+            ...frame,
+            maxHeight: Math.max(0, metrics.visualViewport.offsetTop + metrics.visualViewport.height - frame.top - 8),
+            overflowY: 'auto',
+        }, role: "list", "aria-label": "Suggestions", onPointerDown: event => event.preventDefault(), children: [_jsx(GlassBackground, { shape: { kind: 'roundedRectangle', cornerRadius: 28 } }), children] }), document.body);
+}

package/dist/search/SearchToolbarField.d.ts

@@ -1,8 +1,9 @@
 import { type RefObject } from 'react';
 import type { Searchable } from './searchable.js';
-export declare function SearchToolbarField({ configuration, scroller, host, navigation, }: {
+export declare function SearchToolbarField({ configuration, scroller, host, navigation, drawer, }: {
     configuration: Searchable;
     scroller: RefObject<HTMLDivElement | null>;
     host: HTMLElement;
     navigation?: boolean;
+    drawer?: boolean;
 }): import("react").JSX.Element;