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

package/dist/list-form/editing.d.ts

@@ -5,7 +5,7 @@ export type EditMode = 'inactive' | 'active';
 /** A row's identity in `List` selection: the `ForEach` id. */
 export type ListItemID = string | number;
 /**
- * Every navigation destination owns one edit mode, as a SwiftUI `NavigationStack` destination does:
+ * Every navigation destination owns one edit mode, for its retained entry:
  * its `EditButton` and its lists read and write the same value, and another screen keeps its own.
  */
 export declare function EditModeScope({ children }: {
@@ -25,14 +25,14 @@ export type ListSelectionModel = Readonly<{
     /** `single` selects one row (an optional binding); `multiple` collects a set. */
     mode: 'single' | 'multiple';
     isSelected(id: ListItemID): boolean;
-    /** A row tap: replaces a single selection; toggles a set only while editing, as SwiftUI does. */
+    /** A row tap: replaces a single selection; toggles a set only while editing. */
     activate(id: ListItemID, editing: boolean): void;
 }>;
 export declare const ListSelectionContext: import("react").Context<Readonly<{
     /** `single` selects one row (an optional binding); `multiple` collects a set. */
     mode: 'single' | 'multiple';
     isSelected(id: ListItemID): boolean;
-    /** A row tap: replaces a single selection; toggles a set only while editing, as SwiftUI does. */
+    /** A row tap: replaces a single selection; toggles a set only while editing. */
     activate(id: ListItemID, editing: boolean): void;
 }> | null>;
 /**
@@ -82,7 +82,7 @@ export declare function forEachRows<T>(props: ForEachProps<T>): ForEachRow[];
 /** What an editable row needs from its list item: edit state, selection and the item's actions. */
 export type ListItemState = Readonly<{
     editing: boolean;
-    /** While editing with a selection, a row's own press selects it, as a SwiftUI list row does. */
+    /** While editing with a selection, a row's own press selects it, as a list row does. */
     pressSelects: boolean;
     select(): void;
     /** Rows that also declare actions hand them to the item, which owns the row's one gesture host. */
@@ -94,7 +94,7 @@ export type RowActionsDelegation = RowActionsProps & Readonly<{
 }>;
 export declare const ListItemContext: import("react").Context<Readonly<{
     editing: boolean;
-    /** While editing with a selection, a row's own press selects it, as a SwiftUI list row does. */
+    /** While editing with a selection, a row's own press selects it, as a list row does. */
     pressSelects: boolean;
     select(): void;
     /** Rows that also declare actions hand them to the item, which owns the row's one gesture host. */

package/dist/list-form/editing.js

@@ -3,7 +3,7 @@ import { createContext, Fragment, useContext, useMemo, useState } from 'react';
 const inactiveEverywhere = ['inactive', () => { }];
 const EditModeContext = createContext(inactiveEverywhere);
 /**
- * Every navigation destination owns one edit mode, as a SwiftUI `NavigationStack` destination does:
+ * Every navigation destination owns one edit mode, for its retained entry:
  * its `EditButton` and its lists read and write the same value, and another screen keeps its own.
  */
 export function EditModeScope({ children }) {

package/dist/motion/animationValue.d.ts

@@ -4,14 +4,14 @@ declare const brand: unique symbol;
 export type Animation = Readonly<{
     [brand]: true;
 }>;
-/** Duration and bounce options for `Animation.spring`. */
+/** Options for a spring defined by duration and bounce. */
 export type SpringOptions = Readonly<{
     /** The perceptual duration in milliseconds. Defaults to 500. */
     durationMs?: number;
     /** 0 settles without overshoot. Values are clamped to 0 through 0.99. Defaults to 0. */
     bounce?: number;
 }>;
-/** SwiftUI's named springs. `default` is the curve `withAnimation` uses with no argument. */
+/** Named spring timing values. `default` is the curve `withAnimation` uses with no argument. */
 export declare const Animation: Readonly<{
     spring: (options?: SpringOptions) => Animation;
     smooth: Animation;

package/dist/motion/animationValue.js

@@ -1,8 +1,8 @@
 const brand = Symbol('satin.animation');
 /**
- * SwiftUI's `spring(duration:bounce:)` mapping, as Apple documents it: the duration is the
+ * Duration is the
  * period of the undamped spring (omega = 2π / duration), and bounce is 1 − damping ratio for
- * bounce ≥ 0. SwiftUI's negative (over-damped) bounces are not offered: the shared spring
+ * bounce ≥ 0. Negative, over-damped bounces are not offered: the shared spring
  * solver (glass/lens/menuSpring.ts) models damping ratios up to 1.
  */
 function spring({ durationMs = 500, bounce = 0 } = {}) {
@@ -15,24 +15,23 @@ function spring({ durationMs = 500, bounce = 0 } = {}) {
     const animation = Object.freeze({ [brand]: true, omega, zeta });
     return animation;
 }
-/** SwiftUI's named springs. `default` is the curve `withAnimation` uses with no argument. */
+/** Named spring timing values. `default` is the curve `withAnimation` uses with no argument. */
 export const Animation = Object.freeze({
     spring,
-    /** SwiftUI `.smooth`: duration 0.5 s, bounce 0. */
+    /** Smooth spring: duration 0.5 s, bounce 0. */
     smooth: spring({ durationMs: 500, bounce: 0 }),
-    /** SwiftUI `.snappy`: duration 0.5 s, bounce 0.15. */
+    /** Snappy spring: duration 0.5 s, bounce 0.15. */
     snappy: spring({ durationMs: 500, bounce: 0.15 }),
-    /** SwiftUI `.bouncy`: duration 0.5 s, bounce 0.3. */
+    /** Bouncy spring: duration 0.5 s, bounce 0.3. */
     bouncy: spring({ durationMs: 500, bounce: 0.3 }),
-    /** SwiftUI `.default`. The value is the measured fit recorded in the measured reference
+    /** Default spring. The value is the measured fit recorded in the measured reference
      * (matchedGeometryEffect, October 11); see DEFAULT_ANIMATION_DURATION_MS. */
     get default() {
         return defaultAnimation;
     },
 });
-/* The perceptual duration of SwiftUI's `.default` animation on iOS 27, which is a critically
- * damped spring. Source: the stock SwiftUI matchedGeometryEffect fixture recorded by the
- * matched-geometry implementation (the measured reference, October 11). */
+/* Default perceptual duration for the critically damped animation spring. The measured
+ * fit and recording provenance live in the measured reference. */
 export const DEFAULT_ANIMATION_DURATION_MS = 500;
 const defaultAnimation = spring({ durationMs: DEFAULT_ANIMATION_DURATION_MS, bounce: 0 });
 /** The spring with a unit displacement and the given initial velocity (units per second). */

package/dist/motion/matchedGeometry.d.ts

@@ -27,22 +27,22 @@ export type MatchedGeometryEffectProps = Readonly<{
     children: ReactNode;
 }>;
 /**
- * SwiftUI `matchedGeometryEffect(id:in:isSource:)`: when a `withAnimation` change removes this
+ * When a `withAnimation` change removes this
  * view and inserts another with the same id, the new one moves from the old one's frame to its
  * own while the two cross-fade. A view that only moves or resizes
  * animates from where it was. A matched view with no partner fades in or out.
  *
  * Wrap one element that has no transform of its own. Changes made outside `withAnimation`
- * apply at once, as in SwiftUI.
+ * apply at once.
  * @example
  * const art = useNamespace()
  * <MatchedGeometryEffect id="artwork" in={art}><Image src={cover} alt="" /></MatchedGeometryEffect>
- * @experimental Frame matching only (SwiftUI's default `properties: .frame`, `anchor: .center`).
+ * @experimental Matches the frame around its center only.
  * A non-source view does not follow its source outside an animation.
  */
 export declare function MatchedGeometryEffect({ id, in: namespace, isSource, children, }: MatchedGeometryEffectProps): import("react").JSX.Element;
 /**
- * `withAnimation` applies the state changes in `update`, then animates the
+ * Applies the state changes in `update`, then animates the
  * `MatchedGeometryEffect` views they move, insert or remove. Call it from an event handler.
  * Keyed List rows also move to their new positions. Other views take their new layout at once.
  * Returns the callback result and propagates errors. Only synchronous updates participate.

package/dist/motion/matchedGeometry.js

@@ -17,9 +17,8 @@ import { fadeSettleMs, runFrameTimes, sampleChannel, sampleProgress, } from './s
  *
  * A view whose id leaves and enters in the same change keeps its identity: the new view starts
  * from the old one's frame and fades in, and the old view stays on screen as a "ghost" (its own
- * detached DOM node, already decoded) that travels with it and fades out. That cross-fade is
- * SwiftUI's: a stock iOS 27 fixture shows both views on one frame, with opacities that sum to 1
- * on the animation's own spring (the measured reference, October 11).
+ * detached DOM node, already decoded) that travels with it and fades out. Their opacities sum to 1
+ * throughout the spring-driven cross-fade. Measurement provenance lives in the measured reference.
  */
 const namespaceBrand = Symbol('satin.namespace');
 const entries = new Set();
@@ -40,17 +39,17 @@ export function defineNamespace() {
     return Object.freeze({ [namespaceBrand]: true });
 }
 /**
- * SwiftUI `matchedGeometryEffect(id:in:isSource:)`: when a `withAnimation` change removes this
+ * When a `withAnimation` change removes this
  * view and inserts another with the same id, the new one moves from the old one's frame to its
  * own while the two cross-fade. A view that only moves or resizes
  * animates from where it was. A matched view with no partner fades in or out.
  *
  * Wrap one element that has no transform of its own. Changes made outside `withAnimation`
- * apply at once, as in SwiftUI.
+ * apply at once.
  * @example
  * const art = useNamespace()
  * <MatchedGeometryEffect id="artwork" in={art}><Image src={cover} alt="" /></MatchedGeometryEffect>
- * @experimental Frame matching only (SwiftUI's default `properties: .frame`, `anchor: .center`).
+ * @experimental Matches the frame around its center only.
  * A non-source view does not follow its source outside an animation.
  */
 export function MatchedGeometryEffect({ id, in: namespace, isSource = true, children, }) {
@@ -226,13 +225,13 @@ function moveView(element, key, from, box, animation) {
         target: box,
         velocity: from.velocity,
         animation,
-        // A new partner fades in (SwiftUI's default .opacity insertion); a view that stays carries
+        // A new partner fades in through the default opacity transition; a view that stays carries
         // on from the opacity it is showing.
         opacity: { from: stayed ? from.opacity : 0, to: 1 },
         ghost: false,
     });
 }
-/** SwiftUI's default `.opacity` transition for a matched view with no partner. */
+/** An opacity transition for a matched view with no partner. */
 function fadeView(element, key, box, animation, opacity) {
     startRun({
         element,

package/dist/motion/springTrack.d.ts

@@ -1,6 +1,5 @@
 import { type MenuSpring } from '../glass/lens/menuSpring.js';
-/** A measured spring: SwiftUI's `.interpolatingSpring(stiffness:damping:)` with unit mass, released
- * `delay` ms after the animation starts. */
+/** A unit-mass spring defined by stiffness and damping, released after an optional delay in ms. */
 export type SpringParameters = Readonly<{
     stiffness: number;
     damping: number;

package/dist/motion/springTrack.js

@@ -28,19 +28,22 @@ export function sampledKeyframes(track, frame) {
     return track.progress.map((progress, index) => ({ ...frame(progress), offset: index / last }));
 }
 export function sampledMotionTrack(duration, sample, tolerance = 0.2) {
-    if (!(duration > 0) || !Number.isFinite(duration) || !(tolerance > 0) || !Number.isFinite(tolerance))
+    if (!(duration > 0) ||
+        !Number.isFinite(duration) ||
+        !(tolerance > 0) ||
+        !Number.isFinite(tolerance))
         throw Error('Motion tracks require a finite positive duration and tolerance');
     let count = Math.max(1, Math.ceil(duration / (1000 / 120)));
     // GPU and compositor consumers require even offsets. Refine the whole grid,
     // rather than giving them independent adaptive sample positions.
     while (count <= 4096) {
-        const values = Array.from({ length: count + 1 }, (_, index) => sample(duration * index / count));
+        const values = Array.from({ length: count + 1 }, (_, index) => sample((duration * index) / count));
         if (!values.every(Number.isFinite))
             throw Error('Motion track contains a non-finite value');
         let accurate = true;
         for (let index = 0; accurate && index < count; index++) {
             for (const fraction of [0.25, 0.5, 0.75]) {
-                const exact = sample(duration * (index + fraction) / count);
+                const exact = sample((duration * (index + fraction)) / count);
                 const linear = values[index] + (values[index + 1] - values[index]) * fraction;
                 if (!Number.isFinite(exact))
                     throw Error('Motion track contains a non-finite value');
@@ -59,11 +62,13 @@ export function sampledMotionTrack(duration, sample, tolerance = 0.2) {
 /** Read the submitted segment, including its velocity, when a run is interrupted. */
 export function sampledMotionState(track, milliseconds) {
     const last = track.values.length - 1;
-    const position = Math.max(0, Math.min(last, milliseconds / track.duration * last));
+    const position = Math.max(0, Math.min(last, (milliseconds / track.duration) * last));
     const index = Math.min(last - 1, Math.floor(position));
     const from = track.values[index], to = track.values[index + 1];
     return {
         value: from + (to - from) * (position - index),
-        velocity: milliseconds < 0 || milliseconds >= track.duration ? 0 : (to - from) * last / track.duration * 1000,
+        velocity: milliseconds < 0 || milliseconds >= track.duration
+            ? 0
+            : (((to - from) * last) / track.duration) * 1000,
     };
 }

package/dist/navigation/ScreenContainer.js

@@ -130,7 +130,7 @@ export function ScreenContainer({ children, entry, interactionBlocked = false, c
     }), [entry.key, entry.params, entry.transition.phase, isCovered, scrollRegistry, tabActive]);
     useLayoutEffect(() => navigator[navigatorScrollRuntime].bind(entry.key, scrollRegistry), [entry.key, navigator, scrollRegistry]);
     // Without a primary scroll view, content is laid out in the safe area below the bar, as a
-    // SwiftUI VStack is (styles.css). The attribute follows the registry in the same frame.
+    // VStack is (styles.css). The attribute follows the registry in the same frame.
     // The primary's vertical scroll indicator is drawn in the screen frame (scroll/scrollIndicator.ts).
     const motionLayer = useRef(null);
     const indicatorTrack = useRef(null);

package/dist/navigation/chromeCurves.js

@@ -1,7 +1,7 @@
 // Measured iOS 27 navigation bar chrome curves (what bar items do while a page moves) and the
 // keyframe builders that turn them into Web Animations keyframes. Pure data and math: no DOM.
 /** Incoming bar chrome, measured on the iOS 27.0 Simulator from the presentation layers of stock
- * SwiftUI (every display frame,
+ * Measured at every display frame,
  * light and dark agree within 0.04): milliseconds since the page starts moving. A push brings the
  * destination's glass items in faster than a pop brings the revealed screen's back: a push shows
  * 0.56 at 100 ms (Reminders-style list → list, back circle and trailing "…" together), a pop 0.30

package/dist/navigation/types.d.ts

@@ -16,7 +16,7 @@ export type NavigationBarDefinition<Params = unknown> = Readonly<{
     display?: TitleDisplayMode;
     visibility?: Visibility;
     title: string | ((params: Params) => string);
-    /** SwiftUI `navigationSubtitle`: a line under the title, inline or large. */
+    /** A line under the title, inline or large. */
     subtitle?: string;
 }>;
 export type TransitionControllerContext = Readonly<{

package/dist/navigation/zoomGeometry.js

@@ -1,5 +1,5 @@
 /*
- * The geometry of SwiftUI's zoom navigation transition, as pure functions of a rectangle.
+ * Zoom navigation geometry, as pure functions of a rectangle.
  *
  * At every moment the pushed screen is shown inside a rounded "window" rectangle that moves between
  * the source view's frame and the full screen. As natively, the screen's content is scaled so its

package/dist/navigation/zoomMotion.d.ts

@@ -9,7 +9,7 @@ export type ZoomSprings = Readonly<{
     size: ZoomSpring;
 }>;
 /**
- * Push: the centre and the width move together, critically damped (half way at 88 ms; SwiftUI's
+ * Push: the centre and the width move together, critically damped (half way at 88 ms; the measured
  * duration 0.33 s); the height lags slightly. Native moves the width with the centre, so the
  * width shares the centre's spring here and the height takes the size spring (rms 0.002, 51 ticks).
  */

package/dist/navigation/zoomMotion.js

@@ -1,5 +1,5 @@
 /*
- * Measured values of SwiftUI's `.navigationTransition(.zoom(sourceID:in:))` on iOS 27.
+ * Measured spring values for the zoom navigation transition on iOS 27.
  *
  * native reference: a stock native fixture (a 180 pt tile with a 10 pt corner in a
  * NavigationStack grid, pushed to a full-screen page), iPhone 17 Pro Max Simulator, iOS 27.0.
@@ -10,7 +10,7 @@
  * (the measured reference, October 11).
  */
 /**
- * Push: the centre and the width move together, critically damped (half way at 88 ms; SwiftUI's
+ * Push: the centre and the width move together, critically damped (half way at 88 ms; the measured
  * duration 0.33 s); the height lags slightly. Native moves the width with the centre, so the
  * width shares the centre's spring here and the height takes the size spring (rms 0.002, 51 ticks).
  */

package/dist/navigation/zoomTransition.js

@@ -1,6 +1,5 @@
 /*
- * SwiftUI's zoom navigation transition: `matchedTransitionSource(id:in:)` on the view a push starts
- * from, and `.navigationTransition(.zoom(sourceID:in:))` on the pushed screen.
+ * Zoom navigation connects a MatchedTransitionSource to a screen configured with a zoom transition.
  *
  * A push whose screen asks for a zoom, and whose source is on screen in the screen it covers, grows
  * out of the source instead of sliding in. Its pop (the back button) and a downward drag on the
@@ -116,7 +115,7 @@ export function visibleZoomSource(entryKey, rear, excluded) {
     }
     return chosen?.view;
 }
-/** SwiftUI zooms only from a source the user can see: at least part of it in the viewport. */
+/** Zoom transitions require a visible source: at least part of it in the viewport. */
 function isOnScreen(view) {
     const bounds = view.getBoundingClientRect();
     if (!(bounds.width > 0 && bounds.height > 0))
@@ -950,7 +949,7 @@ export function windowKeyframes(from, to, springs, velocity) {
     frames.push({ ms: frames.at(-1).ms + FRAME_MS, rect: to });
     return frames;
 }
-/** A measured Core Animation spring as Satin's `Animation` (SwiftUI's duration/bounce mapping is
+/** A measured Core Animation spring as Satin's `Animation` (the duration/bounce representation is
  * exact: omega = 2π / duration, damping ratio = 1 − bounce). */
 function animationOf(spring) {
     return SpringAnimation.spring({

package/dist/presentation/Presentation.d.ts

@@ -19,7 +19,7 @@ export type SheetProps = PresentationProps & {
      * content that fills the card (Now Playing). A modal NavigationStack root's title is drawn by
      * its navigation bar either way. */
     titleVisibility?: 'visible' | 'hidden';
-    /** SwiftUI's `presentationDragIndicator`. `automatic` shows it only when there is more than one
+    /** Control the sheet drag indicator. `automatic` shows it only when there is more than one
      * detent to drag between, as native does. */
     dragIndicator?: 'automatic' | 'visible' | 'hidden';
 };
@@ -27,7 +27,7 @@ export declare function Sheet(props: SheetProps): import("react").JSX.Element |
 export type FullScreenCoverProps = PresentationProps & {
     children: ReactNode;
 };
-/** SwiftUI's `fullScreenCover`: an opaque presentation over the whole screen that slides up from
+/** An opaque presentation over the whole screen that slides up from
  * the bottom edge. It has no grabber and no interactive dismissal; close it with its binding or
  * `useDismiss()`. Its title labels the dialog for assistive technology and is not drawn. */
 export declare function FullScreenCover({ children, ...props }: FullScreenCoverProps): import("react").JSX.Element | null;

package/dist/presentation/Presentation.js

@@ -23,7 +23,7 @@ export function Sheet(props) {
             props.onDismiss?.();
         } })) : null;
 }
-/** SwiftUI's `fullScreenCover`: an opaque presentation over the whole screen that slides up from
+/** An opaque presentation over the whole screen that slides up from
  * the bottom edge. It has no grabber and no interactive dismissal; close it with its binding or
  * `useDismiss()`. Its title labels the dialog for assistive technology and is not drawn. */
 export function FullScreenCover({ children, ...props }) {

package/dist/presentation/presentationSource.js

@@ -1,7 +1,7 @@
 /** The control a presentation grows from when the app names no anchor. Native iOS 27 presents
  * `confirmationDialog` as a popover from the view that asked for it: a swipe action's dialog points
  * at its row, a toolbar button's dialog grows out of the button. Satin's natural structure attaches
- * the dialog at screen level, so the pressed control stands in for SwiftUI's attachment point. */
+ * the dialog at screen level, so the pressed control supplies the attachment point. */
 const lastPress = new WeakMap();
 const tracked = new WeakSet();
 // A press older than this did not open the dialog (a timer or a data change did).

package/dist/public/controls.d.ts

@@ -112,7 +112,7 @@ export type ButtonProps = AriaAttributes & RowInteractionProps & {
     iconOnly?: false;
 });
 /**
- * SwiftUI `Button`. It adapts to where it is: a tinted row in a `List`, a glass button in a
+ * A pressable control that adapts to where it is: a tinted row in a `List`, a glass button in a
  * toolbar, otherwise the `buttonStyle` you choose. `role="destructive"` carries into every context.
  *
  * @example
@@ -291,7 +291,7 @@ export type VerticalTextFieldProps = Omit<TextareaHTMLAttributes<HTMLTextAreaEle
 /** A single-line field, or with `axis="vertical"` a field that grows to its `lineLimit`. */
 export type TextFieldProps = HorizontalTextFieldProps | VerticalTextFieldProps;
 /**
- * SwiftUI `TextField`: controlled text with a label, an optional `prompt` and keyboard intent from
+ * Single-line controlled text with a label, an optional `prompt` and keyboard intent from
  * `kind`. In a `List` or `Form` it becomes the row; elsewhere it draws a standalone field.
  * `axis="vertical"` grows with its content.
  *
@@ -314,7 +314,7 @@ export type SecureFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type
     prompt?: string;
     textFieldStyle?: TextFieldStyle;
 };
-/** SwiftUI `SecureField`: password entry with secure system input, adapting to a row in a form. */
+/** Password entry with secure system input, adapting to a row in a form. */
 export declare const SecureField: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "onChange" | "onSubmit" | "placeholder" | "size" | "type" | "value"> & {
     label: string;
     value: string;
@@ -336,7 +336,7 @@ export type TextEditorProps = Omit<TextareaHTMLAttributes<HTMLTextAreaElement>,
     prompt?: string;
     textFieldStyle?: TextFieldStyle;
 };
-/** SwiftUI `TextEditor`: multiline text, adapting to a row in a form. */
+/** Multiline text entry, adapting to a row in a form. */
 export declare const TextEditor: import("react").ForwardRefExoticComponent<Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "defaultValue" | "onChange" | "placeholder" | "rows" | "value"> & {
     value: string;
     onChange(value: string): void;

package/dist/public/controls.js

@@ -52,7 +52,7 @@ export function Form(props) {
     return (_jsx(List, { ...props, listStyle: "insetGrouped", scrollDismissesKeyboard: props.scrollDismissesKeyboard ?? 'immediately' }));
 }
 /**
- * SwiftUI `Button`. It adapts to where it is: a tinted row in a `List`, a glass button in a
+ * A pressable control that adapts to where it is: a tinted row in a `List`, a glass button in a
  * toolbar, otherwise the `buttonStyle` you choose. `role="destructive"` carries into every context.
  *
  * @example
@@ -72,9 +72,9 @@ export const Button = forwardRef(function Button({ children, symbol, role, butto
     const resolvedBorderShape = resolveButtonBorderShape(buttonBorderShape);
     const [isPressed, setPressed] = useState(false);
     // A toolbar button labelled with an icon-only Label or a SymbolImage is a glass circle, and so is a
-    // titled button with a symbol: SwiftUI's `Button("New Reminder", systemImage: "plus")` in a toolbar
+    // A titled toolbar button with a symbol uses a circular control.
     // draws only its symbol (iOS 27.0 native reference), the title becoming its accessible name. A bare symbol
-    // with no title is the same circle (SwiftUI's `Button { } label: { Image(systemName:) }`).
+    // An icon-only toolbar button uses the same circle.
     const symbolTitle = toolbar && symbol && typeof children === 'string' && !rest.iconOnly ? children : undefined;
     const bareSymbolName = toolbar && symbol && (children == null || typeof children === 'boolean') && !rest.iconOnly
         ? rest['aria-label']?.trim() || symbol
@@ -236,7 +236,7 @@ function toggleLabel(props, descriptionId) {
  *   options={[{ id: 'home', label: 'Home', symbol: 'house', color: systemColor('red') }]} />
  */
 export function Picker({ pickerStyle = 'menu', selection, onSelectionChange, disabled, ...rest }) {
-    // `ControlStyleProvider disabled` disables a Picker as SwiftUI's `.disabled` does a subtree.
+    // `ControlStyleProvider disabled` disables a Picker throughout its subtree.
     const configuration = useControlStyle({ disabled });
     const props = {
         ...rest,
@@ -276,7 +276,7 @@ const Field = forwardRef(function TextField({ prompt, textFieldStyle, style, ...
     return (_jsx(Fields.TextField, { ...fieldProps, style: style, ref: ref, placeholder: prompt ?? (hidden ? props.label : undefined), variant: variant, labelVisibility: hidden ? 'hidden' : 'visible' }));
 });
 /**
- * SwiftUI `TextField`: controlled text with a label, an optional `prompt` and keyboard intent from
+ * Single-line controlled text with a label, an optional `prompt` and keyboard intent from
  * `kind`. In a `List` or `Form` it becomes the row; elsewhere it draws a standalone field.
  * `axis="vertical"` grows with its content.
  *
@@ -285,12 +285,12 @@ const Field = forwardRef(function TextField({ prompt, textFieldStyle, style, ...
  */
 // The cast keeps single-line refs and events precisely typed when axis is omitted.
 export const TextField = Field;
-/** SwiftUI `SecureField`: password entry with secure system input, adapting to a row in a form. */
+/** Password entry with secure system input, adapting to a row in a form. */
 export const SecureField = forwardRef(function SecureField({ prompt, textFieldStyle, style, ...props }, ref) {
     const variant = useFieldVariant(textFieldStyle);
     return (_jsx(Fields.SecureField, { ...props, style: style, ref: ref, placeholder: prompt ?? (variant !== 'standalone' ? props.label : undefined), variant: variant, labelVisibility: prompt !== undefined || variant !== 'standalone' ? 'hidden' : 'visible' }));
 });
-/** SwiftUI `TextEditor`: multiline text, adapting to a row in a form. */
+/** Multiline text entry, adapting to a row in a form. */
 export const TextEditor = forwardRef(function TextEditor({ prompt, textFieldStyle, style, ...props }, ref) {
     const variant = useFieldVariant(textFieldStyle);
     return (_jsx(Editor, { ...props, minLines: props.minLines ?? (variant === 'row' ? 1 : 3), style: style, ref: ref, placeholder: prompt ?? (variant === 'plain' ? props.label : undefined), variant: variant, labelVisibility: prompt !== undefined || variant !== 'standalone' ? 'hidden' : 'visible' }));

package/dist/public/glass.d.ts

@@ -14,14 +14,13 @@ export type GlassEffectProps = HTMLAttributes<HTMLDivElement> & {
     in?: NamespaceID;
     /** Morph identity within namespace; independent of the DOM id. */
     glassEffectID?: string;
-    /** `glassEffectUnion(id:namespace:)`: effects with one union id draw as one shape. */
+    /** Effects with one union id draw as one shape. */
     glassEffectUnion?: string;
-    /** `glassEffectTransition`. */
+    /** Controls how an identified effect enters or leaves its container. */
     glassEffectTransition?: 'matchedGeometry' | 'materialize' | 'identity';
 };
 /**
- * `glassEffect(_:in:)`: draws Liquid Glass behind its content in the given shape (a
- * capsule by default). Inside a `GlassEffectContainer`, effects with ids morph into one another.
+ * Draws glass behind its content in the given shape, using a capsule by default. Inside a `GlassEffectContainer`, effects with ids morph into one another.
  *
  * @example
  * <GlassEffect glass={Glass.regular.interactive()} shape="circle">

package/dist/public/glass.js

@@ -3,8 +3,7 @@ import { Glass, resolveGlass } from './glassValue.js';
 import { GlassFieldContext } from './fieldContext.js';
 import { GlassEffect as Effect } from '../glass/GlassEffect.js';
 /**
- * `glassEffect(_:in:)`: draws Liquid Glass behind its content in the given shape (a
- * capsule by default). Inside a `GlassEffectContainer`, effects with ids morph into one another.
+ * Draws glass behind its content in the given shape, using a capsule by default. Inside a `GlassEffectContainer`, effects with ids morph into one another.
  *
  * @example
  * <GlassEffect glass={Glass.regular.interactive()} shape="circle">

package/dist/public/navigationTransition.d.ts

@@ -17,7 +17,7 @@ export type ZoomTransitionOptions = Readonly<{
     sourceID: string;
     in: NamespaceID;
 }>;
-/** SwiftUI's navigation transitions. */
+/** Transitions between retained navigation entries. */
 export declare const NavigationTransition: Readonly<{
     automatic: NavigationTransition;
     zoom: (options: ZoomTransitionOptions) => NavigationTransition;

package/dist/public/navigationTransition.js

@@ -4,7 +4,7 @@ import { NavigatorContext } from '../navigation/navigationContext.js';
 import { installZoomDismissDrag } from '../navigation/zoomDrag.js';
 import { registerTransitionSource, registerZoomRequest } from '../navigation/zoomTransition.js';
 const brand = Symbol('satin.navigationTransition');
-/** SwiftUI's navigation transitions. */
+/** Transitions between retained navigation entries. */
 export const NavigationTransition = Object.freeze({
     /** The platform's push: the screen slides in from the trailing edge. */
     automatic: Object.freeze({ [brand]: true, kind: 'automatic' }),

package/dist/public/scroll.d.ts

@@ -34,5 +34,5 @@ export type ScrollViewProps = Omit<HTMLAttributes<HTMLDivElement>, 'id'> & {
     scrollPosition?: never;
     onScrollGeometryChange?: never;
 });
-/** SwiftUI ScrollView with framework-owned restoration and native scrolling. */
+/** A scroll surface with framework-owned restoration and native scrolling. */
 export declare const ScrollView: import("react").ForwardRefExoticComponent<ScrollViewProps & import("react").RefAttributes<ScrollViewHandle>>;

package/dist/public/scroll.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from 'react';
 import { ScrollSurface } from '../scroll/ScrollSurface.js';
-/** SwiftUI ScrollView with framework-owned restoration and native scrolling. */
+/** A scroll surface with framework-owned restoration and native scrolling. */
 export const ScrollView = forwardRef(function ScrollView(props, ref) {
     return _jsx(ScrollSurface, { ...props, ref: ref });
 });

package/dist/public/toolbar.js

@@ -69,7 +69,7 @@ export function ToolbarSpacer({ sizing = 'flexible', placement = 'automatic', })
 /** `ToolbarItemGroup`: its items render as consecutive `ToolbarItem`s of the placement,
  * which share one glass capsule (iOS 26+ draws a group and adjacent items identically). */
 export function ToolbarItemGroup({ children, placement }) {
-    // SwiftUI gives confirmation actions separate capsules, even inside a group.
+    // gives confirmation actions separate capsules, even inside a group.
     if (placement === 'confirmationAction')
         return (_jsx(ToolbarItem, { placement: placement, children: _jsx("div", { "data-satin-toolbar-confirmation-group": "true", children: children }) }));
     return (_jsx(_Fragment, { children: Children.toArray(children).map((child, index) => (_jsx(ToolbarItem, { placement: placement, children: child }, isValidElement(child) && child.key !== null ? child.key : index))) }));

package/dist/root/SatinRoot.js

@@ -159,6 +159,7 @@ export function SatinRoot({ background: legacyBackground, app: suppliedApp, offl
     const downloadedBytes = useRef(0);
     const [launchAttempt, setLaunchAttempt] = useState(0);
     const [glassReady, setGlassReady] = useState(false);
+    const [bundlePrepared, setBundlePrepared] = useState(import.meta.env.DEV || !app);
     const [glassError, setGlassError] = useState(null);
     const [glassFailed, setGlassFailed] = useState(false);
     useLayoutEffect(() => {
@@ -235,10 +236,13 @@ export function SatinRoot({ background: legacyBackground, app: suppliedApp, offl
                                 downloadActivity.current = performance.now();
                                 downloadedBytes.current = progress.loaded;
                             }
-                            // Release launch rings confirm updates; first-install bytes
-                            // still drive readiness/watchdogs without promising an update.
-                            if (app.updateProfile !== 'release')
-                                setLaunchProgress(progress);
+                            // First-install bytes describe a real download in every profile.
+                            // Applied-update confirmation remains a separate successor phase.
+                            setLaunchProgress(progress);
+                        }).then(ready => {
+                            if (!cancelled && ready)
+                                setBundlePrepared(true);
+                            return ready;
                         }),
                     prepareLaunchContent(rootRef.current, contentPreparation.signal),
                 ]);
@@ -489,7 +493,7 @@ export function SatinRoot({ background: legacyBackground, app: suppliedApp, offl
             return;
         return startDevFidelityAssertions(initialHistoryLength.current);
     }, []);
-    return (_jsx(RuntimeContext, { value: runtime, children: _jsxs(MediaPlayerRoot, { onActivityChange: onMediaActivityChange, children: [_jsx("div", { ...props, ref: rootRef, className: className, "data-satin-role": "chrome", "data-satin-root": "true", "data-satin-launch": launch, "data-satin-presentation": presentationPending ? 'preparing' : 'ready', inert: launch !== 'ready' || presentationPending, "data-satin-layout-horizontal": nextLayout.layoutClass.horizontal, "data-satin-layout-vertical": nextLayout.layoutClass.vertical, style: geometryStyles, children: _jsx(AdaptiveTabsContext, { value: tabs, children: _jsx("div", { "data-satin-status-band-source": "scene", children: _jsxs(GlassMaterialRoot, { displacement: glassDisplacement, onLaunchReady: setGlassReady, children: [DeveloperMenu && app && launch === 'ready' ? (_jsx(Suspense, { fallback: null, children: _jsx(DeveloperMenu, {}) })) : null, app ? (_jsx(OrientationGuard, { app: app, width: metrics.safeFrame.width, height: metrics.safeFrame.height, children: _jsx(ReachabilityProvider, { profile: app, offlinePresentation: offlinePresentation, children: children }) })) : (children)] }) }) }) }), launch === 'failed'
+    return (_jsx(RuntimeContext, { value: runtime, children: _jsxs(MediaPlayerRoot, { onActivityChange: onMediaActivityChange, children: [_jsx("div", { ...props, ref: rootRef, className: className, "data-satin-role": "chrome", "data-satin-root": "true", "data-satin-launch": launch, "data-satin-presentation": presentationPending ? 'preparing' : 'ready', inert: launch !== 'ready' || presentationPending, "data-satin-layout-horizontal": nextLayout.layoutClass.horizontal, "data-satin-layout-vertical": nextLayout.layoutClass.vertical, style: geometryStyles, children: _jsx(AdaptiveTabsContext, { value: tabs, children: _jsx("div", { "data-satin-status-band-source": "scene", children: _jsxs(GlassMaterialRoot, { displacement: glassDisplacement, prepared: bundlePrepared, onLaunchReady: setGlassReady, children: [DeveloperMenu && app && launch === 'ready' ? (_jsx(Suspense, { fallback: null, children: _jsx(DeveloperMenu, {}) })) : null, app ? (_jsx(OrientationGuard, { app: app, width: metrics.safeFrame.width, height: metrics.safeFrame.height, children: _jsx(ReachabilityProvider, { profile: app, offlinePresentation: offlinePresentation, children: children }) })) : (children)] }) }) }) }), launch === 'failed'
                     ? createPortal(_jsxs("div", { "data-satin-role": "chrome", "data-satin-launch-error": "true", "data-satin-glass-error": glassError ? true : undefined, role: "alert", style: { zIndex: launchErrorLayer }, children: [!glassError ? (_jsx("img", { className: "satin-launch-error-icon", src: document.querySelector('#satin-launch-screen .satin-launch-icon img')?.src ??
                                     app?.launchScreen?.icon ??
                                     app?.icons[0]?.src, alt: "" })) : null, _jsxs("div", { className: "satin-launch-error-message", children: [_jsx("h1", { children: glassError ? 'Glass Renderer Failed' : 'Unable to Open App' }), glassError ? (_jsx("pre", { style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: `${glassError.code} · ${glassError.stage}\n${glassError.message}${glassError.reason ? `\n${glassError.reason}` : ''}` })) : (_jsx("p", { children: preparationError })), _jsx("button", { type: "button", onClick: async () => {