react-x11 2.15.3 → 2.16.0

package/src/symbols.js

@@ -0,0 +1,200 @@
+// Symbols by name: the platform's own icons, drawn in the text colour inside
+// a window (#591) — the names `useTray`'s `icon` and a menu item's `iconName`
+// already take, and nothing that draws in a window did.
+//
+// Two providers, one per icon system, behind the same two questions, how
+// big and draw it here:
+//
+// - **SF Symbols** on the Cocoa backend, which brings its own
+//   (`app.symbols`, src/cocoa/symbols.js): a symbol is a template, drawn in
+//   the fill colour at the weight and point size of the text beside it.
+// - **The freedesktop icon theme** everywhere else (src/icontheme.js): the
+//   user's theme, looked up at the size the text calls for. A `-symbolic` icon
+//   is preferred and drawn the same way, its shape in the text colour; an icon
+//   that is only drawn in its own colours is shown as it is.
+//
+// A name one system does not have simply is not there, and takes no room —
+// the same bargain a tray icon's name makes — so an app that runs on both
+// picks its names by platform, as it does for the tray.
+
+import { cssColorStraight, decodeImage, SvgView } from 'ntk';
+import * as nodeFs from 'node:fs';
+
+import { IconTheme } from './icontheme.js';
+import { Surface } from './ntk.js';
+import { xsettings } from './xsettings.js';
+
+/** A `fontWeight` as the number both icon systems configure with. */
+export function symbolWeight(weight) {
+  if (typeof weight === 'number') return weight;
+  if (weight === 'bold') return 700;
+  return 400;
+}
+
+const warned = new Set();
+/** A development warning, once per message. */
+export function warnOnce(message) {
+  if (process.env.NODE_ENV === 'production' || warned.has(message)) return;
+  warned.add(message);
+  console.warn(message);
+}
+
+// --- the freedesktop icon theme -----------------------------------------------
+
+/**
+ * The size a theme is asked for beside text of `pointSize`: 16 for 14px text,
+ * which is the pairing every toolkit's menus and toolbars are drawn at, and in
+ * proportion from there. An icon theme's icons are square.
+ */
+export const iconSizeFor = (pointSize) =>
+  Math.max(1, Math.round((pointSize * 8) / 7));
+
+/**
+ * The user's icon theme on this connection: what the settings daemon says
+ * (`Net/IconThemeName`, which GNOME and Xfce write), and failing that
+ * Adwaita, which `hicolor` then backs up. An explicit `theme` from the test
+ * seam wins.
+ */
+export function iconThemeName(app) {
+  const named = xsettings(app)?.get?.('Net/IconThemeName');
+  return typeof named === 'string' && named ? named : 'Adwaita';
+}
+
+class FreedesktopSymbols {
+  constructor(app, { theme, baseDirs, pixmapDirs, fs = nodeFs } = {}) {
+    this.app = app;
+    this.fs = fs;
+    this.theme = new IconTheme({
+      theme: theme ?? iconThemeName(app),
+      baseDirs,
+      pixmapDirs,
+      fs,
+    });
+    this.documents = new Map(); // path -> SvgView | Image | null
+    // path|size|colour -> Surface, least recently drawn first
+    this.rasters = new Map();
+  }
+
+  /** `{ path, symbolic }` for a name at a logical size, or null. A symbolic
+   *  variant is preferred: it is the one that takes the text colour. */
+  _resolve(name, pointSize, scale) {
+    const size = iconSizeFor(pointSize);
+    const whole = Math.max(1, Math.round(scale));
+    const symbolic = name.endsWith('-symbolic');
+    for (const candidate of symbolic ? [name] : [`${name}-symbolic`, name]) {
+      const path = this.theme.find(candidate, size, whole);
+      if (path) return { path, symbolic: candidate.endsWith('-symbolic') };
+    }
+    return null;
+  }
+
+  size(name, options) {
+    if (!this._resolve(name, options.pointSize, options.displayScale)) {
+      return null;
+    }
+    const side = iconSizeFor(options.pointSize);
+    return { width: side, height: side };
+  }
+
+  draw(ctx, name, rect, options) {
+    const found = this._resolve(name, options.pointSize, options.displayScale);
+    if (!found) return false;
+    // square, centred in the box, on whole device pixels
+    const side = Math.max(1, Math.floor(Math.min(rect.width, rect.height)));
+    const x = Math.round(rect.x + (rect.width - side) / 2);
+    const y = Math.round(rect.y + (rect.height - side) / 2);
+    const raster = this._raster(found, side, options.color);
+    if (!raster) return false;
+    ctx.drawImage(raster, x, y, side, side);
+    return true;
+  }
+
+  /** The icon drawn at `side` device pixels — in `color` for a symbolic one —
+   *  kept for the next paint. */
+  _raster(found, side, color) {
+    const ink = found.symbolic
+      ? (cssColorStraight(color) ?? [0, 0, 0, 1])
+      : null;
+    const key = `${found.path}\u0000${side}\u0000${ink?.join(',') ?? ''}`;
+    const kept = this.rasters.get(key);
+    if (kept) {
+      this.rasters.delete(key);
+      this.rasters.set(key, kept);
+      return kept;
+    }
+    const document = this._document(found.path);
+    if (!document) return null;
+    let surface;
+    try {
+      surface = new Surface(this.app, { width: side, height: side });
+    } catch {
+      return null; // no offscreen surfaces here: the headless mock
+    }
+    surface.render((sctx) => {
+      sctx.clearRect(0, 0, side, side);
+      if (document instanceof SvgView) document.draw(sctx, 0, 0, side, side);
+      else sctx.drawImage(document, 0, 0, side, side);
+      if (ink) {
+        // the shape's coverage, in the text colour: what AppKit does with a
+        // template, and what GTK does with a symbolic icon
+        sctx.globalCompositeOperation = 'source-in';
+        sctx.fillStyle = `rgba(${Math.round(ink[0] * 255)}, ${Math.round(ink[1] * 255)}, ${Math.round(ink[2] * 255)}, ${ink[3]})`;
+        sctx.fillRect(0, 0, side, side);
+      }
+    });
+    this.rasters.set(key, surface);
+    if (this.rasters.size > 64) {
+      const [oldest, evicted] = this.rasters.entries().next().value;
+      this.rasters.delete(oldest);
+      evicted.destroy?.();
+    }
+    return surface;
+  }
+
+  _document(path) {
+    if (this.documents.has(path)) return this.documents.get(path);
+    let document = null;
+    try {
+      const bytes = this.fs.readFileSync(path);
+      if (path.endsWith('.svg')) {
+        document = new SvgView(null);
+        document.setSvg(bytes.toString('utf8'));
+      } else {
+        document = decodeImage(bytes);
+      }
+    } catch (err) {
+      warnOnce(`react-x11: the icon ${path} did not load: ${err.message}`);
+    }
+    this.documents.set(path, document);
+    return document;
+  }
+
+  destroy() {
+    for (const surface of this.rasters.values()) surface.destroy?.();
+    this.rasters.clear();
+  }
+}
+
+// --- per app --------------------------------------------------------------------
+
+const providers = new WeakMap();
+
+/**
+ * The symbol provider for a connection: the one the app brings, which is the
+ * Cocoa app's SF Symbols, or the freedesktop icon theme, made on first use.
+ */
+export function symbolsFor(app) {
+  let provider = providers.get(app);
+  if (!provider) {
+    provider = app?.symbols ?? new FreedesktopSymbols(app);
+    providers.set(app, provider);
+  }
+  return provider;
+}
+
+/** Look icons up in a theme of the test's own, at base directories it names. */
+export function setIconThemeForTests(app, options) {
+  providers.get(app)?.destroy?.();
+  if (options == null) providers.delete(app);
+  else providers.set(app, new FreedesktopSymbols(app, options));
+}

package/src/testing/mock-app.js

@@ -288,6 +288,16 @@ export function createMockApp() {
           wnd.grabbed = false;
           wnd.calls.push(['ungrabPointer']);
         },
+        // …and a popup that takes the keyboard holds this one
+        grabKeyboard(options, cb) {
+          wnd.keyboardGrabbed = true;
+          wnd.calls.push(['grabKeyboard']);
+          cb?.(null, 0);
+        },
+        ungrabKeyboard() {
+          wnd.keyboardGrabbed = false;
+          wnd.calls.push(['ungrabKeyboard']);
+        },
         // ntk >= 7.5.0. `xi2: 'auto'` creates a window on core events and
         // calls this the first time it is scrolled, so the call is the
         // observable half of the upgrade — `wnd.xi2Selected` is what a test

package/src/trayhooks.js

@@ -74,9 +74,10 @@ import { StatusNotifierItem, allocateItemSlot } from './statusnotifier.js';
  *
  * With `menu`, a click opens it — the same `items` vocabulary `MenuBar` and
  * `useDockMenu` take, an item's `onSelect` firing when picked. Without one,
- * `onClick` is called with the button and, where the backend knows it, the
- * item's screen rect. `null` means no item. Every field follows its value
- * while mounted; the item is removed on unmount.
+ * `onClick` is called with the button and where the click was, in logical
+ * screen pixels — with the item's rect, where the backend knows it. `null`
+ * means no item. Every field follows its value while mounted; the item is
+ * removed on unmount.
  *
  * `available` is whether this backend has a tray at all, and it **settles**:
  * false on the first frame, true once a tray has been found. Branch on it for
@@ -89,6 +90,8 @@ export function useTray(options) {
   const itemRef = useRef(null);
   const [rect] = useState(null);
   const [remote, setRemote] = useState(false);
+  // whether the freedesktop registration has answered, either way
+  const [answered, setAnswered] = useState(false);
   const [error, setError] = useState(null);
   // The feature vocabulary for whichever rung answered. Probed once per
   // backend rather than per render — it describes the mechanism, not the
@@ -166,6 +169,10 @@ export function useTray(options) {
     const appId = currentRegistration()?.appId ?? 'react-x11';
     const item = new StatusNotifierItem({
       getOptions: () => live.current,
+      // The display a click's position is read against: the host sends it in
+      // a unit of its own choosing — see "The position has no unit" in
+      // statusnotifier.js.
+      app,
       appId,
       slot: slotRef.current,
       decodeIcon: decodeIconBytes,
@@ -180,16 +187,19 @@ export function useTray(options) {
     sniRef.current = item;
     previous.current = { ...live.current };
     void item.start().then((ok) => {
-      if (!cancelled) setRemote(ok);
+      if (cancelled) return;
+      setRemote(ok);
+      setAnswered(true);
     });
     return () => {
       cancelled = true;
       sniRef.current = null;
       setRemote(false);
+      setAnswered(false);
       setError(null);
       void item.stop();
     };
-  }, [native, options == null]);
+  }, [app, native, options == null]);
 
   // The item reads its fields through `getOptions`, so a render only has to
   // say *which* of them moved — see `StatusNotifierItem.update`.
@@ -215,6 +225,12 @@ export function useTray(options) {
   const backend = native ? 'cocoa' : remote ? caps.backend : null;
   return {
     available: native || remote,
+    // Whether `available` is an answer yet: at once on the Cocoa rung and for
+    // no item at all, and on the freedesktop one once the host has taken or
+    // refused the registration — so an app whose whole UI is its tray can
+    // render nothing until then, rather than a fallback window that flashes
+    // up and away on every start.
+    settled: native || !options || answered,
     backend,
     features: native || remote ? caps.features : NO_CAPABILITY.features,
     error,

package/src/types/capabilities.d.ts

@@ -124,4 +124,16 @@ export declare function desktopCapability<N extends DesktopCapabilityName>(
  */
 export declare function useDesktopCapability<N extends DesktopCapabilityName>(
   name: N,
-): DesktopCapabilityFor<N>;
+): DesktopCapabilityState<N>;
+
+/** {@link useDesktopCapability}'s answer, and whether it is one yet. */
+export type DesktopCapabilityState<N extends DesktopCapabilityName> =
+  DesktopCapabilityFor<N> & {
+    /**
+     * False until the first probe answers, and true from then on, re-probes
+     * included — so an app can hold its fallback back rather than flash it.
+     * True on the first frame where nothing had to be asked: the tray and
+     * the Dock tile on macOS.
+     */
+    settled: boolean;
+  };

package/src/types/components.d.ts

@@ -418,6 +418,17 @@ export interface SliderProps
   disabled?: boolean;
   height?: number;
   style?: StyleProp;
+  /**
+   * The thumb's style, over its default: a 16px circle on `surface` with a
+   * ring. Its `width` and `height`, as numbers, are what the drag's travel
+   * and the control's height are measured with.
+   */
+  thumbStyle?: StyleProp;
+  /** The track's style, over `height` and `track`. Its `height` is the
+   *  fill's too. */
+  trackStyle?: StyleProp;
+  /** The filled part of the track, up to the value, over `accent`. */
+  fillStyle?: StyleProp;
 }
 export const Slider: ComponentType<SliderProps>;
 
@@ -761,6 +772,28 @@ export function anchorRect(
   options?: AnchorOptions,
 ): AnchorRect | null;
 
+/**
+ * The same placement against a rect **on the screen** rather than a node —
+ * the item a tray click reports, a point where the pointer was — in logical
+ * screen pixels on both sides. With no node to ask, `scale` is the
+ * display's (default 1) and `direction` decides `'start'` and `'end'`; the
+ * popup is kept on the monitor the rect is on. `null` for a rect with no
+ * `x`/`y`.
+ */
+export function anchorScreenRect(
+  app: unknown,
+  rect: ScreenAnchorRect,
+  options?: Omit<AnchorOptions, 'at' | 'alignTo'> & { scale?: number },
+): AnchorRect | null;
+
+/** A rect on the screen, in logical pixels; `{x, y}` alone is a point. */
+export interface ScreenAnchorRect {
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+}
+
 /** Centre a popup of this size on the node's screen. */
 export function centerRect(
   node: DrawnNode,

package/src/types/elements.d.ts

@@ -5,14 +5,14 @@
  */
 
 import type { Ref, RefObject, ReactNode, Key } from 'react';
-import type { Color, Cursor, StyleProp } from './style.js';
+import type { Color, Cursor, FontWeight, StyleProp } from './style.js';
 import type {
   DrawnNode,
   NtkWindow,
   ScrollableNode,
   TextInputNode,
 } from './nodes.js';
-import type { AnchorOptions } from './components.js';
+import type { AnchorOptions, ScreenAnchorRect } from './components.js';
 import type {
   ChangeEvent,
   SelectionChangeEvent,
@@ -580,6 +580,16 @@ export interface PopupProps extends WindowProps {
    * this client at all. Needs ntk >= 3.7.0.
    */
   grab?: boolean;
+  /**
+   * Take the keyboard while the popup is up: its keys come to it whatever
+   * holds the focus, which is what a popover a tray click opened needs — a
+   * menu-bar app has no window of its own for keys to arrive at. A keyboard
+   * grab on X, taken and dropped with the map like `grab`. On macOS a window
+   * AppKit can make key, shown activating the app, as `NSPopover`'s own
+   * window is — decided when the popup is created, so it does not change on
+   * a mounted one. A grabbing popup on Wayland has the keyboard already.
+   */
+  grabKeyboard?: boolean;
   /**
    * `true` (the default) keeps the window manager out entirely, which is
    * what makes a menu a menu — no frame, no repositioning, no taskbar entry.
@@ -597,7 +607,9 @@ export interface PopupProps extends WindowProps {
   /**
    * Hang this popup off a node — `anchorRect`'s options plus the node to
    * measure, and the popup works out its own position from them, ignoring
-   * `x`/`y`.
+   * `x`/`y`. Or off a rect on the screen with no node behind it, `rect`
+   * instead of `to`: the item a tray click reports, placed against with the
+   * same flip and clamp.
    *
    * What this does that computing a rect in the application cannot: a popup
    * with an `'auto'` size only knows how big it is *inside* `realize()`,
@@ -622,12 +634,26 @@ export interface PopupProps extends WindowProps {
  *  that renders them) or the node itself. */
 export type AnchorTarget = DrawnNode | RefObject<DrawnNode | null> | null;
 
-export interface PopupAnchor extends Omit<AnchorOptions, 'alignTo'> {
+/** Where a popup hangs: a node, or a rect on the screen. */
+export type PopupAnchor = NodeAnchor | ScreenAnchor;
+
+export interface NodeAnchor extends Omit<AnchorOptions, 'alignTo'> {
   /** The node this popup hangs off. */
   to: AnchorTarget;
   /** Takes the alignment axis from another node — see
    *  {@link AnchorOptions.alignTo}. */
   alignTo?: AnchorTarget;
+  rect?: never;
+}
+
+export interface ScreenAnchor extends Omit<AnchorOptions, 'alignTo' | 'at'> {
+  /**
+   * A rect on the screen, in logical pixels — what `useTray`'s `onClick`
+   * reports where the platform knows the item's frame. `{x, y}` alone is a
+   * point. Nothing moves it but a new one, and it is never out of view.
+   */
+  rect: ScreenAnchorRect;
+  to?: never;
 }
 
 // --- drawn elements --------------------------------------------------------
@@ -758,10 +784,35 @@ export interface FileUrl {
 
 /**
  * What `src` accepts: a file path or file URL (PNG/JPEG, decoded in JS),
- * encoded PNG/JPEG bytes, raw RGBA pixels, or an ntk `Image`/`Surface`.
+ * encoded PNG/JPEG bytes, raw RGBA pixels, an ntk `Image`/`Surface`, or a
+ * symbol by name.
  */
 export type ImageSource =
-  string | FileUrl | Uint8Array | RawImageSource | DirectImageSource;
+  | string
+  | FileUrl
+  | Uint8Array
+  | RawImageSource
+  | DirectImageSource
+  | SymbolImageSource;
+
+/**
+ * The platform's own icon by name, drawn in the text colour: an SF Symbol on
+ * macOS (`'speaker.wave.3.fill'`), and elsewhere an icon from the user's
+ * freedesktop icon theme (`'audio-volume-high'`), its `-symbolic` variant
+ * preferred. Sized like the text around it — the size its `fontSize` calls
+ * for — unless the element is styled a size of its own. A name this desktop
+ * does not have takes no room and draws nothing.
+ */
+export interface SymbolImageSource {
+  symbol: string;
+  /** Default: the weight of the text around it. SF Symbols only. */
+  weight?: FontWeight;
+  /** Relative to the text size, default `'medium'`. SF Symbols only. */
+  scale?: 'small' | 'medium' | 'large';
+  /** How much of a variable symbol shows, 0 to 1 — the waves of
+   *  `speaker.wave.3.fill` at a volume. SF Symbols on macOS 13 and later. */
+  variableValue?: number;
+}
 
 /**
  * An existing server-side Picture, named by X id. The size is stated by the

package/src/types/style.d.ts

@@ -305,6 +305,14 @@ export interface PaintStyle {
   outlineColor?: Color;
   /** The gap between the border box and the ring. Default 1. */
   outlineOffset?: number;
+  /**
+   * How opaque the node is **with everything inside it**, from 0 to 1: the
+   * subtree is drawn once and composited at this alpha, so a card, its
+   * border, its icon and its text fade as one. A paint property — legal in a
+   * state block, and it transitions and loops. `0` draws nothing and is
+   * still hit; values outside 0..1 are clamped.
+   */
+  opacity?: number;
 }
 
 /**
@@ -327,6 +335,34 @@ export type TextOverflow = 'clip' | 'ellipsis';
 export type TextRendering =
   'auto' | 'optimizeSpeed' | 'optimizeLegibility' | 'geometricPrecision';
 
+/** One `fontVariantNumeric` keyword, and the OpenType feature it turns on. */
+export type NumericVariant =
+  | 'lining-nums' // lnum
+  | 'oldstyle-nums' // onum
+  | 'proportional-nums' // pnum
+  | 'tabular-nums' // tnum
+  | 'diagonal-fractions' // frac
+  | 'stacked-fractions' // afrc
+  | 'ordinal' // ordn
+  | 'slashed-zero'; // zero
+
+/**
+ * CSS's `font-variant-numeric`: `'normal'`, or keywords separated by spaces,
+ * at most one of each pair that contradicts — lining or oldstyle,
+ * proportional or tabular, diagonal or stacked fractions. Typed as a first
+ * keyword and whatever follows; the rest is checked when the style is.
+ */
+export type FontVariantNumeric =
+  'normal' | NumericVariant | `${NumericVariant} ${string}`;
+
+/**
+ * CSS's `font-feature-settings`, by OpenType tag: the tags to turn on,
+ * `['tnum', 'ss01']`, or tag → on or off, or the alternate a feature picks,
+ * `{ liga: false, salt: 2 }`.
+ */
+export type FontFeatureSettings =
+  readonly string[] | Readonly<Record<string, boolean | number>>;
+
 /** Text properties. All affect measurement except `color`. */
 export interface TextStyle {
   color?: Color;
@@ -346,6 +382,19 @@ export interface TextStyle {
    *  at any size. `'auto'` (default) lets size decide. Changing it repaints
    *  without reflowing: it cannot move anything. */
   textRendering?: TextRendering;
+  /** CSS's `letter-spacing`, in pixels: added after every character, the
+   *  last on a line included, and negative to tighten. Spaced text drops the
+   *  optional ligatures (`liga`, `clig`, `dlig`, `hlig`) unless
+   *  `fontFeatureSettings` names them. Inherits. */
+  letterSpacing?: number;
+  /** Which figures: `'tabular-nums'` gives every digit one width, so a
+   *  number that changes holds its width while it does. The friendly names
+   *  for features `fontFeatureSettings` can also set by tag, and it wins
+   *  where the two meet. Inherits, apart from `fontFeatureSettings`. */
+  fontVariantNumeric?: FontVariantNumeric;
+  /** Any OpenType feature, by tag. A feature the face does not have is
+   *  ignored. Compared by value, so an object literal is fine. Inherits. */
+  fontFeatureSettings?: FontFeatureSettings;
   textAlign?: TextAlign;
   lineHeight?: number;
   /** CSS's `text-wrap`. `'nowrap'` measures the text at unbounded width, so
@@ -436,6 +485,14 @@ export interface AnimationSpec {
   easing?: Easing;
   /** Turn around at each end instead of wrapping back to `from`. */
   alternate?: boolean;
+  /**
+   * When the loop's own time starts, in ms — CSS's `animation-delay`. A
+   * positive delay holds `from` that long before the first crossing; a
+   * negative one starts the loop that far in. Default `0`. What staggers
+   * loops of one duration: three dots at `0`, `-150` and `-300` never move
+   * together.
+   */
+  delay?: number;
 }
 
 /**

package/src/types/system.d.ts

@@ -267,6 +267,110 @@ export interface DesktopSettings {
  */
 export function useDesktopSettings(): DesktopSettings;
 
+// --------------------------------------------------------------------------
+// The app's own settings
+// --------------------------------------------------------------------------
+
+/** A value a settings store can keep: what JSON can. */
+export type SettingValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly SettingValue[]
+  | { readonly [key: string]: SettingValue };
+
+export interface SettingsOptions<T extends Record<string, SettingValue>> {
+  /**
+   * A reverse-DNS name no other app uses, like `'com.example.myapp'`: the
+   * name of the app's settings directory. Nothing is registered with it.
+   */
+  appId: string;
+  /** Each setting's value when nothing was saved. */
+  defaults?: T;
+  /** Where `settings.json` goes instead of the per-user directory for the
+   *  app — for a portable install, or a test. */
+  directory?: string;
+}
+
+/** A value's kind: `false` as `boolean`, `'brown'` as `string`, so a
+ *  default does not narrow what the setting may be set to. */
+export type SettingKind<V> = V extends boolean
+  ? boolean
+  : V extends string
+    ? string
+    : V extends number
+      ? number
+      : V;
+
+/** A setting's type: its default's kind, for a key the defaults name, else
+ *  the fallback's. */
+export type SettingOf<T, K, V> = SettingKind<K extends keyof T ? T[K] : V>;
+
+/**
+ * What an app remembers between launches, kept in `settings.json` in its
+ * per-user directory, written atomically and coalesced.
+ */
+export interface Settings<T extends Record<string, SettingValue>> {
+  /** The file the values are kept in. */
+  readonly path: string;
+  /** `[value, setValue]` for one setting, like `useState`; every component
+   *  using the key sees the same value, and a change is saved. A key with no
+   *  default takes a fallback. */
+  use<K extends string, V extends SettingValue = never>(
+    key: K,
+    fallback?: V,
+  ): [
+    SettingOf<T, K, V>,
+    (
+      value:
+        | SettingOf<T, K, V>
+        | ((previous: SettingOf<T, K, V>) => SettingOf<T, K, V>),
+    ) => void,
+  ];
+  get<K extends string, V extends SettingValue = never>(
+    key: K,
+    fallback?: V,
+  ): K extends keyof T ? SettingOf<T, K, V> : SettingOf<T, K, V> | undefined;
+  /** Change a setting now, and save it a moment later — a quarter second
+   *  after the last change, and at least once a second while they keep
+   *  coming. Throws a `TypeError` for a value JSON cannot keep. */
+  set<K extends string>(
+    key: K,
+    value: K extends keyof T ? SettingOf<T, K, never> : SettingValue,
+  ): void;
+  /** Forget what was saved for a setting: its default again. */
+  reset(key: string): void;
+  /** Save what is waiting now. Resolves when it is on disk. */
+  flush(): Promise<void>;
+  /** Hear every change; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void;
+}
+
+/**
+ * The settings store for an app — one per file in the process, so every call
+ * with the same `appId` shares values.
+ *
+ * ```tsx
+ * const settings = createSettings({
+ *   appId: 'com.example.Hush',
+ *   defaults: { volume: 0.5, dark: false },
+ * });
+ * function Volume() {
+ *   const [volume, setVolume] = settings.use('volume');
+ *   return <Slider value={volume} onChange={setVolume} />;
+ * }
+ * ```
+ *
+ * It lives in `~/Library/Application Support/<appId>/settings.json` on macOS
+ * and `$XDG_CONFIG_HOME/<appId>/settings.json` elsewhere, and is read the
+ * first time a value is asked for. What is still unsaved when the process
+ * exits is written then.
+ */
+export function createSettings<T extends Record<string, SettingValue>>(
+  options: SettingsOptions<T>,
+): Settings<T>;
+
 // --------------------------------------------------------------------------
 // Locale
 // --------------------------------------------------------------------------