@gjsify/gtk-host 0.45.0 → 0.47.0

package/lib/types/generated/widgets.d.ts

@@ -1,3 +1,3 @@
 import type { GeneratedWidget } from '../types.js';
-export declare const GENERATED_PROVENANCE: "Gtk-4.0 Adw-1";
+export declare const GENERATED_PROVENANCE: "Gtk-4.0/4.23.3 Adw-1/1.10.0";
 export declare const GENERATED_WIDGETS: readonly GeneratedWidget[];

package/lib/types/generator/emit-types.d.mts

@@ -23,7 +23,7 @@
  *    arrives as `unknown` so using it fails (TS2345). A generated surface that
  *    typed handlers loosely would break every handler that names its parameter.
  */
-import type { SurfaceModel } from './surface.mjs';
+import type { SurfaceModel } from './model.mjs';
 /**
  * Volar's own resolution rule, reproduced so the generator can SEE the gap.
  *

package/lib/types/generator/emit.d.mts

@@ -17,8 +17,7 @@
  * answer. The machine-INDEPENDENT check is the runtime one that already exists —
  * `descriptorProblems()` against the installed typelib.
  */
-import type { ChildPolicy, WidgetDescriptor } from '../types.js';
-import type { GirClass, GirNamespace } from './gir.mjs';
+import type { WidgetDescriptor } from '../types.js';
 /**
  * The `gi://` import a generated table needs, per GIR namespace.
  *
@@ -29,12 +28,23 @@ import type { GirClass, GirNamespace } from './gir.mjs';
  * trust.
  */
 export declare const GJS_MODULES: Readonly<Record<string, string>>;
+/** What a widget row needs. Three fields, not a GIR class — see `girs-vocabulary.mts`. */
+export interface WidgetRow {
+    readonly gtype: string;
+    readonly namespace: string;
+    readonly name: string;
+}
 export interface EmitInput {
-    readonly namespaces: readonly GirNamespace[];
-    readonly widgets: readonly GirClass[];
+    /** The provenance line, verbatim: `Gtk-4.0/4.23.3 Adw-1/1.8.0`. */
+    readonly provenance: string;
+    readonly widgets: readonly WidgetRow[];
+    /**
+     * Every GType the vocabulary knows, widgets and bases alike. G1 asks whether a curated
+     * row names something that exists, and a widget-only set would report every curated
+     * base as missing.
+     */
+    readonly knownGTypes: ReadonlySet<string>;
     readonly curated: readonly WidgetDescriptor[];
-    /** `methodsOf` from the conformance module — one extractor, not a second copy. */
-    readonly methodsOf: (policy: ChildPolicy) => string[];
     /** GIR namespace -> `gi://` import. Defaults to the GTK/Adwaita pair. */
     readonly modules?: Readonly<Record<string, string>>;
 }

package/lib/types/generator/girs-vocabulary.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Read the widget vocabulary from `@girs/<ns>/vocabulary` and build the emitter's model.
+ *
+ * WHY THIS REPLACED A GIR READER. This package used to parse the `.gir` XML itself, which
+ * made it the SECOND reader of a format ts-for-gir already reads — and two readers of one
+ * format are two truths that drift apart silently. ADR 0029 moved the vocabulary into
+ * `@girs/*` so there is one. What stays here is the DIALECT: kebab tags, the camelCase
+ * second spelling, `on<Signal>` prop names, Vue's Volar aliases. None of that is in the
+ * vocabulary and none of it belongs there, as its own header says.
+ *
+ * WHY IT READS BOTH HALVES. The runtime `.js` carries the facts as values (`OWN_PROPS`,
+ * `DECLS`, `OWN_SIGNALS`, `ENUM_NICKS`), which is what a check can compare against a live
+ * typelib. The `.d.ts` carries the rendered TypeScript for each property, which no amount
+ * of runtime data can reconstruct: `GtkBaselinePositionNick | Gtk.BaselinePosition`
+ * depends on that file's own imports. So the types come from the declarations and the
+ * facts come from the values, and neither is re-derived from the other.
+ *
+ * The `.d.ts` half is READ in `vocabulary-dts.mts`, which touches no file and so
+ * imports no `gi://` — that is what lets `generator.spec.ts` pin its regexes against
+ * literal fixtures instead of against whichever `@girs` happens to be installed.
+ */
+import type { SurfaceModel } from './model.mjs';
+/** The three fields `emit-types.mts` reads off a widget. Not a GIR class any more. */
+export interface WidgetRef {
+    readonly gtype: string;
+    readonly namespace: string;
+    readonly name: string;
+}
+export interface VocabularySource {
+    /** Import name, e.g. `gtk-4.0`. */
+    readonly pkg: string;
+    /** GType prefix, e.g. `Gtk`. */
+    readonly prefix: string;
+}
+/**
+ * Load the vocabulary packages and build the model the emitters already consume.
+ *
+ * `dir` is the `node_modules/@girs` root; the caller resolves it, because a generator
+ * should not guess where its own dependencies live.
+ */
+export declare function buildFromVocabulary(dir: string, sources: readonly VocabularySource[]): Promise<{
+    model: SurfaceModel;
+    widgets: WidgetRef[];
+    provenance: string;
+}>;

package/lib/types/generator/main.d.mts

@@ -1,15 +1,23 @@
 /**
  * The generator CLI.
  *
- *   gjsify run generate -- [--gir-dir DIR]... [--out DIR]
+ *   gjsify run generate -- [--girs-dir DIR] [--out DIR]
  *
- * WHY THE GIR PATH IS AN ARGUMENT AND NOT A DEPENDENCY. The GIR files are not in
- * this repository and should not be: `Gtk-4.0.gir` alone is 6.2 MB, they are
- * distro artefacts, and four different GTK versions sit on the maintainer
- * workstation. So the ARTEFACT is committed (ADR 0028 § Implementation) and the
- * input is located at generation time — from `--gir-dir`, from `GJSIFY_GIR_DIR`,
- * or from the search list below. A fresh clone builds, checks, packs and tests
- * with no GIR present at all; only regenerating needs one.
+ * WHERE THE VOCABULARY COMES FROM. The input used to be GIR XML: distro artefacts
+ * that are not in this repository, 6.2 MB for `Gtk-4.0.gir` alone, with four GTK
+ * versions on the maintainer workstation and no way to know which one a build saw.
+ * It is now the `@girs/<ns>/vocabulary` subpath (ADR 0029), which is an ordinary
+ * dependency, resolved like any other. That closes the provenance question the old
+ * route could only answer by convention: each vocabulary states the namespace,
+ * version and library version it was generated from, and this generator copies that
+ * into the artefact header instead of naming the files it happened to read.
+ *
+ * `--girs-dir` stays an argument so a locally built `@girs` can be generated against
+ * before it is published. Without it the directory is found by walking up from the
+ * working directory, which is what makes `npm run generate` work from the package.
+ *
+ * The ARTEFACT remains committed (ADR 0028 § Implementation): a fresh clone builds,
+ * checks, packs and tests without regenerating anything.
  *
  * THERE IS NO `--check` MODE, and the attempt to add one is worth recording: the
  * `generate` script pipes the output through `gjsify format`, which reflows it

package/lib/types/generator/model.d.mts

@@ -0,0 +1,95 @@
+/**
+ * The declaration graph the type surfaces are emitted from — the shape only.
+ *
+ * ONE INTERFACE PER DECLARATION, carrying its OWN members and extending its bases —
+ * not one flat interface per widget. The measurement decides it: the concrete widgets
+ * have thousands of writable property slots between them and a few hundred distinct
+ * property names. Flattening would emit the same `visible?: boolean` once per widget;
+ * mirroring the inheritance the vocabulary reports emits it once, on `GtkWidgetProps`,
+ * and the diff of a GTK update then shows what actually changed.
+ *
+ * WHO FILLS IT. `girs-vocabulary.mts`, from `@girs/<ns>/vocabulary`. This module used
+ * to hold a `buildSurface()` that filled the same shape from GIR XML this package
+ * parsed itself; ADR 0029 moved the vocabulary into `@girs/*` so there is one reader
+ * of that format instead of two. Only the shape survived, which is why the file is
+ * `model.mts` and no longer `surface.mts`: `surface` now names the `@girs` subpath.
+ */
+import type { WidgetRow } from './emit.mjs';
+export interface PropMember {
+    readonly kebab: string;
+    readonly camel: string;
+    readonly ts: string;
+    /**
+     * The hover blurb, from the JSDoc above the property in the vocabulary's `.d.ts`.
+     *
+     * The typelib strips documentation by design — which is why gi-docgen reads the
+     * GIR — and hover text is what a published type surface is FOR (ADR 0028 § 6). So
+     * the doc travels with the rendered type, out of the half of the vocabulary that
+     * can carry it; the runtime half is values, and a value cannot hold a comment.
+     */
+    readonly doc?: string;
+    readonly deprecated: boolean;
+    readonly since?: string;
+}
+export interface SignalMember {
+    readonly signal: string;
+    readonly prop: string;
+    /** Already rendered — `Gtk.ListBox.SignalSignatures['row-activated']`. */
+    readonly ts: string;
+    readonly doc?: string;
+    readonly deprecated: boolean;
+    readonly since?: string;
+}
+export interface Declaration {
+    /** Namespace-qualified — `Gtk.Box`. The graph is keyed on this, the way GIR references. */
+    readonly key: string;
+    readonly gtype: string;
+    readonly kind: 'class' | 'interface';
+    /** `GtkBoxProps`. */
+    readonly iface: string;
+    readonly bases: readonly string[];
+    readonly props: readonly PropMember[];
+    readonly signals: readonly SignalMember[];
+    readonly doc?: string;
+    /**
+     * The library release this TYPE arrived in, where GIR states one.
+     *
+     * Distinct from a member's `since`: it answers "does the installed library have
+     * this class at all", which is the question a bare `ctor()` returning `undefined`
+     * used to ask by crashing. Only about 11% of GIR classes carry a `version`, so an
+     * absent value means "not stated", never "has always existed".
+     */
+    readonly since?: string;
+}
+export interface SurfaceModel {
+    /**
+     * The widget rows, sorted by GType name.
+     *
+     * The same three fields the table emitter takes, so the type comes from there
+     * rather than being restated — a second spelling of a row is a second thing to
+     * keep in step with `girs-vocabulary.mts`, which fills both.
+     */
+    readonly widgets: readonly WidgetRow[];
+    readonly declarations: ReadonlyMap<string, Declaration>;
+    /** Widget GType -> the GTypes of every declaration its members come from, self first. */
+    readonly closure: ReadonlyMap<string, readonly string[]>;
+    /** Enum GType -> nicks, for the emitted aliases and for the runtime nick check. */
+    readonly enumNicks: ReadonlyMap<string, readonly string[]>;
+    readonly namespacesUsed: ReadonlySet<string>;
+    /** Namespace -> the `@girs` package that types it, so the emitter needs no second source. */
+    readonly packages: Readonly<Record<string, string>>;
+    /**
+     * Base -> members it must not contribute, because a nearer declaration disagrees.
+     *
+     * EMPTY TODAY, AND NOT DEFENSIVE MACHINERY. TypeScript requires a multiply
+     * inherited member to be IDENTICAL in every base — `string` and `string | null`
+     * are not — and GTK's interfaces do redeclare class properties, so a base that
+     * loses a member has to be emitted as `Omit<Base, 'name'>`: a local redeclaration
+     * does NOT repair incompatible bases, it turns one error into another. The GIR
+     * route computed those conflicts here; the published vocabulary resolves them
+     * upstream, so the map now arrives empty. It stays because `emit-types.mts`
+     * renders `Omit<>` from it, and a vocabulary that reintroduces a conflict needs a
+     * way to say so — the alternative is a surface that does not compile.
+     */
+    readonly omissions: ReadonlyMap<string, ReadonlyMap<string, readonly string[]>>;
+}

package/lib/types/generator/names.d.mts

@@ -0,0 +1,19 @@
+/**
+ * The two name transforms this package's DIALECT owns.
+ *
+ * Everything else that used to live here — the GIR-type-to-TypeScript mapper, the
+ * enum-nick unions, the `@girs` package map — moved into `@girs/<ns>/vocabulary`
+ * with ADR 0029, which renders each property's type in its own `.d.ts` and ships
+ * the nicks as data. What no vocabulary can answer is how a FRAMEWORK spells a
+ * member, because every framework spells it differently; that is dialect, it stays
+ * here, and it is why this file is `names.mts` and no longer `tsmap.mts`.
+ *
+ * Both are also read by `generated.spec.ts`, which runs them against the host's own
+ * inverse (`toSignalName`) over every generated name. Two independent
+ * implementations checked against each other is the point: nothing made them agree,
+ * and the first run of that check found that they did not.
+ */
+/** `row-activated` -> `onRowActivated`; `notify` handled by the caller. */
+export declare const eventPropOf: (signal: string) => string;
+/** `can-focus` -> `canFocus`. The inverse of the host's `toPropertyName`. */
+export declare const camelOf: (kebab: string) => string;

package/lib/types/generator/vocabulary-dts.d.mts

@@ -0,0 +1,47 @@
+/** One member, as the `.d.ts` renders it: the TS text plus whatever JSDoc sits above. */
+export interface DeclaredProp {
+    readonly ts: string;
+    readonly doc?: string;
+    readonly since?: string;
+    readonly deprecated: boolean;
+}
+/** One `export interface <GType>Props` — its own JSDoc, and its own members. */
+export interface DeclaredInterface {
+    readonly doc?: string;
+    readonly props: Map<string, DeclaredProp>;
+}
+interface DocBlock {
+    readonly doc?: string;
+    readonly since?: string;
+    readonly deprecated: boolean;
+}
+/**
+ * The JSDoc block directly above a declaration, or nothing.
+ *
+ * ADJACENCY IS THE WHOLE RULE. `text` is everything preceding the declaration, so the
+ * nearest block above it may belong to a sibling several members up. Requiring
+ * whitespace only between that block's terminator and the declaration is what
+ * separates "this member is documented" from "some earlier member was".
+ */
+export declare function readDocBlock(text: string): DocBlock;
+/**
+ * Read the namespace imports a vocabulary declares: `import type Gdk from
+ * '@girs/gdk-4.0'`.
+ *
+ * These are the only honest answer to "which namespaces do the rendered types reach
+ * into". Deriving it from the source list instead emitted `Gdk.RGBA` with no Gdk
+ * import — TS2503, in a file nobody edits by hand.
+ */
+export declare function readNamespaceImports(text: string, ownPkg: string): Map<string, string>;
+/**
+ * The interfaces a vocabulary `.d.ts` declares, with each property's rendered type.
+ *
+ * Brace-matched rather than terminated on a closing brace at column 0: an interface
+ * body can contain a nested object type, and a reader that stops at the first one
+ * silently truncates it. That exact shortcut is already recorded as a defect in two
+ * sibling scripts.
+ */
+export declare function readDeclaredInterfaces(text: string): Map<string, DeclaredInterface>;
+/** Property lines plus the JSDoc block immediately above each one. */
+export declare function readProps(body: string): Map<string, DeclaredProp>;
+export {};

package/lib/types/host.d.ts

@@ -1,4 +1,4 @@
-import GObject from 'gi://GObject';
+import GObject from 'gi://GObject?version=2.0';
 import type Gtk from '@girs/gtk-4.0';
 import type { HostAnchor, HostElement, HostNode, HostText, WidgetDescriptor } from './types.js';
 export declare function createElement(tag: string, props?: Record<string, unknown>): HostElement;

package/lib/types/policies.d.ts

@@ -9,8 +9,14 @@ export declare function addressOf(el: HostElement): Gtk.Widget;
  * is the spelling anyone reaching for `activatable` or `selectable` uses, and
  * wrapping a row inside a second row nests two selectable widgets and detaches
  * activation from the one the author configured.
+ *
+ * A `slotted` policy reaches this too, per SLOT: an adder that hands the child to an
+ * inner `Gtk.ListBox` needs exactly the same wrap, and `Adw.ExpanderRow`'s `add_row` is
+ * one. The measurement behind that is on `ChildPolicy`'s `wrapSlots`; the short version
+ * is that `gtk_list_box_remove` does not unwrap, so without this the child leaks behind
+ * one `Gtk-WARNING` at unmount.
  */
-export declare function makeWrapper(policy: ChildPolicy, child: Gtk.Widget): Gtk.Widget | null;
+export declare function makeWrapper(policy: ChildPolicy, child: Gtk.Widget, slot: string | null): Gtk.Widget | null;
 /**
  * A container the host owns that no window shows — the DOM's detached `<div>`.
  *

package/lib/types/props.d.ts

@@ -1,4 +1,4 @@
-import GObject from 'gi://GObject';
+import GObject from 'gi://GObject?version=2.0';
 import type { WidgetDescriptor } from './types.js';
 /** `backgroundColor` and `background-color` both name the GObject property `background-color`. */
 export declare function toPropertyName(name: string): string;
@@ -33,6 +33,18 @@ export declare function constructOnlyNames(klass: GObject.ObjectClass, gtypeName
  * assumed. Also the primitive a renderer needs for a "did you mean" diagnostic.
  */
 export declare const lookupEnumNick: (gtypeName: string, nick: string) => number | undefined;
+/**
+ * The member names an installed enum registers, or `undefined` if this host has none.
+ *
+ * The INVERSE of {@link lookupEnumNick}, and it exists for the one question that
+ * function cannot answer: a nick the vocabulary never emitted is absent from every
+ * list a check could iterate, so only the host's own members can reveal it. Read off
+ * the same `ENUM_NAMESPACES` table, so the two cannot disagree about where an enum
+ * lives — a second copy of that list is what made `Pango` missing once already.
+ *
+ * `$gtype` and anything non-numeric are not members; GJS puts both on the same object.
+ */
+export declare function enumMembers(gtypeName: string): string[] | undefined;
 /**
  * Turn an authored value into one GObject will actually store.
  *

package/lib/types/registry.d.ts

@@ -1,4 +1,4 @@
-import GObject from 'gi://GObject';
+import GObject from 'gi://GObject?version=2.0';
 import type { WidgetDescriptor } from './types.js';
 export declare function registerWidget(descriptor: WidgetDescriptor): void;
 export declare function registerWidgets(descriptors: readonly WidgetDescriptor[]): void;

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

@@ -0,0 +1,22 @@
+import Gdk from 'gi://Gdk?version=4.0';
+import Gtk from 'gi://Gtk?version=4.0';
+/** A document GTK refused, or one that would have discarded what follows it. */
+export declare class StyleSheetError extends Error {
+    readonly name = "StyleSheetError";
+    constructor(message: string);
+}
+/**
+ * Refuse a document that would take everything after it with it.
+ *
+ * `subject` names what is being loaded, because the two callers have very different
+ * readers: a generated rule is this package's bug, and an application's theme
+ * document is the application's.
+ */
+export declare function assertContained(document: string, subject: string): void;
+/**
+ * Put a provider on a display at `priority`, and say which display that was.
+ *
+ * `subject` names what is being installed, because the failure a caller has to act
+ * on is "there is no display yet" and the fix depends on which document it is.
+ */
+export declare function installProvider(provider: Gtk.CssProvider, subject: string, display: Gdk.Display | null | undefined, priority: number): Gdk.Display;

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

@@ -1,13 +1,16 @@
 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 { MINIMAL_TOKENS, TAILWIND_DEFAULT_TOKENS, lookupToken, mergeTokens, requireToken, tailwindDefaultHint, } 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 type { AlignValue, Edge, JustifyValue, LayoutIntent, LayoutPartition, LayoutProps, OverlayIntent, WrapIntent, } 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 { StyleSheet, VARIANT_PSEUDO } from './sheet.js';
 export type { StyleSheetOptions } from './sheet.js';
+export { assertContained, StyleSheetError } from './document.js';
+export { ADWAITA_NAMED_COLORS, NEUTRAL_THEME, NOT_ADWAITA_NAMED_COLORS, THEME_PROVIDER_PRIORITY, ThemeRegistry, } from './theme.js';
+export type { Theme, ThemeRegistryOptions } from './theme.js';

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

@@ -27,6 +27,7 @@ export interface LayoutProps {
     paddingBottom?: string;
     paddingLeft?: string;
     flexDirection?: 'row' | 'column';
+    flexWrap?: 'nowrap' | 'wrap';
     flexGrow?: string;
     alignItems?: AlignValue;
     justifyContent?: JustifyValue;
@@ -114,6 +115,25 @@ export interface LayoutIntent {
      * `relative` would make it undetectable.
      */
     readonly overlay?: OverlayIntent;
+    /**
+     * `flex-wrap` — the element becomes a DIFFERENT WIDGET.
+     *
+     * A `Gtk.Box` lays its children on one line and has no second line to put
+     * anything on. Wrapping on GTK is `Gtk.FlowBox`, which is not another property
+     * on the box but another class — so this is the same shape as
+     * {@link LayoutIntent.distribute}'s `space-between`: L1 names the widget the
+     * answer needs and L2 swaps it, because L1 resolves properties for an element
+     * and has no say in what the element becomes.
+     *
+     * The SPACINGS travel with it, and that is the reason this field carries values
+     * at all rather than being a flag. `Gtk.FlowBox` has NO `spacing` (measured,
+     * `gtk-props.ts`) — it has `row-spacing` and `column-spacing`, both real at once
+     * — so a gap on a wrapping element cannot take the `Gtk.Box:spacing` route the
+     * gap routes below use, and the axis-qualified spellings stop being an
+     * orientation question. Routing them here is what keeps `gap-*` from emitting a
+     * property the widget does not install.
+     */
+    readonly wrap?: WrapIntent;
     /**
      * `text-*` — only a text widget aligns text.
      *
@@ -124,6 +144,20 @@ export interface LayoutIntent {
      */
     readonly textAlign?: 'left' | 'center' | 'right' | 'justify';
 }
+/**
+ * `flex-nowrap` / `flex-wrap`, with the spacings a wrapping widget needs.
+ *
+ * `single` is carried rather than dropped for the reason `relative` is: it is the
+ * half L2 can hold the other half against, and a resolution that never sees it
+ * cannot tell "this element does not wrap" from "nobody asked".
+ */
+export type WrapIntent = {
+    readonly lines: 'single';
+} | {
+    readonly lines: 'multi';
+    readonly rowSpacing?: number;
+    readonly columnSpacing?: number;
+};
 export type OverlayIntent = {
     readonly role: 'context';
 } | {

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

@@ -1,11 +1,6 @@
 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

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

@@ -0,0 +1,158 @@
+import Gdk from 'gi://Gdk?version=4.0';
+/**
+ * Where a theme document is installed. See decision 2 for why it is this number.
+ *
+ * Exported because it is the fact a reader has to check against their own providers,
+ * and because a consumer installing a fourth document needs to know what it has to
+ * sit between.
+ */
+export declare const THEME_PROVIDER_PRIORITY: number;
+/**
+ * The named colours libadwaita defines, measured rather than read.
+ *
+ * MEASURED on libadwaita 1.9.3 by resolving `var(--<name>, <sentinel>)` on a real
+ * widget and checking the sentinel did NOT come back — the only test that
+ * distinguishes "the name exists" from "the name is a typo that defines nothing".
+ * `theme.spec.ts` re-measures both directions against the libadwaita that is
+ * running, so a release that renames one goes red here rather than in a window.
+ *
+ * The list is what a theme may OVERRIDE, and overriding a name libadwaita does not
+ * define is the exact silent failure this set exists to catch: `--acccent-bg-color`
+ * is a perfectly valid custom property that nothing ever reads.
+ */
+export declare const ADWAITA_NAMED_COLORS: readonly string[];
+/**
+ * Names that are NOT custom properties, and the claim each one carries.
+ *
+ * Without this direction the set above could name every string in GTK and still
+ * pass. `borders` is the interesting row: it is a real Adwaita colour under the
+ * LEGACY `@define-color` mechanism and is not a CSS variable, which is exactly the
+ * confusion decision 1 is about. `accent_bg_color` is the same point in the other
+ * spelling — the underscored legacy name of a variable that does exist.
+ */
+export declare const NOT_ADWAITA_NAMED_COLORS: readonly string[];
+/** One named look: a GTK CSS document, a palette, and which desktops default to it. */
+export interface Theme {
+    /** How the application asks for it. Also what a refusal names. */
+    readonly name: string;
+    /**
+     * The application's own GTK CSS document.
+     *
+     * Goes through the same containment probe as a generated rule, and for a
+     * stronger reason: this is the document this package did not write.
+     */
+    readonly css?: string;
+    /**
+     * Adwaita named colours to redefine, WITHOUT the `--` prefix.
+     *
+     * `{ 'accent-bg-color': 'rgb(53 132 228)' }`. Emitted as a `:root` block ahead of
+     * {@link Theme.css}, so a rule in {@link Theme.css} redefining one of these names
+     * WINS — the last definition in a document is the one that applies.
+     */
+    readonly namedColors?: Readonly<Record<string, string>>;
+    /**
+     * The `process.platform` values this theme is the default for, or `'*'` for any.
+     *
+     * Data on the theme rather than a table in the registry, because "this look
+     * belongs on macOS" is a fact about the look.
+     *
+     * `'*'` exists because `process.platform` has more values than the three desktops
+     * this project targets — `freebsd`, `openbsd`, `android`, `sunos`, … — and GTK
+     * runs on several of them. A registry that only knew `linux`/`darwin`/`win32`
+     * would make `selectDefault(process.platform)`, the call this seam is documented
+     * with, THROW on a platform where nothing is wrong. A fallback theme says so once
+     * instead, and a named theme still wins over it by being registered later.
+     */
+    readonly defaultOn?: readonly string[];
+}
+/**
+ * The one theme shipped now, and it deliberately changes nothing.
+ *
+ * A GTK application should look like the desktop it is running on, and the accent is
+ * the user's — they picked it in Settings and expect their applications to use it.
+ * So the neutral theme is an EMPTY document, and that is a statement rather than a
+ * placeholder: selecting it is how an application returns to Adwaita exactly, which
+ * is measurably true because reloading the provider to the empty string restores
+ * every named colour to libadwaita's own value.
+ *
+ * It is also what makes the registry useful with one theme registered: there is
+ * always something to switch back TO.
+ */
+export declare const NEUTRAL_THEME: Theme;
+export interface ThemeRegistryOptions {
+    /**
+     * 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 {@link THEME_PROVIDER_PRIORITY}; see decision 2. */
+    readonly priority?: number;
+}
+/**
+ * Named themes, one selected, swapped on a single provider.
+ *
+ * NOT a module-level singleton, unlike the token configuration one layer up. A
+ * registry holds a `Gdk.Display` and a `Gtk.CssProvider`, so a test that could not
+ * make its own would have to share the session's — and the registry is exactly the
+ * object whose whole behaviour is "what is installed on the display right now".
+ */
+export declare class ThemeRegistry {
+    #private;
+    constructor(options?: ThemeRegistryOptions);
+    /**
+     * Add a theme, refusing anything that would be a silent no-op.
+     *
+     * The document is PROBED here rather than at selection, so the error names the
+     * line that declared the theme instead of the line that switched to it — which
+     * may be a user clicking a row in the application's settings, hours later.
+     */
+    register(theme: Theme): this;
+    /** The registered names, in registration order. */
+    get names(): readonly string[];
+    /** The selected theme's name, or null before anything is selected. */
+    get current(): string | null;
+    /** The document a theme produces. Exposed because a test that cannot read it proves nothing. */
+    documentOf(theme: Theme): string;
+    /**
+     * Switch to a registered theme, replacing whatever was loaded.
+     *
+     * Idempotent, and cheap enough to call from a settings row's handler: the
+     * document was probed at registration, so this is one `load_from_string` plus, on
+     * the first call only, one `add_provider_for_display`.
+     */
+    select(name: string): void;
+    /**
+     * Select the theme that declares itself the default for `platform`.
+     *
+     * The platform is a PARAMETER and this module never reads `process.platform`
+     * itself — the same discipline the intent seam one layer up argues for. It keeps
+     * a `process` read (and the OS declaration that comes with one) out of a package
+     * whose job is GTK, and it lets a settings screen preview another desktop's look
+     * by passing that desktop's name.
+     *
+     * The last registered match wins, so an application registering its own theme
+     * after the neutral one gets its own — including over a theme that declares
+     * `'*'`, which is how the shipped neutral default stays a fallback rather than a
+     * ceiling.
+     */
+    selectDefault(platform: string): void;
+    /**
+     * Take the theme document off the display, leaving nothing behind.
+     *
+     * Selecting the neutral theme reloads the document to empty, which is all an
+     * application needs. It is NOT all a TEST needs, and the difference was measured
+     * in this file's own spec: a vector that read "libadwaita's own accent" read the
+     * PREVIOUS vector's green instead, because that registry's provider was still on
+     * the shared display with a `--accent-bg-color` in it — and the assertion named
+     * "back to Adwaita exactly" then passed against the green. Ownership belongs with
+     * whoever created the registry, so there has to be a way to give it up.
+     *
+     * The provider is removed from the display it was INSTALLED on rather than from
+     * whatever `Gdk.Display.get_default()` answers now. A later `select()` installs
+     * again: position relative to the generated sheet is decided by the priority
+     * numbers, not by insertion order, so re-installing cannot land in the wrong
+     * place (decision 2).
+     */
+    dispose(): void;
+}

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

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