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

package/dist/public/structure.d.ts

@@ -0,0 +1,65 @@
+import type { SymbolName } from '../symbols/Symbol.js';
+import type { ComponentType, ReactNode } from 'react';
+import type { Register, RegisteredRoutes, RouteProps, Routes } from './routes.js';
+/** A primary stack: its root route and, when that route requires them, the root's params. */
+export type StackDeclaration<R extends Routes> = {
+    [K in keyof R['definitions'] & string]: {
+        root: K;
+    } & ({} extends RouteProps<R, K> ? {
+        params?: RouteProps<R, K>;
+    } : {
+        params: RouteProps<R, K>;
+    });
+}[keyof R['definitions'] & string];
+/** The tab declaration contract used by public app declarations. */
+export type TabDeclaration<R extends Routes> = StackDeclaration<R> & {
+    /** The tab's identity: typed by `TabId`, used by `TabView selection` and restoration. */
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    symbol?: SymbolName;
+    /** `Tab(role: .search)`: the separated search tab. */
+    role?: 'search';
+    /** Wraps the tab's stack, for per-tab providers. Render `<NavigationStack />` inside it. */
+    content?: ComponentType;
+};
+/** An app's primary navigation: either tabs, each owning a stack, or one stack. */
+export type NavigationDeclaration<R extends Routes = RegisteredRoutes> = {
+    tabs: readonly TabDeclaration<R>[];
+    stack?: never;
+    defaultTab?: string;
+} | {
+    stack: StackDeclaration<R>;
+    tabs?: never;
+    defaultTab?: never;
+};
+/**
+ * Declares the app's primary tabs or its single stack before anything renders, so every stack
+ * and tab id exists (and is typed) from the first frame. Pass the result to `runApp`; `TabView`,
+ * `Tab` and `NavigationStack` then render it. Components may freely wrap those views.
+ *
+ * @example
+ * const navigation = defineNavigation(routes, {
+ *   tabs: [{ id: 'home', label: 'Home', symbol: 'house', root: 'home' }],
+ * })
+ */
+export declare function defineNavigation<R extends Routes, const D extends NavigationDeclaration<R>>(routes: R, declaration: D & (D extends {
+    tabs: readonly {
+        id: infer I;
+    }[];
+} ? {
+    defaultTab?: I;
+} : unknown)): D;
+/** Checks a declaration against its routes; `defineNavigation` and `runApp` both call it. */
+export declare function validateNavigation<R extends Routes, D extends NavigationDeclaration<R>>(routes: R, declaration: D): D;
+/** The navigation declared through `Register`, which types bare `TabView`, `Tab` and
+ * `NavigationStack`; `never` when the app has not registered one. */
+export type RegisteredNavigation = Register extends {
+    navigation: infer D extends NavigationDeclaration<Routes>;
+} ? D : never;
+/** The union of a navigation declaration's tab ids. */
+export type TabId<D = RegisteredNavigation> = D extends {
+    tabs: readonly {
+        id: infer Id extends string;
+    }[];
+} ? Id : never;

package/dist/public/structure.js

@@ -0,0 +1,40 @@
+/**
+ * Declares the app's primary tabs or its single stack before anything renders, so every stack
+ * and tab id exists (and is typed) from the first frame. Pass the result to `runApp`; `TabView`,
+ * `Tab` and `NavigationStack` then render it. Components may freely wrap those views.
+ *
+ * @example
+ * const navigation = defineNavigation(routes, {
+ *   tabs: [{ id: 'home', label: 'Home', symbol: 'house', root: 'home' }],
+ * })
+ */
+export function defineNavigation(routes, declaration) {
+    return validateNavigation(routes, declaration);
+}
+/** Checks a declaration against its routes; `defineNavigation` and `runApp` both call it. */
+export function validateNavigation(routes, declaration) {
+    if (Boolean(declaration.tabs) === Boolean(declaration.stack))
+        throw new Error('Declare tabs or a single stack, exclusively');
+    const stacks = 'tabs' in declaration && declaration.tabs
+        ? declaration.tabs
+        : [{ id: 'main', ...declaration.stack }];
+    if (!stacks.length)
+        throw new Error('Navigation requires at least one primary stack');
+    const ids = new Set();
+    for (const stack of stacks) {
+        if (!stack.id?.trim() || ids.has(stack.id))
+            throw new Error(`Invalid or duplicate tab id: ${stack.id}`);
+        ids.add(stack.id);
+        if (!Object.hasOwn(routes.definitions, stack.root) ||
+            !routes.definitions[stack.root]?.validate(stack.params))
+            throw new Error(`Invalid root route: ${stack.root}`);
+    }
+    if (declaration.defaultTab !== undefined && !ids.has(declaration.defaultTab))
+        throw new Error(`Unknown default tab: ${declaration.defaultTab}`);
+    return Object.freeze({
+        ...declaration,
+        ...(declaration.tabs
+            ? { tabs: Object.freeze(declaration.tabs.map(tab => Object.freeze({ ...tab }))) }
+            : { stack: Object.freeze({ ...declaration.stack }) }),
+    });
+}

package/dist/public/toolbar.d.ts

@@ -0,0 +1,37 @@
+import { type ReactNode } from 'react';
+import type { ToolbarSlot } from './screenChrome.js';
+/** A `bottomBar` toolbar item joins its screen's bottom inset chain (registered by Screen). */
+export declare const BottomBarRegistrationContext: import("react").Context<(() => () => void) | null>;
+/** A `DefaultToolbarItem kind="search"` reports the element it holds in the bottom bar. */
+export declare const SearchToolbarItemContext: import("react").Context<((element: HTMLElement | null) => void) | null>;
+/** The supported toolbar placement names. */
+export type ToolbarItemProps = {
+    placement: 'subtitle' | 'largeTitle' | 'largeSubtitle' | 'principal' | 'topBarLeading' | 'topBarTrailing' | 'primaryAction' | 'confirmationAction' | 'cancellationAction' | 'automatic' | 'bottomBar';
+    children?: ReactNode;
+};
+export declare const ToolbarContext: import("react").Context<"group" | boolean>;
+export declare const ToolbarConfirmationContext: import("react").Context<boolean>;
+export declare const ToolbarSlotsContext: import("react").Context<Partial<Record<ToolbarSlot, HTMLDivElement | null>>>;
+/** Places one navigation or bottom-bar item. Adjacent actions share a glass capsule; ToolbarSpacer separates groups. */
+export declare function ToolbarItem({ children, placement }: ToolbarItemProps): import("react").ReactPortal | null;
+/** Which system item to place, and where. */
+export type DefaultToolbarItemProps = {
+    /** `DefaultToolbarItem(kind:)`. Only `search` is drawn. */
+    kind: 'search';
+    placement?: 'bottomBar' | 'automatic';
+};
+/** Places the screen search field among bottom-bar items. Requires Screen searchable. */
+export declare function DefaultToolbarItem({ kind }: DefaultToolbarItemProps): import("react").ReactPortal | null;
+/** The spacer's sizing and placement. */
+export type ToolbarSpacerProps = {
+    /** `SpacerSizing`: `fixed` separates two items' glass by the standard 12 pt gap;
+     * `flexible` (the default) takes the free space of the bar, like `ToolbarSpacer()`. */
+    sizing?: 'fixed' | 'flexible';
+    placement?: ToolbarItemProps['placement'];
+};
+/** `ToolbarSpacer(_:placement:)`. Consecutive items of one placement share one glass
+ * capsule; a spacer between them splits it. Place it directly in `toolbar`, next to the items. */
+export declare function ToolbarSpacer({ sizing, placement, }: ToolbarSpacerProps): import("react").JSX.Element | null;
+/** `ToolbarItemGroup`: its items render as consecutive `ToolbarItem`s of the placement,
+ * which share one glass capsule (iOS 26+ draws a group and adjacent items identically). */
+export declare function ToolbarItemGroup({ children, placement }: ToolbarItemProps): import("react").JSX.Element;

package/dist/public/toolbar.js

@@ -0,0 +1,76 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { Children, createContext, isValidElement, useContext, useLayoutEffect, useState, } from 'react';
+import { createPortal } from 'react-dom';
+import { ToolbarMaterialContext } from '../glass/toolbarMaterialContext.js';
+// Toolbar items render into the slot elements their Screen registered for its entry, through a
+// portal, so they keep the screen's React context while drawing in the navigation bar.
+/** A `bottomBar` toolbar item joins its screen's bottom inset chain (registered by Screen). */
+export const BottomBarRegistrationContext = createContext(null);
+/** A `DefaultToolbarItem kind="search"` reports the element it holds in the bottom bar. */
+export const SearchToolbarItemContext = createContext(null);
+export const ToolbarContext = createContext(false);
+export const ToolbarConfirmationContext = createContext(false);
+const toolbarPlacement = {
+    principal: 'principal',
+    subtitle: 'subtitle',
+    largeTitle: 'largeTitle',
+    largeSubtitle: 'largeSubtitle',
+    topBarLeading: 'topBarLeading',
+    topBarTrailing: 'trailing',
+    primaryAction: 'trailing',
+    confirmationAction: 'trailing',
+    cancellationAction: 'leading',
+    automatic: 'trailing',
+    bottomBar: 'bottom',
+};
+export const ToolbarSlotsContext = createContext({});
+/** Places one navigation or bottom-bar item. Adjacent actions share a glass capsule; ToolbarSpacer separates groups. */
+export function ToolbarItem({ children, placement }) {
+    const slots = useContext(ToolbarSlotsContext);
+    const registerBottomBar = useContext(BottomBarRegistrationContext);
+    const slot = toolbarPlacement[placement];
+    const destination = slots[slot] ?? (slot === 'topBarLeading' ? slots.leading : undefined);
+    useLayoutEffect(() => {
+        if (slot === 'bottom' && destination)
+            return registerBottomBar?.();
+    }, [slot, destination, registerBottomBar]);
+    // A spacer inside an item (the pre-reference spelling) separates items like a direct ToolbarSpacer.
+    const spacer = isValidElement(children) && children.type === ToolbarSpacer;
+    return destination
+        ? createPortal(_jsx("div", { "data-satin-toolbar-item": spacer ? 'spacer' : 'item', children: _jsx(ToolbarMaterialContext, { value: !['subtitle', 'largeTitle', 'largeSubtitle'].includes(slot), children: _jsx(ToolbarContext, { value: !['subtitle', 'largeTitle', 'largeSubtitle'].includes(slot), children: _jsx(ToolbarConfirmationContext, { value: placement === 'confirmationAction', children: children }) }) }) }), destination)
+        : null;
+}
+/** Places the screen search field among bottom-bar items. Requires Screen searchable. */
+export function DefaultToolbarItem({ kind }) {
+    const slots = useContext(ToolbarSlotsContext);
+    const report = useContext(SearchToolbarItemContext);
+    const destination = slots.bottom;
+    const [element, setElement] = useState(null);
+    useLayoutEffect(() => {
+        report?.(element);
+        return () => report?.(null);
+    }, [report, element]);
+    return destination && kind === 'search'
+        ? createPortal(_jsx("div", { ref: setElement, "data-satin-toolbar-item": "search", "data-satin-search-toolbar-host": "" }), destination)
+        : null;
+}
+/** `ToolbarSpacer(_:placement:)`. Consecutive items of one placement share one glass
+ * capsule; a spacer between them splits it. Place it directly in `toolbar`, next to the items. */
+export function ToolbarSpacer({ sizing = 'flexible', placement = 'automatic', }) {
+    const slots = useContext(ToolbarSlotsContext);
+    const inItem = useContext(ToolbarContext) !== false;
+    const spacer = _jsx("span", { "aria-hidden": "true", "data-satin-toolbar-spacer": sizing });
+    if (inItem)
+        return spacer;
+    const slot = toolbarPlacement[placement];
+    const destination = slots[slot] ?? (slot === 'topBarLeading' ? slots.leading : undefined);
+    return destination ? createPortal(spacer, destination) : null;
+}
+/** `ToolbarItemGroup`: its items render as consecutive `ToolbarItem`s of the placement,
+ * which share one glass capsule (iOS 26+ draws a group and adjacent items identically). */
+export function ToolbarItemGroup({ children, placement }) {
+    // SwiftUI gives confirmation actions separate capsules, even inside a group.
+    if (placement === 'confirmationAction')
+        return (_jsx(ToolbarItem, { placement: placement, children: _jsx("div", { "data-satin-toolbar-confirmation-group": "true", children: children }) }));
+    return (_jsx(_Fragment, { children: Children.toArray(children).map((child, index) => (_jsx(ToolbarItem, { placement: placement, children: child }, isValidElement(child) && child.key !== null ? child.key : index))) }));
+}

package/dist/push/PushPermissionExplainer.d.ts

@@ -0,0 +1,14 @@
+import { type PushNotifications } from './notifications.js';
+/** Mount at the app root so renewals reconcile even when Settings is not visible. */
+export declare function PushNotificationsLifecycle({ controller }: {
+    controller: PushNotifications;
+}): null;
+export declare function PushPermissionExplainer({ controller, title, children, }: {
+    controller: PushNotifications;
+    title?: string;
+    children: React.ReactNode;
+}): import("react").JSX.Element;
+/** A runtime user credential, never a build-time VITE secret. Keep its value in memory. */
+export declare function PushRelayTokenField({ onChange }: {
+    onChange: (token: string) => void;
+}): import("react").JSX.Element;

package/dist/push/PushPermissionExplainer.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect } from 'react';
+import { Pressable } from '../press/Pressable.js';
+import { usePushNotifications } from './notifications.js';
+/** Mount at the app root so renewals reconcile even when Settings is not visible. */
+export function PushNotificationsLifecycle({ controller }) {
+    useEffect(() => controller.start(), [controller]);
+    return null;
+}
+export function PushPermissionExplainer({ controller, title = 'Notifications', children, }) {
+    const state = usePushNotifications(controller);
+    useEffect(() => controller.educate(), [controller]);
+    return (_jsxs("section", { className: "satin-push-explainer", children: [_jsx("h2", { children: title }), _jsx("div", { children: children }), _jsx("p", { role: "status", children: state.status === 'unsupported'
+                    ? 'Open this app from your iPhone Home Screen to use notifications.'
+                    : state.status === 'denied'
+                        ? 'Notifications are off. You can allow them in iPhone Settings → Notifications.'
+                        : state.status === 'subscribed'
+                            ? 'Notifications are on.'
+                            : 'Choose Enable to allow this app to notify you.' }), state.error && _jsx("p", { role: "alert", children: state.error }), _jsx(Pressable, { disabled: ['loading', 'unsupported', 'denied', 'requesting'].includes(state.status), onPress: () => {
+                    void (state.status === 'subscribed' ? controller.unsubscribe() : controller.enable());
+                }, children: state.status === 'subscribed'
+                    ? 'Turn Off Notifications'
+                    : state.status === 'requesting'
+                        ? 'Enabling…'
+                        : 'Enable Notifications' }), _jsx("p", { children: "Badge visibility is controlled in iPhone Settings and cannot be read by this app." })] }));
+}
+/** A runtime user credential, never a build-time VITE secret. Keep its value in memory. */
+export function PushRelayTokenField({ onChange }) {
+    return (_jsxs("label", { className: "satin-push-token", children: ["Notification access token", _jsx("input", { "data-satin-role": "text-input", type: "password", autoComplete: "off", autoCapitalize: "none", spellCheck: false, onChange: event => onChange(event.currentTarget.value) })] }));
+}

package/dist/push/notifications.d.ts

@@ -0,0 +1,54 @@
+import type { AppDefinition } from '../app/definition.js';
+export interface PushSubscriptionPayload {
+    endpoint: string;
+    p256dh: string;
+    auth: string;
+    applicationServerKey: string;
+}
+export interface PushServerAdapter {
+    upsertSubscription(input: {
+        subscription: PushSubscriptionPayload;
+        replacesEndpoint: string | null;
+    }): Promise<unknown>;
+    removeSubscription(input: {
+        endpoint: string;
+        reason: string;
+    }): Promise<void>;
+}
+export interface PushNotificationState {
+    status: 'loading' | 'unsupported' | 'needs-education' | 'ready' | 'requesting' | 'subscribed' | 'denied' | 'revoked' | 'rotation-needed';
+    subscription: PushSubscriptionPayload | null;
+    error: string | null;
+}
+/** Create once outside React. Only enable() requests permission, synchronously from a gesture. */
+export declare function createPushNotifications(options: {
+    app: AppDefinition;
+    applicationServerKey: string;
+    server: PushServerAdapter;
+}): {
+    getSnapshot: () => PushNotificationState;
+    subscribe: (listener: () => void) => () => void;
+    educate: () => void;
+    enable: () => Promise<void>;
+    unsubscribe: () => Promise<void>;
+    reconcile: () => Promise<void>;
+    start: () => () => void;
+};
+export type PushNotifications = ReturnType<typeof createPushNotifications>;
+export declare function usePushNotifications(controller: PushNotifications): PushNotificationState;
+export declare function setAppBadge(count: number | 'clear'): Promise<'unavailable' | 'applied-visibility-unknown' | 'failed'>;
+/** Obtain a user-scoped token at runtime. Never bundle the relay sender token. */
+export declare function createPushRelayAdapter(options: {
+    url: string;
+    token: () => string | Promise<string>;
+}): {
+    upsertSubscription: (input: {
+        subscription: PushSubscriptionPayload;
+        replacesEndpoint: string | null;
+    }) => Promise<any>;
+    removeSubscription: (input: {
+        endpoint: string;
+        reason: string;
+    }) => Promise<void>;
+    sendTest: () => Promise<any>;
+};

package/dist/push/notifications.js

@@ -0,0 +1,276 @@
+import { useSyncExternalStore } from 'react';
+import { registerDefinedAppShell } from '../app/runtime.js';
+function base64(bytes) {
+    return btoa(String.fromCharCode(...new Uint8Array(bytes)))
+        .replaceAll('+', '-')
+        .replaceAll('/', '_')
+        .replace(/=+$/, '');
+}
+function keyBytes(key) {
+    const bytes = Uint8Array.from(atob(key.replaceAll('-', '+').replaceAll('_', '/')), c => c.charCodeAt(0));
+    if (bytes.length !== 65 || bytes[0] !== 4)
+        throw new Error('Invalid public VAPID key');
+    return bytes;
+}
+function serialize(subscription) {
+    const p256dh = subscription.getKey('p256dh'), auth = subscription.getKey('auth'), key = subscription.options.applicationServerKey;
+    if (!p256dh || !auth || !key)
+        throw new Error('Incomplete subscription');
+    return {
+        endpoint: subscription.endpoint,
+        p256dh: base64(p256dh),
+        auth: base64(auth),
+        applicationServerKey: base64(key),
+    };
+}
+/** Create once outside React. Only enable() requests permission, synchronously from a gesture. */
+export function createPushNotifications(options) {
+    const publicKey = keyBytes(options.applicationServerKey);
+    const listeners = new Set();
+    let state = { status: 'loading', subscription: null, error: null };
+    let manager;
+    let observedSubscription = null;
+    let busy = false, educated = false, serverRejected = false;
+    let acknowledged = null;
+    const storageKey = `satin:push:${options.app.id}`;
+    try {
+        acknowledged = JSON.parse(localStorage.getItem(storageKey) ?? 'null');
+    }
+    catch {
+        /* Storage may be unavailable. */
+    }
+    const publish = (status, subscription = state.subscription, error = null) => {
+        state = { status, subscription, error };
+        listeners.forEach(listener => listener());
+    };
+    const remember = (value) => {
+        acknowledged = value;
+        try {
+            if (value)
+                localStorage.setItem(storageKey, JSON.stringify(value));
+            else
+                localStorage.removeItem(storageKey);
+        }
+        catch {
+            /* Next foreground sync remains idempotent. */
+        }
+    };
+    const handoff = async (subscription) => {
+        try {
+            await options.server.upsertSubscription({
+                subscription,
+                replacesEndpoint: acknowledged?.endpoint ?? null,
+            });
+        }
+        catch (error) {
+            if (error &&
+                typeof error === 'object' &&
+                'code' in error &&
+                error.code === 'subscription-expired')
+                serverRejected = true;
+            throw error;
+        }
+        serverRejected = false;
+        remember(subscription);
+        publish('subscribed', subscription);
+    };
+    const remove = async (reason) => {
+        if (acknowledged)
+            await options.server.removeSubscription({ endpoint: acknowledged.endpoint, reason });
+        remember(null);
+    };
+    const reconcile = async () => {
+        if (busy)
+            return;
+        busy = true;
+        try {
+            if (!window.isSecureContext ||
+                !(matchMedia('(display-mode: standalone)').matches ||
+                    navigator.standalone) ||
+                typeof Notification === 'undefined') {
+                publish('unsupported', null);
+                return;
+            }
+            // Worker-owned delivery requires the app-shell registration, even at root scope.
+            manager = (await registerDefinedAppShell(options.app))?.registration.pushManager;
+            if (!manager) {
+                publish('unsupported', null);
+                return;
+            }
+            const current = await manager.getSubscription();
+            observedSubscription = current;
+            if (Notification.permission !== 'granted' || !current) {
+                const previous = !!acknowledged;
+                if (previous)
+                    await remove(Notification.permission === 'granted' ? 'subscription-missing' : 'permission-revoked');
+                publish(Notification.permission === 'denied'
+                    ? 'denied'
+                    : previous
+                        ? 'revoked'
+                        : educated
+                            ? 'ready'
+                            : 'needs-education', null);
+                return;
+            }
+            const subscription = serialize(current);
+            if (subscription.applicationServerKey !== options.applicationServerKey) {
+                publish('rotation-needed', subscription);
+                return;
+            }
+            // Re-upsert at declared foreground opportunities also repairs server record loss.
+            await handoff(subscription);
+        }
+        catch {
+            publish('rotation-needed', state.subscription, 'Could not sync notifications. Check your connection and try again.');
+        }
+        finally {
+            busy = false;
+        }
+    };
+    const enable = async () => {
+        if (busy ||
+            !manager ||
+            !educated ||
+            !navigator.userActivation?.isActive ||
+            Notification.permission === 'denied')
+            return;
+        busy = true;
+        publish('requesting');
+        try {
+            // No await precedes this prompt. The explainer Enable button owns the gesture.
+            const permission = Notification.permission === 'default'
+                ? await Notification.requestPermission()
+                : Notification.permission;
+            if (permission !== 'granted') {
+                publish(permission === 'denied' ? 'denied' : 'ready', null);
+                return;
+            }
+            let current = observedSubscription;
+            if (current &&
+                (serverRejected || serialize(current).applicationServerKey !== options.applicationServerKey)) {
+                if (!(await current.unsubscribe()))
+                    throw new Error('Unsubscribe failed');
+                current = null;
+                observedSubscription = null;
+            }
+            current ??= await manager.subscribe({
+                userVisibleOnly: true,
+                applicationServerKey: publicKey,
+            });
+            observedSubscription = current;
+            const subscription = serialize(current);
+            publish('rotation-needed', subscription);
+            await handoff(subscription);
+        }
+        catch {
+            publish('rotation-needed', state.subscription, 'Could not enable notifications. Try again while online.');
+        }
+        finally {
+            busy = false;
+        }
+    };
+    const unsubscribe = async () => {
+        if (busy || !manager)
+            return;
+        busy = true;
+        try {
+            const current = await manager.getSubscription();
+            observedSubscription = current;
+            if (current && !(await current.unsubscribe()))
+                throw new Error('Unsubscribe failed');
+            observedSubscription = null;
+            await remove('user-disabled');
+            publish('ready', null);
+        }
+        catch {
+            publish('rotation-needed', state.subscription, 'Could not finish turning off notifications. Try again.');
+        }
+        finally {
+            busy = false;
+        }
+    };
+    return {
+        getSnapshot: () => state,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        educate: () => {
+            educated = true;
+            if (state.status === 'needs-education')
+                publish('ready');
+        },
+        enable,
+        unsubscribe,
+        reconcile,
+        start: () => {
+            const foreground = () => {
+                if (document.visibilityState === 'visible')
+                    void reconcile();
+            };
+            void reconcile();
+            document.addEventListener('visibilitychange', foreground);
+            window.addEventListener('online', foreground);
+            return () => {
+                document.removeEventListener('visibilitychange', foreground);
+                window.removeEventListener('online', foreground);
+            };
+        },
+    };
+}
+export function usePushNotifications(controller) {
+    return useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+}
+export async function setAppBadge(count) {
+    if (count !== 'clear' && (!Number.isSafeInteger(count) || count < 0))
+        throw new Error('Badge must be a non-negative integer');
+    try {
+        if (count === 'clear' || count === 0) {
+            if (!navigator.clearAppBadge)
+                return 'unavailable';
+            await navigator.clearAppBadge();
+        }
+        else {
+            if (!navigator.setAppBadge)
+                return 'unavailable';
+            await navigator.setAppBadge(count);
+        }
+        return 'applied-visibility-unknown';
+    }
+    catch {
+        return 'failed';
+    }
+}
+/** Obtain a user-scoped token at runtime. Never bundle the relay sender token. */
+export function createPushRelayAdapter(options) {
+    const base = new URL(options.url);
+    if (base.protocol !== 'https:' || base.username || base.password || base.search || base.hash)
+        throw new Error('Use a trusted HTTPS relay URL');
+    if (!base.pathname.endsWith('/'))
+        base.pathname += '/';
+    const request = async (path, body) => {
+        const response = await fetch(new URL(path, base), {
+            method: 'POST',
+            signal: AbortSignal.timeout(10_000),
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${await options.token()}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok)
+            throw Object.assign(new Error('Push relay request failed'), {
+                code: response.status === 409 ? 'subscription-expired' : 'relay-unavailable',
+            });
+        return response.json();
+    };
+    return {
+        upsertSubscription: (input) => request('subscriptions', input),
+        removeSubscription: async (input) => {
+            await request('unsubscribe', input);
+        },
+        sendTest: () => request('test', {}),
+    };
+}

package/dist/push/routes.d.ts

@@ -0,0 +1,20 @@
+/** Shared, validated route codec. No navigation or browser history side effects. */
+export interface PushRoute<Params extends Record<string, string | number | boolean> = Record<string, string>> {
+    screen: string;
+    params?: Params;
+    tab?: string;
+    version?: number;
+}
+export type PushRouteRules = Record<string, {
+    params: readonly string[];
+    tabs?: readonly string[];
+    version?: number;
+    validate?: (params: unknown) => boolean;
+    schemaOwned?: boolean;
+}>;
+export declare function validatePushRoute(route: PushRoute<Record<string, string | number | boolean>>, rules: PushRouteRules): PushRoute<Record<string, string | number | boolean>>;
+export declare function encodePushRoute(base: string, route: PushRoute<Record<string, string | number | boolean>>, rules: PushRouteRules, deliveryId: string): string;
+export declare function decodePushRoute(input: string, base: string, rules: PushRouteRules): {
+    route: PushRoute<Record<string, string | number | boolean>>;
+    id: string;
+} | null;