@gjsify/react-native 0.47.0 → 0.49.0

package/lib/types/components.d.ts

@@ -1,11 +1,12 @@
 import { type ReactElement, type ReactNode, type Ref } from 'react';
+import type { AccessibilityProps } from './primitives/accessibility.js';
 import type { ClassNameInput } from './primitives/classes.js';
 import { type TextInputHandle } from './primitives/handles.js';
 import { type ChildContext, type PrimitivePlan, type WidgetNode } from './primitives/resolve.js';
 import { type StyleInput } from './primitives/style.js';
 import type { StyleTokens } from '@gjsify/gtk-host/style';
 /** What every primitive accepts on top of its own props. */
-export interface CommonProps {
+export interface CommonProps extends AccessibilityProps {
     className?: ClassNameInput;
     style?: StyleInput;
     children?: ReactNode;
@@ -101,6 +102,15 @@ export interface ScrollViewProps extends CommonProps {
     /** NativeWind's spelling for the inner node's class list. See `ContentSpec.classNameProp`. */
     contentContainerClassName?: ClassNameInput;
 }
+/**
+ * How many scrollers are currently watching their viewport's width.
+ *
+ * A column has nothing to invalidate when that width changes — its height is not a
+ * function of it — and a column that subscribed anyway would render identically to
+ * one that did not, queueing a resize per window resize with nothing to show for it.
+ * Only a count tells them apart.
+ */
+export declare const railWatchCount: () => number;
 export declare function ScrollView(props: ScrollViewProps): ReactElement;
 export interface ActivityIndicatorProps extends CommonProps {
     animating?: boolean;
@@ -231,6 +241,38 @@ export declare function Button(props: ButtonProps): ReactElement;
  * lost a screen.
  */
 export declare function SafeAreaView(props: ViewProps): ReactElement;
+export interface ModalProps extends CommonProps {
+    /** Default `true`, as React Native's is. `false` renders nothing at all. */
+    visible?: boolean;
+    /**
+     * The user asked for this modal to go away — `Adw.Dialog::close-attempt`.
+     *
+     * REQUIRED IN PRACTICE, exactly as React Native documents it for Android and
+     * tvOS, and here for the same reason made explicit: the dialog is built with
+     * `can-close: false`, so Escape, the close control and a click on the backdrop
+     * all arrive HERE and none of them takes the sheet down. Setting `visible` to
+     * false does. Without this prop a modal cannot be dismissed by the user, which
+     * is React Native's behaviour and not a limitation of this layer.
+     */
+    onRequestClose?: () => void;
+    /** The modal is on screen — `Gtk.Widget::map`, which fires once. */
+    onShow?: () => void;
+}
+/**
+ * A portal: the element's host node is not its parent node (ADR 0045).
+ *
+ * The whole component is `visible`. Everything else — presenting the dialog against
+ * the parent's toplevel, waiting for one when the tree is still detached, taking the
+ * sheet back down on unmount — is the host's placement axis, which is why this is
+ * eight lines and why a Vue or Solid binding gets the same behaviour for free.
+ *
+ * THE HOOKS RUN EITHER WAY, and that is the one thing this file could get wrong: an
+ * early return before `usePlan` would change the component's hook count the first
+ * time `visible` flipped, which React refuses outright. So the plan is always built
+ * and only the RENDER is conditional — and an unrendered element is one React
+ * deletes, which reaches `destroy` in the host and closes the dialog.
+ */
+export declare function Modal(props: ModalProps): ReactElement | null;
 export interface KeyboardAvoidingViewProps extends ViewProps {
     /** A declared no-op: there is no on-screen keyboard to move out of the way of. */
     behavior?: 'height' | 'position' | 'padding';

package/lib/types/generated/unsupported-react-native.d.ts

@@ -1,11 +1,9 @@
-export declare const Modal: never;
 export declare const RefreshControl: never;
 export declare const AppState: never;
 export declare const PixelRatio: never;
 export declare const PlatformColor: never;
 export declare const AccessibilityInfo: never;
 export declare const LayoutAnimation: never;
-export declare const InteractionManager: never;
 export declare const useAnimatedValue: never;
 export declare const useAnimatedValueXY: never;
 export declare const useAnimatedColor: never;
@@ -48,10 +46,16 @@ export declare const UIManager: never;
 export declare const findNodeHandle: never;
 export declare const registerCallableModule: never;
 export declare const Networking: never;
-export declare const NativeDialogManagerAndroid: never;
 export declare const ProgressBarAndroid: never;
-export declare const Touchable: never;
 export declare const NativeEventEmitter: never;
 export declare const DeviceEventEmitter: never;
 export declare const NativeAppEventEmitter: never;
 export declare const RootTagContext: never;
+export declare const AssetRegistry: never;
+export declare const unstable_VirtualArray: never;
+export declare const unstable_createVirtualCollectionView: never;
+export declare const unstable_VirtualColumn: never;
+export declare const unstable_VirtualColumnGenerator: never;
+export declare const unstable_VirtualRow: never;
+export declare const unstable_getScrollParent: never;
+export declare const unstable_DEFAULT_INITIAL_NUM_TO_RENDER: never;

package/lib/types/index.d.ts

@@ -1,9 +1,9 @@
-export { AppRegistry, registerRootComponent } from './app-registry.js';
+export { AppRegistry, lastWindowChromeProblems, registerRootComponent } from './app-registry.js';
 export type { ComponentProvider, RunApplicationOptions } from './app-registry.js';
 export { EventEmitter } from './event-emitter.js';
 export type { EventSubscription } from './event-emitter.js';
-export { ActivityIndicator, Button, Image, ImageBackground, KeyboardAvoidingView, Pressable, SafeAreaView, ScrollView, StatusBar, Switch, Text, TextInput, TouchableHighlight, TouchableOpacity, TouchableWithoutFeedback, View, } from './components.js';
-export type { ActivityIndicatorProps, ButtonProps, CommonProps, ImageBackgroundProps, ImageProps, ImageURISource, KeyboardAvoidingViewProps, PressableProps, PressableState, ScrollViewProps, StatusBarProps, SwitchProps, TextInputProps, TextProps, TouchableHighlightProps, TouchableProps, TouchableWithoutFeedbackProps, ViewProps, } from './components.js';
+export { ActivityIndicator, Button, Image, ImageBackground, KeyboardAvoidingView, Modal, Pressable, SafeAreaView, ScrollView, StatusBar, Switch, Text, TextInput, TouchableHighlight, TouchableOpacity, TouchableWithoutFeedback, View, } from './components.js';
+export type { ActivityIndicatorProps, ButtonProps, CommonProps, ImageBackgroundProps, ImageProps, ImageURISource, KeyboardAvoidingViewProps, ModalProps, PressableProps, PressableState, ScrollViewProps, StatusBarProps, SwitchProps, TextInputProps, TextProps, TouchableHighlightProps, TouchableProps, TouchableWithoutFeedbackProps, ViewProps, } from './components.js';
 export { FlatList, SectionList, VirtualizedList, VirtualizedSectionList } from './lists/components.js';
 export type { FlatListProps, ListRenderItemInfo, ListSeparators, ListSlot, SectionListProps, SectionListSection, VirtualizedListProps, } from './lists/components.js';
 export { Alert, Appearance, Dimensions, Keyboard, Linking, Platform, Share } from './apis/index.js';

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

@@ -0,0 +1,112 @@
+/**
+ * One GTK accessible attribute, and the GValue GTK reads its value out of.
+ *
+ * `set` picks the call — `Gtk.Accessible.update_property()` or `update_state()`.
+ * They are two enums (`Gtk.AccessibleProperty`, `Gtk.AccessibleState`) with
+ * overlapping nicks, so which SET an attribute belongs to is not derivable from
+ * its name and is declared here.
+ */
+export interface AccessibleAttribute {
+    readonly set: 'property' | 'state';
+    /**
+     * The enum member's nick — `label`, `help-text`, `checked`, `disabled`.
+     *
+     * A nick rather than the enum member, for the reason every other route holds
+     * strings: nothing under `primitives/` imports `gi://`. The call layer resolves
+     * it the way `@gjsify/gtk-host`'s `props.ts` resolves any enum nick, by
+     * upper-casing and swapping `-` for `_`.
+     */
+    readonly name: string;
+    /** Which GValue GTK reads it out of — see this module's header; every one is measured. */
+    readonly as: 'string' | 'boolean' | 'tristate';
+}
+/** A prop whose own value is one accessible attribute — `accessibilityLabel`. */
+export interface AccessibleValueRoute {
+    readonly to: 'accessible';
+    readonly from: 'value';
+    readonly attribute: AccessibleAttribute;
+}
+/**
+ * A prop whose value is a RECORD of accessible attributes — `accessibilityState`.
+ *
+ * React Native has exactly one of these and its five keys all land, which is the
+ * happier half of a mapping that is otherwise full of refusals: `disabled` and
+ * `busy` are GTK booleans, and `selected`, `checked` and `expanded` are GTK
+ * TRISTATES — so `checked: 'mixed'`, the one genuinely three-valued thing in
+ * React Native's accessibility surface, has an exact GTK member
+ * (`Gtk.AccessibleTristate.MIXED`) rather than an approximation.
+ *
+ * `refuses` is empty today and is kept because the next key React Native adds is
+ * more likely to have no GTK attribute than to have one, and a key refused BY NAME
+ * with a reason is the answer this table gives everywhere else.
+ */
+export interface AccessibleMembersRoute {
+    readonly to: 'accessible';
+    readonly from: 'members';
+    readonly members: Readonly<Record<string, AccessibleAttribute>>;
+    /** Keys this layer recognises and cannot answer, each with what to do instead. */
+    readonly refuses: Readonly<Record<string, string>>;
+}
+export type AccessibleRoute = AccessibleValueRoute | AccessibleMembersRoute;
+/**
+ * One accessible attribute write, decided here and CALLED one layer up.
+ *
+ * `value` is already the shape the call layer puts in a GValue: a string for
+ * `string`, a boolean for `boolean`, and 0/1/2 for `tristate` — the numeric
+ * `Gtk.AccessibleTristate` member, resolved here so the call layer holds no
+ * vocabulary of its own.
+ */
+export interface ResolvedAccessible {
+    /** The React Native prop that asked for it, for a refusal's benefit. */
+    readonly prop: string;
+    readonly set: 'property' | 'state';
+    readonly name: string;
+    readonly value: string | boolean | number;
+}
+/**
+ * The accessibility props every primitive accepts, declared ONCE for both L3s.
+ *
+ * Here rather than in either binding because the two `CommonProps` are
+ * hand-maintained and this set is identical in both — the second copy is where a
+ * prop that exists in React and not in Solid comes from, and `PROPS.md` would keep
+ * claiming both answered it. L2 owns the vocabulary; a binding extends it.
+ */
+export interface AccessibilityProps {
+    /**
+     * Recognised and without effect — every GTK widget is already in the
+     * accessibility tree. The table's row carries the whole reason and names the
+     * prop that takes an element OUT of it (`accessibilityRole="none"`).
+     */
+    accessible?: boolean;
+    /** The accessible NAME — `Gtk.AccessibleProperty.LABEL`, what a screen reader says on focus. */
+    accessibilityLabel?: string;
+    /**
+     * The accessible ROLE — the GObject property `Gtk.Accessible:accessible-role`.
+     *
+     * `string` rather than React Native's own union, because the mapping is the
+     * table's and an unmapped value is a named refusal at render rather than a type
+     * error: React Native's own type ends in `| string`, so a union here would
+     * reject nothing the table accepts and accept nothing extra.
+     */
+    accessibilityRole?: string;
+    /** What acting on this element does — `Gtk.AccessibleProperty.HELP_TEXT`. */
+    accessibilityHint?: string;
+    /** The accessible STATES — `Gtk.Accessible.update_state()`; `checked` is a real tri-state. */
+    accessibilityState?: {
+        disabled?: boolean;
+        busy?: boolean;
+        checked?: boolean | 'mixed';
+        selected?: boolean;
+        expanded?: boolean;
+    };
+}
+/**
+ * A route plus the authored value → the attribute writes it stands for.
+ *
+ * Throws nothing itself: it reports a bad value as a `problem` so the caller raises
+ * the one `PrimitiveError` this layer raises, with the primitive's own name in it.
+ */
+export declare function resolveAccessible(route: AccessibleRoute, prop: string, value: unknown): {
+    entries: readonly ResolvedAccessible[];
+    problem: string | null;
+};

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

@@ -21,6 +21,8 @@ export type PropStatus =
  | 'gesture'
 /** Calls `Gtk.Accessible.announce()` when a signal reports the content changed. */
  | 'announcement'
+/** Writes a `Gtk.Accessible` property or state through `update_property()`/`update_state()`. */
+ | 'accessible'
 /** Recognised and deliberately without effect on a desktop window. */
  | 'ignored'
 /** Refused by name, with a reason. Throws a `PrimitiveError` when rendered. */
@@ -44,6 +46,22 @@ export interface PropAnswer {
     readonly why: string;
     /** What it reaches on the GTK side: property names, a signal, or nothing. */
     readonly gtk: readonly string[];
+    /**
+     * The VALUES this prop refuses by name, each with its own reason (#1555).
+     *
+     * A field rather than a fold into {@link why}, because the prop is ACCEPTED and
+     * only some of its values are not: `accessibilityRole` answers most role names and
+     * refuses a handful, and a row that said `property | — ` could not tell a reader
+     * which — `propRefusedValues` is the reader that can. Keyed by the VALUE for a
+     * mapped property route and by the KEY for an accessible record
+     * (`accessibilityState`), which is the same question at the two grains the table
+     * has.
+     *
+     * The reason is the table's own string, not a sentence built here: `prop-table.ts`
+     * wraps it in the subject the resolver throws, so the static answer and the render
+     * stay one string (ADR 0039 § 2).
+     */
+    readonly refuses: Readonly<Record<string, string>>;
 }
 /** Does this status let a render proceed? `ignored` counts — it is a declared no-op, not a refusal. */
 export declare const isAccepted: (status: PropStatus) => boolean;

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

@@ -7,6 +7,15 @@
  * both the throw and the static answer are built from it.
  */
 export declare const primitiveErrorMessage: (primitive: string, subject: string, detail: string) => string;
+/**
+ * How a VALUE reads inside a subject — `prop "accessibilityRole" = "keyboardkey"`.
+ *
+ * Here rather than in `resolve.ts`, where it started, because the per-value refusals
+ * are answerable statically now (ADR 0039 § Amendment, #1555) and `prop-table.ts` has
+ * to build the same subject the throw does. Two formatters that happen to agree are
+ * not one string.
+ */
+export declare const describeValue: (value: unknown) => string;
 /** A primitive, prop or combination this layer cannot answer for, and why. */
 export declare class PrimitiveError extends Error {
     readonly name = "PrimitiveError";

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

@@ -1,4 +1,5 @@
 import type { LayoutIntent, StyleTokens } from '@gjsify/gtk-host/style';
+import { type ResolvedAccessible } from './accessibility.js';
 import type { ClassNameInput } from './classes.js';
 import { type ChildContext, type ChildFacts, type Orientation, type WidgetFacts } from './intents.js';
 import { type ClassNameSink, type StyleInput } from './style.js';
@@ -77,6 +78,7 @@ export interface ResolvedAnnouncement {
     /** The `Gtk.AccessibleAnnouncementPriority` nick. */
     readonly priority: 'low' | 'medium' | 'high';
 }
+export type { ResolvedAccessible } from './accessibility.js';
 export interface PrimitivePlan {
     readonly primitive: string;
     /** The node the PARENT adopts. */
@@ -100,6 +102,14 @@ export interface PrimitivePlan {
     readonly gestures: readonly ResolvedGesture[];
     /** Live regions this element declares. At most one, and empty for every primitive but `Text`. */
     readonly announcements: readonly ResolvedAnnouncement[];
+    /**
+     * Accessible attributes to write through `Gtk.Accessible.update_property()` and
+     * `update_state()`, decided here and CALLED one layer up — the same split
+     * {@link ResolvedFile} and {@link ResolvedAnnouncement} have, and for the same
+     * reason: the call needs `gi://Gtk` enum members and a `GObject.Value`, and
+     * nothing under `primitives/` imports `gi://`.
+     */
+    readonly accessibility: readonly ResolvedAccessible[];
     /** What a `ref` on this element receives, or null for the widget itself. */
     readonly handle: HandleKind | null;
     /** Where a text child goes, or null when text under this primitive is refused. */

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

@@ -1,5 +1,6 @@
 import { partition, type Partitioned, type StyleProps } from '@gjsify/gtk-host/style';
 import type { StyleTokens } from '@gjsify/gtk-host/style';
+import { type AnimatedValueLike } from '../animated/brand.js';
 import { type ClassGroups, type ClassNameInput } from './classes.js';
 /**
  * A React Native `style` prop.
@@ -21,6 +22,28 @@ interface StyleInputArray extends ReadonlyArray<StyleInput> {
  * exactly like a style that was never written.
  */
 export declare function flattenStyle(style: StyleInput): StyleObject;
+/**
+ * A style → its plain entries and its `Animated.Value`s, split before the partition.
+ *
+ * L2's and not `components.ts`', because TWO readers need this split and one of them
+ * is a PARENT. `Animated.View` needs the animated half to bind; a parent counting its
+ * absolutely positioned children needs to be able to READ an
+ * `<Animated.View className="absolute" style={{ opacity: value }}>` at all, and
+ * `normalise` refuses a non-scalar style value by design (`scalarOnly`). So the raw
+ * style handed to `declaresAbsolute` threw where the parent wanted an answer, the
+ * throw was swallowed as "not absolute", and the child then got the refusal that names
+ * the PARENT for something the parent could not see — #1451, and the reason two
+ * finished features (a 160 ms fade and `absolute`) did not compose.
+ *
+ * Dropping the animated half hides nothing. An `Animated.Value` under a plain `<View>`
+ * is still refused BY NAME when that element resolves its own style, which is the
+ * element that authored it — the parent's read is a question about somebody else's
+ * props and never the place that judges them.
+ */
+export declare function splitAnimatedStyle(style: StyleInput): {
+    readonly plain: StyleObject;
+    readonly animated: Readonly<Record<string, AnimatedValueLike>>;
+};
 /** What one element authored, before any of it has been interpreted. */
 export interface StyleAuthored {
     readonly className?: ClassNameInput;

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

@@ -1,3 +1,4 @@
+import type { AccessibleRoute } from './accessibility.js';
 import type { Orientation, WidgetFacts } from './intents.js';
 /** How a prop's value becomes a GTK value. */
 export type Coercion = 
@@ -29,6 +30,17 @@ export interface PropertyRoute {
     readonly names: readonly string[];
     readonly as: Coercion;
     readonly map?: Readonly<Record<string, string | number | boolean>>;
+    /**
+     * Values this layer recognises and refuses, each with what to do instead.
+     *
+     * A value simply ABSENT from {@link map} already gets a named refusal listing
+     * the known ones, and that is the right answer for a typo. It is the wrong
+     * answer for a real React Native spelling with no GTK member:
+     * `accessibilityRole="keyboardkey"` is not a typo, and "Known: adjustable,
+     * alert, …" tells its author nothing they can act on. A key here answers by
+     * name instead, in the voice every {@link RefusedRoute} uses.
+     */
+    readonly refuses?: Readonly<Record<string, string>>;
     /** Properties that come with this prop being SET at all, whatever its value. */
     readonly also?: Readonly<Record<string, unknown>>;
 }
@@ -144,7 +156,7 @@ export interface GestureRoute {
     /** The `Gtk.GestureClick` signal — `released` for a completed press. */
     readonly signal: string;
 }
-export type PropRoute = PropertyRoute | StylePropertyRoute | EventRoute | RefusedRoute | IgnoredRoute | FileRoute | GestureRoute | AnnounceRoute;
+export type PropRoute = PropertyRoute | StylePropertyRoute | EventRoute | RefusedRoute | IgnoredRoute | FileRoute | GestureRoute | AnnounceRoute | AccessibleRoute;
 /**
  * The imperative handle a `ref` on this primitive receives, instead of the widget.
  *

package/lib/types/primitives/text-metrics.spec.d.ts

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

package/lib/types/prop-table.d.ts

@@ -44,6 +44,35 @@ export declare function acceptsProp(primitive: string, prop: string, variant?: P
  * a consumer's test makes and the message is what it prints when it fails.
  */
 export declare function explainProp(primitive: string, prop: string, variant?: PropVariant): string | null;
+/**
+ * The values (or record keys) this prop refuses by name, each with its reason.
+ *
+ * Empty for most props. `accessibilityRole` is the one that made this necessary: it is
+ * an ACCEPTED property route and a handful of React Native's role names have no GTK
+ * member, each answered with its own sentence — and until #1555 not one of them was
+ * reachable except by rendering it and catching the throw.
+ */
+export declare function propRefusedValues(primitive: string, prop: string, variant?: PropVariant): readonly string[];
+/**
+ * Would `<Primitive prop={value}>` render?
+ *
+ * `false` when the PROP is refused and when this particular VALUE is, which are two
+ * different fixes and therefore two different sentences — see {@link explainPropValue}.
+ */
+export declare function acceptsPropValue(primitive: string, prop: string, value: unknown, variant?: PropVariant): boolean;
+/**
+ * The sentence a render would print for this prop with THIS value.
+ *
+ * `null` when it renders. The subject is built here rather than in `answers.ts`, which
+ * may hold no relative value import (ADR 0039 § 2, and the generator that imports it
+ * under Node type stripping is why) — so the formatter the throw uses lives in
+ * `errors.ts` and both call it.
+ *
+ * A value merely ABSENT from a mapped prop's table is NOT answered here: that is the
+ * "Known: …" a typo gets, it is built from the map at the moment of the throw, and this
+ * surface is about the values the table refuses ON PURPOSE.
+ */
+export declare function explainPropValue(primitive: string, prop: string, value: unknown, variant?: PropVariant): string | null;
 /** Every prop name this primitive's table row carries, sorted. Framework props are not among them. */
 export declare function propNames(primitive: string, variant?: PropVariant): readonly string[];
 /**

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

@@ -0,0 +1,106 @@
+import type { ReactElement, ReactNode } from 'react';
+/** Where an inner level puts what it wants the window's one header bar to show. */
+export interface ChromeSlot {
+    /**
+     * Set the owning header bar's title widget, or `null` to give it back.
+     *
+     * The element needs `slot: 'title'` — it is rendered as a child of the owner's
+     * `AdwHeaderBar`, and that is `Adw.HeaderBar.set_title_widget`.
+     */
+    setTitleWidget(element: ReactElement | null): void;
+}
+/**
+ * What a navigator finds at the level it was rendered.
+ *
+ * There is deliberately no "am I the owner" field: ownership is only ever the answer
+ * to "who claims the window's bar", `useChrome` does that itself, and a navigator that
+ * read it would be tempted to decide the window controls by it — which is the mistake
+ * the header records.
+ */
+export interface Chrome {
+    /** A header bar above already carries the window controls, so this level's must not. */
+    readonly decorated: boolean;
+    /** The enclosing header bar's title slot, or `null` when there is no bar above. */
+    readonly titleSlot: ChromeSlot | null;
+}
+/** What a level publishes to the subtree below it. */
+interface ChromeLevel {
+    /** A navigator above already claimed the window's header bar. */
+    readonly taken: boolean;
+    /** A header bar between the window and here carries the window controls. */
+    readonly decorated: boolean;
+    /** That level's header bar title slot, when the level has a bar at all. */
+    readonly titleSlot: ChromeSlot | null;
+}
+/**
+ * Publish a level to everything a navigator renders below it.
+ *
+ * EVERY navigator has to do this for every screen it renders, including the ones with
+ * no bar to contribute to (`titleSlot: null`): without it a nested navigator reads the
+ * default and believes it is outermost, and its claim on the window's header bar is
+ * then the second one — a refusal, at mount, in an application that was only nesting
+ * two navigators.
+ */
+export declare const provideChromeLevel: (level: ChromeLevel, children: ReactNode) => ReactElement;
+/**
+ * The level below a header bar: whatever else is true, the controls are accounted for.
+ *
+ * `decorated: true` unconditionally, and that is arithmetic rather than a choice — the
+ * bar either carried the controls (because nothing above it had them) or something
+ * above it did.
+ */
+export declare const underHeaderBar: (titleSlot: ChromeSlot | null) => ChromeLevel;
+/** The level below a navigator level that rendered no bar: only ownership changed. */
+export declare const withoutHeaderBar: (decorated: boolean) => ChromeLevel;
+/**
+ * What this navigator finds, and the window claim that goes with being outermost.
+ *
+ * `rendersChrome` is the navigator's own answer to "am I putting a header bar ON SCREEN
+ * right now", and the claim depends on it. A `<Tabs headerShown={false}>`, or a stack
+ * showing a `headerShown: false` screen, renders none, and taking the window's away
+ * would leave the window with NO chrome — an Adwaita window carries no titlebar of its
+ * own, so that is a window that cannot be closed. Which is also why `decorated` is TRUE
+ * in that case: the window's own bar is still there, carrying the controls, and a bar
+ * further down must not carry a second set.
+ *
+ * ON SCREEN, not "somewhere in this navigator": only mapped bars draw, so a claim held
+ * for a bar on a page further down the stack is a claim against nothing. What that
+ * measured, and which pages count, is in `stack.ts` at the call.
+ *
+ * The claim is a layout EFFECT with an undo, so a navigator that unmounts gives the
+ * window its bar back — which is what makes a re-render, a route change and a
+ * hot-reloaded root layout safe rather than one-shot.
+ */
+export declare function useChrome(navigator: string, rendersChrome: boolean): Chrome;
+/** One title slot per header bar, plus whatever has been contributed to each. */
+export interface TitleSlots {
+    /** The widget contributed for this key, or `null` while nothing has been. */
+    titleWidgetFor(key: string): ReactElement | null;
+    /** The slot for this key, with an identity that survives every re-render. */
+    slotFor(key: string): ChromeSlot;
+    /** Drop the slots of every bar this navigator no longer renders. */
+    retain(keys: ReadonlySet<string>): void;
+}
+/**
+ * The contributions a navigator's header bars hold, keyed by bar.
+ *
+ * The slots are CACHED by key for the reason `usePageBindings` records one file over:
+ * a fresh object per render would make the context value change on every commit and
+ * re-run every consumer's effect, which for this consumer means clearing and
+ * re-setting the contribution in a loop.
+ *
+ * Cached and therefore PRUNED, through the one lifecycle `per-route-cache.ts` owns:
+ * the key is a route key, of which React Navigation mints a fresh one per pushed
+ * instance, so an unpruned map grows with the navigation history (#1547). `held` and
+ * `widgets` need no prune of their own — a contributor's effect cleanup clears both on
+ * the way out — and `retain` is the caller's, because only the navigator knows which
+ * bars it still renders.
+ *
+ * A SECOND live contribution to one bar REFUSES. The cleanup in a contributor's
+ * effect clears the slot before it re-runs, so the same contributor re-setting is
+ * never the occupied case — an occupied slot means two navigators are pointing at one
+ * title, and a silent overwrite would show one of them and lose the other with no
+ * message anywhere.
+ */
+export declare function useTitleSlots(navigator: string): TitleSlots;
+export {};

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

@@ -25,7 +25,9 @@ export type RouterErrorCode =
 /** 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';
+ | 'no-route-node'
+/** Two navigators inside one screen both contributing to its header bar's title. */
+ | 'chrome-taken';
 /** A routing input, file name or call this layer cannot answer for, and why. */
 export declare class RouterError extends Error {
     readonly name = "RouterError";

package/lib/types/router/per-route-cache.d.ts

@@ -0,0 +1,21 @@
+/** How many per-route cache entries the process is holding right now. */
+export declare const perRouteCacheEntries: () => number;
+/** A `Map` keyed by route key that is pruned to the pages a navigator still renders. */
+export declare class PerRouteCache<T> {
+    private readonly held;
+    /** The value for `key`, made once and kept — the identity every caller depends on. */
+    getOrCreate(key: string, make: () => T): T;
+    /** Replace what is held for `key`. For values a render recomputes, like screen options. */
+    set(key: string, value: T): void;
+    get(key: string): T | undefined;
+    /**
+     * Drop every key that is not in `keys`. The whole lifecycle, in one call.
+     *
+     * Deleting the key the loop is standing on is defined behaviour for a `Map`
+     * iterator — no snapshot is needed, and taking one would only hide that.
+     */
+    retain(keys: ReadonlySet<string>): void;
+    /** Drop everything. What an unmounting navigator owes the count. */
+    clear(): void;
+    get size(): number;
+}

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

@@ -5,7 +5,12 @@ import { type ScreenDeclaration } from './screens.js';
 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. */
+    /**
+     * `false` renders the screen with no `Adw.HeaderBar`, and so with no back button.
+     *
+     * It also leaves the level below with no title slot to contribute to, so a
+     * navigator inside this screen renders its own bar — see `chrome.ts`.
+     */
     headerShown?: boolean;
     /** `none` turns the transition off for this screen only. */
     animation?: 'default' | 'none';

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

@@ -1,10 +1,24 @@
 import { type ReactElement, type ReactNode } from 'react';
-import type Adw from '@girs/adw-1';
+import Adw from 'gi://Adw?version=1';
 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;
+    /**
+     * The switcher button's icon, as an icon-theme name (`go-home-symbolic`).
+     *
+     * NOT OPTIONAL DECORATION, which is why it is here rather than left to the
+     * application. `Adw.ViewSwitcher` reserves the icon whether or not one is set —
+     * MEASURED, the same five tabs measure 317/647 px with icons and without — and a
+     * page with no `icon-name` draws the icon theme's missing-image glyph in the space
+     * it reserved. So the choice was never "icons or no icons"; it was "your icon or a
+     * broken one".
+     *
+     * A name the theme does not carry draws that same glyph, and nothing says so.
+     * `Gtk.IconTheme.has_icon()` is the check worth running when picking one.
+     */
+    iconName?: string;
 }
 /**
  * Put the stack on the focused page, or leave it alone because that page is not there yet.
@@ -53,8 +67,39 @@ export interface TabsProps {
     children?: ReactNode;
     /** Options for every tab, before its own. */
     screenOptions?: TabScreenOptions;
-    /** `false` drops the header bar, and with it the switcher. */
+    /** `false` drops the header bar, and with it the switcher and the bottom bar. */
     headerShown?: boolean;
+    /**
+     * A persistent bar between the content and the switcher bar — a now-playing strip,
+     * a selection toolbar, an offline notice.
+     *
+     * ## Why a prop rather than a child
+     *
+     * `<Tabs>` reads its children as `<Tabs.Screen>` DECLARATIONS and refuses anything
+     * else by name, so there is no child position to put this in. And an app cannot
+     * wrap `<Tabs>` from outside either: the switcher is created with `slot: 'title'`,
+     * which resolves against the PARENT, so a box placed between a tab layout and the
+     * header bar takes the switcher's slot away and the router refuses it. A consumer
+     * hit exactly that and recorded "no mini player" as a limitation for weeks.
+     *
+     * ## Where it lands, measured
+     *
+     * `Adw.ToolbarView`'s `bottom` slot is an ADDER, so it takes this and the switcher
+     * bar together, and the order decides the stacking. MEASURED on libadwaita 1.9.3 in a
+     * 480x320 window: with two bottom bars added in sequence, the FIRST sits closer to
+     * the content — content at y=0 h=214, first-added at y=217, second-added at y=257.
+     * So this is rendered BEFORE the switcher bar, which puts it above it, which is
+     * where a phone puts a now-playing strip relative to its tab bar.
+     *
+     * Wrapped in a `Gtk.Box` rather than slotted directly, so that a caller can hand
+     * over any node — including a fragment or a component whose root element it does
+     * not control — without having to know that a slot name is involved.
+     *
+     * NOT RENDERED under `headerShown: false`, which drops the whole toolbar view and
+     * has nowhere to put it. Named here rather than worked around, because a navigator
+     * that asked for no chrome getting a bar anyway would be the greater surprise.
+     */
+    bottomBar?: ReactNode;
 }
 /**
  * `expo-router`'s `<Tabs>`: its tabs are the FILES this `_layout` owns.

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

@@ -1,4 +1,5 @@
 import { createElement, mount } from '@gjsify/gtk-host/solid';
+import type { AccessibilityProps } from '../primitives/accessibility.js';
 import type { ClassNameInput } from '../primitives/classes.js';
 import { type TextInputHandle } from '../primitives/handles.js';
 import type { StyleInput } from '../primitives/style.js';
@@ -14,7 +15,7 @@ type HostNode = ReturnType<typeof createElement>;
 export type PrimitiveChild = HostNode | string | number | boolean | null | undefined;
 export type PrimitiveChildren = PrimitiveChild | readonly PrimitiveChildren[];
 /** What every primitive accepts on top of its own props. */
-export interface CommonProps {
+export interface CommonProps extends AccessibilityProps {
     className?: ClassNameInput;
     style?: StyleInput;
     children?: PrimitiveChildren;