@gjsify/gtk-host 0.52.0 → 0.54.0

package/lib/types/fonts.d.ts

@@ -1,8 +1,11 @@
 import Gtk from 'gi://Gtk?version=4.0';
+import { type FontFaceFailure } from '@gjsify/utils/font-map';
 import { type FontFamilyMatch } from './font-families.js';
 import { type FontSource, type ResolveFontSourcesOptions } from './font-dir.js';
 import { type PlanUiFontOptions, type UiFontPlan, type UiFontPolicy } from './ui-font.js';
 export { describeFontFamilyMatch, matchFontFamilies, matchFontFamily, type FontFamilyMatch, type FontFamilyMatchKind, } from './font-families.js';
+export { CAIRO_FONT_TYPE_FT, isUnsupportedByFontMap } from '@gjsify/utils/font-map';
+export type { FontFaceFailure } from '@gjsify/utils/font-map';
 export { ADWAITA_UI_FONT_FAMILY, GNOME_UI_FONT_POINT_SIZE, UI_FONT_POLICIES, planUiFont, planUiFontPolicy, type PlanUiFontOptions, type PlanUiFontPolicyOptions, type UiFontPlan, type UiFontPlanKind, type UiFontPolicy, } from './ui-font.js';
 export { resolveFontSources, type FontSource, type ResolveFontSourcesOptions } from './font-dir.js';
 /**
@@ -36,11 +39,6 @@ export interface InitFontsOptions extends Omit<ResolveFontSourcesOptions, 'env'>
      */
     readonly expectedFamilies?: readonly string[];
 }
-/** A face the font map would not take, and why. */
-export interface FontFaceFailure {
-    readonly path: string;
-    readonly message: string;
-}
 /**
  * A {@link FontSource} and the faces IT contributed.
  *
@@ -61,6 +59,14 @@ export interface FontSourceOutcome extends FontSource {
     readonly registered: readonly string[];
     /** Faces from THIS directory the font map declined — see {@link isUnsupportedByFontMap}. */
     readonly declined: readonly string[];
+    /**
+     * Faces from THIS directory that are on the map and that no layout can be served by — the map had
+     * already resolved their family to the fallback and caches that answer. Disjoint from
+     * {@link declined} and a subset of {@link registered}; `FontFaceRegistration.unreachable` in
+     * `@gjsify/utils/font-map` owns the reading and the fresh-map fallback that normally clears this
+     * list, so a non-empty one means that fallback was unavailable and the substitution is real.
+     */
+    readonly unreachable: readonly string[];
     /** Faces from THIS directory that failed otherwise, plus the directory itself if unreadable. */
     readonly failed: readonly FontFaceFailure[];
 }
@@ -98,6 +104,19 @@ export interface InitFontsResult {
      * {@link isUnsupportedByFontMap}.
      */
     readonly declined: readonly string[];
+    /**
+     * Faces that are on the map and that no layout can be served by, across every {@link sources}
+     * entry: the map resolved their family to the fallback before the face arrived and caches that
+     * answer, so registering the face changed `list_families()` and nothing else. A SUBSET of
+     * {@link registered} — the face really is on the map and `get_family` answers its family — which
+     * is why it is reported beside the flat lists rather than inside them.
+     *
+     * EMPTY wherever the fontconfig fallback took over, which is the whole point of it: then a fresh
+     * map serves the faces and there is nothing left to say. Non-empty means that fallback was
+     * unavailable (`PANGOCAIRO_BACKEND` pinned, no fontconfig configuration, no fc backend) and the
+     * substitution will happen whatever the application does next.
+     */
+    readonly unreachable: readonly string[];
     /**
      * Faces that failed for any other reason, across every {@link sources} entry. Each was warned
      * about; none threw.
@@ -133,31 +152,18 @@ export interface InitFontsResult {
      * the map holds afterwards, which is what a match reads.
      */
     readonly matches: readonly FontFamilyMatch[];
+    /**
+     * `true` when this call REPLACED the process's default font map with a fontconfig-backed one
+     * so the faces could be registered at all — see `probeFontconfigMap` in `@gjsify/utils/font-map`.
+     *
+     * Reported because it is a whole-application consequence of one call: every widget created
+     * afterwards renders through FreeType instead of the platform rasteriser. It happens only
+     * where the default map DECLINED registration (a CoreText map — `gjsify run` on a Homebrew
+     * GTK), the faces brought a family that map does not already hold, fontconfig has a
+     * configuration of its own, and nobody pinned `PANGOCAIRO_BACKEND` (ADR 0038 § Amendment 5).
+     */
+    readonly fontconfigFallback: boolean;
 }
-/**
- * Did the font map decline runtime registration outright?
- *
- * `pango_font_map_add_font_file()` is a vfunc, and the CoreText map implements none — so on macOS
- * the call falls through to the base implementation, which answers `G_IO_ERROR_NOT_SUPPORTED`.
- * That is not a failure to report: macOS is already correct declaratively, because the bundle's
- * `ATSApplicationFontsPath` had the OS activate the staged directory before the process started,
- * and the ordering makes the runtime call the wrong tool there rather than merely a redundant one
- * — `pango_core_text_font_map_changed()` only bumps a serial, there is no
- * `kCTFontManagerRegisteredFontsChangedNotification` observer and no re-scan path in
- * `pangocoretext-fontmap.c`, so a face registered after the map initialises could not be recovered
- * by poking it anyway.
- *
- * Keyed on the ERROR rather than on `process.platform`, which is the difference between a
- * capability test and a guess about who is asking. It costs no `gjsify.os` declaration (this
- * package makes no OS decision, and ADR 0018's candidate set is derived from the code that reads
- * the host), and it stays right for any other map that declines. The OS name was never the thing
- * being asked — which stopped being hypothetical: the backend is whichever one is selected rather
- * than one per platform, and `@gjsify/node-gi`'s loader selects `PANGOCAIRO_BACKEND=fc` on the
- * bundled windowing runtime (ADR 0038 § Amendment 3), so a darwin process on it reaches this
- * arm's other side and REGISTERS the faces. A `process.platform` branch would have had to be
- * found and reversed instead.
- */
-export declare function isUnsupportedByFontMap(error: unknown): boolean;
 /**
  * Register every face in the application's shipped font directory with the default font map.
  *
@@ -165,8 +171,11 @@ export declare function isUnsupportedByFontMap(error: unknown): boolean;
  * fontconfig backend rather than tidiness: it caches the FONTSET resolved for a description and
  * `add_font_file` does not invalidate it, so a `Pango.Layout` that measured the family first keeps
  * measuring the fallback for the life of the process even though the family is then in
- * `list_families()`. win32 clears its cache instead and recovers, so registering early is free
- * there and unrecoverable-if-missed on Linux (measured both ways; `fonts.spec.ts`).
+ * `list_families()`. win32 clears its cache instead and recovers, so registering early is free there
+ * and unrecoverable-if-missed on Linux (measured both ways; `fonts.spec.ts`). Calling it late is no
+ * longer SILENTLY wrong, though: `registerFontFaces` measures what it registered, replaces the default
+ * map when a face turned out to be unserved, and reports what it could not rescue in
+ * {@link InitFontsResult.unreachable} — see the file header for what that leaves of the rule.
  *
  * Nothing here is eager: this
  * package is the element model renderers bind to and owns no application lifecycle, and a

package/lib/types/host.d.ts

@@ -24,23 +24,22 @@ export declare function setEventHandler(el: HostElement, prop: string, next: ((.
 /**
  * The ARIA object, diffed against the one it replaces.
  *
- * ONE GROUPED PROP RATHER THAN 53 FLAT `aria*` ONES, and the reasons are measured rather
- * than aesthetic. (1) TypeScript exempts every hyphen-containing JSX attribute from
- * excess-property checking — the measurement `emit-types.mts` already records for the
- * kebab property spellings — so a flat `aria-labell` would be accepted in silence, while a
- * key inside a fresh object literal IS checked. (2) The ARIA names are not the widget's
- * properties and collide with them: `label`, `orientation`, `checked`, `expanded` and
- * `selected` are all both, and `orientation` is settable on a `GtkLabel` that implements no
- * `GtkOrientable` at all — one object keeps the two vocabularies apart by construction
- * instead of by prefix. (3) The other surface over this same vocabulary already spells it
- * this way: a `.blp` author writes `accessibility { label: "…"; }` (ADR 0034). (4) `setProp`
- * already has this shape for `layout` — a structured, non-ParamSpec prop routed to its own
- * mechanism — so this adds one reserved key to the host, not 53.
+ * ONE GROUPED PROP RATHER THAN 53 FLAT `aria*` ONES, for measured reasons. (1)
+ * TypeScript exempts every hyphen-containing JSX attribute from excess-property checking —
+ * the measurement `emit-types.mts` already records for the kebab property spellings — so a
+ * flat `aria-labell` would be accepted in silence, while a key inside a fresh object literal
+ * IS checked. (2) The ARIA names collide with the widget's own properties: `label`,
+ * `orientation`, `checked`, `expanded` and `selected` are all both, and `orientation` is
+ * settable on a `GtkLabel` that implements no `GtkOrientable` at all — one object keeps the
+ * two vocabularies apart by construction instead of by prefix. (3) The other surface over
+ * this vocabulary already spells it this way: a `.blp` author writes `accessibility {
+ * label: "…"; }` (ADR 0034). (4) `setProp` already has this shape for `layout`, so this adds
+ * one reserved key to the host, not 53.
  *
  * REFUSED ON THE CLASS, not on the widget: every framework builds bottom-up, so props are
  * authored long before materialisation, and asking the instance would report
- * `<gtk-string-list accessibility={…}>` from inside a later `materialize` rather than at the
- * call that wrote it.
+ * `<gtk-string-list accessibility={…}>` from inside a later `materialize` rather than at
+ * the call that wrote it.
  *
  * The plan is built BEFORE anything is recorded, for the reason the property path states:
  * `el.accessibility` is replayed verbatim by `replayInto`, so a refused value kept there
@@ -55,32 +54,23 @@ export declare function insert(node: HostNode, parent: HostElement, anchor?: Hos
 /**
  * TWO facts, not one: it says it is an element, and it carries a descriptor.
  *
- * `kind` alone is a plain string a GObject wrapper could carry; the descriptor is
- * what every host op actually dereferences. Checking both keeps the refusal from
- * being either paranoid or fooled.
+ * `kind` alone is a plain string a GObject wrapper could carry; the descriptor is what
+ * every host op actually dereferences. Checking both keeps the refusal from being either
+ * paranoid or fooled.
  *
- * Exported because the Vue adapter had these same two lines VERBATIM, and its own
- * comment said so — it needs the question before `adopt`, to tell a host parent
- * from the raw widget `<Teleport :to="el">` hands through. A predicate stated in
- * two places is a predicate that can disagree with itself about what a node is.
+ * Exported because the Vue adapter needs the question before `adopt`, to tell a host
+ * parent from the raw widget `<Teleport :to="el">` hands through.
  */
 export declare function isHostElement(value: unknown): value is HostElement;
 /**
  * Name a foreign value the way its owner would recognise it.
  *
- * ONE function, because there were two and each was wrong for the other's input.
- * The host's read `constructor.$gtype`, so it could not name a DOM element — the
- * single most likely thing to arrive from a Solid app that imported `<Dynamic>`
- * from `solid-js/web`. The Solid adapter's read `tagName`, so it answered
- * `a Object` for the GObject wrapper `<Teleport :to="el">` hands over. Both are
- * asking "what did I get instead of a node", so both answers belong to one place.
- *
- * ORDER IS LOAD-BEARING, and it is measured rather than reasoned: under gjs
- * 1.88.1 `({}).constructor.$gtype` EXISTS and `GObject.type_name` calls it
- * `JSObject`. So a `$gtype`-first version names every object literal — and every
- * DOM-ish stub, which is an object literal — `JSObject`, and the host's own
- * documented `a plain object` fallback was unreachable for exactly the shape it
- * names. `tagName` first, and `JSObject` treated as the absence of a GType.
+ * ORDER IS LOAD-BEARING, and it is measured rather than reasoned: under gjs 1.88.1
+ * `({}).constructor.$gtype` EXISTS and `GObject.type_name` calls it `JSObject`. A
+ * `$gtype`-first version would therefore name every object literal — and every DOM-ish
+ * stub, which is an object literal — `JSObject`, and the `a plain object` fallback would be
+ * unreachable for exactly the shape it names. `tagName` first, `JSObject` treated as the
+ * absence of a GType.
  */
 export declare function describeValue(value: unknown): string;
 /** Detach only — reversible. Frameworks move nodes; `remove` must not destroy one. */
@@ -88,30 +78,25 @@ export declare function remove(node: HostNode): void;
 /**
  * Destroy every child of `parent`, bounded.
  *
- * Exported because both adapters wrote their OWN `childSnapshot` to do exactly this
- * — byte-identical to each other, and both walking `next` raw. That is the one walk
- * the bound above exists to make unforgettable, and it is the walk where the
- * malformed link actually appears: `insert(node, parent, node)` is a defined DOM
- * no-op, so Solid's adjacent-swap fast path emits it against a CONTAINER's child
- * list. Unbounded, that is a hang rather than GTK's usual exit 0.
- *
- * This replaces a `clearContainer` that had no callers anywhere and DETACHED rather
- * than destroyed — the wrong half for every caller that wanted it, and a name React's
- * own HostConfig already uses for the destroying kind.
+ * Every walk over `next` goes through `childSnapshot` so the bound cannot be forgotten at a
+ * new call site, and this is the walk where the malformed link actually appears: `insert(
+ * node, parent, node)` is a defined DOM no-op, so Solid's adjacent-swap fast path emits it
+ * against a CONTAINER's child list. Unbounded, that is a hang rather than GTK's usual
+ * exit 0.
  */
 export declare function destroyChildren(parent: HostElement): void;
 /**
  * Disconnect a node's handlers WITHOUT touching the tree.
  *
- * The narrow half of `destroy`, and it exists because a framework can tell us "this
- * node is gone" while still holding its sibling links: Solid disposes a per-node
- * scope BEFORE its reconciler runs, and `reconcileArrays` opens with
- * `getNextSibling(last)`. Unlinking there made every trailing insertion append at
- * the end of the parent instead of before the marker.
+ * The narrow half of `destroy`, and it exists because a framework can tell us "this node is
+ * gone" while still holding its sibling links: Solid disposes a per-node scope BEFORE its
+ * reconciler runs, and `reconcileArrays` opens with `getNextSibling(last)`. Unlinking there
+ * made every trailing insertion append at the end of the parent instead of before the
+ * marker.
  *
- * The leak this closes is about handlers, not links — GJS blocks JS callbacks
- * during GC, so an undisconnected handler outlives its widget. The framework's own
- * `removeNode` still does the unlinking, in its own order.
+ * The leak this closes is about handlers, not links — GJS blocks JS callbacks during GC, so
+ * an undisconnected handler outlives its widget. The framework's own `removeNode` still
+ * does the unlinking, in its own order.
  */
 export declare function disconnectHandlers(el: HostElement): void;
 /**
@@ -128,43 +113,36 @@ export declare function destroy(node: HostNode): void;
 /**
  * Put a host tree inside an existing GTK container the application owns.
  *
- * The container is resolved through the SAME table as every other parent —
- * `nearestRegistered` walks the real type hierarchy, so an application's own
- * `GObject.registerClass` subclass inherits its ancestor's policy. Guessing a
- * method name here would be the generic `add` that GTK4 deliberately removed.
+ * The container is resolved through the SAME table as every other parent, so an
+ * application's own `GObject.registerClass` subclass inherits its ancestor's policy.
+ * Guessing a method name here would be the generic `add` that GTK4 deliberately removed.
  */
 export declare function mountRoot(el: HostElement, container: GObject.Object): void;
 /**
  * The materialised widget of a host node — for a `ref`, or for a test.
  *
- * ONE implementation. The Solid and React adapters each carried this function,
- * identical apart from two comment lines, and Vue carried none — so a Vue app had
- * no supported way to reach a widget at all and its only route was
- * `materialize()`, which is exactly the call the `destroyed` guard below exists to
- * intercept.
+ * ONE implementation, because a caller reaching `materialize()` directly is exactly what the
+ * `destroyed` guard below exists to intercept.
  *
- * The flag is exact and the obvious heuristic is not: `materialize` would happily
- * build a fresh, propertyless, unparented widget for a destroyed node — `destroy`
- * clears `props` and `layout` precisely so one cannot look re-materialisable — and
- * "no widget, not attached, no props" also describes a brand-new element.
+ * The flag is exact and the obvious heuristic is not: `materialize` would happily build a
+ * fresh, propertyless, unparented widget for a destroyed node — `destroy` clears `props`
+ * and `layout` precisely so one cannot look re-materialisable — and "no widget, not
+ * attached, no props" also describes a brand-new element.
  */
 export declare function widgetOf(node: HostNode): Gtk.Widget;
 /**
  * An off-screen container the host owns — the analogue of the DOM's detached `<div>`.
  *
- * `<KeepAlive>` and `<Suspense>` ask a renderer for one: `KeepAliveImpl.setup`
- * opens with `createElement("div")` and `SuspenseImpl` does the same for its
- * `hiddenContainer`. Forwarded as a TAG, "div" reached `lookupWidget` and threw
- * `unknown-tag` inside `callWithErrorHandling`, whose production arm is
- * `console.error` with no rethrow: `mount()` returned normally, the container held
- * zero children, GTK said nothing, exit 0.
- *
- * The Vue adapter answered that with `adopt(new Gtk.Box())` — the one runtime
- * `gi://` import and the one concrete widget class in any adapter, i.e. the widget
- * knowledge ADR 0027 § 7 forbids. Which widget backs it is the table's business
- * (`makeDetachedContainer`), and this op is what leaves the adapter with nothing to
- * know: the deactivated subtree is really unparented from the visible tree and
- * really held alive, so reactivating it moves the SAME widgets back.
+ * `<KeepAlive>` and `<Suspense>` ask a renderer for one: `KeepAliveImpl.setup` opens with
+ * `createElement("div")` and `SuspenseImpl` does the same for its `hiddenContainer`.
+ * Forwarded as a TAG, "div" reached `lookupWidget` and threw `unknown-tag` inside
+ * `callWithErrorHandling`, whose production arm is `console.error` with no rethrow:
+ * `mount()` returned normally, the container held zero children, GTK said nothing, exit 0.
+ *
+ * Which widget backs it is the table's business (`makeDetachedContainer`), and this op is
+ * what leaves the adapter with nothing to know — the widget knowledge ADR 0027 § 7 forbids.
+ * The deactivated subtree is really unparented from the visible tree and really held
+ * alive, so reactivating it moves the SAME widgets back.
  */
 export declare const createDetachedContainer: () => HostElement;
 /**

package/lib/types/index.d.ts

@@ -3,9 +3,9 @@ export { GtkHostError } from './errors.js';
 export { adopt, createAnchor, createDetachedContainer, createElement, createText, destroyChildren, destroy, disconnectHandlers, firstChild, insert, isHostElement, isText, materialize, mountRoot, nextSibling, parentNode, prevSibling, remove, setElementText, setEventHandler, setProp, setSlot, setText, widgetOf, } from './host.js';
 export { addressOf, isPortal, placementOf, portalOf, reorderMode } from './policies.js';
 export { toSignalName, isEventProp } from './signals.js';
-export { constructOnlyNames, isConstructOnly, isWritable, lookupEnumNick, paramSpecs, toPropertyName, } from './props.js';
+export { constructOnlyNames, gtypeOfName, isConstructOnly, isWritable, lookupEnumNick, paramSpecs, toPropertyName, } from './props.js';
 export { assertInjective, tagOf } from './tags.js';
 export { blankReason, checkRendered, probeEnabled, runHostProbe, runHostProbeApp, shotEvidence, type CaptureWidget, type HostProbe, type HostProbeApp, type ProbeCheck, type ShotEvidence, } from './probe.js';
 export type { AccessibilityAttribute, ElementChild, ElementChildren, JsxAttributes, RawSignalAttributes, SlotAttribute, VueAttributes, WithOnce, } from './attrs.js';
-export { clearRegistry, hasWidget, lookupWidget, nearestRegistered, registerWidget, registerWidgets, registeredTags, } from './registry.js';
+export { clearRegistry, classOf, hasClass, hasWidget, lookupWidget, nearestRegistered, registerWidget, registerWidgets, registeredTags, requireClass, type InstalledClass, } from './registry.js';
 export { ADW_DESCRIPTORS, BUILTIN_DESCRIPTORS, CURATED_DESCRIPTORS, GENERATED_PROVENANCE, GENERATED_WIDGETS, GTK_DESCRIPTORS, mergeGenerated, registerBuiltinWidgets, tableProvenance, } from './descriptors/index.js';