@gjsify/gtk-host 0.50.0 → 0.51.0

package/lib/esm/font-dir.js

@@ -1 +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};
+import"./_virtual/_rolldown/runtime.js";const e=[`.ttf`,`.otf`,`.ttc`,`.otc`];function resolveFontSources(e={}){let t=nonEmpty(e.runtimeFontDir)??nonEmpty(e.env?.GJSIFY_GTK_RUNTIME_FONT_DIR),n=resolveFontDir(e),r=[];return t!==void 0&&r.push({dir:t,origin:`runtime`}),n!==void 0&&n!==t&&r.push({dir:n,origin:`app`}),r}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,resolveFontSources};

package/lib/esm/font-families.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";const e=/^(.*\S)\s\d+pt$/,fold=e=>e.trim().toLowerCase();function matchFontFamily(t,n){let r=fold(t),i=n.find(e=>fold(e)===r);if(i!==void 0)return{declared:t,family:i,kind:`exact`,candidates:[i]};let a=n.filter(t=>{let n=e.exec(t);return n!==null&&fold(n[1])===r});if(a.length===1)return{declared:t,family:a[0],kind:`optical`,candidates:a};if(a.length>1)return{declared:t,family:void 0,kind:`ambiguous`,candidates:a};let o=e.exec(t.trim());if(o!==null){let e=n.find(e=>fold(e)===fold(o[1]));if(e!==void 0)return{declared:t,family:e,kind:`optical`,candidates:[e]}}return{declared:t,family:void 0,kind:`absent`,candidates:[]}}function matchFontFamilies(e,t){return e.map(e=>matchFontFamily(e,t))}function describeFontFamilyMatch(e){switch(e.kind){case`exact`:return`${e.declared}: on the font map under that name`;case`optical`:return`${e.declared}: on the font map as "${e.family}" — this font stack keeps the optical-size axis in the family name, so the declared name resolves to nothing and Pango substitutes the default sans without a word. Ask for the name on the right.`;case`ambiguous`:return`${e.declared}: the font map carries ${e.candidates.length} optical sizes of it (${e.candidates.join(`, `)}) and no family under the declared name. Which one to use at which point size is a design decision, so nothing here picks for you.`;case`absent`:return`${e.declared}: NOT on the font map. Text asking for it renders in a substituted family — Pango does not report a missing family, so nothing else will say so.`}}export{describeFontFamilyMatch,matchFontFamilies,matchFontFamily};
+import"./_virtual/_rolldown/runtime.js";const e=/^(.*\S)\s(?:\d+pt|Text|Caption|Subhead|Banner)$/i,fold=e=>e.trim().toLowerCase();function matchFontFamily(t,n){let r=fold(t),i=n.find(e=>fold(e)===r);if(i!==void 0)return{declared:t,family:i,kind:`exact`,candidates:[i]};let a=n.filter(t=>{let n=e.exec(t);return n!==null&&fold(n[1])===r});if(a.length===1)return{declared:t,family:a[0],kind:`optical`,candidates:a};if(a.length>1)return{declared:t,family:void 0,kind:`ambiguous`,candidates:a};let o=e.exec(t.trim());if(o!==null){let e=n.find(e=>fold(e)===fold(o[1]));if(e!==void 0)return{declared:t,family:e,kind:`optical`,candidates:[e]}}return{declared:t,family:void 0,kind:`absent`,candidates:[]}}function matchFontFamilies(e,t){return e.map(e=>matchFontFamily(e,t))}function describeFontFamilyMatch(e){switch(e.kind){case`exact`:return`${e.declared}: on the font map under that name`;case`optical`:return`${e.declared}: on the font map as "${e.family}" — this font stack keeps the optical-size axis in the family name, so the declared name resolves to nothing and Pango substitutes the default sans without a word. Ask for the name on the right.`;case`ambiguous`:return`${e.declared}: the font map carries ${e.candidates.length} optical sizes of it (${e.candidates.join(`, `)}) and no family under the declared name. Which one to use at which point size is a design decision, so nothing here picks for you.`;case`absent`:return`${e.declared}: NOT on the font map. Text asking for it renders in a substituted family — Pango does not report a missing family, so nothing else will say so.`}}export{describeFontFamilyMatch,matchFontFamilies,matchFontFamily};

package/lib/esm/fonts.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{isFontFace as e,resolveFontDir as t}from"./font-dir.js";import{describeFontFamilyMatch as n,matchFontFamilies as r,matchFontFamily as i}from"./font-families.js";import a from"gi://Gio?version=2.0";import o from"gi://GLib?version=2.0";import s from"gi://PangoCairo?version=1.0";function isUnsupportedByFontMap(e){return e instanceof o.Error&&e.matches(a.io_error_quark(),a.IOErrorEnum.NOT_SUPPORTED)}function initFonts(e={}){let i=t({...e,env:{GJSIFY_FONT_DIR:o.getenv(`GJSIFY_FONT_DIR`)??void 0}}),c=[],l=[],u=[],d=e.expectedFamilies??[];if(i===void 0&&d.length===0)return{dir:i,registered:c,declined:l,failed:u,families:[],matches:[]};let f=s.FontMap.get_default(),p=i===void 0?[]:familyNames(f);if(i!==void 0){let e=[];collectFaces(a.File.new_for_path(i),e,u);for(let t of e.sort())try{f.add_font_file(t),c.push(t)}catch(e){if(isUnsupportedByFontMap(e)){l.push(t);continue}u.push({path:t,message:messageOf(e)})}}let m=familyNames(f),h=i===void 0?[]:m.filter(e=>!p.includes(e)).sort(),g=r(d,m);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 g)e.kind!==`exact`&&console.warn(`initFonts: ${n(e)}`);return{dir:i,registered:c,declined:l,failed:u,families:h,matches:g}}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`,a.FileQueryInfoFlags.NOFOLLOW_SYMLINKS,null);for(let t=i.next_file(null);t!==null;t=i.next_file(null)){let o=i.get_child(t),s=o.get_path();s!==null&&(t.get_file_type()===a.FileType.DIRECTORY?collectFaces(o,n,r):e(t.get_name())&&n.push(s))}}catch(e){r.push({path:t.get_path()??``,message:messageOf(e)})}}function messageOf(e){return e instanceof o.Error||e instanceof Error?e.message:String(e)}export{n as describeFontFamilyMatch,initFonts,isUnsupportedByFontMap,r as matchFontFamilies,i as matchFontFamily};
+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};

package/lib/esm/ui-font.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e=11,t=`Adwaita Sans`,n=[`system`,`size`,`adwaita`];function planUiFont(e,t={}){let n=t.size??11,r=(e??``).trim(),i=/^(.*\S)\s+(\d+(?:\.\d+)?)$/.exec(r);if(i===null)return{next:void 0,kind:`unparsed`,family:r===``?void 0:r,size:void 0};let a=i[1],o=Number.parseFloat(i[2]),s=t.family??a,c=o<n?n:o;return s===a&&c===o?{next:void 0,kind:`kept`,family:a,size:o}:{next:`${s} ${String(c)}`,kind:t.family!==void 0&&t.family!==a?`family`:`raised`,family:s,size:c}}function planUiFontPolicy(e){let{policy:t,current:n,baseline:r}=e;if(t===`system`)return r===void 0?{next:void 0,kind:`kept`,family:void 0,size:void 0}:r===n?describe(r,`kept`):describe(r,`restored`);if(t===`size`)return planUiFont(n,{size:e.size,family:e.family});let i=e.family??`Adwaita Sans`,a=e.size??11,o=`${i} ${String(a)}`;return o===(n??``).trim()?{next:void 0,kind:`kept`,family:i,size:a}:{next:o,kind:`family`,family:i,size:a}}function describe(e,t){let n=/^(.*\S)\s+(\d+(?:\.\d+)?)$/.exec(e.trim());return{next:t===`kept`?void 0:e,kind:t,family:n?n[1]:e.trim()||void 0,size:n?Number.parseFloat(n[2]):void 0}}export{t as ADWAITA_UI_FONT_FAMILY,e as GNOME_UI_FONT_POINT_SIZE,n as UI_FONT_POLICIES,planUiFont,planUiFontPolicy};

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

@@ -17,6 +17,36 @@ export interface ResolveFontDirOptions {
     /** Environment to read `GJSIFY_FONT_DIR` from. */
     env?: Record<string, string | undefined>;
 }
+/** A directory of faces, and who put it there. */
+export interface FontSource {
+    readonly dir: string;
+    /**
+     * `runtime` = the GTK runtime bundle's own faces (the GNOME UI typeface, shipped by
+     * `@gjsify/gtk-runtime-<target>` and named by `@gjsify/node-gi`'s loader);
+     * `app` = the faces THIS application staged with `gjsify ship`.
+     */
+    readonly origin: 'runtime' | 'app';
+}
+export interface ResolveFontSourcesOptions extends ResolveFontDirOptions {
+    /** Wins over `GJSIFY_GTK_RUNTIME_FONT_DIR` — a bundle checkout, or a test fixture. */
+    runtimeFontDir?: string;
+}
+/**
+ * Every directory of faces this process should register, RUNTIME first.
+ *
+ * TWO SOURCES, NOT ONE, and they answer different questions. `GJSIFY_FONT_DIR` is the
+ * application's own brand face, staged by `gjsify ship` (ADR 0038).
+ * `GJSIFY_GTK_RUNTIME_FONT_DIR` is the GNOME UI typeface the GTK runtime bundle carries,
+ * because off Linux nothing installs it: measured on Windows 11 against the published 0.50.0
+ * bundle, `Adwaita Sans 11` and `Cantarell 11` both resolve to Tahoma, and Pango reports that
+ * substitution by rendering it. An application must never have to choose between its own face
+ * and the platform's, which is why this is a second variable rather than a contested one.
+ *
+ * RUNTIME FIRST, so the platform faces are on the map before an application's — the order the
+ * two were designed in. Duplicates collapse: pointing both variables at one directory
+ * registers it once instead of handing every face to `add_font_file` twice.
+ */
+export declare function resolveFontSources(options?: ResolveFontSourcesOptions): FontSource[];
 /**
  * Resolve the directory holding the application's shipped faces, or `undefined` when none is named.
  *

package/lib/types/fonts.d.ts

@@ -1,8 +1,28 @@
 import { type FontFamilyMatch } from './font-families.js';
-import { type ResolveFontDirOptions } from './font-dir.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';
-/** Everything {@link resolveFontDir} takes except the environment, which {@link initFonts} reads. */
-export interface InitFontsOptions extends Omit<ResolveFontDirOptions, 'env'> {
+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';
+/**
+ * Everything {@link resolveFontSources} takes except the environment, which {@link initFonts}
+ * reads.
+ */
+export interface InitFontsOptions extends Omit<ResolveFontSourcesOptions, 'env'> {
+    /**
+     * Which {@link UiFontPolicy} to apply to `gtk-font-name`, or nothing at all.
+     *
+     * DEFAULT: NOTHING. Registering faces and rewriting the user's font setting are two different
+     * acts, and only the first is unambiguously this call's business — a runtime that changes a
+     * font setting nobody asked it to change is a surprise, and it would also make `system`
+     * unreachable in practice, because the host's own value would already have been overwritten
+     * before a consumer could choose to keep it. `size` is the RECOMMENDED value for an app
+     * shipping a bundled GTK; it is a recommendation in the documentation, not a default here.
+     *
+     * Passing a policy still captures the baseline first, so switching back to `system` later
+     * works. See {@link applyUiFontPolicy}, which is also callable on its own at any time.
+     */
+    readonly uiFont?: UiFontPolicy | ApplyUiFontPolicyOptions;
     /**
      * The family names this application will ASK FOR — checked against the map once registration
      * is done, and reported in {@link InitFontsResult.matches}.
@@ -22,8 +42,23 @@ export interface FontFaceFailure {
 }
 /** 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. */
+    /**
+     * The APPLICATION's font directory that was read, or `undefined` when nothing named one.
+     *
+     * Unchanged in meaning since before the runtime bundle had faces of its own, which is why
+     * it is still singular: a caller asserting "my staged face was found" must not start
+     * 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[];
+    /**
+     * What the UI-font-size policy did, or `undefined` when it did not run.
+     *
+     * `undefined` is the ordinary answer on Linux: no runtime bundle names a font directory
+     * there, so the default leaves `gtk-font-name` alone entirely.
+     */
+    readonly uiFont: UiFontPlan | undefined;
     /** Faces now on the default font map. */
     readonly registered: readonly string[];
     /** Faces the font map declined as unsupported — see {@link isUnsupportedByFontMap}. */
@@ -106,3 +141,59 @@ export declare function isUnsupportedByFontMap(error: unknown): boolean;
  * `gjsify ship` staged one, so an unset variable is the ordinary case and does nothing quietly.
  */
 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;
+}
+/**
+ * `gtk-font-name` as this process first found it — what the `system` policy restores.
+ *
+ * READING IT CAPTURES IT, which is the point: the value is only correct if it is taken before
+ * anything writes. A consumer that wants to show the host's own font in a preferences dialog
+ * therefore gets the right answer by asking early, and `initFonts()` asks at startup.
+ *
+ * `undefined` means either "not captured yet, and the toolkit is not initialised" or "this host's
+ * `gtk-font-name` is genuinely unset". Both lead to the same correct behaviour under `system`:
+ * leave the setting alone.
+ */
+export declare function uiFontBaseline(): string | undefined;
+/**
+ * Apply one of the three {@link UiFontPolicy} states to `gtk-font-name`.
+ *
+ * The writing half of `ui-font.ts`, and the function a preferences dialog calls when the user
+ * changes the setting — including the way BACK: `system` restores the baseline this module
+ * 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.
+ */
+export declare function applyUiFontPolicy(request: UiFontPolicy | ApplyUiFontPolicyOptions): UiFontPlan;
+/**
+ * Can this process offer the `adwaita` policy at all — is the GNOME face on the font map?
+ *
+ * THE QUESTION A PREFERENCES DIALOG HAS TO ASK BEFORE IT OFFERS THE OPTION. Forcing
+ * `Adwaita Sans 11` on a host where that family never arrived — an old bundle, a system GTK with
+ * no adwaita-fonts package — does not fail: Pango substitutes, and the user who picked "use the
+ * Adwaita font" gets Tahoma. That is one substitution traded for another, with a setting that
+ * now lies about what it did.
+ *
+ * Answered as a {@link FontFamilyMatch} rather than a boolean because `optical` is a real third
+ * state, measured on Windows: a family can be on the map under a decorated name (`Merriweather
+ * 18pt`), in which case the honest thing is to ask for THAT name — `match.family` — rather than
+ * to report the face as missing. `available` is the convenience for the common case.
+ *
+ * Call it AFTER `initFonts()`, which is what puts the bundled faces on the map.
+ */
+export declare function adwaitaUiFontAvailability(family?: string): UiFontAvailability;
+/** What {@link adwaitaUiFontAvailability} answers. */
+export interface UiFontAvailability {
+    /** The family that was asked about. */
+    readonly family: string;
+    /** How it resolves on the font map as it now stands. */
+    readonly match: FontFamilyMatch;
+    /** `false` when the family is absent, i.e. the `adwaita` policy would substitute. */
+    readonly available: boolean;
+}

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

@@ -0,0 +1,87 @@
+/**
+ * The point size GNOME's interface is designed at — `org.gnome.desktop.interface font-name`'s
+ * default has been `Cantarell 11` and is now `Adwaita Sans 11`.
+ */
+export declare const GNOME_UI_FONT_POINT_SIZE = 11;
+/**
+ * The GNOME UI face, and the family `@gjsify/gtk-runtime-<target>` bundles.
+ *
+ * `Adwaita Sans` rather than `Cantarell`, which it succeeded: adwaita-fonts ships no Cantarell,
+ * so naming it here would ask for a family no bundle carries.
+ */
+export declare const ADWAITA_UI_FONT_FAMILY = "Adwaita Sans";
+/** Which of the three states an application wants. See the note at the top of this file. */
+export type UiFontPolicy = 'system' | 'size' | 'adwaita';
+/**
+ * The three states, in the order a preferences dialog should offer them.
+ *
+ * Exported so a consumer building that dialog enumerates them instead of hard-coding three
+ * strings that then drift from this type — the settings UI and the policy are two copies of one
+ * list otherwise, and only one of them is checked by the compiler.
+ */
+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';
+/** What {@link planUiFont} or {@link planUiFontPolicy} decided, and why. */
+export interface UiFontPlan {
+    /** The `gtk-font-name` to set, or `undefined` when nothing should change. */
+    readonly next: string | undefined;
+    /**
+     * `raised` — the host's size was below GNOME's and is corrected;
+     * `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.
+     */
+    readonly kind: UiFontPlanKind;
+    /** The family in effect after the plan, for reporting. */
+    readonly family: string | undefined;
+    /** The point size in effect after the plan, for reporting. */
+    readonly size: number | undefined;
+}
+export interface PlanUiFontOptions {
+    /** Target point size. Defaults to {@link GNOME_UI_FONT_POINT_SIZE}. */
+    readonly size?: number;
+    /** Force this family too. Off by default — see the policy note at the top of this file. */
+    readonly family?: string;
+}
+/**
+ * Decide the `gtk-font-name` for a host whose current one is `current`.
+ *
+ * PARSED HERE RATHER THAN THROUGH `Pango.FontDescription.from_string`, which is the obvious
+ * tool and the wrong one for this job: that parser NEVER fails — an unparsable tail becomes part
+ * of the family — so every malformed value would come back as a description with size 0, and
+ * "this host has no size I can read" would be indistinguishable from "this host asked for 0 pt".
+ * The distinction is the whole point of the `unparsed` arm: a value this cannot read is left
+ * exactly as it is, because silently rewriting a setting one does not understand is worse than
+ * a font that is 2 pt small.
+ *
+ * The grammar accepted is the one `gtk-font-name` actually carries: a family, optional style
+ * words, then a trailing size — `Segoe UI 9`, `Cantarell Bold 11`, `Adwaita Sans 11.5`. A
+ * fractional size is kept fractional; Pango's own `to_string` emits those.
+ */
+export declare function planUiFont(current: string | undefined, options?: PlanUiFontOptions): UiFontPlan;
+export interface PlanUiFontPolicyOptions extends PlanUiFontOptions {
+    /** Which of the three states to plan for. */
+    readonly policy: UiFontPolicy;
+    /** `gtk-font-name` as it stands right now. */
+    readonly current: string | undefined;
+    /**
+     * `gtk-font-name` as this PROCESS first found it, before anything wrote to it.
+     *
+     * Only the `system` policy reads it, and without it that policy cannot exist: once a value
+     * has been overwritten the host's own is not recoverable — not from GTK, not from the
+     * display, not from GSettings (Windows has none, and on Linux the setting a user actually
+     * chose may itself have been a session-level override). `fonts.ts` captures it on first
+     * contact; `uiFontBaseline()` is the reader.
+     */
+    readonly baseline?: string | undefined;
+}
+/**
+ * Decide `gtk-font-name` for one of the three {@link UiFontPolicy} states.
+ *
+ * Pure, like {@link planUiFont} it builds on, so all three states and the way back are exercised
+ * as unit tests on node with no display and no `Gtk.Settings`. {@link applyUiFontPolicy} in
+ * `fonts.ts` is the half that writes.
+ */
+export declare function planUiFontPolicy(options: PlanUiFontPolicyOptions): UiFontPlan;

package/lib/types/ui-font.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.50.0",
+    "version": "0.51.0",
     "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.50.0"
+        "@gjsify/adwaita-core": "^0.51.0"
     },
     "peerDependencies": {
         "@vue/runtime-core": "^3.5.0",
@@ -124,10 +124,10 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.50.0",
+        "@gjsify/cli": "^0.51.0",
         "@vue/runtime-core": "^3.5.0",
         "solid-js": "^1.9.0",
-        "@gjsify/unit": "^0.50.0",
+        "@gjsify/unit": "^0.51.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",