@gjsify/gtk-host 0.41.0 → 0.43.0

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

@@ -1,5 +1,56 @@
+import type { GeneratedWidget, WidgetDescriptor } from '../types.js';
 export { GTK_DESCRIPTORS } from './gtk.js';
 export { ADW_DESCRIPTORS } from './adw.js';
-export declare const BUILTIN_DESCRIPTORS: import("../types.js").WidgetDescriptor[];
+export { GENERATED_PROVENANCE, GENERATED_WIDGETS } from '../generated/widgets.js';
+/**
+ * The hand-measured table: every widget whose PLACEMENT RULE is known.
+ *
+ * Kept separate from `BUILTIN_DESCRIPTORS` because the generator's gates take it
+ * as their input. Merging first and then checking would make G1 ("every curated
+ * gtype is in the GIR") and G3 ("every method a policy names exists") trivially
+ * true — the generated rows come from the GIR by construction and name no method,
+ * so a gate fed the merged table would pass while checking nothing.
+ */
+export declare const CURATED_DESCRIPTORS: readonly WidgetDescriptor[];
+/**
+ * Construct-only properties a GType ABORTS the process without.
+ *
+ * Not an exception: `adw_layout_slot_constructed` calls `g_error()`, which is
+ * fatal by contract — no catch, no diagnostic, SIGABRT and a core dump. A table
+ * that merely LISTS such a tag hands a renderer a way to kill the process, and
+ * `descriptorProblems()` cannot see it because it never instantiates anything.
+ *
+ * MEASURED bare-constructing all 164 generated rows on gjs 1.88.1 / GTK 4.22.4 /
+ * Adw 1.10, resuming past each abort: **163 construct, one does not**, and not a
+ * single row throws. So this map is one entry rather than a policy — and
+ * `constructsEveryDescriptor` in `generated.spec.ts` is what keeps it one entry.
+ *
+ * CURATED, like every other placement fact: the GIR says `id` is construct-only
+ * and nullable, which is exactly what it says about properties that construct
+ * fine. Only running it tells them apart (ADR 0028 § 1).
+ */
+export declare const REQUIRED_CONSTRUCT_PROPS: Readonly<Record<string, readonly string[]>>;
+export declare function mergeGenerated(curated: readonly WidgetDescriptor[], generated: readonly GeneratedWidget[]): WidgetDescriptor[];
+/**
+ * Curated placement rules, plus a tag for every other widget in the GIR.
+ *
+ * The direction is one-way and enforced by shape rather than by review: a
+ * `GeneratedWidget` carries no `children`, no `textSink` and no `eventAliases`, so
+ * the generator CANNOT contradict a curated descriptor — it can only add a gtype
+ * that was not there. A generated-only row gets `children: { kind: 'uncurated' }`,
+ * which means the widget can be created, given properties and given handlers,
+ * while inserting a child into it raises an error naming the tag that needs a
+ * curated policy. Guessing an adder is the one thing not on offer: `add`, `append`
+ * and `set_child` all exist somewhere in GTK, and calling the wrong one is a
+ * warning at exit 0.
+ */
+export declare const BUILTIN_DESCRIPTORS: readonly WidgetDescriptor[];
 /** Install the built-in table. Idempotent — registration is keyed on the GType name. */
 export declare function registerBuiltinWidgets(): void;
+/** What the shipped table is made of, for a diagnostic or an about box. */
+export declare const tableProvenance: () => {
+    gir: "Gtk-4.0 Adw-1";
+    curated: number;
+    generated: number;
+    total: number;
+};

package/lib/types/errors.d.ts

@@ -16,11 +16,26 @@ export declare class GtkHostError extends Error {
 }
 export declare const err: {
     unknownTag: (tag: string) => GtkHostError;
+    missingConstructProp: (tag: string, prop: string) => GtkHostError;
     unknownProp: (tag: string, prop: string) => GtkHostError;
     readOnlyProp: (tag: string, prop: string) => GtkHostError;
     badEnum: (tag: string, prop: string, nick: string, gtypeName: string) => GtkHostError;
     unknownSignal: (tag: string, prop: string, signal: string) => GtkHostError;
     signalTaken: (tag: string, prop: string, other: string, signal: string) => GtkHostError;
+    /**
+     * A DOM event-phase modifier has no GObject translation, so it is named, not guessed.
+     *
+     * `capture` selects a phase of DOM tree propagation and a GObject signal does not
+     * propagate through a tree at all — it is emitted on ONE object. `passive` is a
+     * promise not to call `preventDefault`, which no GObject signal has. Kebabing
+     * either into the signal name produced `emits no signal "clicked-capture"`, i.e.
+     * this host blaming the user's spelling for a concept it simply does not carry.
+     *
+     * It lived in `signals.ts` as a bare `new GtkHostError` for its whole life, which
+     * made this file's claim to BE the list false: the code existed, and the only
+     * place that enumerates the codes did not know it.
+     */
+    eventModifier: (prop: string, modifier: string) => GtkHostError;
     badString: (tag: string, prop: string, got: string) => GtkHostError;
     badBoolean: (tag: string, prop: string, value: string) => GtkHostError;
     badFlags: (tag: string, prop: string, value: string, gtypeName: string) => GtkHostError;
@@ -29,5 +44,11 @@ export declare const err: {
     unclaimedChild: (parentTag: string, childTag: string) => GtkHostError;
     unknownSlot: (parentTag: string, slot: string, known: string[]) => GtkHostError;
     rejectedChild: (parentTag: string, childTag: string, reason: string) => GtkHostError;
+    uncuratedPlacement: (parentTag: string, childTag: string) => GtkHostError;
+    siblingCycle: (parentTag: string) => GtkHostError;
     notAWidget: (tag: string) => GtkHostError;
+    occupiedSlot: (parentTag: string, childTag: string, setter: string) => GtkHostError;
+    notAnElement: (kind: string) => GtkHostError;
+    destroyedNode: (tag: string) => GtkHostError;
+    notAHostParent: (got: string) => GtkHostError;
 };