@gjsify/react-native 0.43.0 → 0.45.0

package/lib/types/primitives/table.d.ts

@@ -13,10 +13,18 @@ export type Coercion =
  | 'map'
 /** A number is a pixel count; a string is looked up in the map. */
  | 'pixels-or-map';
+/**
+ * Which of an element's up-to-three GTK nodes a prop lands on.
+ *
+ * `outer` is the node the parent adopts, `content` the node the element's children
+ * go into, `backdrop` a node that takes no children and sits BEHIND them —
+ * `ImageBackground`'s picture, and the only reason the third one exists.
+ */
+export type NodeKind = 'outer' | 'content' | 'backdrop';
 export interface PropertyRoute {
     readonly to: 'property';
     /** Which node it lands on. `content` is the implicit inner box, where there is one. */
-    readonly on?: 'outer' | 'content';
+    readonly on?: NodeKind;
     /** The GTK properties this one prop fills — plural for `size`, which is two requests. */
     readonly names: readonly string[];
     readonly as: Coercion;
@@ -63,7 +71,42 @@ export interface IgnoredRoute {
     readonly to: 'ignored';
     readonly why: string;
 }
-export type PropRoute = PropertyRoute | StylePropertyRoute | EventRoute | RefusedRoute | IgnoredRoute;
+/**
+ * A prop whose value becomes a `Gio.File` — and the reason it is its own kind.
+ *
+ * `Gtk.Picture:file` takes a `Gio.File`, an OBJECT, and building one needs
+ * `gi://Gio`. Nothing under `primitives/` imports `gi://` (that is what makes L2
+ * testable without a display and reusable by a binding that never loads GTK), so the
+ * table cannot produce the value — only the DECISION about it. So L2 does the whole
+ * of the decision, which is where every refusal lives (`http:` has no synchronous
+ * loader, a `require()` id has no asset registry, an array is a device-scale
+ * picker), and hands the framework layer a `{ kind, value }` pair it turns into one
+ * call: `Gio.File.new_for_path` or `Gio.File.new_for_uri`.
+ */
+export interface FileRoute {
+    readonly to: 'file';
+    /** Which node it lands on. */
+    readonly on?: NodeKind;
+    /** The GTK property that takes the file — `file` on a `Gtk.Picture`. */
+    readonly property: string;
+}
+/**
+ * A prop bound through a gesture CONTROLLER rather than a signal on the widget.
+ *
+ * `TouchableWithoutFeedback` is the one primitive that needs it: it has no button
+ * chrome, so its widget is a `Gtk.Box`, and a box emits no `clicked` (measured —
+ * `Gtk.Button`'s two signals are `activate` and `clicked`, and a box has neither).
+ * The desktop answer is a `Gtk.GestureClick` added to the widget, whose `released`
+ * signal is the press completing. A controller is `add_controller(new
+ * Gtk.GestureClick())` — a constructed OBJECT, so the same rule as {@link FileRoute}
+ * applies: the table names the signal, the framework layer builds the controller.
+ */
+export interface GestureRoute {
+    readonly to: 'gesture';
+    /** The `Gtk.GestureClick` signal — `released` for a completed press. */
+    readonly signal: string;
+}
+export type PropRoute = PropertyRoute | StylePropertyRoute | EventRoute | RefusedRoute | IgnoredRoute | FileRoute | GestureRoute;
 /** A second styleable node inside the element, which the children go into. */
 export interface ContentSpec {
     readonly tag: string;
@@ -82,6 +125,16 @@ export interface ContentSpec {
      * the one that holds every child.
      */
     readonly classNameProp: string | null;
+    /**
+     * The slot this node declares to the OUTER node, when the outer node is slotted.
+     *
+     * Absent means the outer node's default slot, which is what every `single`-child
+     * container has. `ImageBackground` is the one primitive that needs it: its outer
+     * node is a `Gtk.Overlay`, whose two slots are not interchangeable — `child`
+     * holds the widget the overlay SIZES ITSELF TO and `add_overlay` stacks widgets
+     * on top of it.
+     */
+    readonly slot?: string;
 }
 export interface PrimitiveSpec {
     /** GType name, which is the tag the host takes. */
@@ -114,6 +167,30 @@ export interface PrimitiveSpec {
         readonly prop: string;
         readonly whenTrue: PrimitiveSpec;
     };
+    /**
+     * A node BEHIND the children, which takes no children of its own.
+     *
+     * `ImageBackground` is the whole of this field, and the shape is forced rather
+     * than chosen. React Native's own `ImageBackground` is a `View` whose first child
+     * is an absolutely positioned `Image` — which is exactly the `overlayOnAbsoluteChild`
+     * switch above. But MEASURED on gtk 4.22.4: a `Gtk.Overlay` paints every overlay
+     * child ABOVE its main child, so a picture in the overlay slot covers the
+     * children instead of sitting behind them. The picture therefore has to be the
+     * MAIN child, and the children move into the overlay slot — which is a third
+     * node, not a variation of the second.
+     */
+    readonly backdrop?: ContentSpec;
+    /**
+     * This primitive answers for no `style` and no `className`, and why.
+     *
+     * `Button` only. React Native's `Button` takes neither — its documented styling
+     * story is "you cannot", and GTK agrees: an `Adw`-themed button is styled by the
+     * theme and by its own classes (`suggested-action`), not by a caller's utility
+     * list. Refusing here rather than in a component's prop type is what makes the
+     * refusal reach a JavaScript caller and both L3s, and it is a REFUSAL rather than
+     * a silent drop for the reason every other one in this file is.
+     */
+    readonly refusesStyle?: string;
 }
 export declare const PRIMITIVES: Readonly<Record<string, PrimitiveSpec>>;
 /** The primitives this layer answers for. Derived, so it cannot disagree with the table. */

package/lib/types/router/errors.d.ts

@@ -0,0 +1,37 @@
+/** What went wrong, as a stable identifier. */
+export type RouterErrorCode = 
+/** A file under the routes directory matches none of the four conventions. */
+'unknown-convention'
+/** A `[…]` segment with nothing between the brackets. */
+ | 'param-without-name'
+/** Two route files resolve to the same URL. */
+ | 'duplicate-route'
+/** `[...rest]` — a catch-all segment, which this layer does not answer yet. */
+ | 'deep-dynamic-unsupported'
+/** `(a,b)` — expo-router's shared groups, which this layer does not answer. */
+ | 'shared-group-unsupported'
+/** A `_layout` file whose directory holds no routes. */
+ | 'layout-without-routes'
+/** The route manifest is empty, or not the shape the plugin emits. */
+ | 'bad-manifest'
+/** A route module with no default export, or one that is not a component. */
+ | 'bad-route-module'
+/** `router.*` was called with no router mounted. */
+ | 'no-router-mounted'
+/** An href no route in the manifest matches. */
+ | 'unresolved-href'
+/** A child of `<Stack>` / `<Tabs>` that is not its own `.Screen`. */
+ | 'not-a-screen-child'
+/** An `options` key the navigator has no GTK answer for. */
+ | 'unknown-screen-option'
+/** A navigator rendered outside the router, so it has no route node to build from. */
+ | 'no-route-node';
+/** A routing input, file name or call this layer cannot answer for, and why. */
+export declare class RouterError extends Error {
+    readonly name = "RouterError";
+    /** The stable identifier. Assert this in a test; print the message to a human. */
+    readonly code: RouterErrorCode;
+    /** The file, href or prop the refusal is about. */
+    readonly subject: string;
+    constructor(code: RouterErrorCode, subject: string, detail: string);
+}

package/lib/types/router/index.d.ts

@@ -0,0 +1,10 @@
+export { router, usePathname, useLocalSearchParams, navigationRef } from './navigation.js';
+export { Stack, type StackProps, type StackScreenOptions } from './stack.js';
+export { Tabs, type TabsProps, type TabScreenOptions } from './tabs.js';
+export { RouterRoot, type RouterRootProps } from './root.js';
+export { RouterError, type RouterErrorCode } from './errors.js';
+export { buildRouteTree, pathConfigOf, screenUrls, type PathConfigLeaf, type PathConfigNode, type PathConfigTree, type RouteManifest, type RouteManifestEntry, type RouteNode, } from './routes.js';
+export { componentFor, provideRouteNode, screenOptionsFrom, useRouteNode, useSynthesisedScreens, type ScreenDeclaration, } from './screens.js';
+export * from '../generated/unsupported-router-exports.js';
+export { ROUTER_NAMES, ROUTER_SUPPORT_TABLE, explainUnsupported, isImportable } from '../support-table.js';
+export type { SupportEntry, SupportStatus, SupportTier } from '../support-table.js';

package/lib/types/router/navigation.d.ts

@@ -0,0 +1,72 @@
+import { type RouteNode } from './routes.js';
+/** The container ref every navigator in the tree hangs under. */
+export declare const navigationRef: import("@react-navigation/core").NavigationContainerRefWithCurrent<ReactNavigation.RootParamList>;
+/**
+ * Bind the module-level `router` to a mounted tree. Called by `RouterRoot`.
+ *
+ * Refuses a second binding by name. The alternative — the newest `RouterRoot` wins —
+ * makes `router.push` navigate a tree the user is not looking at.
+ */
+export declare function installRouter(tree: RouteNode): void;
+/** Release the binding. Called when `RouterRoot` unmounts. */
+export declare function uninstallRouter(): void;
+/**
+ * Tell every subscriber the navigation state moved.
+ *
+ * Called from the container's `onReady` and `onStateChange`. It carries no state,
+ * because the state is read live — see `listeners` for the measurement behind that.
+ */
+export declare function notifyStateChanged(): void;
+/**
+ * `expo-router`'s `router`: four methods, and every argument a URL.
+ *
+ * ADR 0032 measured the calls — `push` 19 times, `back` and `replace` a handful
+ * each, `navigate` where a screen must not stack up. That is the whole object.
+ */
+export declare const router: {
+    /** Go to `href`, adding a history entry even when that screen is already showing. */
+    readonly push: (href: string) => void;
+    /** Go to `href`, reusing the screen when it is already the current one. */
+    readonly navigate: (href: string) => void;
+    /** Replace the current screen with `href`, leaving the history length alone. */
+    readonly replace: (href: string) => void;
+    /**
+     * Go back one entry.
+     *
+     * REFUSES when there is nowhere to go, which React Navigation's own `goBack`
+     * does not — it returns quietly. A quiet return is the silent drop this layer
+     * refuses everywhere else: the user presses back, the window does not change,
+     * and nothing anywhere says why.
+     */
+    readonly back: () => void;
+};
+/**
+ * The current URL, without its query string.
+ *
+ * `useSyncExternalStore` and not `useNavigationState`, for two reasons that both
+ * matter: the value is derived from the ROOT state while a hook inside a screen sees
+ * only its own navigator's, and the store can change between render and commit —
+ * the tear `useSyncExternalStore` exists to prevent. The snapshot is a STRING, which
+ * is what makes reading it live from the container legal: React compares snapshots by
+ * identity, and a fresh object every call is the "getSnapshot should be cached"
+ * warning.
+ *
+ * The `/` it answers before the container is ready is not a placeholder: nothing has
+ * been navigated to yet, and the root URL is what the tree is about to show.
+ */
+export declare function usePathname(): string;
+/**
+ * The params of the CURRENT route — the `[param]` values and the query string.
+ *
+ * `Local`, in expo-router's own sense: the params of the screen that calls it, not
+ * of whichever screen is focused elsewhere in the tree. That is `useRoute()`, which
+ * reads the nearest route context, minus React Navigation's own nesting keys —
+ * `screen`, `params`, `initial`, `state`, `path`, `pop` and `merge` are how a nested
+ * NAVIGATE addresses a child navigator, and handing them back as though the author
+ * had written them makes those seven param names silently unusable.
+ *
+ * Values are strings, because a URL segment is one. A number or a boolean that
+ * arrived through a dispatched param is stringified rather than dropped; anything
+ * structural (an object, an array) is left out, and `[param]` cannot produce one.
+ */
+export declare function useLocalSearchParams<T extends Record<string, string> = Record<string, string>>(): Partial<T>;

package/lib/types/router/root.d.ts

@@ -0,0 +1,24 @@
+import { type ReactElement } from 'react';
+import { type RouteManifest } from './routes.js';
+/** What `<RouterRoot>` needs. */
+export interface RouterRootProps {
+    /**
+     * Every route file, as `{ contextKey, module }`.
+     *
+     * From the bundler plugin's virtual module in the ordinary case; a hand-written
+     * array works identically, which is the point of putting the conventions in this
+     * package rather than in the plugin (ADR 0032 § 12 — the build chain belongs to
+     * the consumer).
+     */
+    manifest: RouteManifest;
+}
+/**
+ * The router, mounted.
+ *
+ * Throws — by name, with the file to create — when the routes directory has no
+ * `_layout`. expo-router requires one too, and the reason is worth stating: the root
+ * layout is where the application says WHICH navigator its top level is, and there is
+ * no defensible default. Quietly supplying a `<Stack>` would make a missing file look
+ * like a working application whose tabs never appear.
+ */
+export declare function RouterRoot(props: RouterRootProps): ReactElement;

package/lib/types/router/router.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/router/routes.d.ts

@@ -0,0 +1,90 @@
+/** One entry of the manifest a bundler plugin emits, or a consumer writes by hand. */
+export interface RouteManifestEntry {
+    /**
+     * The file's path relative to the routes directory, extension included —
+     * `(tabs)/home.tsx`. expo-router calls this the context key and so does this,
+     * because it is the string every diagnostic quotes back.
+     */
+    readonly contextKey: string;
+    /**
+     * The module the file exported, ALREADY EVALUATED.
+     *
+     * Eager, not `() => import(…)`, and that is a decision rather than a shortcut.
+     * A lazy route needs a Suspense boundary, and `@gjsify/gtk-host/react`'s
+     * `render()` is synchronous by construction — a boundary that suspends on the
+     * first commit leaves the container EMPTY and returns cleanly, which is the
+     * silent-empty-window failure that host exists to refuse. A desktop application
+     * also ships as one bundle (ADR 0024), so there is no download for laziness to
+     * defer. `unknown` rather than a React type keeps this module framework-free;
+     * `screens.ts` is where the shape is checked, by name.
+     */
+    readonly module: unknown;
+}
+/** What a bundler plugin emits: every route file it found, in a stable order. */
+export type RouteManifest = readonly RouteManifestEntry[];
+/** A node of the route tree — one navigator, or one screen inside one. */
+export interface RouteNode {
+    /** `layout` renders a navigator and has children; `screen` renders a route file. */
+    readonly kind: 'layout' | 'screen';
+    /**
+     * The React Navigation route name: this node's path RELATIVE to the navigator
+     * that holds it. `index`, `home`, `(tabs)`, `detail/[id]`, `+not-found`.
+     */
+    readonly name: string;
+    /** The URL pattern this node contributes, in React Navigation's `:param` spelling. */
+    readonly path: string;
+    /** Param names this node's own pattern introduces, in declaration order. */
+    readonly params: readonly string[];
+    /** The file behind it. `null` for the synthesised root, which has no `_layout`. */
+    readonly contextKey: string | null;
+    /** That file's evaluated module. `null` when `contextKey` is. */
+    readonly module: unknown;
+    /** Children. Non-empty exactly when `kind` is `layout`. */
+    readonly children: readonly RouteNode[];
+    /** The `+not-found` route. Its pattern is `*`, so it matches last. */
+    readonly notFound: boolean;
+}
+/**
+ * The routes directory → the navigator tree.
+ *
+ * @throws RouterError for every one of the conventions' failure modes: a file that
+ * matches none of them, a `[param]` with no name, two files claiming one URL, a
+ * `_layout` with nothing under it, and a manifest that is empty or misshapen.
+ */
+export declare function buildRouteTree(manifest: RouteManifest): RouteNode;
+/** A navigator's entry in React Navigation's path config: children, and which is first. */
+export interface PathConfigTree {
+    readonly initialRouteName?: string;
+    readonly screens: Readonly<Record<string, PathConfigNode>>;
+}
+/** A screen's entry: one URL pattern, and no children. */
+export interface PathConfigLeaf {
+    readonly path: string;
+}
+/** Either, which is what makes the config a tree. */
+export type PathConfigNode = PathConfigLeaf | PathConfigTree;
+/**
+ * The tree → the config `getStateFromPath` / `getPathFromState` take.
+ *
+ * REUSED RATHER THAN WRITTEN, and this function is the whole reason the reuse
+ * works: React Navigation already turns a URL into navigation state and state back
+ * into a URL, correctly, for nested navigators and for params. What it needs is a
+ * description of the tree, and the tree is what the file convention produces. So
+ * `router.navigate('/detail/7')` is `getStateFromPath` + `getActionFromState`, and
+ * `usePathname()` is `getPathFromState` — no matcher of our own in either
+ * direction, which is where a second router would have started.
+ *
+ * ONLY A SCREEN CARRIES A `path`, AND ITS PATH IS THE JOIN OF ITS ANCESTORS'.
+ * MEASURED, because the obvious shape does not work: giving the navigator its own
+ * `path` (`'(tabs)'` → `''`, `detail` → `'detail'`) makes React Navigation build a
+ * config entry for the navigator ITSELF as well as for its screens, and it then
+ * refuses the whole config — "Found conflicting screens with the same pattern. The
+ * pattern '' resolves to both 'index' and '(tabs)'". A navigator is not a
+ * destination; only the screen inside it is. Folding the prefix into the children
+ * keeps the `screens` nesting (which is what makes the resulting STATE nest, and
+ * therefore what makes a nested navigator work at all) while leaving exactly one
+ * pattern per screen.
+ */
+export declare function pathConfigOf(tree: RouteNode, prefix?: string): PathConfigTree;
+/** Every screen's URL pattern, for a diagnostic that lists what WOULD have matched. */
+export declare function screenUrls(tree: RouteNode, prefix?: string): readonly string[];

package/lib/types/router/routes.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/router/screens.d.ts

@@ -0,0 +1,48 @@
+import { type ComponentType, type ReactElement, type ReactNode } from 'react';
+import type { RouteNode } from './routes.js';
+/** Publish `node` to the navigator a layout component is about to render. */
+export declare const provideRouteNode: (node: RouteNode, children: ReactNode) => ReactElement;
+/** The layout node this navigator belongs to, or a refusal naming the fix. */
+export declare function useRouteNode(navigator: string): RouteNode;
+export declare function componentFor(node: RouteNode): ComponentType<Record<string, unknown>>;
+/** What a `<Stack.Screen>` / `<Tabs.Screen>` declaration carries. */
+export interface ScreenDeclaration {
+    /** The route name — the file's path relative to this navigator, e.g. `index`. */
+    name: string;
+    /** Per-screen options. Validated against the navigator's own allow-list. */
+    options?: Record<string, unknown>;
+}
+/**
+ * A navigator's declared children → options by route name.
+ *
+ * REFUSES ANY OTHER CHILD BY NAME. `<Stack>{loading ? <Spinner/> : null}</Stack>` is
+ * the shape that gets written, and expo-router ignores it — which means a widget the
+ * author put in a navigator vanishes with no message. The refusal names the child
+ * and says where content belongs, which is inside a route file.
+ *
+ * `allowed` is the navigator's own option vocabulary, and an option outside it is
+ * refused for the same reason: `headerTintColor` silently doing nothing is a defect
+ * that only a screenshot can find.
+ */
+export declare function screenOptionsFrom(navigator: string, ScreenMarker: ComponentType<ScreenDeclaration>, allowed: readonly string[], children: ReactNode): ReadonlyMap<string, Record<string, unknown>>;
+/**
+ * The React Navigation `<Screen>` elements a navigator's node implies.
+ *
+ * Memoised on the node and the options, because `useNavigationBuilder` reads these
+ * children on every render and rebuilding the elements is cheap while rebuilding the
+ * COMPONENTS is not — `componentFor` is what holds that line, and this hook keeps
+ * the element array from churning as well.
+ */
+export declare function useSynthesisedScreens(node: RouteNode, Screen: ComponentType<ScreenDeclaration>, options: ReadonlyMap<string, Record<string, unknown>>): readonly ReactElement[];
+/**
+ * Core's own `Screen`, which is the only component `useNavigationBuilder` accepts.
+ *
+ * Reached through the public factory rather than imported: `@react-navigation/core`
+ * does not export `Screen` from its index (it is meant to arrive with a `Navigator`),
+ * and calling the factory with a component nothing renders is the documented way to
+ * get the pair. The typed shape is asserted here once so no navigator repeats it.
+ */
+export declare function navigationPair<Props>(View: ComponentType<Props>): {
+    readonly Navigator: ComponentType<Props>;
+    readonly Screen: ComponentType<ScreenDeclaration>;
+};

package/lib/types/router/stack.d.ts

@@ -0,0 +1,118 @@
+import { type ReactElement, type ReactNode } from 'react';
+import type Adw from '@girs/adw-1';
+import { type ScreenDeclaration } from './screens.js';
+/** What one screen of a stack can be told. */
+export interface StackScreenOptions {
+    /** The page title, shown by the page's own header bar. Defaults to the route name. */
+    title?: string;
+    /** `false` renders the screen with no `Adw.HeaderBar`, and so with no back button. */
+    headerShown?: boolean;
+    /** `none` turns the transition off for this screen only. */
+    animation?: 'default' | 'none';
+}
+/** What `applyStack` did, so a vector can assert the classification and not the paint. */
+export type StackChange = 'pop' | 'push' | 'replace' | 'none';
+/**
+ * Classify the difference, and apply the one operation that fits it.
+ *
+ * `animate` is asked about the page that is MOVING — the departing one for a pop and
+ * the arriving one for a push, because the transition belongs to the page the user is
+ * about to stop or start looking at.
+ */
+export declare function applyStack(view: Adw.NavigationView, current: readonly string[], desired: readonly string[], animate: (key: string | undefined) => boolean): StackChange;
+/**
+ * Which pages exist, and which of them are on their way out.
+ *
+ * Generic over the descriptor, and exported with the three functions that advance
+ * it, because this is where behaviour 3's edge cases live and none of them needs a
+ * widget or a reconciler to be wrong: a key held after its page is gone leaks for
+ * the life of the process, a key dropped too early flashes an empty page, and a
+ * reordered `order` makes the host reorder `Adw.NavigationView`'s children — which
+ * that widget answers by taking pages out of the navigation stack. Pure arithmetic
+ * over key sets is exactly what a spec can pin exhaustively.
+ */
+export interface Tracking<D> {
+    /** Page order — append-only for as long as a key is needed. See the header. */
+    readonly order: readonly string[];
+    /** The focused route key at the last advance, so a departure can be recognised. */
+    readonly focused: string | undefined;
+    /** Descriptors whose routes are gone and whose pages GTK is still animating out. */
+    readonly closing: Readonly<Record<string, D>>;
+}
+/** The tracking a first render starts from. */
+export declare const initialTracking: <D>(live: readonly string[], focused: string | undefined) => Tracking<D>;
+/** Every key that must still be rendered: the live routes plus what is closing. */
+export declare const neededKeys: <D>(tracking: Tracking<D>, live: readonly string[]) => readonly string[];
+/** Has anything changed that the tracking has to answer for? */
+export declare const needsAdvance: <D>(tracking: Tracking<D>, live: readonly string[], focused: string | undefined) => boolean;
+/**
+ * The next tracking, given the live routes and the descriptors of the LAST commit.
+ *
+ * `previous` and not the current descriptors: the descriptor of a route that just
+ * left the state is not in the current map any more, and the closing page still has
+ * to render something.
+ *
+ * ONLY THE DEPARTING FOCUSED KEY BECOMES `closing`. A route removed from the middle
+ * of the stack was never on screen, so nothing is animating it out and holding it
+ * would be a leak with no symptom.
+ */
+export declare function advanceTracking<D>(tracking: Tracking<D>, live: readonly string[], focused: string | undefined, previous: Readonly<Record<string, D>>): Tracking<D>;
+/** Let go of one closing page. Identity-stable when the key was not closing. */
+export declare function releaseFrom<D>(tracking: Tracking<D>, key: string): Tracking<D>;
+/**
+ * Run `action` at most once per microtask, however many times the trigger fires.
+ *
+ * MEASURED on libadwaita 1.9.3: `pop_to_tag` over two pages emits `popped` TWICE,
+ * and the widget's navigation stack is ALREADY FINAL at the first emission — both
+ * handlers see `a,b`. So every emission in a burst asks the same question.
+ *
+ * AND THE OBVIOUS JUSTIFICATION IS NOT THE ONE THAT HOLDS, which is worth writing
+ * down because it is the one a reader will supply. "Without this it over-pops" is
+ * NOT measured: with the coalescer disabled, a four-to-two gesture still lands on two
+ * routes, because `@react-navigation/core` 7.21.13 updates `navigation.getState()`
+ * eagerly on dispatch, so the second handler computes a delta of zero. What the
+ * coalescer actually buys is:
+ *
+ *   - ATTRIBUTABILITY. Undebounced, correctness rests on that eagerness, which is an
+ *     internal and not a documented contract. If a future version batched its state,
+ *     an undebounced bridge would dispatch the same pop N times and the symptom —
+ *     "back skips two screens" — would surface nowhere near the cause.
+ *   - N − 1 fewer passes per gesture: one dispatch and one walk of the widget's list
+ *     model instead of one per popped page.
+ *
+ * Also measured, and the reason no echo guard is needed anywhere else here:
+ * `replace_with_tags` emits NO `popped` at all, so this layer's own React→widget sync
+ * cannot re-enter through the bridge.
+ */
+export declare function coalesce(action: () => void): () => void;
+/**
+ * A `<Stack.Screen>` declaration. Read as data by `<Stack>`; never rendered.
+ *
+ * It throws if it ever IS rendered, because that means it was put somewhere no
+ * navigator reads it — inside a `<View>`, or in a route file — and a component that
+ * rendered nothing there would be a silent drop.
+ */
+declare function StackScreen(_props: ScreenDeclaration & {
+    options?: StackScreenOptions;
+}): never;
+declare namespace StackScreen {
+    var displayName: string;
+}
+/** What `<Stack>` accepts. */
+export interface StackProps {
+    /** `<Stack.Screen>` declarations, and nothing else. */
+    children?: ReactNode;
+    /** Options for every screen, before its own. */
+    screenOptions?: StackScreenOptions;
+}
+/**
+ * `expo-router`'s `<Stack>`: its screens are the FILES this `_layout` owns.
+ *
+ * Its children are read as declarations, so the ordinary React reflex — putting
+ * content in a navigator — is refused by name rather than dropped.
+ */
+export declare function Stack(props: StackProps): ReactElement;
+export declare namespace Stack {
+    var Screen: typeof StackScreen;
+}
+export {};

package/lib/types/router/tabs.d.ts

@@ -0,0 +1,36 @@
+import { type ReactElement, type ReactNode } from 'react';
+import { type ScreenDeclaration } from './screens.js';
+/** What one tab can be told. */
+export interface TabScreenOptions {
+    /** The switcher button's label. Defaults to the route name. */
+    title?: string;
+}
+/** A `<Tabs.Screen>` declaration. Read as data by `<Tabs>`; never rendered. */
+declare function TabsScreen(_props: ScreenDeclaration & {
+    options?: TabScreenOptions;
+}): never;
+declare namespace TabsScreen {
+    var displayName: string;
+}
+/** What `<Tabs>` accepts. */
+export interface TabsProps {
+    /** `<Tabs.Screen>` declarations, and nothing else. */
+    children?: ReactNode;
+    /** Options for every tab, before its own. */
+    screenOptions?: TabScreenOptions;
+    /** `false` drops the header bar, and with it the switcher. */
+    headerShown?: boolean;
+}
+/**
+ * `expo-router`'s `<Tabs>`: its tabs are the FILES this `_layout` owns.
+ *
+ * Every tab is mounted. React Native's tab navigator mounts lazily because a phone
+ * cannot afford five screens; a GTK page that is not the visible child of an
+ * `Adw.ViewStack` is not realised and costs a widget, and the laziness would buy a
+ * flash on first switch. Declared as a limit rather than left as a surprise.
+ */
+export declare function Tabs(props: TabsProps): ReactElement;
+export declare namespace Tabs {
+    var Screen: typeof TabsScreen;
+}
+export {};

package/lib/types/solid/index.d.ts

@@ -48,10 +48,15 @@ export interface PressableProps extends CommonProps {
     /**
      * Never a function of `{ pressed }`.
      *
-     * `PrimitiveChildren` excludes functions, which is the build-time half of ADR
-     * 0032 § 7's refusal — the same half `components.ts` gets from `ReactNode`. The
-     * runtime half is in `factsOf`, and it is generic rather than per-primitive here
-     * because Solid resolves children before any primitive sees them.
+     * `PrimitiveChildren` excludes functions, which is the build-time half of the
+     * refusal. The runtime half is in `factsOf`, and it is generic rather than
+     * per-primitive here because Solid resolves children before any primitive sees
+     * them.
+     *
+     * The REACT binding implements the function form; this one does not, and the
+     * reason is in `factsOf`' message: a Solid component body runs once, so the press
+     * state has to reach the child as a signal rather than as a re-render, which is a
+     * design of its own rather than a port.
      */
     children?: PrimitiveChildren;
 }

package/lib/types/stylesheet.d.ts

@@ -0,0 +1,75 @@
+import { type StyleInput, type StyleObject } from './primitives/style.js';
+/** React Native's own shape: a name per style, each a property record. */
+export type NamedStyles<T> = {
+    readonly [K in keyof T]: StyleObject;
+};
+/**
+ * `{ position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 }`.
+ *
+ * React Native's own object, value for value — and every one of the five properties
+ * is routed by L1 (`position` and the four edges), so it needs no special case here.
+ * The numeric zeros are what React Native writes and `normalise()` turns each into
+ * `"0px"`, which is what the partition reads.
+ *
+ * On GTK it resolves to the overlay intent with all four edges at 0, which L2 answers
+ * as `halign: fill, valign: fill` on an overlay child — the one case where React
+ * Native's four offsets and GTK's two alignments agree exactly, because filling both
+ * axes is the only inset an overlay child can express without a coordinate pair.
+ */
+export declare const absoluteFillObject: StyleObject;
+export declare const StyleSheet: {
+    /**
+     * The style set, unchanged — see the header for why that is the honest answer.
+     *
+     * The signature is React Native's: the generic keeps each key's type, so
+     * `styles.title` is a style and `styles.titlee` is a type error.
+     */
+    readonly create: <T extends NamedStyles<T>>(styles: T) => T;
+    /**
+     * A `style` prop → one flat object, later entries winning.
+     *
+     * L2's `flattenStyle`, exported under React Native's name rather than
+     * reimplemented: the resolver has to flatten the same prop with the same
+     * precedence, and two functions answering "what does `[a, cond && b]` mean" is
+     * the second truth this package keeps lifting out.
+     */
+    readonly flatten: (style: StyleInput) => StyleObject;
+    /**
+     * Two styles into one, React Native's own semantics.
+     *
+     * `b` wins where both set a property, `null`/`undefined` fall away, and the result
+     * is an ARRAY when both are present — because that is what React Native returns
+     * and code downstream compares identities. `flatten` is what collapses it.
+     */
+    readonly compose: (a: StyleInput, b: StyleInput) => StyleInput;
+    /**
+     * One device pixel, in logical pixels — read fresh, never cached.
+     *
+     * A GETTER because `Gdk.Display.get_default()` is null until `Gtk.init()`
+     * (measured) and real code reads this at module scope: before the display exists
+     * the answer is 1, and the same read once the application is running answers from
+     * the monitors. A constant would freeze the first of those for the process.
+     * `apis/display.ts` holds the measurement and the reason it takes the SMALLEST
+     * monitor scale.
+     */
+    readonly hairlineWidth: number;
+    /**
+     * React Native's `absoluteFill`, which is the same object as `absoluteFillObject`.
+     *
+     * It was a registered style id and is now the object itself, so the two members
+     * differ in name only. Both are exported because ported code uses both spellings
+     * and an absent one is a `MISSING_EXPORT` rather than a value that behaves.
+     */
+    readonly absoluteFill: Readonly<Record<string, unknown>>;
+    readonly absoluteFillObject: Readonly<Record<string, unknown>>;
+    /**
+     * Refused by name: it installs a GLOBAL transform on every style in the process.
+     *
+     * React Native uses it to let a platform rewrite style values before they reach
+     * the native side. Here the equivalent hook already exists and is scoped:
+     * `configureStyle({ tokens })` is where a project's own values enter, and a
+     * process-wide preprocessor would be a second, invisible one that no element
+     * could opt out of.
+     */
+    readonly setStyleAttributePreprocessor: () => never;
+};