@octane-xplat/ui 0.6.0 → 0.7.0

package/types/{props.d.ts → generated/props.d.ts}

@@ -1,9 +1,8 @@
 /** Shared prop/type contract — the single source of truth for the public
  *  API surface. Platform leaves import these types so prop shapes cannot
- *  drift across .web/.native, and `tsc --emitDeclarationOnly` emits this
- *  file into the published package's boundary types (tsrx can't emit
- *  declarations — pure .ts is what escapes that). No imports here:
- *  everything must stay dependency-free and platform-agnostic. */
+ *  drift across .web/native-default, and `tsrx-typegen` emits the package's
+ *  declarations from its public entrypoints and component leaves. No imports
+ *  here: the shared contracts stay dependency-free and platform-agnostic. */
 export interface PanEvent {
     x: number;
     y: number;
@@ -37,6 +36,30 @@ export interface LayoutChildProps {
     alignSelf?: string;
     order?: number;
 }
+/** JSON-compatible modifier data accepted by the platform-authentic widgets. */
+export type NativeModifierValue = string | number | boolean | null | readonly NativeModifierValue[] | {
+    readonly [key: string]: NativeModifierValue;
+};
+/** A serializable change to a NativeScript view's style or native property.
+ *  Platform-specific UI subpaths apply modifier arrays after shared props and
+ *  the matching `ios`/`android` escape bag. */
+export type NativeModifier = {
+    type: 'style';
+    values: Record<string, NativeModifierValue | undefined>;
+} | {
+    type: 'property';
+    name: string;
+    value: NativeModifierValue;
+};
+/** Adds the native-only modifier escape hatch to an OS-backed widget's props. */
+export type PlatformWidgetProps<Props> = Props & {
+    modifiers?: readonly NativeModifier[];
+};
+/** Native glyph names for the OS-authentic UI subpaths. */
+export interface PlatformIconChoice {
+    ios: string;
+    android: string;
+}
 /** 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
@@ -371,32 +394,6 @@ export interface ListProps extends RefreshProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
-/** Paged horizontal swipe container — onboarding flows, media galleries.
- *  Chrome-reset OS paging on native (ViewPager2 / UICollectionView paging via
- *  @nativescript-community/ui-pager), a scroll-snap scroller on web. Follows
- *  the platform-list contract: `items` + `renderItem`, no children — each
- *  page is a full-host-size cell. No indicator is built in; compose dots
- *  from `Row` + `View` driven by `page`/`onPageChange`. */
-export interface PagerProps extends LayoutChildProps, AccessibilityProps {
-    className?: any;
-    style?: any;
-    id?: string;
-    items: any[];
-    renderItem: (item: any, index: number) => any;
-    renderEmpty?: () => any;
-    /** Controlled page index — pass with `onPageChange` to own the page.
-     *  Writes scroll/settle to the page; user swipes call `onPageChange`. */
-    page?: number;
-    /** Starting page for uncontrolled use (default 0). */
-    defaultPage?: number;
-    /** Fires when the settled page changes — a completed swipe on both
-     *  targets. Programmatic `page` writes do not echo back through it. */
-    onPageChange?: (index: number) => void;
-    /** Platform escape hatches, applied after the shared props. */
-    ios?: Record<string, any>;
-    android?: Record<string, any>;
-    web?: Record<string, any>;
-}
 export interface ScrollViewProps extends LayoutChildProps, AccessibilityProps, RefreshProps {
     className?: any;
     style?: any;
@@ -408,6 +405,26 @@ export interface ScrollViewProps extends LayoutChildProps, AccessibilityProps, R
     android?: any;
     web?: any;
 }
+/** Shared virtualized vertical list. Item keys must be unique and stable
+ *  across inserts and reorders. Rows outside the rendered window unmount;
+ *  keep durable row state keyed by item identity outside the row component. */
+export interface VirtualListProps<T = any> extends LayoutChildProps, AccessibilityProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    items: readonly T[];
+    keyExtractor: (item: T, index: number) => string | number;
+    getItemType?: (item: T, index: number) => string | number;
+    renderItem: (item: T, index: number) => any;
+    renderEmpty?: () => any;
+    renderHeader?: () => any;
+    renderFooter?: () => any;
+    renderSeparator?: () => any;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, 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. */
@@ -438,6 +455,10 @@ export interface WebViewLoadEvent {
     /** Failure description; present only on the `onError` path. */
     error?: string;
 }
+export interface WebViewContentSize {
+    width: number;
+    height: number;
+}
 /** Embedded web document — chrome-reset bucket: web renders a sandboxed
  *  `<iframe>`, native renders the OS web view (`webview` → WKWebView /
  *  android.webkit.WebView). The *frame* is normalized; the document's
@@ -461,6 +482,12 @@ export interface WebViewProps extends LayoutChildProps, AccessibilityProps {
     /** After each successful document load (web `load`; native
      *  `loadFinished` without an error). */
     onLoad?: (e: WebViewLoadEvent) => void;
+    /** Report the embedded document's measured size when the platform can read
+     *  it. Cross-origin browser frames cannot be inspected. */
+    onLayoutContent?: (size: WebViewContentSize) => void;
+    /** Resize the host to the embedded document's measured height. Browser
+     *  frames must be same-origin; native measurement is best-effort. */
+    matchContents?: boolean;
     /** On load failure. Native reports the NS `loadFinished` error string;
      *  web maps the iframe `error` event, which does not fire reliably
      *  cross-browser — treat as best-effort there. */
@@ -510,6 +537,8 @@ export interface SafeAreaProps {
     className?: any;
     style?: any;
     children?: any;
+    /** Do not inset the child away from the system's safe area. */
+    ignoreSafeArea?: boolean;
     /** NativeScript props applied to the host after shared props. */
     ios?: Record<string, any>;
     android?: Record<string, any>;
@@ -655,7 +684,10 @@ export interface PopoverProps {
     web?: Record<string, any>;
 }
 export interface HoverableProps {
-    /** Content shown after the pointer rests over the children on web. */
+    id?: string;
+    /** Content shown after the pointer rests over the children on pointer
+     *  platforms (web, macOS). Touch targets never mount the card — keep
+     *  essential information out of it. */
     card: any;
     /** Styling for the card's wrapper view inside the popover — e.g. a
      *  pointer bridge covering the anchor↔card gap or a positional offset. */
@@ -671,11 +703,13 @@ export interface HoverableProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
-/** Web-only tooltip (`@octane-xplat/ui/web`, decision #47) — `trigger` is
- *  the anchor content, `content` the tooltip body. Hover-intent delay plus
- *  keyboard focus; wires `aria-describedby` onto the focusable trigger and
- *  dismisses on Escape, blur, or scroll. */
+/** Tooltip — `trigger` is the anchor content, `content` the hint body.
+ *  Pointer platforms show the hint after hover/focus intent (web adds
+ *  `aria-describedby` + Escape/scroll dismissal; macOS presents an anchored
+ *  NSPopover). Touch targets render the trigger and never mount the hint —
+ *  keep essential information out of `content`. */
 export interface TooltipProps {
+    id?: string;
     trigger: any;
     content: any;
     /** Styling for the tooltip panel inside the popover. */
@@ -809,6 +843,16 @@ export interface TabsProps {
      *  Web: route outlet. Native: pushes render inside the pane's Frame. */
     resolveScreen?: (name: string, params: Record<string, unknown>) => any;
 }
+/** Platform tab-bar item shape. `icon` may be a registered name or a native
+ *  asset value returned by `Icon.select()` from the matching subpath. */
+export type PlatformTabSpec = Omit<TabSpec, 'icon'> & {
+    icon?: string;
+};
+export type PlatformTabsProps = Omit<TabsProps, 'tabs'> & {
+    tabs: readonly PlatformTabSpec[];
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+};
 export interface Route {
     stack: string;
     name: string;
@@ -890,6 +934,28 @@ export interface RouteManifest {
     layouts: Record<string, any>;
     loaders?: Record<string, (params: Record<string, unknown>) => unknown | Promise<unknown>>;
 }
+/** One programmatic route entry for `defineRoutes` — the manifest fields a
+ *  route file would have produced, supplied directly. `path` uses the
+ *  route-dir vocabulary: `'docs/:slug'` (or `'docs/[slug]'`), `'index'`/`''`
+ *  for the root route. `screen` is the component itself — not a module. */
+export interface RouteSpec {
+    path: string;
+    screen: any;
+    /** Default presentation, like a `+modal`/`+fade` filename suffix. */
+    presentation?: 'push' | 'modal' | 'fade';
+    loader?: RouteMeta['loader'];
+    beforeLoad?: BeforeLoad;
+    head?: RouteHeadExport;
+    /** Diagnostics label recorded on `RouteMeta.file` (warn strings). */
+    source?: string;
+}
+/** Input to `defineRoutes`: the route list plus optional path-keyed layouts
+ *  — `layouts: { docs: Shell }` plays the `_layout.tsrx` role for every
+ *  route under `docs/*`. */
+export interface RouteSpecSet {
+    routes: readonly RouteSpec[];
+    layouts?: Record<string, any>;
+}
 export interface OpenWindowOptions {
     /** Data made available to the native window content resolver. */
     data?: Record<string, unknown>;
@@ -1152,6 +1218,32 @@ export interface FieldGroupProps {
     android?: any;
     web?: any;
 }
+/** Shared settings/navigation row. Use the four shorthand props for common
+ *  rows, or `ListItem.Leading`/`Content`/`Supporting`/`Trailing` children
+ *  when the row needs custom composition. */
+export interface ListItemProps extends AccessibilityProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    title?: any;
+    supportingText?: any;
+    leading?: any;
+    trailing?: any;
+    onPress?: () => void;
+    disabled?: boolean;
+    children?: any;
+}
+export interface ListItemSlotProps {
+    className?: any;
+    children?: any;
+}
+export interface ListItemComponent {
+    (props: ListItemProps): unknown;
+    Leading: (props: ListItemSlotProps) => unknown;
+    Content: (props: ListItemSlotProps) => unknown;
+    Supporting: (props: ListItemSlotProps) => unknown;
+    Trailing: (props: ListItemSlotProps) => unknown;
+}
 /** InputNumber — normalized TextInput (number keyboard) flanked by −/+
  *  steppers. `value`/`onValueChange` for controlled, `defaultValue` for
  *  uncontrolled. `step` defaults to 1; `min`/`max` clamp. */
@@ -1523,104 +1615,6 @@ export interface ProgressGroupProps {
     android?: any;
     web?: any;
 }
-export type VideoFit = 'contain' | 'cover' | 'fill';
-export interface VideoEvent {
-    /** Playback position in milliseconds. */
-    position?: number;
-    /** Clip duration in milliseconds, once known (0 before then). */
-    duration?: number;
-    /** Failure description. */
-    message?: string;
-}
-export interface VideoHandle {
-    play(): void;
-    pause(): void;
-    /** Seek to a position in milliseconds. */
-    seekTo(ms: number): void;
-    /** Current playback position in ms (0 before metadata loads). */
-    currentTime(): number;
-    /** Clip duration in ms (0 before metadata loads). */
-    duration(): number;
-    /** The platform surface (`HTMLVideoElement` / plugin `Video`). */
-    native: any;
-}
-/** Embedded video — surface-hosted bucket: the OS engine owns the pixels
- *  (web `<video>` / `@nstudio/nativescript-exoplayer` → AVPlayerViewController
- *  + ExoPlayer2), all chrome is self-drawn so `controls` looks identical on
- *  every target. Times are milliseconds on every platform. */
-export interface VideoProps extends LayoutChildProps, AccessibilityProps {
-    className?: any;
-    style?: any;
-    id?: string;
-    /** Remote URL; native also accepts `~/` bundle paths and absolute files. */
-    src: string;
-    /** Frame shown until playback starts. */
-    poster?: string;
-    /** Controlled playback — pair with `onPlayingChange`. Leave unset for
-     *  uncontrolled playback (the transport and `bind` handle still work). */
-    playing?: boolean;
-    /** Uncontrolled start-playing shorthand. Browsers block unmuted
-     *  autoplay — pair with `muted` when `autoPlay` matters on web. */
-    autoPlay?: boolean;
-    muted?: boolean;
-    loop?: boolean;
-    /** Self-drawn transport overlay (play/pause, scrubber, time, mute) —
-     *  tap the surface to show/hide. Default true. */
-    controls?: boolean;
-    /** Content fitting inside the frame: `contain` (letterbox, default),
-     *  `cover` (crop to fill), `fill` (stretch). */
-    fit?: VideoFit;
-    /** Playback metadata is loaded; `e.duration` is the clip length in ms. */
-    onReady?: (e: VideoEvent) => void;
-    onEnded?: () => void;
-    /** Fires on user toggles and controlled `playing` writes. */
-    onPlayingChange?: (playing: boolean) => void;
-    /** Fires when the transport's mute button toggles. */
-    onMutedChange?: (muted: boolean) => void;
-    /** Web only — the plugin players surface no error event on native. */
-    onError?: (e: VideoEvent) => void;
-    /** Imperative handle — play/pause/seek/time plus `native` for anything
-     *  the shared props don't cover. */
-    bind?: (h: VideoHandle) => void;
-    /** Platform escape hatches, applied after the shared props. */
-    ios?: Record<string, any>;
-    android?: Record<string, any>;
-    web?: Record<string, any>;
-}
-export interface CameraViewHandle {
-    /** The platform view (`HTMLVideoElement` / plugin `CameraPlus`). */
-    native: any;
-}
-/** Live camera preview — surface-hosted: web runs `getUserMedia` into a
- *  `<video>`, native embeds `CameraPlus` (@nstudio/nativescript-camera-plus;
- *  AVCaptureSession preview / CameraX FancyCamera) with its built-in
- *  buttons switched off. Still capture is deliberately not on the handle —
- *  `media.capturePhoto` in `@octane-xplat/platform` owns that; reach the
- *  preview's own capture (e.g. `CameraPlus.takePicture`) through `bind`'s
- *  `native` when the intent UI won't do. The leaf owns the permission
- *  request on both platforms. */
-export interface CameraViewProps extends LayoutChildProps, AccessibilityProps {
-    className?: any;
-    style?: any;
-    id?: string;
-    /** Lens — default `'back'`. */
-    facing?: 'front' | 'back';
-    /** Default true. `false` tears down the preview stream/session. */
-    active?: boolean;
-    /** The preview surface is live (web: first frame; native: view loaded
-     *  after permission — the sensor may still be warming). */
-    onReady?: () => void;
-    onError?: (e: {
-        message?: string;
-    }) => void;
-    /** Imperative handle — `native` for anything the shared props don't
-     *  cover (torch, zoom, preview-frame capture). */
-    bind?: (h: CameraViewHandle) => void;
-    /** Platform escape hatches, applied after the shared props. */
-    ios?: Record<string, any>;
-    android?: Record<string, any>;
-    web?: Record<string, any>;
-}
 export type ColorScheme = 'light' | 'dark';
 /** Minimal external-store contract `useStore` subscribes to. */
 export interface ReadableStore<T> {

package/types/generated/refresh-metrics.d.ts

@@ -0,0 +1,8 @@
+/** Pull-to-refresh geometry — one strip height drives the indicator
+ *  reveal, the default trigger threshold, and the docked gap on every
+ *  target (px on web, dip on native — equal by the dip≈px contract). */
+export declare const REFRESH_HEADER_HEIGHT = 64;
+/** Finger-travel → content displacement. iOS rubber-band applies ~0.5
+ *  resistance at small pulls; web/Android drive the same ratio so the
+ *  affordance reads identically across targets. */
+export declare function dampenPull(dy: number): number;

package/types/generated/refresh.d.ts

@@ -0,0 +1,42 @@
+export interface RefreshConfig {
+    onRefresh?: () => void;
+    refreshing?: boolean;
+    threshold?: number;
+}
+export interface RefreshHost {
+    /** The scrolling view — NS ScrollView or ListView. */
+    scroller: any;
+    /** The overlay strip (owns the self-drawn spinner), translated in/out. */
+    indicator: any;
+    /** True when the scroller is resting at its top edge (Android only —
+     *  iOS reads the overscroll directly from contentOffset). */
+    isAtTop: () => boolean;
+    /** Latest props — a ref so callback identity churn can't re-attach. */
+    cfg: {
+        current: RefreshConfig;
+    };
+}
+export interface RefreshController {
+    /** Call when `refreshing` changes — docks/undocks the indicator. */
+    sync: () => void;
+    detach: () => void;
+}
+/** Pan-driven pull-to-refresh over any NS scrollable (scrollview or
+ *  listview). Two mechanics, one visual:
+ *
+ *  iOS — UIScrollView's own bounce supplies the content displacement
+ *  (NS gesture delegates allow simultaneous recognition, so our pan on
+ *  the scroller observes alongside the scroll pan). The handler reads
+ *  `contentOffset` for the live gap and docks with
+ *  `contentInset.top += H` — the exact mechanics UIRefreshControl uses.
+ *
+ *  Android — there is no overscroll; the scroller box itself is
+ *  translated inside the clipping wrapper while the damped drag
+ *  accumulates. Docking holds the translate at H. Edge glow is disabled
+ *  (OVER_SCROLL_NEVER) so no OS chrome leaks into the pixels.
+ *
+ *  Releasing past `threshold` fires `onRefresh` once per pull and holds
+ *  the docked gap; the controlled `refreshing` prop keeps it docked.
+ *  A short grace window collapses the dock if `refreshing` never comes —
+ *  props land a render after `onRefresh` fires. */
+export declare function createPullToRefresh(host: RefreshHost): RefreshController;

package/types/generated/refresh.web.d.ts

@@ -0,0 +1,23 @@
+export interface RefreshConfig {
+    onRefresh?: () => void;
+    refreshing?: boolean;
+    threshold?: number;
+}
+export interface RefreshController {
+    /** Call when `refreshing` changes — docks/undocks the indicator. */
+    sync: () => void;
+    detach: () => void;
+}
+/** Pointer/touch-driven pull-to-refresh for the DOM leaf — the web has no
+ *  native overscroll, so drag distance translates the scroller inside the
+ *  clipped wrapper while the self-drawn indicator slides into the gap.
+ *  `touchmove` must be non-passive: `preventDefault` is what keeps the
+ *  browser from taking the gesture as a scroll (or Chrome's own
+ *  pull-to-refresh on Android). Mouse drags ride the pointer events. */
+export declare function createPullToRefresh(host: {
+    scroller: HTMLElement | null;
+    indicator: HTMLElement | null;
+    cfg: {
+        current: RefreshConfig;
+    };
+}): RefreshController;

package/types/generated/root-layout.mobile.d.ts

@@ -0,0 +1,22 @@
+import { RootLayout } from '@nativescript/core';
+/** Called by the Screen leaf's <rootlayout> onLoaded/onUnloaded. */
+export declare function registerRootLayout(rl: RootLayout | undefined | null): void;
+export declare function unregisterRootLayout(rl: RootLayout | undefined | null): void;
+/** The most recently mounted rootlayout — the top of the push stack. For
+ *  imperative services (toast, sheet) there is no invoking component to
+ *  walk from; last-mounted is the pushed page when one exists. Caveat: tabs
+ *  keep visited panes mounted — last is the newest, not the visible tab. */
+export declare function topRootLayout(): RootLayout | undefined;
+/** Resolve the RootLayout enclosing `view` by walking the native parent
+ *  chain — the screen shell is a RootLayout (Screen), so the first
+ *  RootLayout ancestor IS the current page's overlay host. Falls back to
+ *  the top registry entry when the component renders outside any Screen. */
+export declare function rootLayoutFor(view: any): RootLayout | undefined;
+/** Search every registered rootlayout for a view by id — overlays/sheets/
+ *  toasts land on different rootlayouts depending on which screen's shell
+ *  mounted last. Unloaded subtrees are skipped: a covered page unloads its
+ *  views (NativeScript detaches their native recognizers while the JS views
+ *  stay parented), so an unloaded match is a dead twin that can swallow
+ *  interaction probes — the live view either doesn't exist here yet or sits
+ *  under a loaded branch. */
+export declare function findInRootLayouts(id: string): any;

package/types/generated/route-host.mobile.d.ts

@@ -0,0 +1 @@
+export { RouteHost, screenParamsFor } from './RouteHost.mobile.js';

package/types/generated/route-table.d.ts

@@ -0,0 +1,90 @@
+/** Shared route-dir manifest — the file-router half of the nav contract
+ *  (docs/navigation-notes.md). Apps glob their route dir per platform and
+ *  pass the module map here; the suffix seam applies to directories the
+ *  same way it does to imports:
+ *
+ *    // route-manifest.web.ts — generated globs also omit a plain route when
+ *    // a `.web` twin exists, so native-default modules are never evaluated.
+ *    const files = import.meta.glob(
+ *      ['./app/**\/*.{tsrx,tsx}', '!./app/**\/*.mobile.{tsrx,tsx}',
+ *       '!./app/**\/*.ios.{tsrx,tsx}', '!./app/**\/*.android.{tsrx,tsx}',
+ *       '!./app/**\/*.macos.{tsrx,tsx}', '!./app/**\/*.windows.{tsrx,tsx}',
+ *       '!./app/**\/*.linux.{tsrx,tsx}'],
+ *      { eager: true });
+ *    export const routes = deriveRouteManifest(files, ['web']);
+ *
+ *    // route-manifest.mobile.ts — excludes *.web.tsrx; prefer by running OS
+ *    export const routes = deriveRouteManifest(files,
+ *      Device.os === 'Android' ? ['android', 'mobile'] : ['ios', 'mobile']);
+ *
+ *  Conventions (route dir = `dir`, default 'app'):
+ *    app/detail.tsrx        → route 'detail'
+ *    app/demo/[id].tsrx     → route 'demo/:id'  ([param] → :param)
+ *    app/foo/index.tsrx     → 'foo'           (index = the dir's own route)
+ *    app/settings.web.tsrx  → 'settings' on web only — `prefer` decides
+ *    app/_layout.tsrx       → layouts['']     — a shell, not a route
+ *    app/chat/_layout.tsrx  → layouts['chat'] — nested shells cataloged
+ *
+ *  `prefer` ranks platform suffixes — a suffix absent from it is another
+ *  platform's file and is skipped entirely; unsuffixed files are the
+ *  fallback (rank = prefer.length). Web callers pass ['web']; mobile
+ *  callers pass the running OS first. */
+import type { Route, RouteManifest, RouteMeta, RouteSpec, RouteSpecSet } from './props.js';
+/** Internal error carrier used by the public `redirect()` helper. Keeping
+ * this in the shared route table gives both platform leaves the same guard
+ * behavior without importing a platform runtime. */
+export declare class RouteRedirect extends Error {
+    readonly route: Route;
+    constructor(route: Route);
+}
+export declare function deriveRouteManifest(files: Record<string, any>, prefer: readonly string[], dir?: string): RouteManifest;
+/** Build a manifest from app data rather than the route dir — the
+ *  programmatic half of the route contract (host frameworks derive specs
+ *  from their own sources, e.g. `readdirSync` over a content dir). Each
+ *  spec's `path` uses the route-dir vocabulary; `layouts` keys are path
+ *  prefixes playing the `_layout` role. Same-name duplicates inside the
+ *  set keep the later entry with a warn, matching merge precedence. */
+export declare function defineRoutes(input: readonly RouteSpec[] | RouteSpecSet): RouteManifest;
+/** Compose manifests into one — file-derived base plus any number of
+ *  programmatic sets (`registerRoutes(mergeRouteManifests(fromDir, dynamic))`).
+ *  Registration order is precedence: on a same-name collision the later
+ *  manifest's route wins and the loser's loader/beforeLoad/head go with it —
+ *  a warn fires once per colliding name. `layouts` merge key-wise the same
+ *  way. `matchRoute` order is rebuilt by specificity after the merge. */
+export declare function mergeRouteManifests(...manifests: RouteManifest[]): RouteManifest;
+/** Match URL path segments against a manifest — returns the winning meta
+ *  plus extracted params, or null. First hit wins (routes are pre-sorted
+ *  by specificity). */
+export declare function matchRoute(routes: readonly RouteMeta[], segs: string[]): {
+    meta: RouteMeta;
+    params: Record<string, unknown>;
+} | null;
+/** Serialize a Route to a URL path (no origin): manifest routes substitute
+ *  `:param` segments from params (leftover params → query string);
+ *  non-manifest names keep the legacy `/<stack>/<name>?params` shape. */
+export declare function buildRoutePath(routes: readonly RouteMeta[], r: Route): string;
+/** `?a=1&b=2` → params — shared code carries no URLSearchParams
+ *  (invariant 4: no DOM globals on the native path). */
+export declare function parseQueryString(qs: string | undefined): Record<string, unknown>;
+/** Full URL or path → canonical path for matching. `https://x/a/b?y` →
+ *  `/a/b?y`; custom-scheme links keep their host as the first segment —
+ *  `textcoral://post/5` → `/post/5` (the common app-scheme convention). */
+export declare function linkPath(url: string): string;
+/** Match a URL path+query against the manifest into a Route — the shared
+ *  half of web's URL parse and native's deep-link handling. Whole-path
+ *  match wins ('/demo/x' → root 'demo/:id'); a non-matching first segment
+ *  is the stack prefix ('/demos/demo/x' → stack 'demos'). Unmatched names
+ *  fall through as literal routes for pre-manifest callers. */
+export declare function matchUrl(routes: readonly RouteMeta[], url: string): Route | null;
+/** Fire a route's `loader` export — prefetch, not a data layer: the
+ *  screen's own `query$` reads still own the data, this just warms the
+ *  cache before mount. Sync throws and async rejections warn rather
+ *  than break navigation. */
+export declare function runLoader(routes: readonly RouteMeta[], r: Route): void;
+/** Layout components wrapping a route name, outermost → innermost —
+ *  'chat/room' picks up `app/chat/_layout.tsrx`, 'a/b/c' chains 'a' then
+ *  'a/b'. The '' root layout is the app's own shell (entry renders it)
+ *  and never joins a chain. Leaves apply the chain at render: native
+ *  wraps each pushed Page's component, web wraps the outlet's resolved
+ *  element. */
+export declare function layoutChain(layouts: Record<string, any>, name: string): any[];

package/types/generated/route.d.ts

@@ -0,0 +1,74 @@
+/** Native twin of route.web — same Route contract over Frame/Page stacks.
+ *  `pushRoute` resolves a stack ('root' = the app's root Frame — an
+ *  explicit registerStack('root') or, by default, the Frame returned by
+ *  Application.getRootView(); named stacks come from TabSpec.stack panes
+ *  or registerStack) and pushes a Page hosting the registered screen —
+ *  each pushed Page is its own Octane root (decision #9: pages never
+ *  share context with their presenter). Params land as props; named-stack
+ *  pushes get `_stack` injected so the screen can popRoute its own stack.
+ *
+ *  Registration contract (the footgun this module exists to defuse):
+ *  - `registerScreens(table)` once — pushRoute resolves `name` through it.
+ *  - 'root' needs nothing when the app boots a Frame as its root view
+ *    (the standard shape); non-Frame roots can't host pushes at all.
+ *  - named stacks register via `TabSpec.stack` or `registerStack`.
+ *  Every drop path warns loudly — silent no-ops are how apps ship a
+ *  default route on native while working fine on web. */
+import type { Route, RouteManifest, RouteMeta, ScreenTable } from './props.js';
+export type { Route } from './props.js';
+/** Register the app's name → screen table (call once, from the shared
+ *  routes module). Native `pushRoute` resolves `route.name` through it;
+ *  on web the table feeds `screenFor` for outlets without a
+ *  `resolveScreen` prop. `manifest` (from deriveRouteManifest) is stored
+ *  for parity — the web leaf matches URLs through it; native navigation
+ *  is name+params and only needs the table. */
+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;
+/** Layer a programmatic manifest (from `defineRoutes`) over the registered
+ *  routes — same-name entries win over the base with a warn, so a host
+ *  framework can override a file route deliberately. Registered layers
+ *  survive later registerRoutes re-registration (e.g. routes.gen HMR). */
+export declare function addRoutes(manifest: RouteManifest): void;
+export declare function layoutsForRoute(name: string): any[];
+export declare function screenFor(name: string): ScreenTable[string] | undefined;
+/** Register an Android hardware-back interceptor. Interceptors run
+ *  most-recent-first (so the topmost mounted screen wins) before the
+ *  framework's default pop; returning true consumes the press. Returns
+ *  an unsubscribe. iOS has no hardware back — interceptors simply never
+ *  fire there. */
+export declare function addBackInterceptor(fn: () => boolean): () => void;
+export declare function redirect(r: Route): never;
+export declare function pushRoute(r: Route): void;
+/** Pop the top page of a stack ('root' default) — or dismiss the top
+ *  modal if one is open. Quiet no-op at the base page — matching web,
+ *  where back at the app root is a no-op; loud only when the stack
+ *  itself doesn't exist. */
+export declare function popRoute(stack?: string): void;
+/** Route stamped on a stack's current page, or null at its base page. */
+export declare function routeFor(stack: string): Route | null;
+/** The top route across stacks — root's current route wins (a root push
+ *  covers the shell); otherwise the most recently registered named stack
+ *  showing a pushed page. Native has no boot URL, so this is an
+ *  approximation of web's "current URL route", not a deep link. */
+export declare function currentRoute(): Route | null;
+/** Named stacks containing routes, including Android's swap-pane stacks. */
+export declare function routeStacks(): string[];
+/** The modal route currently open, if any — parity with the web leaf. */
+export declare function currentModalRoute(): Route | null;
+/** Deep-link entry: normalize a URL (http(s) or app-scheme) to a path,
+ *  match it against the manifest, push the route. Wire it at boot:
+ *  `onDeepLink(pushDeepLink)` plus one `consumeInitialUrl()` call. */
+export declare function pushDeepLink(url: string): boolean;
+/** Path-string parity for the web leaf's hrefFor — a canonical
+ *  /<stack>/<path> rendering of the route (deep-linking consumes it
+ *  there). Native navigation itself is name+params, not URLs. */
+export declare function hrefFor(r: Route): string;
+export declare function useRoute(stack: string): Route | null;
+/** Whether the selected native stack has a page (or route-owned Android swap
+ * entry) that can be popped. The modal root is also a back affordance. */
+export declare function canGoBack(stack?: string): boolean;
+export declare function useCanGoBack(stack?: string): boolean;
+/** The modal route overlaying the shell — parity with the web leaf. */
+export declare function useModalRoute(): Route | null;