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

@@ -2,7 +2,7 @@ import type { InteractivePressProfile } from './interactivePress.js';
 import { type TabHeldGeometry } from './tabMotion.js';
 export { SCOPE_THUMB } from './scopeSegments.js';
 /**
- * The held glass lens of a Toggle or Slider thumb. Measured 2026-10-09 on stock SwiftUI controls
+ * The held glass lens of a Toggle or Slider thumb. Measured 2026-10-09 on native controls
  * (iPhone 17 Pro Max Simulator, iOS 27.0, dark; counter-retimed idb contacts; `pooled-response-models.json`): a stationary hold keeps the 37 × 24 pt
  * white thumb for about 333 ms, then the thumb becomes a clear lens that springs to its held size.
  * Release restores the size with a slower spring. Mass is 1; width and height share one response.

package/dist/glass/lens/controlLift.js

@@ -2,7 +2,7 @@ import { TAB_INTERACTIVE_MOTION } from './tabMotion.js';
 import { SCOPE_THUMB } from './scopeSegments.js';
 export { SCOPE_THUMB } from './scopeSegments.js';
 /**
- * The held glass lens of a Toggle or Slider thumb. Measured 2026-10-09 on stock SwiftUI controls
+ * The held glass lens of a Toggle or Slider thumb. Measured 2026-10-09 on native controls
  * (iPhone 17 Pro Max Simulator, iOS 27.0, dark; counter-retimed idb contacts; `pooled-response-models.json`): a stationary hold keeps the 37 × 24 pt
  * white thumb for about 333 ms, then the thumb becomes a clear lens that springs to its held size.
  * Release restores the size with a slower spring. Mass is 1; width and height share one response.

package/dist/glass/lens/interactivePress.d.ts

@@ -1,7 +1,7 @@
 import { type GlassContactKind } from '../contactPhysics.js';
 /**
- * The one press response of interactive Liquid Glass (buttons, bar and toolbar buttons, the
- * back button, Glass.interactive() surfaces). Fitted 2026-09-25 to stock SwiftUI on the iOS
+ * The one press response of interactive glass (buttons, bar and toolbar buttons, the
+ * back button, Glass.interactive() surfaces). Fitted 2026-09-25 to native controls on the iOS
  * 27.0 Simulator (ParityReference `--glass-press`, idb presses at human speed: 0.6 s holds and
  * 0.12 s taps, light and dark; glass edges measured on the centre row and column):
  *

package/dist/glass/lens/interactivePress.js

@@ -1,8 +1,8 @@
 import { MENU_MORPH_DURATION, sampleMenuMorph } from './menuMorphMotion.js';
 import { GLASS_CONTACT_PHYSICS } from '../contactPhysics.js';
 /**
- * The one press response of interactive Liquid Glass (buttons, bar and toolbar buttons, the
- * back button, Glass.interactive() surfaces). Fitted 2026-09-25 to stock SwiftUI on the iOS
+ * The one press response of interactive glass (buttons, bar and toolbar buttons, the
+ * back button, Glass.interactive() surfaces). Fitted 2026-09-25 to native controls on the iOS
  * 27.0 Simulator (ParityReference `--glass-press`, idb presses at human speed: 0.6 s holds and
  * 0.12 s taps, light and dark; glass edges measured on the centre row and column):
  *

package/dist/glass/lens/menu-opening-native-fits.json

@@ -5,7 +5,7 @@
         "centerX": 364,
         "centerY": 156,
         "diameter": 58,
-        "measurement": "Fresh native button versus glass-off control: 58 x 58.333 pt at 90-level threshold. The SwiftUI label frame is 44 pt."
+        "measurement": "Fresh native button versus glass-off control: 58 x 58.333 pt at 90-level threshold. The label frame is 44 pt."
     },
     "panel": {
         "centerX": 267.5,

package/dist/glass/lens/menuContextFit.json

@@ -3,7 +3,7 @@
         "scene": "reference iOS 27 Simulator Notes, light and dark touch-clocked recordings",
         "source": "native opening measurements/curve fit and native-samples.json; recognition = touch +750ms",
         "limits": "Translucent threshold contours are estimates; same-device optical acceptance remains pending.",
-        "content": "openContent: native iPad Pro 11 (2nd gen) iOS 27.0.1 SwiftUI .contextMenu on a chat bubble, warm-light-chat-tall (3 counter-qualified trials, native menu measurements curve fit, width RMS 0.028, height RMS 0.017) on the recognition clock (content settle start = this epoch + 55 ms). Centres follow their size axis (native's first resolved frame is already at 89% width). Dark uses the light fit (dark windows were rejected)."
+        "content": "openContent: native iPad Pro 11 (2nd gen) iOS 27.0.1 .contextMenu on a chat bubble, warm-light-chat-tall (3 counter-qualified trials, native menu measurements curve fit, width RMS 0.028, height RMS 0.017) on the recognition clock (content settle start = this epoch + 55 ms). Centres follow their size axis (native's first resolved frame is already at 89% width). Dark uses the light fit (dark windows were rejected)."
     },
     "open": {
         "dark": {

package/dist/glass/lens/menuDropFit.json

@@ -1,6 +1,6 @@
 {
     "provenance": {
-        "scene": "Stock SwiftUI Menu(\"Menu selection\") in a List Section (native reference app), iPadOS 27.0, light",
+        "scene": "Native controls Menu(\"Menu selection\") in a List Section (native reference app), iPadOS 27.0, light",
         "device": "iPad Pro 12.9 (6th gen), real HID taps via WDA",
         "capture": "Native ReplayKit recording in a native reference app with a 60 Hz refresh counter (3.31% skipped refreshes, max skip 1: fit-valid, not playback-valid)",
         "method": "Platter box per refresh (blurred frame difference against the closed frame, the label's text masked), timed by the counter. Open: two cycles, normalised from a point at the drop's first centre (Satin's plain drop grows from a point) to the settled panel; frames with at least 60% of the settled mask area, the 230-450 ms settle weighted 3x. Close: platter edges read per refresh from 60 Hz tiles (+-8 px), normalised from the panel to the drop that pours back into the label.",

package/dist/glass/lens/menuField.d.ts

@@ -10,7 +10,7 @@ import type { MenuSourceKind } from '../regions.js';
  * The trigger's glyph and the menu's rows are ink drawn inside that glass (the ink kernel), so
  * the growing rim lenses them and no page element is scaled, blurred or clipped.
  *
- * Phone reference: iOS 27.0 iPhone 17 Pro Max Simulator, stock SwiftUI toolbar Menu
+ * Phone reference: iOS 27.0 iPhone 17 Pro Max Simulator, native toolbar menu
  * (native recording menu measurements). Times are ms after the morph's time zero:
  * native release +43 ms on open (regionScene anchors it on the trigger's release), close tap
  * +41 ms on close. Measured (native release/tap times): the pressed 48 pt button holds, dips to
@@ -25,7 +25,7 @@ import type { MenuSourceKind } from '../regions.js';
  * shape passes its button. Rows fade from the first close frame (246 → 96 in about 15 ms of
  * motion, a faint blurred copy until about +140 ms).
  *
- * Triggers that are not a circle (same Simulator, stock SwiftUI Menu from a labelled capsule
+ * Triggers that are not a circle (same Simulator, native menu from a labelled capsule
  * 129 x 50, a full-width button 400 x 50 and a toolbar group 152 x 44; phase-morph-shapes-notes.md):
  * the drop does not start as the trigger. The whole trigger glass contracts in about three frames
  * (its width to 0.71 and 0.47 of rest while its height is at 0.90 and 0.74: it shortens faster

package/dist/glass/lens/menuField.js

@@ -11,7 +11,7 @@ import { menuSpring } from './menuSpring.js';
  * The trigger's glyph and the menu's rows are ink drawn inside that glass (the ink kernel), so
  * the growing rim lenses them and no page element is scaled, blurred or clipped.
  *
- * Phone reference: iOS 27.0 iPhone 17 Pro Max Simulator, stock SwiftUI toolbar Menu
+ * Phone reference: iOS 27.0 iPhone 17 Pro Max Simulator, native toolbar menu
  * (native recording menu measurements). Times are ms after the morph's time zero:
  * native release +43 ms on open (regionScene anchors it on the trigger's release), close tap
  * +41 ms on close. Measured (native release/tap times): the pressed 48 pt button holds, dips to
@@ -26,7 +26,7 @@ import { menuSpring } from './menuSpring.js';
  * shape passes its button. Rows fade from the first close frame (246 → 96 in about 15 ms of
  * motion, a faint blurred copy until about +140 ms).
  *
- * Triggers that are not a circle (same Simulator, stock SwiftUI Menu from a labelled capsule
+ * Triggers that are not a circle (same Simulator, native menu from a labelled capsule
  * 129 x 50, a full-width button 400 x 50 and a toolbar group 152 x 44; phase-morph-shapes-notes.md):
  * the drop does not start as the trigger. The whole trigger glass contracts in about three frames
  * (its width to 0.71 and 0.47 of rest while its height is at 0.90 and 0.74: it shortens faster
@@ -456,7 +456,7 @@ const MENU_LABEL_INK = {
         lens: [[0, 0]],
     },
 };
-/** A plain glyph's drop (a Menu labelled with a bare symbol, no glass at rest): stock SwiftUI
+/** A plain glyph's drop (a Menu labelled with a bare symbol, no glass at rest): the measured platform control
  * in the iOS 27.0 Simulator, counter-retimed (menuGlyphDropFit.json). Open: the glyph vanishes on
  * the tap; the body's first frame is already 94 x 82 pt with the rows inside it, small and
  * blurred; they reach full size by +120 ms and are sharp by +154 ms. Close: the rows blur and

package/dist/glass/lens/menuGlyphDropFit.json

@@ -1,6 +1,6 @@
 {
     "provenance": {
-        "source": "plain-menu-morph native/PlainMenuRef.swift: stock SwiftUI Menu { … } label: { Image(systemName: \"ellipsis\") } (no glass), iOS 27.0 Simulator, iPhone 17 Pro Max, light; raw/pmm-light-1.mp4",
+        "source": "plain-menu-morph native/PlainMenuRef.swift: native controls Menu { … } label: { Image(systemName: \"ellipsis\") } (no glass), iOS 27.0 Simulator, iPhone 17 Pro Max, light; raw/pmm-light-1.mp4",
         "cadence": "refresh counter 58.47 Hz, skips 0.23 %, max skip 1, 0 unreadable: valid for fitting (duplicates removed by counter, times = refresh index x 17.1 ms)",
         "openOnset": "counter 1512, the refresh where the glyph disappears (the tap)",
         "closeOnset": "counter 1562, the last refresh before the open menu moves",

package/dist/glass/lens/menuMorphFit.json

@@ -1,6 +1,6 @@
 {
     "provenance": {
-        "scene": "ParityReference --menu-morph, stock SwiftUI toolbar Menu, black fixture",
+        "scene": "ParityReference --menu-morph, native controls toolbar Menu, black fixture",
         "capture": "native menu native recording",
         "contoursSha256": "548f8629dda83afa8467ced2bb0533db024468359f35f602e54febb6ba918310",
         "units": "milliseconds and normalized centerX, centerY, width, height",