@gjsify/gtk-host 0.41.0 → 0.44.0

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;

package/lib/types/tags.d.ts

@@ -0,0 +1,25 @@
+/**
+ * GType name <-> kebab tag, and the map must be INJECTIVE.
+ *
+ * Two spellings exist because two dialects insist on different ones, and the
+ * difference is measured rather than chosen (ADR 0028 § 7):
+ *
+ *  - JSX intrinsic elements MUST be kebab. A capitalized `JSX.IntrinsicElements`
+ *    key is never consulted — `<GtkBox/>` is `TS2304: Cannot find name 'GtkBox'`,
+ *    because TypeScript reads a capitalized JSX name as a value reference.
+ *  - A Vue `GlobalComponents` key is the GTYPE name. Volar resolves a kebab tag
+ *    to EITHER spelling but a Pascal tag only to a Pascal key, so one key covers
+ *    `<gtk-box>` and `<GtkBox>` both.
+ *
+ * The GType name therefore stays the table key, the GtkBuilder XML key and the
+ * Vue key; kebab is the JSX spelling and an accepted registry alias.
+ */
+/** `GtkGLArea` -> `gtk-gl-area`, `AdwSpinRow` -> `adw-spin-row`, `GtkATContext` -> `gtk-at-context`. */
+export declare function tagOf(gtype: string): string;
+/**
+ * Refuse a table whose tags are not unique.
+ *
+ * A collision would make one of the two widgets unreachable by tag, silently —
+ * so it is an error at generation time, never a warning in a log nobody reads.
+ */
+export declare function assertInjective(gtypes: readonly string[]): void;

package/lib/types/testing/gate.d.mts

@@ -0,0 +1,25 @@
+import { type Runtime } from '@gjsify/unit';
+import type { DiagnosticsGate } from '../conformance/diagnostics.js';
+export declare const gated: (gate: DiagnosticsGate, name: string, body: () => Promise<void>) => Promise<void>;
+/**
+ * The runtimes that can host GTK — and an IDENTITY list on purpose.
+ *
+ * These suites need a reachable GTK, not a particular interpreter, so the
+ * expressive form would be a capability (`@gjsify/unit` splits `'Display'` from
+ * `'Gl'` for exactly that reason). It is not used here, and the reason is the
+ * failure mode rather than taste.
+ *
+ * A capability can only be PROBED — nothing about `(os, env)` answers "is the Gtk
+ * typelib reachable from this process", and `@gjsify/unit` is Tier 1 and must not
+ * import `gi://` to find out. A probe that answers "no" makes the whole suite STAND
+ * DOWN, and `requireAxes` cannot catch that: it only holds axes the host MATCHES.
+ * So a container that lost its GTK would run zero tests and report success — the
+ * green-that-checked-nothing shape, arriving through the very gate meant to widen
+ * coverage. Measured once already: gated on `'Gjs'` alone, this suite built for the
+ * node target exited 0 having run 0 tests from 0 gates, 9 stood down.
+ *
+ * Named identities instead mean the suite RUNS wherever it was built, and a missing
+ * GTK dies loudly at `Gtk.init()` in the first line of each suite. Louder beats
+ * more expressive when the quiet failure is a pass.
+ */
+export declare const GTK_HOSTS: Runtime[];

package/lib/types/types.d.ts

@@ -63,14 +63,31 @@ export interface HostElement extends HostNodeBase {
      * criticals per replay, at exit 0.
      */
     attached: boolean;
+    /** True once `destroy` has torn this element down. It never comes back. */
+    destroyed: boolean;
+    /**
+     * Children this element already had before the host adopted it.
+     *
+     * Only an ADOPTED root has any: a renderer mounts into a container the
+     * application built, and those children are in the GTK tree while being absent
+     * from the shadow tree. Placement offsets past them, or the first insertion
+     * computes "first" and the whole rendered tree lands ABOVE the app's own chrome.
+     */
+    foreign: readonly Gtk.Widget[];
 }
 export type HostNode = HostElement | HostText | HostAnchor;
 export type PolicyKind = 'none' | 'single' | 'ordered' | 'indexed' | 'slotted' | 'keyed' | 'coords';
 /**
  * How a parent adopts children. GTK4 deleted `GtkContainer`, so there is no
- * generic `add` — and `Gtk.Buildable.add_child` is introspected as a vfunc only
- * (`typeof headerBar.add_child === 'undefined'`, measured on gjs 1.88.1), so it
- * is not an escape hatch either. Every container states its own rules here.
+ * generic `add`. `Gtk.Buildable.add_child` is introspected as a vfunc only
+ * (`typeof headerBar.add_child === 'undefined'`, gjs 1.88.1) — but the vfunc form
+ * IS callable and DOES dispatch correctly, measured across 29 containers, so it is
+ * a real escape hatch. This comment used to claim otherwise.
+ *
+ * The table exists because the generic call is unsafe as a default, not because it
+ * is unavailable: `GtkLabel.vfunc_add_child` accepts a child and says nothing until
+ * `Finalizing GtkLabel …, but it still has children left` at teardown. Every
+ * container states its own rules here, and a widget with no rule is REFUSED.
  */
 export type ChildPolicy = {
     kind: 'none';
@@ -128,7 +145,36 @@ export type ChildPolicy = {
     kind: 'coords';
     attach: string;
     remove: string;
+}
+/**
+ * Generated, not curated: the tag exists, its placement rule does not.
+ *
+ * The generated table adds every concrete GtkWidget descendant the GIR
+ * describes — 164 of them — while the curated table measures placement for a
+ * fraction. Guessing an adder for the rest would be the worst of the three
+ * options: `add` and `append` and `set_child` all exist somewhere in GTK, and
+ * calling the wrong one is a warning at exit 0.
+ *
+ * So the honest state is spelled out. Such a widget can be CREATED and given
+ * properties and handlers; inserting a child raises a named error that says
+ * which tag needs a curated policy. A leaf widget — most of the 164 — needs
+ * nothing more.
+ */
+ | {
+    kind: 'uncurated';
 };
+/**
+ * One row of the GENERATED table: a tag, its GType, and how to reach the class.
+ *
+ * Deliberately not a `WidgetDescriptor`: it carries no placement rule, so making
+ * it the same type would invite a `children` field to appear here and become a
+ * second source for what `descriptors/` owns.
+ */
+export interface GeneratedWidget {
+    readonly gtype: string;
+    readonly tag: string;
+    readonly ctor: () => GObject.ObjectClass & (new (props?: Record<string, unknown>) => GObject.Object);
+}
 export interface WidgetDescriptor {
     /** GType name — and the tag a renderer writes. `GtkButton`, `AdwActionRow`. */
     readonly gtype: string;
@@ -142,4 +188,11 @@ export interface WidgetDescriptor {
     readonly textSink?: string;
     /** `onActivate` -> `activate` is derived; irregular pairs live here, in the TABLE. */
     readonly eventAliases?: Readonly<Record<string, string>>;
+    /**
+     * Construct-only properties whose ABSENCE aborts the process rather than
+     * raising — see `REQUIRED_CONSTRUCT_PROPS` in `descriptors/` for the measurement.
+     * Checked in `materialize`, because after `g_object_new` there is nothing left
+     * to check with.
+     */
+    readonly requiresProps?: readonly string[];
 }

package/lib/types/vue-components.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The Vue surface: `GlobalComponents`, keyed by GType name.
+ *
+ * Import it once, for its side effect, anywhere in a Vue project:
+ *
+ *     import '@gjsify/gtk-host/vue-components';
+ *
+ * WHY GTYPE NAMES AND NOT KEBAB. Volar camelizes and capitalises a template tag
+ * before it looks the component up, so ONE `GtkBox` key answers both `<GtkBox>`
+ * and `<gtk-box>`. A kebab key answers only the kebab spelling — measured, a
+ * Pascal tag against a kebab key is TS2339. So the GType name is the key, exactly
+ * as it is the registry key and the GtkBuilder key.
+ *
+ * The exception is generated, not curated: that camelize has no acronym knowledge,
+ * so `gtk-gl-area` becomes `GtkGlArea` and misses `GtkGLArea`. Those widgets get
+ * an extra kebab key in `WidgetPropsVueAliases`, and the generator finds them by
+ * rule rather than by bug report — one today.
+ *
+ * `strictTemplates: true` IS REQUIRED, AND IT MUST BE SET IN THE BASE OF THE
+ * `extends` CHAIN. Measured on `vue-tsc@3.3.11`, four cells, all four: the BASE
+ * tsconfig's value wins and the child's is ignored outright — a base with
+ * `strictTemplates: true` stays strict under a child that sets `false`, and a lax
+ * base stays lax under a child that sets `true`. So in a monorepo the shared base
+ * config decides this for every package, a per-package override does nothing, and
+ * nothing says so. Check the value with `vue-tsc --showConfig`, not by reading the
+ * nearest tsconfig.
+ *
+ * This is the load-bearing warning.
+ * Measured: without it, an unknown prop, an unknown event and an entirely
+ * UNRESOLVED tag are all silently accepted, while wrong VALUE types still error.
+ * A project without it therefore sees type errors appear and concludes the surface
+ * is working, while every misspelled property and every widget whose key does not
+ * resolve goes unchecked.
+ */
+import type { DefineComponent } from '@vue/runtime-core';
+import type { VueAttributes, WithOnce } from './attrs.js';
+import type { WidgetPropsByGType, WidgetPropsVueAliases } from './generated/props.js';
+type VueWidgetProps = WidgetPropsByGType & WidgetPropsVueAliases;
+export type GtkGlobalComponents = {
+    [K in keyof VueWidgetProps]: DefineComponent<WithOnce<VueWidgetProps[K]> & VueAttributes>;
+};
+declare module '@vue/runtime-core' {
+    interface GlobalComponents extends GtkGlobalComponents {
+    }
+}
+export {};