@stacksjs/mobile 0.75.97 → 0.75.99

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Bundled TypeScript declarations
- * Generated from 8 source files
+ * Generated from 16 source files
  */
 
 import { NativeTab } from 'craft-native/mobile';
@@ -11,17 +11,6 @@ declare function host(): CraftHost | undefined;
 /** Reads the current host, including a bridge injected after this module loaded. */
 declare function getNativeMobileBridge(): CraftMobileBridge | null;
 declare function isNativeMobile(): boolean;
-/**
- * Whether this page runs inside Craft's phone shell, before the bridge exists.
- *
- * Craft installs `window.craft` once the page has finished loading — images
- * and all — so `isNativeMobile()` answers `false` during setup on a phone, and
- * a layout that decides then renders the website's chrome in the app. The
- * transports are there from the start: Android's `CraftAndroid` interface, and
- * on iOS the `craft` message handler. Craft's macOS windows carry that handler
- * too, so on iOS an iPhone or iPad user agent is what makes it the phone app.
- */
-declare function hasNativeMobileHost(): boolean;
 /**
  * Resolves `true` inside the phone shell and `false` in a browser, at a moment
  * when the answer is right.
@@ -32,21 +21,14 @@ declare function hasNativeMobileHost(): boolean;
  * decide something to render anything.
  */
 declare function whenNativeMobile(timeoutMs?: number): Promise<boolean>;
-/**
- * Resolves once the bridge object (`window.craft`) is installed: `true` then,
- * `false` in a browser at once, or after `timeoutMs` in a host that never
- * installs it.
- *
- * Not whenNativeMobile(), which answers `true` as soon as the phone shell is
- * recognisable, before the bridge exists and before anything can be asked of it.
- */
-declare function whenBridgeReady(timeoutMs?: unknown): Promise<boolean>;
 declare function onMobileReady(callback: (event: CraftReadyEvent) => void): () => void;
 declare function withNativeFeedback<T>(action: () => T | Promise<T>): Promise<T>;
+// Each service's async methods wait for a native host's bridge (afterBridge):
+// asked during an older shell's launch, they reached the web fallback, and a
+// secure-storage read answered from localStorage.
 declare const biometrics: BiometricsApi;
 declare const camera: CameraApi;
 declare const device: DeviceApi;
-declare const haptics: HapticsApi;
 declare const lifecycle: LifecycleApi;
 declare const location: LocationApi;
 declare const notifications: NotificationsApi;
@@ -54,6 +36,16 @@ declare const permissions: PermissionsApi;
 declare const secureStorage: SecureStorageApi;
 declare const share: ShareApi;
 declare const appReview: AppReviewApi;
+/**
+ * Haptic feedback: UIImpactFeedbackGenerator, UINotificationFeedbackGenerator
+ * and UISelectionFeedbackGenerator on iOS, a short vibration elsewhere.
+ *
+ * Never held for a bridge still loading, and never rejects: a tap played late
+ * is a wrong tap, and feedback failing must not stop the flow it decorates.
+ * `prepare()` wakes the Taptic Engine ahead of a likely tap (a finger landing
+ * on a pressable), so the tap that follows plays without latency.
+ */
+declare const haptics: HapticsApi;
 /**
  * Deep links, asked of the bridge once there is one.
  *
@@ -72,6 +64,11 @@ declare const keepAwake: KeepAwakeApi;
  * to the Web Speech API.
  */
 declare const speech: SpeechApi;
+/**
+ * Connectivity. A change subscription made before the bridge arrived listened
+ * to the browser's online/offline events only, and never heard the native
+ * monitor; it is made once the bridge is there.
+ */
 declare const network: NetworkApi;
 declare const pushNotifications: PushNotificationsApi;
 declare const health: HealthApi;
@@ -84,8 +81,170 @@ declare const watchConnectivity: WatchConnectivityApi;
  */
 declare const splash: { hide: () => boolean };
 declare const mobile: MobileApi;
+
+// From: src/bridge.ts
+/** The page's window, when there is one. */
+declare function craftHost(): CraftHost | undefined;
+/** `window.craft`, the bridge object, once installed. */
+declare function craftRoot(): Record<string, any> | undefined;
+/**
+ * Whether this page runs inside Craft's phone shell, before the bridge exists.
+ *
+ * Craft installs `window.craft` once the page has finished loading on an older
+ * shell — images and all — so a bridge check answers `false` during setup on
+ * a phone, and a layout that decides then renders the website's chrome in the
+ * app. The transports are there from the start: Android's `CraftAndroid`
+ * interface, and on iOS the `craft` message handler. Craft's macOS windows
+ * carry that handler too, so on iOS an iPhone or iPad user agent is what makes
+ * it the phone app.
+ */
+declare function hasNativeMobileHost(): boolean;
+/** A native host whose bridge object is not installed yet: worth waiting for. */
+declare function bridgePending(): boolean;
+/**
+ * Resolves once the bridge object (`window.craft`) is installed: `true` then,
+ * `false` in a browser at once, or after `timeoutMs` in a host that never
+ * installs it.
+ *
+ * Not whenNativeMobile(), which answers `true` as soon as the phone shell is
+ * recognisable, before the bridge exists and before anything can be asked of it.
+ */
+declare function whenBridgeReady(timeoutMs?: unknown): Promise<boolean>;
+/**
+ * The bridge function at `path` (`'dialog.confirm'`), or null when this host
+ * has none. Synchronous: no waiting for a bridge still on its way.
+ */
+declare function nativeFunctionNow(path: string): ((...args: any[]) => unknown) | null;
+/**
+ * The bridge function at `path`, waiting for a native host's bridge to arrive
+ * first. Null in a browser, on a shell that predates the API, or when the
+ * bridge did not come within `timeoutMs`.
+ */
+declare function nativeFunction(path: string, timeoutMs?: unknown): Promise<((...args: any[]) => unknown) | null>;
+/**
+ * Calls the bridge function at `path`, or `fallback` where there is none.
+ *
+ * Inside a native host whose bridge is still loading, the call is held until
+ * it arrives, so an early call reaches the native implementation rather than
+ * the web one.
+ */
+declare function callNative<T>(path: string, args: unknown[], fallback: () => T | Promise<T>, options?: CallNativeOptions): Promise<T>;
+/**
+ * Runs `run` once a native host's bridge is installed: at once when it is
+ * there or in a browser, after it arrives (or `BRIDGE_WAIT_MS` passes) in a
+ * host still loading it.
+ *
+ * craft-native's services read `window.craft` at call time and take their web
+ * path when it is missing, which during an older shell's launch it is. The
+ * services this package exports call through here, as plain object literals
+ * rather than wrapped at import: a bundler drops an object literal nobody
+ * imports, and could not drop a call made at module scope once minified.
+ */
+declare function afterBridge<T>(run: () => T | Promise<T>, timeoutMs?: unknown): Promise<T>;
+/**
+ * Subscribes once the bridge can take the subscription: at once when it is
+ * there or in a browser, otherwise when it arrives. The returned function
+ * unsubscribes either way, including before the subscription was made.
+ */
+declare function subscribeWhenReady(subscribe: () => (() => void) | void, timeoutMs?: unknown): () => void;
+/** Listens for a Craft DOM event on the window; the detail is passed through. */
+declare function onCraftEvent<T = Record<string, unknown>>(name: string, callback: (detail: T) => void): () => void;
+/**
+ * Reaching Craft's bridge at the right moment.
+ *
+ * Craft's iOS shell injects `window.craft` at document start, but an older
+ * shell installs it once the page has finished loading. A call made before
+ * then used to find no bridge and quietly take the web path: a secure-storage
+ * read answered from localStorage, a confirm drew the browser's own dialog.
+ * Inside a native host, a call now waits for the bridge (briefly: a host that
+ * never installs one gets the web fallback after `BRIDGE_WAIT_MS`), and only a
+ * browser takes the fallback at once.
+ */
+/** How long a call waits for a native host's bridge before using the web fallback. */
+declare const BRIDGE_WAIT_MS: 2500;
 declare interface CraftHost extends EventTarget {
   craft?: unknown
+  CraftAndroid?: unknown
+  webkit?: { messageHandlers?: Record<string, unknown> }
+  document?: Document
+  navigator?: Navigator
+}
+declare interface CallNativeOptions {
+  fallbackOnError?: boolean
+  timeoutMs?: number
+}
+
+// From: src/controls.ts
+/**
+ * Calls `onLongPress` when a finger (or mouse) stays on `element` for
+ * `delay`. The click that follows a long press is swallowed, so a long press
+ * on a link opens its menu without also following it, and the browser's own
+ * callout menu is kept out of the way.
+ */
+declare function observeLongPress(element: HTMLElement, options: LongPressOptions): () => void;
+/** Which of `count` equal segments across `rect` the x coordinate is over, clamped to the ends. */
+declare function segmentAt(x: number, rect: { left: number, width: number }, count: number): number;
+/**
+ * Scrubbing a segmented control: a finger that lands on the chosen segment and
+ * slides drags the thumb across, and lifting chooses where it stopped. A tap
+ * elsewhere stays the button's own click.
+ */
+declare function observeSegmentScrub(track: HTMLElement, options: SegmentScrubOptions): () => void;
+/** The segment an arrow, Home or End key moves to from `index`, or null for any other key. */
+declare function segmentForKey(key: string, index: number, count: number): number | null;
+/** Moves focus to the `index`th tab of a segmented control, as arrow keys do in a tab list. */
+declare function focusSegment(track: HTMLElement, index: number): void;
+/**
+ * Wakes the Taptic Engine as a finger lands on anything marked
+ * `data-native-pressable`, so the tap that follows its press plays at once.
+ *
+ * Listening for touchstart at all is also what makes iOS apply `:active`, the
+ * pressed state the shell's stylesheet draws.
+ */
+declare function installPressables(root: EventTarget): () => void;
+declare interface LongPressOptions {
+  delay?: number
+  tolerance?: number
+  onPressStart?: () => void
+  onPressEnd?: () => void
+  onLongPress: (event: { x: number, y: number }) => void
+}
+declare interface SegmentScrubOptions {
+  count: () => number
+  selected: () => number
+  onPress?: (pressed: boolean) => void
+  onScrub: (index: number) => void
+  onCommit: (index: number) => void
+}
+
+// From: src/events.ts
+/**
+ * The appearance as it stands. The shell writes `--craft-font-scale` and
+ * `data-craft-reduce-*` on the root element before the page runs, so this is
+ * right at setup too; elsewhere it reads the media queries.
+ */
+declare function currentAppearance(): NativeAppearance;
+/** A `craftAppearance` detail, made whole. */
+declare function normalizeAppearance(detail: Partial<NativeAppearance> | null | undefined): NativeAppearance;
+/**
+ * Calls `callback` with the appearance now and whenever the phone's settings
+ * change (Dynamic Type, Reduce Motion, Reduce Transparency, Light/Dark).
+ */
+declare function onAppearance(callback: (appearance: NativeAppearance) => void, options?: { immediate?: boolean }): () => void;
+/** The app came back to the front after `backgroundedMs` away. */
+declare function onResume(callback: (detail: { backgroundedMs: number }) => void): () => void;
+/** iOS is short of memory: drop caches that can be rebuilt. */
+declare function onMemoryWarning(callback: () => void): () => void;
+/** A content-available push arrived. The handler's settling completes it. */
+declare function onSilentPush(handler: (payload: Record<string, unknown>) => unknown): () => void;
+/** iOS woke the app to refresh (BGAppRefreshTask). The handler's settling completes it. */
+declare function onBackgroundRefresh(handler: () => unknown): () => void;
+declare interface NativeAppearance {
+  contentSizeCategory?: string
+  fontScale: number
+  reduceMotion: boolean
+  reduceTransparency: boolean
+  colorScheme: 'light' | 'dark'
 }
 
 // From: src/gestures.ts
@@ -116,17 +275,53 @@ declare function pullDistance(scrollTop: number, fingerTravel: number): number;
  * it disarms. Letting go while armed runs `onRefresh`.
  */
 declare function observePullToRefresh(options: PullToRefreshOptions): () => void;
-/** Where a page scrolls: the window, or a stand-in with the same shape. */
+/**
+ * Where a large-title navigation bar is for a scroll offset.
+ *
+ * The title collapses over its own height. Pulled past the top (iOS's rubber
+ * band, a negative offset) it grows a little, at most 10%, anchored at its
+ * leading edge.
+ */
+declare function largeTitleMetrics(offset: number, height?: number): LargeTitleMetrics;
+/**
+ * Links a navigation bar to the page's scroll, a frame at a time.
+ *
+ * Writes `--native-nav-progress` (0 to 1) and `--native-nav-stretch` on
+ * `element`, so its CSS can fade the material in, move the small title into
+ * the bar and stretch the large one, all on the compositor. Nothing re-renders.
+ */
+declare function observeLargeTitle(element: HTMLElement, options?: LargeTitleOptions): () => void;
+/**
+ * The element a selector names, as a scroll host: for a screen whose content
+ * scrolls inside a container rather than the page. Undefined (the window)
+ * when nothing matches.
+ */
+declare function resolveScrollHost(selector: string | null | undefined): ScrollHost | undefined;
+/**
+ * Where a page scrolls: the window, a scrolling element (a screen that scrolls
+ * inside its own container), or a stand-in with the same shape.
+ */
 declare interface ScrollHost extends EventTarget {
   scrollY?: number
+  scrollTop?: number
   document?: { scrollingElement?: { scrollTop: number } | null }
 }
 declare interface PullToRefreshOptions {
   threshold?: number
-  onPull?: (distance: number, armed: boolean) => void
+  onPull?: (distance: number, armed: boolean, pull: { bounce: number }) => void
   onRefresh: () => unknown | Promise<unknown>
   host?: ScrollHost
 }
+declare interface LargeTitleMetrics {
+  progress: number
+  stretch: number
+}
+declare interface LargeTitleOptions {
+  height?: number
+  title?: HTMLElement | null
+  host?: ScrollHost
+  onChange?: (metrics: LargeTitleMetrics) => void
+}
 
 // From: src/navigation.ts
 /** Whether going back stays inside this app. */
@@ -154,6 +349,17 @@ declare function enterNavTrail(trail: NavTrailEntry[], path: string, limit?: num
 declare function backLabelFor(previous: NavTrailEntry | null, fallback: string, max?: number): string;
 /** The trail for this window: it outlives each screen, not a full reload. */
 declare function navTrail(): NavTrailEntry[];
+/**
+ * The path a back from the screen on show returns to, in its own tab's stack.
+ *
+ * The trail is one list for the window, but the stx router keeps a stack per
+ * tab, so a screen opened in Calendar after a visit to Today goes back to
+ * Calendar, not to whatever was entered last. Answers null at a tab's root,
+ * and undefined when there is no router that keeps tabs to ask.
+ */
+declare function previousScreenPath(): string | null | undefined;
+/** The latest trail entry for `path`, which carries that screen's name. */
+declare function trailEntryFor(trail: NavTrailEntry[], path: string): NavTrailEntry | null;
 /**
  * The in-app path a deep link opens, or null when it is not this app's.
  *
@@ -281,6 +487,402 @@ declare interface IndoorFix {
 }
 type IndoorVerdict = 'indoors' | 'outside' | 'unsure';
 
+// From: src/native.ts
+declare function hostNavigator(): Navigator | undefined;
+/** A rectangle the bridge can serialise: getBoundingClientRect() returns a DOMRect, which it cannot. */
+declare function toNativeRect(rect: { x?: number, y?: number, left?: number, top?: number, width: number, height: number }): NativeRect;
+/** Shows an action sheet: `useActionSheet()(options)`, for a page that keeps the function. */
+declare function useActionSheet(): (options: ActionSheetOptions) => Promise<string | null>;
+/**
+ * Asks before doing something. `await confirmAction({ title: 'Delete this
+ * workout?', confirmLabel: 'Delete', destructive: true })` raises the iOS
+ * destructive-action sheet and resolves `true` when the action was chosen.
+ */
+declare function confirmAction(options: ConfirmActionOptions): Promise<boolean>;
+/**
+ * Shows a context menu beside `element`, the one that was long-pressed.
+ * Resolves with the chosen item's id, or null.
+ */
+declare function showContextMenuFor(element: Element, options: Omit<ContextMenuOptions, 'anchor'>): Promise<string | null>;
+declare function openOnTheWeb(url: string, options: BrowserOpenOptions): BrowserResult;
+declare function symbolKey(name: string, options: SymbolOptions): string;
+declare function downloadOnTheWeb(href: string, filename: string): string | null;
+declare function pickOnTheWeb(types: string[]): Promise<PickedFile | null>;
+declare function screenOrientation(): LockableOrientation | undefined;
+declare const done: () => true;
+declare const no: () => false;
+declare const nothing: () => null;
+declare const dialog: DialogApi;
+declare const contextMenu: ContextMenuApi;
+declare const browser: BrowserApi;
+declare const symbolRequests: Map<string, Promise<string | null>>;
+declare const symbolImages: Map<string, string | null>;
+declare const symbols: SymbolsApi;
+declare const statusBar: StatusBarApi;
+declare const chrome: ChromeApi;
+declare const refresh: RefreshApi;
+declare const background: BackgroundApi;
+declare const clipboard: ClipboardApi;
+declare const db: DatabaseApi;
+declare const files: FilesApi;
+declare const shortcuts: ShortcutsApi;
+declare const widgets: WidgetsApi;
+/**
+ * @defaultValue
+ * ```ts
+ * {
+ *   portrait: 'portrait-primary',
+ *   portraitUpsideDown: 'portrait-secondary',
+ *   landscape: 'landscape',
+ *   landscapeLeft: 'landscape-primary',
+ *   landscapeRight: 'landscape-secondary'
+ * }
+ * ```
+ */
+declare const WEB_ORIENTATIONS: Record<OrientationLock, string>;
+declare const orientation: OrientationApi;
+declare const auth: AuthApi;
+declare const storeKit: StoreKitApi;
+// ---------------------------------------------------------------------------
+// Dialogs
+declare interface DialogApi {
+  alert: (options: AlertOptions) => Promise<void>
+  confirm: (options: ConfirmOptions) => Promise<boolean>
+  actionSheet: (options: ActionSheetOptions) => Promise<string | null>
+}
+declare interface ConfirmActionOptions extends ConfirmOptions {
+  style?: 'sheet' | 'alert'
+  anchor?: NativeRect
+}
+// ---------------------------------------------------------------------------
+// Context menus
+declare interface ContextMenuApi {
+  show: (options: ContextMenuOptions) => Promise<string | null>
+}
+// ---------------------------------------------------------------------------
+// In-app browser
+declare interface BrowserOpenOptions {
+  mode?: 'safari' | 'auth'
+  callbackScheme?: string
+}
+declare interface BrowserResult {
+  url?: string
+  cancelled: boolean
+}
+declare interface BrowserApi {
+  open: (url: string, options?: BrowserOpenOptions) => Promise<BrowserResult>
+}
+// ---------------------------------------------------------------------------
+// SF Symbols
+declare interface SymbolOptions {
+  pointSize?: number
+  weight?: 'ultralight' | 'thin' | 'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'heavy' | 'black'
+  color?: string
+  scale?: 'small' | 'medium' | 'large'
+}
+declare interface SymbolsApi {
+  isAvailable: () => boolean
+  image: (name: string, options?: SymbolOptions) => Promise<string | null>
+  cached: (name: string, options?: SymbolOptions) => string | null | undefined
+  clearCache: () => void
+}
+declare interface StatusBarApi {
+  setStyle: (style: StatusBarStyle) => Promise<boolean>
+}
+declare interface ChromeApi {
+  setUnderPageColor: (color: string) => Promise<boolean>
+  setKeyboardAccessory: (visible: boolean) => Promise<boolean>
+}
+// ---------------------------------------------------------------------------
+// Native pull-to-refresh
+declare interface RefreshApi {
+  isAvailable: () => boolean
+  enable: (options?: { tintColor?: string }) => Promise<boolean>
+  disable: () => Promise<boolean>
+  end: () => Promise<boolean>
+  onRefresh: (callback: () => void) => () => void
+}
+declare interface BackgroundApi {
+  complete: (ok: boolean) => Promise<boolean>
+}
+// ---------------------------------------------------------------------------
+// Clipboard
+declare interface ClipboardApi {
+  write: (text: string) => Promise<boolean>
+  read: () => Promise<string | null>
+}
+// ---------------------------------------------------------------------------
+// The app's own SQLite database (Documents/craft.db)
+declare interface DatabaseExecuteResult {
+  rowsAffected: number
+  lastInsertId: number
+}
+declare interface DatabaseApi {
+  isAvailable: () => boolean
+  query: <T = Record<string, unknown>>(sql: string, params?: unknown[]) => Promise<T[] | null>
+  execute: (sql: string, params?: unknown[]) => Promise<DatabaseExecuteResult | null>
+}
+// ---------------------------------------------------------------------------
+// Files, documents and the camera's scanner
+declare interface PickedFile {
+  name: string
+  path?: string
+  data?: string
+  mimeType?: string
+}
+declare interface ScannedCode {
+  type: string
+  data: string
+}
+declare interface FilesApi {
+  openPDF: (source: string, page?: number) => Promise<boolean>
+  takeScreenshot: () => Promise<string | null>
+  scanQRCode: () => Promise<ScannedCode | null>
+  pickFile: (types?: string[]) => Promise<PickedFile | null>
+  saveFile: (data: string, filename: string, mimeType?: string) => Promise<string | null>
+  downloadFile: (url: string, filename: string) => Promise<string | null>
+}
+// ---------------------------------------------------------------------------
+// Home screen quick actions
+declare interface HomeScreenShortcut {
+  type: string
+  title: string
+  subtitle?: string
+  symbol?: string
+  userInfo?: Record<string, string>
+}
+declare interface ShortcutsApi {
+  set: (shortcuts: HomeScreenShortcut[]) => Promise<boolean>
+  clear: () => Promise<boolean>
+  onShortcut: (callback: (type: string) => void) => () => void
+}
+// ---------------------------------------------------------------------------
+// Home screen widgets (WidgetKit)
+declare interface WidgetsApi {
+  update: (data: Record<string, unknown>) => Promise<boolean>
+  reload: () => Promise<boolean>
+}
+declare interface OrientationApi {
+  lock: (orientation: OrientationLock) => Promise<boolean>
+  unlock: () => Promise<boolean>
+}
+declare interface LockableOrientation { lock?: (orientation: string) => Promise<void>, unlock?: () => void }
+// ---------------------------------------------------------------------------
+// Sign in with Apple
+declare interface AppleSignInResult {
+  userId: string
+  email?: string
+  name?: string
+  identityToken?: string
+  authorizationCode?: string
+}
+declare interface AuthApi {
+  signInWithApple: () => Promise<AppleSignInResult | null>
+}
+// ---------------------------------------------------------------------------
+// In-app purchase (StoreKit 2)
+declare interface StoreProduct {
+  id: string
+  displayName: string
+  description: string
+  price: string
+  displayPrice: string
+}
+declare interface StoreTransaction {
+  transactionId: string
+  productId: string
+}
+declare interface StoreKitApi {
+  isAvailable: () => boolean
+  products: (ids: string[]) => Promise<StoreProduct[]>
+  purchase: (id: string) => Promise<StoreTransaction | null>
+  restore: () => Promise<StoreTransaction[]>
+}
+// ---------------------------------------------------------------------------
+// System chrome
+type StatusBarStyle = 'default' | 'light' | 'dark';
+// ---------------------------------------------------------------------------
+// Orientation
+type OrientationLock = 'portrait' | 'portraitUpsideDown' | 'landscape' | 'landscapeLeft' | 'landscapeRight';
+
+// From: src/refresh-control.ts
+/** Whether an element is laid out in view: connected, and not inside something hidden. */
+declare function isShown(element: HTMLElement): boolean;
+/**
+ * Refreshes the screen `element` belongs to with the native control, for as
+ * long as the returned function is not called. Check `refresh.isAvailable()`
+ * first: a shell without the control needs the web gesture instead.
+ */
+declare function observeNativeRefresh(element: HTMLElement, options: NativeRefreshOptions): () => void;
+declare interface NativeRefreshOptions {
+  tintColor?: string
+  onRefresh: () => unknown
+}
+
+// From: src/sheet-gesture.ts
+/**
+ * Where each detent leaves a panel `height` tall on a `viewport` tall screen:
+ * large shows all of it, medium the bottom half of the screen, and dismissed
+ * none.
+ */
+declare function sheetStops(height: number, viewport: number, detents: readonly SheetDetent[]): SheetStop[];
+/**
+ * Where a released sheet goes.
+ *
+ * A flick (faster than 0.5px/ms) goes on to the next stop in its direction,
+ * past the lowest detent meaning dismissed. A slow release dismisses once the
+ * sheet is more than half way down from its lowest detent, and otherwise
+ * springs back to the nearest detent.
+ */
+declare function settleSheet(state: { y: number, velocity: number, stops: SheetStop[] }): SheetSettle;
+/** iOS's resistance past the top: the further it is pulled, the less it gives. */
+declare function rubberBand(overshoot: number, dimension?: number): number;
+/**
+ * Lets a sheet be dragged by its handles. While dragging, the panel follows
+ * the finger with `is-dragging` set (the stylesheet turns its transition off)
+ * and its parent's `--native-sheet-presence` (1 open, 0 gone) dims the
+ * backdrop to match; on release both are handed back to the stylesheet, which
+ * animates to wherever `onSettle` puts it.
+ */
+declare function observeSheetDrag(options: SheetDragOptions): () => void;
+/**
+ * Holds the page still and out of reach behind `keep`: everything outside it
+ * becomes inert (no taps, no focus, hidden from VoiceOver) and the document
+ * stops scrolling. Returns the release. Nested sheets count, so the page
+ * scrolls again only once the last has closed.
+ */
+declare function lockBackground(keep: HTMLElement): () => void;
+/**
+ * Moves `element` to the end of the body, out of every stacking context and
+ * transform on the way, and returns the way back: to where it was, or out of
+ * the document when that place has gone (the page navigated away).
+ */
+declare function liftToBody(element: HTMLElement): () => void;
+/**
+ * The iOS card presentation: while a large sheet is up, the page behind it
+ * shrinks back from the screen's edges, centred on what was in view. Undone by
+ * calling it with `false`.
+ */
+declare function presentPageAsCard(doc: Document, on: boolean): void;
+/** A flick faster than this (CSS pixels a millisecond) moves on to the next stop. */
+declare const SHEET_FLICK_VELOCITY: 0.5;
+/** A resting place, as the panel's downward offset from its fully open position. */
+declare interface SheetStop {
+  name: SheetSettle
+  y: number
+}
+declare interface SheetDragOptions {
+  panel: HTMLElement
+  handles: HTMLElement[]
+  detents: () => SheetDetent[]
+  detent: () => SheetDetent
+  viewport?: () => number
+  onSettle: (to: SheetSettle) => void
+}
+/**
+ * What makes a bottom sheet behave like a UISheetPresentationController:
+ * dragged by its grabber or header, flicked away, resting at a medium or a
+ * large detent, and holding the page behind it still and out of reach.
+ */
+type SheetDetent = 'medium' | 'large';
+type SheetSettle = SheetDetent | 'dismiss';
+
+// From: src/sheets.ts
+/**
+ * Keeps Tab and Shift+Tab inside `container`: called from a keydown listener,
+ * it moves focus from one end to the other instead of out of it.
+ */
+declare function trapFocus(container: HTMLElement, event: KeyboardEvent): void;
+/**
+ * An alert or action sheet drawn in HTML. Resolves with the chosen action's
+ * id, or null when it is dismissed or Cancel is chosen.
+ */
+declare function presentChoice(options: ChoiceOptions): Promise<string | null>;
+declare function presentAlert(options: AlertOptions): Promise<void>;
+declare function presentConfirm(options: ConfirmOptions): Promise<boolean>;
+declare function presentActionSheet(options: ActionSheetOptions): Promise<string | null>;
+/** Where a menu of `size` opens beside `anchor` within a `viewport`, 12px clear of its edges. */
+declare function placeMenu(anchor: NativeRect, size: { width: number, height: number }, viewport: { width: number, height: number }): { top: number, left: number, origin: string };
+/**
+ * A context menu drawn in HTML over a blurred page, beside the element that
+ * was pressed. Resolves with the chosen item's id, or null when dismissed.
+ */
+declare function presentContextMenu(options: ContextMenuOptions): Promise<string | null>;
+declare interface DialogAction {
+  id: string
+  title: string
+  style?: DialogActionStyle
+}
+/** A rectangle in CSS pixels relative to the viewport, as getBoundingClientRect() reports. */
+declare interface NativeRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+declare interface ChoiceOptions {
+  variant: 'alert' | 'sheet'
+  title?: string
+  message?: string
+  actions: DialogAction[]
+  cancelLabel?: string
+}
+declare interface ContextMenuItem {
+  id: string
+  title: string
+  symbol?: string
+  icon?: string
+  destructive?: boolean
+  disabled?: boolean
+}
+declare interface ContextMenuOptions {
+  items: ContextMenuItem[]
+  anchor: NativeRect
+  title?: string
+}
+declare interface AlertOptions {
+  title: string
+  message?: string
+  okLabel?: string
+}
+declare interface ConfirmOptions {
+  title: string
+  message?: string
+  confirmLabel?: string
+  cancelLabel?: string
+  destructive?: boolean
+}
+declare interface ActionSheetOptions {
+  title?: string
+  message?: string
+  actions: DialogAction[]
+  anchor?: NativeRect
+  cancelLabel?: string
+}
+type DialogActionStyle = 'default' | 'destructive' | 'cancel';
+
+// From: src/shell.ts
+/** Writes an appearance where CSS can read it: `--native-font-scale` and `data-native-reduce-*`. */
+declare function applyAppearance(root: HTMLElement, appearance: NativeAppearance): void;
+/**
+ * The colour behind the page: the first opaque background of the body or the
+ * root element. The under-page area should read as more of the page when it
+ * is pulled past its top or bottom, not as a white or black band.
+ */
+declare function pageBackground(doc: Document): string | null;
+/** Whether the page draws dark: the `.dark` class, or the system's preference where the app follows it. */
+declare function pageIsDark(doc: Document): boolean;
+/**
+ * Keeps the native chrome in step with the page until the returned function
+ * is called: on install, whenever the colour scheme flips (the `.dark` class
+ * or the system's), after each navigation, and on every appearance change.
+ */
+declare function installNativeChrome(doc: Document, options?: NativeChromeOptions): () => void;
+declare interface NativeChromeOptions {
+  root?: HTMLElement
+  keyboardAccessory?: boolean
+}
+
 // From: src/spotlight.ts
 /**
  * Read configured kinds, leaving out any that could not work.
@@ -484,6 +1086,20 @@ declare interface SpotlightIndex {
 declare function readTabLinks(nav: ParentNode): TabLink[];
 /** The native bar's description of those links: the tabs, and which is current. */
 declare function nativeTabs(links: TabLink[]): { tabs: NativeTab[], selected?: string };
+/** Whether the stx router runs the tabs itself (`data-stx-nav="tab"`, re-select included). */
+declare function routerHandlesTabs(): boolean;
+/**
+ * Choosing the tab already current scrolls its screen back to the top, as on
+ * iOS, and announces `stx:tabreselect` { href } for a screen that wants to do
+ * more (a list that resets its filter).
+ *
+ * The stx router does this itself for `data-stx-nav="tab"` links, popping to
+ * the tab's root on a second choice; this covers a router that predates tabs,
+ * and stands aside wherever the router has them.
+ */
+declare function handleTabReselect(nav: HTMLElement, options?: TabReselectOptions): () => void;
+/** Marks `element` as covering the tab bar, or no longer, and says so. */
+declare function coverTabBar(element: Element, covering: boolean): void;
 /**
  * Mirror `nav`'s tabs into the native tab bar, for as long as the returned
  * function is not called. Answers null when there is no native bar, and the
@@ -491,6 +1107,12 @@ declare function nativeTabs(links: TabLink[]): { tabs: NativeTab[], selected?: s
  */
 declare function mirrorTabBar(nav: HTMLElement, options?: MirrorTabBarOptions): (() => void) | null;
 declare const tabBar: TabBarApi;
+/**
+ * What an open sheet raises when it starts or stops covering the tab bar. A
+ * sheet on iOS slides up over the tab bar; the native bar is drawn above the
+ * page, so while one is up the bar steps aside instead.
+ */
+declare const TAB_BAR_COVER_EVENT: 'stacks:tab-bar-cover';
 declare interface TabBarApi {
   isAvailable: () => boolean
   set: (tabs: NativeTab[], options?: { selected?: string, tint?: string, tintDark?: string }) => boolean
@@ -506,6 +1128,9 @@ declare interface TabLink {
   badge: string
   current: boolean
 }
+declare interface TabReselectOptions {
+  scrollToTop?: () => void
+}
 declare interface MirrorTabBarOptions {
   hidden?: () => boolean
   api?: TabBarApi
@@ -587,6 +1212,22 @@ declare interface MobileApi {
   health: HealthApi
   liveActivities: LiveActivitiesApi
   watchConnectivity: WatchConnectivityApi
+  dialog: import('./native').DialogApi
+  contextMenu: import('./native').ContextMenuApi
+  browser: import('./native').BrowserApi
+  symbols: import('./native').SymbolsApi
+  statusBar: import('./native').StatusBarApi
+  chrome: import('./native').ChromeApi
+  refresh: import('./native').RefreshApi
+  background: import('./native').BackgroundApi
+  clipboard: import('./native').ClipboardApi
+  db: import('./native').DatabaseApi
+  files: import('./native').FilesApi
+  shortcuts: import('./native').ShortcutsApi
+  widgets: import('./native').WidgetsApi
+  orientation: import('./native').OrientationApi
+  auth: import('./native').AuthApi
+  storeKit: import('./native').StoreKitApi
   isNativeMobile: () => boolean
   whenNative: (timeoutMs?: number) => Promise<boolean>
   onReady: (callback: (event: CraftReadyEvent) => void) => () => void
@@ -683,6 +1324,7 @@ declare interface HapticsApi {
   notification: (type?: HapticNotificationType) => Promise<void>
   selection: () => Promise<void>
   vibrate: (pattern: number[]) => Promise<void>
+  prepare: (kind?: HapticKind) => Promise<void>
 }
 declare interface PermissionsApi {
   check: (permission: PermissionType) => Promise<PermissionStatus>
@@ -872,6 +1514,7 @@ type PermissionStatus = 'granted' | 'denied' | 'undetermined' | 'restricted';
  */
 type BiometricType = 'faceId' | 'touchId' | 'fingerprint' | 'face' | 'iris' | 'none';
 type AppState = 'active' | 'inactive' | 'background';
+type HapticKind = 'impact' | 'notification' | 'selection';
 type HealthDataType = | 'steps'
   | 'heartRate'
   | 'activeEnergy'
@@ -889,6 +1532,6 @@ type HealthWorkoutActivity = | 'running' | 'cycling' | 'walking' | 'hiking' | 's
   | 'stairClimbing' | 'yoga' | 'pilates' | 'strength' | 'hiit' | 'crossTraining'
   | 'crossCountrySkiing' | 'skiing' | 'paddling' | 'climbing' | 'dance' | 'mobility' | 'other';
 
-export { normalizeDeepLinkURL, getNativeMobileBridge, isNativeMobile, hasNativeMobileHost, whenNativeMobile, whenBridgeReady, onMobileReady, withNativeFeedback, biometrics, camera, device, haptics, lifecycle, location, notifications, permissions, secureStorage, share, appReview, deepLinks, keepAwake, speech, network, pushNotifications, health, liveActivities, watchConnectivity, splash, mobile, pageScrollTop, observePageScroll, pullDistance, observePullToRefresh, ScrollHost, PullToRefreshOptions, canGoBack, goBack, enterNavTrail, backLabelFor, navTrail, deepLinkPath, followDeepLinks, HistoryHost, NavTrailEntry, fixDistance, usableFixes, routeStats, paceLabel, speedLabel, createRouteRecorder, ROUTE_GAP_S, RouteFix, RouteStats, RouteStatsOptions, RouteRecorderOptions, RouteRecorder, indoorVerdict, typedDistanceKm, INDOOR_CHECK_AFTER_S, IndoorFix, IndoorVerdict, readSpotlightKinds, spotlightKind, spotlightAction, spotlightSlot, spotlightActions, spotlightActivityTypes, spotlightTitle, placeSpotlightItem, removeSpotlightItem, spotlightRoute, readSpotlightEntries, spotlightBridge, createSpotlightIndex, onSpotlightTap, MAX_SPOTLIGHT_SLOTS_PER_KIND, SpotlightKind, SpotlightKindInput, SpotlightItem, SpotlightEntry, SpotlightKindsResult, SpotlightPlacement, SpotlightBridge, SpotlightIndexOptions, SpotlightIndex, readTabLinks, nativeTabs, mirrorTabBar, tabBar, TabBarApi, TabLink, MirrorTabBarOptions, CraftMobileCapabilities, CraftMobileBridge, CraftReadyEvent, MobileApi, DeviceInfo, DeviceCapabilities, CameraOptions, PhotoResult, Location, LocationOptions, LocationRecordingState, LocationRecordingResult, ShareOptions, NotificationOptions, DeviceApi, HapticsApi, PermissionsApi, CameraApi, BiometricsApi, SecureStorageApi, LocationApi, ShareApi, LifecycleApi, NotificationsApi, KeepAwakeApi, SpeechOptions, SpeechApi, DeepLinksApi, NetworkStatus, NetworkApi, AppReviewApi, PushNotificationsApi, HealthDataOptions, HealthDataResult, HealthWorkoutLocation, HealthWorkout, HealthWorkoutResult, HealthWorkoutQuery, HealthWorkoutSample, HealthDailyValue, HealthAuthorizationOptions, HealthApi, LiveActivityState, LiveActivityOptions, LiveActivitiesApi, WatchConnectivityApi, HapticStyle, HapticNotificationType, PermissionType, PermissionStatus, BiometricType, AppState, HealthDataType, HealthDailyType, HealthWorkoutType, HealthWorkoutActivity };
+export { normalizeDeepLinkURL, getNativeMobileBridge, isNativeMobile, whenNativeMobile, onMobileReady, withNativeFeedback, biometrics, camera, device, lifecycle, location, notifications, permissions, secureStorage, share, appReview, haptics, deepLinks, keepAwake, speech, network, pushNotifications, health, liveActivities, watchConnectivity, splash, mobile, craftHost, craftRoot, hasNativeMobileHost, bridgePending, whenBridgeReady, nativeFunctionNow, nativeFunction, callNative, afterBridge, subscribeWhenReady, onCraftEvent, BRIDGE_WAIT_MS, CraftHost, CallNativeOptions, observeLongPress, segmentAt, observeSegmentScrub, segmentForKey, focusSegment, installPressables, LongPressOptions, SegmentScrubOptions, currentAppearance, normalizeAppearance, onAppearance, onResume, onMemoryWarning, onSilentPush, onBackgroundRefresh, NativeAppearance, pageScrollTop, observePageScroll, pullDistance, observePullToRefresh, largeTitleMetrics, observeLargeTitle, resolveScrollHost, ScrollHost, PullToRefreshOptions, LargeTitleMetrics, LargeTitleOptions, canGoBack, goBack, enterNavTrail, backLabelFor, navTrail, previousScreenPath, trailEntryFor, deepLinkPath, followDeepLinks, HistoryHost, NavTrailEntry, fixDistance, usableFixes, routeStats, paceLabel, speedLabel, createRouteRecorder, ROUTE_GAP_S, RouteFix, RouteStats, RouteStatsOptions, RouteRecorderOptions, RouteRecorder, indoorVerdict, typedDistanceKm, INDOOR_CHECK_AFTER_S, IndoorFix, IndoorVerdict, toNativeRect, useActionSheet, confirmAction, showContextMenuFor, dialog, contextMenu, browser, symbols, statusBar, chrome, refresh, background, clipboard, db, files, shortcuts, widgets, orientation, auth, storeKit, DialogApi, ConfirmActionOptions, ContextMenuApi, BrowserOpenOptions, BrowserResult, BrowserApi, SymbolOptions, SymbolsApi, StatusBarApi, ChromeApi, RefreshApi, BackgroundApi, ClipboardApi, DatabaseExecuteResult, DatabaseApi, PickedFile, ScannedCode, FilesApi, HomeScreenShortcut, ShortcutsApi, WidgetsApi, OrientationApi, AppleSignInResult, AuthApi, StoreProduct, StoreTransaction, StoreKitApi, StatusBarStyle, OrientationLock, ActionSheetOptions, AlertOptions, ChoiceOptions, ConfirmOptions, ContextMenuItem, ContextMenuOptions, DialogAction, DialogActionStyle, NativeRect, isShown, observeNativeRefresh, NativeRefreshOptions, sheetStops, settleSheet, rubberBand, observeSheetDrag, lockBackground, liftToBody, presentPageAsCard, SHEET_FLICK_VELOCITY, SheetStop, SheetDragOptions, SheetDetent, SheetSettle, trapFocus, presentChoice, presentAlert, presentConfirm, presentActionSheet, placeMenu, presentContextMenu, applyAppearance, pageBackground, pageIsDark, installNativeChrome, NativeChromeOptions, readSpotlightKinds, spotlightKind, spotlightAction, spotlightSlot, spotlightActions, spotlightActivityTypes, spotlightTitle, placeSpotlightItem, removeSpotlightItem, spotlightRoute, readSpotlightEntries, spotlightBridge, createSpotlightIndex, onSpotlightTap, MAX_SPOTLIGHT_SLOTS_PER_KIND, SpotlightKind, SpotlightKindInput, SpotlightItem, SpotlightEntry, SpotlightKindsResult, SpotlightPlacement, SpotlightBridge, SpotlightIndexOptions, SpotlightIndex, readTabLinks, nativeTabs, routerHandlesTabs, handleTabReselect, coverTabBar, mirrorTabBar, tabBar, TAB_BAR_COVER_EVENT, TabBarApi, TabLink, TabReselectOptions, MirrorTabBarOptions, CraftMobileCapabilities, CraftMobileBridge, CraftReadyEvent, MobileApi, DeviceInfo, DeviceCapabilities, CameraOptions, PhotoResult, Location, LocationOptions, LocationRecordingState, LocationRecordingResult, ShareOptions, NotificationOptions, DeviceApi, HapticsApi, PermissionsApi, CameraApi, BiometricsApi, SecureStorageApi, LocationApi, ShareApi, LifecycleApi, NotificationsApi, KeepAwakeApi, SpeechOptions, SpeechApi, DeepLinksApi, NetworkStatus, NetworkApi, AppReviewApi, PushNotificationsApi, HealthDataOptions, HealthDataResult, HealthWorkoutLocation, HealthWorkout, HealthWorkoutResult, HealthWorkoutQuery, HealthWorkoutSample, HealthDailyValue, HealthAuthorizationOptions, HealthApi, LiveActivityState, LiveActivityOptions, LiveActivitiesApi, WatchConnectivityApi, HapticStyle, HapticNotificationType, PermissionType, PermissionStatus, BiometricType, AppState, HapticKind, HealthDataType, HealthDailyType, HealthWorkoutType, HealthWorkoutActivity };
 export { NativeTab } from 'craft-native/mobile';
 export { NativeTabBarOptions } from 'craft-native/mobile';