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

package/dist/sw/vite.d.ts

@@ -1,4 +1,6 @@
 import type { Plugin } from 'vite';
+/** Options for the service worker build plugin: extra files to precache, public routes, legacy
+ * cache names and diagnostic headers. */
 export interface SatinAppShellPluginOptions {
     readonly mediaProbe?: string;
     readonly shellFile?: string;
@@ -12,6 +14,8 @@ export interface SatinAppShellPluginOptions {
     /** Explicit diagnostic build only; production serves cached responses unchanged. */
     readonly diagnosticTimingHeaders?: boolean;
 }
+/** The Vite build plugin that generates the app's service worker and precache list. `satinApp`
+ * includes it; use it directly only in Satin tooling. */
 export declare function satinAppShell(options?: SatinAppShellPluginOptions): Plugin;
 export { satinApp, satinAppFixtures, type SatinAppOptions } from '../app/vite.js';
 export { defineApp } from '../public/definition.js';

package/dist/sw/vite.js

@@ -2,6 +2,8 @@ import { copyFile, mkdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { APP_SHELL_VERSION_FILE } from './protocol.js';
 import { generateAppShell } from './generator.js';
+/** The Vite build plugin that generates the app's service worker and precache list. `satinApp`
+ * includes it; use it directly only in Satin tooling. */
 export function satinAppShell(options = {}) {
     let config;
     let outputWritten = false;

package/dist/symbols/Symbol.d.ts

@@ -1,11 +1,12 @@
 import { type ReactNode, type SVGProps } from 'react';
 import { type CoreSymbolName } from './catalogue.js';
 import type { SymbolGlyph, SymbolSource, SymbolWeight, SymbolScale, SymbolRenderingMode } from './types.js';
-/** A symbol name in SF Symbols style (`'plus'`, `'trash.fill'`). The bundled names autocomplete;
- * any string is accepted for glyphs added through `SymbolProvider`. */
+/** A symbol name, such as `'plus'` or `'trash.fill'`. The bundled names autocomplete; any string
+ * is accepted for glyphs added through `SymbolProvider`. */
 export type SymbolName = CoreSymbolName | (string & {});
 export declare const SymbolSelectionContext: import("react").Context<boolean>;
-/** Extend or override glyphs locally. Paths must be original or redistributable with provenance. */
+/** Adds or replaces symbol glyphs for everything inside it. Paths must be original, or
+ * redistributable with their provenance recorded. */
 export declare function SymbolProvider({ glyphs, children, }: {
     glyphs: SymbolSource;
     children: ReactNode;
@@ -24,8 +25,9 @@ export type SymbolImageProps = Omit<SVGProps<SVGSVGElement>, 'name' | 'children'
     glyph?: SymbolGlyph;
 };
 /**
- * `Image(systemName:)`: a vector symbol that sizes with the surrounding font and takes its
- * colour. A `.fill` variant is chosen automatically where the context selects it (a selected tab).
+ * Draws a named vector symbol that sizes with the surrounding font and takes its colour. A
+ * `.fill` variant is chosen automatically where the context calls for it, such as a selected
+ * tab.
  *
  * @example
  * <SymbolImage name="star.fill" />

package/dist/symbols/Symbol.js

@@ -6,7 +6,8 @@ import { symbolGeometry, symbolNormalization, symbolNormalizationTransform, symb
 import { useInheritedSymbolWeight } from './inheritedWeight.js';
 const SourceContext = createContext(coreSymbols);
 export const SymbolSelectionContext = createContext(false);
-/** Extend or override glyphs locally. Paths must be original or redistributable with provenance. */
+/** Adds or replaces symbol glyphs for everything inside it. Paths must be original, or
+ * redistributable with their provenance recorded. */
 export function SymbolProvider({ glyphs, children, }) {
     const inherited = useContext(SourceContext);
     return _jsx(SourceContext, { value: { ...inherited, ...glyphs }, children: children });
@@ -20,8 +21,9 @@ export function resolveSymbol(source, name, selected = false) {
     return Object.hasOwn(source, name) ? source[name] : undefined;
 }
 /**
- * `Image(systemName:)`: a vector symbol that sizes with the surrounding font and takes its
- * colour. A `.fill` variant is chosen automatically where the context selects it (a selected tab).
+ * Draws a named vector symbol that sizes with the surrounding font and takes its colour. A
+ * `.fill` variant is chosen automatically where the context calls for it, such as a selected
+ * tab.
  *
  * @example
  * <SymbolImage name="star.fill" />

package/dist/symbols/catalogue.d.ts

@@ -1,4 +1,4 @@
 import type { SymbolGlyph } from './types.js';
-/** The core symbol name contract used by public app declarations. */
+/** Every symbol name in the bundled catalogue. */
 export type CoreSymbolName = "pin" | "pin.fill" | "pin.slash" | "pin.slash.fill" | "star" | "star.fill" | "house" | "house.fill" | "bell" | "bell.fill" | "person" | "person.fill" | "calendar" | "clock" | "clock.fill" | "trash" | "trash.fill" | "heart" | "heart.fill" | "folder" | "folder.fill" | "pencil" | "checkmark" | "checkmark.circle" | "checkmark.circle.fill" | "xmark" | "xmark.circle" | "xmark.circle.fill" | "info.circle" | "info.circle.fill" | "ellipsis" | "ellipsis.circle" | "ellipsis.circle.fill" | "plus" | "minus" | "chevron.left" | "chevron.right" | "chevron.up" | "chevron.down" | "circle" | "circle.fill" | "chart.bar" | "chart.bar.fill" | "photo" | "photo.fill" | "envelope" | "envelope.fill" | "bookmark" | "bookmark.fill" | "timer" | "timer.fill" | "stopwatch" | "stopwatch.fill" | "book" | "book.fill" | "doc.text" | "doc.text.fill" | "rectangle.stack" | "rectangle.stack.fill" | "slider.horizontal.3" | "square.and.arrow.up" | "square.and.arrow.up.fill" | "square.and.pencil" | "square.and.pencil.fill" | "gearshape" | "gearshape.fill" | "magnifyingglass" | "sidebar.left" | "arrowshape.turn.up.left" | "arrowshape.turn.up.left.fill" | "chevron.up.chevron.down" | "questionmark.square" | "questionmark.square.fill" | "play" | "play.fill" | "pause" | "pause.fill" | "arrow.clockwise" | "bolt" | "bolt.fill" | "flag" | "flag.fill" | "tray" | "tray.fill" | "cart" | "cart.fill" | "list.bullet" | "person.crop.circle" | "person.crop.circle.fill" | "dot.radiowaves.left.right" | "square.grid.2x2" | "square.grid.2x2.fill" | "battery.100" | "camera" | "camera.fill" | "car" | "device.phone.portrait" | "globe" | "keyboard" | "lock" | "lock.fill" | "moon" | "moon.fill" | "hand.raised" | "hand.raised.fill" | "sparkles" | "textformat" | "hourglass" | "arrow.up" | "arrow.down" | "arrow.down.circle" | "arrow.down.circle.fill" | "stop" | "stop.fill" | "doc.on.doc" | "doc.on.doc.fill" | "face.smiling" | "face.smiling.fill" | "bell.slash" | "bell.slash.fill" | "envelope.open" | "envelope.open.fill" | "envelope.badge" | "envelope.badge.fill" | "hand.thumbsup" | "hand.thumbsup.fill" | "hand.thumbsdown" | "hand.thumbsdown.fill" | "line.3.horizontal" | "line.3.horizontal.decrease" | "photo.on.rectangle" | "square.stack" | "square.stack.fill" | "forward" | "forward.fill" | "backward" | "backward.fill" | "shuffle" | "repeat" | "repeat.1" | "music.note" | "music.note.list" | "music.mic" | "music.house" | "music.house.fill" | "speaker" | "speaker.fill" | "speaker.wave.3" | "speaker.wave.3.fill" | "quote.bubble" | "quote.bubble.fill" | "tv.music.note" | "tv.music.note.fill" | "waveform" | "play.circle" | "play.circle.fill" | "play.rectangle" | "play.rectangle.fill" | "plus.circle" | "plus.circle.fill" | "checkmark.square" | "checkmark.square.fill" | "heart.slash" | "heart.slash.fill" | "flag.slash" | "flag.slash.fill" | "person.2" | "person.2.fill" | "arrowshape.turn.up.right" | "arrowshape.turn.up.right.fill" | "bubble.left.and.bubble.right" | "bubble.left.and.bubble.right.fill" | "text.insert" | "text.append" | "text.badge.plus" | "viewfinder" | "sun.max" | "sun.max.fill" | "gift" | "gift.fill" | "airplane" | "pawprint" | "briefcase" | "briefcase.fill" | "list.number" | "dot.radiowaves.left.and.right" | "exclamationmark.triangle" | "exclamationmark.triangle.fill" | "arrow.right" | "arrow.left" | "square.and.arrow.down" | "square.and.arrow.down.fill" | "gear" | "link" | "arrow.counterclockwise" | "arrow.uturn.backward" | "arrow.uturn.forward" | "archivebox" | "archivebox.fill" | "line.3.horizontal.decrease.circle" | "line.3.horizontal.decrease.circle.fill" | "questionmark.circle" | "questionmark.circle.fill" | "arrow.up.arrow.down" | "tag" | "tag.fill" | "paperplane" | "paperplane.fill" | "flame" | "flame.fill" | "location" | "location.fill" | "doc" | "doc.fill" | "mappin" | "mappin.and.ellipse" | "arrow.up.right" | "at" | "drop" | "drop.fill" | "headphones" | "bed.double" | "bed.double.fill" | "pause.circle" | "pause.circle.fill" | "display" | "dollarsign.circle" | "dollarsign.circle.fill" | "checkmark.seal" | "checkmark.seal.fill" | "tray.full" | "tray.full.fill" | "person.badge.plus" | "person.badge.plus.fill" | "folder.badge.plus" | "arrow.2.squarepath" | "dumbbell" | "figure.run" | "leaf" | "clock.arrow.circlepath" | "receipt" | "airplayaudio" | "bell.badge.fill" | "bell.badge" | "bicycle" | "book.closed.fill" | "book.closed" | "brain.head.profile" | "calendar.badge.clock" | "chart.line.uptrend.xyaxis" | "checklist" | "cross.case.fill" | "cross.case" | "cup.and.saucer.fill" | "cup.and.saucer" | "dumbbell.fill" | "exclamationmark.2" | "eye.fill" | "eye.slash.fill" | "eye.slash" | "eye" | "fork.knife" | "graduationcap.fill" | "graduationcap" | "key.fill" | "key" | "leaf.fill" | "list.bullet.clipboard.fill" | "list.bullet.clipboard" | "note.text.fill" | "note.text" | "pill.fill" | "pill" | "receipt.fill" | "scalemass.fill" | "scalemass" | "server.rack.fill" | "server.rack";
 export declare const coreSymbols: Readonly<Record<CoreSymbolName, SymbolGlyph>>;

package/dist/symbols/types.d.ts

@@ -1,5 +1,6 @@
 import type { FontWeight } from '../content/content.js';
-/** Filled paths on Framework7's 56-unit grid. No font, HTML or external resource. */
+/** A symbol's artwork: filled SVG paths on a 56-unit grid, with optional layers for hierarchical
+ * and palette rendering, and its provenance. No font, HTML or external resource. */
 export type SymbolGlyph = Readonly<{
     paths: readonly Readonly<{
         d: string;
@@ -22,9 +23,10 @@ export type SymbolGlyph = Readonly<{
 }>;
 /** Glyphs by symbol name, for `SymbolProvider`. */
 export type SymbolSource = Readonly<Record<string, SymbolGlyph>>;
-/** `Font.Weight` as applied to a symbol. */
+/** The weight a symbol is drawn at. It uses the same names as font weights. */
 export type SymbolWeight = FontWeight;
-/** `Image.Scale`. */
+/** A symbol's size relative to the text around it: `small`, `medium` or `large`. */
 export type SymbolScale = 'small' | 'medium' | 'large';
-/** `SymbolRenderingMode`. */
+/** How a symbol's layers are coloured: `monochrome` in one colour, `hierarchical` in shades of
+ * one colour, or `palette` with a colour per layer. */
 export type SymbolRenderingMode = 'monochrome' | 'hierarchical' | 'palette';

package/dist/tabs/TabSection.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-/** Groups destinations in the adaptable sidebar without creating another navigator. */
+/** A sidebar group's title, optional id and placement, and its `Tab` children. */
 export type TabSectionProps = Readonly<{
     title: string;
     /** Stable section identity when titles change or two sections have the same title. */
@@ -8,5 +8,6 @@ export type TabSectionProps = Readonly<{
     tabPlacement?: 'sidebarOnly';
     children: ReactNode;
 }>;
-/** A collapsible sidebar group. TabView consumes this declaration. */
+/** Groups `Tab`s under a collapsible header in the `TabView` sidebar. It adds no navigator of its
+ * own. */
 export declare function TabSection({ children }: TabSectionProps): ReactNode;

package/dist/tabs/TabSection.js

@@ -1,4 +1,5 @@
-/** A collapsible sidebar group. TabView consumes this declaration. */
+/** Groups `Tab`s under a collapsible header in the `TabView` sidebar. It adds no navigator of its
+ * own. */
 export function TabSection({ children }) {
     return children;
 }

package/dist/tabs/TabView.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PadSearchPresentationContext, PadSearchTabContext, } from '../search/PadSearchPresentationContext.js';
 import { TabSidebarSurface } from './TabSidebarSurface.js';
 import { ScrollSurface } from '../scroll/ScrollSurface.js';
 import { TabSection } from './TabSection.js';
@@ -53,6 +54,8 @@ function RetainedTab({ active, presented, id, children, register, focusOnActivat
 }
 /** Lazy, retained tabs. Hidden app effects remain app-owned; Satin work pauses. */
 export function TabView({ children, selection, defaultSelection, onSelectionChange, bottomAccessory, bottomAccessoryMaterial = 'glass', tabViewStyle = 'automatic', }) {
+    const [searchOwner, setSearchOwner] = useState(null);
+    const searchPresentation = useMemo(() => ({ owner: searchOwner, setOwner: setSearchOwner }), [searchOwner]);
     const layout = useLayoutClass();
     const { metrics } = useSatinLayoutRuntime();
     const canShowSidebar = tabViewStyle === 'sidebarAdaptable' &&
@@ -204,55 +207,55 @@ export function TabView({ children, selection, defaultSelection, onSelectionChan
             if (overlaySidebar)
                 changeSidebar(false);
         }, children: [item.role === 'search' ? (_jsx(SymbolImage, { name: "magnifyingglass" })) : item.symbol ? (_jsx(SymbolImage, { name: item.symbol })) : (item.icon), _jsx("span", { children: item.label })] }, item.id));
-    return (_jsxs("div", { ref: container, "data-satin-tab-view": "true", "data-satin-tab-sidebar-expanded": showSidebar || undefined, "data-satin-tab-sidebar-overlay": overlaySidebar || undefined, "data-satin-tab-sidebar-collapsed-overlay": didCollapseOverlay || undefined, "data-satin-tab-sidebar-expanded-from-tabs": (showSidebar && !overlaySidebar && expandedFromTabs) || undefined, style: didCollapseOverlay
-            ? {
-                '--satin-tab-sidebar-return-inset': `${metrics.physicalInsets.top}px`,
-            }
-            : undefined, children: [showSidebar && (_jsxs(TabSidebarSurface, { overlay: overlaySidebar, onDismiss: () => changeSidebar(false), children: [_jsx("div", { "data-satin-tab-sidebar-toggle-host": "true", children: _jsx(GlassButton, { "data-satin-tab-sidebar-hide": "true", iconOnly: true, "aria-label": "Hide Tab Sidebar", onPress: () => changeSidebar(false), children: _jsx(SymbolImage, { name: "tab-sidebar-collapse", glyph: tabSidebarCollapseGlyph, width: 25.3, height: 25.3 }) }) }), _jsxs(ScrollSurface, { id: `${scopeId}-sidebar-scroll`, primary: false, role: "tablist", "aria-orientation": "vertical", onKeyDown: handleTabKeyDown, children: [sidebarItems
-                                .filter(item => item.role === 'search' || !grouped.has(item.id))
-                                .map(sidebarRow), sections.map(section => {
-                                const expanded = !collapsedSections.has(section.id);
-                                const groupId = `${scopeId}-section-${encodeURIComponent(section.id)}`;
-                                return (_jsxs("div", { "data-satin-tab-section": "true", children: [_jsxs(Pressable, { "aria-label": section.title, "aria-expanded": expanded, "aria-controls": groupId, "data-satin-tab-section-header": "true", onPress: () => setCollapsedSections(previous => {
-                                                const next = new Set(previous);
-                                                if (expanded)
-                                                    next.add(section.id);
-                                                else
-                                                    next.delete(section.id);
-                                                return next;
-                                            }), children: [_jsx("span", { children: section.title }), _jsx(SymbolImage, { name: expanded ? 'chevron.down' : 'chevron.right' })] }), _jsx("div", { id: groupId, role: "group", "aria-label": section.title, hidden: !expanded, children: sidebarItems
-                                                .filter(item => item.role !== 'search' && section.tabs.includes(item.id))
-                                                .map(sidebarRow) })] }, section.id));
-                            })] })] })), _jsx(SafeAreaInset, { inert: showSidebar && overlaySidebar, edge: "bottom", spacing: 0, content: _jsxs("div", { ref: bottomChrome, "data-satin-tab-bottom-chrome": readDeviceIdiom() === 'phone' ? 'phone' : 'pad', 
-                    // Search's compact hit target uses the full dock, even when its resting bar hugs
-                    // two or three items. Only an actual accessory makes that resting bar full-width.
-                    style: (bottomAccessory != null || searchTab) && readDeviceIdiom() === 'phone'
-                        ? {
-                            width: glassDockWidth(metrics.layoutViewport.width, metrics.screen, metrics.insets, metrics.layoutViewport.height),
-                            marginInline: 'auto',
-                            transform: `translateX(${(metrics.insets.left - metrics.insets.right) / 2}px)`,
-                        }
-                        : undefined, children: [bottomAccessory != null && (_jsx("div", { ref: accessoryContact, "data-satin-tab-bottom-accessory": "true", 
-                            // Native iPad: 24 pt edge margins, 48 pt minimum row. In portrait
-                            // only this floating chrome clears the 280 pt modal sidebar;
-                            // landscape's parent already owns the native sidebar column.
-                            style: readDeviceIdiom() === 'pad'
-                                ? {
-                                    marginLeft: showSidebar && overlaySidebar ? 304 : 24,
-                                    marginRight: 24,
-                                    // The installed iPad can report a 25 pt system inset.
-                                    // Compensate it fully to retain the native 24 pt edge gap.
-                                    marginBottom: 24 - metrics.physicalInsets.bottom,
-                                    minHeight: 48,
-                                }
-                                : undefined, children: _jsx("div", { "data-satin-accessory-clip": "true", children: _jsx("div", { "data-satin-accessory-content": "true", children: bottomAccessoryMaterial === 'custom' ? (bottomAccessory) : (_jsx(GlassEffect, { style: { width: '100%', height: '100%' }, children: bottomAccessory })) }) }) })), selected !== undefined && (!showSidebar || overlaySidebar) && (_jsx(TabBarAccessoryContext, { value: bottomAccessory != null, children: _jsx(TabBar, { inert: showSidebar && overlaySidebar, "aria-hidden": (showSidebar && overlaySidebar) || undefined, style: showSidebar && overlaySidebar ? { visibility: 'hidden' } : undefined, items: barItems, selected: selected, onSelect: select, onShowSidebar: canShowSidebar ? () => changeSidebar(true) : undefined }) })), searchTab && (_jsx("div", { "data-satin-tab-compact-search": "true", children: _jsx("button", { type: "button", "aria-label": searchTab.accessibilityLabel ?? searchTab.label, disabled: searchTab.disabled, onClick: () => {
-                                    restoreCompactTabBar(bottomChrome.current);
-                                    // A selected Search shortcut reforms the bar without reselecting its stack.
-                                    if (selected !== searchTab.id)
-                                        select(searchTab.id);
-                                } }) }))] }), children: tabs.map((tab, index) => (_jsx(RetainedTab, { panelId: items[index].panelId, tabId: showSidebar
-                        ? `${items[index].tabId}-sidebar`
-                        : barItems.some(item => item.id === tab.id)
-                            ? items[index].tabId
-                            : undefined, label: tab.label, focusOnActivate: tab.id !== initialSelection, id: tab.id, active: tab.id === requested, presented: tab.id === selected, register: register, children: mounted.includes(tab.id) ? tab.children : null }, tab.id))) })] }));
+    return (_jsx(PadSearchPresentationContext, { value: searchPresentation, children: _jsxs("div", { ref: container, "data-satin-tab-view": "true", "data-satin-tab-sidebar-expanded": showSidebar || undefined, "data-satin-tab-sidebar-overlay": overlaySidebar || undefined, "data-satin-tab-sidebar-collapsed-overlay": didCollapseOverlay || undefined, "data-satin-tab-sidebar-expanded-from-tabs": (showSidebar && !overlaySidebar && expandedFromTabs) || undefined, style: didCollapseOverlay
+                ? {
+                    '--satin-tab-sidebar-return-inset': `${metrics.physicalInsets.top}px`,
+                }
+                : undefined, children: [showSidebar && (_jsxs(TabSidebarSurface, { overlay: overlaySidebar, onDismiss: () => changeSidebar(false), children: [_jsx("div", { "data-satin-tab-sidebar-toggle-host": "true", children: _jsx(GlassButton, { "data-satin-tab-sidebar-hide": "true", iconOnly: true, "aria-label": "Hide Tab Sidebar", onPress: () => changeSidebar(false), children: _jsx(SymbolImage, { name: "tab-sidebar-collapse", glyph: tabSidebarCollapseGlyph, width: 25.3, height: 25.3 }) }) }), _jsxs(ScrollSurface, { id: `${scopeId}-sidebar-scroll`, primary: false, role: "tablist", "aria-orientation": "vertical", onKeyDown: handleTabKeyDown, children: [sidebarItems
+                                    .filter(item => item.role === 'search' || !grouped.has(item.id))
+                                    .map(sidebarRow), sections.map(section => {
+                                    const expanded = !collapsedSections.has(section.id);
+                                    const groupId = `${scopeId}-section-${encodeURIComponent(section.id)}`;
+                                    return (_jsxs("div", { "data-satin-tab-section": "true", children: [_jsxs(Pressable, { "aria-label": section.title, "aria-expanded": expanded, "aria-controls": groupId, "data-satin-tab-section-header": "true", onPress: () => setCollapsedSections(previous => {
+                                                    const next = new Set(previous);
+                                                    if (expanded)
+                                                        next.add(section.id);
+                                                    else
+                                                        next.delete(section.id);
+                                                    return next;
+                                                }), children: [_jsx("span", { children: section.title }), _jsx(SymbolImage, { name: expanded ? 'chevron.down' : 'chevron.right' })] }), _jsx("div", { id: groupId, role: "group", "aria-label": section.title, hidden: !expanded, children: sidebarItems
+                                                    .filter(item => item.role !== 'search' && section.tabs.includes(item.id))
+                                                    .map(sidebarRow) })] }, section.id));
+                                })] })] })), _jsx(SafeAreaInset, { inert: showSidebar && overlaySidebar, edge: "bottom", spacing: 0, content: _jsxs("div", { ref: bottomChrome, "data-satin-tab-bottom-chrome": readDeviceIdiom() === 'phone' ? 'phone' : 'pad', 
+                        // Search's compact hit target uses the full dock, even when its resting bar hugs
+                        // two or three items. Only an actual accessory makes that resting bar full-width.
+                        style: (bottomAccessory != null || searchTab) && readDeviceIdiom() === 'phone'
+                            ? {
+                                width: glassDockWidth(metrics.layoutViewport.width, metrics.screen, metrics.insets, metrics.layoutViewport.height),
+                                marginInline: 'auto',
+                                transform: `translateX(${(metrics.insets.left - metrics.insets.right) / 2}px)`,
+                            }
+                            : undefined, children: [bottomAccessory != null && (_jsx("div", { ref: accessoryContact, "data-satin-tab-bottom-accessory": "true", 
+                                // Native iPad: 24 pt edge margins, 48 pt minimum row. In portrait
+                                // only this floating chrome clears the 280 pt modal sidebar;
+                                // landscape's parent already owns the native sidebar column.
+                                style: readDeviceIdiom() === 'pad'
+                                    ? {
+                                        marginLeft: showSidebar && overlaySidebar ? 304 : 24,
+                                        marginRight: 24,
+                                        // The installed iPad can report a 25 pt system inset.
+                                        // Compensate it fully to retain the native 24 pt edge gap.
+                                        marginBottom: 24 - metrics.physicalInsets.bottom,
+                                        minHeight: 48,
+                                    }
+                                    : undefined, children: _jsx("div", { "data-satin-accessory-clip": "true", children: _jsx("div", { "data-satin-accessory-content": "true", children: bottomAccessoryMaterial === 'custom' ? (bottomAccessory) : (_jsx(GlassEffect, { style: { width: '100%', height: '100%' }, children: bottomAccessory })) }) }) })), selected !== undefined && (!showSidebar || overlaySidebar) && (_jsx(TabBarAccessoryContext, { value: bottomAccessory != null, children: _jsx(TabBar, { inert: showSidebar && overlaySidebar, "aria-hidden": (showSidebar && overlaySidebar) || undefined, style: showSidebar && overlaySidebar ? { visibility: 'hidden' } : undefined, items: barItems, selected: selected, onSelect: select, onShowSidebar: canShowSidebar ? () => changeSidebar(true) : undefined }) })), searchTab && (_jsx("div", { "data-satin-tab-compact-search": "true", children: _jsx("button", { type: "button", "aria-label": searchTab.accessibilityLabel ?? searchTab.label, disabled: searchTab.disabled, onClick: () => {
+                                        restoreCompactTabBar(bottomChrome.current);
+                                        // A selected Search shortcut reforms the bar without reselecting its stack.
+                                        if (selected !== searchTab.id)
+                                            select(searchTab.id);
+                                    } }) }))] }), children: tabs.map((tab, index) => (_jsx(RetainedTab, { panelId: items[index].panelId, tabId: showSidebar
+                            ? `${items[index].tabId}-sidebar`
+                            : barItems.some(item => item.id === tab.id)
+                                ? items[index].tabId
+                                : undefined, label: tab.label, focusOnActivate: tab.id !== initialSelection, id: tab.id, active: tab.id === requested, presented: tab.id === selected, register: register, children: _jsx(PadSearchTabContext, { value: tab.role === 'search' && tab.id === selected ? tab.id : null, children: mounted.includes(tab.id) ? tab.children : null }) }, tab.id))) })] }) }));
 }

package/dist/tasks/useTask.d.ts

@@ -2,15 +2,16 @@
 export type TaskCommit = (update: () => void) => boolean;
 /** The work `useTask` runs: pass `signal` to fetches and publish state through `commit`. */
 export type TaskAction = (signal: AbortSignal, commit: TaskCommit) => void | Promise<void>;
-/** `task(id:)`: a change of `id` cancels the current run and starts a new one. */
+/** Options for `useTask`. A change of `id` cancels the current run and starts a new one. */
 export type TaskOptions = Readonly<{
     id?: unknown;
 }>;
 /** Cancels the current run and starts the task again; resolves when that run ends. */
 export type TaskRunner = () => Promise<void>;
 /**
- * A task tied to this view’s lifetime. Pass signal to fetch and publish results through
- * commit. Cancellation is cooperative; arbitrary setters outside commit cannot
- * be intercepted. The returned runner cancels and replaces the current run.
+ * Runs async work while its screen is showing. It cancels the run when the screen is covered,
+ * its tab is hidden or the component unmounts, and starts again when it shows. Pass `signal` to
+ * `fetch` and publish results through `commit`. An error the task throws reaches the nearest
+ * error boundary. The returned runner cancels and replaces the current run.
  */
 export declare function useTask(action: TaskAction, { id }?: TaskOptions): TaskRunner;

package/dist/tasks/useTask.js

@@ -2,9 +2,10 @@ import { useCallback, useContext, useLayoutEffect, useRef, useState } from 'reac
 import { ScreenContext } from '../navigation/navigationContext.js';
 import { TabActivityContext } from '../tabs/context.js';
 /**
- * A task tied to this view’s lifetime. Pass signal to fetch and publish results through
- * commit. Cancellation is cooperative; arbitrary setters outside commit cannot
- * be intercepted. The returned runner cancels and replaces the current run.
+ * Runs async work while its screen is showing. It cancels the run when the screen is covered,
+ * its tab is hidden or the component unmounts, and starts again when it shows. Pass `signal` to
+ * `fetch` and publish results through `commit`. An error the task throws reaches the nearest
+ * error boundary. The returned runner cancels and replaces the current run.
  */
 export function useTask(action, { id } = {}) {
     const screen = useContext(ScreenContext);

package/dist/testing.d.ts

@@ -1,6 +1,7 @@
-/** App-test assertion without exposing navigation engine objects. */
+/** Throws unless the visible screen in `container` is the route `screen`. For app tests. */
 export declare function assertNavigation(container: ParentNode, screen: string): void;
-/** Explicit diagnostic action. The token is requested at call time and never persisted. */
+/** Sends a test notification through a push relay and returns how many devices accepted it. The
+ * token is requested when called and never stored. */
 export declare function sendTestNotification(relay: {
     url: string;
     token: () => string | Promise<string>;

package/dist/testing.js

@@ -1,11 +1,12 @@
 import { createPushRelayAdapter } from './push/notifications.js';
-/** App-test assertion without exposing navigation engine objects. */
+/** Throws unless the visible screen in `container` is the route `screen`. For app tests. */
 export function assertNavigation(container, screen) {
     const active = container.querySelector('[data-satin-screen-container][data-satin-covered="false"]');
     if (active?.getAttribute('data-satin-screen') !== screen)
         throw new Error(`Expected active route ${screen}`);
 }
-/** Explicit diagnostic action. The token is requested at call time and never persisted. */
+/** Sends a test notification through a push relay and returns how many devices accepted it. The
+ * token is requested when called and never stored. */
 export function sendTestNotification(relay) {
     return createPushRelayAdapter(relay).sendTest();
 }

package/dist/text-input/TextEditor.js

@@ -24,7 +24,11 @@ export const TextEditor = forwardRef(function TextEditor({ value, onChange, labe
             // Only a scroll surface bounds growth. A content-sized parent is the editor's own height,
             // so reading it as a limit would stop the editor from ever growing.
             const containerHeight = surface?.clientHeight ?? Infinity;
-            const visibleHeight = keyboard.viewportHeight > 0
+            // A sheet enters from outside the viewport. Its transformed screen position is
+            // not an editing limit: transforms do not deliver a ResizeObserver notification
+            // when the sheet settles. Only intersect screen geometry for an open keyboard.
+            const keyboardVisible = keyboard.height > 0 && keyboard.viewportHeight > 0;
+            const visibleHeight = keyboardVisible
                 ? keyboard.viewportHeight -
                     Math.max(0, (surface?.getBoundingClientRect().top ?? 0) - keyboard.offsetTop)
                 : containerHeight;
@@ -32,7 +36,7 @@ export const TextEditor = forwardRef(function TextEditor({ value, onChange, labe
             // to measure it: use an isolated, non-focusable copy with the same text layout instead.
             const available = maxLines === undefined
                 ? Math.min(containerHeight, visibleHeight) - 24
-                : Math.min(Math.max(minLines, maxLines) * lineHeight + padding, keyboard.viewportHeight > 0 ? visibleHeight - 24 : Infinity);
+                : Math.min(Math.max(minLines, maxLines) * lineHeight + padding, keyboardVisible ? visibleHeight - 24 : Infinity);
             const height = editorHeight(measureEditorContentHeight(element), minLines, lineHeight, padding, available);
             if (element.style.height === `${height}px`)
                 return;
@@ -65,7 +69,7 @@ export const TextEditor = forwardRef(function TextEditor({ value, onChange, labe
             observer.disconnect();
             element.removeEventListener('input', resize);
         };
-    }, [value, minLines, maxLines, keyboard.viewportHeight, keyboard.offsetTop]);
+    }, [value, minLines, maxLines, keyboard.height, keyboard.viewportHeight, keyboard.offsetTop]);
     useLayoutEffect(() => {
         if (autoFocus && ref.current)
             focusFromFramework(ref.current, { preventScroll: true });

package/dist/text-input/focusChain.d.ts

@@ -1,4 +1,4 @@
-/** The focusable field capabilities accepted by a declared editing order. */
+/** The parts of a field element that `useFocusChain` uses to move focus. */
 export type FocusChainField = Pick<HTMLInputElement, 'focus' | 'blur' | 'disabled' | 'readOnly' | 'isConnected' | 'closest'>;
 /** Explicit order survives conditional rendering; disabled/unmounted fields are skipped. */
 export declare function createFocusChain<Key extends string>(order: readonly Key[]): {
@@ -10,8 +10,9 @@ export declare function createFocusChain<Key extends string>(order: readonly Key
     dismiss(): void;
 };
 /**
- * `@FocusState` for a form: the return key moves to the next field in `order` and the
- * last one dismisses the keyboard. Spread `field(key)` onto each field.
+ * Moves focus through a form's fields in `order`. The return key goes to the next field and the
+ * last one dismisses the keyboard. Disabled and unmounted fields are skipped. Spread
+ * `field(key)` onto each field.
  *
  * @example
  * const focus = useFocusChain(['name', 'email'])

package/dist/text-input/focusChain.js

@@ -49,8 +49,9 @@ export function createFocusChain(order) {
     };
 }
 /**
- * `@FocusState` for a form: the return key moves to the next field in `order` and the
- * last one dismisses the keyboard. Spread `field(key)` onto each field.
+ * Moves focus through a form's fields in `order`. The return key goes to the next field and the
+ * last one dismisses the keyboard. Disabled and unmounted fields are skipped. Spread
+ * `field(key)` onto each field.
  *
  * @example
  * const focus = useFocusChain(['name', 'email'])

package/dist/text-input/kinds.d.ts

@@ -1,7 +1,7 @@
 import type { InputHTMLAttributes } from 'react';
 /** What a field holds, setting its keyboard, autofill and autocorrection together. */
 export type TextFieldKind = 'text' | 'name' | 'email' | 'url' | 'tel' | 'number' | 'decimal' | 'search' | 'username' | 'new-password' | 'current-password' | 'one-time-code';
-/** `SubmitLabel`: the return key's title. */
+/** The return key's title: `done`, `go`, `next`, `search` or `send`. */
 export type SubmitLabel = 'done' | 'go' | 'next' | 'search' | 'send';
 type Attributes = Pick<InputHTMLAttributes<HTMLInputElement>, 'type' | 'inputMode' | 'autoComplete' | 'autoCapitalize' | 'autoCorrect' | 'spellCheck' | 'enterKeyHint'>;
 export declare function textFieldAttributes(kind?: TextFieldKind, submitLabel?: SubmitLabel): Attributes;

package/dist/web/WebView.d.ts

@@ -1,4 +1,6 @@
 import { type CSSProperties } from 'react';
+/** The embedded page's load state. A cross-origin page reports `unverified`, because its contents
+ * cannot be read. */
 export type WebFrameState = {
     status: 'idle' | 'loading';
 } | {
@@ -12,20 +14,24 @@ export type WebFrameState = {
     status: 'unavailable';
     reason: 'invalid-url' | 'load-error';
 };
+/** Whether a `reload` or `stop` request was sent to the frame, or why not. */
 export type WebFrameActionResult = {
     status: 'dispatched';
 } | {
     status: 'unavailable';
     reason: 'not-mounted' | 'cross-origin-or-denied';
 };
-/** Only same-origin frames expose their current page or accept reload/stop commands. */
+/** Reads a `WebView`'s state and sends it `reload` and `stop`. Only same-origin frames expose
+ * their current page or accept these commands. */
 export interface WebFrameController {
     readonly state: WebFrameState;
     reload(): WebFrameActionResult;
     stop(): WebFrameActionResult;
 }
-/** Observe a WebView and request the operations its origin permits. */
+/** Makes a controller to pass to a `WebView`, for reading its state and reloading or stopping it. */
 export declare function useWebFrame(): WebFrameController;
+/** The page URL, its accessible title, an optional controller, and what the page may run. Scripts
+ * and forms are off by default. */
 export interface WebViewProps {
     url: string;
     /** Accessible name for the embedded page. */
@@ -38,5 +44,6 @@ export interface WebViewProps {
     style?: CSSProperties;
     onStateChange?: (state: WebFrameState) => void;
 }
-/** A sandboxed embedded page. Framing policy and partitioned storage remain browser-owned. */
+/** Embeds a web page in a sandboxed frame. The browser decides whether the page may be framed, and
+ * the frame's storage is partitioned from the app's. */
 export declare function WebView({ url: input, title, controller, className, style, onStateChange, allowsJavaScript, allowsForms, }: WebViewProps): import("react").JSX.Element | null;

package/dist/web/WebView.js

@@ -50,7 +50,7 @@ function createFrameStore() {
         },
     };
 }
-/** Observe a WebView and request the operations its origin permits. */
+/** Makes a controller to pass to a `WebView`, for reading its state and reloading or stopping it. */
 export function useWebFrame() {
     const store = useMemo(() => {
         const value = createFrameStore();
@@ -60,7 +60,8 @@ export function useWebFrame() {
     useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
     return store.controller;
 }
-/** A sandboxed embedded page. Framing policy and partitioned storage remain browser-owned. */
+/** Embeds a web page in a sandboxed frame. The browser decides whether the page may be framed, and
+ * the frame's storage is partitioned from the app's. */
 export function WebView({ url: input, title, controller, className, style, onStateChange, allowsJavaScript = false, allowsForms = false, }) {
     const local = useWebFrame();
     const store = stores.get(controller ?? local);

package/dist/web/authentication.d.ts

@@ -1,3 +1,5 @@
+/** The OAuth provider, client, callback and app URLs for `defineWebAuthentication`, and the
+ * `exchange` function that finishes sign-in on your server. */
 export interface WebAuthenticationConfiguration {
     /** Stable name, unique within this app origin. */
     id: string;
@@ -16,6 +18,8 @@ export interface WebAuthenticationConfiguration {
     /** Establish your session on the server. Never return or message tokens to another window. */
     exchange: (request: WebAuthenticationExchange) => Promise<void>;
 }
+/** What `exchange` receives: the authorization code, the PKCE verifier and the values your
+ * server needs to redeem and check it. */
 export interface WebAuthenticationExchange {
     code: string;
     codeVerifier: string;
@@ -26,6 +30,7 @@ export interface WebAuthenticationExchange {
     expectedIssuer?: string;
     signal: AbortSignal;
 }
+/** Where a sign-in stands, from `idle` through `pending` and `completing` to a final status. */
 export type WebAuthenticationState = {
     status: 'idle';
 } | {
@@ -38,6 +43,7 @@ export type WebAuthenticationState = {
     status: 'failed' | 'unavailable';
     reason: string;
 };
+/** Whether `start` opened the provider in a popup or a redirect, or why it could not. */
 export type WebAuthenticationStartResult = {
     status: 'dispatched';
     transport: 'popup' | 'redirect';
@@ -45,6 +51,7 @@ export type WebAuthenticationStartResult = {
     status: 'unavailable';
     reason: string;
 };
+/** The outcome of `complete` on the callback page: the URL to return to, or why it was rejected. */
 export type WebAuthenticationCallbackResult = {
     status: 'completed';
     returnURL: string;
@@ -52,12 +59,15 @@ export type WebAuthenticationCallbackResult = {
     status: 'rejected' | 'unavailable';
     reason: string;
 };
+/** A prepared sign-in. Call `start` from the user's press. */
 export interface WebAuthenticationRequest {
     /** Call synchronously in the user's press handler. A blocked popup may retry as redirect. */
     start(options?: {
         transport?: 'popup' | 'redirect';
     }): WebAuthenticationStartResult;
 }
+/** A sign-in flow made by `defineWebAuthentication`: prepare, start, complete and resume it, or
+ * subscribe to its state. */
 export interface WebAuthentication {
     /** Generate PKCE and durably register the transaction before enabling the sign-in button. */
     prepare(): Promise<WebAuthenticationRequest>;
@@ -71,5 +81,6 @@ export interface WebAuthentication {
     /** Attach bounded popup monitoring and lifecycle listeners. Returns their cleanup. */
     connect(): () => void;
 }
-/** Durable authorization-code + PKCE handoff. This does not implement a native authentication session. */
+/** Sets up an OAuth authorization-code sign-in with PKCE. The transaction is stored durably, so
+ * it survives a redirect or a suspended app. Your server redeems the code. */
 export declare function defineWebAuthentication(configuration: WebAuthenticationConfiguration): WebAuthentication;

package/dist/web/authentication.js

@@ -29,7 +29,8 @@ function callbackValue(value, state) {
         return { state, error: response.error };
     return null;
 }
-/** Durable authorization-code + PKCE handoff. This does not implement a native authentication session. */
+/** Sets up an OAuth authorization-code sign-in with PKCE. The transaction is stored durably, so
+ * it survives a redirect or a suspended app. Your server redeems the code. */
 export function defineWebAuthentication(configuration) {
     const app = secureWebURL(configuration.appURL, configuration.appURL);
     const callback = secureWebURL(configuration.callbackURL, app.href);

package/dist/web/openURL.d.ts

@@ -1,10 +1,12 @@
 import { type CSSProperties, type ReactNode } from 'react';
-/** A preference for the browser-owned presentation, not a Safari launch guarantee. */
+/** How to open a web page. `prefersInApp` is a preference; the browser decides how the page is
+ * presented. */
 export interface OpenURLOptions {
     /** Defaults to true. A strict external-browser request is unavailable on this runtime. */
     prefersInApp?: boolean;
 }
-/** Dispatched means WebKit accepted the action; it does not mean the page loaded. */
+/** What happened to an open request: `handled` in the app, `dispatched` to the browser, or
+ * `unavailable` with a reason. `dispatched` does not mean the page loaded. */
 export type OpenURLResult = {
     status: 'handled';
     destination: 'app';
@@ -15,6 +17,7 @@ export type OpenURLResult = {
     status: 'unavailable';
     reason: 'invalid-url' | 'external-browser' | 'unregistered-app-url' | 'navigation-failed' | 'popup-blocked';
 };
+/** The function `useOpenURL` returns. It opens a URL and reports the result at once. */
 export type OpenURLAction = (url: string, options?: OpenURLOptions) => OpenURLResult;
 /** Internal factory keeps the same policy in component and imperative actions. */
 export declare function createOpenURLAction(options: {
@@ -22,8 +25,10 @@ export declare function createOpenURLAction(options: {
     openInternal: (url: string) => boolean;
     dispatch: (url: string) => boolean;
 }): OpenURLAction;
-/** Open a web URL from an action. Registered app URLs stay in the current document. */
+/** Returns a function that opens a URL from an action. App URLs that match a registered route
+ * navigate inside the app; other URLs go to the browser. */
 export declare function useOpenURL(): OpenURLAction;
+/** The link's destination URL, its content and an optional result callback. */
 export interface LinkProps extends OpenURLOptions {
     destination: string;
     children: ReactNode;
@@ -33,5 +38,6 @@ export interface LinkProps extends OpenURLOptions {
     /** Receives dispatch or rejection immediately, never inferred page completion. */
     onResult?: (result: OpenURLResult) => void;
 }
-/** An accessible URL action with the framework's press and scroll-cancellation policy. */
+/** Opens a URL when pressed, like `useOpenURL`. A press that turns into a scroll does not open
+ * it. */
 export declare function Link({ destination, prefersInApp, onResult, children, ...props }: LinkProps): import("react").JSX.Element;