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

package/dist/public/navigationTransition.d.ts

@@ -2,8 +2,8 @@ import { type ReactNode } from 'react';
 import type { NamespaceID } from '../motion/matchedGeometry.js';
 declare const brand: unique symbol;
 /**
- * `NavigationTransition`: how a pushed screen arrives and leaves. Give one to `Screen`'s
- * `navigationTransition`.
+ * How a pushed screen arrives and leaves: `automatic` (a slide) or `zoom`. Give one to
+ * `Screen`'s `navigationTransition`.
  */
 export type NavigationTransition = Readonly<{
     [brand]: true;
@@ -22,7 +22,7 @@ export declare const NavigationTransition: Readonly<{
     automatic: NavigationTransition;
     zoom: (options: ZoomTransitionOptions) => NavigationTransition;
 }>;
-/** Props of `MatchedTransitionSource`. */
+/** The source's id and namespace, and the one element the screen zooms out of. */
 export type MatchedTransitionSourceProps = Readonly<{
     /** The id a `NavigationTransition.zoom` names as its `sourceID`. */
     id: string;
@@ -31,8 +31,8 @@ export type MatchedTransitionSourceProps = Readonly<{
     children: ReactNode;
 }>;
 /**
- * `matchedTransitionSource(id:in:)`: marks the view a zoom transition starts from and
- * returns to. A push zooms only while its source is on screen; otherwise it slides as usual.
+ * Marks the view a zoom transition starts from and returns to. A push zooms only while its
+ * source is on screen; otherwise it slides as usual.
  * @example
  * <MatchedTransitionSource id={album.id} in={albumZoom}>
  *   <Image src={album.artwork} alt="" />

package/dist/public/navigationTransition.js

@@ -13,8 +13,8 @@ export const NavigationTransition = Object.freeze({
     zoom: ({ sourceID, in: namespace }) => Object.freeze({ [brand]: true, kind: 'zoom', sourceID, namespace }),
 });
 /**
- * `matchedTransitionSource(id:in:)`: marks the view a zoom transition starts from and
- * returns to. A push zooms only while its source is on screen; otherwise it slides as usual.
+ * Marks the view a zoom transition starts from and returns to. A push zooms only while its
+ * source is on screen; otherwise it slides as usual.
  * @example
  * <MatchedTransitionSource id={album.id} in={albumZoom}>
  *   <Image src={album.artwork} alt="" />

package/dist/public/presentation.d.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 import type { PresentationDetent } from '../presentation/model.js';
-/** Sheet's presentation binding, title, detents and drag behaviour. */
+/** A sheet's presentation binding, title, detents and drag behaviour. Supplying `selection`
+ * requires `onSelectionChange`. */
 export type SheetProps = {
     isPresented: boolean;
     onPresentedChange(presented: boolean): void;
@@ -19,15 +20,15 @@ export type SheetProps = {
     onSelectionChange(detent: PresentationDetent): void;
 });
 /**
- * `sheet(isPresented:)`: a card over the current screen, with optional detents. It can
- * host its own `NavigationStack modal`. Keep `isPresented` in plain React state: presentations
- * start closed after a relaunch.
+ * A card that slides up over the current screen and can rest at several heights. It can host
+ * its own `NavigationStack modal`. Keep `isPresented` in plain React state: presentations start
+ * closed after a relaunch.
  *
  * @example
  * <Sheet isPresented={adding} onPresentedChange={setAdding} title="New Note">...</Sheet>
  */
 export declare function Sheet(props: SheetProps): import("react").JSX.Element;
-/** FullScreenCover's presentation binding and accessible title. */
+/** A full-screen cover's presentation binding and accessible title. */
 export type FullScreenCoverProps = {
     isPresented: boolean;
     onPresentedChange(presented: boolean): void;
@@ -35,6 +36,6 @@ export type FullScreenCoverProps = {
     onDismiss?(): void;
     children: ReactNode;
 };
-/** `fullScreenCover`: an opaque presentation over the whole screen, closed through its
- * binding or `useDismiss()`. */
+/** An opaque presentation that slides up over the whole screen. It has no interactive dismissal;
+ * close it through its binding or `useDismiss()`. */
 export declare function FullScreenCover(props: FullScreenCoverProps): import("react").JSX.Element;

package/dist/public/presentation.js

@@ -2,9 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { FullScreenCover as EngineFullScreenCover, Sheet as EngineSheet, } from '../presentation/Presentation.js';
 import { ModalPresentationContext } from './presentationContext.js';
 /**
- * `sheet(isPresented:)`: a card over the current screen, with optional detents. It can
- * host its own `NavigationStack modal`. Keep `isPresented` in plain React state: presentations
- * start closed after a relaunch.
+ * A card that slides up over the current screen and can rest at several heights. It can host
+ * its own `NavigationStack modal`. Keep `isPresented` in plain React state: presentations start
+ * closed after a relaunch.
  *
  * @example
  * <Sheet isPresented={adding} onPresentedChange={setAdding} title="New Note">...</Sheet>
@@ -14,8 +14,8 @@ export function Sheet(props) {
         throw new TypeError('Controlled sheet selection requires onSelectionChange.');
     return (_jsx(ModalPresentationContext, { value: true, children: _jsx(EngineSheet, { ...props }) }));
 }
-/** `fullScreenCover`: an opaque presentation over the whole screen, closed through its
- * binding or `useDismiss()`. */
+/** An opaque presentation that slides up over the whole screen. It has no interactive dismissal;
+ * close it through its binding or `useDismiss()`. */
 export function FullScreenCover(props) {
     return (_jsx(ModalPresentationContext, { value: true, children: _jsx(EngineFullScreenCover, { ...props }) }));
 }

package/dist/public/runtime.d.ts

@@ -83,13 +83,13 @@ export declare function NavigationStack<R extends Routes = RegisteredRoutes, D =
 export type NavigationSplitViewProps<D = RegisteredNavigation> = {
     tab?: TabId<D>;
 };
-/** `NavigationSplitView`: the declared root becomes the sidebar and pushes become the
- * retained detail stack. It collapses to a plain stack at compact width. A `NavigationStack` never
- * splits by itself. */
+/** Shows the declared root as a sidebar and pushes into a retained detail column. At compact
+ * width it collapses to a plain stack. A `NavigationStack` never splits by itself. */
 export declare function NavigationSplitView<D = RegisteredNavigation>(props: NavigationSplitViewProps<D>): import("react").JSX.Element;
 /** The typed parameter tuple accepted by push and replace. */
 export type NavigationArguments<P> = {} extends P ? [params?: P] : [params: P];
-/** The current stack's typed navigation actions. */
+/** The actions `useNavigation` returns: `push`, `replace`, `pop`, `popToRoot` and
+ * `showAcknowledgements`, typed against the routes. */
 export interface Navigation<R extends Routes> {
     /** Opens the built-in credit and bundled licenses. Returns false when opted out or while a back gesture owns navigation. */
     showAcknowledgements(): boolean;
@@ -124,11 +124,12 @@ export type TabViewProps<D = RegisteredNavigation> = {
 export type TabProps<D = RegisteredNavigation> = {
     id: TabId<D>;
 };
-/** Render one declared tab's content; identities and root stacks come from defineNavigation. */
+/** Renders one declared tab inside a `TabView`. Its id, label and root stack come from
+ * `defineNavigation`. */
 export declare function Tab<D = RegisteredNavigation>({ id }: TabProps<D>): import("react").JSX.Element;
 /**
- * `TabView`: renders the tabs from `defineNavigation`, each retaining its own stack, and
- * restores the selected tab with the scene. Pass `selection` and `onSelectionChange` to control it;
- * a controlled tab press only requests the change.
+ * Renders the tabs from `defineNavigation`. Each tab keeps its own stack, and the selected tab is
+ * restored with the scene. Pass `selection` and `onSelectionChange` to control it; a controlled
+ * tab press only requests the change.
  */
 export declare function TabView<D = RegisteredNavigation>(props: TabViewProps<D>): import("react").JSX.Element;

package/dist/public/runtime.js

@@ -121,9 +121,8 @@ export function NavigationStack(props) {
         throw new Error('Primary roots belong in defineNavigation, not JSX');
     return props.modal ? _jsx(ModalStack, { ...props }) : _jsx(PrimaryStack, { tab: props.tab });
 }
-/** `NavigationSplitView`: the declared root becomes the sidebar and pushes become the
- * retained detail stack. It collapses to a plain stack at compact width. A `NavigationStack` never
- * splits by itself. */
+/** Shows the declared root as a sidebar and pushes into a retained detail column. At compact
+ * width it collapses to a plain stack. A `NavigationStack` never splits by itself. */
 export function NavigationSplitView(props) {
     if ('root' in props || 'params' in props || 'modal' in props)
         throw new Error('NavigationSplitView uses a declared primary sidebar root');
@@ -206,7 +205,8 @@ export function useNavigation() {
         };
     }, [navigator, routes, app]);
 }
-/** Render one declared tab's content; identities and root stacks come from defineNavigation. */
+/** Renders one declared tab inside a `TabView`. Its id, label and root stack come from
+ * `defineNavigation`. */
 export function Tab({ id }) {
     return _jsx(DeclaredTab, { id: id });
 }
@@ -219,9 +219,9 @@ function DeclaredTab({ id }) {
     return (_jsx(PrimaryTabContext, { value: id, children: Content ? _jsx(Content, {}) : _jsx(PrimaryStack, {}) }));
 }
 /**
- * `TabView`: renders the tabs from `defineNavigation`, each retaining its own stack, and
- * restores the selected tab with the scene. Pass `selection` and `onSelectionChange` to control it;
- * a controlled tab press only requests the change.
+ * Renders the tabs from `defineNavigation`. Each tab keeps its own stack, and the selected tab is
+ * restored with the scene. Pass `selection` and `onSelectionChange` to control it; a controlled
+ * tab press only requests the change.
  */
 export function TabView(props) {
     return _jsx(DeclaredTabView, { ...props });

package/dist/public/scroll.d.ts

@@ -4,14 +4,15 @@ import type { TaskAction } from '../tasks/useTask.js';
 import type { ScrollAnchor, ScrollPositionBinding, VerticalScrollGeometry } from '../scroll/position.js';
 import type { ScrollEdgeEffectHidden, ScrollEdgeEffectStyleSelection } from '../scroll/edgePolicy.js';
 import type { ScrollOffset, ScrollToTopOptions } from '../scroll/types.js';
-/** The current offset and imperative positioning of a scroll view. */
+/** A scroll view's ref handle: its current offset, `scrollTo` a target and `scrollToTop`. */
 export interface ScrollViewHandle {
     readonly offset: ScrollOffset;
     /** Position a vertical ScrollTarget. Horizontal target positioning is unsupported. */
     scrollTo(id: string, anchor?: ScrollAnchor): boolean;
     scrollToTop(options?: ScrollToTopOptions): void;
 }
-/** Scroll policy. Target positioning, refresh and scalar geometry are vertical-only. */
+/** A scroll view's id, axis, refresh action, keyboard dismissal, edge material and position
+ * options. Targets, refresh and geometry work only on the vertical axis. */
 export type ScrollViewProps = Omit<HTMLAttributes<HTMLDivElement>, 'id'> & {
     id: string;
     chain?: boolean;
@@ -34,5 +35,7 @@ export type ScrollViewProps = Omit<HTMLAttributes<HTMLDivElement>, 'id'> & {
     scrollPosition?: never;
     onScrollGeometryChange?: never;
 });
-/** A scroll surface with framework-owned restoration and native scrolling. */
+/** A scrolling region, vertical by default. Inside a screen its `id` keys scroll restoration, so
+ * keep it stable. `refreshable` adds pull to refresh, and a ref handle scrolls to a
+ * `ScrollTarget`. */
 export declare const ScrollView: import("react").ForwardRefExoticComponent<ScrollViewProps & import("react").RefAttributes<ScrollViewHandle>>;

package/dist/public/scroll.js

@@ -1,7 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from 'react';
 import { ScrollSurface } from '../scroll/ScrollSurface.js';
-/** A scroll surface with framework-owned restoration and native scrolling. */
+/** A scrolling region, vertical by default. Inside a screen its `id` keys scroll restoration, so
+ * keep it stable. `refreshable` adds pull to refresh, and a ref handle scrolls to a
+ * `ScrollTarget`. */
 export const ScrollView = forwardRef(function ScrollView(props, ref) {
     return _jsx(ScrollSurface, { ...props, ref: ref });
 });

package/dist/public/structure.d.ts

@@ -11,14 +11,14 @@ export type StackDeclaration<R extends Routes> = {
         params: RouteProps<R, K>;
     });
 }[keyof R['definitions'] & string];
-/** The tab declaration contract used by public app declarations. */
+/** One tab in `defineNavigation`: its id, label, symbol or icon, and the root of its stack. */
 export type TabDeclaration<R extends Routes> = StackDeclaration<R> & {
     /** The tab's identity: typed by `TabId`, used by `TabView selection` and restoration. */
     id: string;
     label: string;
     icon?: ReactNode;
     symbol?: SymbolName;
-    /** `Tab(role: .search)`: the separated search tab. */
+    /** `search` marks the search tab, drawn apart from the other tabs. */
     role?: 'search';
     /** Wraps the tab's stack, for per-tab providers. Render `<NavigationStack />` inside it. */
     content?: ComponentType;

package/dist/public/toolbar.d.ts

@@ -4,7 +4,8 @@ import type { ToolbarSlot } from './screenChrome.js';
 export declare const BottomBarRegistrationContext: import("react").Context<(() => () => void) | null>;
 /** A `DefaultToolbarItem kind="search"` reports the element it holds in the bottom bar. */
 export declare const SearchToolbarItemContext: import("react").Context<((element: HTMLElement | null) => void) | null>;
-/** The supported toolbar placement names. */
+/** A toolbar item's placement and content. `automatic` lets the bar choose; `bottomBar` puts it
+ * in the bottom toolbar. */
 export type ToolbarItemProps = {
     placement: 'subtitle' | 'largeTitle' | 'largeSubtitle' | 'principal' | 'topBarLeading' | 'topBarTrailing' | 'primaryAction' | 'confirmationAction' | 'cancellationAction' | 'automatic' | 'bottomBar';
     children?: ReactNode;
@@ -12,26 +13,29 @@ export type ToolbarItemProps = {
 export declare const ToolbarContext: import("react").Context<"group" | boolean>;
 export declare const ToolbarConfirmationContext: import("react").Context<boolean>;
 export declare const ToolbarSlotsContext: import("react").Context<Partial<Record<ToolbarSlot, HTMLDivElement | null>>>;
-/** Places one navigation or bottom-bar item. Adjacent actions share a glass capsule; ToolbarSpacer separates groups. */
+/** Places one item in the navigation bar or the bottom toolbar. Adjacent actions share a glass
+ * capsule; a `ToolbarSpacer` separates groups. */
 export declare function ToolbarItem({ children, placement }: ToolbarItemProps): import("react").ReactPortal | null;
-/** Which system item to place, and where. */
+/** Which system item to place, and where. Only `search` exists. */
 export type DefaultToolbarItemProps = {
-    /** `DefaultToolbarItem(kind:)`. Only `search` is drawn. */
+    /** The system item. Only `search` is drawn. */
     kind: 'search';
     placement?: 'bottomBar' | 'automatic';
 };
-/** Places the screen search field among bottom-bar items. Requires Screen searchable. */
+/** Places the screen's search field among its bottom toolbar items. The screen must be
+ * `searchable`. */
 export declare function DefaultToolbarItem({ kind }: DefaultToolbarItemProps): import("react").ReactPortal | null;
 /** The spacer's sizing and placement. */
 export type ToolbarSpacerProps = {
-    /** `SpacerSizing`: `fixed` separates two items' glass by the standard 12 pt gap;
-     * `flexible` (the default) takes the free space of the bar, like `ToolbarSpacer()`. */
+    /** `fixed` separates two items' glass by the standard 12 pt gap; `flexible`, the default,
+     * takes the free space of the bar. */
     sizing?: 'fixed' | 'flexible';
     placement?: ToolbarItemProps['placement'];
 };
-/** `ToolbarSpacer(_:placement:)`. Consecutive items of one placement share one glass
- * capsule; a spacer between them splits it. Place it directly in `toolbar`, next to the items. */
+/** Splits toolbar items into separate glass capsules. Consecutive items of one placement share
+ * one capsule; a spacer between them splits it. Place it directly in `toolbar`, next to the
+ * items. */
 export declare function ToolbarSpacer({ sizing, placement, }: ToolbarSpacerProps): import("react").JSX.Element | null;
-/** `ToolbarItemGroup`: its items render as consecutive `ToolbarItem`s of the placement,
- * which share one glass capsule (iOS 26+ draws a group and adjacent items identically). */
+/** Groups several items under one placement. They render as consecutive `ToolbarItem`s and share
+ * one glass capsule. */
 export declare function ToolbarItemGroup({ children, placement }: ToolbarItemProps): import("react").JSX.Element;

package/dist/public/toolbar.js

@@ -1,4 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { readDeviceIdiom } from '../layout/deviceIdiom.js';
 import { Children, createContext, isValidElement, useContext, useLayoutEffect, useState, } from 'react';
 import { createPortal } from 'react-dom';
 import { ToolbarMaterialContext } from '../glass/toolbarMaterialContext.js';
@@ -24,7 +25,8 @@ const toolbarPlacement = {
     bottomBar: 'bottom',
 };
 export const ToolbarSlotsContext = createContext({});
-/** Places one navigation or bottom-bar item. Adjacent actions share a glass capsule; ToolbarSpacer separates groups. */
+/** Places one item in the navigation bar or the bottom toolbar. Adjacent actions share a glass
+ * capsule; a `ToolbarSpacer` separates groups. */
 export function ToolbarItem({ children, placement }) {
     const slots = useContext(ToolbarSlotsContext);
     const registerBottomBar = useContext(BottomBarRegistrationContext);
@@ -40,11 +42,13 @@ export function ToolbarItem({ children, placement }) {
         ? createPortal(_jsx("div", { "data-satin-toolbar-item": spacer ? 'spacer' : 'item', children: _jsx(ToolbarMaterialContext, { value: !['subtitle', 'largeTitle', 'largeSubtitle'].includes(slot), children: _jsx(ToolbarContext, { value: !['subtitle', 'largeTitle', 'largeSubtitle'].includes(slot), children: _jsx(ToolbarConfirmationContext, { value: placement === 'confirmationAction', children: children }) }) }) }), destination)
         : null;
 }
-/** Places the screen search field among bottom-bar items. Requires Screen searchable. */
+/** Places the screen's search field among its bottom toolbar items. The screen must be
+ * `searchable`. */
 export function DefaultToolbarItem({ kind }) {
     const slots = useContext(ToolbarSlotsContext);
     const report = useContext(SearchToolbarItemContext);
-    const destination = slots.bottom;
+    // iPad search is owned by the navigation column's trailing slot.
+    const destination = readDeviceIdiom() === 'pad' ? undefined : slots.bottom;
     const [element, setElement] = useState(null);
     useLayoutEffect(() => {
         report?.(element);
@@ -54,8 +58,9 @@ export function DefaultToolbarItem({ kind }) {
         ? createPortal(_jsx("div", { ref: setElement, "data-satin-toolbar-item": "search", "data-satin-search-toolbar-host": "" }), destination)
         : null;
 }
-/** `ToolbarSpacer(_:placement:)`. Consecutive items of one placement share one glass
- * capsule; a spacer between them splits it. Place it directly in `toolbar`, next to the items. */
+/** Splits toolbar items into separate glass capsules. Consecutive items of one placement share
+ * one capsule; a spacer between them splits it. Place it directly in `toolbar`, next to the
+ * items. */
 export function ToolbarSpacer({ sizing = 'flexible', placement = 'automatic', }) {
     const slots = useContext(ToolbarSlotsContext);
     const inItem = useContext(ToolbarContext) !== false;
@@ -66,8 +71,8 @@ export function ToolbarSpacer({ sizing = 'flexible', placement = 'automatic', })
     const destination = slots[slot] ?? (slot === 'topBarLeading' ? slots.leading : undefined);
     return destination ? createPortal(spacer, destination) : null;
 }
-/** `ToolbarItemGroup`: its items render as consecutive `ToolbarItem`s of the placement,
- * which share one glass capsule (iOS 26+ draws a group and adjacent items identically). */
+/** Groups several items under one placement. They render as consecutive `ToolbarItem`s and share
+ * one glass capsule. */
 export function ToolbarItemGroup({ children, placement }) {
     // gives confirmation actions separate capsules, even inside a group.
     if (placement === 'confirmationAction')

package/dist/reachability/model.d.ts

@@ -1,10 +1,10 @@
-/** The result of the app server reachability probe. */
+/** Whether the app server answered: `reachable`, `server-unreachable` or `device-offline`. */
 export type ReachabilityStatus = 'device-offline' | 'server-unreachable' | 'reachable';
 /** The server probe result, including an unknown initial state. */
 export type ReachabilityStateStatus = ReachabilityStatus | 'unknown';
 /** Whether a destination remains usable without the app server. */
 export type ReachabilityRoutePolicy = 'local-first' | 'requires-server';
-/** The framework connectivity presentation to show for a failed probe. */
+/** How Satin shows a failed probe: a `banner`, a `full-screen` offline view, or `none`. */
 export type ReachabilitySurface = 'banner' | 'full-screen' | 'none';
 /** The endpoint and deadlines used to probe the app server. */
 export interface ReachabilityProbeConfig {
@@ -66,7 +66,7 @@ export interface ReachabilityPresentation {
     readonly reason: Exclude<ReachabilityStatus, 'reachable'>;
     readonly surface: Exclude<ReachabilitySurface, 'none'>;
 }
-/** The connectivity state of an app that does not require an app server. */
+/** The reachability state of an app that needs no app server. Its status is always `local`. */
 export interface LocalReachabilityState {
     readonly connectivity: 'local';
     readonly status: 'local';
@@ -82,6 +82,7 @@ export interface ServerReachabilityState {
     readonly route: string;
     readonly status: ReachabilityStateStatus;
 }
+/** The full reachability state: local for apps without a server, or the server probe state. */
 export type ReachabilityState = LocalReachabilityState | ServerReachabilityState;
 export interface ReachabilityReduction {
     readonly commands: readonly ReachabilityCommand[];

package/dist/reachability/react.d.ts

@@ -1,5 +1,7 @@
 import { type ComponentType, type PropsWithChildren } from 'react';
 import type { ReachabilityProfile, ReachabilitySurface } from './model.js';
+/** What the offline view shows: why the server is unavailable, how it is presented, and the
+ * recheck and back actions. */
 export interface OfflinePresentationProps {
     readonly reason: 'device-offline' | 'server-unreachable';
     readonly surface: Exclude<ReachabilitySurface, 'none'>;
@@ -12,7 +14,8 @@ export declare function ReachabilityProvider({ profile, offlinePresentation, chi
     profile: ReachabilityProfile;
     offlinePresentation?: ComponentType<OfflinePresentationProps>;
 }>): import("react").JSX.Element;
-/** The server status and visible offline presentation, with fetch and retry helpers. */
+/** The app server's status and the offline view currently shown, with `fetch` and `recheck`
+ * helpers that feed the status. */
 export declare function useReachability(): {
     recheck: () => void;
     reportFetchOutcome: (outcome: 'response' | 'network-failure' | 'aborted') => void;

package/dist/reachability/react.js

@@ -37,7 +37,8 @@ function useReachabilityController() {
         fetch: controller.fetch,
     };
 }
-/** The server status and visible offline presentation, with fetch and retry helpers. */
+/** The app server's status and the offline view currently shown, with `fetch` and `recheck`
+ * helpers that feed the status. */
 export function useReachability() {
     const { state, ...commands } = useReachabilityController();
     return {

package/dist/root/SatinRoot.d.ts

@@ -15,11 +15,11 @@ export type SatinRootProps = PropsWithChildren<Omit<HTMLAttributes<HTMLDivElemen
     /** Receives every renderer failure, including failures after launch. Release builds switch failed glass to the fallback material. */
     onGlassError?: (error: GlassError) => void;
 }>;
-/** A content-role wrapper's children and plain div attributes. */
+/** The wrapped content and plain div attributes. */
 export type SelectableProps = PropsWithChildren<HTMLAttributes<HTMLDivElement>>;
 /** Re-enters app-chrome policy inside a Selectable region. */
 export declare function Chrome({ children, ...props }: SelectableProps): import("react").JSX.Element;
-/** `textSelection(.enabled)`: restores text selection and system callouts for
- * user-authored content, which app chrome otherwise suppresses. */
+/** Lets the user select and copy the text inside it. App chrome turns text selection off
+ * everywhere else, so wrap user-authored content such as notes or messages. */
 export declare function Selectable({ children, ...props }: SelectableProps): import("react").JSX.Element;
 export declare function SatinRoot({ background: legacyBackground, app: suppliedApp, offlinePresentation, onAppShellReady, children, className, glassDisplacement, onGlassError, style, ...props }: SatinRootProps): import("react").JSX.Element;

package/dist/root/SatinRoot.js

@@ -1,15 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { MediaPlayerRoot } from '../media/react.js';
 import { useDisplayCornerRadius } from '../safe-area/displayCorners.js';
-import { retryFailedInstallation } from '../app/earlyWorker.js';
 import { installStatusBand } from '../app/statusBand.js';
 import { windowControlsBackInset } from '../safe-area/windowChrome.js';
-import { automaticGlassFallbackAllowed } from '../glass/failurePolicy.js';
 import { installGlassErrorAlert } from '../glass/errorAlert.js';
 import { reportGlassError, subscribeGlassErrors } from '../glass/errors.js';
 import { installKeyboardAdapter } from '../keyboard/adapter.js';
-import { launchErrorLayer } from '../app/launchScreen.js';
-import { setLaunchScreen, setLaunchProgress, showAppliedUpdate, completeLaunchProgress, } from '../app/launchScreenRuntime.js';
+import { setLaunchScreen, showLaunchFailure, prelaunchController, setLaunchProgress, showAppliedUpdate, completeLaunchProgress, } from '../app/launchScreenRuntime.js';
 import { settingsChromeTokens } from '../settings/tokens.js';
 import { installViewportPolicy } from '../app/viewport.js';
 import { prepareOfflineBundle, prepareLaunchContent } from '../app/launch.js';
@@ -22,7 +19,7 @@ import { OrientationGuard } from '../app/OrientationGuard.js';
 import { getBuiltApp, useAppBackground, registerDefinedAppShell } from '../app/runtime.js';
 import { defineSatinApp } from '../app/definition.js';
 import { ReachabilityProvider } from '../reachability/react.js';
-import { createPortal, flushSync } from 'react-dom';
+import { flushSync } from 'react-dom';
 import { AdaptiveTabsContext } from '../layout/adaptiveTabsContext.js';
 import { createLayoutClassState, reduceLayoutClass } from '../layout/layoutClass.js';
 import { lazy, Suspense, useEffect, useCallback, useLayoutEffect, useMemo, useRef, useState, } from 'react';
@@ -133,8 +130,8 @@ function installDocumentPolicy(root, background, tint) {
 export function Chrome({ children, ...props }) {
     return (_jsx("div", { ...props, "data-satin-role": "chrome", children: children }));
 }
-/** `textSelection(.enabled)`: restores text selection and system callouts for
- * user-authored content, which app chrome otherwise suppresses. */
+/** Lets the user select and copy the text inside it. App chrome turns text selection off
+ * everywhere else, so wrap user-authored content such as notes or messages. */
 export function Selectable({ children, ...props }) {
     return (_jsx("div", { ...props, "data-satin-role": "content", children: children }));
 }
@@ -154,19 +151,15 @@ export function SatinRoot({ background: legacyBackground, app: suppliedApp, offl
         throw new Error('SatinRoot style.background is owned by the app definition.');
     }
     const [launch, setLaunch] = useState(app ? 'preparing' : 'ready');
-    const [preparationError, setPreparationError] = useState('Check your connection and try again.');
     const downloadActivity = useRef(0);
     const downloadedBytes = useRef(0);
-    const [launchAttempt, setLaunchAttempt] = useState(0);
+    const launchAttempt = 0;
     const [glassReady, setGlassReady] = useState(false);
     const [bundlePrepared, setBundlePrepared] = useState(import.meta.env.DEV || !app);
-    const [glassError, setGlassError] = useState(null);
     const [glassFailed, setGlassFailed] = useState(false);
     useLayoutEffect(() => {
         installGlassErrorAlert();
         return subscribeGlassErrors(error => {
-            if (!automaticGlassFallbackAllowed())
-                setGlassError(error);
             // A renderer failure owns its visible error alert, never the app's
             // content/launch state. In particular, loss during resume cannot blank it.
             setGlassFailed(true);
@@ -203,8 +196,9 @@ export function SatinRoot({ background: legacyBackground, app: suppliedApp, offl
     // appearance/context recovery must not restore the logo or hide its content.
     const presentationPending = Boolean(app) && launch !== 'ready';
     useLayoutEffect(() => {
-        setLaunchScreen(launch === 'preparing');
-    }, [launch]);
+        if (app && launch !== 'failed')
+            setLaunchScreen(launch === 'preparing');
+    }, [app, launch]);
     const [preparedAttempt, setPreparedAttempt] = useState(null);
     useLayoutEffect(() => {
         performance.mark('satin-first-react-commit');
@@ -245,6 +239,7 @@ export function SatinRoot({ background: legacyBackground, app: suppliedApp, offl
                             return ready;
                         }),
                     prepareLaunchContent(rootRef.current, contentPreparation.signal),
+                    prelaunchController().stylesReady(),
                 ]);
                 if (cancelled || !bundleReady)
                     return;
@@ -275,7 +270,7 @@ export function SatinRoot({ background: legacyBackground, app: suppliedApp, offl
             catch (error) {
                 if (!cancelled) {
                     performance.mark('satin-launch-preparation-failed');
-                    setPreparationError(error instanceof Error ? error.message : String(error));
+                    showLaunchFailure(error instanceof Error ? error.message : String(error));
                     setLaunch('failed');
                     console.error('Satin launch failed', error);
                 }
@@ -314,7 +309,7 @@ export function SatinRoot({ background: legacyBackground, app: suppliedApp, offl
         return armPreparationBudget(() => {
             const message = 'App preparation stopped making progress. Please try again.';
             performance.mark('satin-launch-preparation-timeout');
-            setPreparationError(message);
+            showLaunchFailure(message);
             setLaunch('failed');
             console.error('Satin launch preparation timed out after 30 seconds of visible idle time.');
         }, () => downloadActivity.current);
@@ -493,24 +488,5 @@ export function SatinRoot({ background: legacyBackground, app: suppliedApp, offl
             return;
         return startDevFidelityAssertions(initialHistoryLength.current);
     }, []);
-    return (_jsx(RuntimeContext, { value: runtime, children: _jsxs(MediaPlayerRoot, { onActivityChange: onMediaActivityChange, children: [_jsx("div", { ...props, ref: rootRef, className: className, "data-satin-role": "chrome", "data-satin-root": "true", "data-satin-launch": launch, "data-satin-presentation": presentationPending ? 'preparing' : 'ready', inert: launch !== 'ready' || presentationPending, "data-satin-layout-horizontal": nextLayout.layoutClass.horizontal, "data-satin-layout-vertical": nextLayout.layoutClass.vertical, style: geometryStyles, children: _jsx(AdaptiveTabsContext, { value: tabs, children: _jsx("div", { "data-satin-status-band-source": "scene", children: _jsxs(GlassMaterialRoot, { displacement: glassDisplacement, prepared: bundlePrepared, onLaunchReady: setGlassReady, children: [DeveloperMenu && app && launch === 'ready' ? (_jsx(Suspense, { fallback: null, children: _jsx(DeveloperMenu, {}) })) : null, app ? (_jsx(OrientationGuard, { app: app, width: metrics.safeFrame.width, height: metrics.safeFrame.height, children: _jsx(ReachabilityProvider, { profile: app, offlinePresentation: offlinePresentation, children: children }) })) : (children)] }) }) }) }), launch === 'failed'
-                    ? createPortal(_jsxs("div", { "data-satin-role": "chrome", "data-satin-launch-error": "true", "data-satin-glass-error": glassError ? true : undefined, role: "alert", style: { zIndex: launchErrorLayer }, children: [!glassError ? (_jsx("img", { className: "satin-launch-error-icon", src: document.querySelector('#satin-launch-screen .satin-launch-icon img')?.src ??
-                                    app?.launchScreen?.icon ??
-                                    app?.icons[0]?.src, alt: "" })) : null, _jsxs("div", { className: "satin-launch-error-message", children: [_jsx("h1", { children: glassError ? 'Glass Renderer Failed' : 'Unable to Open App' }), glassError ? (_jsx("pre", { style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: `${glassError.code} · ${glassError.stage}\n${glassError.message}${glassError.reason ? `\n${glassError.reason}` : ''}` })) : (_jsx("p", { children: preparationError })), _jsx("button", { type: "button", onClick: async () => {
-                                            if (glassError) {
-                                                window.location.reload();
-                                                return;
-                                            }
-                                            try {
-                                                if (app)
-                                                    await retryFailedInstallation(app.scope);
-                                            }
-                                            catch (error) {
-                                                setPreparationError(error instanceof Error ? error.message : String(error));
-                                                return;
-                                            }
-                                            setLaunch('preparing');
-                                            setLaunchAttempt(value => value + 1);
-                                        }, children: "Try Again" })] })] }), document.body)
-                    : null] }) }));
+    return (_jsx(RuntimeContext, { value: runtime, children: _jsx(MediaPlayerRoot, { onActivityChange: onMediaActivityChange, children: _jsx("div", { ...props, ref: rootRef, className: className, "data-satin-role": "chrome", "data-satin-root": "true", "data-satin-launch": launch, "data-satin-presentation": presentationPending ? 'preparing' : 'ready', inert: launch !== 'ready' || presentationPending, "data-satin-layout-horizontal": nextLayout.layoutClass.horizontal, "data-satin-layout-vertical": nextLayout.layoutClass.vertical, style: geometryStyles, children: _jsx(AdaptiveTabsContext, { value: tabs, children: _jsx("div", { "data-satin-status-band-source": "scene", children: _jsxs(GlassMaterialRoot, { displacement: glassDisplacement, prepared: bundlePrepared, onLaunchReady: setGlassReady, children: [DeveloperMenu && app && launch === 'ready' ? (_jsx(Suspense, { fallback: null, children: _jsx(DeveloperMenu, {}) })) : null, app ? (_jsx(OrientationGuard, { app: app, width: metrics.safeFrame.width, height: metrics.safeFrame.height, children: _jsx(ReachabilityProvider, { profile: app, offlinePresentation: offlinePresentation, children: children }) })) : (children)] }) }) }) }) }) }));
 }

package/dist/root/mountSatin.d.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
 import { type RootOptions } from 'react-dom/client';
 /** 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.
  */