@octane-xplat/ui 0.5.0 → 0.7.0

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;

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

@@ -0,0 +1,67 @@
+/** Web route store — the browser half of the nav contract. One linear URL
+ *  stack; `stack` names the conceptual outlet ('root' covers the app, a
+ *  named stack is the pane that owns it — parallel stacks map to nested
+ *  routes). URL shape: /<stack>/<path>?query or /<path>?query for root,
+ *  where <path> comes from the route-dir manifest — `app/demo/[id].tsrx`
+ *  pushes as /demo/<id-value>. Names not in the manifest keep the legacy
+ *  /<name>?params shape. Module-scope like every other store — the pane
+ *  that owns `stack` subscribes with useRoute(stack) and swaps content.
+ *
+ *  Modal routes (presentation 'modal' — `+modal` route files or a
+ *  pushRoute override) push a real URL but overlay instead of replacing:
+ *  `current` keeps the underlying route, `modalRoute` carries the modal.
+ *  Back (popstate or popRoute) dismisses it. */
+export type { Route } from './props.js';
+import type { Route, RouteManifest, RouteMeta, ScreenTable } from './props.js';
+/** Register the app's name → screen table. On web the table feeds
+ *  `screenFor` — the fallback outlet resolution in Tabs when no
+ *  `resolveScreen` prop is given; on native `pushRoute` resolves
+ *  `route.name` through it. `manifest` (from deriveRouteManifest) enables
+ *  path-param matching — call once from the shared routes module. */
+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 screenFor(name: string): ScreenTable[string] | undefined;
+/** Directory layouts wrapping a route, outermost → innermost — outlets
+ *  wrap their resolved element with these (`_layout.tsrx` files). */
+export declare function layoutsFor(name: string): any[];
+export { layoutsFor as layoutsForRoute };
+export declare function redirect(r: Route): never;
+export declare function pushRoute(r: Route): void;
+/** Web history is one linear stack — back pops whatever route is current;
+ *  per-stack pops aren't expressible, so `stack` is accepted for parity
+ *  and ignored. A pushed modal is the top entry, so back dismisses it. */
+export declare function popRoute(_stack?: string): void;
+/** No-op twin of the native leaf. Browser back is already real history —
+ *  there is no hardware-back event to intercept on web, so registered
+ *  interceptors never fire. Warns once so a mistaken call site isn't
+ *  silently absent. */
+export declare function addBackInterceptor(_fn: () => boolean): () => void;
+/** Current route if it targets `stack`, else null. */
+export declare function routeFor(stack: string): Route | null;
+/** Web has one linear browser history; expose its active route stack for parity. */
+export declare function routeStacks(): string[];
+/** The route active at boot — for deep-link tab selection. */
+export declare function currentRoute(): Route | null;
+/** The modal route overlaying the current one, if any. */
+export declare function currentModalRoute(): Route | null;
+/** Deep-link entry, web half — the URL *is* the route state, so this is a
+ *  plain pushRoute of the matched path (parity with the native leaf, where
+ *  apps wire `onDeepLink(pushDeepLink)`). */
+export declare function pushDeepLink(url: string): boolean;
+/** URL for a Route — Link's href and shareable-path helper. */
+export declare function hrefFor(r: Route): string;
+export declare function useRoute(stack: string): Route | null;
+/** Whether the selected conceptual stack has an in-app route to pop. A
+ * browser's pre-app history is intentionally not counted. */
+export declare function canGoBack(stack?: string): boolean;
+export declare function useCanGoBack(stack?: string): boolean;
+/** The modal route overlaying the shell — outlets render it above their
+ *  normal content (URL preserved underneath). */
+export declare function useModalRoute(): Route | null;

package/types/generated/safeAreaInsets.d.ts

@@ -0,0 +1,8 @@
+export interface SafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**  Reads the root view's insets; Android and pre-attachment reads may be zero. */
+export declare function useSafeAreaInsets(): SafeAreaInsets;

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

@@ -0,0 +1,8 @@
+export interface SafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**  Approximate CSS safe-area values, measured on mount and viewport resize. */
+export declare function useSafeAreaInsets(): SafeAreaInsets;

package/types/generated/sheet-detents.d.ts

@@ -0,0 +1,23 @@
+export interface SheetDetentsController {
+    /** Slide the panel in from below the screen edge — call once the host
+     *  is inside the RootLayout (the RootLayout open call replaces the
+     *  built-in enter/exit animation, which would fight detent offsets:
+     *  it always animates translateY to 0). */
+    enter: () => void;
+    detach: () => void;
+}
+/** Drag-to-snap detents on a RootLayout sheet host: a self-drawn grabber
+ *  strip (top-aligned grid child — the only drag target, so it never
+ *  fights inner scrolling) drives the host's translateY; the host is
+ *  sized to the largest detent and parked at the offset for the current
+ *  one. `closeNow` fires after the dismiss slide-out — the caller decides
+ *  what closing means (declarative `onDismiss` via RootLayout 'closed',
+ *  or the `openSheet` resolution).
+ *
+ *  In-window on native: the OS detent presentations
+ *  (UISheetPresentationController / BottomSheetBehavior via
+ *  BottomSheetDialogFragment) host a modal VC or a separate dialog
+ *  window — a different surface contract than the RootLayout child this
+ *  sheet is (UIModal/MaterialDialog own the modal path), so the snap
+ *  mechanics are self-drawn and identical to the web leaf. */
+export declare function attachSheetDetents(host: any, detents: readonly number[], closeNow: () => void): SheetDetentsController;

package/types/generated/sheet-detents.web.d.ts

@@ -0,0 +1,13 @@
+export interface SheetDetentsController {
+    detach: () => void;
+}
+/** Drag-to-snap detents on a `.vx-sheet` panel: a self-drawn grabber strip
+ *  (the only drag target — it never fights inner scrolling) drives the
+ *  panel's translateY; the panel is sized to the largest detent and parked
+ *  at the offset for the current one. `closeNow` fires after the dismiss
+ *  slide-out — the caller decides what closing means (declarative
+ *  `onDismiss` or the `openSheet` resolution). In-window on every target —
+ *  the OS detent presentations (UISheetPresentationController /
+ *  BottomSheetDialog) host a modal VC/dialog window, not a RootLayout
+ *  child, so the snap mechanics stay self-drawn for pixel parity. */
+export declare function attachSheetDetents(panel: HTMLElement, detents: readonly number[], closeNow: () => void): SheetDetentsController;

package/types/generated/sheet-service.d.ts

@@ -0,0 +1,11 @@
+import { GridLayout } from '@nativescript/core';
+import type { ModalOpenResult, OpenSheet } from './props.js';
+/** The most recently opened sheet's host view — for harness asserts (view
+ *  identity beats tree search; the owning rootlayout may unload/reload). */
+export declare function sheetHost(): GridLayout | null;
+/** Close the most recently opened sheet (resolve with `result`). */
+export declare function closeSheet(result?: ModalOpenResult): void;
+/** Imperative in-window sheet: a dedicated Octane root on a bottom-docked
+ *  GridLayout host opened on the CURRENT rootlayout (topRootLayout — the
+ *  service has no declaring view). Resolves when the sheet closes. */
+export declare const openSheet: OpenSheet;

package/types/generated/sheet-service.web.d.ts

@@ -0,0 +1,6 @@
+import type { ModalOpenResult, OpenSheet } from './props.js';
+/** Close the most recently opened sheet (resolve with `result`). */
+export declare function closeSheet(result?: ModalOpenResult): void;
+/** Imperative in-window sheet: portal layer at document root, bottom-
+ *  anchored panel, dedicated Octane root. Resolves when the sheet closes. */
+export declare const openSheet: OpenSheet;

package/types/generated/sheet-snap.d.ts

@@ -0,0 +1,18 @@
+/** Detent math shared by the web/native sheet-detents attachments.
+ *  Detents are viewport-height fractions; the panel is sized to the
+ *  largest detent and parked at the translateY offset for the current
+ *  one, so a snap is just a transform write — no layout thrash. */
+/** Downward/upward finger speed (px/s web, dip/s native) that overrides
+ *  nearest-detent snapping — a fling snaps one detent in its direction. */
+export declare const DETENT_FLICK_VELOCITY = 500;
+/** Sorted, filtered, deduped detent fractions. Empty → the caller keeps
+ *  the content-sized sheet behavior (detents off). */
+export declare function normalizeDetents(input?: readonly number[]): number[];
+/** Resting translateY for a detent: the panel is `max * vh` tall, so the
+ *  portion below the screen edge is `(max - detent) * vh`. */
+export declare function detentOffset(detents: readonly number[], index: number, vh: number): number;
+/** Snap target for a release at translateY `ty` with vertical velocity
+ *  `vy` (positive = dragging down). Returns the detent index, or -1 to
+ *  dismiss: released below half of the smallest detent, or a downward
+ *  fling while at/below it. */
+export declare function snapDetentIndex(ty: number, vy: number, detents: readonly number[], vh: number): number;

package/types/generated/stacks.d.ts

@@ -0,0 +1,9 @@
+import { Frame } from '@nativescript/core';
+export declare function registerStack(name: string, frame: Frame): void;
+export declare function getStack(name: string): Frame | undefined;
+/** All registered stacks in registration order — for hardware-back
+ *  resolution (pop whichever stack is visibly on top). */
+export declare function stackEntries(): IterableIterator<[string, Frame]>;
+/** Internal: route.native attaches frame listeners as stacks appear —
+ *  named frames can register after a useRoute subscription ran. */
+export declare function onStackRegistered(cb: (name: string, frame: Frame) => void): void;

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

@@ -0,0 +1,4 @@
+/** Web twin — one linear URL stack; named stacks don't apply. */
+export declare function registerStack(_name: string, _frame: unknown): void;
+export declare function getStack(_name: string): undefined;
+export declare function stackEntries(): IterableIterator<[string, never]>;

package/types/generated/store.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Module-scope store — the shared-state primitive for this stack.
+ *
+ * Why it exists: the universal (native) renderer RETAINS child components
+ * whose props are shallow-unchanged when a parent re-renders — their render
+ * functions do not re-run, so a bare `store.get()` in a child stays stale
+ * (the DOM renderer re-invokes them, React-style). The portable rule is:
+ * every component that reads shared state subscribes to it. The renderer-owned
+ * `use-store` leaves implement that subscription; this file is the hook-free
+ * half, so plain `.ts` is correct.
+ */
+import type { Store } from './props.js';
+export type { ReadableStore, Store } from './props.js';
+export declare function createStore<T>(initial: T): Store<T>;

package/types/generated/styled.d.ts

@@ -0,0 +1,20 @@
+/**
+ * styled() — decision #7, Tamagui-shaped but CSS-backed. base/variants are
+ * class strings composed into className; the leaf decides what those classes
+ * mean per platform.
+ *
+ *   const DangerBtn = styled(Pressable, { base: 'btn', variants: { danger: 'bg-danger' } });
+ *   <DangerBtn danger />  →  className=['btn','bg-danger']
+ *
+ * Universal constraint (Exp 16): component elements require the
+ * compiler-stamped UNIVERSAL_COMPONENT mark and JSX/`@{ }` only lowers at
+ * module level — so a component factory can't be authored with JSX. This
+ * leaf stamps the mark itself via defineUniversalComponent and returns
+ * universalComponent(...) elements directly. If upstream exposes a blessed
+ * factory path, switch to it (driver-level fix candidate). */
+export declare function styled<P extends {
+    className?: any;
+}, V extends Record<string, any>>(Base: (props: P) => any, def: {
+    base?: any;
+    variants?: V;
+}): import("@nativescript-community/octane").UniversalComponent<P & { [K in keyof V]?: boolean | undefined; }>;

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

@@ -0,0 +1,10 @@
+/** @jsxImportSource octane */
+/**
+ * styled() — decision #7. Web side: DOM codegen lowers JSX in nested
+ * functions fine, so the factory is a plain component. */
+export declare function styled<P extends {
+    className?: any;
+}, V extends Record<string, any>>(Base: (props: P) => any, def: {
+    base?: any;
+    variants?: V;
+}): (props: P & { [K in keyof V]?: boolean; }) => import("octane/jsx-runtime").JSX.Element;

package/types/generated/svg.mobile.d.ts

@@ -0,0 +1,23 @@
+import { SVGView } from './vendor/ui-svg/index.js';
+import type { IconGlyph } from './props.js';
+declare module '@nativescript-community/octane/intrinsics' {
+    interface NativeScriptElements {
+        svgview: Omit<Attributes<typeof SVGView>, 'src'> & {
+            /** SVGView awaits promise srcs — remote .svg URLs arrive as fetched markup. */
+            src?: string | Promise<string>;
+            stretch?: 'none' | 'fill' | 'aspectFit' | 'aspectFill';
+        };
+    }
+}
+/** True when an `src` carries SVG: inline markup, an svg data URI, or an
+ *  .svg path/URL. Anything else stays on the raster <image> path. */
+export declare function isSvgSrc(src: string): boolean;
+/** Normalize an svg-shaped src into SVGView's grammar: file/resource paths and
+ *  markup pass through, data URIs decode to markup, remote URLs fetch to
+ *  markup (SVGView has no fetch of its own — it awaits promise srcs). */
+export declare function svgSource(src: string): string | Promise<string>;
+/** IconGlyph → a full `<svg>` string for SVGView. `svg` path data gets a
+ *  `<path>` with the requested fill; `markup` wraps inside a viewBox shell
+ *  with `color`/`fill` set on the root so `currentColor` and default-fill
+ *  children pick up the tint. */
+export declare function glyphSvgMarkup(glyph: IconGlyph, color?: string): string | undefined;

package/types/generated/tap-to-blur.mobile.d.ts

@@ -0,0 +1,16 @@
+/** Tap-outside-to-blur: iOS keeps a focused UITextField/UITextView as first
+ *  responder until something else takes it, so a tap on blank chrome never
+ *  dismisses the keyboard on its own.
+ *
+ *  iOS: a single window-level UITapGestureRecognizer (ref-counted across
+ *  attach calls) sees every touch in the app window — popups/sheets included —
+ *  where a recognizer on an intermediate container proved unreliable. On each
+ *  tap we hit-test and resign first responder unless the hit view is an
+ *  editable text view (otherwise the field would focus-then-blur in the same
+ *  tap — recognizers fire on touch-up, after the field's touch-down focus).
+ *  Keyboard taps live in a separate UIWindow, so they never reach it.
+ *  `cancelsTouchesInView` stays false so taps still reach buttons.
+ *
+ *  Android: hides the soft keyboard from the currently focused view when a
+ *  tap lands on the attached container. */
+export declare function attachTapToBlur(view: any): () => void;

package/types/generated/text-write.d.ts

@@ -0,0 +1,9 @@
+/** Controlled `text` write for TextInput/TextArea leaves. The driver's
+ *  generic prop path writes view.text verbatim; on Android the EditText
+ *  setText resets the cursor to 0 on every controlled write. Park and
+ *  restore the selection around the write (clamped to the new length so an
+ *  append-shrink can't throw). iOS keeps the plain write — UITextField's
+ *  text setter preserves the selected text range already.
+ *  Returns without writing when the value already matches — the textChange
+ *  echo of the user's own typing must not bounce back through setText. */
+export declare function writeText(view: any, value: string | undefined | null): void;

package/types/generated/theme/colorScheme.d.ts

@@ -0,0 +1,6 @@
+export type { ColorScheme } from '../props.js';
+import type { ColorScheme } from '../props.js';
+export declare function getColorScheme(): ColorScheme;
+export declare function subscribeSystemScheme(cb: () => void): () => void;
+/** Reactive system appearance — 'light' | 'dark', re-renders on OS change. */
+export declare function useColorScheme(): ColorScheme;

package/types/generated/theme/colorScheme.linux.d.ts

@@ -0,0 +1,5 @@
+export type { ColorScheme } from '../props.js';
+import type { ColorScheme } from '../props.js';
+export declare function getColorScheme(): ColorScheme;
+export declare function subscribeSystemScheme(cb: () => void): () => void;
+export declare function useColorScheme(): ColorScheme;

package/types/generated/theme/colorScheme.web.d.ts

@@ -0,0 +1,5 @@
+export type { ColorScheme } from '../props.js';
+import type { ColorScheme } from '../props.js';
+export declare function getColorScheme(): ColorScheme;
+export declare function subscribeSystemScheme(cb: () => void): () => void;
+export declare function useColorScheme(): ColorScheme;

package/types/generated/theme/status-bar-scheme.mobile.d.ts

@@ -0,0 +1 @@
+export {};

package/types/generated/theme/theme-scheme.d.ts

@@ -0,0 +1,20 @@
+export type ThemePreference = 'light' | 'dark' | 'system';
+/** App-level theme override. 'system' clears the override and follows the OS. */
+export declare function setThemePreference(p: ThemePreference): void;
+export declare function getThemePreference(): ThemePreference;
+/** The effective scheme: explicit override if set, else system appearance. */
+export declare function getThemeScheme(): 'light' | 'dark';
+/** Reactive effective scheme — re-renders on override or OS change. */
+export declare function useThemeScheme(): 'light' | 'dark';
+/** Class string to stamp on independently-mounted roots (portal hosts,
+ *  overlay/sheet/modal/toast containers): 'ns-dark dark' when effective
+ *  dark, '' otherwise. Both names because tokens.css publishes both
+ *  selectors and hosts may render either vocabulary. */
+export declare function themeSchemeClasses(): string;
+/** Subscribe imperative hosts to effective-scheme changes; returns an
+ *  unsubscribe. Use for hosts that live outside any render cycle. */
+export declare function onThemeSchemeChange(cb: () => void): () => void;
+/** Stamp `base + themeSchemeClasses()` onto an imperative host (NS view or
+ *  DOM element) and keep it live — returns an unsubscribe to call when the
+ *  host closes. Works on both leaves since both honor `.className`. */
+export declare function applyThemeClasses(view: any, base: string): () => void;

package/types/generated/toast-anchor.d.ts

@@ -0,0 +1,4 @@
+import type { ToastContent, ToastOptions } from './props.js';
+/**  FIFO queue. Anchored options use Popover; unanchored options use the
+ * RootLayout with top/bottom start/end alignment. */
+export declare function showToast(content: ToastContent, options?: ToastOptions): void;

package/types/generated/toast-anchor.web.d.ts

@@ -0,0 +1,4 @@
+import type { ToastContent, ToastOptions } from './props.js';
+/**  FIFO queue. `anchor` uses the same portal positioning as Popover; without
+ * one, top/bottom and their start/end alignment variants use the viewport. */
+export declare function showToast(content: ToastContent, options?: ToastOptions): void;

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

@@ -0,0 +1,8 @@
+/** Per-element transform composition for imperative writes. The DOM has a
+ *  single `transform` string where native has discrete view props, so web
+ *  keeps the last-written value per transform prop and re-joins them —
+ *  an AnimatedValue on `rotate` and a setTranslate drag on the same
+ *  element don't clobber each other. */
+/** Write one transform prop without disturbing the element's other
+ *  transform components (or its stylesheet/base transform). */
+export declare function writeTransformProp(el: HTMLElement, prop: string, value: number): void;