@octane-xplat/ui 0.3.0 → 0.4.0

package/types/index.d.ts

@@ -6,11 +6,13 @@
 // emit declarations for .tsrx (upstream: tsrx-org/tsrx#136); this file is
 // what `tsc --emitDeclarationOnly` on pure .ts buys us.
 
-import type { UniversalComponent } from 'octane/universal';
+import type { UniversalComponent } from 'octane/universal'
 import type {
 	AnimatedValue,
 	AbsoluteProps,
 	ActivityIndicatorProps,
+	BeforeLoad,
+	BeforeLoadArgs,
 	ColorScheme,
 	DrawerProps,
 	GridProps,
@@ -20,20 +22,30 @@ import type {
 	ImageProps,
 	KeyboardAvoidingProps,
 	LayoutChildProps,
+	LinkProps,
 	ListProps,
+	MeterProps,
 	ModalProps,
 	ModalOpenOptions,
 	ModalOpenResult,
+	NavLinkProps,
 	OpenModal,
+	OpenWindowOptions,
 	OverlayProps,
+	PopoverAnchorRef,
 	PopoverPlacement,
 	PopoverProps,
 	PlatformBadgeProps,
 	PressableProps,
 	ReadableStore,
 	Route,
+	RouteContext,
+	RouteHead,
+	RouteHeadExport,
 	RouteManifest,
 	RouteMeta,
+	RichTextProps,
+	RichTextSpanProps,
 	RowProps,
 	ScreenProps,
 	SafeAreaProps,
@@ -53,12 +65,14 @@ import type {
 	ToastOptions,
 	ToastPosition,
 	ViewProps,
-} from './props';
+} from './props'
 
 export type {
 	AbsoluteProps,
 	AnimatedValue,
 	ActivityIndicatorProps,
+	BeforeLoad,
+	BeforeLoadArgs,
 	ColorScheme,
 	DrawerProps,
 	GridProps,
@@ -68,12 +82,16 @@ export type {
 	ImageProps,
 	KeyboardAvoidingProps,
 	LayoutChildProps,
+	LinkProps,
 	ListProps,
 	ModalProps,
 	ModalOpenOptions,
 	ModalOpenResult,
+	NavLinkProps,
 	OpenModal,
+	OpenWindowOptions,
 	OverlayProps,
+	PopoverAnchorRef,
 	PopoverPlacement,
 	PopoverProps,
 	PanEvent,
@@ -81,8 +99,13 @@ export type {
 	PressableProps,
 	ReadableStore,
 	Route,
+	RouteContext,
+	RouteHead,
+	RouteHeadExport,
 	RouteManifest,
 	RouteMeta,
+	RichTextProps,
+	RichTextSpanProps,
 	RowProps,
 	ScreenProps,
 	SafeAreaProps,
@@ -103,72 +126,87 @@ export type {
 	ToastOptions,
 	ToastPosition,
 	ViewProps,
-} from './props';
+} from './props'
+
+/** ScrollBox shares ScrollView's public shell props; native renders it inline. */
+export type ScrollBoxProps = ScrollViewProps
 
 // ---------- primitives ----------
 
-export declare const View: UniversalComponent<ViewProps>;
+export declare const View: UniversalComponent<ViewProps>
 /** Column-direction alias of View. */
-export declare const Column: UniversalComponent<ViewProps>;
-export declare const Row: UniversalComponent<RowProps>;
-export declare const Grid: UniversalComponent<GridProps>;
-export declare const Stack: UniversalComponent<StackProps>;
-export declare const Absolute: UniversalComponent<AbsoluteProps>;
-export declare const Spacer: UniversalComponent<SpacerProps>;
-export declare const Text: UniversalComponent<TextProps>;
-export declare const Pressable: UniversalComponent<PressableProps>;
-export declare const TextInput: UniversalComponent<TextInputProps>;
-export declare const TextArea: UniversalComponent<TextAreaProps>;
-export declare const List: UniversalComponent<ListProps>;
-export declare const ScrollView: UniversalComponent<ScrollViewProps>;
-export declare const Image: UniversalComponent<ImageProps>;
-export declare const Screen: UniversalComponent<ScreenProps>;
-export declare const SafeArea: UniversalComponent<SafeAreaProps>;
-export declare const KeyboardAvoiding: UniversalComponent<KeyboardAvoidingProps>;
-export declare const Drawer: UniversalComponent<DrawerProps>;
-export declare const Switch: UniversalComponent<SwitchProps>;
-export declare const ActivityIndicator: UniversalComponent<ActivityIndicatorProps>;
-export declare const Slider: UniversalComponent<SliderProps>;
-export declare const Icon: UniversalComponent<IconProps>;
-export declare const Heading: UniversalComponent<HeadingProps>;
-export declare const PlatformBadge: UniversalComponent<PlatformBadgeProps>;
-
-export declare function registerIcon(name: string, glyph: IconGlyph): void;
-export declare function registerIcons(record: Record<string, IconGlyph>): void;
+export declare const Column: UniversalComponent<ViewProps>
+export declare const Row: UniversalComponent<RowProps>
+export declare const Grid: UniversalComponent<GridProps>
+export declare const Stack: UniversalComponent<StackProps>
+export declare const Absolute: UniversalComponent<AbsoluteProps>
+export declare const Spacer: UniversalComponent<SpacerProps>
+export declare const Text: UniversalComponent<TextProps>
+export declare const RichText: UniversalComponent<RichTextProps>
+export declare const RichTextSpan: UniversalComponent<RichTextSpanProps>
+export declare const Pressable: UniversalComponent<PressableProps>
+export declare const Link: UniversalComponent<LinkProps>
+export declare const NavLink: UniversalComponent<NavLinkProps>
+export declare const TextInput: UniversalComponent<TextInputProps>
+export declare const TextArea: UniversalComponent<TextAreaProps>
+export declare const List: UniversalComponent<ListProps>
+export declare const ScrollBox: UniversalComponent<ScrollBoxProps>
+export declare const ScrollView: UniversalComponent<ScrollViewProps>
+export declare const Image: UniversalComponent<ImageProps>
+export declare const Screen: UniversalComponent<ScreenProps>
+export declare const SafeArea: UniversalComponent<SafeAreaProps>
+export declare const KeyboardAvoiding: UniversalComponent<KeyboardAvoidingProps>
+export declare const Drawer: UniversalComponent<DrawerProps>
+export declare const Switch: UniversalComponent<SwitchProps>
+export declare const ActivityIndicator: UniversalComponent<ActivityIndicatorProps>
+export declare const Meter: UniversalComponent<MeterProps>
+export declare const Slider: UniversalComponent<SliderProps>
+export declare const Icon: UniversalComponent<IconProps>
+export declare const Heading: UniversalComponent<HeadingProps>
+export declare const PlatformBadge: UniversalComponent<PlatformBadgeProps>
+
+export declare function registerIcon(name: string, glyph: IconGlyph): void
+export declare function registerIcons(record: Record<string, IconGlyph>): void
 
 // ---------- overlays / shells ----------
 
-export declare const Modal: UniversalComponent<ModalProps>;
-export declare const openModal: OpenModal;
-export declare const Overlay: UniversalComponent<OverlayProps>;
-export declare const Popover: UniversalComponent<PopoverProps>;
-export declare function showToast(content: ToastContent, options?: ToastOptions): void;
-export declare const Tabs: UniversalComponent<TabsProps>;
+export declare const Modal: UniversalComponent<ModalProps>
+export declare const openModal: OpenModal
+export declare function openWindow(options?: OpenWindowOptions): any
+export declare const Overlay: UniversalComponent<OverlayProps>
+export declare const Popover: UniversalComponent<PopoverProps>
+export declare function showToast(content: ToastContent, options?: ToastOptions): void
+export declare const Tabs: UniversalComponent<TabsProps>
 
 // ---------- stacks (native registry; no-op on web) ----------
 
-export declare function registerStack(name: string, frame: any): void;
-export declare function getStack(name: string): any;
-export declare function stackEntries(): IterableIterator<[string, any]>;
+export declare function registerStack(name: string, frame: any): void
+export declare function getStack(name: string): any
+export declare function stackEntries(): IterableIterator<[string, any]>
 
 // ---------- routes (real on both: URL store on web, Frame stacks on native) ----------
 
-export declare function pushRoute(r: Route): void;
-export declare function popRoute(stack?: string): void;
-export declare function routeFor(stack: string): Route | null;
-export declare function currentRoute(): Route | null;
-export declare function useRoute(stack: string): Route | null;
+export declare function pushRoute(r: Route): void
+export declare function popRoute(stack?: string): void
+export declare function routeStacks(): string[]
+export declare function layoutsForRoute(name: string): any[]
+export declare function routeFor(stack: string): Route | null
+export declare function currentRoute(): Route | null
+export declare function canGoBack(stack?: string): boolean
+export declare function useCanGoBack(stack?: string): boolean
+export declare function redirect(route: Route): never
+export declare function useRoute(stack: string): Route | null
 /** name → screen table; native pushRoute resolves `route.name` through
  *  it, web outlets fall back to it via `screenFor`. `manifest` (from
  *  deriveRouteManifest) enables path-param URL matching on web. Call
  *  once at boot. */
-export declare function registerScreens(table: ScreenTable, manifest?: RouteMeta[]): void;
+export declare function registerScreens(table: ScreenTable, manifest?: RouteMeta[]): void
 /** One-call registration for route-dir apps — screens + URL patterns +
  *  layouts all come from deriveRouteManifest. */
-export declare function registerRoutes(manifest: RouteManifest): void;
-export declare function screenFor(name: string): any;
+export declare function registerRoutes(manifest: RouteManifest): void
+export declare function screenFor(name: string): any
 /** Canonical /<stack>/<path> for a Route — Link's href on web. */
-export declare function hrefFor(r: Route): string;
+export declare function hrefFor(r: Route): string
 
 // ---------- route dir (file → route manifest; docs/navigation-notes.md) ----------
 
@@ -180,25 +218,31 @@ export declare function deriveRouteManifest(
 	files: Record<string, any>,
 	prefer: readonly string[],
 	dir?: string,
-): RouteManifest;
+): RouteManifest
 
 // ---------- animation / theme ----------
 
-export declare function useAnimation(initial?: number, prop?: string): AnimatedValue;
-export declare function getColorScheme(): ColorScheme;
-export declare function useColorScheme(): ColorScheme;
-export interface SafeAreaInsets { top: number; right: number; bottom: number; left: number; }
-export declare function useSafeAreaInsets(): SafeAreaInsets;
+export declare function useAnimation(initial?: number, prop?: string): AnimatedValue
+export declare function getColorScheme(): ColorScheme
+export declare function useColorScheme(): ColorScheme
+export interface SafeAreaInsets {
+	top: number
+	right: number
+	bottom: number
+	left: number
+}
+
+export declare function useSafeAreaInsets(): SafeAreaInsets
 
 // ---------- styled ----------
 
 export declare function styled<P extends { className?: any }, V extends Record<string, any>>(
 	Base: (props: P) => any,
 	def: { base?: any; variants?: V },
-): UniversalComponent<P & { [K in keyof V]?: boolean }>;
+): UniversalComponent<P & { [K in keyof V]?: boolean }>
 
 // ---------- stores ----------
 
-export declare function createStore<T>(initial: T): Store<T>;
-export declare function useStore<T>(store: ReadableStore<T>): T;
-export declare function useStore<T, S>(store: ReadableStore<T>, select: (state: T) => S): S;
+export declare function createStore<T>(initial: T): Store<T>
+export declare function useStore<T>(store: ReadableStore<T>): T
+export declare function useStore<T, S>(store: ReadableStore<T>, select: (state: T) => S): S

package/types/props.d.ts

@@ -32,7 +32,42 @@ export interface LayoutChildProps {
     alignSelf?: string;
     order?: number;
 }
-export interface GridProps {
+/** Flex-container props shared by View/Row/Pressable — RN vocabulary, applied
+ *  to the host flexboxlayout natively and the element's style on web.
+ *  `gap` is a dip number (px on web); NS supports it on FlexboxLayout only
+ *  (GridLayout has no gap). */
+export interface FlexContainerProps {
+    justifyContent?: 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly';
+    alignItems?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+    flexWrap?: boolean | 'wrap' | 'nowrap' | 'wrap-reverse';
+    gap?: number | string;
+    rowGap?: number | string;
+    columnGap?: number | string;
+}
+/** Liquid Glass material config. Native maps it to `iosGlassEffect`
+ *  (iOS 26+; inert on Android and older iOS), web to the `vx-glass`
+ *  backdrop-filter approximation. `variant:'clear'` is the faint,
+ *  mostly-transparent glass; `'regular'` is Apple's default. */
+export interface GlassConfig {
+    variant?: 'regular' | 'clear' | 'identity' | 'none';
+    /** Touch-tracking highlight — only meaningful on <LiquidGlass>; the
+     *  per-view glass applied by `glass` never receives touches upstream. */
+    interactive?: boolean;
+    tint?: string;
+    /** (LiquidGlassContainer only) merge distance between glass siblings. */
+    spacing?: number;
+    /** Effect-change animation in ms (default 300). */
+    animateChangeDuration?: number;
+}
+/** `glass` surface prop value: `true`/string shorthand or a config object.
+ *  `'none'`/`'identity'`/`false` mean no glass. */
+export type GlassProp = boolean | 'regular' | 'clear' | 'identity' | 'none' | GlassConfig;
+/** Static glass material on container primitives — background glass behind
+ *  the view's content. Interactive glass needs <LiquidGlass>. */
+export interface GlassSurfaceProps {
+    glass?: GlassProp;
+}
+export interface GridProps extends GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
@@ -42,22 +77,55 @@ export interface GridProps {
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
-export interface StackProps {
+export interface StackProps extends GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
-export interface AbsoluteProps {
+export interface AbsoluteProps extends GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
+}
+/** Interactive glass surface — the element root IS the platform's glass
+ *  effect view (NS `LiquidGlass`, a UIVisualEffectView hosting children).
+ *  Real material on iOS 26+; inert layout on Android and older iOS;
+ *  backdrop-filter approximation on web. */
+export interface LiquidGlassProps extends LayoutChildProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    id?: string;
+    variant?: 'regular' | 'clear';
+    interactive?: boolean;
+    tint?: string;
+    animateChangeDuration?: number;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+/** Merged-glass region — sibling glass elements inside morph together
+ *  across `spacing` dips (NS `LiquidGlassContainer`, an AbsoluteLayout:
+ *  children position via left/top). */
+export interface LiquidGlassContainerProps extends LayoutChildProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    id?: string;
+    spacing?: number;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
 }
 export interface SpacerProps {
     className?: any;
@@ -65,8 +133,9 @@ export interface SpacerProps {
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
-export interface ViewProps extends LayoutChildProps {
+export interface ViewProps extends LayoutChildProps, FlexContainerProps, GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
@@ -81,10 +150,11 @@ export interface ViewProps extends LayoutChildProps {
     android?: any;
     web?: any;
 }
-export interface RowProps extends LayoutChildProps {
+export interface RowProps extends LayoutChildProps, FlexContainerProps, GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
+    id?: string;
     /** Platform-specific properties are applied after shared props. */
     ios?: any;
     android?: any;
@@ -94,6 +164,7 @@ export interface TextProps extends LayoutChildProps {
     className?: any;
     style?: any;
     children?: any;
+    id?: string;
     numberOfLines?: number;
     /** Native Label does not expose text selection; implemented with CSS on web. */
     selectable?: boolean;
@@ -114,7 +185,32 @@ export interface TextProps extends LayoutChildProps {
     android?: any;
     web?: any;
 }
-export interface PressableProps extends LayoutChildProps {
+/** Inline rich text container. Children should be RichTextSpan components so
+ * the native leaf can preserve each run as a NativeScript Span. */
+export interface RichTextProps extends LayoutChildProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    id?: string;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** One styled or tappable inline run inside RichText. `text` is an explicit
+ * native-safe escape hatch; a single string child is also accepted. */
+export interface RichTextSpanProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    text?: string;
+    onPress?: () => void;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface PressableProps extends LayoutChildProps, FlexContainerProps, GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
@@ -200,9 +296,6 @@ export interface ListProps {
     /** Stable item key for web reconciliation. Falls back to `item.id`; native
      *  ListView recycles by index and does not consume keys. */
     keyFor?: (item: any) => string | number;
-    /** Metadata hint only in v1. Switch heterogeneous row markup in renderItem;
-     *  the current renderers do not consume this value. */
-    kindFor?: (item: any) => string;
     /** Native iOS row-height estimate. Web virtualization is not enabled in v1. */
     estimatedItemHeight?: number;
     /** Called when the list approaches its end. */
@@ -212,7 +305,7 @@ export interface ListProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
-export interface ScrollViewProps extends LayoutChildProps {
+export interface ScrollViewProps extends LayoutChildProps, GlassSurfaceProps {
     className?: any;
     style?: any;
     id?: string;
@@ -223,6 +316,19 @@ export interface ScrollViewProps extends LayoutChildProps {
     android?: any;
     web?: any;
 }
+/** Scrollable ordinary content on web. Native is an inline flex container so
+ * a child ListView can own the scrolling without nesting recycling views in a
+ * native ScrollView. */
+export interface ScrollBoxProps extends LayoutChildProps, GlassSurfaceProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    children?: any;
+    /** Platform-specific properties are applied after the shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
 export interface ImageProps extends LayoutChildProps {
     className?: any;
     style?: any;
@@ -242,6 +348,7 @@ export interface ScreenProps {
     ios?: any;
     android?: any;
     web?: any;
+    id?: string;
 }
 export interface SafeAreaProps {
     className?: any;
@@ -251,6 +358,7 @@ export interface SafeAreaProps {
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
 export interface KeyboardAvoidingProps {
     className?: any;
@@ -259,10 +367,12 @@ export interface KeyboardAvoidingProps {
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
 export interface DrawerProps {
     className?: any;
     style?: any;
+    id?: string;
     main?: any;
     drawer?: any;
     open?: boolean;
@@ -290,6 +400,19 @@ export interface ActivityIndicatorProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
+export interface MeterProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    children?: any;
+    value: number;
+    max?: number;
+    size?: number;
+    strokeWidth?: number;
+    color?: string;
+    trackColor?: string;
+    accessibilityLabel?: string;
+}
 export interface SliderProps {
     className?: any;
     style?: any;
@@ -313,9 +436,16 @@ export interface IconProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
-/** One registered icon representation. `svg` contains path `d` data. */
+/** One registered icon representation. `svg` contains path `d` data;
+ *  `markup` is full inner-SVG markup (groups, transforms, several paths)
+ *  rendered inside an `<svg viewBox>` shell on web and through `svgview`
+ *  (ui-svg) on native. `font`, `src`, and `text` are per-platform
+ *  fallbacks, in that order. */
 export interface IconGlyph {
     svg?: string;
+    markup?: string;
+    viewBox?: string;
+    text?: string;
     font?: {
         family: string;
         glyph: string;
@@ -348,11 +478,17 @@ export interface OverlayProps {
     web?: Record<string, any>;
 }
 export type PopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
+/** A platform-neutral ref to the host view or element that owns a popover. */
+export interface PopoverAnchorRef {
+    readonly current: unknown;
+}
 export interface PopoverProps {
-    /** Native view or web element, commonly a ref object populated by `bind`. */
-    anchor?: any;
+    /** Ref to a native view or web element, commonly populated by `bind`. */
+    anchor: PopoverAnchorRef;
     open?: boolean;
     placement?: PopoverPlacement;
+    dismissOnOutsideTap?: boolean;
+    onDismiss?: () => void;
     className?: any;
     style?: any;
     children?: any;
@@ -396,6 +532,32 @@ export interface ModalOpenOptions {
 export type ModalOpenResult = unknown;
 /** Public function shape of the imperative modal service. */
 export type OpenModal = (component: any, params?: any, options?: ModalOpenOptions) => Promise<ModalOpenResult>;
+/** Declarative in-window sheet: bottom-anchored panel on the enclosing
+ *  screen's RootLayout (native) or a document-body portal layer (web).
+ *  Unlike `Modal presentation='sheet'` (system modal), content stays
+ *  inside the app window — same window region as the declaring page. */
+export interface SheetProps {
+    open?: boolean;
+    /** Called when the shade is tapped or the sheet is dismissed by the
+     *  platform — not on programmatic `open`→`false` transitions. */
+    onDismiss?: () => void;
+    /** Dim backdrop + tap-to-dismiss (default true). */
+    shadeCover?: boolean;
+    className?: any;
+    style?: any;
+    children?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+/** Options for the imperative `openSheet` service. */
+export interface SheetOpenOptions {
+    shadeCover?: boolean;
+}
+/** Imperative sheet: mounts `component` on a dedicated root in a bottom
+ *  sheet and resolves with the value passed to `close(result)`. The
+ *  component receives `{ params, close }`. */
+export type OpenSheet = (component: any, params?: any, options?: SheetOpenOptions) => Promise<ModalOpenResult>;
 export interface TabSpec {
     title: string;
     render: () => any;
@@ -419,6 +581,44 @@ export interface Route {
     stack: string;
     name: string;
     params: Record<string, unknown>;
+    /** 'push' (default) pushes onto the stack · 'modal' opens its own root
+     *  (native: `showModal`; web: overlay pane, URL preserved) · 'fade' is a
+     *  push with a fade transition. A `+modal`/`+fade` filename suffix in
+     *  the route dir sets the manifest default; this field overrides it. */
+    presentation?: 'push' | 'modal' | 'fade';
+    /** Loader result supplied to the route screen as `data`. */
+    loaderData?: unknown;
+    /** Loader rejection supplied to the route screen as `error`. */
+    loaderError?: unknown;
+    /** Context returned by the route's `beforeLoad` export. It is merged into
+     * screen props and remains available from `useRoute`. */
+    context?: RouteContext;
+}
+/** Values shared by a route guard and the screen it admits. */
+export type RouteContext = Record<string, unknown>;
+export interface BeforeLoadArgs {
+    params: Record<string, unknown>;
+    context: RouteContext;
+}
+export type BeforeLoad = (args: BeforeLoadArgs) => RouteContext | void | Promise<RouteContext | void>;
+/** The deliberately small cross-platform head surface. `meta` keys become
+ * web `<meta name="..." content="...">` tags; native consumes `title`. */
+export interface RouteHead {
+    title?: string;
+    meta?: Record<string, string>;
+}
+export type RouteHeadExport = RouteHead | ((params: Record<string, unknown>) => RouteHead);
+export interface LinkProps {
+    href: string;
+    target?: string;
+    className?: any;
+    children?: any;
+}
+export interface NavLinkProps {
+    route: Route;
+    activeClassName?: string;
+    className?: any;
+    children?: any;
 }
 /** name → screen component table for `registerScreens` — the app owns the
  *  route table; native `pushRoute` resolves `route.name` through it and
@@ -435,6 +635,19 @@ export interface RouteMeta {
     params: string[];
     /** Source file (glob key) — diagnostics only. */
     file: string;
+    /** Declared default presentation — set by a `+modal`/`+fade` filename
+     *  suffix (`app/settings+modal.tsrx` → route 'settings', modal). */
+    presentation?: 'push' | 'modal' | 'fade';
+    /** Optional `loader` named export — a prefetch hook, not a data layer.
+     *  pushRoute fires it (fire-and-forget) before navigating so the
+     *  screen's `query$` reads hit a warm cache; boot/deep-link routes
+     *  skip it (the screen mounts in the same tick anyway). */
+    loader?: (params: Record<string, unknown>) => unknown;
+    /** Optional guard awaited before a push commits. A thrown `redirect(...)`
+     * short-circuits the attempted route. */
+    beforeLoad?: BeforeLoad;
+    /** Optional route title/meta declaration, or a params-only function. */
+    head?: RouteHeadExport;
 }
 /** Output of `deriveRouteManifest` — `screens` feeds `registerScreens`
  *  (native pushRoute + web outlet fallback), `routes` feeds web URL
@@ -443,6 +656,13 @@ export interface RouteManifest {
     screens: ScreenTable;
     routes: RouteMeta[];
     layouts: Record<string, any>;
+    loaders?: Record<string, (params: Record<string, unknown>) => unknown | Promise<unknown>>;
+}
+export interface OpenWindowOptions {
+    /** Data made available to the native window content resolver. */
+    data?: Record<string, unknown>;
+    /** Optional URL used by the web window. */
+    url?: string;
 }
 export interface AnimatedValue {
     readonly value: number;