@gjsify/gtk-host 0.43.0 → 0.45.0

package/lib/types/policies.d.ts

@@ -52,6 +52,17 @@ export declare const makeDetachedContainer: () => Gtk.Widget;
  */
 export declare function unhandledPolicy(policy: never): never;
 export declare function setterSlotOf(parent: HostElement, child: HostElement): string | null;
+/**
+ * The slots this policy fills with an ADDER, by slot name.
+ *
+ * `set_`-prefixed or not is the whole distinction, and TWO decisions turn on it,
+ * which is why the predicate is here once rather than spelled out at each. A
+ * setter-backed slot is emptied by writing `null` back through itself, so
+ * `policyProblems()` lets such a policy name no `remove`; and it holds one child,
+ * so `rotateTail` returns before touching it — a policy with no adder slot at all
+ * has no order to pay for, which is what `reorderMode()` reports.
+ */
+export declare function adderSlots(policy: ChildPolicy): string[];
 /** Every one-child slot this policy has, by setter name — `single` has exactly one. */
 export declare function setterSlots(policy: ChildPolicy): string[];
 /**

package/lib/types/probe.d.ts

@@ -1,4 +1,5 @@
 import Adw from 'gi://Adw?version=1';
+import Gtk from 'gi://Gtk?version=4.0';
 /** Record one assertion. A `false` is a finding; nothing else is. */
 export type ProbeCheck = (what: string, ok: boolean) => void;
 /** What a showcase gives the harness. */
@@ -13,8 +14,28 @@ export interface HostProbe<T> {
      * and the exact getters, never the host's own bookkeeping, which would agree
      * with itself while the window is wrong. Return whatever belongs in the result
      * line; the harness adds the failure list and the diagnostic count.
+     *
+     * MAY BE ASYNC, and one adapter forces it: Vue flushes render jobs on a
+     * microtask, so an assertion after a click has to `await nextTick()` or it reads
+     * the pre-patch tree. Without this the Vue showcase hand-rolled the whole
+     * harness, and the copy carried the pre-`describeLogRecord` collector bug with
+     * it — a log record with no `MESSAGE` counted as a diagnostic and then described
+     * as the empty string.
      */
-    assert(ui: T, check: ProbeCheck): Record<string, unknown>;
+    assert(ui: T, check: ProbeCheck): Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Release what the assertions built, before the diagnostics are counted.
+     *
+     * ORDER IS THE POINT. Teardown is exactly where GTK reports a mis-parented tree
+     * — `Finalizing GtkLabel …, but it still has children left` arrives at finalize,
+     * at exit 0 (ADR 0027 § Context). A probe that counts diagnostics and THEN tears
+     * down cannot see the one class of defect that only surfaces there, which is
+     * what both hand-written probes did.
+     *
+     * Optional because a probe that owns nothing has nothing to release; the
+     * harness's own `build` result is reachable only from here.
+     */
+    teardown?(ui: T): void;
     /** Prefix of the machine-readable result line. Default `PROBE`. */
     label?: string;
 }
@@ -34,6 +55,15 @@ export declare function probeEnabled(): boolean;
 /**
  * Run the showcase's assertions once and return the process exit code.
  *
+ * **The probe always builds HEADLESS, in both paths.** It is handed `null` rather
+ * than the `GApplication`, for two reasons that point the same way. It makes the two
+ * paths return the same verdict about the same tree — a probe whose GUI run differs
+ * from its headless run is two probes. And it keeps the GUI path from constructing
+ * and (now that `teardown` exists) destroying an `Adw.ApplicationWindow` INSIDE
+ * `activate`, which is the exact neighbourhood of the segfault recorded on
+ * `runHostProbeApp` below. Nothing a probe asserts needs an application; `present`
+ * gets the real one.
+ *
  * The diagnostics gate is reset first and asserted last, and both halves are the
  * harness's rather than the showcase's. Reset, because in the GUI path this runs
  * from `activate` — AFTER Adw startup, where a session-bus, portal, theme or a11y
@@ -42,7 +72,7 @@ export declare function probeEnabled(): boolean;
  * failure mode is exit 0: a mis-parented widget floods `Gtk-WARNING` and the
  * process still succeeds.
  */
-export declare function runHostProbe<T>(probe: HostProbe<T>, app?: Adw.Application | null): number;
+export declare function runHostProbe<T>(probe: HostProbe<T>): Promise<number>;
 /**
  * The whole `main` of a gtk-host showcase.
  *
@@ -56,3 +86,51 @@ export declare function runHostProbe<T>(probe: HostProbe<T>, app?: Adw.Applicati
  * and hangs a view load on its spinner (the class `@gjsify/adwaita-app` documents).
  */
 export declare function runHostProbeApp<T>(probe: HostProbeApp<T>): Promise<void>;
+/**
+ * Rasterise one widget. `@gjsify/devtools`' `captureWidgetPng` has this shape;
+ * `null` means the widget has no renderer or no size yet, never "the image is empty".
+ */
+export type CaptureWidget = (widget: Gtk.Widget) => Uint8Array | null;
+/** What a picture of a subtree is worth, in numbers a `check` can read. */
+export interface ShotEvidence {
+    /**
+     * STRICT descendants of the container in the REAL GTK tree.
+     *
+     * The decisive number, and the cheapest. `0` is not "a small tree": it is a
+     * container nothing was rendered into, which is what a refused render, an
+     * unmounted root and a component that returned `null` all look like from here.
+     */
+    widgets: number;
+    width: number;
+    height: number;
+    /** PNG byte count, `0` when `capture` produced none. */
+    bytes: number;
+}
+/**
+ * Count what a shot of `container` would be a picture OF.
+ *
+ * Reads the real GTK tree (`get_first_child`/`get_next_sibling`) rather than any
+ * host bookkeeping — the shadow tree would agree with itself here, which is the
+ * whole reason `conformance/` exists.
+ */
+export declare function shotEvidence(container: Gtk.Widget, capture: CaptureWidget): ShotEvidence;
+/**
+ * Why a shot of this evidence would be blank — or `null` when it would not.
+ *
+ * Ordered by what a reader can act on. "Nothing was rendered" and "the renderer had
+ * no surface yet" are different bugs with the same photograph, and a message that
+ * cannot tell them apart sends the reader back to guessing — the state
+ * `describeLogRecord` exists to end one layer down.
+ *
+ * A NON-EMPTY PNG IS NOT PROOF, which is why byte count is the LAST question rather
+ * than the only one: a window with a refused tree still rasterises to several KB of
+ * perfectly valid background.
+ */
+export declare function blankReason(evidence: ShotEvidence): string | null;
+/**
+ * Record "this actually rendered" as a probe check, named.
+ *
+ * Takes the evidence rather than the widget so a caller that already shot it does
+ * not rasterise twice, and so the reason lands in the failure list verbatim.
+ */
+export declare function checkRendered(check: ProbeCheck, what: string, evidence: ShotEvidence): void;

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

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

package/lib/types/props.d.ts

@@ -53,10 +53,13 @@ export declare function coerce(spec: GObject.ParamSpec, value: unknown, tag: str
  * leaves behind, not what the ParamSpec declares.
  *
  * The two disagree far too often to treat the ParamSpec as an approximation.
- * Measured on gjs 1.88.1 / GTK 4.22.4 / Adw 1.10 across the 26 shipped
- * descriptors: 953 scalar properties are both readable and writable, and
- * **104 of them disagree** — 78 once construct-only `css-name` is set aside.
- * Twelve property names carry it, four of them behavioural:
+ * Measured on gjs 1.88.1 / GTK 4.22.4 / libadwaita 1.9.3, one probe per row, over
+ * the curated descriptors as this table ships them — 27 of them at the time of the
+ * measurement, so the totals move when a row joins: 981 scalar properties are both
+ * readable and writable, and **107 of them disagree** — 80 once construct-only
+ * `css-name` is set aside. Twelve property names carry it, four of them
+ * behavioural, and those four are pinned BY NAME in `props.spec.ts` because a name
+ * is what survives a re-count:
  *
  *     GtkWindow.visible                 spec=true   constructed=false
  *     AdwActionRow.activatable          spec=true   constructed=false

package/lib/types/signals.d.ts

@@ -18,9 +18,11 @@ export declare function parseEventProp(prop: string, aliases?: Readonly<Record<s
 export declare const toSignalName: (prop: string, aliases?: Readonly<Record<string, string>>) => string;
 /** An event prop is `on:` + a raw signal name, or `on` + an uppercase letter. */
 export declare function isEventProp(prop: string): boolean;
-export declare const beginHostWrite: () => void;
+export declare const beginHostWrite: (target?: object | null) => void;
 export declare const endHostWrite: () => void;
 export declare const inHostWrite: () => boolean;
+/** Is this object one whose property the host is writing at this instant? */
+export declare const isHostWriteTarget: (o: object) => boolean;
 export declare function setHandler(el: HostElement, prop: string, next: ((...args: unknown[]) => unknown) | null): void;
 /** Disconnect every handler on a node. The only place a handler dies. */
 export declare function clearHandlers(el: HostElement): void;

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

@@ -0,0 +1,6 @@
+/** A utility class, property or combination this vocabulary cannot answer for, and why. */
+export declare class UnknownUtilityError extends Error {
+    readonly name = "UnknownUtilityError";
+    readonly utility: string;
+    constructor(utility: string, detail: string);
+}

package/lib/types/style/gtk-css.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Property names GTK4 accepts in a stylesheet, with a value that parses.
+ *
+ * The value matters: `border-radius: 8px` and `border-radius: 9999px` both parse,
+ * but a property is only provably present when some value for it is accepted.
+ */
+export declare const GTK_CSS_PROBES: ReadonlyArray<readonly [property: string, value: string]>;
+/**
+ * Property names GTK4 REFUSES, and the reason each one is here.
+ *
+ * Most of them are the layout model the web has and GTK does not — there is no
+ * `display: flex`, no absolute positioning, no intrinsic `width`. They must become
+ * widget selection and widget properties, which is the layout half.
+ *
+ * Two groups are not that, and both are here because a reader would assume the
+ * opposite. `text-align` is not about layout at all: it is the property most likely
+ * to be grouped with `color` and `font-size` by anyone reading a Tailwind `text-*`
+ * vocabulary, and GTK drops it in silence. The four logical spacings ARE spacing,
+ * whose physical spellings sit in the accepted table three lines up — the refusal
+ * is per NAME, not per concept, and that is the asymmetry `layout.ts` is built on.
+ */
+export declare const NOT_GTK_CSS: ReadonlyArray<readonly [property: string, value: string]>;
+/** The property names of {@link GTK_CSS_PROBES}, for a membership test. */
+export declare const GTK_CSS_PROPERTIES: ReadonlySet<string>;

package/lib/types/style/gtk-css.spec.d.ts

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

package/lib/types/style/gtk-props.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Properties GTK installs, with the GType of their value.
+ *
+ * `GtkWidget` rows are the universal set — every widget in the table inherits
+ * them, which is what lets `layout.ts` emit them without knowing the tag.
+ */
+export declare const GTK_WIDGET_PROPERTY_PROBES: ReadonlyArray<readonly [gtype: string, property: string, valueType: string]>;
+/**
+ * Properties the class does NOT install, and the claim each one carries.
+ *
+ * Without this direction the table above could name every property in GTK and
+ * still pass — and every routing decision in `layout.ts` rests on an absence
+ * rather than on a presence.
+ */
+export declare const NOT_GTK_WIDGET_PROPERTIES: ReadonlyArray<readonly [gtype: string, property: string]>;
+/**
+ * The property NAMES of {@link GTK_WIDGET_PROPERTY_PROBES}, for a membership test.
+ *
+ * NAMES ONLY, deliberately weaker than the table: L1 does not know which widget a
+ * class list will land on, so the strongest guard it can run is "GTK installs a
+ * property by this name SOMEWHERE in the vocabulary". `orientation` passes it on
+ * an element that turns out to be a `Gtk.Label`, and refusing that is L2's job,
+ * with the tag in hand. Reading this set as "every widget has these" is the one
+ * mistake it invites, and `GTK_WIDGET_PROPERTY_PROBES` is the table that answers
+ * the per-class question.
+ */
+export declare const GTK_WIDGET_PROPERTIES: ReadonlySet<string>;

package/lib/types/style/gtk-props.spec.d.ts

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

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

@@ -0,0 +1,13 @@
+export { GTK_CSS_PROBES, GTK_CSS_PROPERTIES, NOT_GTK_CSS } from './gtk-css.js';
+export { GTK_WIDGET_PROPERTIES, GTK_WIDGET_PROPERTY_PROBES, NOT_GTK_WIDGET_PROPERTIES } from './gtk-props.js';
+export { MINIMAL_TOKENS, lookupToken, requireToken } from './tokens.js';
+export type { Scale, StyleTokens } from './tokens.js';
+export { UnknownUtilityError } from './errors.js';
+export { PAINT_PROPERTIES, partitionPaint, resolvePaintUtility } from './paint.js';
+export type { PaintProps } from './paint.js';
+export { LAYOUT_PROPERTIES, partitionLayout, resolveLayoutUtility } from './layout.js';
+export type { AlignValue, Edge, JustifyValue, LayoutIntent, LayoutPartition, LayoutProps, OverlayIntent, } from './layout.js';
+export { partition, resolveUtilities, resolveUtility } from './resolve.js';
+export type { Partitioned, StyleProps } from './resolve.js';
+export { StyleSheet, StyleSheetError, VARIANT_PSEUDO } from './sheet.js';
+export type { StyleSheetOptions } from './sheet.js';

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

@@ -0,0 +1,163 @@
+import { type StyleTokens } from './tokens.js';
+/** React Native's own `alignItems`/`alignSelf` vocabulary. */
+export type AlignValue = 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
+/** React Native's own `justifyContent` vocabulary. */
+export type JustifyValue = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly';
+/** The four physical edges an absolutely positioned element offsets from. */
+export type Edge = 'top' | 'right' | 'bottom' | 'left';
+/**
+ * The properties the layout half understands, in React Native's spelling.
+ *
+ * The VALUES are React Native's too — `alignItems: 'flex-start'`, not `'start'` —
+ * and that is the point of ADR 0032 § 4 rather than a detail. A class list and a
+ * `style={{…}}` object are one information set arriving by two routes, and 48 of
+ * the measured application's 57 style objects carry exactly these names and values.
+ * Normalising the classes into a third spelling would put a translation table
+ * between the two front ends and give the partition two truths to keep in step.
+ */
+export interface LayoutProps {
+    marginTop?: string;
+    marginRight?: string;
+    marginBottom?: string;
+    marginLeft?: string;
+    marginStart?: string;
+    marginEnd?: string;
+    paddingTop?: string;
+    paddingRight?: string;
+    paddingBottom?: string;
+    paddingLeft?: string;
+    flexDirection?: 'row' | 'column';
+    flexGrow?: string;
+    alignItems?: AlignValue;
+    justifyContent?: JustifyValue;
+    alignSelf?: AlignValue;
+    gap?: string;
+    columnGap?: string;
+    rowGap?: string;
+    width?: string;
+    height?: string;
+    overflow?: 'visible' | 'hidden' | 'scroll';
+    display?: 'flex' | 'none';
+    position?: 'relative' | 'absolute';
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+    textAlign?: 'left' | 'center' | 'right' | 'justify';
+}
+/**
+ * What L1 could not answer, for L2 to resolve against the shadow tree.
+ *
+ * Every field here is a case where the same input compiles to DIFFERENT GTK
+ * depending on something no per-element function can see. Nothing is an intent for
+ * being hard: `overflow-hidden` needs the parent no more than `bg-red` does, and it
+ * is a widget property below rather than a field here.
+ */
+export interface LayoutIntent {
+    /**
+     * `flex-1` — `hexpand` on a row, `vexpand` on a column.
+     *
+     * ADR 0032 § 6, and the reason the intent mechanism exists at all: the axis is
+     * the PARENT's orientation, which an element does not know about itself.
+     */
+    readonly expand?: 'main-axis';
+    /**
+     * `items-*` — the cross-axis alignment of every CHILD.
+     *
+     * Two things missing at once. GTK has no `align-items`: the alignment lives on
+     * each child as `halign`/`valign`, so L2 must walk children this function has
+     * never seen. And WHICH of the two it is depends on this element's own
+     * orientation, which is `Gtk.Box`'s default when no `flex-row`/`flex-col` says
+     * otherwise — and the defaults disagree (`Gtk.Box` is horizontal, a React
+     * Native `View` is a column), so there is not even a safe fallback to guess.
+     */
+    readonly alignChildren?: AlignValue;
+    /**
+     * `justify-*` — main-axis distribution.
+     *
+     * `space-between` is a WIDGET CHOICE, not a property: `Gtk.CenterBox` for two or
+     * three children and a named refusal beyond that (ADR 0032 § 6). The child count
+     * decides, and L1 has no children. The other three are the box's own
+     * `halign`/`valign`, which needs the orientation for the same reason
+     * {@link LayoutIntent.alignChildren} does.
+     */
+    readonly distribute?: JustifyValue;
+    /**
+     * `self-*` — this element's own cross-axis alignment.
+     *
+     * `halign` or `valign` by the PARENT's orientation. Same shape as
+     * {@link LayoutIntent.expand}, same reason, one axis over.
+     */
+    readonly alignSelf?: AlignValue;
+    /**
+     * `gap-x-*` / `gap-y-*` — a spacing that is only valid on one orientation.
+     *
+     * `Gtk.Box` has ONE `spacing` (measured), so an axis-qualified gap is either
+     * that spacing or nothing at all, and which it is depends on the orientation
+     * L1 cannot see. Refusing the spelling outright was the alternative and is
+     * worse: `gap-x-2` on a row is ordinary, unambiguous authoring, and L2 answers
+     * it exactly.
+     */
+    readonly axisSpacing?: {
+        readonly axis: 'horizontal' | 'vertical';
+        readonly pixels: number;
+    };
+    /**
+     * `absolute` / `relative` / `inset-*` / `top-*` — the parent must be a `Gtk.Overlay`.
+     *
+     * A widget cannot make its own parent a different class, so the child's
+     * `absolute` is a request L2 executes on the PARENT. The `context` role is
+     * `relative`'s: it sets nothing (an overlay establishes the context by being
+     * one) but it is carried rather than dropped, because it is the half of the
+     * pair L2 can hold the other half against — an `absolute` child under a parent
+     * that never declared `relative` is a real authoring bug, and a dropped
+     * `relative` would make it undetectable.
+     */
+    readonly overlay?: OverlayIntent;
+    /**
+     * `text-*` — only a text widget aligns text.
+     *
+     * `xalign` and `justify` are `Gtk.Label`'s; `Gtk.Box` has neither (measured).
+     * A `<View className="text-center">` wrapping a `<Text>` is ordinary React
+     * Native, and on GTK the property has to travel to the label, which is a tree
+     * walk and therefore L2's.
+     */
+    readonly textAlign?: 'left' | 'center' | 'right' | 'justify';
+}
+export type OverlayIntent = {
+    readonly role: 'context';
+} | {
+    readonly role: 'child';
+    readonly edges: Readonly<Partial<Record<Edge, number>>>;
+};
+/** What {@link partitionLayout} contributes to the partition. */
+export interface LayoutPartition {
+    readonly css: readonly string[];
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly intent: LayoutIntent;
+}
+/**
+ * One utility class → the layout properties it sets, or `null` for "not mine".
+ *
+ * `null` rather than a throw is what lets `resolve.ts` try both halves without
+ * either of them knowing the other exists. A family this half DOES own with a bad
+ * token still throws, and that distinction is the whole point: `flex-2` is a
+ * refusal with a reason, `wibble-3` is an unknown name.
+ */
+export declare function resolveLayoutUtility(utility: string, tokens: StyleTokens): LayoutProps | null;
+/**
+ * The {@link LayoutProps} keys, for the dispatch's ownership test.
+ *
+ * DERIVED from the route table rather than listed: a second list is a second thing
+ * to keep true, and the one that drifts is the one that decides whether a property
+ * is routed at all.
+ */
+export declare const LAYOUT_PROPERTIES: ReadonlySet<string>;
+/**
+ * Layout properties → `{ css, props, intent }`.
+ *
+ * The two cross-key refusals run first, because both are cases where every
+ * individual property is fine and the COMBINATION is what GTK cannot express.
+ * They are the reason this is not a per-property `map`.
+ */
+export declare function partitionLayout(props: LayoutProps): LayoutPartition;

package/lib/types/style/layout.spec.d.ts

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

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

@@ -0,0 +1,53 @@
+import { type StyleTokens } from './tokens.js';
+/** The properties the paint half understands, in React Native's spelling. */
+export interface PaintProps {
+    backgroundColor?: string;
+    color?: string;
+    opacity?: string;
+    borderRadius?: string;
+    borderTopLeftRadius?: string;
+    borderTopRightRadius?: string;
+    borderBottomLeftRadius?: string;
+    borderBottomRightRadius?: string;
+    borderWidth?: string;
+    borderTopWidth?: string;
+    borderRightWidth?: string;
+    borderBottomWidth?: string;
+    borderLeftWidth?: string;
+    borderColor?: string;
+    fontSize?: string;
+    fontWeight?: string;
+    fontFamily?: string;
+    fontStyle?: string;
+    letterSpacing?: string;
+    lineHeight?: string;
+    textDecorationLine?: string;
+    textTransform?: string;
+}
+/**
+ * React Native property name → the GTK CSS property it becomes.
+ *
+ * Exported so `paint.spec.ts` can assert the invariant this table rests on — that
+ * every value is a property GTK measurably accepts — directly, rather than through
+ * `partition`'s per-call guard, which no input can reach while the table is right.
+ */
+export declare const CSS_NAME: Readonly<Record<keyof PaintProps, string>>;
+/**
+ * One utility class → the paint properties it sets, or `null` for "not mine".
+ *
+ * Returns a partial record rather than mutating, so a caller can see what a single
+ * class contributed — which is what makes the last-wins rule testable.
+ */
+export declare function resolvePaintUtility(utility: string, tokens: StyleTokens): PaintProps | null;
+/** The {@link PaintProps} keys, for the dispatch's ownership test. */
+export declare const PAINT_PROPERTIES: ReadonlySet<string>;
+/**
+ * Paint properties → GTK CSS declarations.
+ *
+ * Every emitted name is checked against the MEASURED accepted set rather than
+ * trusted: a property this table maps but GTK does not accept would be dropped by
+ * GTK's parser with no diagnostic, which is the exact silence the whole partition
+ * exists to avoid. The check is cheap and it has caught the one property that looks
+ * like paint and is not.
+ */
+export declare function partitionPaint(props: PaintProps): readonly string[];

package/lib/types/style/paint.spec.d.ts

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

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

@@ -0,0 +1,58 @@
+import { type LayoutIntent, type LayoutProps } from './layout.js';
+import { type PaintProps } from './paint.js';
+import type { StyleTokens } from './tokens.js';
+/** One normalised property set, in React Native's spelling (ADR 0032 § 4). */
+export type StyleProps = PaintProps & LayoutProps;
+/** What the partition hands back — GTK's three destinations, all of them. */
+export interface Partitioned {
+    /** GTK CSS declarations, `property: value`, without the braces. */
+    readonly css: readonly string[];
+    /**
+     * Widget properties in GTK's own spelling, with values the host will apply.
+     *
+     * The values are what `applyProps` coerces through the ParamSpec — a nick for
+     * an enum, a boolean for a boolean, an integer for a `gint`. NOT what a raw
+     * GJS setter accepts: `box.orientation = 'vertical'` keeps HORIZONTAL with no
+     * diagnostic at all (measured, gjs 1.88.1), which is the whole reason the host
+     * has a coercion step.
+     */
+    readonly props: Readonly<Record<string, unknown>>;
+    /** What only the shadow tree can answer, for L2 at attach time. */
+    readonly intent: LayoutIntent;
+}
+/**
+ * One utility class → the properties it sets.
+ *
+ * Paint runs first, and the order is not arbitrary: the paint families are closed
+ * sets of scale names, so its `null` is a cheap "no such family here", while the
+ * layout half owns the open-ended spellings (`gap-x-4`, `w-1/2`) whose parsing is
+ * where a wrong claim would be expensive.
+ */
+export declare function resolveUtility(utility: string, tokens: StyleTokens): StyleProps;
+/**
+ * A class list → the properties it sets, later classes winning.
+ *
+ * Last-wins is CSS's own rule for equal specificity and the one authors expect from
+ * a utility vocabulary. It is done HERE, on the property record, rather than by
+ * emitting two declarations and letting GTK resolve them — GTK resolves equal
+ * specificity by SHEET ORDER, not by the order of names in `css-classes`, so
+ * "the later class wins" would be false the moment two generated classes met.
+ *
+ * It is also why `m-*` puts its horizontal half in the same KEYS as `mx-*`: two
+ * spellings of one edge only resolve by last-wins while they are one key.
+ */
+export declare function resolveUtilities(utilities: readonly string[], tokens: StyleTokens): StyleProps;
+/**
+ * Properties → `{ css, props, intent }`.
+ *
+ * Splits the record by ownership and hands each half to its own partition, because
+ * the layout half's refusals are CROSS-KEY (a physical and a logical margin
+ * together, two gap spellings at once) and it can only see them with its whole
+ * share in hand.
+ *
+ * A property NEITHER half routes throws rather than being skipped. That is the same
+ * rule as an unknown utility, one layer down, and it is the one that catches a
+ * `style={{…}}` object carrying a React Native property nobody has mapped yet —
+ * the front end with no class name to check.
+ */
+export declare function partition(props: StyleProps): Partitioned;

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

@@ -0,0 +1,40 @@
+import Gdk from 'gi://Gdk?version=4.0';
+/** A variant this sheet knows how to express, and the pseudo-class it becomes. */
+export declare const VARIANT_PSEUDO: Readonly<Record<string, string>>;
+/** A rule GTK refused, or one that would have poisoned the document. */
+export declare class StyleSheetError extends Error {
+    readonly name = "StyleSheetError";
+    constructor(message: string);
+}
+export interface StyleSheetOptions {
+    /**
+     * Where the provider is installed. Omitted means the default display — the
+     * right answer for an application and the wrong one for a test, which is why
+     * it is injectable at all.
+     */
+    readonly display?: Gdk.Display | null;
+    /** Provider priority. Defaults to `STYLE_PROVIDER_PRIORITY_APPLICATION`. */
+    readonly priority?: number;
+}
+export declare class StyleSheet {
+    #private;
+    constructor(options?: StyleSheetOptions);
+    /**
+     * Register `declarations` (and optional variants) and return their class name.
+     *
+     * Idempotent: the same declarations always yield the same name and the document
+     * gains nothing the second time.
+     */
+    classFor(declarations: readonly string[], variants?: Readonly<Record<string, readonly string[]>>): string;
+    /** The document as GTK sees it. Exposed because a test that cannot read it proves nothing. */
+    toString(): string;
+    /** How many distinct rules the document holds. */
+    get size(): number;
+    /**
+     * Load the document now, rather than on the next microtask.
+     *
+     * A test has no microtask checkpoint it can rely on, and an application that is
+     * about to present a window wants the styles already in place.
+     */
+    flush(): void;
+}

package/lib/types/style/sheet.spec.d.ts

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

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

@@ -0,0 +1,58 @@
+/** A scale: token name → the CSS value it stands for. */
+export type Scale = Readonly<Record<string, string>>;
+/**
+ * Every scale the partition consults.
+ *
+ * All optional: a project that has no `letterSpacing` scale simply has no
+ * `tracking-*` utilities, and asking for one is an error naming the empty scale
+ * rather than a silent no-op.
+ */
+export interface StyleTokens {
+    /**
+     * The one scale `m-*`, `p-*`, `gap-*`, `inset-*` and the edge utilities read.
+     *
+     * ONE scale for all of them because that is what a token file actually holds —
+     * `mt-2xs` and `gap-2xs` name the same 2xs — and splitting it would ask a
+     * project to repeat itself once per family.
+     *
+     * A value only reaches the WIDGET-PROPERTY channel if it is a pixel length:
+     * `margin-top` is a `gint` of device pixels (measured, `gtk-props.ts`) and GTK
+     * exposes no unit conversion there. A scale spelled in `rem` therefore still
+     * works for padding, which is CSS-only, and is a named error on a margin rather
+     * than a silently rounded one.
+     */
+    readonly spacing?: Scale;
+    /** `w-<token>`, falling back to {@link StyleTokens.spacing} — Tailwind's own layering. */
+    readonly width?: Scale;
+    /** `h-<token>`, falling back to {@link StyleTokens.spacing}. */
+    readonly height?: Scale;
+    readonly colors?: Scale;
+    readonly borderRadius?: Scale;
+    readonly borderWidth?: Scale;
+    readonly fontSize?: Scale;
+    readonly fontWeight?: Scale;
+    readonly fontFamily?: Scale;
+    readonly letterSpacing?: Scale;
+    readonly lineHeight?: Scale;
+    readonly opacity?: Scale;
+}
+/**
+ * A minimal set, for tests and for a consumer who has no token file yet.
+ *
+ * Deliberately SMALL rather than a copy of Tailwind's defaults. A large default
+ * scale would let a project's typo resolve against a value nobody chose, which is
+ * the failure the declared-vocabulary rule exists to prevent — and it would make
+ * "the values come from the project" false in the common case.
+ */
+export declare const MINIMAL_TOKENS: StyleTokens;
+/** A token's value, or `undefined` when the scale is absent or does not carry it. */
+export declare const lookupToken: (scale: Scale | undefined, token: string) => string | undefined;
+/**
+ * A token's value, or a named error that lists what the scale DOES hold.
+ *
+ * Both halves of the partition read scales, so the reader lives with the scales
+ * rather than in whichever half needed it first. Listing the known keys is the
+ * whole value of the message: "not in the borderRadius scale" turns a typo into a
+ * search, "Known: full, lg, md, none, sm" turns it into a one-line fix.
+ */
+export declare function requireToken(scale: Scale | undefined, token: string, utility: string, scaleName: string): string;