@gjsify/gtk-host 0.46.0 → 0.47.0

package/lib/esm/font-dir.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e=[`.ttf`,`.otf`,`.ttc`,`.otc`];function resolveFontDir(e={}){return nonEmpty(e.fontDir)??nonEmpty(e.env?.GJSIFY_FONT_DIR)}function isFontFace(t){let n=t.toLowerCase();return e.some(e=>n.endsWith(e))}function nonEmpty(e){if(e===void 0)return;let t=e.trim();return t===``?void 0:t}export{e as FONT_FACE_EXTENSIONS,isFontFace,resolveFontDir};

package/lib/esm/fonts.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{isFontFace as e,resolveFontDir as t}from"./font-dir.js";import n from"gi://GLib?version=2.0";import r from"gi://Gio?version=2.0";import i from"gi://PangoCairo?version=1.0";function isUnsupportedByFontMap(e){return e instanceof n.Error&&e.matches(r.io_error_quark(),r.IOErrorEnum.NOT_SUPPORTED)}function initFonts(e={}){let a=t({...e,env:{GJSIFY_FONT_DIR:n.getenv(`GJSIFY_FONT_DIR`)??void 0}}),o=[],s=[],c=[];if(a===void 0)return{dir:a,registered:o,declined:s,failed:c};let l=[];collectFaces(r.File.new_for_path(a),l,c);let u=i.FontMap.get_default();for(let e of l.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)})}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.`);return{dir:a,registered:o,declined:s,failed:c}}function collectFaces(t,n,i){try{let a=t.enumerate_children(`standard::name,standard::type`,r.FileQueryInfoFlags.NOFOLLOW_SYMLINKS,null);for(let t=a.next_file(null);t!==null;t=a.next_file(null)){let o=a.get_child(t),s=o.get_path();s!==null&&(t.get_file_type()===r.FileType.DIRECTORY?collectFaces(o,n,i):e(t.get_name())&&n.push(s))}}catch(e){i.push({path:t.get_path()??``,message:messageOf(e)})}}function messageOf(e){return e instanceof n.Error||e instanceof Error?e.message:String(e)}export{initFonts,isUnsupportedByFontMap};

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

@@ -0,0 +1,42 @@
+/**
+ * The desktop face extensions `gjsify ship` stages, lower-cased.
+ *
+ * The same four the writing half accepts (`discoverFonts`, ADR 0038), and deliberately not a
+ * shared constant: this package cannot depend on `@gjsify/cli` — wrong direction and wrong tier —
+ * so the pairing is a specification both ends implement rather than a value one imports.
+ *
+ * `.woff`/`.woff2`/`.eot` are absent from BOTH ends. The writer refuses them by name because
+ * whether FreeType opens one is `FT_CONFIG_OPTION_USE_BROTLI`, a build option of whichever
+ * FreeType the SHIPPED artifact loads rather than of the packaging host; a reader that accepted
+ * them would hand the font map a file it may decline on the target and nowhere else.
+ */
+export declare const FONT_FACE_EXTENSIONS: readonly string[];
+export interface ResolveFontDirOptions {
+    /** Wins over everything — a dev tree (`data/fonts`), or a test fixture. */
+    fontDir?: string;
+    /** Environment to read `GJSIFY_FONT_DIR` from. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Resolve the directory holding the application's shipped faces, or `undefined` when none is named.
+ *
+ * Precedence: explicit option, then `GJSIFY_FONT_DIR` — exported by the `gjsify ship` launcher,
+ * which is the only party that knows whether the payload became `/usr`, a `--prefix` tree, `/app`,
+ * a bundle's `Contents/Resources` or a Windows program directory.
+ *
+ * There is NO system fallback, and that is the one place this parts company with
+ * `resolveLocaleDir`, whose `/usr/share/locale` default is both correct and free. The analogous
+ * `/usr/share/fonts` is neither: fontconfig has already scanned it, so walking it again would add
+ * hundreds of `add_font_file` calls to every startup to arrive at families the font map holds
+ * anyway. `undefined` therefore means "this application ships no faces of its own" — the ordinary
+ * case, and a quiet one, because the launcher exports the variable only when it staged a face.
+ */
+export declare function resolveFontDir(options?: ResolveFontDirOptions): string | undefined;
+/**
+ * Is `name` a face {@link FONT_FACE_EXTENSIONS} covers?
+ *
+ * Extension-only and case-insensitive: `BRAND.TTF` is an ordinary name on the case-preserving
+ * filesystems macOS and Windows have, and a lowercase-only test would drop it into exactly the
+ * substituted-family failure this mechanism exists to prevent.
+ */
+export declare function isFontFace(name: string): boolean;

package/lib/types/font-dir.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/fonts.d.ts

@@ -0,0 +1,64 @@
+import { type ResolveFontDirOptions } from './font-dir.js';
+/** Everything {@link resolveFontDir} takes except the environment, which {@link initFonts} reads. */
+export type InitFontsOptions = Omit<ResolveFontDirOptions, 'env'>;
+/** A face the font map would not take, and why. */
+export interface FontFaceFailure {
+    readonly path: string;
+    readonly message: string;
+}
+/** What {@link initFonts} did, so a caller that cares can assert on it. */
+export interface InitFontsResult {
+    /** The directory that was read, or `undefined` when nothing named one. */
+    readonly dir: string | undefined;
+    /** Faces now on the default font map. */
+    readonly registered: readonly string[];
+    /** Faces the font map declined as unsupported — see {@link isUnsupportedByFontMap}. */
+    readonly declined: readonly string[];
+    /** Faces that failed for any other reason. Each was warned about; none threw. */
+    readonly failed: readonly FontFaceFailure[];
+}
+/**
+ * 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), it stays right if a fontconfig-backed Pango is ever selected on darwin — the backend
+ * is chosen by what is compiled in, not per platform, and `PANGOCAIRO_BACKEND=fc` selects one — and
+ * it stays right for any other map that declines. The OS name was never the thing being asked.
+ */
+export declare function isUnsupportedByFontMap(error: unknown): boolean;
+/**
+ * Register every face in the application's shipped font directory with the default font map.
+ *
+ * Call it once at startup, and BEFORE any text is laid out — that ordering is load-bearing on the
+ * 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`).
+ *
+ * Nothing here is eager: this
+ * package is the element model renderers bind to and owns no application lifecycle, and a
+ * module-load side effect would decide an application's initialisation order invisibly — the same
+ * reason `gjsify ship` stages the faces and names the directory instead of injecting the call.
+ *
+ * Total, like `installDevtools`: a face that will not open costs one stderr line and appears in
+ * {@link InitFontsResult.failed}, never an exception. 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, so it is loud and it is reported.
+ *
+ * Safe to call when the application ships no faces: `GJSIFY_FONT_DIR` is exported only when
+ * `gjsify ship` staged one, so an unset variable is the ordinary case and does nothing quietly.
+ */
+export declare function initFonts(options?: InitFontsOptions): InitFontsResult;

package/lib/types/fonts.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/gtk-host",
-    "version": "0.46.0",
+    "version": "0.47.0",
     "description": "Framework-agnostic GTK4/Adwaita host: the element model UI-framework renderers bind to",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -18,6 +18,10 @@
             "types": "./lib/types/list/index.d.ts",
             "default": "./lib/esm/list/index.js"
         },
+        "./fonts": {
+            "types": "./lib/types/fonts.d.ts",
+            "default": "./lib/esm/fonts.js"
+        },
         "./vue": {
             "types": "./lib/types/adapters/vue.d.ts",
             "default": "./lib/esm/adapters/vue.js"
@@ -93,7 +97,8 @@
         "@girs/glib-2.0": "4.6.0",
         "@girs/gobject-2.0": "4.6.0",
         "@girs/gtk-4.0": "4.6.0",
-        "@girs/pango-1.0": "4.6.0"
+        "@girs/pango-1.0": "4.6.0",
+        "@girs/pangocairo-1.0": "4.6.0"
     },
     "peerDependencies": {
         "@vue/runtime-core": "^3.5.0",
@@ -116,10 +121,10 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.46.0",
+        "@gjsify/cli": "^0.47.0",
         "@vue/runtime-core": "^3.5.0",
         "solid-js": "^1.9.0",
-        "@gjsify/unit": "^0.46.0",
+        "@gjsify/unit": "^0.47.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",