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

package/dist/docs/tailwind.md

@@ -0,0 +1,76 @@
+# Using Tailwind with Satin
+
+Add Tailwind v4 to a Satin starter:
+
+```sh
+npm install -D tailwindcss@4 @tailwindcss/vite@4
+```
+
+Keep `satinApp()` in `vite.config.ts` and add the Tailwind plugin:
+
+```ts
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import { defineApp, satinApp } from '@satinhq/kit/vite'
+import { defineConfig } from 'vite'
+import { app } from './src/app'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss(), satinApp(defineApp(app))],
+})
+```
+
+Put this in your app's `src/styles.css`, which the starter already imports:
+
+```css
+@layer theme, base, satin, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+
+@custom-variant dark (&:where([data-satin-appearance='dark'], [data-satin-appearance='dark'] *));
+```
+
+This follows Tailwind's [Preflight opt-out](https://tailwindcss.com/docs/preflight#disabling-preflight).
+Importing all of `tailwindcss` also installs a global reset. Omit that reset:
+Satin supplies control defaults, and Preflight changes plain headings, images
+and other app content. Keep app resets out of the framework's document and controls.
+
+`satinApp()` includes the framework stylesheet automatically, before app CSS.
+Satin reserves the layer order shown above and puts its rules in `satin`.
+Utilities therefore win over framework stylesheet declarations; ordinary unlayered
+app CSS wins over both. Inline component styles and explicit component props
+still take precedence over ordinary utility classes. Prefer the component's
+props for control appearance, sizing and row geometry.
+
+Use utilities on app content or components that accept `className`:
+
+```tsx
+import { Button, ListRow, Text } from '@satinhq/kit'
+
+export function Example() {
+  return (
+    <ListRow>
+      <Text className="text-fuchsia-600">A colored label</Text>
+      <Button className="text-fuchsia-600" onPress={() => {}}>Save</Button>
+    </ListRow>
+  )
+}
+```
+
+`ListRow` does not accept `className`. Use `listRowBackground`, `listRowInsets`
+and `listRowSeparator`, or apply utilities to content inside the row.
+
+The custom `dark` variant follows Satin's effective appearance, including an
+in-app override. Tailwind's default media-query variant follows only the system.
+For safe areas, continue using Satin containers and geometry tokens. Do not add
+viewport-height, raw scrolling or `env(safe-area-inset-*)` utilities to the shell.
+
+Run your app's typecheck, fidelity lint and build after adding classes.
+Fidelity lint does not expand dependency imports or utility names, so a passing
+lint cannot approve a reset or a geometry utility.
+`satin check <url>` checks a deployment's files and headers; it does not inspect
+the CSS cascade or certify the appearance of utility classes.
+
+For a custom build integration that does not use `satinApp()`, the stylesheet
+fallback is `import '@satinhq/kit/styles.css'` once, before app styles. Apps using
+`satinApp()` need no framework CSS import; existing imports remain compatible.

package/dist/docs/tokens.md

@@ -1,6 +1,6 @@
 # Geometry and appearance tokens
 
-Load `@satinhq/kit/styles.css` once. Satin supplies these properties inside its mounted root and may override geometry in adaptive pane descendants. Consume the nearest value; do not copy root measurements into a sidebar or detail pane. Unknown custom-property names do not produce a TypeScript error and can leave a CSS declaration invalid.
+`satinApp()` includes framework styles automatically. Satin supplies these properties inside its mounted root and may override geometry in adaptive pane descendants. Consume the nearest value; do not copy root measurements into a sidebar or detail pane. Unknown custom-property names do not produce a TypeScript error and can leave a CSS declaration invalid.
 
 | Property | Value | Use |
 | --- | --- | --- |

package/dist/gestures/GestureView.d.ts

@@ -1,12 +1,14 @@
 import { type ReactNode } from 'react';
 import type { Gesture } from './gesture.js';
+/** The gestures a `GestureView` recognizes: a normal, a simultaneous and a high-priority gesture. */
 export type GestureViewProps = Readonly<{
     gesture?: Gesture;
     simultaneousGesture?: Gesture;
     highPriorityGesture?: Gesture;
     children: ReactNode;
 }>;
-/** A scoped gesture region. Scroll and navigation retain their own ownership.
+/** A region that recognizes custom gestures on its children. Scrolling and the back swipe still
+ * win the touches they own.
  * @experimental Real-touch arbitration and native thresholds remain unqualified.
  */
 export declare function GestureView({ gesture, simultaneousGesture, highPriorityGesture, children, }: GestureViewProps): import("react").JSX.Element;

package/dist/gestures/GestureView.js

@@ -6,7 +6,8 @@ import { cancelPointerPressForOwnedGesture, observePointerPressCancellation, } f
 import { createGestureArena, failGesture, reduceGestureArena, } from './arena.js';
 import { interactivePopRecognizer, nativeScrollRecognizer } from './existingCompetitors.js';
 const regions = new WeakMap();
-/** A scoped gesture region. Scroll and navigation retain their own ownership.
+/** A region that recognizes custom gestures on its children. Scrolling and the back swipe still
+ * win the touches they own.
  * @experimental Real-touch arbitration and native thresholds remain unqualified.
  */
 export function GestureView({ gesture, simultaneousGesture, highPriorityGesture, children, }) {

package/dist/gestures/gesture.d.ts

@@ -1,18 +1,23 @@
 import { type GestureDecision, type GestureRecognizerContext } from './arena.js';
+/** A point in CSS pixels. */
 export type GesturePoint = Readonly<{
     x: number;
     y: number;
 }>;
+/** A drag's current and start locations, its translation and its velocity. */
 export type DragGestureValue = Readonly<{
     location: GesturePoint;
     startLocation: GesturePoint;
     translation: GesturePoint;
     velocity: GesturePoint;
 }>;
+/** A pinch's scale relative to its start, and the point it started around. */
 export type MagnifyGestureValue = Readonly<{
     magnification: number;
     startAnchor: GesturePoint;
 }>;
+/** The binding `useGestureState` returns. A gesture updates it while active and resets it when it
+ * ends. */
 export type GestureState<Value> = Readonly<{
     update(value: Value): void;
     reset(): void;
@@ -27,6 +32,8 @@ export type GestureSample = Readonly<{
     drag: DragGestureValue;
     magnify: MagnifyGestureValue | undefined;
 }>;
+/** A gesture made by `DragGesture`, `LongPressGesture`, `TapGesture` or `MagnifyGesture`, for a
+ * `GestureView`. */
 export type Gesture = Readonly<{
     kind: 'drag' | 'longPress' | 'tap' | 'magnify';
     axis: 'horizontal' | 'vertical' | 'any';
@@ -37,26 +44,39 @@ export type Gesture = Readonly<{
     ended(sample: GestureSample): void;
     cancelled(): void;
 }>;
-/** A React value plus a gesture-owned update/reset binding. Cancellation and release
- * restore the initial value; no mutable proxy is exposed to application code. */
+/** Returns a value that a gesture drives, and the binding to pass as the gesture's `state`. The
+ * value goes back to `initialValue` when the gesture ends or is cancelled. */
 export declare function useGestureState<Value>(initialValue: Value): readonly [Value, GestureState<Value>];
+/** A drag's callbacks and state, the distance it must travel before it starts (10 by default) and
+ * the axis it accepts. */
 export type DragGestureOptions = Callbacks<DragGestureValue> & Readonly<{
     minimumDistance?: number;
     axis?: Gesture['axis'];
 }>;
+/** A drag that starts after the finger moves `minimumDistance` along the accepted axis. */
 export declare function DragGesture({ minimumDistance, axis, ...options }?: DragGestureOptions): Gesture;
+/** A long press's callbacks and state, how long it must be held (500 ms by default) and how far
+ * the finger may move (10 by default). */
 export type LongPressGestureOptions = Callbacks<boolean> & Readonly<{
     minimumDurationMs?: number;
     maximumDistance?: number;
 }>;
+/** A press held for `minimumDurationMs` without moving more than `maximumDistance`. */
 export declare function LongPressGesture({ minimumDurationMs, maximumDistance, ...options }?: LongPressGestureOptions): Gesture;
+/** A tap's callbacks and state, the number of taps (1 by default) and how far the finger may
+ * move (10 by default). */
 export type TapGestureOptions = Callbacks<GesturePoint> & Readonly<{
     count?: number;
     maximumDistance?: number;
 }>;
+/** A tap, or `count` taps, that ends without moving more than `maximumDistance`. It reports where
+ * the finger lifted. */
 export declare function TapGesture({ count, maximumDistance, ...options }?: TapGestureOptions): Gesture;
+/** A pinch's callbacks and state, and how far the scale must change before it starts (0.01 by
+ * default). */
 export type MagnifyGestureOptions = Callbacks<MagnifyGestureValue> & Readonly<{
     minimumScaleDelta?: number;
 }>;
+/** A two-finger pinch that starts once the scale changes by `minimumScaleDelta`. */
 export declare function MagnifyGesture({ minimumScaleDelta, ...options }?: MagnifyGestureOptions): Gesture;
 export {};

package/dist/gestures/gesture.js

@@ -1,7 +1,7 @@
 import { useMemo, useRef, useState } from 'react';
 import { deferGesture, failGesture, recognizeGesture, } from './arena.js';
-/** A React value plus a gesture-owned update/reset binding. Cancellation and release
- * restore the initial value; no mutable proxy is exposed to application code. */
+/** Returns a value that a gesture drives, and the binding to pass as the gesture's `state`. The
+ * value goes back to `initialValue` when the gesture ends or is cancelled. */
 export function useGestureState(initialValue) {
     const [value, setValue] = useState(initialValue);
     const initial = useRef(initialValue);
@@ -38,6 +38,7 @@ function distance(value, name) {
         throw new Error(`${name} must be finite and non-negative.`);
     return value;
 }
+/** A drag that starts after the finger moves `minimumDistance` along the accepted axis. */
 export function DragGesture({ minimumDistance = 10, axis = 'any', ...options } = {}) {
     distance(minimumDistance, 'Drag minimumDistance');
     return Object.freeze({
@@ -56,6 +57,7 @@ export function DragGesture({ minimumDistance = 10, axis = 'any', ...options } =
         },
     });
 }
+/** A press held for `minimumDurationMs` without moving more than `maximumDistance`. */
 export function LongPressGesture({ minimumDurationMs = 500, maximumDistance = 10, ...options } = {}) {
     distance(minimumDurationMs, 'Long press minimumDurationMs');
     distance(maximumDistance, 'Long press maximumDistance');
@@ -74,6 +76,8 @@ export function LongPressGesture({ minimumDurationMs = 500, maximumDistance = 10
         },
     });
 }
+/** A tap, or `count` taps, that ends without moving more than `maximumDistance`. It reports where
+ * the finger lifted. */
 export function TapGesture({ count = 1, maximumDistance = 10, ...options } = {}) {
     if (!Number.isInteger(count) || count < 1)
         throw new Error('Tap count must be a positive integer.');
@@ -90,6 +94,7 @@ export function TapGesture({ count = 1, maximumDistance = 10, ...options } = {})
         },
     });
 }
+/** A two-finger pinch that starts once the scale changes by `minimumScaleDelta`. */
 export function MagnifyGesture({ minimumScaleDelta = 0.01, ...options } = {}) {
     distance(minimumScaleDelta, 'Magnify minimumScaleDelta');
     return Object.freeze({

package/dist/glass/GlassEffect.d.ts

@@ -28,7 +28,8 @@ export type GlassEffectProps = HTMLAttributes<HTMLDivElement> & Readonly<{
 }>;
 /** Local content remains DOM-owned; only the material canvas is painted by reference. */
 export declare function GlassEffect({ glass, shape, touchLight, glassEffectID, namespace, union, transition, press, emerge, onEmergeSettled, onEmergeInk, children, style, onPointerDown, onPointerUp, onClick, ...props }: GlassEffectProps): import("react").JSX.Element;
-/** `GlassEffectContainer`: groups related glass outlines into one field. */
+/** Groups nearby glass effects so they render together and blend or morph into one another.
+ * `spacing`, 20 pt by default, sets how close effects must be to merge. */
 export declare function GlassEffectContainer({ spacing, children, ...props }: HTMLAttributes<HTMLDivElement> & {
     spacing?: number;
 }): import("react").JSX.Element;

package/dist/glass/GlassEffect.js

@@ -245,7 +245,8 @@ export function GlassEffect({ glass = Glass.regular, shape = 'capsule', touchLig
                     justifyContent: style?.justifyContent,
                 }, children: children })) : (children)] }));
 }
-/** `GlassEffectContainer`: groups related glass outlines into one field. */
+/** Groups nearby glass effects so they render together and blend or morph into one another.
+ * `spacing`, 20 pt by default, sets how close effects must be to merge. */
 export function GlassEffectContainer({ spacing = 20, children, ...props }) {
     const id = useId(), element = useRef(null), canvas = useRef(null);
     const liquid = useContext(MaterialEffectContext);

package/dist/glass/GlassPresentation.d.ts

@@ -14,6 +14,7 @@ export type GlassPresentationConsumer = Readonly<{
         intrinsicWidth?: boolean;
         placement?: 'bottom' | 'top';
         itemFrames?: readonly TabItemFrame[];
+        searchProgress?: number;
         items: readonly TabBarItem[];
         selected: string;
         onSelect: (id: string) => void;

package/dist/glass/GlassPresentation.js

@@ -182,6 +182,8 @@ export function GlassPresentation({ consumer }) {
         ? consumer.tabs.itemFrames
         : undefined;
     const tabBarPlacement = consumer?.tabs?.placement;
+    const searchProgress = tabBarPlacement === 'top' ? (consumer?.tabs?.searchProgress ?? 0) : 0;
+    const tabBarOpacity = 1 - searchProgress;
     const compactTabs = readDeviceIdiom() === 'phone' && width > height;
     const intrinsicTabs = Boolean(consumer?.tabs?.intrinsicWidth) && !compactTabs;
     const intrinsicGeometry = useMemo(() => (intrinsicTabs ? intrinsicTabGeometry(dockWidth, tabCount) : undefined), [intrinsicTabs, dockWidth, tabCount]);
@@ -232,8 +234,11 @@ export function GlassPresentation({ consumer }) {
         : 7;
     // The measured TabView material occupies the bottom safe-area band; its
     // glyphs remain above the Home indicator inside that material.
-    const dockY = insetFrame?.y ??
-        (isDragPage ? dragFrames.capsule.y : height - GLASS_DOCK_BOTTOM_GAP_PX - fallbackDockHeight);
+    const dockY = (insetFrame?.y ??
+        (isDragPage
+            ? dragFrames.capsule.y
+            : height - GLASS_DOCK_BOTTOM_GAP_PX - fallbackDockHeight)) -
+        64 * searchProgress;
     const dockRadius = isDragPage
         ? dragFrames.capsule.height / 2
         : topFrames
@@ -276,6 +281,7 @@ export function GlassPresentation({ consumer }) {
         tabBarPillWidth,
         tabBarPillWidths,
         tabBarPlacement,
+        tabBarOpacity,
         tabBarPillHeight,
         tabBarPillCenterY,
         tabBarSelectedIndex: tabBarVisible ? selectedTab : undefined,
@@ -654,12 +660,13 @@ export function GlassPresentation({ consumer }) {
         // DOM, selected state and renderer-neutral region registrations mounted.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [consumer?.backend]);
-    useEffect(() => {
+    const synchronizeGeometry = useCallback(() => {
         runtimeRef.current?.updateGeometry({
             tabBarCentres,
             tabBarPillWidth,
             tabBarPillWidths,
             tabBarPlacement,
+            tabBarOpacity,
             tabBarMinimizedOffsetX,
             tabBarPillHeight,
             tabBarPillCenterY,
@@ -683,6 +690,7 @@ export function GlassPresentation({ consumer }) {
         tabBarCentres,
         tabBarPillWidths,
         tabBarPlacement,
+        tabBarOpacity,
         tabBarMinimizedOffsetX,
         tabBarPillWidth,
         tabBarPillHeight,
@@ -703,6 +711,14 @@ export function GlassPresentation({ consumer }) {
         rightX,
         width,
     ]);
+    useLayoutEffect(() => {
+        if (readDeviceIdiom() === 'pad')
+            synchronizeGeometry();
+    }, [synchronizeGeometry]);
+    useEffect(() => {
+        if (readDeviceIdiom() !== 'pad')
+            synchronizeGeometry();
+    }, [synchronizeGeometry]);
     useEffect(() => runtimeRef.current?.setTabSelection(tabBarVisible ? selectedTab : undefined), [selectedTab, tabBarVisible]);
     useLayoutEffect(() => runtimeRef.current?.commitAppearance(appearance), [appearance]);
     // Settings and reference backgrounds are different DOM roots. Hand the newly
@@ -864,12 +880,13 @@ export function GlassPresentation({ consumer }) {
                         height: liquidEnvelope.frameHeight,
                     }
                     : {
+                        opacity: tabBarOpacity,
                         borderRadius: dockRadius,
                         left: dockX,
                         top: dockY,
                         width: dockWidth,
                         height: dockHeight,
-                    }, "data-satin-tab-layout": topFrames ? 'top' : compactTabs ? 'compact' : undefined, role: liquidMotion !== 'none' ? 'presentation' : tabBarVisible ? 'tablist' : undefined, "aria-label": liquidMotion !== 'none'
+                    }, inert: searchProgress > 0 || undefined, "aria-hidden": searchProgress > 0 || undefined, "data-satin-tab-layout": topFrames ? 'top' : compactTabs ? 'compact' : undefined, role: liquidMotion !== 'none' ? 'presentation' : tabBarVisible ? 'tablist' : undefined, "aria-label": liquidMotion !== 'none'
                     ? `Liquid ${liquidMotion} surface`
                     : tabBarVisible
                         ? probe

package/dist/glass/TabBar.js

@@ -1,4 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PadSearchBarMotion } from '../search/padSearchBarMotion.js';
+import { PadSearchPresentationContext } from '../search/PadSearchPresentationContext.js';
 import { useControlStyle } from '../public/controlStyle.js';
 import { orderedTabItems, TopTabLabel } from '../tabs/presentation.js';
 import { handleTabKeyDown } from '../tabs/keyboard.js';
@@ -20,6 +22,8 @@ import { useGlassMaterialContext } from './context.js';
 import { resolveTabBarModel, TabBarAccessoryContext } from './tabBarModel.js';
 import {} from './tokens.js';
 export function TabBar({ className, adaptive = true, onShowSidebar, items: declaredItems, onSelect, selected, style, variant = 'regular', ...props }) {
+    const searchPresentation = useContext(PadSearchPresentationContext);
+    const searchProgress = searchPresentation?.owner === selected ? 1 : 0;
     const { tint } = useControlStyle();
     const liquid = useContext(MaterialEffectContext);
     const layoutClass = useLayoutClass();
@@ -37,6 +41,19 @@ export function TabBar({ className, adaptive = true, onShowSidebar, items: decla
     const { chromeLayer, registerRegion } = useGlassMaterialContext();
     const regionId = useId();
     const elementRef = useRef(null);
+    const padBarMotion = useRef(null);
+    const previousSearchProgress = useRef(searchProgress);
+    useLayoutEffect(() => {
+        if (!sidebar || liquidTop || previousSearchProgress.current === searchProgress)
+            return;
+        previousSearchProgress.current = searchProgress;
+        const element = elementRef.current;
+        if (!element)
+            return;
+        padBarMotion.current ??= new PadSearchBarMotion();
+        padBarMotion.current.start(element, searchProgress, undefined);
+    }, [sidebar, liquidTop, searchProgress]);
+    useLayoutEffect(() => () => padBarMotion.current?.dispose(), []);
     const hasAccessory = useContext(TabBarAccessoryContext);
     const compact = readDeviceIdiom() === 'phone' && metrics.layoutViewport.width > metrics.layoutViewport.height;
     const intrinsicWidth = readDeviceIdiom() === 'phone' && !compact && items.length < 4 && !hasAccessory;
@@ -88,6 +105,7 @@ export function TabBar({ className, adaptive = true, onShowSidebar, items: decla
             tint,
             insetHost: elementRef.current ?? undefined,
             placement: 'top',
+            searchProgress,
             itemFrames,
         });
         return () => liquid?.registerTabs(regionId, undefined);
@@ -102,6 +120,7 @@ export function TabBar({ className, adaptive = true, onShowSidebar, items: decla
         tint,
         liquidTop,
         itemFrames,
+        searchProgress,
     ]);
     useLayoutEffect(() => {
         if (sidebar)
@@ -152,12 +171,15 @@ export function TabBar({ className, adaptive = true, onShowSidebar, items: decla
     const tabBarStyle = {
         ...style,
         ...(sidebar ? sidebarCssTokens : {}),
+        ...(sidebar && searchProgress
+            ? { translate: `0 ${-64 * searchProgress}px`, opacity: 1 - searchProgress }
+            : {}),
         '--satin-tab-tint': tint,
         '--satin-tab-count': items.length,
         '--satin-tab-selection-offset': `${selectedIndex * 100}%`,
         '--satin-tab-selected-index': selectedIndex,
     };
-    return createPortal(_jsxs("nav", { ...props, ref: elementRef, role: "tablist", onKeyDown: handleTabKeyDown, "aria-label": props['aria-label'] ?? 'App tabs', className: className, "data-satin-glass-region": sidebar ? undefined : regionId, "data-satin-tab-placement": sidebar ? 'top' : 'bottom', "data-satin-glass-variant": variant, "data-satin-role": "chrome", "data-satin-tab-bar": "true", style: tabBarStyle, children: [_jsx(GlassBackground, { glass: variant === 'clear' ? Glass.clear : Glass.regular }), _jsxs("div", { "data-satin-tab-items": "true", children: [onShowSidebar && (_jsx(Pressable, { "data-satin-tab-sidebar-show": "true", "aria-label": "Show Tab Sidebar", onPress: onShowSidebar, children: _jsx(SymbolImage, { name: "sidebar.left" }) })), items.map((item, index) => {
+    return createPortal(_jsxs("nav", { ...props, ref: elementRef, role: "tablist", inert: props.inert || (sidebar && searchProgress > 0) || undefined, "aria-hidden": props['aria-hidden'] || (sidebar && searchProgress > 0) || undefined, onKeyDown: handleTabKeyDown, "aria-label": props['aria-label'] ?? 'App tabs', className: className, "data-satin-glass-region": sidebar ? undefined : regionId, "data-satin-tab-placement": sidebar ? 'top' : 'bottom', "data-satin-glass-variant": variant, "data-satin-role": "chrome", "data-satin-tab-bar": "true", style: tabBarStyle, children: [_jsx(GlassBackground, { glass: variant === 'clear' ? Glass.clear : Glass.regular }), _jsxs("div", { "data-satin-tab-items": "true", children: [onShowSidebar && (_jsx(Pressable, { "data-satin-tab-sidebar-show": "true", "aria-label": "Show Tab Sidebar", onPress: onShowSidebar, children: _jsx(SymbolImage, { name: "sidebar.left" }) })), items.map((item, index) => {
                         const isSelected = item.id === selected;
                         return (_jsxs(Pressable, { role: "tab", id: item.tabId, "aria-controls": item.panelId, "aria-selected": isSelected, tabIndex: isSelected || (selectedIndex < 0 && index === 0) ? 0 : -1, "aria-label": item.accessibilityLabel ??
                                 (sidebar && item.role === 'search'

package/dist/glass/errorAlert.js

@@ -33,7 +33,8 @@ export function installGlassErrorAlert() {
         const errors = getGlassErrors().filter(error => !error.transient);
         if (!errors.length)
             return;
-        if (document.getElementById('satin-launch-error')) {
+        const prelaunch = window.__SATIN_PRELAUNCH__;
+        if (prelaunch && ['preparing', 'failed'].includes(prelaunch.snapshot().state)) {
             document.querySelector(':root > pre[data-satin-glass-error]')?.remove();
             return;
         }

package/dist/glass/errors.d.ts

@@ -1,5 +1,7 @@
-/** Serializable across the renderer worker boundary. Release failures may select the fallback material. */
+/** Why the glass renderer failed, such as `gpu-unavailable` or `device-lost`. In a release build a
+ * failure can switch glass to the fallback material. */
 export type GlassErrorCode = 'gpu-unavailable' | 'adapter-unavailable' | 'device-request' | 'context-configure' | 'device-lost' | 'validation' | 'out-of-memory' | 'shader-compilation' | 'worker-startup' | 'readiness-timeout' | 'presentation' | 'unsupported-configuration';
+/** One glass renderer failure: its code, message, the stage it happened in and when. */
 export type GlassError = Readonly<{
     code: GlassErrorCode;
     message: string;

package/dist/glass/fallback/runtime.d.ts

@@ -7,6 +7,7 @@ export declare class FallbackGlassRuntime {
     private regions;
     private dock;
     private thumb;
+    private padSearch?;
     private minimize;
     private minimizeDom;
     private tab;

package/dist/glass/fallback/runtime.js

@@ -1,3 +1,4 @@
+import { PadSearchBarMotion } from '../../search/padSearchBarMotion.js';
 import { getGlassErrors } from '../errors.js';
 import { createRenderSpecs, } from '../renderSpecs.js';
 import { TabMotion, TAB_INTERACTIVE_MOTION } from '../lens/tabMotion.js';
@@ -13,6 +14,7 @@ export class FallbackGlassRuntime {
     regions;
     dock;
     thumb;
+    padSearch;
     minimize = new TabMinimizeIntent();
     minimizeDom;
     tab = new TabMotion(TAB_INTERACTIVE_MOTION);
@@ -93,7 +95,7 @@ export class FallbackGlassRuntime {
     dockSpec() {
         const spec = createRenderSpecs(this.options.geometry, this.options.appearance).find(spec => spec.id === 'dock');
         // Chrome's DOM host already owns the viewport placement.
-        return { ...spec, frameX: 0, frameY: 0 };
+        return { ...spec, opacity: 1, frameX: 0, frameY: 0 };
     }
     minimizeTrack(direction, path = 'tap') {
         const track = this.minimizeDom.start(direction, this.dockSpec(), path);
@@ -131,9 +133,13 @@ export class FallbackGlassRuntime {
         this.thumb.paint(this.thumbSpec(selection), this.options.appearance);
     }
     updateGeometry(next) {
+        const previousOpacity = this.options.geometry.tabBarOpacity;
         const previousPlacement = this.options.geometry.tabBarPlacement;
         this.options = { ...this.options, geometry: { ...this.options.geometry, ...next } };
         const geometry = this.options.geometry;
+        if (previousPlacement === 'top' && geometry.tabBarOpacity !== undefined && previousOpacity !== geometry.tabBarOpacity) {
+            (this.padSearch ??= new PadSearchBarMotion()).start(this.options.elements.chrome.dock, 1 - geometry.tabBarOpacity, this.dockSpec());
+        }
         this.tab.configure(geometry.tabBarCentres, geometry.tabBarPillWidth, geometry.tabBarPillHeight, geometry.dockWidth, {
             selected: geometry.tabBarSelectedIndex ?? 0,
             centerY: geometry.tabBarPillCenterY,
@@ -274,6 +280,7 @@ export class FallbackGlassRuntime {
         this.dispose(owner);
     }
     dispose(_owner) {
+        this.padSearch?.dispose();
         if (this.disposed)
             return;
         this.disposed = true;

package/dist/glass/liquidContext.d.ts

@@ -7,6 +7,8 @@ export type RegisteredTabBar = TabBarProps & Readonly<{
     /** 'top': the regular-width iPad bar, laid out by `itemFrames` inside `insetHost`. */
     placement?: 'bottom' | 'top';
     itemFrames?: readonly TabItemFrame[];
+    /** iPad search handoff; applied to material, foreground and controls together. */
+    searchProgress?: number;
 }>;
 export type MaterialEffectRegistration = Readonly<{
     /** The one glass renderer. */

package/dist/glass/menuPresenter.d.ts

@@ -2,6 +2,8 @@ import type { MenuEntry } from './menuTypes.js';
 import { type MenuContactSample } from '../menu/menuContact.js';
 import { type ReactNode } from 'react';
 import { type PressableProps } from '../press/Pressable.js';
+/** The props a custom `Menu` trigger receives. Forward all of them to the element that opens the
+ * menu. */
 export type MenuTriggerProps = Pick<PressableProps, 'onPress' | 'disabled' | 'aria-expanded' | 'aria-haspopup' | 'aria-controls'>;
 export type MenuProps = Readonly<{
     label: ReactNode;

package/dist/glass/regions.d.ts

@@ -45,7 +45,8 @@ type GlassRect = Readonly<{
     width: number;
     height: number;
 }>;
-/** Normalized RGBA channels in 0...1. Glass.tintRGBA rejects nonfinite or out-of-range channels. */
+/** A glass tint as red, green, blue and alpha channels from 0 to 1. `Glass.tintRGBA` rejects
+ * values outside that range. */
 export type GlassTint = readonly [red: number, green: number, blue: number, alpha: number];
 export type GlassMaterial = Readonly<{
     variant: 'regular' | 'clear';

package/dist/glass/renderSpecs.d.ts

@@ -202,6 +202,7 @@ export type RuntimeGeometry = Readonly<{
     tabBarPillWidths?: readonly number[];
     /** 'top' is the regular-width iPad tab bar; the phone dock is 'bottom' (the default). */
     tabBarPlacement?: 'bottom' | 'top';
+    tabBarOpacity?: number;
     tabBarPillHeight?: number;
     tabBarPillCenterY?: number;
     tabBarCentres?: readonly number[];

package/dist/glass/renderSpecs.js

@@ -151,6 +151,7 @@ export function createRenderSpecs(geometry, appearance = 'light', liquidMotion =
             frameX: geometry.dockX,
             frameY: geometry.dockY,
             id: 'dock',
+            opacity: geometry.tabBarOpacity,
             radius: geometry.dockRadius,
         },
         {

package/dist/glass/webgpu/controlRim.d.ts

@@ -0,0 +1,29 @@
+/** Exterior rim measured from the iOS 27 stock 44 pt circle, at 3 device pixels/pt.
+ * See scripts/research/glass-blackroom/fit-rim.py and the round-2 evidence packet.
+ *
+ * The dark line is outside the material aperture. Its colour comes from the local
+ * backdrop, while the interior specular is a separate normal-dependent lobe.
+ * Both lateral normals have the same response; a signed horizontal term would
+ * introduce lighting that the native flat-background captures do not contain.
+ */
+export declare function controlRimUniform(appearance: 'light' | 'dark'): [number, number, number, number];
+/** Native dark regular glass changes with the short side, independently of corner radius.
+ * The 44/50/62/64/70/80/100 pt sweep measured white interior 185/185/185/185/175/159/128.
+ * Grey and 75% grey deltas follow backdrop squared. Limit extrapolation to the measured range.
+ */
+export declare function controlSizeResponse(appearance: 'light' | 'dark', width: number, height: number): number;
+/** White backdrop, bottom exterior at 2 pt: native 44/62 pt controls are 252,
+ * 80 pt controls are 248 light / 246 dark; the unscaled kernel is 245.
+ * Keep the broad shadow separate from the sub-point rim coverage.
+ */
+export declare function controlShadowScale(appearance: 'light' | 'dark', width: number, height: number): number;
+/** Native 44 pt sweep at background code levels 32/64/96/128: first exterior pixel 6/17/32/52. */
+export declare const CONTROL_RIM_LOW_LUMA_GAIN = 0.6891894;
+/** Joint least-squares fit of the unclipped black/grey/white cardinal profiles.
+ * Final amplitudes include the 1.02493656 contrast fit over 32 unclipped flat-background
+ * vertical rays after the measured size response. Photo cases were held out.
+ * Shared across appearances: the native colour matrix supplies their different contrast.
+ * Narrow support/amount, diffuse support/amount (all support distances in points).
+ */
+export declare const CONTROL_SPECULAR: readonly [1.25, 1.5385214, 6.4, 0.38803352];
+export declare const controlRimWGSL = "\nfn materialBoundary(distance: f32, normal: vec2<f32>, uv: vec2<f32>) -> vec4<f32> {\n    let rim = global.uControlRim_slot;\n    let angular = normal.x * normal.x + rim.w * normal.y * normal.y;\n    let backdrop = materialMip(uv, 0.0);\n    let luminance = dot(backdrop, vec3f(0.2126, 0.7152, 0.0722));\n    let opacity = rim.y + 0.6891894 * max(0.5 - luminance, 0.0);\n    let radial = opacity * clamp(1.0 - max(distance, 0.0) / rim.x, 0.0, 1.0);\n    // Size sweep: exterior contrast changes linearly above mid-grey, while the face\n    // changes quadratically. Normalizing by luminance expresses that contrast as coverage.\n    let sizeContrast = global.uControlSize_slot.x * max(2.0 * luminance - 1.0, 0.0);\n    let sizeCoverage = sizeContrast / max(0.6 * luminance, 0.001);\n    let coverage = clamp(radial * angular * (1.0 + sizeCoverage), 0.0, 1.0);\n    // Nine-level native sweep: light reflects a quadratic colour transform;\n    // dark retains a small highlight in the upper half of the backdrop range.\n    let lightColour = clamp(backdrop * (backdrop - vec3f(0.5)), vec3f(0.0), vec3f(1.0));\n    let darkColour = 0.6 * max(backdrop - vec3f(0.5), vec3f(0.0)) * (vec3f(1.0) - backdrop);\n    let colour = mix(lightColour, darkColour, rim.z);\n    return vec4f(colour * coverage, coverage);\n}\nfn controlSpecular(distance: f32, normal: vec2<f32>) -> f32 {\n    let profile = global.uControlSpecular_slot;\n    let depth = max(-distance, 0.0);\n    let narrow = profile.y * max(1.0 - depth / profile.x, 0.0);\n    let diffuse = profile.w * max(1.0 - depth / profile.z, 0.0);\n    let facing = clamp((abs(normal.y) - 0.16) / 0.84, 0.0, 1.0);\n    return (narrow + diffuse) * facing * facing * facing;\n}\n";