@octane-xplat/ui 0.9.0 → 0.11.0

package/types/generated/query-cache.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Shared keyed cache over `octane/signals` `query$`.
+ *
+ * `query$` scopes a request to its declaring owner: a module-level query is
+ * one root cell, a component-level query is one instance cell. There is
+ * no cross-owner dedupe, no cross-screen invalidation, and no persistence.
+ * This module adds the app-facing cache contract on top, without changing the
+ * primitive:
+ *
+ * - `cachedQuery$(key, select, load, options)` declares a query whose results
+ *   live in a module-level cache keyed by `[...key, selection]`. Two screens
+ *   (or two query declarations) that resolve the same cache key share the
+ *   cached value and dedupe an in-flight request.
+ * - `invalidateQueries(key)` marks matching entries stale and refetches the
+ *   owning queries in every live scope — same-identity retries, so each
+ *   screen keeps its previous data while it refreshes.
+ * - `clearQueryCache(key?)` evicts entries (and persisted records) without
+ *   refetching — for sign-out and schema bumps.
+ * - `persist` opts a query into durable snapshots through a pluggable
+ *   `QueryStorageAdapter` (`platformQueryStorage`, or an app adapter such as
+ *   idb-keyval on web). The envelope carries a compatibility `version`, the
+ *   save time for `maxAge`/`staleTime` policies, and an app-resolved `scope`
+ *   (e.g. the auth boundary) — the app owns the policy, the cache owns the
+ *   mechanics.
+ *
+ * Mutations stay app-owned async functions: await the write, then call
+ * `invalidateQueries`. There is deliberately no `mutation$` here.
+ *
+ * Identity model: the octane request identity stays `[query, selection]`, so
+ * invalidation refetches keep `previous` and stay stale-while-revalidate.
+ * The cache key adds the family `key` prefix so prefix invalidation and
+ * persistence namespacing are expressible. Canonicalization sorts object
+ * fields — `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` are one cache entry even
+ * though octane request identity is positional.
+ *
+ * Requires the patched `octane` used by xplat apps: instance-scoped
+ * descriptors bind their declaring owner at construction, which is what lets
+ * `invalidateQueries` reach a screen-owned query from module code.
+ */
+import { skip, type QueryContext, type QuerySignal } from 'octane/signals';
+/** One JSON-canonical element of a `QueryKey`. */
+export type QueryKeyPart = string | number | boolean | null | readonly QueryKeyPart[] | {
+    readonly [field: string]: QueryKeyPart | undefined;
+};
+/**
+ * A query-family key. Family keys prefix the cache key; the selector's
+ * selection is appended, so `['user']` covers `['user', '42']` and
+ * `invalidateQueries(['user'])` reaches every selection of that family.
+ */
+export type QueryKey = readonly QueryKeyPart[];
+export interface QueryStorageAdapter {
+    get(key: string): string | null | undefined | PromiseLike<string | null | undefined>;
+    set(key: string, value: string): void | PromiseLike<void>;
+    remove(key: string): void | PromiseLike<void>;
+}
+/**
+ * Opt-in durable snapshots for one `cachedQuery$` family. The envelope is
+ * `{ v: version, t: savedAt, d: data }` under storage key
+ * `xplat:query:<scope>:<canonical key>`. Apps layer their policy on top:
+ * `version` is the schema/app/API compatibility bump, `maxAge` the TTL, and
+ * `scope` the resolved auth boundary (return `null` to leave the query
+ * memory-only for that boundary).
+ */
+export interface QueryPersistence {
+    readonly storage: QueryStorageAdapter;
+    readonly version: string | number;
+    /** Milliseconds a stored snapshot stays restorable. Default: no expiry. */
+    readonly maxAge?: number;
+    /** Resolved at each read/write; `null` skips persistence for this call. */
+    readonly scope?: () => string | null;
+}
+export interface CachedQueryOptions<T = unknown> {
+    /**
+     * Milliseconds a cache entry stays fresh — new readers are served without
+     * a request. Default `0`: mounting or selecting a stale entry serves the
+     * cached value and revalidates in the background.
+     */
+    readonly staleTime?: number;
+    readonly persist?: QueryPersistence;
+    /**
+     * Distinguishes same-family declarations inside one scope. Without it,
+     * every `cachedQuery$` in a scope that shares the family also shares one
+     * query cell (first selector/loader wins). Rarely needed — different
+     * families never collide.
+     */
+    readonly key?: string;
+}
+/**
+ * Declare a `query$` whose results are shared through the module-level query
+ * cache. Same signature shape as `query$`, plus a required family `key` that
+ * gives the query a stable cross-screen identity and an invalidation target.
+ *
+ * The returned handle is a full `QuerySignal`: `.get()` suspends, `.latest()`
+ * and `.snapshot()` read without suspending, and `.refetch()`/`.retry()`/
+ * `.reset()` force a fresh request.
+ *
+ * The inner query uses an explicit, family-derived key so every re-render
+ * declaration resolves to the same cell. Two declarations in the same scope
+ * that share a family therefore also share a cell — the first selector and
+ * loader bound in that scope wins, the same as declaring the same `query$`
+ * twice. To keep same-family declarations distinct inside one scope, pass a
+ * distinguishing `options.key`.
+ */
+export declare function cachedQuery$<A, T>(key: QueryKey, select: () => A | typeof skip, load: (selection: A, context: QueryContext<T>) => T | PromiseLike<T>, options?: CachedQueryOptions<T>): QuerySignal<T>;
+export interface InvalidateQueriesOptions {
+    /** Match only the exact key; default invalidates the key's whole subtree. */
+    readonly exact?: boolean;
+}
+/**
+ * Mark matching cache entries stale and refetch every live query that can own
+ * them. Call with no key to invalidate the whole cache.
+ *
+ * Owners refetch through their own query cell, so screens keep their current
+ * data while the new request runs (`snapshot().refreshing`). Entries whose
+ * owners are unmounted stay stale; their next reader revalidates.
+ */
+export declare function invalidateQueries(key?: QueryKey, options?: InvalidateQueriesOptions): void;
+export interface ClearQueryCacheOptions {
+    readonly exact?: boolean;
+}
+/**
+ * Evict matching cache entries — and their persisted records — without
+ * refetching. Mounted queries keep the data they already show; the next
+ * reader repopulates. Call with no key to clear the whole cache (e.g. on
+ * sign-out, before the auth scope changes).
+ */
+export declare function clearQueryCache(key?: QueryKey, options?: ClearQueryCacheOptions): void;
+/** Map-backed storage adapter — tests, examples, and custom persistence hosts. */
+export declare function createMemoryQueryStorage(): QueryStorageAdapter;

package/types/generated/query-storage.d.ts

@@ -0,0 +1,9 @@
+import type { QueryStorageAdapter } from './query-cache.js';
+/**
+ * Default query persistence adapter on iOS/Android — NativeScript
+ * `ApplicationSettings` (NSUserDefaults/SharedPreferences). Synchronous and
+ * suitable for bounded JSON snapshots; keep persisted query payloads small.
+ * A file-backed adapter remains the upgrade path for larger caches — supply
+ * it via `persist.storage`.
+ */
+export declare const platformQueryStorage: QueryStorageAdapter;

package/types/generated/query-storage.macos.d.ts

@@ -0,0 +1,8 @@
+import { type QueryStorageAdapter } from './query-cache.js';
+/**
+ * Default query persistence adapter on macOS — the AppKit host has no
+ * `__xplatAppKit` defaults bridge yet, so persisted snapshots live for the
+ * process only. Supply a durable adapter via `persist.storage` when an
+ * AppKit bridge lands.
+ */
+export declare const platformQueryStorage: QueryStorageAdapter;

package/types/generated/query-storage.web.d.ts

@@ -0,0 +1,8 @@
+import type { QueryStorageAdapter } from './query-cache.js';
+/**
+ * Default query persistence adapter on web — `window.localStorage`.
+ * Synchronous, shared per origin, and bounded to JSON text payloads; apps
+ * needing larger or structured snapshots can supply an idb-keyval-style
+ * `QueryStorageAdapter` to `persist.storage` instead.
+ */
+export declare const platformQueryStorage: QueryStorageAdapter;

package/types/generated/ref-list.d.ts

@@ -0,0 +1,7 @@
+import type { Octane } from 'octane/jsx-runtime';
+type FlatRef<T> = ((instance: T | null) => void) | {
+    current: T | null;
+};
+export declare function refList<T>(...refs: (Octane.Ref<T> | undefined)[]): FlatRef<T>[];
+export declare function mergedRef<T>(...refs: (Octane.Ref<T> | undefined)[]): FlatRef<T>;
+export {};

package/types/generated/relative-position.d.ts

@@ -0,0 +1,5 @@
+/** View-relative DIP coordinates for native overlay placement. */
+export declare function relativePosition(view: any, relativeTo: any): {
+    x: number;
+    y: number;
+} | undefined;

package/types/generated/resize-basis.d.ts

@@ -0,0 +1,5 @@
+import type { ResizableBasisSource } from './resize-state.js';
+/** Native basis — the `containerRef` view's measured size when supplied,
+ *  else the device screen. `layoutChanged` on the container tracks bounds;
+ *  orientation changes re-measure the screen fallback. */
+export declare const nativeBasisSource: ResizableBasisSource;

package/types/generated/resize-basis.macos.d.ts

@@ -0,0 +1,4 @@
+import type { ResizableBasisSource } from './resize-state.js';
+/** AppKit basis — the `containerRef` view's frame when supplied, else the
+ *  host window's size via the bridge when it reports one. */
+export declare const macosBasisSource: ResizableBasisSource;

package/types/generated/resize-basis.web.d.ts

@@ -0,0 +1,6 @@
+import type { ResizableBasisSource } from './resize-state.js';
+/** Web basis — the `containerRef` element's content box when supplied, else
+ *  the viewport. ResizeObserver tracks the container; window resize tracks
+ *  the viewport fallback. Storage prefix matches upstream so a migrated app
+ *  keeps saved sizes. */
+export declare const webBasisSource: ResizableBasisSource;

package/types/generated/resize-math.d.ts

@@ -0,0 +1,27 @@
+import type { ResizablePercentSize, ResizablePixelSize, ResizableSize } from './props.js';
+/**
+ * Resizable size math — 1:1 port of Astryx's parse/toPixels/clamp helpers.
+ * Pixel and percentage size constructors plus the basis-resolving and
+ * clamping used by the hook.
+ */
+/** An exact pixel/dip size — `pixel(240)`. */
+export declare function pixel(value: number): ResizablePixelSize;
+/** A percentage with exactly one pixel bound — `percent(50, {min: pixel(200)})`
+ *  means 50% of the basis, not below 200px. Throws on out-of-range or
+ *  conflicting inputs like upstream. */
+export declare function percent(value: number, constraint: {
+    min: ResizablePixelSize;
+} | {
+    max: ResizablePixelSize;
+}): ResizablePercentSize;
+export declare function isPixelSize(v: unknown): v is ResizablePixelSize;
+export declare function isPercentSize(v: unknown): v is ResizablePercentSize;
+/**
+ * Resolve a ResizableSize to a pixel value.
+ * @param basis The pixel size of the reference container/viewport, used for
+ *   percentage sizes and bounds. Returns null when the size cannot resolve.
+ */
+export declare function toPixels(size: ResizableSize | undefined, basis: number): number | null;
+/** Clamp a size to [min, max] then snap to the nearest configured snap
+ *  point. Snaps always win — the panel can only rest at snap values. */
+export declare function clampSize(size: number, minPx: number, maxPx: number, snaps: readonly number[]): number;

package/types/generated/resize-persist.d.ts

@@ -0,0 +1,7 @@
+/** Resizable `autoSaveId` persistence — NativeScript ApplicationSettings. */
+export interface PersistedResizableState {
+    size?: number | null;
+    isCollapsed?: boolean;
+}
+export declare function loadResizableState(key: string): PersistedResizableState | null;
+export declare function persistResizableState(key: string, state: PersistedResizableState): void;

package/types/generated/resize-persist.macos.d.ts

@@ -0,0 +1,8 @@
+/** Resizable `autoSaveId` persistence — the AppKit host has no settings
+ *  seam yet, so persistence is in-memory for the session. */
+export interface PersistedResizableState {
+    size?: number | null;
+    isCollapsed?: boolean;
+}
+export declare function loadResizableState(key: string): PersistedResizableState | null;
+export declare function persistResizableState(key: string, state: PersistedResizableState): void;

package/types/generated/resize-persist.web.d.ts

@@ -0,0 +1,9 @@
+/** Resizable `autoSaveId` persistence — localStorage on web. Three legacy
+ *  formats are read like upstream's: a bare number, `{ size }` alone, and
+ *  `{ size, isCollapsed }` where size may be null while collapsed. */
+export interface PersistedResizableState {
+    size?: number | null;
+    isCollapsed?: boolean;
+}
+export declare function loadResizableState(key: string): PersistedResizableState | null;
+export declare function persistResizableState(key: string, state: PersistedResizableState): void;

package/types/generated/resize-state.d.ts

@@ -0,0 +1,39 @@
+import type { ResizableConfig, ResizableDirection, ResizableRegion, UseResizableSingleConfig } from './props.js';
+export declare const DEFAULT_COLLAPSED_SIZE = 40;
+/** Platform seam the machine needs: measure the % basis and observe it for
+ *  changes. Each leaf supplies these so the state machine stays platform-free. */
+export interface ResizableBasisSource {
+    /** Current basis in px/dips for the axis (container size, or the
+     *  viewport/screen when no container is supplied). */
+    measure: (containerRef: {
+        current: any;
+    } | undefined, direction: ResizableDirection) => number | null;
+    /** Subscribe to basis changes; returns an unsubscribe. */
+    observe: (containerRef: {
+        current: any;
+    } | undefined, direction: ResizableDirection, cb: () => void) => () => void;
+    /** Storage key prefix — `astryx-resizable:` upstream. */
+    storagePrefix: string;
+}
+/** One resizable region's machine — plain object so multi-region use and
+ *  per-platform hooks stay thin. Re-entrant gesture handlers mirror the
+ *  upstream hook exactly. */
+export interface ResizableMachine {
+    region: ResizableRegion;
+    /** Recompute bounds when the measured basis changed. */
+    remeasure: () => void;
+    /** Push new config (props changed between renders). */
+    update: (config: UseResizableSingleConfig) => void;
+    subscribe: (cb: () => void) => () => void;
+    /** Snapshot for getSnapshot — a fresh object only when size/collapsed change. */
+    getSnapshot: () => {
+        size: number;
+        isCollapsed: boolean;
+    };
+}
+/** Build a single resizable region. `storageKey` defaults to autoSaveId;
+ *  multi-region callers pass `${autoSaveId}:${key}`. */
+export declare function createResizableRegion(config: UseResizableSingleConfig, basis: ResizableBasisSource, storageKey?: string): ResizableMachine;
+/** Map a component's simplified `resizable` config (e.g. SideNav) to the
+ *  full single-region config. */
+export declare function regionConfigFrom(resizable: true | ResizableConfig | undefined): UseResizableSingleConfig | null;

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

@@ -0,0 +1,6 @@
+/** Native RootLayout instances have no counterpart in the DOM renderer. */
+export declare function registerRootLayout(_layout: unknown): void;
+export declare function unregisterRootLayout(_layout: unknown): void;
+export declare function topRootLayout(): undefined;
+export declare function rootLayoutFor(_view: unknown): undefined;
+export declare function findInRootLayouts(_id: string): null;

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

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

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

@@ -1,5 +1,5 @@
 /** Shared route-dir manifest — the file-router half of the nav contract
- *  (docs/navigation-notes.md). Apps glob their route dir per platform and
+ *  (docs/notes/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:
  *
@@ -20,6 +20,8 @@
  *  Conventions (route dir = `dir`, default 'app'):
  *    app/detail.tsrx        → route 'detail'
  *    app/demo/[id].tsrx     → route 'demo/:id'  ([param] → :param)
+ *    app/demo/[[ref]].tsrx  → 'demo/:ref?'    ([[p]] = optional param)
+ *    app/docs/[...r].tsrx   → 'docs/*r'       ([...p] = terminal catch-all)
  *    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
@@ -65,13 +67,18 @@ export declare function mergeRouteManifests(...manifests: RouteManifest[]): Rout
 export declare function manifestToJson(manifest: RouteManifest): RouteManifestJson;
 /** 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). */
+ *  by specificity). A `:param?` segment matches zero or one segment —
+ *  the matcher consumes greedily and backtracks to the absent case so a
+ *  later static can still align; a terminal `*` captures the remaining
+ *  segments `/`-joined into `params['*']` (a named `*rest` into 'rest'). */
 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);
+ *  `:param` segments from params (leftover params → query string); a
+ *  `:param?` segment with no value drops out of the path entirely, and a
+ *  terminal `*`/`*rest` splices in its `/`-joined param value.
  *  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
@@ -84,13 +91,18 @@ 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. */
+ *  is the stack prefix ('/demos/demo/x' → stack 'demos'). Whole-path
+ *  includes catch-alls: a root `*` claims every URL, including
+ *  stack-prefixed ones — apps needing named-stack links scope their
+ *  splats under a prefix. 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. */
+/** Fire a route's `loader` without committing navigation — the opt-in
+ *  prefetch primitive, for warming a `query$` cache ahead of a push an
+ *  app expects to make. This is NOT the navigation loader path: a push
+ *  awaits the loader itself (`commitRoute`) and hands its result to the
+ *  screen as `data`/`error`; the value fired here is discarded. 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

package/types/generated/route.d.ts

@@ -33,6 +33,9 @@ export declare function registerRoutes(manifest: RouteManifest): void;
 export declare function addRoutes(manifest: RouteManifest): void;
 export declare function layoutsForRoute(name: string): any[];
 export declare function screenFor(name: string): ScreenTable[string] | undefined;
+/** The route's declared `ErrorBoundary` export, if any — outlets wrap the
+ *  resolved screen in `RouteBoundary` with it. */
+export declare function errorBoundaryFor(name: string): any;
 /** 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

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

@@ -0,0 +1,28 @@
+import type { Route, RouteHead, RouteManifest, RouteMeta, ScreenTable } from './props.js';
+export declare function registerScreens(table: ScreenTable, manifest?: RouteMeta[]): void;
+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. Registered
+ *  layers survive later registerRoutes re-registration. */
+export declare function addRoutes(manifest: RouteManifest): void;
+export declare function screenFor(name: string): ScreenTable[string] | undefined;
+export declare function layoutsFor(name: string): any[];
+/** The route's declared `ErrorBoundary` export, if any — outlets wrap the
+ *  resolved screen in `RouteBoundary` with it. */
+export declare function errorBoundaryFor(name: string): any;
+export declare function routeFor(stack: string): Route | null;
+export declare function currentRoute(): Route | null;
+export declare function currentModalRoute(): Route | null;
+export declare function routeStacks(): string[];
+export declare function canGoBack(stack?: string): boolean;
+export declare function useCanGoBack(stack?: string): boolean;
+export declare function useRoute(stack?: string): Route | null;
+export declare function useModalRoute(): Route | null;
+export declare function redirect(route: Route): never;
+export declare function pushRoute(route: Route): void;
+export declare function popRoute(stack?: string): void;
+export declare function pushDeepLink(url: string): void;
+export declare function hrefFor(route: Route): string;
+export declare function addBackInterceptor(_handler: () => boolean): () => void;
+export declare function useRouteHead(_route: Route | null): RouteHead | undefined;
+export { layoutsFor as layoutsForRoute };

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

@@ -28,6 +28,9 @@ export declare function registerRoutes(manifest: RouteManifest): void;
  *  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;
+/** The route's declared `ErrorBoundary` export, if any — outlets wrap the
+ *  resolved screen in `RouteBoundary` with it. */
+export declare function errorBoundaryFor(name: string): any;
 /** Directory layouts wrapping a route, outermost → innermost — outlets
  *  wrap their resolved element with these (`_layout.tsrx` files). */
 export declare function layoutsFor(name: string): any[];

package/types/generated/safe-url.d.ts

@@ -0,0 +1,4 @@
+/** Return the normalized URL, or null for a blocked scheme. */
+export declare function sanitizeUrl(url: string): string | null;
+/** Inspect a navigation string without changing the value used by its sink. */
+export declare function isSafeUrl(url: string): boolean;

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

@@ -0,0 +1,10 @@
+/** @jsxImportSource octane */
+export interface SafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**  The AppKit root view begins below the title bar; there are no additional
+ * safe-area insets in this window-hosted renderer. */
+export declare function useSafeAreaInsets(): SafeAreaInsets;

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

@@ -0,0 +1,11 @@
+export type Scheme = 'light' | 'dark';
+export declare const mutedColor: (scheme: Scheme) => string;
+export declare const textColor: (scheme: Scheme) => string;
+export declare const accentColor: (scheme: Scheme) => string;
+export declare const successColor: () => string;
+export declare const warningColor: () => string;
+export declare const dangerColor: () => string;
+/** StatusDot variant → ink color painted on the dot on native. */
+export declare function statusDotColor(variant: string, scheme: Scheme): string;
+/** ProgressBar variant → fill color on native. */
+export declare function progressFillColor(variant: string, scheme: Scheme): string;

package/types/generated/select-options.d.ts

@@ -0,0 +1,10 @@
+import type { SelectOption } from './props.js';
+export declare function selectValues(value: string | string[] | null | undefined): string[];
+export declare function sameSelection(a: string[], b: string[]): boolean;
+export declare function filterSelectOptions(options: SelectOption[], query: string): SelectOption[];
+export declare function groupSelectOptions(options: SelectOption[]): {
+    heading: string | undefined;
+    options: SelectOption[];
+}[];
+/** Bulk toggles affect only the visible enabled set, retaining hidden/disabled values. */
+export declare function toggleVisibleSelection(selected: string[], options: SelectOption[]): string[];

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

@@ -12,7 +12,7 @@ export interface SheetDetentsController {
  *  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).
+ *  or the `openBottomSheet` resolution).
  *
  *  In-window on native: the OS detent presentations
  *  (UISheetPresentationController / BottomSheetBehavior via
@@ -20,4 +20,15 @@ export interface SheetDetentsController {
  *  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;
+export interface SheetDetentsOptions {
+    /** False blocks the swipe-to-dismiss outcome (Astryx 'required' sheets) —
+     *  a release below the smallest stop snaps back instead of closing. */
+    dismissible?: boolean;
+    /** Live translateY updates for scrim-opacity modulation on web. */
+    onOffset?: (offset: number, vh: number) => void;
+    /** No snap points: the panel keeps its content height and the grabber
+     *  only owns swipe-to-dismiss (release below ~40% of the panel or a
+     *  downward fling). */
+    swipeOnly?: boolean;
+}
+export declare function attachSheetDetents(host: any, detents: readonly number[], closeNow: () => void, options?: SheetDetentsOptions): SheetDetentsController;

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

@@ -1,13 +1,23 @@
 export interface SheetDetentsController {
     detach: () => void;
 }
+export interface SheetDetentsOptions {
+    /** False blocks the swipe-to-dismiss outcome — a release below the
+     *  smallest stop snaps back instead of closing. */
+    dismissible?: boolean;
+    /** Live translateY updates for scrim-opacity modulation. */
+    onOffset?: (offset: number, vh: number) => void;
+    /** No snap points: the panel keeps its content height and the grabber
+     *  only owns swipe-to-dismiss. */
+    swipeOnly?: boolean;
+}
 /** 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 —
+ *  `onOpenChange` or the `openBottomSheet` 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;
+export declare function attachSheetDetents(panel: HTMLElement, detents: readonly number[], closeNow: () => void, options?: SheetDetentsOptions): SheetDetentsController;

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

@@ -8,6 +8,14 @@ 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[];
+/** One snap point → viewport-height fraction. A number ≤ 1 is already a
+ *  fraction; a larger number is px/dips. Strings accept 'NN%' and 'NNpx'
+ *  (bare numeric strings are px). Returns null when unresolvable. */
+export declare function snapPointFraction(point: number | string, vh: number): number | null;
+/** Astryx `snapPoints` → sorted detent fractions (the existing controller
+ *  shape). `vh` is the viewport height in px/dips. Stops larger than the
+ *  window clamp to 1. Empty → detents off. */
+export declare function normalizeSnapPoints(input: readonly (number | string)[] | undefined, vh: 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;

package/types/generated/spacing.d.ts

@@ -0,0 +1,4 @@
+/** Astryx spacing steps are 4px/dip units (`--spacing-N` = N×4). Shared by
+ *  components whose props take a step number (ScrollableArea padding,
+ *  Dialog padding, Carousel gap). */
+export declare function spacingStep(step: number | undefined): number | undefined;

package/types/generated/stack-layout.d.ts

@@ -0,0 +1,40 @@
+import type { StackProps, StackItemProps } from './props.js';
+/** Astryx spacing step → dips (step × 4, matching the upstream
+ *  `--spacing-N` scale: 0.5→2, 1→4, 2→8, 3→12, 4→16, …, 10→40). */
+export declare function spacingPx(step: number | undefined | null): number | undefined;
+export interface ResolvedStackLayout {
+    /** 'row' | 'column' — the flex-direction value both engines share. */
+    flexDirection: 'row' | 'column';
+    justifyContent?: string;
+    alignItems?: string;
+    flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
+    gap?: number;
+    scrollable: boolean;
+    /** Resolved per-edge padding in dips (edge → axis → padding precedence). */
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    /** Logical variants for web's inline/block-aware styles. */
+    paddingInlineStart?: number;
+    paddingInlineEnd?: number;
+    paddingBlockStart?: number;
+    paddingBlockEnd?: number;
+}
+/** Resolve Stack's directional alignment + spacing props into flex values.
+ *  `hAlign`/`vAlign` follow the physical axes; `justify`/`align` alias the
+ *  main/cross axes of the active direction. */
+export declare function resolveStackLayout(props: StackProps): ResolvedStackLayout;
+/** The web `style` fragment for a resolved stack (logical padding +
+ *  px-unit sizing — octane renders numbers as px for length props). */
+export declare function stackWebStyle(layout: ResolvedStackLayout, props: StackSizeLike): Record<string, any>;
+export interface StackSizeLike {
+    width?: number | string;
+    height?: number | string;
+    maxWidth?: number | string;
+    minHeight?: number | string;
+}
+/** The style fragment for StackItem — `fill` grows (and is allowed to
+ *  shrink) into remaining space; the min-size reset lets it become a
+ *  scroll region under a flex parent. */
+export declare function stackItemStyle(props: StackItemProps): Record<string, any>;

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

@@ -0,0 +1,3 @@
+export declare function registerStack(name: string, stack: unknown): void;
+export declare function getStack(name: string): unknown;
+export declare function stackEntries(): IterableIterator<[string, unknown]>;

package/types/generated/styled.d.ts

@@ -17,4 +17,6 @@ export declare function styled<P extends {
 }, 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; }>;
+}): (props: P & {
+    [K in keyof V]?: boolean;
+}, context: any) => any;

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

@@ -0,0 +1,9 @@
+/**  Compose CSS-backed class names onto an AppKit component factory. */
+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;
+}, context: any) => any;

package/types/generated/surfaces.macos.d.ts

@@ -0,0 +1,4 @@
+/**  @jsxImportSource @octane-xplat/macos-renderer */
+import type { OverlayProps, PopoverProps } from './props.js';
+export declare function Overlay(props: OverlayProps): unknown;
+export declare function Popover(props: PopoverProps): unknown;

package/types/generated/svg-glyph.d.ts

@@ -0,0 +1,6 @@
+import type { IconGlyph } from './props.js';
+/** 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/svg-image.macos.d.ts

@@ -0,0 +1,3 @@
+export declare function svgDataUri(markup: string): string;
+/** Normalize bundled markup and SVG data URIs for AppKit's image host. */
+export declare function appKitImageSource(src: string): string;