@gjsify/utils 0.53.0 → 0.54.0

package/lib/esm/font-map.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"gi://GLib?version=2.0";import t from"gi://Gio?version=2.0";import n from"gi://PangoCairo?version=1.0";import r from"gi://Pango?version=1.0";const i=1;function fontMapNamespace(){let e=n.FontMap;if(e!=null&&typeof e.get_default==`function`&&typeof e.new_for_font_type==`function`)return e}function isUnsupportedByFontMap(n){let r=e.Error,i=t.io_error_quark,a=t.IOErrorEnum?.NOT_SUPPORTED;return typeof r!=`function`||typeof i!=`function`||a===void 0||!(n instanceof r)?!1:n.matches(i(),a)}function fontErrorMessage(t){let n=e.Error;return typeof n==`function`&&t instanceof n?t.message??String(t):t instanceof Error?t.message:String(t)}function fontMapFamilies(e){return e.list_families().map(e=>e.get_name())}function fontMapHasFamily(e,t){return e.get_family(t)!==null}function layoutSize(e,t){let n=new r.FontDescription;n.set_family(t),n.set_size(40*r.SCALE);let i=r.Layout.new(e.create_context());return i.set_font_description(n),i.set_text(`Wg`,-1),i.get_pixel_size().join(`x`)}function fontMapServesFamily(e,t,n=layoutSize){return n(e,t)!==n(e,`ZzzGjsifySubstitutionControlQx`)}const a={map:null,before:[],failed:new Map,adopted:!1};function probeFontconfigMap(t,n,r,i=[]){if(r.length===0||e.getenv(`PANGOCAIRO_BACKEND`)!==null)return a;let o=t.new_for_font_type(1);if(o==null)return a;let s=fontMapFamilies(o);if(s.length===0)return a;let c=new Map;for(let e of r)try{o.add_font_file(e)}catch(t){c.set(e,fontErrorMessage(t))}let l=fontMapFamilies(o).filter(e=>!s.includes(e));if(l.length===0)return{map:o,before:s,failed:c,adopted:!1};let alreadyReached=e=>!i.includes(e)&&n.get_family(e)!==null;if(l.every(alreadyReached))return{map:o,before:s,failed:c,adopted:!1};let u=o.set_default;return typeof u==`function`?(u.call(o),{map:o,before:s,failed:c,adopted:!0}):{map:o,before:s,failed:c,adopted:!1}}function noRegistration(){return{available:!1,map:void 0,before:[],registered:[],declined:[],unreachable:[],failed:[],fontconfigFallback:!1}}function registerFontFaces(e,t){let n=fontMapNamespace();if(n===void 0)return noRegistration();let r=t??n.get_default();if(e.length===0)return{...noRegistration(),available:!0,map:r,before:fontMapFamilies(r)};let i=fontMapFamilies(r),a=[],o=[],s=[],c=[];for(let t of e)try{r.add_font_file(t),a.push(t)}catch(e){if(isUnsupportedByFontMap(e)){o.push(t);continue}c.push({path:t,message:fontErrorMessage(e)})}let l=[];a.length>0&&(l=fontMapFamilies(r).filter(e=>!i.includes(e)).filter(e=>!fontMapServesFamily(r,e)),l.length>0&&s.push(...a));let u=[...o,...s];if(u.length>0){let e=probeFontconfigMap(n,r,u,l),t=[];for(let n of o){let r=e.failed.get(n);r===void 0?e.adopted?a.push(n):t.push(n):c.push({path:n,message:r})}if(o.length=0,o.push(...t),e.adopted)s.length=0;else{let t=s.filter(t=>!e.failed.has(t));for(let t of s){let n=e.failed.get(t);n!==void 0&&c.push({path:t,message:n})}s.length=0,s.push(...t)}if(e.adopted&&e.map!==null)return{available:!0,map:e.map,before:e.before,registered:a,declined:o,unreachable:s,failed:c,fontconfigFallback:!0}}return{available:!0,map:r,before:i,registered:a,declined:o,unreachable:s,failed:c,fontconfigFallback:!1}}export{i as CAIRO_FONT_TYPE_FT,fontErrorMessage,fontMapFamilies,fontMapHasFamily,fontMapServesFamily,isUnsupportedByFontMap,registerFontFaces};

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

@@ -0,0 +1,164 @@
+import Pango from 'gi://Pango?version=1.0';
+/**
+ * `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`: 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.
+ */
+export declare const CAIRO_FONT_TYPE_FT = 1;
+/** A face the font map would not take, and why. */
+export interface FontFaceFailure {
+    readonly path: string;
+    readonly message: string;
+}
+/** What one {@link registerFontFaces} call did. */
+export interface FontFaceRegistration {
+    /**
+     * `false` where there is no Pango font map to register anything on at all — a `--app browser`
+     * bundle empties `gi://` (`plugins/gjs-imports-empty.ts`), and there a browser's OWN font
+     * machinery is what resolves a `FontFace`.
+     *
+     * Reported rather than left to be inferred from an empty outcome, because the two must not be
+     * reported alike: nothing was DECLINED on a browser, and a caller warning about a decline there
+     * would print a font warning per face in every web app.
+     */
+    readonly available: boolean;
+    /**
+     * The map in force afterwards — the adopted fontconfig one where the fallback ran, the `map` that
+     * was passed in otherwise. `undefined` when {@link available} is `false`.
+     *
+     * A caller registering more than one batch MUST thread this forward: after a swap the process
+     * default is the fontconfig map, and only this value knows.
+     */
+    readonly map: Pango.FontMap | undefined;
+    /**
+     * The family names the registering map held before any face was added — the BEFORE of a family
+     * diff. On the fallback path this is the CANDIDATE's list, because the diff has to be taken on
+     * the map that ends up in force or every family the two backends merely SPELL differently would
+     * be credited to this call.
+     */
+    readonly before: readonly string[];
+    /** Faces now on the map. */
+    readonly registered: readonly string[];
+    /**
+     * Faces no map here would take — see {@link isUnsupportedByFontMap}. A face in a shipped `.app`
+     * lands here and is CORRECT: the OS activated the directory before the process started.
+     */
+    readonly declined: readonly string[];
+    /**
+     * Faces this call put on the map that no layout can be served by — registered, `get_family`
+     * answers the family, and text asking for it still measures the fallback. A SUBSET of
+     * {@link registered}, and disjoint from {@link declined}.
+     *
+     * ITS OWN FIELD rather than a third bucket beside the two above, and the difference is what
+     * happened to the map. `declined` is a map that would not TAKE the face, which for a shipped
+     * `.app` is the correct outcome; a face here was TAKEN and then could not SERVE it. A caller
+     * reading `declined` tells its user that no font map would take this file and points at
+     * `ATSApplicationFontsPath` and `initFonts()` — advice that is wrong here, because the face is
+     * already on the map and re-running a registration cannot help. That is why the distinction is
+     * data rather than a comment: one is silent and correct, the other is loud and necessary, and
+     * a caller cannot tell them apart without laying text out itself.
+     *
+     * EMPTY where the fontconfig fallback took over, which is the whole point of it: then the faces
+     * render and there is nothing left to report.
+     */
+    readonly unreachable: readonly string[];
+    /** Faces that failed for any other reason, plus any the fontconfig map could not open either. */
+    readonly failed: readonly FontFaceFailure[];
+    /**
+     * `true` when this call REPLACED the process's default font map with a fontconfig-backed one.
+     *
+     * A whole-application consequence of one call — every widget created afterwards renders through
+     * FreeType instead of the platform rasteriser — so it is reported rather than inferred, and
+     * `PANGOCAIRO_BACKEND=coretext` gives the platform map back (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 Pango's base implementation, which answers `G_IO_ERROR_NOT_SUPPORTED`. That is
+ * not a failure to report: a shipped `.app` is already correct declaratively, because
+ * `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, and it stays right for any
+ * other map that declines — which stopped being hypothetical: the backend is whichever 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;
+/**
+ * The reported reason as a GError's `message`, never a stringified GError.
+ *
+ * `GLib.Error` is NOT `instanceof Error` under GJS — measured on gjs 1.88.1, where
+ * `GLib.Error.new_literal(…) instanceof Error` is `false`. A plain `instanceof Error` narrowing
+ * therefore misses EXACTLY the errors this module sees, and every diagnostic printed over them would
+ * silently degrade to `String(error)` — which is not obviously broken, only domain-prefixed.
+ */
+export declare function fontErrorMessage(error: unknown): string;
+/**
+ * The family names a font map currently holds.
+ *
+ * Typed `Pango.FontMap` and not `PangoCairo.FontMap`, which is what the call sites have:
+ * `pango_cairo_font_map_get_default()` is declared to RETURN the base type.
+ */
+export declare function fontMapFamilies(fontMap: Pango.FontMap): string[];
+/** Is `family` one this map can resolve? Pango's own answer, asked directly rather than inferred. */
+export declare function fontMapHasFamily(fontMap: Pango.FontMap, family: string): boolean;
+/**
+ * How {@link fontMapServesFamily} takes its reading: a value that is EQUAL for a family the map
+ * serves and for one it substitutes.
+ *
+ * A seam, so the decision can be held from a host that cannot produce the condition — the same
+ * discipline {@link isUnsupportedByFontMap} exists for, and the reason `font-map.spec.ts` can assert
+ * the decision on every leg instead of only where a poisoned map can be built.
+ */
+export type FontFamilyProbe = (fontMap: Pango.FontMap, family: string) => string;
+/**
+ * Does this map actually SERVE `family`, or does asking for it get the fallback?
+ *
+ * A LAYOUT, because that is the only reading that does not lie, and the readings that look cheaper
+ * were measured first (pango 1.58.2 / gjs 1.88.1, on the fc map Fedora has, reached here with
+ * `PANGOCAIRO_BACKEND=fontconfig`) on a map that had resolved the family to the fallback and then
+ * had the face registered on it:
+ *
+ *   `get_family(name)`                  answers it
+ *   `list_families()`                   contains it
+ *   `load_font(desc).describe()`        the requested family — from a FRESH context
+ *   `get_serial()`                      1, exactly as on an unpoisoned map
+ *   `Pango.Layout` pixel size           THE FALLBACK — 86x66, identical to an invented family
+ *
+ * So the map holds the face, hands the right font to a caller that asks for it by name, reports the
+ * same serial as a healthy map, and lays every glyph out in Verdana: a per-map-instance cache of the
+ * negative resolution, which `add_font_file` does not invalidate and which nothing in JS reaches.
+ * Warming a context with `load_font` first does not help (measured — still 86x66), and neither does a
+ * context created after the registration; only a map that never saw the question serves it, which is
+ * the fresh map {@link probeFontconfigMap} builds.
+ *
+ * Which is also why the equality is against a control family rather than against a fixed number: the
+ * fallback's metrics are the host's business (Verdana 86x66 here, 87x63 on the Fedora 44 leg), and a
+ * number pinned to one host's default sans would red everywhere else while proving nothing extra.
+ */
+export declare function fontMapServesFamily(fontMap: Pango.FontMap, family: string, probe?: FontFamilyProbe): boolean;
+/**
+ * Register faces on a font map, falling back to a fontconfig-backed one when that map DECLINES.
+ *
+ * `map` defaults to the process default and exists so a caller can keep a batch on the map a previous
+ * batch adopted — see {@link FontFaceRegistration.map}.
+ *
+ * Total: a face that will not open, or that no map here will take, is reported and never thrown.
+ * Taking an application down over a decorative face would be worse than rendering it in a fallback —
+ * but doing so SILENTLY is the defect this exists against (ADR 0038), so both are reported and the
+ * caller decides what to say about them.
+ */
+export declare function registerFontFaces(faces: readonly string[], map?: Pango.FontMap): FontFaceRegistration;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/utils",
-    "version": "0.53.0",
+    "version": "0.54.0",
     "description": "Utils module for gjsify",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -18,6 +18,10 @@
             "types": "./lib/types/core.d.ts",
             "default": "./lib/esm/core.js"
         },
+        "./font-map": {
+            "types": "./lib/types/font-map.d.ts",
+            "default": "./lib/esm/font-map.js"
+        },
         "./main-loop": {
             "types": "./lib/types/main-loop.d.ts",
             "default": "./lib/esm/main-loop.js"
@@ -32,6 +36,7 @@
         "check": "gjsify tsc --noEmit",
         "build": "gjsify run build:gjsify && gjsify run build:types",
         "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:esm": "gjsify tsc -p tsconfig.build.json",
         "build:types": "gjsify tsc",
         "build:test": "gjsify run build:test:gjs",
         "build:test:gjs": "gjsify build src/test.ts --app gjs --outfile test.gjs.js",
@@ -44,14 +49,16 @@
         "fs"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.53.0",
+        "@gjsify/cli": "^0.54.0",
         "typescript": "^6.0.3"
     },
     "dependencies": {
         "@girs/gio-2.0": "5.4.0",
         "@girs/giounix-2.0": "5.4.0",
         "@girs/gjs": "5.4.0",
-        "@girs/glib-2.0": "5.4.0"
+        "@girs/glib-2.0": "5.4.0",
+        "@girs/pango-1.0": "5.4.0",
+        "@girs/pangocairo-1.0": "5.4.0"
     },
     "license": "MIT",
     "repository": {
@@ -78,6 +85,12 @@
                 "browser": "polyfill",
                 "nativescript": "polyfill"
             },
+            "./font-map": {
+                "gjs": "polyfill",
+                "node": "polyfill",
+                "browser": "polyfill",
+                "nativescript": "polyfill"
+            },
             "./main-loop": {
                 "gjs": "polyfill",
                 "node": "polyfill",