@satinhq/kit 0.1.0-beta.2 → 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

@@ -6,17 +6,18 @@ import { IgnoresSafeAreaContext } from './context.js';
 import { createContext, useContext, useLayoutEffect, useRef, useMemo, useCallback, } from 'react';
 /** Whether an enclosing SafeAreaInset already owns the bottom boundary (keyboard, home indicator). */
 export const BottomInsetContext = createContext({ consumed: false });
-/** SwiftUI's system spacing between content and a safe-area inset (`spacing: nil`). */
+/** Default spacing between content and a safe-area inset. */
 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')
@@ -41,7 +42,7 @@ function BottomInset({ content, spacing, children, ...props }) {
         geometry.publish((parent.geometry?.value ?? 0) + measuredHeight.current + spacing + extension);
     }, [geometry, parent.geometry, spacing]);
     // `IgnoresSafeArea regions="keyboard"` around the inset: the boundary stays above the home
-    // indicator while the keyboard is up, as SwiftUI's `ignoresSafeArea(.keyboard)`.
+    // indicator while the keyboard is up `ignoresSafeArea(.keyboard)`.
     const keyboardIgnored = useContext(IgnoresSafeAreaContext).keyboard;
     const inset = useRef(null);
     const accessory = useRef(null);
@@ -112,7 +113,7 @@ function BottomInset({ content, spacing, children, ...props }) {
  *   native adds it to the scroll view's adjusted inset (iOS 27 native reference `inset-top`: 116 + 44.33 + 8);
  * - leading/trailing: the accessory is a column of the safe area's height and the content's frame
  *   gives up its width plus `spacing` (`inset-leading`: strip 0–60, cards from 68).
- * A background drawn by the accessory's root view reaches the screen's top edge, as a SwiftUI
+ * A background drawn by the accessory's root view reaches the screen's top edge. An accessory
  * `background` ignores the safe area by default (`inset-top`: the yellow fills 0–160.33).
  */
 function EdgeInset({ edge, content, spacing, children, ...props }) {

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

@@ -3,7 +3,7 @@ import { startsScreenContent } from '../scroll/screenGeometry.js';
 import { SafeAreaInset } from './SafeAreaInset.js';
 import { ContentMarginsContext, IgnoresSafeAreaContext, NO_LENGTHS, SafeAreaPaddingContext, } from './context.js';
 import { useContext, useLayoutEffect, useRef } from 'react';
-/** SwiftUI's default padding amount (`padding()` and `safeAreaPadding()` with no length). */
+/** Default padding used when no length is supplied. */
 const SYSTEM_PADDING_PX = 16;
 function edgesOf(set) {
     const edges = new Set();
@@ -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,18 +59,20 @@ 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);
     const container = regions === 'keyboard' ? new Set() : set;
     const keyboard = regions !== 'container' && set.has('bottom');
     const element = useRef(null);
-    // Only a view that reaches the safe edge extends past it, as SwiftUI's does.
+    // Only a view that reaches the safe edge extends past it.
     useLayoutEffect(() => {
         const node = element.current;
         if (!node)

package/dist/safe-area/useSafeAreaMetrics.js

@@ -60,7 +60,7 @@ function readInsets(element) {
     };
 }
 // Native home-indicator boundaries, in points. Phone: Foundation 00, iPhone 17 Pro Max,
-// iOS 27 portrait. Pad: a SwiftUI .safeAreaInset(edge: .bottom) composer on iPad Pro
+// iOS 27 portrait. Pad: a .safeAreaInset(edge: .bottom) composer on iPad Pro
 // 12.9-inch, iPadOS 27, which keeps 25 pt in portrait and in landscape.
 const PHONE_HOME_INDICATOR_INSET = 34;
 const PAD_HOME_INDICATOR_INSET = 25;
@@ -72,7 +72,7 @@ const PAD_FITTED_STATUS_BAND = 32;
  * With viewport-fit auto/contain, the system takes the status band outside the viewport,
  * but content still reaches the screen bottom and every env() inset reads zero. Without
  * this boundary, bottom bars and composers sit in the home-indicator band: on iPad a
- * composer sat 25 pt lower than the same SwiftUI layout, its trailing edge in the corner
+ * composer sat 25 pt lower than the same layout, its trailing edge in the corner
  * that carries the window-resize grabber. Device identity comes from the shared
  * resolver, never from screen dimensions.
  */

package/dist/scroll/ScrollSurface.d.ts

@@ -28,15 +28,15 @@ export type ScrollSurfaceProps = Omit<HTMLAttributes<HTMLDivElement>, 'id'> & Sc
     /**
      * Whether this is the screen's primary scroll view, which gets the large title, the bar's
      * content inset and the scroll edge effect. By default the outermost vertical scroll view at the
-     * top of the screen's content is primary, as in SwiftUI.
+     * top of the screen's content is primary.
      */
     primary?: boolean;
-    /** SwiftUI `scrollEdgeEffectHidden(_:for: .top)`: no scroll edge effect under the bar. */
+    /** Hide the scroll edge effect under the top bar. */
     scrollEdgeEffectHidden?: ScrollEdgeEffectHidden;
     /** Soft/automatic select the existing top treatment. Hard is explicitly unsupported. */
     scrollEdgeEffectStyle?: ScrollEdgeEffectStyleSelection;
 }>;
-/** SwiftUI `ScrollView`: a named scroll surface whose position is retained by the framework. */
+/** A named scroll surface whose position is retained by the framework. */
 export declare const ScrollSurface: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "id"> & Readonly<{
     defaultScrollAnchor?: 'top' | 'bottom';
     maintainVisibleContentPosition?: boolean;
@@ -52,10 +52,10 @@ export declare const ScrollSurface: import("react").ForwardRefExoticComponent<Om
     /**
      * Whether this is the screen's primary scroll view, which gets the large title, the bar's
      * content inset and the scroll edge effect. By default the outermost vertical scroll view at the
-     * top of the screen's content is primary, as in SwiftUI.
+     * top of the screen's content is primary.
      */
     primary?: boolean;
-    /** SwiftUI `scrollEdgeEffectHidden(_:for: .top)`: no scroll edge effect under the bar. */
+    /** Hide the scroll edge effect under the top bar. */
     scrollEdgeEffectHidden?: ScrollEdgeEffectHidden;
     /** Soft/automatic select the existing top treatment. Hard is explicitly unsupported. */
     scrollEdgeEffectStyle?: ScrollEdgeEffectStyleSelection;

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. */
@@ -27,7 +28,7 @@ export const ListNavigationContext = createContext(undefined);
 /** A scroll view's content is inside its safe area: modifiers above it stop at its frame. */
 const NO_IGNORED = { container: new Set(), keyboard: false };
 const cssLength = (value) => typeof value === 'number' ? `${value}px` : (value ?? '0px');
-/** SwiftUI `ScrollView`: a named scroll surface whose position is retained by the framework. */
+/** A named scroll surface whose position is retained by the framework. */
 export const ScrollSurface = forwardRef(function ScrollSurface({ axis = 'vertical', chain = false, children, primary, scrollEdgeEffectHidden, scrollEdgeEffectStyle, refreshable, scrollDismissesKeyboard = 'never', id, defaultScrollAnchor, maintainVisibleContentPosition, scrollPosition, onScrollGeometryChange, ...props }, forwardedRef) {
     const refresh = refreshable;
     if (axis !== 'vertical' &&
@@ -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/position.js

@@ -84,7 +84,7 @@ export function createScrollPositionController(surface, content, targets, option
         pending = undefined;
         const targetTop = top(target);
         const height = target.getBoundingClientRect().height;
-        // Targets align within the content insets, as SwiftUI's do: a screen's primary scroll view
+        // Targets align within the content insets, within the owned scroll region: a screen's primary scroll view
         // reaches under the bar and the bottom bars, and its padding is the bar's and the bottom inset
         // chain's content inset. Other scroll views only clear the enclosing bottom insets' accessories.
         const style = getComputedStyle(surface);

package/dist/scroll/screenGeometry.d.ts

@@ -1,5 +1,5 @@
 /**
- * Whether a scroll view starts its screen's content, as a SwiftUI scroll view that reaches the
+ * Whether a scroll view starts its screen's content, as a scroll view that reaches the
  * top safe-area edge does. Only such a scroll view extends under the navigation bar and takes the
  * bar's content inset; one placed below other content keeps its own frame, like a Form under a
  * header in a VStack.

package/dist/scroll/screenGeometry.js

@@ -11,7 +11,7 @@ function occupiesFlow(element) {
     return position !== 'absolute' && position !== 'fixed';
 }
 /**
- * Whether a scroll view starts its screen's content, as a SwiftUI scroll view that reaches the
+ * Whether a scroll view starts its screen's content, as a scroll view that reaches the
  * top safe-area edge does. Only such a scroll view extends under the navigation bar and takes the
  * bar's content inset; one placed below other content keeps its own frame, like a Form under a
  * header in a VStack.

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);