@gjsify/gtk-host 0.53.0 → 0.54.0

package/lib/esm/fonts.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{isFontFace as e,resolveFontSources as t}from"./font-dir.js";import{describeFontFamilyMatch as n,matchFontFamilies as r,matchFontFamily as i}from"./font-families.js";import{ADWAITA_UI_FONT_FAMILY as a,GNOME_UI_FONT_POINT_SIZE as o,UI_FONT_POLICIES as s,planUiFont as c,planUiFontPolicy as l}from"./ui-font.js";import u from"gi://Gtk?version=4.0";import d from"gi://Gio?version=2.0";import f from"gi://GLib?version=2.0";import p from"gi://PangoCairo?version=1.0";function isUnsupportedByFontMap(e){return e instanceof f.Error&&e.matches(d.io_error_quark(),d.IOErrorEnum.NOT_SUPPORTED)}const m=1;function adoptFontconfigMap(e,t){if(t.length===0||f.getenv(`PANGOCAIRO_BACKEND`)!==null)return;let n=p.FontMap.new_for_font_type(1);if(n===null)return;let r=familyNames(n);if(r.length===0)return;let i=new Map;for(let e of t)try{n.add_font_file(e)}catch(t){i.set(e,messageOf(t))}if(!familyNames(n).filter(e=>!r.includes(e)).every(t=>e.get_family(t)!==null))return n.set_default(),{map:n,before:r,failed:i}}function initFonts(e={}){let i=t({...e,env:{GJSIFY_FONT_DIR:f.getenv(`GJSIFY_FONT_DIR`)??void 0,GJSIFY_GTK_RUNTIME_FONT_DIR:f.getenv(`GJSIFY_GTK_RUNTIME_FONT_DIR`)??void 0}}),a=i.find(e=>e.origin===`app`)?.dir,o=[],s=[],c=[],l=[],u=e.expectedFamilies??[];if(i.length===0&&u.length===0)return{dir:a,sources:o,uiFont:void 0,registered:s,declined:c,failed:l,families:[],matches:[],fontconfigFallback:!1};let m=p.FontMap.get_default(),h=i.length===0?[]:familyNames(m),g=i.map(e=>({source:e,registered:[],declined:[],failed:[]}));for(let e of g){let t=[];collectFaces(d.File.new_for_path(e.source.dir),t,e.failed);for(let n of t.sort())try{m.add_font_file(n),e.registered.push(n)}catch(t){if(isUnsupportedByFontMap(t)){e.declined.push(n);continue}e.failed.push({path:n,message:messageOf(t)})}}let _=adoptFontconfigMap(m,g.flatMap(e=>e.declined));if(_!==void 0){m=_.map,h=_.before;for(let e of g){let t=e.declined;e.declined=[];for(let n of t){let t=_.failed.get(n);t===void 0?e.registered.push(n):e.failed.push({path:n,message:t})}}}for(let e of g)s.push(...e.registered),c.push(...e.declined),l.push(...e.failed),o.push({...e.source,registered:e.registered,declined:e.declined,failed:e.failed});let v=familyNames(m),y=i.length===0?[]:v.filter(e=>!h.includes(e)).sort(),b=r(u,v);captureUiFontBaseline();let x=e.uiFont===void 0?void 0:applyUiFontPolicy(e.uiFont);for(let e of l)console.warn(`initFonts: ${e.path} could not be read as an application font (${e.message}). Text asking for a family this application ships will render in a substituted one.`);for(let e of b)e.kind!==`exact`&&console.warn(`initFonts: ${n(e)}`);return{dir:a,sources:o,uiFont:x,registered:s,declined:c,failed:l,families:y,matches:b,fontconfigFallback:_!==void 0}}let h=!1,g;function captureUiFontBaseline(){if(h)return g;let e=u.Settings.get_default();if(e!==null)return g=e.gtk_font_name??void 0,h=!0,g}function uiFontBaseline(){return captureUiFontBaseline()}function applyUiFontPolicy(e){let t=typeof e==`string`?{policy:e}:e,n=t.settings===void 0?u.Settings.get_default():t.settings;if(n===null)return console.warn("applyUiFontPolicy: no Gtk.Settings — the toolkit is not initialised yet, so the policy was NOT applied. Call this after Gtk.init() (or from an application's `startup`), which is still before any window is built."),{next:void 0,kind:`uninitialised`,family:void 0,size:void 0};let r=captureUiFontBaseline(),i=l({...t,family:t.family??resolvedAdwaitaFamily(t.policy),current:n.gtk_font_name??void 0,baseline:r});return i.next===void 0||(n.gtk_font_name=i.next),i}function resolvedAdwaitaFamily(e){if(e!==`adwaita`)return;let t=adwaitaUiFontAvailability();if(t.match.family!==void 0)return t.match.family;console.warn(`applyUiFontPolicy: "${t.family}" is ${t.match.kind} on this font map, so asking for it will render in a substituted family. Register the runtime bundle's faces with initFonts() first, and check adwaitaUiFontAvailability() before offering this policy.`)}function adwaitaUiFontAvailability(e=a){let t=i(e,familyNames(p.FontMap.get_default()));return{family:e,match:t,available:t.kind!==`absent`}}function familyNames(e){return e.list_families().map(e=>e.get_name())}function collectFaces(t,n,r){try{let i=t.enumerate_children(`standard::name,standard::type`,d.FileQueryInfoFlags.NOFOLLOW_SYMLINKS,null);for(let t=i.next_file(null);t!==null;t=i.next_file(null)){let a=i.get_child(t),o=a.get_path();o!==null&&(t.get_file_type()===d.FileType.DIRECTORY?collectFaces(a,n,r):e(t.get_name())&&n.push(o))}}catch(e){r.push({path:t.get_path()??``,message:messageOf(e)})}}function messageOf(e){return e instanceof f.Error||e instanceof Error?e.message:String(e)}export{a as ADWAITA_UI_FONT_FAMILY,m as CAIRO_FONT_TYPE_FT,o as GNOME_UI_FONT_POINT_SIZE,s as UI_FONT_POLICIES,adwaitaUiFontAvailability,applyUiFontPolicy,n as describeFontFamilyMatch,initFonts,isUnsupportedByFontMap,r as matchFontFamilies,i as matchFontFamily,c as planUiFont,l as planUiFontPolicy,t as resolveFontSources,uiFontBaseline};
+import"./_virtual/_rolldown/runtime.js";import{isFontFace as e,resolveFontSources as t}from"./font-dir.js";import{describeFontFamilyMatch as n,matchFontFamilies as r,matchFontFamily as i}from"./font-families.js";import{ADWAITA_UI_FONT_FAMILY as a,GNOME_UI_FONT_POINT_SIZE as o,UI_FONT_POLICIES as s,planUiFont as c,planUiFontPolicy as l}from"./ui-font.js";import u from"gi://Gtk?version=4.0";import d from"gi://Gio?version=2.0";import f from"gi://GLib?version=2.0";import p from"gi://PangoCairo?version=1.0";import{CAIRO_FONT_TYPE_FT as m,fontErrorMessage as h,fontMapFamilies as g,isUnsupportedByFontMap as _,registerFontFaces as v}from"@gjsify/utils/font-map";function initFonts(e={}){let i=t({...e,env:{GJSIFY_FONT_DIR:f.getenv(`GJSIFY_FONT_DIR`)??void 0,GJSIFY_GTK_RUNTIME_FONT_DIR:f.getenv(`GJSIFY_GTK_RUNTIME_FONT_DIR`)??void 0}}),a=i.find(e=>e.origin===`app`)?.dir,o=[],s=[],c=[],l=[],u=[],m=e.expectedFamilies??[];if(i.length===0&&m.length===0)return{dir:a,sources:o,uiFont:void 0,registered:s,declined:c,unreachable:l,failed:u,families:[],matches:[],fontconfigFallback:!1};let h=[],_=p.FontMap.get_default(),y=i.map(e=>({source:e,registered:[],declined:[],unreachable:[],failed:[]})),b=!1;for(let e of y){let t=[];collectFaces(d.File.new_for_path(e.source.dir),t,e.failed);let n=v(t.sort(),_);(h.length===0||n.fontconfigFallback)&&(h=n.before),n.fontconfigFallback&&(b=!0),n.map!==void 0&&(_=n.map),e.registered.push(...n.registered),e.declined.push(...n.declined),e.unreachable.push(...n.unreachable),e.failed.push(...n.failed)}for(let e of y)s.push(...e.registered),c.push(...e.declined),l.push(...e.unreachable),u.push(...e.failed),o.push({...e.source,registered:e.registered,declined:e.declined,unreachable:e.unreachable,failed:e.failed});let x=g(_),S=i.length===0?[]:x.filter(e=>!h.includes(e)).sort(),C=r(m,x);captureUiFontBaseline();let w=e.uiFont===void 0?void 0:applyUiFontPolicy(e.uiFont);for(let e of u)console.warn(`initFonts: ${e.path} could not be read as an application font (${e.message}). Text asking for a family this application ships will render in a substituted one.`);for(let e of l)console.warn(`initFonts: ${e} is registered and its family is on the font map, but text asking for it will still render substituted: the font map had already resolved that family to the fallback and the cached answer cannot be invalidated. Call initFonts() before any text is laid out.`);for(let e of C)e.kind!==`exact`&&console.warn(`initFonts: ${n(e)}`);return{dir:a,sources:o,uiFont:w,registered:s,declined:c,unreachable:l,failed:u,families:S,matches:C,fontconfigFallback:b}}let y=!1,b;function captureUiFontBaseline(){if(y)return b;let e=u.Settings.get_default();if(e!==null)return b=e.gtk_font_name??void 0,y=!0,b}function uiFontBaseline(){return captureUiFontBaseline()}function applyUiFontPolicy(e){let t=typeof e==`string`?{policy:e}:e,n=t.settings===void 0?u.Settings.get_default():t.settings;if(n===null)return console.warn("applyUiFontPolicy: no Gtk.Settings — the toolkit is not initialised yet, so the policy was NOT applied. Call this after Gtk.init() (or from an application's `startup`), which is still before any window is built."),{next:void 0,kind:`uninitialised`,family:void 0,size:void 0};let r=captureUiFontBaseline(),i=l({...t,family:t.family??resolvedAdwaitaFamily(t.policy),current:n.gtk_font_name??void 0,baseline:r});return i.next===void 0||(n.gtk_font_name=i.next),i}function resolvedAdwaitaFamily(e){if(e!==`adwaita`)return;let t=adwaitaUiFontAvailability();if(t.match.family!==void 0)return t.match.family;console.warn(`applyUiFontPolicy: "${t.family}" is ${t.match.kind} on this font map, so asking for it will render in a substituted family. Register the runtime bundle's faces with initFonts() first, and check adwaitaUiFontAvailability() before offering this policy.`)}function adwaitaUiFontAvailability(e=a){let t=i(e,g(p.FontMap.get_default()));return{family:e,match:t,available:t.kind!==`absent`}}function collectFaces(t,n,r){try{let i=t.enumerate_children(`standard::name,standard::type`,d.FileQueryInfoFlags.NOFOLLOW_SYMLINKS,null);for(let t=i.next_file(null);t!==null;t=i.next_file(null)){let a=i.get_child(t),o=a.get_path();o!==null&&(t.get_file_type()===d.FileType.DIRECTORY?collectFaces(a,n,r):e(t.get_name())&&n.push(o))}}catch(e){r.push({path:t.get_path()??``,message:h(e)})}}export{a as ADWAITA_UI_FONT_FAMILY,m as CAIRO_FONT_TYPE_FT,o as GNOME_UI_FONT_POINT_SIZE,s as UI_FONT_POLICIES,adwaitaUiFontAvailability,applyUiFontPolicy,n as describeFontFamilyMatch,initFonts,_ as isUnsupportedByFontMap,r as matchFontFamilies,i as matchFontFamily,c as planUiFont,l as planUiFontPolicy,t as resolveFontSources,uiFontBaseline};

package/lib/types/adapters/react.d.ts

@@ -7,12 +7,10 @@ export type ReactProps = Record<string, unknown>;
 /**
  * The HostConfig, exported because it IS the contract.
  *
- * `react.spec.ts` builds a second reconciler over a Proxy of this object to read
- * the member set the INSTALLED `react-reconciler` asks for, so a version that
- * starts asking for something new fails a test instead of returning `undefined`
- * in a commit. It is also the seam for a consumer who needs a differently
- * configured reconciler (a `LegacyRoot`, a different event priority) without
- * restating the mapping.
+ * `react.spec.ts` builds a second reconciler over a Proxy of this object to read the member set the
+ * INSTALLED `react-reconciler` asks for, so a version that starts asking for something new fails a
+ * test instead of returning `undefined` in a commit. It is also the seam for a consumer who needs
+ * a differently configured reconciler (a `LegacyRoot`, a different event priority).
  */
 export declare const gtkHostConfig: {
     supportsMutation: boolean;
@@ -31,15 +29,14 @@ export declare const gtkHostConfig: {
     /**
      * `false`, always — one text path instead of two.
      *
-     * `true` would tell React to skip text instances for this element and leave
-     * the string in `props.children` for the adapter to write. The host already
-     * owns that translation: a text NODE is concatenated into the descriptor's
-     * `textSink`, and a widget without one refuses text BY TAG NAME. Answering
-     * `true` would move that decision into the adapter, where it would be a
+     * `true` would tell React to skip text instances for this element and leave the string in
+     * `props.children` for the adapter to write. The host already owns that translation: a text NODE
+     * is concatenated into the descriptor's `textSink`, and a widget without one refuses text BY
+     * TAG NAME. Answering `true` would move that decision into the adapter, where it would be a
      * widget-knowledge test — the one thing ADR 0027 § 7 forbids an adapter.
      *
-     * It also keeps `resetTextContent` unreachable: React sets the `ContentReset`
-     * flag only when `shouldSetTextContent` was true for the PREVIOUS props.
+     * It also keeps `resetTextContent` unreachable: React sets the `ContentReset` flag only when
+     * `shouldSetTextContent` was true for the PREVIOUS props.
      */
     shouldSetTextContent: () => boolean;
     getRootHostContext: () => object;
@@ -60,14 +57,11 @@ export declare const gtkHostConfig: {
     /**
      * The priority an update gets when React is not already inside a lane.
      *
-     * React DOM derives this from the DOM event being handled (a click is
-     * discrete, a scroll continuous). A GTK signal handler is not a DOM event and
-     * there is no ambient event to read, so every update is a default-lane one —
-     * the same answer `react-art` and `react-nil` give. Consequence, stated
-     * because it is load-bearing: a `setState` from a GTK handler is CONCURRENT,
-     * so it lands when `scheduler` next runs, i.e. on the next GLib main-loop
-     * iteration. `flushSync` is the escape hatch, and the spec pumps the main
-     * context to prove the scheduled path works at all under GJS.
+     * React DOM derives this from the DOM event being handled (a click is discrete, a scroll
+     * continuous). A GTK signal handler is not a DOM event and there is no ambient event to read, so
+     * every update is a default-lane one — the same answer `react-art` and `react-nil` give.
+     * Consequence, stated because it is load-bearing: a `setState` from a GTK handler is CONCURRENT,
+     * so it lands when `scheduler` next runs, i.e. on the next GLib main-loop iteration.
      */
     resolveUpdatePriority: () => number;
     shouldAttemptEagerTransition: () => boolean;
@@ -81,30 +75,21 @@ export declare const gtkHostConfig: {
     removeChild: (_parent: HostElement, child: HostNode) => void;
     removeChildFromContainer: (_container: HostElement, child: HostNode) => void;
     /**
-     * React clears the root before its FIRST commit — and the application's own
-     * chrome must survive it.
+     * React clears the root before its FIRST commit, and the application's own chrome must survive it.
+     * In the DOM that discards leftover markup. Here the container is a widget the application
+     * built and filled, so this clears what the HOST put there (the shadow children) and never
+     * `el.foreign`, which `adopt` recorded precisely so placement can offset past it.
      *
-     * `updateHostRoot` sets the `Snapshot` flag whenever the previous render
-     * produced no child, and `commitBeforeMutationEffects` then calls this on the
-     * container. In the DOM that discards leftover markup. Here the container is a
-     * widget the application built and filled, so this clears what the HOST put
-     * there (the shadow children) and never `el.foreign`, which `adopt` recorded
-     * precisely so placement can offset past it.
-     *
-     * `destroy` rather than `remove`, for the same reason `removeChild` uses it:
-     * GJS blocks JS callbacks during GC, so a detached node keeps its handlers
-     * for the life of the process.
+     * `destroy` rather than `remove`, for the same reason `removeChild` uses it: GJS blocks JS
+     * callbacks during GC, so a detached node keeps its handlers for the life of the process.
      */
     clearContainer: (container: HostElement) => void;
     /**
      * Diff AND apply — one phase, because React 19 deleted the other one.
      *
-     * The argument list is the change with teeth: React 18 passed
-     * `(instance, updatePayload, type, prevProps, nextProps, handle)` and 19 passes
-     * `(instance, type, prevProps, nextProps, handle)`. The payload slot was
-     * removed from the FRONT, so an adapter that kept the old signature would read
-     * the type string as its payload and iterate a string — which is why this is
-     * spelled out rather than left to positional luck.
+     * The argument list is the change with teeth: React 19 removed the `updatePayload` slot from the
+     * FRONT, so an adapter that kept the old signature would read the type string as its payload
+     * and iterate a string.
      */
     commitUpdate: (instance: HostElement, _type: string, prevProps: ReactProps, nextProps: ReactProps) => void;
     commitTextUpdate: (textInstance: HostText, _oldText: string, newText: string) => void;

package/lib/types/attrs.d.ts

@@ -7,31 +7,28 @@ import type { HostNode } from './types.js';
 /**
  * A `notify::` handler.
  *
- * The host strips the emitting object (`next(...args.slice(1))` in `signals.ts`),
- * so what reaches the callback is the ParamSpec alone. Declared HERE rather than in
- * the generated file because it is the same for every property in GTK — and because
- * a generator that emitted it would have to import GObject for a type that has
- * nothing to do with the GIR it read.
+ * The host strips the emitting object, so what reaches the callback is the ParamSpec alone. Declared
+ * HERE rather than in the generated file because it is the same for every property in GTK — and a
+ * generator that emitted it would have to import GObject for a type that has nothing to do with
+ * the GIR it read.
  */
 export type NotifyHandler = (pspec: GObject.ParamSpec) => void;
 declare const outParam: unique symbol;
 /**
  * A signal parameter GIR declares `out`/`inout` with `caller-allocates="0"`.
  *
- * GJS still passes an argument in that position, and what it holds is whatever
- * was in the memory the marshaller allocated: measured on gjs 1.88.1 / GTK
- * 4.22.4, a handler on `Gtk.SpinButton::input` receives `new_value` as
- * `6.9526682391035e-310`, and one on `Gtk.Editable::insert-text` receives
- * `position` as `1711500784`. Both arrive as ordinary numbers. Nothing warns.
+ * GJS still passes an argument in that position, and what it holds is whatever was in the memory
+ * the marshaller allocated: measured on gjs 1.88.1 / GTK 4.22.4, a handler on
+ * `Gtk.SpinButton::input` receives `new_value` as `6.9526682391035e-310`, and one on
+ * `Gtk.Editable::insert-text` receives `position` as `1711500784`. Both arrive as ordinary numbers.
+ * Nothing warns.
  *
- * So the slot is DECLARED — dropping it would silently shift every parameter
- * after it — and given a type nothing can be read out of, and nothing but
- * itself assigns to. Annotating the parameter `number` is then a compile error
- * naming the position, which is the only place a reader would have looked.
+ * So the slot is DECLARED — dropping it would silently shift every parameter after it — and given
+ * a type nothing can be read out of, and nothing but itself assigns to. Annotating the parameter
+ * `number` is then a compile error naming the position.
  *
- * `caller-allocates="1"` is a different thing and keeps its real type: there the
- * callee is handed a live object to FILL, as `Gtk.Overlay::get-child-position`
- * is handed a `Gdk.Rectangle`.
+ * `caller-allocates="1"` is a different thing and keeps its real type: there the callee is handed
+ * a live object to FILL, as `Gtk.Overlay::get-child-position` is handed a `Gdk.Rectangle`.
  */
 export type OutParam = {
     readonly [outParam]: never;
@@ -39,10 +36,9 @@ export type OutParam = {
 /**
  * What may appear as a child, mirroring Solid's own `JSX.Element`.
  *
- * The shape is copied from `solid-js/types/jsx.d.ts` because a renderer's element
- * union is not a free choice: a string, a number and a boolean are all legal
- * children there, an array of children is legal recursively, and a FUNCTION is
- * not. Substituting our host node for the DOM's `Node` is the only change.
+ * The shape is copied from `solid-js/types/jsx.d.ts` because a renderer's element union is not a free
+ * choice: a string, a number and a boolean are all legal children there, an array of children is
+ * legal recursively, and a FUNCTION is not.
  */
 export type ElementChild = HostNode | ElementChildren | string | number | boolean | null | undefined;
 export interface ElementChildren extends Array<ElementChild> {
@@ -50,10 +46,9 @@ export interface ElementChildren extends Array<ElementChild> {
 /**
  * Add the `.once` spelling of every event prop, without generating 2× the members.
  *
- * `signals.ts` accepts `onClickedOnce` for every `onClicked`, including every
- * `onNotifyFooOnce`, which would be another ~1000 generated members. A mapped type
- * derives them from the interface instead — including the ones a consumer adds by
- * declaration merging.
+ * `signals.ts` accepts `onClickedOnce` for every `onClicked`, including every `onNotifyFooOnce`,
+ * which would be another ~1000 generated members. A mapped type derives them from the interface
+ * instead — including the ones a consumer adds by declaration merging.
  */
 export type WithOnce<T> = T & {
     [K in keyof T & string as K extends `on${string}` ? `${K}Once` : never]?: T[K];
@@ -65,11 +60,11 @@ export interface SlotAttribute {
 /**
  * GTK's ARIA surface, on every element of every dialect. Read by `setAccessibility()`.
  *
- * ONE OBJECT, not 53 flat `aria*` props, and the four reasons are in `setAccessibility`'s
- * own header — the load-bearing one being that TypeScript exempts a hyphenated JSX
- * attribute from excess-property checking while a key in a fresh object literal is
- * checked. `AccessibilityAttributes` is GENERATED, because the names and their value
- * types are GTK's and are stated nowhere a ParamSpec can be read from.
+ * ONE OBJECT, not 53 flat `aria*` props, and the four reasons are in `setAccessibility`'s own
+ * header — the load-bearing one being that TypeScript exempts a hyphenated JSX attribute from
+ * excess-property checking while a key in a fresh object literal is checked.
+ * `AccessibilityAttributes` is GENERATED, because the names and their value types are GTK's and are
+ * stated nowhere a ParamSpec can be read from.
  */
 export interface AccessibilityAttribute {
     accessibility?: AccessibilityAttributes | null;
@@ -77,12 +72,10 @@ export interface AccessibilityAttribute {
 /**
  * The `on:<raw-signal-name>` escape hatch, typed.
  *
- * `parseEventProp` takes `on:` + a signal name verbatim, which is how a signal
- * whose name resists the camelCase derivation gets bound at all. The handler type
- * is deliberately the widest one that is not `any`: parameters of `never` accept
- * a handler declared with any parameters, so nothing a consumer writes is refused.
- * An inline arrow's parameter arrives as `never` here, which is the price of an
- * escape hatch that carries no signal-specific knowledge.
+ * `parseEventProp` takes `on:` + a signal name verbatim, which is how a signal whose name resists
+ * the camelCase derivation gets bound at all. The handler type is deliberately the widest one that
+ * is not `any`: parameters of `never` accept a handler declared with any parameters, so nothing a
+ * consumer writes is refused.
  */
 export interface RawSignalAttributes {
     [key: `on:${string}`]: ((...args: never[]) => unknown) | undefined;
@@ -107,25 +100,20 @@ export interface JsxAttributes<T> extends AccessibilityAttribute, SlotAttribute,
 /**
  * Per-element attributes for Vue.
  *
- * Deliberately NOT `JsxAttributes`: Vue supplies `ref` and `key` itself through
- * `VNodeProps`, which every registered component's props are intersected with.
- * Declaring our own `ref` would intersect two different `ref` types and could
- * leave the property unusable, so the Vue surface adds only what Vue does not —
- * and `children` is a SLOT in Vue, never a prop.
+ * Deliberately NOT `JsxAttributes`: Vue supplies `ref` and `key` itself through `VNodeProps`, which
+ * every registered component's props are intersected with. Declaring our own `ref` would intersect
+ * two different `ref` types and could leave the property unusable.
  */
 export interface VueAttributes extends AccessibilityAttribute, SlotAttribute, RawSignalAttributes {
 }
 /**
  * The properties whose GObject type is a `GMenuModel`, in both spellings.
  *
- * A NAME LIST, not a type test, and the reason is measured rather than stylistic: the
- * obvious `Gio.MenuModel extends NonNullable<T[K]> ? …` also matches every property
- * typed as a wider GObject — `Gio.MenuModel extends GObject.Object` is TRUE — so the
- * widening would leak onto properties that take an entirely different object. The three
- * names below are the whole set on the shipped table (`menu-model` on the two menu
- * buttons, the popover menu and the menu bar; `extra-menu` on the text widgets;
- * `secondary-menu` on `AdwToolbarView`'s header bar), and `type-tests/` holds the
- * widening against real markup in both dialects.
+ * A NAME LIST, not a type test, and the reason is measured: the obvious `Gio.MenuModel extends
+ * NonNullable<T[K]> ? …` also matches every property typed as a wider GObject — `Gio.MenuModel
+ * extends GObject.Object` is TRUE — so the widening would leak onto properties that take an
+ * entirely different object. The names below are the whole set on the shipped table, and
+ * `type-tests/` holds the widening against real markup in both dialects.
  */
 type MenuModelProp = 'menuModel' | 'menu-model' | 'extraMenu' | 'extra-menu' | 'secondaryMenu' | 'secondary-menu';
 /**

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.
@@ -135,7 +154,7 @@ export interface InitFontsResult {
     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 {@link adoptFontconfigMap}.
+     * 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
@@ -145,42 +164,6 @@ export interface InitFontsResult {
      */
     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;
-/**
- * `CAIRO_FONT_TYPE_FT` from `cairo.h` — the value `pango_cairo_font_map_new_for_font_type()` maps
- * to its fontconfig backend.
- *
- * A literal rather than `gi://cairo`'s `FontType.FT`: this module runs on both legs (GJS and
- * `@gjsify/node-gi`), and the enum is part of cairo's ABI, so importing a fourth namespace to
- * spell one stable integer would add a load-time dependency for nothing.
- *
- * Exported so `fonts.spec.ts`'s independent probe spells the SAME integer rather than a second
- * literal that could drift from this one silently — see § duplication instead of a helper.
- */
-export declare const CAIRO_FONT_TYPE_FT = 1;
 /**
  * Register every face in the application's shipped font directory with the default font map.
  *
@@ -188,8 +171,11 @@ export declare const CAIRO_FONT_TYPE_FT = 1;
  * 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;
 /**