@gjsify/gtk-host 0.41.0 → 0.43.0

package/lib/types/jsx-runtime.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The JSX surface — our OWN jsx-runtime, and the measurement that made that the
+ * only option.
+ *
+ * The obvious alternative is to augment Solid's namespace:
+ * `declare module 'solid-js' { namespace JSX { interface IntrinsicElements … } }`.
+ * Measured, that leaves all 208 tags Solid pre-declares (113 HTML + 4 deprecated
+ * HTML + 59 SVG + 32 MathML) valid on a GTK renderer: `<div/>` and `<circle/>`
+ * type-check clean and then render NOTHING, silently. Closing them needs 208
+ * `never` overrides and produces `Type '{}' is not assignable to type 'never'`
+ * instead of "no such element". With our own runtime, `<div/>` is
+ * `TS2339: Property 'div' does not exist on type 'JSX.IntrinsicElements'`.
+ *
+ * TWO CONFIGURATION FACTS A CONSUMER MUST KNOW, both measured:
+ *
+ *  - `jsxImportSource` must point here, and `noImplicitAny` must be ON. With
+ *    `jsx: "preserve"`, no `jsxImportSource` and `noImplicitAny` off, every JSX
+ *    element is implicitly `any` and `tsc` exits 0 having checked NOTHING — the one
+ *    configuration in which this whole surface evaporates in silence.
+ *  - `jsx: "react"` is refused outright (TS5089); `preserve` (what
+ *    babel-preset-solid needs) and `react-jsx` both work.
+ *
+ * AND ONE HOLE THAT CANNOT BE CLOSED: TypeScript exempts every HYPHENATED JSX
+ * attribute from excess-property checking, so `<gtk-box no-such={1}/>` is accepted
+ * — on intrinsics and on components alike. Three index-signature shapes were tried
+ * (`\`${string}-${string}\`` mapped to `unknown`, to `never`, and to a subtracted
+ * union); all three either changed nothing or collided with the declared kebab
+ * keys (TS2411). The camelCase spelling of every property IS checked, which is why
+ * both spellings are generated and camelCase is the one to prefer.
+ */
+import type { JsxAttributes, WithOnce } from './attrs.js';
+import type { HostNode } from './types.js';
+import type { WidgetClassByTag, WidgetPropsByTag } from './generated/props.js';
+/** Every GTK/Adwaita tag, with its properties, its handlers and its `ref`. */
+export type GtkIntrinsicElements = {
+    [K in keyof WidgetPropsByTag]: WithOnce<WidgetPropsByTag[K]> & JsxAttributes<WidgetClassByTag[K]>;
+};
+export declare namespace JSX {
+    /**
+     * The type of a JSX EXPRESSION — a host node, not `ElementChild`.
+     *
+     * It was `ElementChild` (`HostNode | ElementChildren | string | number |
+     * boolean | null | undefined`), which reads like the right answer because that
+     * is what may be PASSED as a child. It is not what a JSX element evaluates
+     * TO: the compiler's `createElement` returns a node, always.
+     *
+     * The imprecision was not cosmetic. `<For>`, `<Index>` and `<Show>` are typed
+     * in `adapters/solid.ts` against `HostNode` — deliberately, because Solid's own
+     * signatures pin `JSX.Element` to the DOM's `Element` — so with `Element` this
+     * wide the FIRST `<For>` in any application failed with
+     * `Type 'ElementChild' is not assignable to type 'HostNode'`, and the whole
+     * control-flow surface was untypeable. Found by the first real JSX app
+     * (`showcases/gtk/solid-host-counter`); the fixtures in `type-tests/jsx/` had
+     * never used a control-flow component, which is why they went green over it.
+     * `type-tests/jsx/positive-element-is-a-node.tsx` is that gap closed.
+     *
+     * Children stay wide: they are typed by `JsxAttributes.children`, not by this.
+     */
+    type Element = HostNode;
+    /** Names the prop children arrive on — without it, nesting is an error. */
+    interface ElementChildrenAttribute {
+        children: Record<never, never>;
+    }
+    interface IntrinsicElements extends GtkIntrinsicElements {
+    }
+}
+export declare function jsx(): never;
+export declare function jsxs(): never;
+export declare function jsxDEV(): never;
+export declare function Fragment(): never;

package/lib/types/policies.d.ts

@@ -11,6 +11,64 @@ export declare function addressOf(el: HostElement): Gtk.Widget;
  * activation from the one the author configured.
  */
 export declare function makeWrapper(policy: ChildPolicy, child: Gtk.Widget): Gtk.Widget | null;
+/**
+ * A container the host owns that no window shows — the DOM's detached `<div>`.
+ *
+ * `<KeepAlive>` and `<Suspense>` ask a renderer for off-screen storage:
+ * `KeepAliveImpl.setup` opens with `createElement("div")` and `SuspenseImpl` does
+ * the same for its `hiddenContainer`. The Vue adapter answered that with its own
+ * `gi://Gtk` import and a literal `new Gtk.Box()` — the ONE runtime toolkit import
+ * and the ONE concrete widget class in any adapter, i.e. exactly the widget
+ * knowledge ADR 0027 § 7 forbids one. It lives here because this is already the
+ * file that builds widgets the author did not write (see `makeWrapper`), and it is
+ * the only one with a runtime `gi://Gtk` import.
+ *
+ * A `Gtk.Box` and not an `Adw.Bin`: the deactivated subtree may hold SEVERAL
+ * children, and a one-child container would silently keep the last.
+ */
+export declare const makeDetachedContainer: () => Gtk.Widget;
+/**
+ * The ONE-CHILD setter this child's placement goes through, or null.
+ *
+ * `single` always is one (`set_child`, `set_content`); a `slotted` slot is one
+ * when its method is a setter (`set_content`, `set_title_widget`) rather than an
+ * adder. Such a slot REPLACES — and it does so silently, which is why four call
+ * sites need the same question answered. Two of them are about an ELEMENT
+ * arriving; the other two are about TEXT, because GTK's text sink is the SAME
+ * slot: measured on gtk 4.22, `button.set_child(w)` followed by
+ * `set_property('label', …)` leaves `w.get_parent() === null`, and `set_child`
+ * after a `label` write leaves `label === null`. One widget, one slot, two APIs.
+ */
+/**
+ * Compile-time exhaustiveness, which this package does NOT get for free.
+ *
+ * `tsconfig.json` sets `strict: false`, so a switch that stops covering its union
+ * simply falls through and returns `undefined` — no error. Adding the `uncurated`
+ * policy kind passed `tsc` cleanly while five switches silently ignored it, which
+ * is exactly the class of green-and-wrong this package exists to prevent
+ * elsewhere. Assignability to `never` is not a strictness option, so a `default`
+ * arm calling this DOES fail the build (measured) and is the only mechanism that
+ * makes the next union member impossible to forget.
+ */
+export declare function unhandledPolicy(policy: never): never;
+export declare function setterSlotOf(parent: HostElement, child: HostElement): string | null;
+/** Every one-child slot this policy has, by setter name — `single` has exactly one. */
+export declare function setterSlots(policy: ChildPolicy): string[];
+/**
+ * Who GTK says is in a one-child slot. `undefined` means there is no getter to ask.
+ *
+ * The slot's own getter is the ONLY honest reader of this, and a child-list walk
+ * is not a substitute: measured on gtk 4.22.4 / libadwaita 1.9.3, a FRESH widget
+ * already has direct children the application never put there —
+ * `Gtk.ScrolledWindow` two `GtkScrollbar`s, `Adw.ToolbarView` two
+ * `GtkRevealer`s, `Adw.Window` an `AdwDialogHost` + an `AdwGizmo`,
+ * `Adw.StatusPage` a `GtkScrolledWindow` — while every one of those widgets
+ * answers `null` from its getter. The getter also survives GTK wrapping the
+ * child: `Gtk.ScrolledWindow.set_child(label)` reports a `GtkViewport`, not the
+ * label, so callers may compare occupants for IDENTITY but never assume the
+ * occupant is the widget they handed over.
+ */
+export declare function slotOccupant(widget: Gtk.Widget, setter: string): Gtk.Widget | null | undefined;
 export interface Placement {
     parent: HostElement;
     child: HostElement;

package/lib/types/probe.d.ts

@@ -0,0 +1,58 @@
+import Adw from 'gi://Adw?version=1';
+/** 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. */
+export interface HostProbe<T> {
+    /**
+     * Build the UI. `app` is `null` on the headless path, where there is no
+     * `GApplication` and the window is never presented.
+     */
+    build(app: Adw.Application | null): T;
+    /**
+     * Assert against the REAL widget tree — `get_first_child()`/`get_next_sibling()`
+     * 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.
+     */
+    assert(ui: T, check: ProbeCheck): Record<string, unknown>;
+    /** Prefix of the machine-readable result line. Default `PROBE`. */
+    label?: string;
+}
+/** A showcase that also has a GUI path — i.e. every one of them. */
+export interface HostProbeApp<T> extends HostProbe<T> {
+    /** GApplication id for the GUI path. */
+    applicationId: string;
+    /** Present the toplevel. Reached only after the assertions have passed. */
+    present(ui: T): void;
+}
+/**
+ * Truthy-env check, matching `@gjsify/devtools`' `GJSIFY_DEVTOOLS` gate semantics
+ * and `@gjsify/storybook`'s `probeEnabled` — one spelling of "opt in" across the
+ * repo, so `=0` and `=false` mean off rather than "any value is on".
+ */
+export declare function probeEnabled(): boolean;
+/**
+ * Run the showcase's assertions once and return the process exit code.
+ *
+ * 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
+ * warning is routine in a container, and counting those would fail the showcase
+ * with the host's name on a diagnostic it did not cause. Asserted, because GTK's
+ * 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;
+/**
+ * The whole `main` of a gtk-host showcase.
+ *
+ * `GJSIFY_HOST_PROBE` truthy: assert headlessly and exit, no window and no main
+ * loop. Otherwise: run the SAME assertions from `activate` before the window is
+ * shown, exit non-zero if any of them failed, then present. The GUI path carrying
+ * the assertions is the load-bearing half — `scripts/showcase-smoke.mjs` launches
+ * the app and waits, so without it the CI leg proves only that the process started.
+ *
+ * `runAsync`, never the sync `run()`: a sync `run()` leaves promise jobs undrained
+ * and hangs a view load on its spinner (the class `@gjsify/adwaita-app` documents).
+ */
+export declare function runHostProbeApp<T>(probe: HostProbeApp<T>): Promise<void>;

package/lib/types/props.d.ts

@@ -1,12 +1,38 @@
 import GObject from 'gi://GObject';
+import type { WidgetDescriptor } from './types.js';
 /** `backgroundColor` and `background-color` both name the GObject property `background-color`. */
 export declare function toPropertyName(name: string): string;
+/**
+ * A props object without the keys a framework reserves for itself.
+ *
+ * The SET is per-framework and stays with the adapter that owns it — Vue's is
+ * `@vue/shared`'s `isReservedProp`, React's is `children` — but the LOOP was
+ * written twice, byte-for-byte apart from the identifier names. That is the second
+ * copy this repo lifts on: the two would drift, and the drifted one fails in a
+ * consumer while the host stays green.
+ *
+ * `undefined` rather than `{}` for an empty result, and that is load-bearing:
+ * `createElement(tag, undefined)` skips the property loop entirely, so a vnode
+ * whose props are ALL reserved must not look like a vnode with one unknown
+ * property.
+ */
+export declare function withoutKeys(props: Record<string, unknown> | null | undefined, skip: ReadonlySet<string>): Record<string, unknown> | undefined;
 /** All ParamSpecs of a class, by kebab name. Cached per GType — `list_properties()` is not cheap. */
 export declare function paramSpecs(klass: GObject.ObjectClass, gtypeName: string): Map<string, GObject.ParamSpec>;
 export declare const isWritable: (spec: GObject.ParamSpec) => boolean;
 export declare const isConstructOnly: (spec: GObject.ParamSpec) => boolean;
 /** Construct-only property names of a class, in declaration order. */
 export declare function constructOnlyNames(klass: GObject.ObjectClass, gtypeName: string): string[];
+/**
+ * The value a nick names on an enum GType, or undefined if it names none.
+ *
+ * Exported for the generated surface's own check: the type surface offers a union
+ * of nicks per enum, and a nick this host cannot resolve would type-check and then
+ * be refused at runtime. `generated.spec.ts` resolves every emitted nick through
+ * this function, so the GIR-member-to-nick spelling is measured rather than
+ * assumed. Also the primitive a renderer needs for a "did you mean" diagnostic.
+ */
+export declare const lookupEnumNick: (gtypeName: string, nick: string) => number | undefined;
 /**
  * Turn an authored value into one GObject will actually store.
  *
@@ -22,8 +48,29 @@ export declare function coerce(spec: GObject.ParamSpec, value: unknown, tag: str
  *
  * React hands `undefined` for a prop that disappeared, and GObject cannot store
  * that: `set_property(name, undefined)` throws "Could not guess unspecified
- * GValue type" (measured). The ParamSpec knows the right answer.
+ * GValue type" (measured). What "removed" means is the value the widget would
+ * have carried had the prop never been authored — and that is what CONSTRUCTION
+ * 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:
+ *
+ *     GtkWindow.visible                 spec=true   constructed=false
+ *     AdwActionRow.activatable          spec=true   constructed=false
+ *     GtkToggleButton.receives-default  spec=false  constructed=true
+ *     GtkListBox.focusable              spec=false  constructed=true  (7 types)
+ *
+ * So `<AdwActionRow activatable={cond}>` with `cond` going `undefined` made a
+ * non-activatable row activatable, and removing `visible` SHOWED a window —
+ * silently, at exit 0, in the package that exists to refuse exactly that.
+ *
+ * `name` is kept as the probe reports it rather than as the ParamSpec's `null`:
+ * `gtk_widget_get_name` falls back to the type name when none was set, so the
+ * probe's answer is the one CSS `#id` matching already sees.
  */
-export declare function defaultValue(spec: GObject.ParamSpec): unknown;
+export declare function removedValue(descriptor: WidgetDescriptor, spec: GObject.ParamSpec): unknown;
 /** Look a property up, refusing the two silent failures: unknown and read-only. */
 export declare function requireSpec(specs: Map<string, GObject.ParamSpec>, tag: string, name: string): GObject.ParamSpec;

package/lib/types/react-jsx-runtime.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The React JSX surface: React's OWN automatic runtime, our OWN element list.
+ *
+ * `./jsx-runtime` in this package deliberately THROWS from `jsx()`/`jsxs()`, and
+ * that refusal is correct for the dialects it serves — Solid's reactivity lives in
+ * what `babel-preset-solid` emits from `jsx: "preserve"`, and Vue's in its SFC
+ * compiler, so an automatic runtime reaching those functions means the pipeline was
+ * misconfigured and nothing would render. React is the opposite case and the
+ * difference is structural rather than a matter of taste: React's `jsx()` builds a
+ * plain, renderer-agnostic React ELEMENT (a `{type, props, key}` record), and the
+ * host mapping happens later, in `react-reconciler`. So the automatic runtime is
+ * exactly the right thing here, and it is React's own — reimplementing it would be
+ * a second `createElement` to keep in step with React's element format.
+ *
+ * That is why this is a SEPARATE subpath instead of a change to `./jsx-runtime`:
+ * one module cannot both refuse the automatic runtime (for Solid) and provide it
+ * (for React). A consumer picks by pointing `jsxImportSource` at one or the other,
+ * and TypeScript appends `/jsx-runtime` (`/jsx-dev-runtime` under
+ * `jsx: "react-jsxdev"`) — hence two export keys beside `./react`. The tsconfig
+ * recipe is in the package README.
+ *
+ * WHY NOT just `jsxImportSource: "react"`. Then the element list comes from
+ * `@types/react`'s own `JSX.IntrinsicElements`, which is the 208-tag problem ADR
+ * 0028 § 8 measured on Solid, one package over: every HTML, SVG and MathML tag
+ * type-checks clean on a GTK renderer and then renders NOTHING. Declaring the
+ * namespace here is what makes `<div/>` a `TS2339` naming the element.
+ *
+ * The element list itself is the generated `WidgetPropsByTag`/`WidgetClassByTag`,
+ * which `scripts/check-type-surfaces.mjs` already holds negative-first through its
+ * `jsx` half. The React-specific plumbing below has no half yet — that gap, and
+ * why adding one is not a one-liner, is in `status/open-todos.md`. Its RUNTIME
+ * half is `adapters/react.spec.ts`.
+ */
+import type { Key, ReactElement, ReactNode, Ref } from 'react';
+import type { WidgetClassByTag, WidgetPropsByTag } from './generated/props.js';
+import type { RawSignalAttributes, SlotAttribute, WithOnce } from './attrs.js';
+export { Fragment } from 'react/jsx-runtime';
+/**
+ * React's own factories, RE-TYPED over this package's element list.
+ *
+ * The functions are React's — identity matters, because they build React's
+ * element format and a reimplementation would be a second one to keep in step.
+ * Only the SIGNATURE is ours: `@types/react` types `type` as React's
+ * `ElementType`, i.e. every HTML/SVG/MathML tag, so a direct call with a GTK tag
+ * would be a type error while a JSX tag (checked against `JSX.IntrinsicElements`
+ * below) would not. The cast is what makes the two agree.
+ */
+export declare const jsx: GtkJsxFactory;
+export declare const jsxs: GtkJsxFactory;
+export declare const jsxDEV: GtkJsxDevFactory;
+/** What may stand in a JSX tag position here: a GTK tag or a component. */
+export type GtkElementType = keyof GtkReactIntrinsicElements | ((props: never) => ReactNode);
+type GtkJsxFactory = (type: GtkElementType, props: unknown, key?: Key) => ReactElement;
+type GtkJsxDevFactory = (type: GtkElementType, props: unknown, key: Key | undefined, isStatic: boolean, source?: unknown, self?: unknown) => ReactElement;
+/**
+ * Per-element attributes React needs on top of the GObject properties.
+ *
+ * Deliberately not `JsxAttributes` from `./attrs.js`: that one types `ref` as
+ * `T | ((el: T) => void)`, which is Solid's spelling. React's `ref` additionally
+ * accepts a `useRef` object, so a shared type would reject the single most common
+ * way a React author holds a widget.
+ *
+ * `ref`, `children` and `key` are declared per element rather than left to
+ * `JSX.IntrinsicAttributes`, which TypeScript unions into the attributes of a
+ * COMPONENT and not of an intrinsic element — measured in ADR 0028 § 8: an
+ * undeclared `ref` is TS2322 and an undeclared `children` makes every nested
+ * element TS2559. `children` must also be optional, or a self-closing tag is
+ * TS2741.
+ */
+export interface ReactWidgetAttributes<T> extends SlotAttribute, RawSignalAttributes {
+    children?: ReactNode;
+    ref?: Ref<T> | undefined;
+    key?: Key | null | undefined;
+}
+/** Every GTK/Adwaita tag, with its properties, its handlers, its `ref` and its `key`. */
+export type GtkReactIntrinsicElements = {
+    [K in keyof WidgetPropsByTag]: WithOnce<WidgetPropsByTag[K]> & ReactWidgetAttributes<WidgetClassByTag[K]>;
+};
+export declare namespace JSX {
+    /**
+     * DELIBERATELY NOT `HostNode`, and not to be made "consistent" with the Solid
+     * surface next door.
+     *
+     * `jsx-runtime.ts` declares `Element = HostNode`, because Solid's control-flow
+     * components (`<For>`, `<Index>`, `<Show>`) are typed against host nodes and the
+     * first `<For>` in an application was otherwise a type error. React's is
+     * `ReactElement` because that is what a React JSX expression evaluates to: `jsx()`
+     * builds a renderer-agnostic element record and the host mapping happens later, in
+     * the reconciler. React's control flow is plain JavaScript, not typed components,
+     * so nothing here needs a host node in that position.
+     *
+     * The two files therefore answer two different questions and will keep disagreeing
+     * on this line. That is the design, which is why it is written down at the line
+     * rather than left to be rediscovered by whoever reaches for the one-line fix.
+     */
+    type Element = ReactElement;
+    type ElementType = GtkElementType;
+    /** Names the prop children arrive on — without it, nesting is an error. */
+    interface ElementChildrenAttribute {
+        children: Record<never, never>;
+    }
+    /** What React itself adds to every element, intrinsic or component. */
+    interface IntrinsicAttributes {
+        key?: Key | null | undefined;
+    }
+    interface IntrinsicElements extends GtkReactIntrinsicElements {
+    }
+}

package/lib/types/registry.d.ts

@@ -4,7 +4,7 @@ export declare function registerWidget(descriptor: WidgetDescriptor): void;
 export declare function registerWidgets(descriptors: readonly WidgetDescriptor[]): void;
 export declare function lookupWidget(tag: string): WidgetDescriptor;
 export declare const hasWidget: (tag: string) => boolean;
-/** Every registered tag — the conformance suite walks this, so coverage is data. */
+/** Every registered GType name — the conformance suite walks this, so coverage is data. */
 export declare const registeredTags: () => string[];
 /**
  * The nearest registered ancestor of a GType, most specific first.

package/lib/types/signals.d.ts

@@ -1,6 +1,21 @@
 import type { HostElement } from './types.js';
+export interface EventBinding {
+    /** The GObject signal name, modifiers removed. */
+    signal: string;
+    /** `.once`: disconnect after the first emission that actually reaches the callback. */
+    once: boolean;
+}
+/**
+ * Split an event prop into the signal GObject knows and the options it does not.
+ *
+ * Both escape hatches come FIRST and are verbatim: an `eventAliases` entry and
+ * the `on:<raw-signal-name>` spelling are the way to bind a signal that really
+ * does end in `-once` or `-capture`, exactly as they are the way to bind any
+ * other irregular name.
+ */
+export declare function parseEventProp(prop: string, aliases?: Readonly<Record<string, string>>): EventBinding;
 /** `onRowActivated` -> `row-activated`; `onNotifyVisible` -> `notify::visible`. */
-export declare function toSignalName(prop: string, aliases?: Readonly<Record<string, string>>): string;
+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;

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,2 @@
+import type { DiagnosticsGate } from '../conformance/diagnostics.js';
+export declare const gated: (gate: DiagnosticsGate, name: string, body: () => Promise<void>) => Promise<void>;

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 {};