@mrmeg/expo-ui 0.27.1 → 0.28.0

package/dist/lib/popoverPlacement.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Side and height cap for a native popover.
+ *
+ * `@rn-primitives/popover` places native content on the requested side and,
+ * when it does not fit, clamps it to the screen edge instead of flipping, so an
+ * oversized popover covers its own trigger or sits under the system bars.
+ * `PopoverContent` resolves the side and a height cap here first; the content
+ * then scrolls inside the cap. Web never calls this: Radix flips on its own.
+ */
+export type PopoverSide = "top" | "bottom";
+export interface PopoverPlacementInput {
+    /** Requested side; undefined means the primitive's default, `"bottom"`. */
+    side: PopoverSide | undefined;
+    sideOffset: number;
+    /** The trigger's measured screen frame, or null until the primitive measures it. */
+    trigger: {
+        pageY: number;
+        height: number;
+    } | null;
+    screenHeight: number;
+    insets: {
+        top?: number;
+        bottom?: number;
+    };
+    /** The content's uncapped height, card chrome included; undefined while unknown. */
+    naturalHeight: number | undefined;
+    avoidCollisions: boolean;
+}
+export interface PopoverPlacement {
+    side: PopoverSide;
+    /** Undefined when the popover is not capped. */
+    maxHeight: number | undefined;
+}
+/** Smallest cap; with less room than this the primitive's inset clamp places the card. */
+export declare const POPOVER_MIN_CAP = 120;
+export declare function resolvePopoverPlacement({ side, sideOffset, trigger, screenHeight, insets, naturalHeight, avoidCollisions, }: PopoverPlacementInput): PopoverPlacement;

package/dist/lib/popoverPlacement.js

@@ -0,0 +1,29 @@
+/**
+ * Side and height cap for a native popover.
+ *
+ * `@rn-primitives/popover` places native content on the requested side and,
+ * when it does not fit, clamps it to the screen edge instead of flipping, so an
+ * oversized popover covers its own trigger or sits under the system bars.
+ * `PopoverContent` resolves the side and a height cap here first; the content
+ * then scrolls inside the cap. Web never calls this: Radix flips on its own.
+ */
+/** Smallest cap; with less room than this the primitive's inset clamp places the card. */
+export const POPOVER_MIN_CAP = 120;
+export function resolvePopoverPlacement({ side, sideOffset, trigger, screenHeight, insets, naturalHeight, avoidCollisions, }) {
+    const requested = side ?? "bottom";
+    if (!avoidCollisions || !trigger) {
+        return { side: requested, maxHeight: undefined };
+    }
+    const room = {
+        top: trigger.pageY - sideOffset - (insets.top ?? 0),
+        bottom: screenHeight - (insets.bottom ?? 0) - (trigger.pageY + trigger.height + sideOffset),
+    };
+    const opposite = requested === "top" ? "bottom" : "top";
+    // Without the natural height (not measured yet, or content that scrolls
+    // itself) there is nothing to compare, so only cap the requested side.
+    const flips = naturalHeight !== undefined &&
+        naturalHeight > room[requested] &&
+        room[opposite] > room[requested];
+    const chosen = flips ? opposite : requested;
+    return { side: chosen, maxHeight: Math.max(room[chosen], POPOVER_MIN_CAP) };
+}

package/dist/lib/themedStyles.d.ts

@@ -1,4 +1,4 @@
-import { type Theme } from "../constants/colors";
+import { type Theme } from "../constants/colors.js";
 /**
  * Registers theme-dependent styles at module scope so react-native-web
  * inserts their CSS rules into the sheet before the prerendered document

package/dist/lib/useAnimatedValue.d.ts

@@ -0,0 +1,15 @@
+import { Animated } from "react-native";
+/**
+ * An `Animated.Value` created once, on the first render, and stable for the
+ * component's lifetime — React Native's `useAnimatedValue`, which
+ * react-native-web 0.21 does not export.
+ *
+ * Replaces `useRef(new Animated.Value(x)).current`, which built and discarded
+ * a value on every render and read a ref during render, so the React Compiler
+ * skipped the whole component. A lazy state initializer is allocated once and
+ * returns a plain value the compiler can reason about. Like the ref version,
+ * only the first render's `initialValue` is used.
+ *
+ * Private to the package: not re-exported from `lib/index.ts`.
+ */
+export declare function useAnimatedValue(initialValue: number): Animated.Value;

package/dist/lib/useAnimatedValue.js

@@ -0,0 +1,19 @@
+import { useState } from "react";
+import { Animated } from "react-native";
+/**
+ * An `Animated.Value` created once, on the first render, and stable for the
+ * component's lifetime — React Native's `useAnimatedValue`, which
+ * react-native-web 0.21 does not export.
+ *
+ * Replaces `useRef(new Animated.Value(x)).current`, which built and discarded
+ * a value on every render and read a ref during render, so the React Compiler
+ * skipped the whole component. A lazy state initializer is allocated once and
+ * returns a plain value the compiler can reason about. Like the ref version,
+ * only the first render's `initialValue` is used.
+ *
+ * Private to the package: not re-exported from `lib/index.ts`.
+ */
+export function useAnimatedValue(initialValue) {
+    const [value] = useState(() => new Animated.Value(initialValue));
+    return value;
+}

package/dist/lib/webHitTarget.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Web pointer targets. react-native-web ignores `hitSlop`, so a control whose
+ * drawn box is shorter than `spacing.touchTarget` (44) grows its target on web
+ * with a transparent, absolutely positioned child inside the drawn box. The
+ * Pressable root keeps its rect (popover and tooltip anchors do not move),
+ * layout does not change, and a click on the child bubbles to the root.
+ *
+ * The default extends vertically only: two controls in an 8pt-gap row must
+ * never share a hit region. A caller `hitSlop` is used as given, like native.
+ * Used by `Button`, `Toggle` and `ToggleGroup` items.
+ */
+import React from "react";
+import { type PressableProps } from "react-native";
+export type HitInsets = {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+/** Slop per side that brings `height` up to `spacing.touchTarget`; 0 when it already is. */
+export declare const verticalSlopFor: (height: number) => number;
+/**
+ * Web insets for the hit extender: the default vertical slop for `height`, or
+ * a caller `hitSlop` (a number on all four sides, insets as given, missing
+ * sides 0). `null` when nothing extends (`hitSlop={0}` opts out).
+ */
+export declare function getWebHitInsets(hitSlop: PressableProps["hitSlop"], height: number): HitInsets | null;
+interface WebHitTargetProps {
+    insets: HitInsets | null;
+    /** The drawn box's border width: an absolute child sits against the padding box, inside the border. */
+    border?: number;
+    testID?: string;
+}
+/**
+ * The transparent hit extender. Render it as the last child of the drawn box
+ * (so it paints above the content); nothing on native or when `insets` is null.
+ * Hidden from assistive tech: the control itself is the accessible element.
+ */
+export declare function WebHitTarget({ insets, border, testID }: WebHitTargetProps): React.JSX.Element | null;
+export {};

package/dist/lib/webHitTarget.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Platform, View } from "react-native";
+import { spacing } from "../constants/spacing.js";
+/** Slop per side that brings `height` up to `spacing.touchTarget`; 0 when it already is. */
+export const verticalSlopFor = (height) => Math.ceil(Math.max(0, spacing.touchTarget - height) / 2);
+/**
+ * Web insets for the hit extender: the default vertical slop for `height`, or
+ * a caller `hitSlop` (a number on all four sides, insets as given, missing
+ * sides 0). `null` when nothing extends (`hitSlop={0}` opts out).
+ */
+export function getWebHitInsets(hitSlop, height) {
+    if (hitSlop === undefined || hitSlop === null) {
+        const slop = verticalSlopFor(height);
+        return slop > 0 ? { top: slop, bottom: slop, left: 0, right: 0 } : null;
+    }
+    const insets = typeof hitSlop === "number"
+        ? { top: hitSlop, bottom: hitSlop, left: hitSlop, right: hitSlop }
+        : { top: hitSlop.top ?? 0, bottom: hitSlop.bottom ?? 0, left: hitSlop.left ?? 0, right: hitSlop.right ?? 0 };
+    return insets.top || insets.bottom || insets.left || insets.right ? insets : null;
+}
+/**
+ * The transparent hit extender. Render it as the last child of the drawn box
+ * (so it paints above the content); nothing on native or when `insets` is null.
+ * Hidden from assistive tech: the control itself is the accessible element.
+ */
+export function WebHitTarget({ insets, border = 0, testID = "hit-target" }) {
+    if (Platform.OS !== "web" || !insets)
+        return null;
+    return (_jsx(View, { testID: testID, "aria-hidden": true, importantForAccessibility: "no-hide-descendants", focusable: false, style: {
+            position: "absolute",
+            // `0 - n` keeps a 0 inset at +0 (a unary minus would give -0).
+            top: 0 - (insets.top + border),
+            bottom: 0 - (insets.bottom + border),
+            left: 0 - (insets.left + border),
+            right: 0 - (insets.right + border),
+        } }));
+}

package/dist/state/feedbackStore.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which interactions may vibrate.
+ *
+ * - `"off"`: never.
+ * - `"selection"` (default): state changes — Switch, Checkbox, Toggle,
+ *   ToggleGroup, SegmentedControl.
+ * - `"all"`: selection plus a light tap on press for Button, pressable Card
+ *   and Item, and every `useScalePress` consumer that has not opted out.
+ *
+ * Web never vibrates regardless of the setting.
+ */
+export type HapticsSetting = "off" | "selection" | "all";
+export type FeedbackStore = {
+    haptics: HapticsSetting;
+    setHaptics: (setting: HapticsSetting) => void;
+};
+/**
+ * Feedback settings the package's controls consult at event time. Set it
+ * through `UIProvider`'s `haptics` prop or `setHaptics()`; read it in a
+ * component with `useFeedbackStore((s) => s.haptics)`.
+ */
+export declare const useFeedbackStore: import("zustand").UseBoundStore<import("zustand").StoreApi<FeedbackStore>>;
+/** Imperative form of `UIProvider`'s `haptics` prop, for app startup code. */
+export declare function setHaptics(setting: HapticsSetting): void;

package/dist/state/feedbackStore.js

@@ -0,0 +1,16 @@
+import { create } from "zustand";
+/**
+ * Feedback settings the package's controls consult at event time. Set it
+ * through `UIProvider`'s `haptics` prop or `setHaptics()`; read it in a
+ * component with `useFeedbackStore((s) => s.haptics)`.
+ */
+export const useFeedbackStore = create((set) => ({
+    haptics: "selection",
+    setHaptics: (setting) => {
+        set({ haptics: setting });
+    },
+}));
+/** Imperative form of `UIProvider`'s `haptics` prop, for app startup code. */
+export function setHaptics(setting) {
+    useFeedbackStore.getState().setHaptics(setting);
+}

package/dist/state/globalUIStore.d.ts

@@ -7,6 +7,8 @@
  * Methods:
  * - show({ type, title, messages, duration, loading, action }): displays a notification
  * - hide(): hides the current notification
+ * - setNotificationOffset(key, { top, bottom }) / clearNotificationOffset(key):
+ *   keep toasts clear of a tab bar or floating header (use `useNotificationOffset`)
  *
  * Notifications auto-dismiss after `DEFAULT_NOTIFICATION_DURATION` unless a
  * `duration` is given. Pass `duration: 0` to keep one up until dismissed;
@@ -35,11 +37,36 @@ export type GlobalNotificationAlert = {
     position?: GlobalNotificationPosition;
     action?: GlobalNotificationAction;
 };
+/**
+ * Extra distance a toast keeps from a window edge, measured from that edge and
+ * including any safe-area inset there — the number `useBottomTabBarHeight()`
+ * returns for a JS tab bar, or a native tab bar's height plus the bottom
+ * inset. `Notification` sits `spacing.sm` past the largest of the inset, the
+ * registered offsets and its 12 pt floor, so a bottom toast clears a tab bar
+ * and a top one clears a floating header. Register with
+ * `useNotificationOffset()` (`@mrmeg/expo-ui/hooks`) from the layout that
+ * owns the bar; the offset lasts while that layout is mounted.
+ */
+export type NotificationOffset = {
+    top?: number;
+    bottom?: number;
+};
 export type GlobalUIState = {
     alert: GlobalNotificationAlert | null;
+    /** Registered offsets by registrant key; see {@link NotificationOffset}. */
+    notificationOffsets: Record<string, NotificationOffset>;
 };
 export type GlobalUIActions = {
     show: (alert: Omit<GlobalNotificationAlert, "show">) => void;
     hide: () => void;
+    /** Register (or update) the offset for one registrant. */
+    setNotificationOffset: (key: string, offset: NotificationOffset) => void;
+    /** Remove one registrant's offset. */
+    clearNotificationOffset: (key: string) => void;
 };
+/**
+ * The effective offset per edge: the largest registered value, 0 with none.
+ * Read it with `useStore(globalUIStore, selectNotificationOffset)`.
+ */
+export declare const selectNotificationOffset: (state: Pick<GlobalUIState, "notificationOffsets">) => Required<NotificationOffset>;
 export declare const globalUIStore: import("zustand").UseBoundStore<import("zustand").StoreApi<GlobalUIState & GlobalUIActions>>;

package/dist/state/globalUIStore.js

@@ -1,8 +1,24 @@
 import { create } from "zustand";
 /** Auto-dismiss delay applied when `show()` is called without a `duration`. */
 export const DEFAULT_NOTIFICATION_DURATION = 4000;
+/**
+ * The effective offset per edge: the largest registered value, 0 with none.
+ * Read it with `useStore(globalUIStore, selectNotificationOffset)`.
+ */
+export const selectNotificationOffset = (state) => {
+    let top = 0;
+    let bottom = 0;
+    for (const offset of Object.values(state.notificationOffsets)) {
+        if (offset.top !== undefined && offset.top > top)
+            top = offset.top;
+        if (offset.bottom !== undefined && offset.bottom > bottom)
+            bottom = offset.bottom;
+    }
+    return { top, bottom };
+};
 export const globalUIStore = create((set) => ({
     alert: null,
+    notificationOffsets: {},
     show: (alert) => set({
         alert: {
             ...alert,
@@ -13,4 +29,11 @@ export const globalUIStore = create((set) => ({
         },
     }),
     hide: () => set({ alert: null }),
+    setNotificationOffset: (key, offset) => set((state) => ({ notificationOffsets: { ...state.notificationOffsets, [key]: offset } })),
+    clearNotificationOffset: (key) => set((state) => {
+        if (!(key in state.notificationOffsets))
+            return state;
+        const { [key]: _removed, ...rest } = state.notificationOffsets;
+        return { notificationOffsets: rest };
+    }),
 }));

package/dist/state/index.d.ts

@@ -1,5 +1,7 @@
-export * from "./globalUIStore";
-export * from "./notify";
-export * from "./SsrViewportContext";
-export * from "./themeStore";
-export * from "./themeColorScope";
+export * from "./globalUIStore.js";
+export * from "./notify.js";
+export * from "./SsrViewportContext.js";
+export * from "./themeStore.js";
+export * from "./themeColorScope.js";
+export * from "./initialScheme.js";
+export * from "./feedbackStore.js";

package/dist/state/index.js

@@ -3,3 +3,5 @@ export * from "./notify.js";
 export * from "./SsrViewportContext.js";
 export * from "./themeStore.js";
 export * from "./themeColorScope.js";
+export * from "./initialScheme.js";
+export * from "./feedbackStore.js";

package/dist/state/initialScheme.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from "react";
+import type { ResolvedTheme } from "./themeStore.js";
+/**
+ * The scheme the FIRST render should use, before the persisted preference has
+ * been read — a server-render hint.
+ *
+ * On web the theme store boots `system` + `light` and only reads the visitor's
+ * preference in `syncThemeFromEnvironment()` after the first commit, so the
+ * server and the hydrating client both paint light and a dark-mode visitor
+ * gets a flash (and any `useId`-dependent markup that differs by scheme
+ * mismatches). An app that knows the scheme on both sides — the template
+ * mirrors it into a `color-scheme` cookie the server and `document.cookie`
+ * both read — wraps its root in this provider; `useTheme()` uses the hint
+ * until `hasLoadedTheme` is true, then the store as always. Mount it ABOVE the
+ * first `useTheme()` caller (the root layout itself usually reads the theme
+ * for the navigation `ThemeProvider`). Native never hydrates and ignores it.
+ *
+ * Context, not `setState`: the store is a module singleton shared by every
+ * concurrent server request, so a per-request value has to travel down the
+ * tree.
+ */
+export declare function InitialSchemeProvider({ scheme, children, }: {
+    scheme: ResolvedTheme | undefined;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<ResolvedTheme | undefined>>;
+/** The first-render scheme hint, or `undefined` outside an `InitialSchemeProvider`. */
+export declare function useInitialScheme(): ResolvedTheme | undefined;

package/dist/state/initialScheme.js

@@ -0,0 +1,29 @@
+import { createContext, createElement, use } from "react";
+const InitialSchemeContext = createContext(undefined);
+/**
+ * The scheme the FIRST render should use, before the persisted preference has
+ * been read — a server-render hint.
+ *
+ * On web the theme store boots `system` + `light` and only reads the visitor's
+ * preference in `syncThemeFromEnvironment()` after the first commit, so the
+ * server and the hydrating client both paint light and a dark-mode visitor
+ * gets a flash (and any `useId`-dependent markup that differs by scheme
+ * mismatches). An app that knows the scheme on both sides — the template
+ * mirrors it into a `color-scheme` cookie the server and `document.cookie`
+ * both read — wraps its root in this provider; `useTheme()` uses the hint
+ * until `hasLoadedTheme` is true, then the store as always. Mount it ABOVE the
+ * first `useTheme()` caller (the root layout itself usually reads the theme
+ * for the navigation `ThemeProvider`). Native never hydrates and ignores it.
+ *
+ * Context, not `setState`: the store is a module singleton shared by every
+ * concurrent server request, so a per-request value has to travel down the
+ * tree.
+ */
+export function InitialSchemeProvider({ scheme, children, }) {
+    // `state/*` modules are `.ts` (the package's source export pattern), hence no JSX.
+    return createElement(InitialSchemeContext.Provider, { value: scheme }, children);
+}
+/** The first-render scheme hint, or `undefined` outside an `InitialSchemeProvider`. */
+export function useInitialScheme() {
+    return use(InitialSchemeContext);
+}

package/dist/state/notify.d.ts

@@ -1,4 +1,4 @@
-import type { GlobalNotificationAlert } from "./globalUIStore";
+import type { GlobalNotificationAlert } from "./globalUIStore.js";
 /**
  * notify
  *

package/dist/state/themeColorScope.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { ColorOverrides } from "./themeStore";
+import type { ColorOverrides } from "./themeStore.js";
 /** Read the active scoped override (null when not inside a scope). */
 export declare function useThemeColorScope(): ColorOverrides | null;
 export declare function ThemeColorScope({ colors, children, }: {

package/dist/state/themeStore.d.ts

@@ -1,5 +1,5 @@
-import type { ThemeColors } from "../constants/colors";
-import type { FontOverrides } from "../constants/fonts";
+import type { ThemeColors } from "../constants/colors.js";
+import type { FontOverrides, SerifPreset } from "../constants/fonts.js";
 export type ThemePreference = "system" | "light" | "dark";
 export type ResolvedTheme = "light" | "dark";
 /**
@@ -27,19 +27,28 @@ export type ColorOverrides = {
     light?: Partial<ThemeColors>;
     dark?: Partial<ThemeColors>;
 };
+/** A radius override for one shape slot. `0` is square corners; `9999` is a pill. */
+export type ShapeSlotOverride = {
+    /** Border radius for every component in the slot. A caller `style` still wins. */
+    borderRadius?: number;
+};
 /**
- * Shape overrides a host app can inject, grouped per component so future
- * shape knobs (card radius, input radius, …) slot in without reshaping the
- * API. Every field is optional; omitted fields keep the package default.
+ * Shape overrides a host app can inject, grouped per slot. Every field is
+ * optional; omitted fields keep the package default. Components read their
+ * slot through `useShape(slot)` and layer it after the static radius, before
+ * the caller's `style`.
+ *
+ * | Slot | Components | Package default |
+ * |---|---|---|
+ * | `button` | Button (every preset) | `spacing.radiusMd` (10) |
+ * | `input` | TextInput (not `underlined`), Select trigger, InputOTP cells | `spacing.radiusMd` (10) |
+ * | `card` | Card, StatCard, EmptyState (`bordered`), SkeletonCard | `spacing.radiusLg` (14) |
+ * | `sheet` | BottomSheet top corners (where the platform lets the sheet draw them: web, Android) | platform |
+ * | `badge` | Badge | `spacing.radiusFull` |
+ * | `dialog` | Dialog and AlertDialog content | `spacing.radiusLg` (14) |
  */
 export type ShapeOverrides = {
-    button?: {
-        /**
-         * Border radius applied to every Button preset. Package default:
-         * `spacing.radiusMd` (10). Use 9999 for pill buttons. A caller `style`
-         * still wins over this, as it always has.
-         */
-        borderRadius?: number;
+    button?: ShapeSlotOverride & {
         /**
          * Whether the `default` preset renders its shadow. Package default: true.
          * Other presets stay flat regardless; the per-instance `withShadow` prop
@@ -47,7 +56,13 @@ export type ShapeOverrides = {
          */
         withShadow?: boolean;
     };
+    input?: ShapeSlotOverride;
+    card?: ShapeSlotOverride;
+    sheet?: ShapeSlotOverride;
+    badge?: ShapeSlotOverride;
+    dialog?: ShapeSlotOverride;
 };
+export type ShapeSlot = keyof ShapeOverrides;
 export type ThemeStore = {
     userTheme: ThemePreference;
     systemTheme: ResolvedTheme;
@@ -72,11 +87,19 @@ export type ThemeStore = {
      */
     fontOverrides: FontOverrides;
     /**
-     * App-injected shape overrides (button radius, default-preset shadow).
-     * Same contract as the other override slots: empty by default, fully
-     * backward compatible when unset.
+     * App-injected shape overrides (radii per slot, the default Button preset's
+     * shadow). Same contract as the other override slots: empty by default,
+     * fully backward compatible when unset.
      */
     shapeOverrides: ShapeOverrides;
+    /**
+     * Which serif the `serif` variant resolves to when no `setFonts` serif
+     * override exists: `"georgia"` (default, the system face) or
+     * `"newsreader"`, set by `useResources({ serif: "newsreader" })` once its
+     * files or stylesheet are in place. Read by `resolveFontStyle` through
+     * `StyledText` and `useFontStyle`.
+     */
+    serifPreset: SerifPreset;
     setTheme: (theme: ThemePreference) => void;
     setSystemTheme: (theme: ResolvedTheme) => void;
     /**
@@ -96,13 +119,43 @@ export type ThemeStore = {
     setFonts: (overrides: FontOverrides) => void;
     /**
      * Replace the active shape overrides. Pass `{}` to clear them and fall back
-     * to the package defaults (button radius 12, default-preset shadow on).
+     * to the package defaults (see the slot table on `ShapeOverrides`: button
+     * and input radius 10 = `spacing.radiusMd`, card and dialog 14 =
+     * `spacing.radiusLg`, badge pill, default-preset shadow on).
      */
     setShape: (overrides: ShapeOverrides) => void;
+    /** Switch the serif preset. `useResources` calls this; apps rarely need to. */
+    setSerifPreset: (preset: SerifPreset) => void;
     loadTheme: () => void;
 };
 export declare function resolveThemePreference(userTheme: ThemePreference, systemTheme: ResolvedTheme): ResolvedTheme;
 export declare const useThemeStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ThemeStore>>;
 export declare function syncSystemTheme(): void;
+/**
+ * Keep `systemTheme` following the OS color scheme (`prefers-color-scheme` on
+ * web, `Appearance` on native). The first holder reads the current scheme and
+ * attaches the one listener; later calls share it.
+ *
+ * Returns this caller's release: once every holder has released, the
+ * listener is removed. Calling a release again is a no-op, so an effect
+ * cleanup that runs twice can't drop another caller's hold. On native the
+ * package holds the listener for the app's lifetime (see the module-load
+ * init below), so an app's release never stops OS tracking there.
+ */
 export declare function startSystemThemeListener(): () => void;
+/**
+ * Single entry point for host apps to populate the store from the
+ * environment: the OS color-scheme listener plus the persisted preference.
+ *
+ * Web apps call it once, from a top-level `useEffect` (never during render or
+ * at module scope — see below), and return its result as the cleanup:
+ * `useEffect(() => syncThemeFromEnvironment(), [])`. Safe to call more than
+ * once (StrictMode's double effects, two roots): every call shares the one
+ * OS listener, re-reads the persisted preference, and returns its own
+ * cleanup, which releases only that call's hold on the listener.
+ *
+ * The listener starts BEFORE `loadTheme()` on purpose: reading the real OS
+ * scheme first means a `system` user resolves straight from the boot-default
+ * "light" to their actual scheme in one commit.
+ */
 export declare function syncThemeFromEnvironment(): () => void;