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

package/dist/public/navigationTransition.d.ts

@@ -0,0 +1,48 @@
+import { type ReactNode } from 'react';
+import type { NamespaceID } from '../motion/matchedGeometry.js';
+declare const brand: unique symbol;
+/**
+ * `NavigationTransition`: how a pushed screen arrives and leaves. Give one to `Screen`'s
+ * `navigationTransition`.
+ */
+export type NavigationTransition = Readonly<{
+    [brand]: true;
+    kind: 'automatic' | 'zoom';
+    sourceID?: string;
+    namespace?: NamespaceID;
+}>;
+/** The source identity and namespace for `NavigationTransition.zoom`. */
+export type ZoomTransitionOptions = Readonly<{
+    /** The id of the `MatchedTransitionSource` the screen zooms out of and back into. */
+    sourceID: string;
+    in: NamespaceID;
+}>;
+/** SwiftUI's navigation transitions. */
+export declare const NavigationTransition: Readonly<{
+    automatic: NavigationTransition;
+    zoom: (options: ZoomTransitionOptions) => NavigationTransition;
+}>;
+/** Props of `MatchedTransitionSource`. */
+export type MatchedTransitionSourceProps = Readonly<{
+    /** The id a `NavigationTransition.zoom` names as its `sourceID`. */
+    id: string;
+    in: NamespaceID;
+    /** One element: the view the screen zooms out of. Its corner radius is the zoom's start. */
+    children: ReactNode;
+}>;
+/**
+ * `matchedTransitionSource(id:in:)`: marks the view a zoom transition starts from and
+ * returns to. A push zooms only while its source is on screen; otherwise it slides as usual.
+ * @example
+ * <MatchedTransitionSource id={album.id} in={albumZoom}>
+ *   <Image src={album.artwork} alt="" />
+ * </MatchedTransitionSource>
+ * @experimental Pushed screens only; `FullScreenCover` and `Sheet` zooms are not available yet.
+ */
+export declare function MatchedTransitionSource({ id, in: namespace, children, }: MatchedTransitionSourceProps): import("react").JSX.Element;
+/**
+ * Applies a screen's `navigationTransition`: registers its zoom request and, while it is shown,
+ * the downward drag that zooms it back into its source.
+ */
+export declare function useNavigationTransition(entryKey: string, transition: NavigationTransition | undefined): void;
+export {};

package/dist/public/navigationTransition.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useLayoutEffect, useRef } from 'react';
+import { NavigatorContext } from '../navigation/navigationContext.js';
+import { installZoomDismissDrag } from '../navigation/zoomDrag.js';
+import { registerTransitionSource, registerZoomRequest } from '../navigation/zoomTransition.js';
+const brand = Symbol('satin.navigationTransition');
+/** SwiftUI's navigation transitions. */
+export const NavigationTransition = Object.freeze({
+    /** The platform's push: the screen slides in from the trailing edge. */
+    automatic: Object.freeze({ [brand]: true, kind: 'automatic' }),
+    /** The screen grows out of its source view, and shrinks back into it when it is popped or
+     * dragged down. */
+    zoom: ({ sourceID, in: namespace }) => Object.freeze({ [brand]: true, kind: 'zoom', sourceID, namespace }),
+});
+/**
+ * `matchedTransitionSource(id:in:)`: marks the view a zoom transition starts from and
+ * returns to. A push zooms only while its source is on screen; otherwise it slides as usual.
+ * @example
+ * <MatchedTransitionSource id={album.id} in={albumZoom}>
+ *   <Image src={album.artwork} alt="" />
+ * </MatchedTransitionSource>
+ * @experimental Pushed screens only; `FullScreenCover` and `Sheet` zooms are not available yet.
+ */
+export function MatchedTransitionSource({ id, in: namespace, children, }) {
+    const wrapper = useRef(null);
+    useLayoutEffect(() => registerTransitionSource({ namespace, id, wrapper: wrapper.current }), [namespace, id]);
+    // display: contents keeps the wrapped element in its parent's flex or grid layout.
+    return (_jsx("div", { ref: wrapper, "data-satin-transition-source": id, style: { display: 'contents' }, children: children }));
+}
+/**
+ * Applies a screen's `navigationTransition`: registers its zoom request and, while it is shown,
+ * the downward drag that zooms it back into its source.
+ */
+export function useNavigationTransition(entryKey, transition) {
+    const navigator = useContext(NavigatorContext);
+    const sourceID = transition?.kind === 'zoom' ? transition.sourceID : undefined;
+    const namespace = transition?.kind === 'zoom' ? transition.namespace : undefined;
+    useLayoutEffect(() => {
+        if (sourceID === undefined || !namespace || !navigator)
+            return;
+        const unregister = registerZoomRequest(entryKey, { namespace, sourceID });
+        const screen = document.querySelector(`[data-satin-screen-key="${CSS.escape(entryKey)}"]`);
+        const uninstall = screen ? installZoomDismissDrag(screen, entryKey, navigator) : undefined;
+        return () => {
+            uninstall?.();
+            unregister();
+        };
+    }, [entryKey, sourceID, namespace, navigator]);
+}

package/dist/public/pickerNavigation.d.ts

@@ -0,0 +1,7 @@
+import { type PickerRowProps } from '../list-form/ListForm.js';
+export declare const pickerRouteId = "__satin:picker";
+type ChoiceState = Omit<PickerRowProps, 'onNavigate' | 'presentation'>;
+export declare function pickerTitle(params: unknown): string;
+export declare function usePickerNavigation(state: ChoiceState): () => void;
+export declare function PickerDestination(): import("react").JSX.Element;
+export {};

package/dist/public/pickerNavigation.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useId, useLayoutEffect, useState, useSyncExternalStore } from 'react';
+import { NavigatorContext, useNavigator, useParams } from '../navigation/navigationContext.js';
+import { List, PickerOptions, Row } from '../list-form/ListForm.js';
+export const pickerRouteId = '__satin:picker';
+const sessions = new Map();
+export function pickerTitle(params) {
+    return sessions.get(params?.id ?? '')?.title ?? '';
+}
+function notify(session) {
+    session.listeners.forEach(listener => listener());
+}
+export function usePickerNavigation(state) {
+    const id = useId();
+    const navigator = useContext(NavigatorContext);
+    useLayoutEffect(() => {
+        const session = sessions.get(id);
+        if (session) {
+            session.state = state;
+            session.title = state.label;
+            notify(session);
+        }
+    }, [id, state]);
+    // Retire the session in layout cleanup, before a press on the open list can reach a Picker
+    // that is no longer there. The destination removes the session when it is popped.
+    useLayoutEffect(() => () => {
+        const session = sessions.get(id);
+        if (session) {
+            session.state = null;
+            notify(session);
+        }
+    }, [id]);
+    return () => {
+        if (!navigator)
+            throw new Error('Picker navigationLink requires NavigationStack');
+        sessions.set(id, { state, title: state.label, listeners: new Set() });
+        navigator.push(pickerRouteId, { id });
+    };
+}
+export function PickerDestination() {
+    const { id } = useParams();
+    const navigator = useNavigator();
+    // The session this destination was pushed for. A later push from the same Picker makes a new one.
+    const [session] = useState(() => sessions.get(id));
+    const state = useSyncExternalStore(listener => {
+        session?.listeners.add(listener);
+        return () => {
+            session?.listeners.delete(listener);
+        };
+    }, () => session?.state ?? null, () => session?.state ?? null);
+    useLayoutEffect(() => () => {
+        if (sessions.get(id) === session)
+            sessions.delete(id);
+    }, [id, session]);
+    const title = session?.title ?? 'Selection';
+    if (!state) {
+        return (_jsx(List, { id: `picker-${id}`, navigationTitle: title, navigationTitleDisplay: "inline", children: _jsx(Row, { label: "Selection unavailable" }) }));
+    }
+    return (_jsx(List, { id: `picker-${id}`, navigationTitle: title, navigationTitleDisplay: "inline", children: _jsx(PickerOptions, { ...state, labelPlacement: "navigationTitle", onChange: value => {
+                // PickerOptions already checked this option against the Picker's current state.
+                state.onChange(value);
+                navigator.pop();
+            } }) }));
+}

package/dist/public/presentation.d.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+import type { PresentationDetent } from '../presentation/model.js';
+/** Sheet's presentation binding, title, detents and drag behaviour. */
+export type SheetProps = {
+    isPresented: boolean;
+    onPresentedChange(presented: boolean): void;
+    title: string;
+    onDismiss?(): void;
+    children: ReactNode;
+    detents?: readonly PresentationDetent[];
+    interactiveDismissDisabled?: boolean;
+    titleVisibility?: 'visible' | 'hidden';
+    dragIndicator?: 'automatic' | 'visible' | 'hidden';
+} & ({
+    selection?: never;
+    onSelectionChange?(detent: PresentationDetent): void;
+} | {
+    selection: PresentationDetent;
+    onSelectionChange(detent: PresentationDetent): void;
+});
+/**
+ * `sheet(isPresented:)`: a card over the current screen, with optional detents. It can
+ * host its own `NavigationStack modal`. Keep `isPresented` in plain React state: presentations
+ * start closed after a relaunch.
+ *
+ * @example
+ * <Sheet isPresented={adding} onPresentedChange={setAdding} title="New Note">...</Sheet>
+ */
+export declare function Sheet(props: SheetProps): import("react").JSX.Element;
+/** FullScreenCover's presentation binding and accessible title. */
+export type FullScreenCoverProps = {
+    isPresented: boolean;
+    onPresentedChange(presented: boolean): void;
+    title: string;
+    onDismiss?(): void;
+    children: ReactNode;
+};
+/** `fullScreenCover`: an opaque presentation over the whole screen, closed through its
+ * binding or `useDismiss()`. */
+export declare function FullScreenCover(props: FullScreenCoverProps): import("react").JSX.Element;

package/dist/public/presentation.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FullScreenCover as EngineFullScreenCover, Sheet as EngineSheet, } from '../presentation/Presentation.js';
+import { ModalPresentationContext } from './presentationContext.js';
+/**
+ * `sheet(isPresented:)`: a card over the current screen, with optional detents. It can
+ * host its own `NavigationStack modal`. Keep `isPresented` in plain React state: presentations
+ * start closed after a relaunch.
+ *
+ * @example
+ * <Sheet isPresented={adding} onPresentedChange={setAdding} title="New Note">...</Sheet>
+ */
+export function Sheet(props) {
+    if (props.selection !== undefined && typeof props.onSelectionChange !== 'function')
+        throw new TypeError('Controlled sheet selection requires onSelectionChange.');
+    return (_jsx(ModalPresentationContext, { value: true, children: _jsx(EngineSheet, { ...props }) }));
+}
+/** `fullScreenCover`: an opaque presentation over the whole screen, closed through its
+ * binding or `useDismiss()`. */
+export function FullScreenCover(props) {
+    return (_jsx(ModalPresentationContext, { value: true, children: _jsx(EngineFullScreenCover, { ...props }) }));
+}

package/dist/public/presentationContext.d.ts

@@ -0,0 +1,2 @@
+export declare const ModalPresentationContext: import("react").Context<boolean>;
+export declare const RestoredScreenMountContext: import("react").Context<boolean>;

package/dist/public/presentationContext.js

@@ -0,0 +1,3 @@
+import { createContext } from 'react';
+export const ModalPresentationContext = createContext(false);
+export const RestoredScreenMountContext = createContext(false);

package/dist/public/routeRegistry.d.ts

@@ -0,0 +1,3 @@
+import type { ScreenRegistry } from '../navigation/registry.js';
+export declare function registerRoutes(routes: object, registry: ScreenRegistry): void;
+export declare function resolveRoutes(routes: object): ScreenRegistry;

package/dist/public/routeRegistry.js

@@ -0,0 +1,10 @@
+const registries = new WeakMap();
+export function registerRoutes(routes, registry) {
+    registries.set(routes, registry);
+}
+export function resolveRoutes(routes) {
+    const registry = registries.get(routes);
+    if (!registry)
+        throw new Error('Use defineRoutes to declare destinations');
+    return registry;
+}

package/dist/public/routes.d.ts

@@ -0,0 +1,74 @@
+import { type ComponentType } from 'react';
+import type { Visibility, TitleDisplayMode, NavigationBackButtonBehavior } from '../navigation/types.js';
+import type { ToolbarMinimizationBehavior, ToolbarMinimizationRestoration, ToolbarMinimizationSafeAreaAdjustment } from '../navigation/toolbarMinimization.js';
+import { type ParameterSchema, type RouteParameters } from '../push/schema.js';
+export { param, type Parameter, type ParameterSchema, type RouteParameters, } from '../push/schema.js';
+/** A destination's static chrome: what its bar shows from the first frame of the push. `Screen`
+ * overrides any of these once the screen has its data. */
+export type RouteOptions<S extends ParameterSchema> = {
+    /** The parameter schema, built with `param`. */
+    params?: S;
+    /** A function of the params lets the title be right on the push's first frame. */
+    title?: string | ((params: RouteParameters<S>) => string);
+    titleDisplay?: TitleDisplayMode;
+    backButton?: NavigationBackButtonBehavior;
+    /** The navigation bar's visibility. */
+    toolbarVisibility?: Visibility;
+    toolbarMinimizationBehavior?: ToolbarMinimizationBehavior;
+    toolbarMinimizationRestoration?: ToolbarMinimizationRestoration;
+    toolbarMinimizationSafeAreaAdjustment?: ToolbarMinimizationSafeAreaAdjustment;
+    /** `skip` keeps this entry (and anything pushed above it) out of the restored path. */
+    restoration?: 'restore' | 'skip';
+    /** The sidebar row this destination selects in a `NavigationSplitView` (default: its id). */
+    sidebar?: string | ((params: RouteParameters<S>) => string);
+};
+/** A screen bound to its parameter schema; made by `route`, collected by `defineRoutes`. */
+export interface RouteDefinition<P = any> {
+    readonly component: ComponentType<P>;
+    readonly options: RouteOptions<any>;
+    readonly validate: (value: unknown) => value is P;
+}
+/**
+ * Binds a screen component to its parameter schema and static chrome. Declare the params first,
+ * then type the component with `RouteParameters<typeof params>`; this order avoids inference
+ * cycles.
+ *
+ * @example
+ * const noteParams = { id: param.string() }
+ * function NoteScreen({ id }: RouteParameters<typeof noteParams>) { ... }
+ * route(NoteScreen, { params: noteParams, title: 'Note' })
+ */
+export declare function route<const S extends ParameterSchema = Record<never, never>>(component: ComponentType<NoInfer<RouteParameters<S>>>, options?: RouteOptions<S>): RouteDefinition<RouteParameters<S>>;
+/** Every destination of an app, made by `defineRoutes`. */
+export interface Routes<D extends Record<string, RouteDefinition> = Record<string, RouteDefinition>> {
+    readonly definitions: D;
+}
+/** The params of one route, as its component receives them. */
+export type RouteProps<R extends Routes, Id extends keyof R['definitions']> = R['definitions'][Id] extends RouteDefinition<infer P> ? P : never;
+/**
+ * Declares every destination once. The same schema
+ * types `useNavigation` and `NavigationLink`, validates restored paths and checks notification
+ * deep links, so a route id or param is never a free-form string.
+ *
+ * @example
+ * export const routes = defineRoutes({
+ *   notes: route(NotesScreen, { title: 'Notes', titleDisplay: 'large' }),
+ *   note: route(NoteScreen, { params: noteParams, title: 'Note' }),
+ * })
+ */
+export declare function defineRoutes<const D extends Record<string, RouteDefinition>>(definitions: D): Routes<D>;
+/**
+ * Augment once in the app to type bare `NavigationLink`, `NavigationStack`, `TabView` and
+ * `useNavigation` without generics.
+ *
+ * @example
+ * declare module '@satinhq/kit' {
+ *   interface Register { routes: typeof routes; navigation: typeof navigation }
+ * }
+ */
+export interface Register {
+}
+/** The routes declared through `Register`; an empty route set when the app has not registered. */
+export type RegisteredRoutes = Register extends {
+    routes: infer R extends Routes;
+} ? R : Routes<Record<never, never>>;

package/dist/public/routes.js

@@ -0,0 +1,105 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PickerDestination, pickerRouteId, pickerTitle } from './pickerNavigation.js';
+import { ScreenContentContext, ScreenChromeContext } from './screenChrome.js';
+import { registerRoutes } from './routeRegistry.js';
+import { createElement, useContext, useSyncExternalStore } from 'react';
+import { createScreenRegistry } from '../navigation/registry.js';
+import { useParams, ScreenContext } from '../navigation/navigationContext.js';
+import { NavigationLayoutContext } from '../layout/navigationLayoutContext.js';
+import { useLayoutClass } from '../root/runtimeContext.js';
+import { param, validateParameters, } from '../push/schema.js';
+const subscribeNever = () => () => { };
+const snapshotZero = () => 0;
+export { param, } from '../push/schema.js';
+/**
+ * Binds a screen component to its parameter schema and static chrome. Declare the params first,
+ * then type the component with `RouteParameters<typeof params>`; this order avoids inference
+ * cycles.
+ *
+ * @example
+ * const noteParams = { id: param.string() }
+ * function NoteScreen({ id }: RouteParameters<typeof noteParams>) { ... }
+ * route(NoteScreen, { params: noteParams, title: 'Note' })
+ */
+export function route(component, options = {}) {
+    const schema = Object.freeze({ ...options.params });
+    options = Object.freeze({ ...options, params: schema });
+    const validate = (value) => validateParameters(schema, value);
+    return Object.freeze({ component, options, validate });
+}
+/**
+ * Declares every destination once. The same schema
+ * types `useNavigation` and `NavigationLink`, validates restored paths and checks notification
+ * deep links, so a route id or param is never a free-form string.
+ *
+ * @example
+ * export const routes = defineRoutes({
+ *   notes: route(NotesScreen, { title: 'Notes', titleDisplay: 'large' }),
+ *   note: route(NoteScreen, { params: noteParams, title: 'Note' }),
+ * })
+ */
+export function defineRoutes(definitions) {
+    for (const id of Object.keys(definitions)) {
+        if (!id.trim() || id.startsWith('__satin:'))
+            throw new Error('A route id must not be empty');
+    }
+    // Built-in destinations need the same content chrome as app routes. Registering only their
+    // bar leaves scroll views with the presentation's empty context and no navigation inset.
+    const destinations = {
+        ...definitions,
+        [pickerRouteId]: route(PickerDestination, {
+            params: { id: param.string() },
+            title: pickerTitle,
+            titleDisplay: 'inline',
+            restoration: 'skip',
+        }),
+    };
+    const screens = Object.entries(destinations).map(([id, definition]) => {
+        const { component, options, validate } = definition;
+        const Screen = () => {
+            const params = useParams() ?? {};
+            // A List can be a route's entire body. Optional Screen declarations must not
+            // be required for system placement or for finding that route's toolbar.
+            const screen = useContext(ScreenContext);
+            const chrome = useContext(ScreenChromeContext);
+            useSyncExternalStore(chrome?.subscribe ?? subscribeNever, chrome?.snapshot ?? snapshotZero, snapshotZero);
+            const slots = screen ? chrome?.slots.get(screen.key) : undefined;
+            const scopedHorizontal = useContext(NavigationLayoutContext);
+            const runtimeHorizontal = useLayoutClass().horizontal;
+            const title = typeof options.title === 'function' ? options.title(params) : options.title;
+            return (_jsx(ScreenContentContext, { value: {
+                    title,
+                    horizontalSizeClass: scopedHorizontal ?? runtimeHorizontal,
+                    bottomToolbar: slots?.bottom ?? undefined,
+                    trailingToolbar: slots?.trailing ?? undefined,
+                    titleDisplay: options.titleDisplay ?? 'inline',
+                    backButton: options.backButton,
+                    toolbarVisibility: options.toolbarVisibility,
+                    toolbarMinimizationBehavior: options.toolbarMinimizationBehavior,
+                    toolbarMinimizationRestoration: options.toolbarMinimizationRestoration,
+                    toolbarMinimizationSafeAreaAdjustment: options.toolbarMinimizationSafeAreaAdjustment,
+                }, children: createElement(component, params) }));
+        };
+        return {
+            id,
+            component: Screen,
+            navigation: {
+                title: options.title ?? '',
+                display: options.titleDisplay ?? 'inline',
+                backButton: options.backButton,
+                visibility: options.toolbarVisibility,
+            },
+            splitSelection: options.sidebar,
+            restoration: {
+                version: 1,
+                schemaOwned: true,
+                persist: options.restoration !== 'skip',
+                pushParams: Object.keys(options.params ?? {}),
+                validate,
+            },
+        };
+    });
+    const routes = Object.freeze({ definitions: Object.freeze(definitions) });
+    registerRoutes(routes, createScreenRegistry(...screens));
+    return routes;
+}

package/dist/public/runtime.d.ts

@@ -0,0 +1,134 @@
+export { TabSection, type TabSectionProps } from '../tabs/TabSection.js';
+import { type PreferredColorScheme } from '../app/appearance.js';
+import { type NavigationDeclaration, type RegisteredNavigation, type StackDeclaration, type TabId } from './structure.js';
+import type { OfflinePresentationProps } from '../reachability/react.js';
+import type { GlassError } from '../glass/errors.js';
+import type { RouteProps } from './routes.js';
+import { type ComponentType, type ReactNode } from 'react';
+import type { AppDefinition } from '../app/definition.js';
+import { type TabViewProps as EngineTabViewProps } from '../tabs/TabView.js';
+import type { Routes, RegisteredRoutes } from './routes.js';
+/** App-wide runtime options for `runApp`. Every one is optional. */
+export type RunAppOptions = {
+    /** Initial scene override; call preferredColorScheme when the setting changes. */
+    preferredColorScheme?: PreferredColorScheme;
+    /** The push relay that delivers this app's notifications; omit it for an app without push. */
+    notifications?: {
+        relay: {
+            url: string;
+            publicKey: string;
+            token?: () => string | Promise<string>;
+        };
+    };
+    /** Replaces the framework's offline presentation. */
+    offline?: ComponentType<OfflinePresentationProps>;
+    /** Release builds fall back to a CSS material when WebGPU cannot render. `onGlassError` still receives every failure. */
+    onGlassError?: (error: GlassError) => void;
+    /** Limits on what the scene checkpoint keeps, and for how long the app may be away. */
+    restoration?: {
+        maxAbsenceMs?: number;
+        maxBytes?: number;
+    };
+    className?: string;
+};
+/** The app, routes, navigation and optional root content mounted by runApp. */
+export type RunAppConfiguration<R extends Routes, D extends NavigationDeclaration<R>> = RunAppOptions & {
+    app: AppDefinition;
+    routes: R;
+    navigation: D;
+    content?: ComponentType;
+};
+/**
+ * Mounts the app into `#root`. Satin creates every
+ * primary stack and restores the scene and its launch route before React's first commit, then
+ * owns navigation, restoration, notifications and the app shell. Call it once.
+ *
+ * `Content` replaces the default root, usually to add app-wide providers; it renders `TabView` or
+ * `NavigationStack` itself. Without it Satin renders the declaration directly.
+ *
+ * @example
+ * runApp({ app, routes, navigation })
+ */
+export declare function runApp<R extends Routes, const D extends NavigationDeclaration<R>>({ app, routes, navigation: declaration, content: Content, ...options }: RunAppConfiguration<R, D>): {
+    unmount: () => void;
+};
+/** Either a declared primary stack (optionally naming its tab), or a modal stack inside a `Sheet`
+ * that declares its own root. */
+export type NavigationStackProps<R extends Routes = RegisteredRoutes, D = RegisteredNavigation> = ([D] extends [never] ? {
+    tab: never;
+    modal?: false;
+    root?: never;
+    params?: never;
+} : {
+    modal?: false;
+    tab?: TabId<D>;
+    root?: never;
+    params?: never;
+}) | ({
+    modal: true;
+    tab?: never;
+} & StackDeclaration<R>);
+/**
+ * Renders an in-memory navigation stack. A primary stack's root comes from
+ * `defineNavigation`, never from JSX. Inside a `Sheet`, `modal` with a `root` makes a stack the
+ * sheet owns.
+ *
+ * @example
+ * <Sheet isPresented={open} onPresentedChange={setOpen} title="New Note">
+ *   <NavigationStack modal root="compose" />
+ * </Sheet>
+ */
+export declare function NavigationStack<R extends Routes = RegisteredRoutes, D = RegisteredNavigation>(props: NavigationStackProps<R, D>): import("react").JSX.Element;
+/** Selects which declared primary stack the split view renders; inside a `Tab`, its own. */
+export type NavigationSplitViewProps<D = RegisteredNavigation> = {
+    tab?: TabId<D>;
+};
+/** `NavigationSplitView`: the declared root becomes the sidebar and pushes become the
+ * retained detail stack. It collapses to a plain stack at compact width. A `NavigationStack` never
+ * splits by itself. */
+export declare function NavigationSplitView<D = RegisteredNavigation>(props: NavigationSplitViewProps<D>): import("react").JSX.Element;
+/** The typed parameter tuple accepted by push and replace. */
+export type NavigationArguments<P> = {} extends P ? [params?: P] : [params: P];
+/** The current stack's typed navigation actions. */
+export interface Navigation<R extends Routes> {
+    /** Opens the built-in credit and bundled licenses. Returns false when opted out or while a back gesture owns navigation. */
+    showAcknowledgements(): boolean;
+    /** Pushes a destination. Returns false, pushing nothing, while the user holds a back swipe. */
+    push<K extends keyof R['definitions'] & string>(id: K, ...args: NavigationArguments<RouteProps<R, K>>): boolean;
+    /** Replaces the top entry without a transition. */
+    replace<K extends keyof R['definitions'] & string>(id: K, ...args: NavigationArguments<RouteProps<R, K>>): void;
+    pop(): void;
+    popToRoot(): void;
+}
+/**
+ * Returns the enclosing stack's navigation actions, typed against the registered routes. A wrong
+ * route id or a missing param is a compile error.
+ *
+ * @example
+ * const navigation = useNavigation()
+ * navigation.push('note', { id: note.id })
+ */
+export declare function useNavigation<R extends Routes = RegisteredRoutes>(): Navigation<R>;
+/** TabView's selection binding and bar behaviour; its tabs come from `defineNavigation`. */
+export type TabViewProps<D = RegisteredNavigation> = {
+    /** Optional Tab and TabSection composition referencing the declared navigation IDs. */
+    children?: ReactNode;
+    selection?: TabId<D>;
+    onSelectionChange?: (id: TabId<D>) => void;
+    bottomAccessory?: ReactNode;
+    /** Use custom when the accessory already supplies its own material. Defaults to glass. */
+    bottomAccessoryMaterial?: EngineTabViewProps['bottomAccessoryMaterial'];
+    tabViewStyle?: 'automatic' | 'sidebarAdaptable';
+};
+/** Names the declared tab to render. */
+export type TabProps<D = RegisteredNavigation> = {
+    id: TabId<D>;
+};
+/** Render one declared tab's content; identities and root stacks come from defineNavigation. */
+export declare function Tab<D = RegisteredNavigation>({ id }: TabProps<D>): import("react").JSX.Element;
+/**
+ * `TabView`: renders the tabs from `defineNavigation`, each retaining its own stack, and
+ * restores the selected tab with the scene. Pass `selection` and `onSelectionChange` to control it;
+ * a controlled tab press only requests the change.
+ */
+export declare function TabView<D = RegisteredNavigation>(props: TabViewProps<D>): import("react").JSX.Element;