@satinhq/kit 0.0.0-stage → 0.1.0-beta.1

package/dist/public/definition.d.ts

@@ -0,0 +1,65 @@
+import { type AppDeploymentInput, type AppDefinition, type AppIcon } from '../app/definition.js';
+import type { ServerReachabilityConfig } from '../reachability/model.js';
+/** What an app declares about itself: identity, install metadata and launch appearance. */
+export type AppDefinitionInput = {
+    /** Built-in acknowledgements screen, available through navigation. Defaults to true. */
+    acknowledgements?: boolean;
+    /** A lowercase slug (`'lift-log'`) or a root-relative path. It keys storage and restoration, so
+     * never change it after install. */
+    id: string;
+    /** The Home Screen name. */
+    name: string;
+    /** Defaults to `name`. */
+    shortName?: string;
+    /** Defaults to `name`. */
+    description?: string;
+    /** One square source image (`{ source: '/icon-1024.png' }`) from which the build derives every
+     * size, or explicit manifest icons. */
+    icons: readonly AppIcon[] | {
+        source: string;
+    };
+    appearance?: {
+        /** The app's accent colour, like an asset catalog `AccentColor`. */
+        tint?: string;
+        /** The light launch background. Defaults to the grouped system background. */
+        background?: string;
+        darkLaunch?: 'match-light' | {
+            readonly background: string;
+        };
+    };
+    /** Defaults to portrait on iPhone and every orientation on iPad. */
+    orientations?: AppDeploymentInput['orientations'];
+    capabilities?: AppDeploymentInput['capabilities'];
+    /** Deployment overrides. Declare connectivity beside the app's other requirements. */
+    advanced?: {
+        /** Release keeps updates for the next launch; preview enables live updates in Safari tabs. */
+        updateProfile?: 'release' | 'preview';
+        installRoute?: AppDeploymentInput['installRoute'];
+        platforms?: AppDeploymentInput['platforms'];
+        viewportFit?: AppDeploymentInput['viewportFit'];
+        launchScreen?: AppDeploymentInput['launchScreen'];
+        mdm?: AppDeploymentInput['mdm'];
+        appShell?: {
+            additionalPrecache: readonly string[];
+        };
+        scope?: AppDeploymentInput['scope'];
+        startRoute?: AppDeploymentInput['startRoute'];
+        shortcuts?: AppDeploymentInput['shortcuts'];
+        updateActivation?: AppDeploymentInput['updateActivation'];
+    };
+} & ({
+    readonly connectivity?: 'local';
+    readonly reachability?: never;
+} | {
+    readonly connectivity: 'server';
+    readonly reachability: ServerReachabilityConfig;
+});
+/**
+ * Declares app identity, install metadata and capabilities once. Pass the result to `runApp` and
+ * to the `@satinhq/kit/vite` plugin. Everything not given is defaulted and the whole definition is
+ * validated, so a bad id or icon fails at build time rather than after install.
+ *
+ * @example
+ * export const app = defineApp({ id: 'notes', name: 'Notes', icons: { source: '/icon.png' } })
+ */
+export declare function defineApp(input: AppDefinitionInput): AppDefinition;

package/dist/public/definition.js

@@ -0,0 +1,58 @@
+import { defineSatinApp, } from '../app/definition.js';
+/**
+ * Declares app identity, install metadata and capabilities once. Pass the result to `runApp` and
+ * to the `@satinhq/kit/vite` plugin. Everything not given is defaulted and the whole definition is
+ * validated, so a bad id or icon fails at build time rather than after install.
+ *
+ * @example
+ * export const app = defineApp({ id: 'notes', name: 'Notes', icons: { source: '/icon.png' } })
+ */
+export function defineApp(input) {
+    if (!input.id.startsWith('/') && !/^[a-z][a-z0-9-]*$/.test(input.id))
+        throw new Error('App id must be a slug or root-relative identity');
+    const advanced = input.advanced ?? {};
+    const scope = advanced.scope ?? '/app/';
+    const source = 'source' in input.icons ? input.icons.source : undefined;
+    const directory = source?.slice(0, source.lastIndexOf('/') + 1) ?? '/';
+    const icons = source
+        ? [180, 192, 512].map(size => ({
+            src: `${directory}satin-${input.id.replace(/[^a-z0-9-]/gi, '')}-icon-${size}.png`,
+            sizes: `${size}x${size}`,
+            type: 'image/png',
+        }))
+        : input.icons;
+    return defineSatinApp({
+        id: input.id.startsWith('/') ? input.id : `/${input.id}`,
+        name: input.name,
+        acknowledgements: input.acknowledgements ?? true,
+        shortName: input.shortName ?? input.name,
+        description: input.description ?? input.name,
+        icons,
+        ...(source ? { iconSource: source } : {}),
+        scope,
+        startRoute: scope,
+        installRoute: '/install',
+        platforms: 'ios',
+        appearance: {
+            ...(input.appearance?.tint ? { tint: input.appearance.tint } : {}),
+            background: input.appearance?.background ?? '#f2f2f7',
+            darkLaunch: input.appearance?.darkLaunch ?? {
+                background: '#000000',
+            },
+        },
+        orientations: input.orientations ?? {
+            supported: ['portrait'],
+            fallback: 'responsive',
+            ipad: { supported: ['portrait', 'landscape'], fallback: 'none' },
+        },
+        capabilities: input.capabilities ?? [],
+        updateActivation: 'cold-launch',
+        updateProfile: 'release',
+        ...advanced,
+        appShell: {
+            additionalPrecache: advanced.appShell?.additionalPrecache ?? [],
+        },
+        connectivity: input.connectivity ?? 'local',
+        ...(input.reachability ? { reachability: input.reachability } : {}),
+    });
+}

package/dist/public/deviceActions.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+/** Prepared text, URL or files to hand to the operating system's share sheet. */
+export type ShareLinkProps = {
+    item: ShareData;
+    children?: ReactNode;
+    disabled?: boolean;
+    /** Completion means the platform accepted the handoff, not that a recipient received it. */
+    onCompletion?(): void;
+    /** Includes AbortError for dismissal or absence of a suitable share target. */
+    onError(error: Error): void;
+};
+/** Opens the system share sheet during the press. Prepare file bytes before rendering. */
+export declare function ShareLink({ item, children, disabled, onCompletion, onError, }: ShareLinkProps): import("react").JSX.Element;
+/** A user-initiated plain-text paste, subject to WebKit's permission UI. */
+export type PasteButtonProps = {
+    children?: ReactNode;
+    disabled?: boolean;
+    onPaste(text: string): void;
+    /** Permission denial and dismissal are reported as browser errors. */
+    onError(error: Error): void;
+};
+/** Reads text only when pressed; it never probes clipboard contents while rendering. */
+export declare function PasteButton({ children, disabled, onPaste, onError }: PasteButtonProps): import("react").JSX.Element;

package/dist/public/deviceActions.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useLayoutEffect, useRef, useState } from 'react';
+import { ScreenContext } from '../navigation/navigationContext.js';
+import { Button } from './controls.js';
+import { useControlStyle } from './controlStyle.js';
+function DeviceAction({ children, disabled, identity, start, onResult, onError, }) {
+    const configuration = useControlStyle({ disabled });
+    const screen = useContext(ScreenContext);
+    const covered = screen?.lifecycle.isCovered ?? false;
+    const unavailable = configuration.disabled || covered;
+    const button = useRef(null);
+    const generation = useRef(0);
+    const pending = useRef(false);
+    const [busy, setBusy] = useState(false);
+    const callbacks = useRef({ onResult, onError });
+    useLayoutEffect(() => {
+        callbacks.current = { onResult, onError };
+    });
+    useLayoutEffect(() => {
+        generation.current += 1;
+        return () => {
+            generation.current += 1;
+        };
+    }, [unavailable, screen?.key, identity]);
+    const activate = () => {
+        const element = button.current;
+        if (pending.current || unavailable || !element?.isConnected)
+            return;
+        if (element.closest('[inert], [aria-hidden="true"]'))
+            return;
+        pending.current = true;
+        setBusy(true);
+        const startedGeneration = generation.current;
+        const current = () => startedGeneration === generation.current &&
+            element.isConnected &&
+            !element.closest('[inert], [aria-hidden="true"]');
+        const finish = () => {
+            pending.current = false;
+            if (element.isConnected)
+                setBusy(false);
+        };
+        const failure = (reason) => {
+            finish();
+            if (current()) {
+                callbacks.current.onError(reason instanceof Error ? reason : new Error(String(reason)));
+            }
+        };
+        let operation;
+        try {
+            // WebKit must see this call inside the original user gesture. No effect,
+            // timer, file preparation or awaited work may precede it.
+            operation = start();
+        }
+        catch (reason) {
+            failure(reason);
+            return;
+        }
+        void operation.then(result => {
+            finish();
+            if (current())
+                callbacks.current.onResult?.(result);
+        }, failure);
+    };
+    return (_jsx(Button, { ref: button, disabled: unavailable || busy, onPress: activate, children: children }));
+}
+/** Opens the system share sheet during the press. Prepare file bytes before rendering. */
+export function ShareLink({ item, children = 'Share', disabled, onCompletion, onError, }) {
+    return (_jsx(DeviceAction, { disabled: disabled, identity: item, onResult: onCompletion, onError: onError, start: () => {
+            if (typeof navigator.share !== 'function') {
+                throw new DOMException('System sharing is unavailable.', 'NotSupportedError');
+            }
+            if (item.files?.length &&
+                (!navigator.canShare || !navigator.canShare({ files: item.files }))) {
+                throw new DOMException('These files cannot be shared by this browser.', 'NotSupportedError');
+            }
+            return navigator.share(item);
+        }, children: children }));
+}
+/** Reads text only when pressed; it never probes clipboard contents while rendering. */
+export function PasteButton({ children = 'Paste', disabled, onPaste, onError }) {
+    return (_jsx(DeviceAction, { disabled: disabled, onResult: onPaste, onError: onError, start: () => {
+            if (typeof navigator.clipboard?.readText !== 'function') {
+                throw new DOMException('Clipboard text reading is unavailable.', 'NotSupportedError');
+            }
+            return navigator.clipboard.readText();
+        }, children: children }));
+}

package/dist/public/environment.d.ts

@@ -0,0 +1,77 @@
+import type { JustUpdated } from '../app/coldLaunchUpdate.js';
+import type { GlassError } from '../glass/errors.js';
+import { type ReactNode, type SetStateAction } from 'react';
+import { setAppBadge } from '../push/notifications.js';
+/**
+ * Reports whether this launch applied an app update: `justUpdated` holds the previous and current
+ * build ids after an update, null otherwise (and until launch settles). Release updates apply
+ * at launch, before first input after foregrounding, or at a clean suspension.
+ */
+export declare function useAppUpdate(): Readonly<{
+    justUpdated: JustUpdated | null;
+}>;
+/** `horizontalSizeClass`: a presentation's own class inside it, else the window's. */
+export declare function useHorizontalSizeClass(): UserInterfaceSizeClass;
+/** `verticalSizeClass`: a presentation's own class inside it, else the window's. */
+export declare function useVerticalSizeClass(): UserInterfaceSizeClass;
+/** The live safe-area insets in CSS pixels. Use them instead of `env(safe-area-inset-*)`. */
+export declare function useSafeAreaInsets(): EdgeInsets;
+/** `scenePhase`: `active` in the foreground with focus, `inactive` without focus,
+ * `background` when hidden. */
+export declare function useScenePhase(): ScenePhase;
+/** `colorScheme`: the appearance Satin is currently drawing, `light` or `dark`. */
+export declare function useColorScheme(): ColorScheme;
+/** Every glass renderer error so far, re-rendering when one is added. For diagnostics screens;
+ * `runApp`'s `onGlassError` is the way to report them. */
+export declare function useGlassErrors(): readonly GlassError[];
+/**
+ * `@SceneStorage`: state kept with the current navigation entry in the scene checkpoint,
+ * so a draft survives a relaunch. Each pushed entry owns its own value. Values must be
+ * JSON-serializable. Keep saved records in a collection, not here.
+ *
+ * @example
+ * const [draft, setDraft] = useSceneStorage('draft', '')
+ */
+export declare function useSceneStorage<T>(key: string, initial: T): readonly [T, (next: SetStateAction<T>) => void];
+/**
+ * `@AppStorage`: a small JSON-serializable preference, kept across launches and shared by
+ * every component that reads the same key.
+ *
+ * @example
+ * const [units, setUnits] = useAppStorage('units', 'kg')
+ */
+export declare function useAppStorage<T>(key: string, initial: T): readonly [T, (next: SetStateAction<T>) => void];
+/**
+ * The app's notification permission and badge. Call `requestAuthorization` from a user gesture,
+ * after explaining why (see `NotificationPermissionExplainer`). Without `runApp`'s
+ * `notifications` option the status is `unsupported`.
+ */
+export declare function useNotifications(): {
+    status: NotificationAuthorizationStatus;
+    error: string | null;
+    requestAuthorization: () => Promise<void>;
+    setBadge: (value: Parameters<typeof setAppBadge>[0]) => Promise<boolean>;
+};
+/** Notification permission, independent of subscription setup and token rotation. */
+export type NotificationAuthorizationStatus = 'unsupported' | 'notDetermined' | 'denied' | 'authorized';
+/** The notification permission explanation's title and app-authored content. */
+export type NotificationPermissionExplainerProps = {
+    title?: string;
+    children: ReactNode;
+};
+/** Explains what notifications are for before the user asks for them; its button requests
+ * authorization from that gesture. */
+export declare function NotificationPermissionExplainer({ title, children, }: NotificationPermissionExplainerProps): import("react").JSX.Element;
+/** `EdgeInsets`: logical safe-area padding in points. */
+export type EdgeInsets = Readonly<{
+    top: number;
+    leading: number;
+    bottom: number;
+    trailing: number;
+}>;
+/** `UserInterfaceSizeClass`: the available size along one axis. */
+export type UserInterfaceSizeClass = 'compact' | 'regular';
+/** `ScenePhase`: the foreground, focus and suspension state. */
+export type ScenePhase = 'active' | 'inactive' | 'background';
+/** `ColorScheme`: the appearance currently drawn by the scene. */
+export type ColorScheme = 'light' | 'dark';

package/dist/public/environment.js

@@ -0,0 +1,171 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PresentationLayoutClassContext } from '../layout/navigationLayoutContext.js';
+import { useCallback, useContext, useEffect, useState, useSyncExternalStore, } from 'react';
+import { useSatinLayoutRuntime } from '../root/runtimeContext.js';
+import { edgeInsetsEqual, useSafeAreaSelector, } from '../safe-area/useSafeAreaMetrics.js';
+import { getGlassErrors, subscribeGlassErrors } from '../glass/errors.js';
+import { useSceneStorage as useEntryStorage } from '../restoration/react.js';
+import { isSerializableState } from '../restoration/scene.js';
+import { useAppContext } from './context.js';
+import { setAppBadge } from '../push/notifications.js';
+import { PushPermissionExplainer } from '../push/PushPermissionExplainer.js';
+/**
+ * Reports whether this launch applied an app update: `justUpdated` holds the previous and current
+ * build ids after an update, null otherwise (and until launch settles). Release updates apply
+ * at launch, before first input after foregrounding, or at a clean suspension.
+ */
+export function useAppUpdate() {
+    const { justUpdated, launchReady } = useSatinLayoutRuntime();
+    return { justUpdated: launchReady ? justUpdated : null };
+}
+/** `horizontalSizeClass`: a presentation's own class inside it, else the window's. */
+export function useHorizontalSizeClass() {
+    const presentation = useContext(PresentationLayoutClassContext);
+    const runtime = useSatinLayoutRuntime().layoutClass;
+    return (presentation ?? runtime).horizontal;
+}
+/** `verticalSizeClass`: a presentation's own class inside it, else the window's. */
+export function useVerticalSizeClass() {
+    const presentation = useContext(PresentationLayoutClassContext);
+    const runtime = useSatinLayoutRuntime().layoutClass;
+    return (presentation ?? runtime).vertical;
+}
+const selectInsets = (metrics) => metrics.insets;
+/** The live safe-area insets in CSS pixels. Use them instead of `env(safe-area-inset-*)`. */
+export function useSafeAreaInsets() {
+    const { top, left, bottom, right } = useSafeAreaSelector(selectInsets, edgeInsetsEqual);
+    const rtl = getComputedStyle(document.documentElement).direction === 'rtl';
+    return { top, leading: rtl ? right : left, bottom, trailing: rtl ? left : right };
+}
+const sceneSnapshot = () => document.visibilityState === 'hidden' ? 'background' : document.hasFocus() ? 'active' : 'inactive';
+function subscribeScene(listener) {
+    document.addEventListener('visibilitychange', listener);
+    window.addEventListener('focus', listener);
+    window.addEventListener('blur', listener);
+    return () => {
+        document.removeEventListener('visibilitychange', listener);
+        window.removeEventListener('focus', listener);
+        window.removeEventListener('blur', listener);
+    };
+}
+/** `scenePhase`: `active` in the foreground with focus, `inactive` without focus,
+ * `background` when hidden. */
+export function useScenePhase() {
+    return useSyncExternalStore(subscribeScene, sceneSnapshot, () => 'inactive');
+}
+/** `colorScheme`: the appearance Satin is currently drawing, `light` or `dark`. */
+export function useColorScheme() {
+    const store = window.__SATIN_APPEARANCE__;
+    if (!store)
+        throw new Error('useColorScheme requires the Satin appearance runtime');
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot).dark
+        ? 'dark'
+        : 'light';
+}
+/** Every glass renderer error so far, re-rendering when one is added. For diagnostics screens;
+ * `runApp`'s `onGlassError` is the way to report them. */
+export function useGlassErrors() {
+    const [errors, setErrors] = useState(getGlassErrors);
+    useEffect(() => subscribeGlassErrors(() => setErrors(getGlassErrors())), []);
+    return errors;
+}
+function schema(initial) {
+    return {
+        version: 1,
+        initial,
+        validate: (value) => isSerializableState(value),
+    };
+}
+/**
+ * `@SceneStorage`: state kept with the current navigation entry in the scene checkpoint,
+ * so a draft survives a relaunch. Each pushed entry owns its own value. Values must be
+ * JSON-serializable. Keep saved records in a collection, not here.
+ *
+ * @example
+ * const [draft, setDraft] = useSceneStorage('draft', '')
+ */
+export function useSceneStorage(key, initial) {
+    const [contract] = useState(() => schema(initial));
+    return useEntryStorage(key, contract);
+}
+const preferenceListeners = new Set();
+/**
+ * `@AppStorage`: a small JSON-serializable preference, kept across launches and shared by
+ * every component that reads the same key.
+ *
+ * @example
+ * const [units, setUnits] = useAppStorage('units', 'kg')
+ */
+export function useAppStorage(key, initial) {
+    const { app } = useAppContext(), storageKey = `satin-preference:${app.id}:${key}`;
+    const [contract] = useState(() => schema(initial));
+    const read = useCallback(() => {
+        try {
+            const raw = localStorage.getItem(storageKey);
+            const value = raw === null ? contract.initial : JSON.parse(raw);
+            return contract.validate(value) ? value : contract.initial;
+        }
+        catch {
+            return contract.initial;
+        }
+    }, [storageKey, contract]);
+    const [value, setValue] = useState(read);
+    useEffect(() => {
+        const update = () => setValue(read());
+        update();
+        preferenceListeners.add(update);
+        window.addEventListener('storage', update);
+        return () => {
+            preferenceListeners.delete(update);
+            window.removeEventListener('storage', update);
+        };
+    }, [read]);
+    const set = useCallback((next) => {
+        const value = typeof next === 'function' ? next(read()) : next;
+        if (!contract.validate(value))
+            throw new Error('App storage requires serializable values');
+        localStorage.setItem(storageKey, JSON.stringify(value));
+        preferenceListeners.forEach(fn => fn());
+    }, [read, contract, storageKey]);
+    return [value, set];
+}
+const unsupported = {
+    status: 'unsupported',
+    subscription: null,
+    error: null,
+};
+const noop = () => () => { };
+const fallback = () => unsupported;
+/**
+ * The app's notification permission and badge. Call `requestAuthorization` from a user gesture,
+ * after explaining why (see `NotificationPermissionExplainer`). Without `runApp`'s
+ * `notifications` option the status is `unsupported`.
+ */
+export function useNotifications() {
+    const { notifications } = useAppContext();
+    const state = useSyncExternalStore(notifications?.subscribe ?? noop, notifications?.getSnapshot ?? fallback, fallback);
+    return {
+        status: notificationAuthorization(state),
+        error: state.error,
+        requestAuthorization: () => {
+            notifications?.educate();
+            return notifications?.enable() ?? Promise.resolve();
+        },
+        setBadge: async (value) => (await setAppBadge(value)) === 'applied-visibility-unknown',
+    };
+}
+function notificationAuthorization(state) {
+    if (state.status === 'unsupported' || typeof Notification === 'undefined')
+        return 'unsupported';
+    if (Notification.permission === 'granted')
+        return 'authorized';
+    if (Notification.permission === 'denied')
+        return 'denied';
+    return 'notDetermined';
+}
+/** Explains what notifications are for before the user asks for them; its button requests
+ * authorization from that gesture. */
+export function NotificationPermissionExplainer({ title, children, }) {
+    const { notifications } = useAppContext();
+    return notifications ? (_jsx(PushPermissionExplainer, { controller: notifications, title: title, children: children })) : (_jsx("p", { role: "status", children: "Notifications are not configured." }));
+}

package/dist/public/fieldContext.d.ts

@@ -0,0 +1,2 @@
+/** A field inside an explicit glass surface uses its standalone editing frame. */
+export declare const GlassFieldContext: import("react").Context<boolean>;

package/dist/public/fieldContext.js

@@ -0,0 +1,3 @@
+import { createContext } from 'react';
+/** A field inside an explicit glass surface uses its standalone editing frame. */
+export const GlassFieldContext = createContext(false);

package/dist/public/filePickers.d.ts

@@ -0,0 +1,25 @@
+/** Select one photo or video as file bytes through the system chooser. */
+export type PhotosPickerProps = {
+    label?: string;
+    selection: File | null;
+    onSelectionChange(file: File): void;
+    matching?: 'images' | 'videos' | 'imagesAndVideos';
+    /** A camera preference, interpreted by the browser rather than guaranteed. */
+    capture?: 'user' | 'environment';
+    disabled?: boolean;
+    onError?(error: Error): void;
+};
+/** Photos-library identifiers and persistent access are not exposed by WebKit. */
+export declare function PhotosPicker({ label, selection, onSelectionChange, matching, ...props }: PhotosPickerProps): import("react").JSX.Element;
+/** Import files from the system chooser. Content types are MIME types or extensions. */
+export type FileImporterProps = {
+    label?: string;
+    selection: readonly File[];
+    onSelectionChange(files: File[]): void;
+    allowedContentTypes?: readonly string[];
+    allowsMultipleSelection?: boolean;
+    disabled?: boolean;
+    onError?(error: Error): void;
+};
+/** Open the system file chooser from a user gesture. Cancel preserves selection. */
+export declare function FileImporter({ label, selection, onSelectionChange, allowedContentTypes, allowsMultipleSelection, ...props }: FileImporterProps): import("react").JSX.Element;

package/dist/public/filePickers.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { NativeFilePicker } from './NativeFilePicker.js';
+/** Photos-library identifiers and persistent access are not exposed by WebKit. */
+export function PhotosPicker({ label = 'Choose Photo', selection, onSelectionChange, matching = 'images', ...props }) {
+    const accept = matching === 'images' ? 'image/*' : matching === 'videos' ? 'video/*' : 'image/*,video/*';
+    return (_jsx(NativeFilePicker, { ...props, label: label, value: selection, accept: accept, onChange: files => onSelectionChange(files[0]) }));
+}
+/** Open the system file chooser from a user gesture. Cancel preserves selection. */
+export function FileImporter({ label = 'Import File', selection, onSelectionChange, allowedContentTypes, allowsMultipleSelection = false, ...props }) {
+    return (_jsx(NativeFilePicker, { ...props, label: label, value: selection, onChange: onSelectionChange, accept: allowedContentTypes?.join(','), multiple: allowsMultipleSelection }));
+}

package/dist/public/glass.d.ts

@@ -0,0 +1,31 @@
+import type { HTMLAttributes } from 'react';
+import type { NamespaceID } from '../motion/matchedGeometry.js';
+import { Glass } from './glassValue.js';
+/** Public glass outlines. Sheet-specific corner geometry stays internal. */
+export type GlassShape = 'capsule' | 'circle' | Readonly<{
+    kind: 'roundedRectangle';
+    cornerRadius: number;
+}>;
+/** The glass material, shape, DOM attributes and independent morph identity. */
+export type GlassEffectProps = HTMLAttributes<HTMLDivElement> & {
+    glass?: Glass;
+    shape?: GlassShape;
+    /** A glass-effect identity namespace: ids morph only within one namespace. */
+    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. */
+    glassEffectUnion?: string;
+    /** `glassEffectTransition`. */
+    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.
+ *
+ * @example
+ * <GlassEffect glass={Glass.regular.interactive()} shape="circle">
+ *   <SymbolImage name="plus" />
+ * </GlassEffect>
+ */
+export declare function GlassEffect({ glass, in: namespace, glassEffectID, glassEffectUnion, glassEffectTransition, shape, ...props }: GlassEffectProps): import("react").JSX.Element;

package/dist/public/glass.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+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.
+ *
+ * @example
+ * <GlassEffect glass={Glass.regular.interactive()} shape="circle">
+ *   <SymbolImage name="plus" />
+ * </GlassEffect>
+ */
+export function GlassEffect({ glass = Glass.regular, in: namespace, glassEffectID, glassEffectUnion, glassEffectTransition, shape, ...props }) {
+    if (shape && typeof shape === 'object' && 'bottomCornerRadius' in shape)
+        throw new TypeError('GlassEffect shape does not accept bottomCornerRadius.');
+    return (_jsx(GlassFieldContext, { value: true, children: _jsx(Effect, { ...props, namespace: namespace ? glassNamespaceKey(namespace) : undefined, shape: shape, glass: resolveGlass(glass), glassEffectID: glassEffectID, union: glassEffectUnion, transition: glassEffectTransition }) }));
+}
+// Renderer keys stay strings; public identity follows the shared namespace value.
+const namespaceKeys = new WeakMap();
+let nextNamespaceKey = 0;
+function glassNamespaceKey(namespace) {
+    let key = namespaceKeys.get(namespace);
+    if (key === undefined) {
+        key = `public-glass-${++nextNamespaceKey}`;
+        namespaceKeys.set(namespace, key);
+    }
+    return key;
+}

package/dist/public/glassValue.d.ts

@@ -0,0 +1,19 @@
+import { Glass as Material, type GlassTint } from '../glass/regions.js';
+/**
+ * `Glass`: the material intent for a `GlassEffect`. Start from `Glass.regular` or
+ * `Glass.clear` and refine it; each call returns a new value. The renderer's treatment stays
+ * internal.
+ *
+ * @example
+ * Glass.regular.tintRGBA([0, 0.48, 1, 0.2]).interactive()
+ */
+export declare class Glass {
+    static readonly regular: Glass;
+    static readonly clear: Glass;
+    private constructor();
+    /** Tints the glass with `[red, green, blue, alpha]`, each 0...1; no argument removes the tint. */
+    tintRGBA(color?: GlassTint): Glass;
+    /** `interactive()`: the glass responds to touch. */
+    interactive(enabled?: boolean): Glass;
+}
+export declare function resolveGlass(glass: Glass): Material;

package/dist/public/glassValue.js

@@ -0,0 +1,32 @@
+import { Glass as Material } from '../glass/regions.js';
+const materials = new WeakMap();
+/**
+ * `Glass`: the material intent for a `GlassEffect`. Start from `Glass.regular` or
+ * `Glass.clear` and refine it; each call returns a new value. The renderer's treatment stays
+ * internal.
+ *
+ * @example
+ * Glass.regular.tintRGBA([0, 0.48, 1, 0.2]).interactive()
+ */
+export class Glass {
+    static regular = new Glass(Material.regular);
+    static clear = new Glass(Material.clear);
+    constructor(material) {
+        materials.set(this, material);
+        Object.freeze(this);
+    }
+    /** Tints the glass with `[red, green, blue, alpha]`, each 0...1; no argument removes the tint. */
+    tintRGBA(color) {
+        return new Glass(resolveGlass(this).tint(color));
+    }
+    /** `interactive()`: the glass responds to touch. */
+    interactive(enabled = true) {
+        return new Glass(resolveGlass(this).interactive(enabled));
+    }
+}
+export function resolveGlass(glass) {
+    const material = materials.get(glass);
+    if (!material)
+        throw new Error('Use Glass.regular or Glass.clear to declare a material');
+    return material;
+}

package/dist/public/keyboard.d.ts

@@ -0,0 +1,4 @@
+import { type KeyboardMetrics as InternalKeyboardMetrics } from '../keyboard/adapter.js';
+export type KeyboardMetrics = Omit<InternalKeyboardMetrics, 'presentation' | 'anticipated'>;
+/** Keyboard geometry in points, including the expected software-keyboard height. */
+export declare function useKeyboardMetrics(): KeyboardMetrics;

package/dist/public/keyboard.js

@@ -0,0 +1,6 @@
+import { useKeyboardMetrics as useInternalKeyboardMetrics, } from '../keyboard/adapter.js';
+/** Keyboard geometry in points, including the expected software-keyboard height. */
+export function useKeyboardMetrics() {
+    const { presentation: _presentation, anticipated: _anticipated, ...geometry } = useInternalKeyboardMetrics();
+    return geometry;
+}