@gjsify/gtk-host 0.51.0 → 0.51.1

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)}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=e.expectedFamilies??[];if(i.length===0&&l.length===0)return{dir:a,sources:i,uiFont:void 0,registered:o,declined:s,failed:c,families:[],matches:[]};let u=p.FontMap.get_default(),m=i.length===0?[]:familyNames(u);for(let e of i){let t=[];collectFaces(d.File.new_for_path(e.dir),t,c);for(let e of t.sort())try{u.add_font_file(e),o.push(e)}catch(t){if(isUnsupportedByFontMap(t)){s.push(e);continue}c.push({path:e,message:messageOf(t)})}}let h=familyNames(u),g=i.length===0?[]:h.filter(e=>!m.includes(e)).sort(),_=r(l,h);captureUiFontBaseline();let v=e.uiFont===void 0?void 0:applyUiFontPolicy(e.uiFont);for(let e of c)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 _)e.kind!==`exact`&&console.warn(`initFonts: ${n(e)}`);return{dir:a,sources:i,uiFont:v,registered:o,declined:s,failed:c,families:g,matches:_}}let m=!1,h;function captureUiFontBaseline(){if(m)return h;let e=u.Settings.get_default();if(e!==null)return h=e.gtk_font_name??void 0,m=!0,h}function uiFontBaseline(){return captureUiFontBaseline()}function applyUiFontPolicy(e){let t=typeof e==`string`?{policy:e}:e,n=u.Settings.get_default();if(n===null)return{next:void 0,kind:`unparsed`,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,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";function isUnsupportedByFontMap(e){return e instanceof f.Error&&e.matches(d.io_error_quark(),d.IOErrorEnum.NOT_SUPPORTED)}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:[]};let m=p.FontMap.get_default(),h=i.length===0?[]:familyNames(m);for(let e of i){let t=[],n=[],r=[],i=[];collectFaces(d.File.new_for_path(e.dir),t,i);for(let e of t.sort())try{m.add_font_file(e),n.push(e)}catch(t){if(isUnsupportedByFontMap(t)){r.push(e);continue}i.push({path:e,message:messageOf(t)})}s.push(...n),c.push(...r),l.push(...i),o.push({...e,registered:n,declined:r,failed:i})}let g=familyNames(m),_=i.length===0?[]:g.filter(e=>!h.includes(e)).sort(),v=r(u,g);captureUiFontBaseline();let y=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 v)e.kind!==`exact`&&console.warn(`initFonts: ${n(e)}`);return{dir:a,sources:o,uiFont:y,registered:s,declined:c,failed:l,families:_,matches:v}}let m=!1,h;function captureUiFontBaseline(){if(m)return h;let e=u.Settings.get_default();if(e!==null)return h=e.gtk_font_name??void 0,m=!0,h}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,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};

package/lib/types/fonts.d.ts

@@ -1,3 +1,4 @@
+import Gtk from 'gi://Gtk?version=4.0';
 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';
@@ -40,6 +41,29 @@ export interface FontFaceFailure {
     readonly path: string;
     readonly message: string;
 }
+/**
+ * A {@link FontSource} and the faces IT contributed.
+ *
+ * WHY THE ATTRIBUTION IS PART OF THE RESULT rather than something a caller re-derives. Since the
+ * GTK runtime bundle started carrying the GNOME UI typeface there are TWO sources, and the flat
+ * {@link InitFontsResult.registered}, {@link InitFontsResult.declined} and
+ * {@link InitFontsResult.failed} lists span both — so "did MY staged face arrive" stopped being
+ * answerable from them the day a published bundle gained a face, silently, with no caller
+ * changing a line. The loop that hands each file to the font map is the only place that knows
+ * which directory it came from; anything downstream is reduced to comparing path prefixes, which
+ * is a guess about filesystem layout rather than a measurement.
+ *
+ * The same argument {@link InitFontsResult.families} makes about the family diff, one field over:
+ * only the call that did the work is in a position to take the reading.
+ */
+export interface FontSourceOutcome extends FontSource {
+    /** Faces from THIS directory now on the default font map. */
+    readonly registered: readonly string[];
+    /** Faces from THIS directory the font map declined — see {@link isUnsupportedByFontMap}. */
+    readonly declined: readonly string[];
+    /** Faces from THIS directory that failed otherwise, plus the directory itself if unreadable. */
+    readonly failed: readonly FontFaceFailure[];
+}
 /** What {@link initFonts} did, so a caller that cares can assert on it. */
 export interface InitFontsResult {
     /**
@@ -50,8 +74,16 @@ export interface InitFontsResult {
      * answering `true` because the platform's were. {@link sources} is the full list.
      */
     readonly dir: string | undefined;
-    /** Every directory registered, runtime first. See {@link FontSource}. */
-    readonly sources: readonly FontSource[];
+    /**
+     * Every directory registered, runtime first, and what each one contributed.
+     *
+     * THE ONLY PLACE A FACE IS ATTRIBUTED TO A DIRECTORY. Read this, not the flat lists below,
+     * whenever the question is about ONE source — "did the face I staged arrive", "did the
+     * runtime bundle bring its own" — because the flat lists answer for all of them at once and
+     * their counts move whenever a published bundle changes what it carries. See
+     * {@link FontSourceOutcome}.
+     */
+    readonly sources: readonly FontSourceOutcome[];
     /**
      * What the UI-font-size policy did, or `undefined` when it did not run.
      *
@@ -59,11 +91,17 @@ export interface InitFontsResult {
      * there, so the default leaves `gtk-font-name` alone entirely.
      */
     readonly uiFont: UiFontPlan | undefined;
-    /** Faces now on the default font map. */
+    /** Faces now on the default font map, ACROSS EVERY {@link sources} entry. */
     readonly registered: readonly string[];
-    /** Faces the font map declined as unsupported — see {@link isUnsupportedByFontMap}. */
+    /**
+     * Faces the font map declined as unsupported, across every {@link sources} entry — see
+     * {@link isUnsupportedByFontMap}.
+     */
     readonly declined: readonly string[];
-    /** Faces that failed for any other reason. Each was warned about; none threw. */
+    /**
+     * Faces that failed for any other reason, across every {@link sources} entry. Each was warned
+     * about; none threw.
+     */
     readonly failed: readonly FontFaceFailure[];
     /**
      * The family names the default font map GAINED across this call, sorted.
@@ -144,6 +182,14 @@ export declare function initFonts(options?: InitFontsOptions): InitFontsResult;
 /** Everything {@link planUiFontPolicy} takes except what this module supplies itself. */
 export interface ApplyUiFontPolicyOptions extends PlanUiFontOptions {
     readonly policy: UiFontPolicy;
+    /**
+     * The settings object to act on. Defaults to `Gtk.Settings.get_default()`.
+     *
+     * A seam, not a knob: the null arm below is the one a real consumer hit, and on a host with a
+     * display there is no way to reach it through the default — `get_default()` never answers null
+     * once GTK is up. Passing `null` explicitly is how the test for it exists at all.
+     */
+    readonly settings?: Gtk.Settings | null;
 }
 /**
  * `gtk-font-name` as this process first found it — what the `system` policy restores.
@@ -165,10 +211,15 @@ export declare function uiFontBaseline(): string | undefined;
  * captured before the first write, which is why switching `adwaita` → `system` at runtime
  * returns the host's own `Segoe UI 9` rather than an approximation of it.
  *
- * `Gtk.Settings.get_default()` answers null before `Gtk.init()`, and that is a legitimate state
- * rather than an error: a program may register its faces before it initialises the toolkit. It
- * reports `unparsed` — the arm that already means "nothing to act on, so nothing changed" —
- * instead of throwing a caller out of a font call over a setting.
+ * `Gtk.Settings.get_default()` answers null before `Gtk.init()`. That is not an error to throw
+ * over — a program may register its faces before it initialises the toolkit — but it is NOT the
+ * same answer as "the policy ran and had nothing to do", and reporting it as `unparsed` said it
+ * was. A consumer that called this at module scope got a plan indistinguishable from a host that
+ * needed no correction, so its setting silently did nothing: measured in Learn6502 0.8.0, where
+ * `ui-font: policy=size -> unparsed (unchanged)` was printed on macOS and on Windows — the one
+ * platform whose 16 px against GNOME's 19 is the reason the policy exists. It now reports
+ * `uninitialised` and says so once, because a caller that is too early can only find out from
+ * here.
  */
 export declare function applyUiFontPolicy(request: UiFontPolicy | ApplyUiFontPolicyOptions): UiFontPlan;
 /**

package/lib/types/ui-font.d.ts

@@ -21,7 +21,7 @@ export type UiFontPolicy = 'system' | 'size' | 'adwaita';
  */
 export declare const UI_FONT_POLICIES: readonly UiFontPolicy[];
 /** The reasons a plan gives. See {@link UiFontPlan.kind}. */
-export type UiFontPlanKind = 'raised' | 'family' | 'restored' | 'kept' | 'unparsed';
+export type UiFontPlanKind = 'raised' | 'family' | 'restored' | 'kept' | 'unparsed' | 'uninitialised';
 /** What {@link planUiFont} or {@link planUiFontPolicy} decided, and why. */
 export interface UiFontPlan {
     /** The `gtk-font-name` to set, or `undefined` when nothing should change. */
@@ -31,7 +31,17 @@ export interface UiFontPlan {
      * `family` — a family override was asked for and applied;
      * `restored` — the host's ORIGINAL value is being put back (the `system` policy);
      * `kept` — nothing to do: the setting already says what the policy wants;
-     * `unparsed` — the current value carries no point size this can reason about.
+     * `unparsed` — the current value carries no point size this can reason about;
+     * `uninitialised` — there was no `Gtk.Settings` to act on, so the policy did NOT run.
+     *
+     * THE LAST TWO ARE NOT THE SAME ANSWER and used to be reported as one. Both leave
+     * `gtk-font-name` alone, which is why collapsing them looked harmless — but `unparsed` means
+     * the policy ran and correctly declined, while `uninitialised` means it never ran at all. A
+     * consumer that calls this before `Gtk.init()` gets a plan that reads exactly like a host
+     * that needed nothing, so the setting it built is dead and its own log line says so in words
+     * that look fine. Learn6502 shipped that: `ui-font: policy=size -> unparsed (unchanged)` on
+     * macOS AND Windows, from a call at module scope, with the size correction never applied on
+     * the one platform it exists for.
      */
     readonly kind: UiFontPlanKind;
     /** The family in effect after the plan, for reporting. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/gtk-host",
-    "version": "0.51.0",
+    "version": "0.51.1",
     "description": "Framework-agnostic GTK4/Adwaita host: the element model UI-framework renderers bind to",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -101,7 +101,7 @@
         "@girs/gtk-4.0": "5.0.0",
         "@girs/pango-1.0": "5.0.0",
         "@girs/pangocairo-1.0": "5.0.0",
-        "@gjsify/adwaita-core": "^0.51.0"
+        "@gjsify/adwaita-core": "^0.51.1"
     },
     "peerDependencies": {
         "@vue/runtime-core": "^3.5.0",
@@ -124,10 +124,10 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.51.0",
+        "@gjsify/cli": "^0.51.1",
         "@vue/runtime-core": "^3.5.0",
         "solid-js": "^1.9.0",
-        "@gjsify/unit": "^0.51.0",
+        "@gjsify/unit": "^0.51.1",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",