@gjsify/react-native 0.45.0 → 0.46.0

package/lib/types/animated/timing.d.ts

@@ -0,0 +1,37 @@
+import { type EasingFunction } from './easing.js';
+import type { AnimatedValue } from './value.js';
+/** What React Native calls an `EndCallback`. */
+export type EndCallback = (result: {
+    readonly finished: boolean;
+}) => void;
+/** `Animated.timing`'s config, as far as this layer answers for it. */
+export interface TimingConfig {
+    readonly toValue: number;
+    readonly duration?: number;
+    readonly easing?: EasingFunction;
+    /**
+     * Accepted and MEANINGLESS, which is a decision rather than an oversight.
+     *
+     * On a phone the flag chooses whether the JavaScript thread interpolates and ships
+     * each frame over the bridge, or the native side owns the whole run. There is no
+     * bridge here: this layer renders in-process onto GTK, `Adw.TimedAnimation` owns
+     * the frame clock either way, and React re-renders for a frame in neither case. So
+     * both values behave identically and the flag is honoured by being ignored — said
+     * out loud here and in the support table, because a config key that is silently
+     * dropped is indistinguishable from one that was misspelled.
+     */
+    readonly useNativeDriver?: boolean;
+}
+/** The handle `Animated.timing` returns. React Native calls it a `CompositeAnimation`. */
+export interface CompositeAnimation {
+    start(callback?: EndCallback): void;
+    stop(): void;
+    reset(): void;
+}
+/**
+ * Animate `value` to `config.toValue` over `config.duration` milliseconds.
+ *
+ * Nothing starts until `.start()` — React Native's own shape, and here it is also
+ * what lets the run pick up a frame clock from whichever view binds the value.
+ */
+export declare function timing(value: AnimatedValue, config: TimingConfig): CompositeAnimation;

package/lib/types/animated/value.d.ts

@@ -0,0 +1,103 @@
+import { ANIMATED_VALUE, type AnimatedValueLike } from './brand.js';
+/**
+ * One place an animated number lands: a widget property this layer writes.
+ *
+ * `widget` is typed `object` rather than `Gtk.Widget` on purpose — see the module
+ * comment. It is here at all because an `Adw.Animation` needs a widget for its frame
+ * clock, and the only widgets this value knows about are the ones bound to it.
+ */
+export interface ValueSink {
+    /** The widget whose frame clock an animation of this value can use. */
+    readonly widget: object;
+    /** Write the number where it belongs. */
+    write(value: number): void;
+}
+/**
+ * The half of a running animation this value drives, implemented in `timing.ts`.
+ *
+ * Three callbacks and no getters: the value tells the run what happened to its
+ * clock, and the run tells the value what the number is. Anything more would put
+ * frame state on both sides.
+ */
+export interface ValueRun {
+    /** A sink arrived and this run has no clock yet — start now. */
+    clockAvailable(widget: object): void;
+    /** The sink that supplied the clock is gone. */
+    clockLost(): void;
+    /** `setValue`, or another animation, took this value over. */
+    interrupted(): void;
+    /**
+     * `resetAnimation`: put the value back to the number this run started from.
+     *
+     * `rewind` and not `reset`, because the handle `Animated.timing` returns has a
+     * PUBLIC `reset()` of its own that routes through the value — two methods called
+     * `reset` calling each other is a stack overflow, and it is one this name avoids
+     * rather than documents.
+     */
+    rewind(): void;
+}
+/**
+ * A number that animates, and the views bound to it.
+ *
+ * The subset ADR 0032's measured application uses — `new Animated.Value(n)`, handed
+ * to `Animated.timing` and read by an `<Animated.View>` style — plus `setValue`,
+ * `__getValue`, `stopAnimation` and `resetAnimation`, which are the four that cost
+ * nothing once the run bookkeeping exists. Everything else on React Native's
+ * `AnimatedValue` is a named refusal in `index.ts`, with its reason.
+ *
+ * The `__`-prefixed methods are React Native's own convention for a node's internals
+ * (`__getValue` is in its public type declarations), and they are how `timing.ts` and
+ * `Animated.View` reach the run and the sinks. They are not part of the surface a
+ * ported application should call.
+ */
+export declare class AnimatedValue implements AnimatedValueLike {
+    #private;
+    readonly [ANIMATED_VALUE]: true;
+    /** Stable per instance. `Animated.View` puts it in an effect's dependency list. */
+    readonly id: number;
+    constructor(value: number);
+    /** The number right now. React Native's own spelling for this read. */
+    __getValue(): number;
+    /**
+     * Jump to a value, stopping whatever was animating it.
+     *
+     * Stopping first is React Native's own behaviour and it is not a detail: a
+     * `setValue` that left the animation running would be overwritten on the next
+     * frame, so the write would appear to do nothing for the rest of the run.
+     */
+    setValue(value: number): void;
+    /**
+     * Stop the running animation where it is; the callback gets the value it stopped at.
+     *
+     * React Native's signature is `stopAnimation(callback?: (value: number) => void)`,
+     * and the value it reports is the one the animation reached — which is why this
+     * cannot be written as `stop(); callback(0)`.
+     */
+    stopAnimation(callback?: (value: number) => void): void;
+    /**
+     * Stop and go back to where the run started.
+     *
+     * `Adw.Animation.reset()` does exactly this on its own side (measured: state
+     * returns to IDLE and `value` to `value-from`, with no `done`), and the run is
+     * what knows the starting number — so the reset is the run's, and this method is
+     * the value's way of asking for it.
+     */
+    resetAnimation(callback?: (value: number) => void): void;
+    /**
+     * Bind a widget property to this value; returns the unbind.
+     *
+     * The sink is written IMMEDIATELY, because a view that only hears about changes
+     * starts out disagreeing with the value — a `new Animated.Value(0)` behind an
+     * `opacity` must make the widget transparent on its first frame, not on the
+     * animation's.
+     */
+    __attach(sink: ValueSink): () => void;
+    /** The widget a new run can take its frame clock from, or null. */
+    __clockWidget(): object | null;
+    /** Take this value over. Any previous run is interrupted, as React Native's is. */
+    __claim(run: ValueRun): void;
+    /** The run finished on its own; nothing to interrupt. */
+    __release(run: ValueRun): void;
+    /** One frame. Called by the run's animation target. */
+    __publish(value: number): void;
+}

package/lib/types/announce.d.ts

@@ -0,0 +1,18 @@
+import Gtk from 'gi://Gtk?version=4.0';
+import type { ResolvedAnnouncement } from './primitives/resolve.js';
+/**
+ * How many elements are currently reporting their content changes to a screen reader.
+ *
+ * `accessibilityLiveRegion="none"` and an absent prop must subscribe to NOTHING, and
+ * both render identically to one that does — only a count tells them apart.
+ */
+export declare const liveRegionWatchCount: () => number;
+/**
+ * Announce `widget`'s own text whenever `announcement.signal` says it changed.
+ *
+ * Returns the unsubscribe. AN EMPTY MESSAGE IS NOT ANNOUNCED: a `Gtk.Label` passes
+ * through `''` on its way between two strings when an application rebuilds its text,
+ * and "say nothing" is what a screen reader should do with it — announcing it would
+ * interrupt the user to say nothing at all.
+ */
+export declare function onLiveRegion(widget: Gtk.Widget, announcement: ResolvedAnnouncement): () => void;

package/lib/types/components.d.ts

@@ -1,14 +1,22 @@
 import { type ReactElement, type ReactNode, type Ref } from 'react';
 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 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 {
     className?: ClassNameInput;
     style?: StyleInput;
     children?: ReactNode;
-    /** The `Gtk.Widget` itself — the host's `getPublicInstance` hands back the real widget. */
+    /**
+     * The `Gtk.Widget` itself — except where React Native documents an imperative
+     * handle, which is `<TextInput>` and its {@link TextInputHandle}.
+     *
+     * `unknown` rather than `Gtk.Widget`, because the two values are not one type and
+     * the primitive decides which arrives. A component that has a handle declares it:
+     * `useRef<TextInput>(null)` resolves to the handle's members.
+     */
     ref?: Ref<unknown>;
     testID?: string;
 }
@@ -51,6 +59,15 @@ export interface TextProps extends CommonProps {
     numberOfLines?: number;
     ellipsizeMode?: 'head' | 'middle' | 'tail';
     selectable?: boolean;
+    /**
+     * Announce this label's text when it changes — `Gtk.Accessible.announce()`.
+     *
+     * Declared on `Text` ALONE, and that is the whole of what GTK can answer: the
+     * announcement is imperative, so the layer needs both the moment and the message,
+     * and a `Gtk.Label` is the one widget whose content is a property. Every other
+     * primitive refuses the prop by name.
+     */
+    accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
 }
 export declare function Text(props: TextProps): ReactElement;
 /** What React Native hands a `Pressable`'s function child. */
@@ -92,7 +109,7 @@ export interface ActivityIndicatorProps extends CommonProps {
     hidesWhenStopped?: boolean;
 }
 export declare function ActivityIndicator(props: ActivityIndicatorProps): ReactElement;
-export interface TextInputProps extends CommonProps {
+export interface TextInputProps extends Omit<CommonProps, 'ref'> {
     value?: string;
     defaultValue?: string;
     placeholder?: string;
@@ -104,6 +121,29 @@ export interface TextInputProps extends CommonProps {
     maxLength?: number;
     secureTextEntry?: boolean;
     keyboardType?: 'default' | 'email-address' | 'phone-pad' | 'number-pad' | 'numeric' | 'decimal-pad' | 'url';
+    /** A declared no-op: there is no autofill service on a GTK desktop. `keyboardType` is the hint that lands. */
+    autoComplete?: string;
+    /** `autoComplete`'s iOS spelling, and the same absent addressee. */
+    textContentType?: string;
+    /** A declared no-op: each widget has one Return behaviour, and `multiline` picks the widget. */
+    submitBehavior?: 'submit' | 'blurAndSubmit' | 'newline';
+    ref?: Ref<TextInputHandle>;
+}
+/**
+ * The INSTANCE type, because in React Native `TextInput` is a class.
+ *
+ * `useRef<TextInput>(null)` and `passwordRef.current?.focus()` are ordinary React
+ * Native code, and both were broken here: the name was a function, so it was a value
+ * and not a type, and the ref carried the bare `Gtk.Widget`. An interface merges with
+ * the function declaration below — they occupy different declaration spaces — so the
+ * name means the component in an expression and the handle in a type position,
+ * exactly as the class does upstream.
+ *
+ * What it does NOT copy is React Native's `TextInput extends React.Component`: the
+ * component here is a function, and nothing may read `props`/`state`/`setState` off
+ * a ref. Those are not part of the ref contract upstream either.
+ */
+export interface TextInput extends TextInputHandle {
 }
 export declare function TextInput(props: TextInputProps): ReactElement;
 export interface SwitchProps extends CommonProps {
@@ -230,4 +270,43 @@ export interface StatusBarProps {
  * different question and refuse by name — see `StatusBarStatics`.
  */
 export declare function StatusBar(_props: StatusBarProps): null;
+/** A `style` prop that may carry `Animated.Value`s. */
+export type AnimatedStyleInput = StyleInput | Readonly<Record<string, unknown>>;
+export interface AnimatedViewProps extends Omit<ViewProps, 'style'> {
+    style?: AnimatedStyleInput;
+}
+/**
+ * A `View` whose animated style entries drive GTK widget properties directly.
+ *
+ * NO RE-RENDER PER FRAME, and that is the design rather than an optimisation. An
+ * `Animated.Value` behind an `opacity` could have been React state, and then a 300 ms
+ * fade would be ~18 reconciler passes over the subtree for a property GTK can
+ * interpolate itself. So the value writes `Gtk.Widget:opacity` through the sink bound
+ * below, `Adw.TimedAnimation` owns the frame clock (`animated/timing.ts`), and React
+ * sees exactly two commits: the mount and the unmount.
+ *
+ * THE FIRST FRAME IS RENDERED, NOT BOUND. The sink is attached in an effect, which
+ * runs after the commit — so the initial number is ALSO written as a widget property
+ * in the render itself. Without it a `new Animated.Value(0)` behind an opacity paints
+ * one frame fully opaque before the effect makes it transparent, which is a flash on
+ * every mount of every faded-in screen.
+ */
+export declare function AnimatedView(props: AnimatedViewProps): ReactElement;
+/**
+ * A themed icon — `Gtk.Image` with an `icon-name`.
+ *
+ * NOT a React Native name and not exported from the package root: it is the widget
+ * ADR 0036's `@expo/vector-icons` surface renders, and it lives here rather than in
+ * that surface for the reason ADR 0032 § 1 gives — a component that named `GtkImage`
+ * itself would put a widget name in L3. `name` is a GTK icon name by the time it
+ * arrives; the Ionicons vocabulary is translated in `surfaces/icon-map.ts`.
+ */
+export interface IconProps extends Omit<CommonProps, 'children'> {
+    /** A GTK icon name, e.g. `go-home-symbolic`. */
+    name: string;
+    /** `Gtk.Image:pixel-size`, in pixels. */
+    size?: number;
+    color?: string;
+}
+export declare function Icon(props: IconProps): ReactElement;
 export {};

package/lib/types/generated/unsupported-async-storage.d.ts

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

package/lib/types/generated/unsupported-expo-audio.d.ts

@@ -0,0 +1,4 @@
+export declare const useAudioPlayer: never;
+export declare const useAudioRecorder: never;
+export declare const AudioModule: never;
+export declare const setAudioModeAsync: never;

package/lib/types/generated/unsupported-expo-constants.d.ts

@@ -0,0 +1,2 @@
+export declare const ExecutionEnvironment: never;
+export declare const AppOwnership: never;

package/lib/types/generated/unsupported-expo-font.d.ts

@@ -0,0 +1,4 @@
+export declare const loadAsync: never;
+export declare const unloadAsync: never;
+export declare const unloadAllAsync: never;
+export declare const FontDisplay: never;

package/lib/types/generated/unsupported-expo-image.d.ts

@@ -0,0 +1,3 @@
+export declare const Image: never;
+export declare const ImageBackground: never;
+export declare const useImage: never;

package/lib/types/generated/unsupported-expo-linking.d.ts

@@ -0,0 +1,4 @@
+export declare const createURL: never;
+export declare const addEventListener: never;
+export declare const openSettings: never;
+export declare const sendIntent: never;

package/lib/types/generated/unsupported-expo-splash-screen.d.ts

@@ -0,0 +1,5 @@
+export declare const preventAutoHideAsync: never;
+export declare const hideAsync: never;
+export declare const hide: never;
+export declare const preventAutoHide: never;
+export declare const setOptions: never;

package/lib/types/generated/unsupported-expo-status-bar.d.ts

@@ -0,0 +1,5 @@
+export declare const setStatusBarStyle: never;
+export declare const setStatusBarHidden: never;
+export declare const setStatusBarBackgroundColor: never;
+export declare const setStatusBarTranslucent: never;
+export declare const setStatusBarNetworkActivityIndicatorVisible: never;

package/lib/types/generated/unsupported-expo-system-ui.d.ts

@@ -0,0 +1,2 @@
+export declare const setBackgroundColorAsync: never;
+export declare const getBackgroundColorAsync: never;

package/lib/types/generated/unsupported-expo-video.d.ts

@@ -0,0 +1,3 @@
+export declare const VideoView: never;
+export declare const useVideoPlayer: never;
+export declare const VideoContentFit: never;

package/lib/types/generated/unsupported-expo-web-browser.d.ts

@@ -0,0 +1,6 @@
+export declare const dismissBrowser: never;
+export declare const openAuthSessionAsync: never;
+export declare const dismissAuthSession: never;
+export declare const maybeCompleteAuthSession: never;
+export declare const warmUpAsync: never;
+export declare const coolDownAsync: never;

package/lib/types/generated/unsupported-nativewind.d.ts

@@ -0,0 +1,5 @@
+export declare const cssInterop: never;
+export declare const remapProps: never;
+export declare const styled: never;
+export declare const vars: never;
+export declare const useColorScheme: never;

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

@@ -0,0 +1,10 @@
+export declare const Gesture: never;
+export declare const GestureDetector: never;
+export declare const PanGestureHandler: never;
+export declare const TapGestureHandler: never;
+export declare const LongPressGestureHandler: never;
+export declare const PinchGestureHandler: never;
+export declare const Swipeable: never;
+export declare const ScrollView: never;
+export declare const Directions: never;
+export declare const State: never;

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

@@ -0,0 +1,4 @@
+export declare const SafeAreaInsetsContext: never;
+export declare const SafeAreaFrameContext: never;
+export declare const withSafeAreaInsets: never;
+export declare const SafeAreaConsumer: never;

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

@@ -0,0 +1 @@
+export declare const WebView: never;

package/lib/types/generated/{unsupported-exports.d.ts → unsupported-react-native.d.ts}

@@ -4,8 +4,6 @@ export declare const AppState: never;
 export declare const PixelRatio: never;
 export declare const PlatformColor: never;
 export declare const AccessibilityInfo: never;
-export declare const Animated: never;
-export declare const Easing: never;
 export declare const LayoutAnimation: never;
 export declare const InteractionManager: never;
 export declare const useAnimatedValue: never;

package/lib/types/generated/unsupported-vector-icons.d.ts

@@ -0,0 +1,11 @@
+export declare const MaterialIcons: never;
+export declare const MaterialCommunityIcons: never;
+export declare const FontAwesome: never;
+export declare const Feather: never;
+export declare const AntDesign: never;
+export declare const Entypo: never;
+export declare const Octicons: never;
+export declare const SimpleLineIcons: never;
+export declare const createIconSet: never;
+export declare const createIconSetFromFontello: never;
+export declare const createIconSetFromIcoMoon: never;

package/lib/types/index.d.ts

@@ -9,18 +9,22 @@ export type { FlatListProps, ListRenderItemInfo, ListSeparators, ListSlot, Secti
 export { Alert, Appearance, Dimensions, Keyboard, Linking, Platform, Share } from './apis/index.js';
 export type { AlertButton, AlertOptions, AppearancePreferences, ColorSchemeName, DimensionKey, DimensionsPayload, DisplayMetrics, PlatformOS, PlatformSelectSpec, ShareAction, ShareContent, } from './apis/index.js';
 export { useColorScheme, useWindowDimensions } from './hooks.js';
+export { Animated, Easing } from './animated/index.js';
+export type { CompositeAnimation, EasingFunction, EndCallback, TimingConfig } from './animated/index.js';
 export { StyleSheet } from './stylesheet.js';
 export type { NamedStyles } from './stylesheet.js';
 export { configureStyle, resetStyleConfig, styleConfig } from './style-config.js';
 export type { StyleConfig } from './style-config.js';
 export * as primitives from './primitives/index.js';
 export { PrimitiveError } from './primitives/errors.js';
+export type { TextInputHandle } from './primitives/handles.js';
 /**
  * React 19 batches every update on its own, so this is the identity call it already
  * is upstream — kept because application code and libraries still wrap in it, and an
  * absent export would refuse something that costs nothing to honour.
  */
 export declare function unstable_batchedUpdates<T, R>(callback: (argument: T) => R, argument: T): R;
-export * from './generated/unsupported-exports.js';
+export * from './generated/unsupported-react-native.js';
 export { OWN_EXPORT_NAMES, SUPPORT_TABLE, SUPPORTED_NAMES, explainUnsupported, isImportable, isOwnExport, type SupportEntry, type SupportStatus, type SupportTier, } from './support-table.js';
+export { PRIMITIVE_VARIANTS, acceptsProp, explainProp, propAnswer, propNames, propTable, type PropAnswer, type PropStatus, type PropVariant, } from './prop-table.js';
 export { UnsupportedError } from './unsupported.js';

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

@@ -0,0 +1,69 @@
+import type { PrimitiveSpec } from './table.js';
+/**
+ * What this layer does about a prop.
+ *
+ * The first six are ACCEPTED — the prop reaches GTK, by the route the name says.
+ * `ignored` is accepted too and reaches nothing, deliberately. Only `refused` and
+ * `unknown` throw, and they are separate because they have different fixes: a
+ * refusal is a decision with a reason, an unknown prop is a name nobody recognised
+ * (usually a typo, sometimes a prop this table has not grown yet).
+ */
+export type PropStatus = 
+/** Becomes one or more GTK widget properties. */
+'property'
+/** Binds a GObject signal. */
+ | 'event'
+/** Joins the normalised style record and goes through the style partition. */
+ | 'style'
+/** Becomes a `Gio.File` on a widget property. */
+ | 'file'
+/** Binds a `Gtk.GestureClick` signal through a controller. */
+ | 'gesture'
+/** Calls `Gtk.Accessible.announce()` when a signal reports the content changed. */
+ | 'announcement'
+/** Recognised and deliberately without effect on a desktop window. */
+ | 'ignored'
+/** Refused by name, with a reason. Throws a `PrimitiveError` when rendered. */
+ | 'refused'
+/** The framework's own (`children`, `key`, `ref`, `className`, `style`); never reaches a widget. */
+ | 'framework'
+/** Not a name this primitive carries at all. Throws a `PrimitiveError` when rendered. */
+ | 'unknown';
+/** What this layer does about one prop of one primitive. */
+export interface PropAnswer {
+    readonly primitive: string;
+    readonly prop: string;
+    readonly status: PropStatus;
+    /**
+     * The reason, for every status that has one.
+     *
+     * For `refused` and `unknown` it is the DETAIL of the `PrimitiveError` the
+     * resolver throws — the same string, not a paraphrase. For `ignored` it is why
+     * the no-op is the right answer. Empty for a prop that simply lands.
+     */
+    readonly why: string;
+    /** What it reaches on the GTK side: property names, a signal, or nothing. */
+    readonly gtk: readonly 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;
+/** The detail of the refusal a prop no primitive row carries gets. `resolve.ts` throws exactly this. */
+export declare const unknownPropDetail: (spec: PrimitiveSpec) => string;
+/** The detail of the refusal an unknown PRIMITIVE gets. `resolve.ts` throws exactly this. */
+export declare const unknownPrimitiveDetail: (names: readonly string[]) => string;
+/**
+ * What `primitive` does about `prop`.
+ *
+ * `frameworkProps` and `spec` arrive as arguments rather than being imported — see
+ * the header: this module is loaded by a Node script that cannot follow a `./x.js`
+ * specifier into a `.ts` file.
+ */
+export declare function answerFor(primitive: string, spec: PrimitiveSpec, prop: string, frameworkProps: ReadonlySet<string>): PropAnswer;
+/**
+ * The props a primitive names, in the order a reader wants them: accepted first.
+ *
+ * Sorted within a status so the generated document is stable — an object's key order
+ * is the table's authoring order, which is not a promise anyone should read a diff
+ * against.
+ */
+export declare function propNamesOf(spec: PrimitiveSpec): readonly string[];

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

@@ -0,0 +1,52 @@
+/** What this layer does about one divergence. */
+export type DefaultVerdict = 
+/** The two disagree and the primitive writes React Native's value. */
+'normalised'
+/** Checked, and the two already agree. Recorded so the sweep is a sweep. */
+ | 'agrees'
+/** They disagree and GTK's is KEPT on purpose — the reason says why. */
+ | 'kept'
+/**
+ * Not a default question at all: the table writes this for ONE primitive's own
+ * layout.
+ *
+ * The distinction is worth a verdict because the closure check below cannot make
+ * it — every `widgetProps` entry looks the same from there — and conflating the
+ * two would let a real divergence hide behind "well, some primitive wanted it".
+ */
+ | 'primitive';
+export interface DefaultRow {
+    /** The GType a primitive names. */
+    readonly gtype: string;
+    /** The property, in GTK's own kebab spelling. */
+    readonly property: string;
+    /** What a freshly constructed widget reports. Re-measured by the spec. */
+    readonly gtk: string | number | boolean;
+    /** React Native's own default, in words. */
+    readonly reactNative: string;
+    /** Where that is written down, or how it was observed. */
+    readonly source: string;
+    readonly verdict: DefaultVerdict;
+    /** The value the primitive writes. Present exactly when the verdict is `normalised`. */
+    readonly normalisedTo?: string | number | boolean;
+    readonly reason: string;
+}
+/**
+ * Every (widget, property) pair whose default this layer has looked at.
+ *
+ * ORDERED BY WIDGET, and the `agrees` rows are not padding: "we checked and they
+ * match" and "nobody has looked" are different states, and only one of them is safe.
+ * A property absent from this file is in the second state.
+ */
+export declare const DEFAULT_ROWS: readonly DefaultRow[];
+/** Every row this layer writes a value for, as `(gtype, property)`. Read by the spec. */
+export declare const NORMALISED_DEFAULTS: readonly DefaultRow[];
+/**
+ * The row for one `(gtype, property)`, or undefined.
+ *
+ * FALLS BACK TO `GtkWidget`, and that is not a convenience: `hexpand`, `opacity` and
+ * `halign` are `Gtk.Widget`'s properties, so a primitive writing one on a
+ * `Gtk.ScrolledWindow` is writing the same property this ledger records once. Keying
+ * a row per widget that inherits them would be twenty copies of one fact.
+ */
+export declare const defaultRowFor: (gtype: string, property: string) => DefaultRow | undefined;

package/lib/types/primitives/defaults.spec.d.ts

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

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

@@ -1,3 +1,12 @@
+/**
+ * The sentence, without throwing it.
+ *
+ * `@gjsify/react-native/prop-table` has to hand a consumer the message a render WOULD
+ * have thrown, and ADR 0039 § 1 says it is the same string rather than a paraphrase.
+ * Two template literals that happen to agree are not that: the format is here once and
+ * both the throw and the static answer are built from it.
+ */
+export declare const primitiveErrorMessage: (primitive: string, subject: string, detail: string) => 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/handles.d.ts

@@ -0,0 +1,56 @@
+import type { HandleKind } from './table.js';
+/**
+ * The imperative handle a `<TextInput ref>` receives.
+ *
+ * React Native's own member list, with every one of them answered — five over GTK
+ * and four refused by name. `widget` is the one addition, and it is not decoration:
+ * the ref used to BE the widget, so a port that already reached for `Gtk.Entry` API
+ * through it keeps working by spelling `ref.current.widget` — and it is also the way
+ * out of every refusal below.
+ */
+export interface TextInputHandle {
+    /** `Gtk.Widget.grab_focus()`. */
+    focus(): void;
+    /**
+     * Give up the focus — `Gtk.Root.set_focus(null)`, and ONLY when this widget holds it.
+     *
+     * The guard is the whole of the correctness here: `set_focus(null)` unsets the
+     * root's focus widget whoever it is, so an unguarded `blur()` on an unfocused
+     * input would take the focus away from whatever really had it.
+     */
+    blur(): void;
+    /** Remove all text. `Gtk.Editable.set_text('')`, or the buffer's own for a multiline input. */
+    clear(): void;
+    /**
+     * Is this the widget its root delivers keys to?
+     *
+     * `Gtk.Widget.is_focus()` and NOT `has-focus`: the latter is the GLOBAL input
+     * focus and is false whenever the window is not the compositor's active one
+     * (MEASURED on gtk 4.22.4 — a mapped, presented window that the compositor never
+     * activated reports `has_focus` false for the widget `grab_focus()` just
+     * returned true for). React Native's `isFocused()` is the per-application
+     * question, which is `is_focus()`.
+     */
+    isFocused(): boolean;
+    /** `Gtk.Editable.select_region(start, end)`, or `Gtk.TextBuffer.select_range` for a multiline input. */
+    setSelection(start: number, end: number): void;
+    /** The `Gtk.Entry` or `Gtk.TextView` itself — everything this handle does not answer. */
+    readonly widget: unknown;
+    /** Refused by name. GTK measures on allocation; see the message. */
+    measure(callback: unknown): never;
+    /** Refused by name — see `measure`. */
+    measureInWindow(callback: unknown): never;
+    /** Refused by name — see `measure`. */
+    measureLayout(relativeTo: unknown, onSuccess: unknown, onFail?: unknown): never;
+    /** Refused by name: the widget is right here, and every GTK property is settable on it. */
+    setNativeProps(props: object): never;
+}
+/**
+ * The handle a plan asks for, or the widget itself.
+ *
+ * `null` for `kind` is the ordinary case and is not an omission: React Native gives
+ * an imperative handle only to the components that document one, and every other
+ * primitive here hands a `ref` the `Gtk.Widget` — which is what it did before this
+ * file existed and what a port that reaches for GTK API relies on.
+ */
+export declare function createHandle(kind: HandleKind | null, widget: unknown, tag: string): unknown;

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

@@ -1,11 +1,17 @@
+export { answerFor, isAccepted, propNamesOf, unknownPrimitiveDetail, unknownPropDetail } from './answers.js';
+export type { PropAnswer, PropStatus } from './answers.js';
 export { splitVariants } from './classes.js';
+export { createHandle } from './handles.js';
+export type { TextInputHandle } from './handles.js';
+export { DEFAULT_ROWS, NORMALISED_DEFAULTS, defaultRowFor } from './defaults.js';
+export type { DefaultRow, DefaultVerdict } from './defaults.js';
 export type { ClassGroups, ClassNameInput } from './classes.js';
 export { PrimitiveError } from './errors.js';
 export { resolveIntent } from './intents.js';
 export type { ChildContext, ChildFacts, IntentInput, IntentResolution, Orientation, WidgetFacts } from './intents.js';
 export { declaresAbsolute, resolvePrimitive } from './resolve.js';
-export type { PrimitiveContext, PrimitivePlan, PrimitiveProps, ResolvedEvent, ResolvedFile, ResolvedGesture, WidgetNode, } from './resolve.js';
+export type { PrimitiveContext, PrimitivePlan, PrimitiveProps, ResolvedAnnouncement, ResolvedEvent, ResolvedFile, ResolvedGesture, WidgetNode, } from './resolve.js';
 export { flattenStyle, mintClass, normalise, variantDeclarations } from './style.js';
 export type { ClassNameSink, StyleAuthored, StyleInput, StyleObject } from './style.js';
 export { FRAMEWORK_PROPS, PRIMITIVE_NAMES, PRIMITIVES } from './table.js';
-export type { Coercion, ContentSpec, EventRoute, FileRoute, GestureRoute, IgnoredRoute, NodeKind, PrimitiveSpec, PropRoute, PropertyRoute, RefusedRoute, StylePropertyRoute, } from './table.js';
+export type { AnnounceRoute, Coercion, ContentSpec, EventRoute, FileRoute, GestureRoute, HandleKind, IgnoredRoute, NodeKind, PrimitiveSpec, PropRoute, PropertyRoute, RefusedRoute, StylePropertyRoute, } from './table.js';