@gjsify/gtk-host 0.47.0 → 0.49.0

package/lib/types/menu.d.ts

@@ -0,0 +1,43 @@
+import Gio from 'gi://Gio?version=2.0';
+import type { AdwMenuInput, AdwMenuModel } from '@gjsify/adwaita-core';
+/**
+ * A portable menu model as a live `Gio.Menu`.
+ *
+ * Accepts the AUTHORED form as well as the normalised one, so a JSX attribute needs no
+ * conversion step of its own: `normalizeMenuModel` is idempotent, which is what makes
+ * the two safe to take through one door.
+ */
+export declare function buildGioMenu(input: AdwMenuInput | AdwMenuModel): Gio.Menu;
+/**
+ * Whether a value is a portable menu model rather than a `GMenuModel`.
+ *
+ * An ARRAY, and nothing else. `Gio.MenuModel` is a GObject and never an array, so the
+ * test cannot confuse the two — and a caller passing a real `Gio.Menu` (the imperative
+ * path every existing GJS application uses) keeps passing it straight through.
+ */
+export declare const isPortableMenu: (value: unknown) => value is AdwMenuInput;
+/**
+ * A `GMenuModel` back as a portable model — the inverse of {@link buildGioMenu}.
+ *
+ * IT EXISTS TO MAKE THE LOSSLESS CLAIM MEASURABLE. ADR 0042 says the model maps onto
+ * `Gio.Menu` with nothing left over; a builder alone cannot show that, because whatever
+ * it drops is dropped in silence. `conformance/menu.ts` drives every vector through
+ * `buildGioMenu` and back through this function and compares, so a forgotten attribute
+ * fails a test naming it instead of disappearing from a popup nobody re-opened.
+ *
+ * It reads what GTK reads plus `id`, so an application's OWN extra attributes do not
+ * survive the round trip — stated rather than implied: this is not a general
+ * `GMenuModel` serialiser, it is the inverse of the builder above.
+ *
+ * TWO EDGES A HAND-BUILT `Gio.Menu` CAN REACH AND THE MODEL CANNOT, both matching GTK
+ * rather than diverging from it:
+ *
+ *   · an item carrying BOTH links reads as a SECTION and its submenu is not walked.
+ *     `GtkMenuTracker` decides the same way (`gtkmenutracker.c:317-352`): it tests
+ *     `G_MENU_LINK_SECTION` first and
+ *     recurses, so the submenu link is unreachable there too.
+ *   · a non-string `label` reads as `''`. `attr()` asks for type `s`; so does
+ *     `g_menu_item_get_attribute (item, "label", "&s", …)`, which fails the same way and
+ *     leaves GTK drawing an unlabelled row.
+ */
+export declare function fromGioMenu(model: Gio.MenuModel): AdwMenuModel;

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

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

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

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

package/lib/types/policies.d.ts

@@ -1,5 +1,6 @@
+import GObject from 'gi://GObject?version=2.0';
 import Gtk from 'gi://Gtk?version=4.0';
-import type { ChildPolicy, HostElement } from './types.js';
+import type { ChildPolicy, HostElement, NodePlacement, WidgetDescriptor } from './types.js';
 /** The object the PARENT addresses: a wrapper row when the policy demands one. */
 export declare function addressOf(el: HostElement): Gtk.Widget;
 /**
@@ -86,6 +87,245 @@ export declare function setterSlots(policy: ChildPolicy): string[];
  * occupant is the widget they handed over.
  */
 export declare function slotOccupant(widget: Gtk.Widget, setter: string): Gtk.Widget | null | undefined;
+/** A placement that does NOT put the node into its parent's child list. */
+export type OutsideParent = Exclude<NodePlacement, {
+    kind: 'parented';
+}>;
+/**
+ * The declared placement of a node. The ONE place absence is turned into a value.
+ *
+ * Everything downstream switches on the union rather than on `descriptor.placement
+ * !== undefined`, so the absent case is a member with a name instead of a
+ * falsiness test that a third kind would quietly join.
+ */
+export declare const placementOf: (descriptor: WidgetDescriptor) => NodePlacement;
+/**
+ * The placement, when it is NOT `parented` — the narrow question every caller asks.
+ *
+ * Returning the arm rather than a boolean is what keeps the two non-parented kinds
+ * ONE question: a caller switches over what it gets and its `never` arm fails to
+ * compile the day a fourth kind arrives.
+ */
+export declare function outsideParentOf(descriptor: WidgetDescriptor): OutsideParent | null;
+/** The portal arm specifically, or null. */
+export declare function portalOf(descriptor: WidgetDescriptor): Extract<NodePlacement, {
+    kind: 'portal';
+}> | null;
+/** `unhandledPolicy`'s twin for the placement axis, and it exists for the same reason. */
+export declare function unhandledPlacement(placement: never): never;
+/** Is this node placed against its parent rather than into it? */
+export declare const isPortal: (el: HostElement) => boolean;
+/**
+ * Does this node take NO position in its parent's child list?
+ *
+ * The question four sibling walks ask, and it is the placement AXIS rather than
+ * the portal arm: a toplevel occupies a parent's child list exactly as little as a
+ * portal does. Asking `isPortal` there was correct while `portal` was the only
+ * non-parented kind and became a silent hole the moment it was not — counting a
+ * toplevel as a sibling shifts every later child by one and hands
+ * `insert_child_after` a widget that is not in the container (a critical at exit 0),
+ * and rotating one calls the parent's adder on a node that must never enter it.
+ */
+export declare const isUnparented: (el: HostElement) => boolean;
+/**
+ * Show a portal node against its parent — or subscribe and wait, if it is too early.
+ *
+ * Returns whether GTK has actually taken the node, which is what `attached` means.
+ *
+ * WHY THE WAIT IS THE FEATURE. Every framework builds bottom-up: React creates the
+ * whole subtree, appends its children, and inserts the ROOT into the container
+ * last, so at the moment a `<Modal>` is inserted its parent is usually not in a
+ * window yet. MEASURED on libadwaita 1.9.3 / GTK 4.22.4, presenting against an
+ * unrooted box: `adw_dialog_present` finds no `AdwDialogHost` among the parent's
+ * ancestors and takes its documented other branch, `present_as_window` — the
+ * dialog opens as a SEPARATE `GtkWindow`, `win.visibleDialog` stays false, exit 0,
+ * no diagnostic. A modal that floats out of its own application is exactly the
+ * green-and-wrong this host exists to refuse, and nothing in the shadow tree can
+ * see it.
+ *
+ * `notify::root` is the instrument. MEASURED: it fires on a GRANDCHILD box when
+ * the toplevel takes the subtree (root -> AdwWindow), and again on unroot (root ->
+ * null). The subscription STAYS for the life of the attachment rather than being
+ * one-shot, because re-rooting is real: measured, unrooting the parent leaves an
+ * already-presented dialog in the OLD window's host — `w1.visibleDialog` still
+ * true after `w1.set_content(null)` — so a subtree moved to a second window would
+ * silently keep showing its modal in the first.
+ *
+ * SYMMETRIC, and the second direction is not free. GTK does not take the dialog
+ * down when the anchor loses its window, so losing a toplevel RETRACTS the node
+ * rather than merely failing to present it (see `placeAgainst`). Without that, a
+ * subtree that is detached and never re-rooted keeps its sheet on screen in the
+ * window it left, and only a re-root — which such a subtree never gets — repairs it.
+ */
+export declare function presentPortal(parent: HostElement, child: HostElement, portal: Extract<NodePlacement, {
+    kind: 'portal';
+}>): boolean;
+/**
+ * Take a portal node back down, with no probe and no `attached` guard.
+ *
+ * UNCONDITIONALLY, twice over, and both halves are measured. The method the
+ * descriptor names is the FORCED close (`force_close`, not `close`): an unmount is
+ * not a user request, and `close()` on a dialog whose `can-close` is FALSE returns
+ * FALSE, emits `close-attempt` and leaves it on screen. And `force_close()` on a
+ * node that was never presented is silent, where `close()` is
+ * `Adwaita-CRITICAL **: Trying to close … that's not presented` at exit 0 — so the
+ * host needs no "is it up?" question, which is the one it could not answer without
+ * knowing what a dialog is.
+ */
+export declare function retractPortal(child: HostElement, portal: Extract<NodePlacement, {
+    kind: 'portal';
+}>): void;
+/**
+ * Show a toplevel node — and it needs nothing from its parent, which is the point.
+ *
+ * NO ANCHOR, NO WAIT, NO SUBSCRIPTION. A portal has two positions in the tree and
+ * defers until the parent supplies the second one; a toplevel HAS no second
+ * position, so the whole `notify::root` machinery next door has nothing to watch
+ * for. Measured: `gtk_window_present` takes 0 arguments where
+ * `adw_dialog_present` takes 1, and that arity is exactly the difference.
+ *
+ * Returns whether GTK has taken the node — always true once there is a widget,
+ * because a root is taken by nobody: measured, a presented window answers
+ * `get_parent() === null` and `get_root() === itself`. That is not the portal's
+ * "claimed but not yet taken" state, it is the finished one.
+ *
+ * AN AUTHORED `visible: false` IS HONOURED rather than overwritten. `present()`
+ * sets the window visible (measured), so presenting unconditionally would make
+ * `<gtk-window visible={false}>` a property this host silently reverses — the
+ * exact shape it exists to refuse. The node is still `attached`: GTK holds it as
+ * its own root whether or not it is on screen, and a later `setProp(el,
+ * 'visible', true)` shows it through the ordinary property path.
+ */
+export declare function presentToplevel(child: HostElement, placement: Extract<NodePlacement, {
+    kind: 'toplevel';
+}>): boolean;
+/**
+ * Take a toplevel back down — the FORCED call, and it is TERMINAL.
+ *
+ * `destroy` and not `close`, measured on GTK 4.22.4: `gtk_window_close()` emits
+ * `close-request`, and an application handler returning TRUE leaves the window
+ * mapped and visible. That veto is how an application asks the USER to confirm,
+ * and an unmount is not a user request — the same reasoning that makes the portal
+ * arm name `force_close`.
+ *
+ * Unconditional for the same reason too: measured, `destroy()` on a window that
+ * was never presented is silent, so no "is it up?" probe is needed. What differs
+ * from the portal is that there IS no way back — measured, `present()` after a
+ * destroy (or after a `close()`, whose default handler destroys) answers
+ * `Gtk-WARNING **: A window is shown after it has been destroyed`.
+ *
+ * SO THIS IS `destroy`'s CALL AND NOT `remove`'s, which is the whole reason
+ * `detachToplevel` exists next door. `remove` documents itself as reversible.
+ */
+export declare function closeToplevel(child: HostElement, placement: Extract<NodePlacement, {
+    kind: 'toplevel';
+}>): void;
+/**
+ * Take a toplevel OFF SCREEN, reversibly — `remove`'s call.
+ *
+ * `remove` is documented as a detach that a later `insert` undoes ("Frameworks
+ * move nodes; `remove` must not destroy one"), and Solid takes it literally: its
+ * `removeNode` calls `remove(node)` for a move and reaches `destroy` only through
+ * the root disposer. Running the declared, TERMINAL close there made a move
+ * `destroy()` the window and then present the corpse —
+ * `Gtk-WARNING **: A window is shown after it has been destroyed`, at exit 0,
+ * visible only because `installDiagnosticsGate()` was watching.
+ *
+ * A PROPERTY WRITE AND NOT A DECLARED METHOD, and that is the honest shape rather
+ * than a shortcut: a window's presence on screen IS its `visible` property — which
+ * is why `presentToplevel` already reads it — so every toplevel detaches the same
+ * way and a per-row name would be the same string once per declared row. The portal
+ * arm needs no counterpart at all, because its declared close is ALREADY reversible.
+ *
+ * MEASURED on GTK 4.22.4, one window, in order: `set_visible(false)` leaves it
+ * `visible` false with one `unmap`, emits NO `close-request`, and keeps it in
+ * `Gtk.Window.list_toplevels()` — so it is a detach and not a teardown; `present()`
+ * afterwards maps it again with no diagnostic at all; a second `set_visible(false)`
+ * is a no-op; and `destroy()` on the hidden window adds no `unmap` and DOES drop it
+ * from the toplevel list. `set_visible` rather than the deprecated `hide()`, which
+ * is the same call one rename older.
+ *
+ * Unbracketed, unlike `writeVisible`'s host writes: this is not bookkeeping around
+ * a libadwaita defect that the consumer's model never mentions — the window really
+ * did leave the screen, and a bound `notify::visible` is entitled to hear it.
+ */
+export declare function detachToplevel(child: HostElement): void;
+/**
+ * Place a node that does NOT go into its parent's child list, and say whether GTK took it.
+ *
+ * The ONE dispatch over the non-parented arms. Every caller in `host.ts` reaches
+ * the axis through this and its two twins below, so a fourth placement kind is
+ * three `never` arms away from compiling rather than a search through the host.
+ */
+export declare function placeOutsideParent(parent: HostElement, child: HostElement, placement: OutsideParent): boolean;
+/**
+ * The REVERSIBLE take-down — what `remove` means, per arm.
+ *
+ * THE TWO ARMS DIFFER HERE AND NOWHERE ELSE, which is why one function could not
+ * serve both: measured, `force_close()` followed by `present(parent)` re-hosts a
+ * dialog against the SAME parent with no diagnostic, while `destroy()` followed by
+ * `present()` is `Gtk-WARNING **: A window is shown after it has been destroyed`.
+ * The portal arm therefore never showed this defect and the toplevel arm shipped
+ * with it: a single `retractOutsideParent` treated a reversible verb and a terminal
+ * one as the same thing.
+ */
+export declare function detachOutsideParent(child: HostElement, placement: OutsideParent): void;
+/**
+ * The TERMINAL take-down — what `destroy` means, and what a DISCARD means.
+ *
+ * Its one caller is `releaseWidget` in `host.ts`, which is every place the host
+ * drops `el.widget`: a toplevel is held by GTK's own list rather than by a parent
+ * (measured, `list_toplevels()` holds a window from CONSTRUCTION and loses it only
+ * on `destroy`), so a discard that merely detached would leak one window each time
+ * — per construct-only write, and per half-built element a failed replay rolls back.
+ */
+export declare function closeOutsideParent(child: HostElement, placement: OutsideParent): void;
+/**
+ * The placement the installed libraries give this class, or null for an ordinary child.
+ *
+ * STRUCTURAL, never a name. ADR 0027 rule 1 forbids widget knowledge in the host,
+ * and a list of gtypes here would be exactly that — so the class is asked two
+ * questions it answers itself. Both were measured over the WHOLE shipped table on
+ * GTK 4.22.4 / libadwaita 1.9.3 rather than over a sample, which is what makes the
+ * second one a partition and not an observation:
+ *
+ *  - `Gtk.Root` is GTK's OWN word for "this widget is a toplevel", and every class
+ *    in the table implementing it — `GtkWindow` through `GtkPrintUnixDialog` — is
+ *    one no parent may legally take.
+ *  - A `present()` that TAKES AN ARGUMENT is a node presented AGAINST something.
+ *    In the table that set is EXACTLY the `Adw.Dialog` descendants and nothing
+ *    else — the ones whose `root` vfunc calls `g_error()`.
+ *    `Gtk.Popover.present()` is the discriminator that makes the ARITY part of the
+ *    question rather than the name: it exists, it takes 0 arguments, and a popover
+ *    is parented with `set_parent()` like any other child.
+ *
+ * The order matters and is not alphabetical: every `Gtk.Root` in the table that has
+ * a `present` at all has a 0-argument one, and `GtkDragIcon` has none — so the root
+ * test has to come first and cannot be replaced by an arity test.
+ *
+ * @param gtype the class's GType — `type_is_a` walks interfaces as well as parents
+ * @param present the class's own `present`, or the value found on an instance
+ */
+export declare function classPlacementKind(gtype: GObject.GType, present: unknown): OutsideParent['kind'] | null;
+/** `classPlacementKind` for a live widget, which is what the insert path holds. */
+export declare function nodePlacementKind(node: Gtk.Widget): OutsideParent['kind'] | null;
+/**
+ * Refuse a child the installed libraries will not adopt, BEFORE the adder runs.
+ *
+ * This is the catchable half of the abort class (ADR 0054). `descriptorProblems()`
+ * says the same thing about the whole TABLE up front, which is what keeps the
+ * shipped rows honest — but `registerWidget` takes descriptors from applications
+ * and nothing checks those, and for one of the two families the consequence is not
+ * a wrong window: `adw_dialog_root()` is `g_error()`, so the process is gone before
+ * any handler runs. A refusal is only possible while there is still a process.
+ *
+ * ONLY WHERE THE DESCRIPTOR IS SILENT, and that is the escape hatch rather than an
+ * oversight. `placement` present — including an explicit `{ kind: 'parented' }` —
+ * means the author has answered this question, and the host does not overrule an
+ * answer with a heuristic. A consumer widget that trips the `present(parent)` half
+ * of the oracle while really being a child says so in one line.
+ */
+export declare function refuseUnparentable(parent: HostElement, child: HostElement): void;
 export interface Placement {
     parent: HostElement;
     child: HostElement;

package/lib/types/react-jsx-runtime.d.ts

@@ -33,7 +33,7 @@
  */
 import type { Key, ReactElement, ReactNode, Ref } from 'react';
 import type { WidgetClassByTag, WidgetPropsByTag } from './generated/props.js';
-import type { RawSignalAttributes, SlotAttribute, WithOnce } from './attrs.js';
+import type { RawSignalAttributes, SlotAttribute, WithOnce, WithPortableValues } from './attrs.js';
 export { Fragment } from 'react/jsx-runtime';
 /**
  * React's own factories, RE-TYPED over this package's element list.
@@ -74,7 +74,7 @@ export interface ReactWidgetAttributes<T> extends SlotAttribute, RawSignalAttrib
 }
 /** Every GTK/Adwaita tag, with its properties, its handlers, its `ref` and its `key`. */
 export type GtkReactIntrinsicElements = {
-    [K in keyof WidgetPropsByTag]: WithOnce<WidgetPropsByTag[K]> & ReactWidgetAttributes<WidgetClassByTag[K]>;
+    [K in keyof WidgetPropsByTag]: WithOnce<WithPortableValues<WidgetPropsByTag[K]>> & ReactWidgetAttributes<WidgetClassByTag[K]>;
 };
 export declare namespace JSX {
     /**

package/lib/types/shared-trees.spec.d.ts

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

package/lib/types/style/font-family.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A `font-family` value → the text that goes into the declaration.
+ *
+ * Exported because a consumer that has been quoting defensively (see the incident in
+ * the header) can call this instead and stop, and because both routes into the
+ * partition — a `style={{ fontFamily }}` object and a `font-*` utility resolving
+ * against `tokens.fontFamily` — must go through exactly this one function.
+ */
+export declare function serialiseFontFamily(value: string): string;
+/**
+ * What GTK does with an authored value that was NOT serialised.
+ *
+ * Three states rather than a boolean, and the third one is why. `refused` is the
+ * loud bug — GTK rejects the declaration, the containment probe rejects the rule,
+ * and the screen is gone. `misread` is the QUIET one: GTK accepts the bare text and
+ * resolves a DIFFERENT family, so the application renders in a substituted font with
+ * no diagnostic anywhere. A boolean column would have merged `misread` into
+ * `accepted` and asserted that serialising changes nothing — which is false for
+ * exactly the vectors where changing something is the whole point.
+ */
+export type BareReading = 'refused' | 'accepted' | 'misread';
+/** One authored `font-family` value, what it must become, and what GTK does with it unserialised. */
+export interface FontFamilyVector {
+    /** What a `tokens.fontFamily` entry or a `style={{ fontFamily }}` carries. */
+    readonly authored: string;
+    /** What {@link serialiseFontFamily} must emit for it. */
+    readonly emitted: string;
+    /**
+     * What GTK does with `authored` AS IT STANDS.
+     *
+     * The column that makes this table a test rather than a restatement, and every
+     * state of it is RE-MEASURED against the running GTK by `gtk-css.spec.ts`:
+     * `refused` must be rejected, `accepted` must parse to the same computed value
+     * as `emitted`, and `misread` must parse to a DIFFERENT one. So the state is a
+     * finding and not a claim, and a vector cannot quietly stop exercising the rule.
+     */
+    readonly bare: BareReading;
+}
+/**
+ * The conformance set for `font-family` values.
+ *
+ * WHY THIS TABLE EXISTS, and it is the whole finding behind #1539. `gtk-css.ts`
+ * probed `['font-family', 'Cantarell']` — ONE word, valid as a bare identifier, and
+ * therefore the single family for which the missing quoting is invisible. The suite
+ * asserted that `font-family` is emitted and never that it is emitted CORRECTLY, so
+ * it would have gone green against an implementation that quoted nothing. A vector
+ * whose value cannot exercise the rule reads exactly like a vector that passed.
+ *
+ * So the set carries, deliberately: a family that NEEDS quoting, a family that does
+ * not, a bare multi-identifier family GTK already accepted (the case a
+ * quote-on-space reading would call broken), a stack mixing a quoted family with a
+ * bare keyword, a value already quoted, a `var()` reference, and a value GTK MISREADS
+ * rather than refuses. `bare` is re-measured by `gtk-css.spec.ts`, which also refuses
+ * a table that has lost its refused or its misread vectors.
+ *
+ * The three added after the first review are the shapes the SPLIT and the two
+ * PASSTHROUGHS have to survive rather than the quoter: a bare name carrying an odd
+ * quote character in front of a fallback, a nested `var()`, and an already-quoted
+ * member holding a carriage return. Each was emitted as something GTK accepted and
+ * was wrong about — so `gtk-css.spec.ts` also holds the three CLASSES directly, by
+ * asking GTK where the fallback member ended up, whether the document survived, and
+ * whether a declaration appeared that nothing here wrote.
+ */
+export declare const FONT_FAMILY_VECTORS: readonly FontFamilyVector[];

package/lib/types/style/index.d.ts

@@ -3,8 +3,10 @@ export { GTK_WIDGET_PROPERTIES, GTK_WIDGET_PROPERTY_PROBES, NOT_GTK_WIDGET_PROPE
 export { MINIMAL_TOKENS, TAILWIND_DEFAULT_TOKENS, lookupToken, mergeTokens, requireToken, tailwindDefaultHint, } from './tokens.js';
 export type { Scale, StyleTokens } from './tokens.js';
 export { UnknownUtilityError } from './errors.js';
-export { PAINT_PROPERTIES, partitionPaint, resolvePaintUtility } from './paint.js';
+export { CSS_VALUE, CSS_VALUE_KIND, PAINT_PROPERTIES, partitionPaint, resolvePaintUtility } from './paint.js';
 export type { PaintProps } from './paint.js';
+export { FONT_FAMILY_VECTORS, serialiseFontFamily } from './font-family.js';
+export type { FontFamilyVector } from './font-family.js';
 export { LAYOUT_PROPERTIES, partitionLayout, resolveLayoutUtility } from './layout.js';
 export type { AlignValue, Edge, JustifyValue, LayoutIntent, LayoutPartition, LayoutProps, OverlayIntent, WrapIntent, } from './layout.js';
 export { partition, resolveUtilities, resolveUtility } from './resolve.js';

package/lib/types/style/paint.d.ts

@@ -32,6 +32,38 @@ export interface PaintProps {
  * `partition`'s per-call guard, which no input can reach while the table is right.
  */
 export declare const CSS_NAME: Readonly<Record<keyof PaintProps, string>>;
+/**
+ * What KIND of value each property carries — and therefore whether that value can
+ * end the declaration early.
+ *
+ * DECLARED, not derived, because it is a judgement about a vocabulary rather than
+ * something the code can compute. It is here so the judgement is machine-held: the
+ * key set is `keyof PaintProps`, so a new property cannot skip it, and
+ * `paint.spec.ts` asserts that the `name`-valued properties are EXACTLY the ones
+ * {@link CSS_VALUE} serialises. A colour, a length, a number and a keyword are all
+ * self-delimiting; a `name` is supplied verbatim by the project and is the only kind
+ * that can carry a space, a comma or a quote.
+ *
+ * The measured answer today is that `font-family` is the only one — checked against
+ * the layout half too, which emits margins and paddings and nothing else. The next
+ * candidate is not hypothetical: `background-image: url(…)` would be the second.
+ */
+export declare const CSS_VALUE_KIND: Readonly<Record<keyof PaintProps, 'colour' | 'length' | 'number' | 'keyword' | 'name'>>;
+/**
+ * The properties whose value is SERIALISED rather than interpolated.
+ *
+ * PER PROPERTY, and that is the design rather than an accident of there being one
+ * entry: a global rule would have to decide what a comma or a space means without
+ * knowing which property it is in, and it means something different in every one.
+ * The table is the seam a second such property joins at, and
+ * {@link CSS_VALUE_KIND} is what makes joining it compulsory.
+ *
+ * Both routes to a `font-family` — a `style={{ fontFamily }}` object and a `font-*`
+ * utility resolving against `tokens.fontFamily` — arrive at `partitionPaint`, so
+ * one entry here covers both. That is why the serialisation lives at the emitter
+ * and not at either front end.
+ */
+export declare const CSS_VALUE: Readonly<Partial<Record<keyof PaintProps, (value: string) => string>>>;
 /**
  * One utility class → the paint properties it sets, or `null` for "not mine".
  *
@@ -49,5 +81,10 @@ export declare const PAINT_PROPERTIES: ReadonlySet<string>;
  * GTK's parser with no diagnostic, which is the exact silence the whole partition
  * exists to avoid. The check is cheap and it has caught the one property that looks
  * like paint and is not.
+ *
+ * The VALUE gets the same treatment, per property, through {@link CSS_VALUE}. A
+ * checked name with an unserialised value is only half the guard: GTK refused the
+ * whole rule for `font-family: Source Sans 3` while the property name was right
+ * (#1539), and the value is the half a project supplies verbatim.
  */
 export declare function partitionPaint(props: PaintProps): readonly string[];

package/lib/types/testing/refusal.d.mts

@@ -0,0 +1,2 @@
+/** The refusal code `fn` raises, or what it did instead — so a wrong refusal reads as one. */
+export declare function codeOf(fn: () => unknown): string;