node-gtk 2.2.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
     <a>
       <img
         alt="NODE-GTK"
-        width="250"
+        width="200"
         src="https://raw.githubusercontent.com/romgrk/node-gtk/master/img/node-gtk-logo.svg?sanitize=true"
       />
     </a>
@@ -12,205 +12,89 @@
 <p align="center">
   <b>GTK bindings for NodeJS</b>
   <br/>
-  <img src="https://img.shields.io/npm/v/node-gtk" alt="Package Version" />
 </p>
 
-`node-gtk` is a [gobject-introspection](https://gi.readthedocs.io/en/latest) library 
-for nodejs. It makes it possible to use any introspected C library, such as GTK, 
-usable. It is similar in essence to [GJS](https://wiki.gnome.org/action/show/Projects/Gjs) 
-or [PyGObject](https://pygobject.readthedocs.io). Please note this project is 
-currently in a _alpha_ state.
-
-Supported Node.js versions: **20**, **22**, **24** (other versions may work but are untested)<br>
-Supported platforms:
-- **Linux** — prebuilt binaries available
-- **macOS** — prebuilt binaries available
-- **Windows** — prebuilt binaries available (but read [Windows](#windows))
-
-
-### Table of contents
-
-- [Usage](#usage)
-- [ES modules](#es-modules)
-- [Documentation](#documentation)
-- [TypeScript](#typescript)
-- [Installing](#installing)
-- [Contributing](#contributing)
-
-## Usage
-
-Below is a [minimal example](./examples/hello-world.js) of how to use node-gtk:
-
-```javascript
-const gi = require('node-gtk');
-const GLib = gi.require('GLib', '2.0');
-const Gtk = gi.require('Gtk', '4.0');
-const Adw = gi.require('Adw', '1');
-
-const loop = GLib.MainLoop.new(null, false);
-const app = new Adw.Application('com.github.romgrk.node-gtk.hello', 0);
-
-app.on('activate', () => {
-  const content = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL });
-  content.append(new Adw.HeaderBar());
-  content.append(new Gtk.Label({ label: 'Hello Adwaita!', vexpand: true }));
-
-  const window = new Adw.ApplicationWindow(app);
-  window.setTitle('node-gtk');
-  window.setDefaultSize(300, 120);
-  window.setContent(content);
-  window.on('close-request', () => (loop.quit(), app.quit(), false));
-  window.present();
-
-  gi.startLoop();
-  loop.run();
-});
-
-process.exit(app.run([]));
-```
-
 <p align="center">
-  <img src="./img/hello-world.png" style="width: 290px; height: auto;"/>
+  <a href="#usage">Usage</a> · <a href="#installing">Installing</a> · <a href="./doc/index.md">Documentation</a> · <a href="#contributing">Contributing</a>
 </p>
 
-You can also easily create custom applications:
-
-[A web browser (using WebKit2GTK)](./examples/browser.js)
-
-<p align="center">
-  <img src="./img/browser.png" style="max-width: 500px; height: auto;"/>
-</p>
+<br />
 
-[A system monitor](./examples/system-monitor.js)
+`node-gtk` lets you build native GTK apps on **linux**, **macOS** and  **windows**
+with full **ESM**, **TypeScript** and **CSS hot-reload** support. Prebuilt binaries 
+are available for Node.js versions **20**, **22** and **24**.
 
 <p align="center">
-  <img src="./img/system-monitor.png" style="width: 400px; height: auto;"/>
+  <img src="./img/browser.png" style="max-width: 500px; height: auto;" alt="A web browser build with node-gtk" />
 </p>
 
-## ES modules
-
-The Usage example above is CommonJS. node-gtk also works under ESM, but the
-blocking main-loop calls (`GLib.MainLoop.run`, `Gio`/`Gtk.Application.run`,
-`Gtk.main`) **return immediately** instead of blocking and **don't return a
-value** — so make the run call the last statement and exit from your handler:
-
-```javascript
-app.on('activate', () => {
-  // ...build the window...
-  window.on('close-request', () => (loop.quit(), app.quit(), false));
-  window.present();
-
-  gi.startLoop();
-  loop.run();      // returns immediately under ESM; do cleanup/exit in the handler
-});
-
-app.run([]);       // not `process.exit(app.run([]))` — the return value is unavailable
-```
-
-CommonJS (and signal callbacks) are unaffected. For the why and the design
-trade-off, see [#449](https://github.com/romgrk/node-gtk/issues/449).
-
-## Documentation
-
-[Read our documentation here](./doc/index.md)
-
-## TypeScript
+## Usage
 
-node-gtk can generate TypeScript declarations for the libraries you use,
-straight from the GObject-Introspection typelibs installed on your machine — so
-the types always match your actual library versions and node-gtk's own runtime
-shape (camelCase methods, signal callbacks, nullability, etc.).
+The **create** tool generates a complete, ready-to-run GTK/Adwaita project, so you
+can start building immediately after [installing GTK4](#installing):
 
 ```sh
-# generates ./node_modules/.node-gtk-types (a hidden, git-ignored cache)
-npx node-gtk generate-types Gtk-4.0 Adw-1
-```
-
-The command emits one declaration file per namespace (plus the full dependency
-closure) and a `node-gtk.d.ts` shim. Point your `tsconfig.json` at it:
-
-```jsonc
-{
-  "compilerOptions": {
-    "moduleResolution": "node16",
-    "paths": { "node-gtk": ["./node_modules/.node-gtk-types/node-gtk.d.ts"] }
-  }
-}
-```
-
-Then `gi.require` is fully typed — the namespace is inferred from the string
-arguments:
-
-```ts
-import * as gi from 'node-gtk'
-
-const Gtk = gi.require('Gtk', '4.0')   // typed as the Gtk-4.0 namespace
-const win = new Gtk.ApplicationWindow({ title: 'Hello', defaultWidth: 400 })
-win.on('close-request', () => false)   // signal name + callback are typed
+npx node-gtk create <your-app>
 ```
 
-You get typed constructor properties (including inherited and interface ones),
-camelCase methods with real return types, GI nullability, typed signal
-overloads, enums, `bigint` for 64-bit integers, out-parameters surfaced as the
-return value, and cross-namespace types. GNOME's API documentation is included
-as JSDoc (with `@param`/`@returns`), so editors show it on hover — this reads the
-`.gir` files installed by the libraries' `-dev`/`-devel` packages; pass
-`--no-docs` for leaner output if they aren't installed or you don't want them.
-
-Because the output is a generated cache under `node_modules`, add a `postinstall`
-script so it regenerates on install:
-
-```json
-{ "scripts": { "postinstall": "node-gtk generate-types Gtk-4.0 Adw-1" } }
-```
+<p align="center">
+  <img src="./img/create-app-example.png" style="width: 500px; height: auto;"/>
+</p>
 
-Run `npx node-gtk generate-types --help` for options.
+Also see our [hello world](./examples/hello-world.mjs), [web browser](./examples/browser.mjs)
+or [system monitor](./examples/system-monitor.mjs) examples.
 
 ## Installing
 
-1. Install `node-gtk` itself
-2. Install the native libraries you use (see examples per platform below)
+There are two steps:
 
-```sh
-npm install node-gtk
-
-# This installs a prebuilt binary when one is available for your platform and
-# Node.js version, otherwise it falls back to building from source.
-```
+1. Install `node-gtk` itself (*done by the create tool*)
+2. Install the native libraries you use (see examples per platform below)
 
 #### Linux
 
 ```sh
 # archlinux
-pacman -S gtk4
+pacman -S gtk4 libadwaita
+
+# fedora
+dnf install gtk4 libadwaita
 
 # ubuntu
-apt install libgtk-4-1
+# Already installed :)
 ```
 
 #### macOS
 
 ```sh
-brew install gtk4
+brew install gtk4 libadwaita adwaita-icon-theme
 ```
 
 #### Windows
 
-Windows doesn't have the dependencies we need in a package manager, therefore 
-`node-gtk` ships prebuilt versions of GTK 4 / Adwaita runtime (DLLs, typelibs, 
-icons), so `npm install node-gtk` is all you need **if** your dependency is in 
-our [list of prebuilt libraries](./windows/runtime-libraries.txt).
+```sh
+# Already installed :)
+```
+
+> [!NOTE]
+> Windows doesn't have the dependencies we need in a package manager, therefore
+> `node-gtk` ships prebuilt versions of GTK 4 / Adwaita, so `npm install node-gtk`
+> is all you need **if** your dependency is in our 
+> [list of prebuilt libraries](./windows/runtime-libraries.txt).
 
 ### build from source
 
-Building from source, or contributing? See [Building from source](./doc/building.md).
+Building from source, or [contributing](./doc/contributing.md)? See [Building from source](./doc/building.md).
 
-## Contributing
+## Documentation
+
+[Read our documentation here](./doc/index.md)
+
+## Other notes
 
-If you'd like to help, we'd be more than happy to have support. To setup your development environment, you can
-run `npm run configure`. You can then build the project with `npm run build`. To generate the `compile_commands.json`
-for LSP to work nicely, you can use [bear](https://github.com/rizsotto/Bear) as `bear -- npm run build`.
+`node-gtk` is a [gobject-introspection](https://gi.readthedocs.io/en/latest) library 
+for nodejs. It makes it possible to use any introspected C library, such as GTK, 
+usable. It is similar in essence to [GJS](https://wiki.gnome.org/action/show/Projects/Gjs) 
+or [PyGObject](https://pygobject.readthedocs.io).
 
-- https://developer.gnome.org/gi/stable/index.html
-- https://v8docs.nodesource.com/
-- https://github.com/nodejs/nan#api
+[MIT License](./LICENSE)

package/bin/node-gtk.js

@@ -4,6 +4,8 @@
  *
  * Subcommands:
  *   generate-types   Generate TypeScript declarations from the installed typelibs.
+ *   create           Create a new GTK/Adwaita application.
+ *   list             List the GObject-Introspection libraries available locally.
  */
 
 const cmd = process.argv[2]
@@ -12,6 +14,13 @@ switch (cmd) {
   case 'generate-types':
     require('../tools/generate-types.js').run(process.argv.slice(3))
     break
+  case 'create':
+    require('../tools/create-app.js').run(process.argv.slice(3))
+    break
+  case 'list':
+  case 'list-libraries':
+    require('../tools/list-libraries.js').run(process.argv.slice(3))
+    break
   case undefined:
   case '-h':
   case '--help':
@@ -20,9 +29,11 @@ switch (cmd) {
 Usage: node-gtk <command> [options]
 
 Commands:
+  create <directory>                         Create a new GTK/Adwaita app
   generate-types <Namespace-Version> [...]   Generate TypeScript types (.d.ts)
+  list [filter]                              List available libraries & versions
 
-Run \`node-gtk generate-types --help\` for details.`)
+Run \`node-gtk <command> --help\` for details.`)
     process.exit(cmd ? 0 : 1)
     break
   default:

package/lib/esm/hooks.mjs

@@ -0,0 +1,49 @@
+/*
+ * hooks.mjs — Node.js ESM module-customization hooks for the `gi:` scheme.
+ *
+ * Enables `import Gtk from 'gi:Gtk-4.0'`, where the default export is the
+ * namespace object returned by node-gtk's `gi.require('Gtk', '4.0')`. Members are
+ * read off that object: `const { Box, Label } = Gtk`.
+ *
+ * Install them with `node --import node-gtk/register app.mjs` (see register.mjs).
+ *
+ * The hooks run on a separate loader thread, so they do NO native work: `load`
+ * only emits a tiny synthetic ES module whose body calls `gi.require` on the
+ * main thread when the module is evaluated. Requires Node >= 20.6 (module.register).
+ */
+
+const PREFIX = 'gi:'
+
+/* Absolute file:// URL to lib/index.js, embedded into the generated source. The
+ * synthetic module's parent URL is the schemeless `gi:` URL, which has no
+ * filesystem base, so a bare `import 'node-gtk'` could not be resolved from it —
+ * the absolute URL sidesteps resolution entirely. */
+const INDEX_URL = new URL('../index.js', import.meta.url).href
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(PREFIX))
+    return { url: specifier, shortCircuit: true }
+  return nextResolve(specifier, context)
+}
+
+export async function load(url, context, nextLoad) {
+  if (!url.startsWith(PREFIX))
+    return nextLoad(url, context)
+
+  // `gi:Gtk-4.0` -> ('Gtk', '4.0'); `gi:Adw-1` -> ('Adw', '1'); `gi:cairo` -> ('cairo', null).
+  // Split on the first '-' only: GI namespace names never contain '-', versions may.
+  const spec = url.slice(PREFIX.length)
+  const dash = spec.indexOf('-')
+  const name = dash === -1 ? spec : spec.slice(0, dash)
+  const version = dash === -1 ? null : spec.slice(dash + 1)
+
+  const call = version === null
+    ? `gi.require(${JSON.stringify(name)})`
+    : `gi.require(${JSON.stringify(name)}, ${JSON.stringify(version)})`
+
+  const source =
+    `import gi from ${JSON.stringify(INDEX_URL)};\n` +
+    `export default ${call};\n`
+
+  return { format: 'module', shortCircuit: true, source }
+}

package/lib/esm/register.mjs

@@ -0,0 +1,17 @@
+/*
+ * register.mjs — install the `gi:` import hooks.
+ *
+ * Usage:  node --import node-gtk/register app.mjs
+ *
+ * Then, in app.mjs:
+ *     import Gtk from 'gi:Gtk-4.0'
+ *     const { Box, Label } = Gtk
+ *
+ * Note: hooks only affect imports evaluated *after* registration. To use a static
+ * `import ... from 'gi:...'` in your entry module, register via the `--import`
+ * flag above (not a programmatic `import 'node-gtk/register'` in that same file).
+ */
+
+import { register } from 'node:module'
+
+register(new URL('./hooks.mjs', import.meta.url))

package/lib/index.js

@@ -8,7 +8,7 @@ const moduleCache = internal.GetModuleCache()
 // Must be loaded first, to setup the GI functions
 const bootstrap = require('./bootstrap.js')
 const module_ = require('./module.js')
-const loop = require('./loop.js')
+require('./loop.js') // installs the automatic main-loop integration
 const registerClass = require('./register-class.js')
 
 /**
@@ -42,7 +42,6 @@ function getGType(value) {
 module.exports = {
   // Public API
   ...module_,
-  startLoop: loop.start,
   registerClass: registerClass,
   getGType: getGType,
   System: internal.System,

package/lib/index.mjs

@@ -0,0 +1,25 @@
+/*
+ * index.mjs
+ *
+ * ESM facade over the CommonJS entry (index.js), so that named imports work:
+ *
+ *     import gi, { require, registerClass } from 'node-gtk'
+ *
+ * Node's CommonJS-to-ESM named-export detection (cjs-module-lexer) cannot see
+ * through index.js's computed `module.exports`, so we re-export explicitly here.
+ * Both this file and `require('node-gtk')` share the same underlying index.js
+ * instance (Node caches it by path), so there is no duplicated state.
+ */
+
+import gi from './index.js'
+
+export default gi
+
+export const require = gi.require
+export const isLoaded = gi.isLoaded
+export const prependSearchPath = gi.prependSearchPath
+export const prependLibraryPath = gi.prependLibraryPath
+export const listAvailableModules = gi.listAvailableModules
+export const registerClass = gi.registerClass
+export const getGType = gi.getGType
+export const System = gi.System

package/lib/inspect.js

@@ -3,7 +3,7 @@ const chalk = require('chalk')
 
 const internal = require('./native.js')
 const gi = require('../lib/index');
-gi.startLoop();
+require('./loop.js').start();
 
 const infos = []
 

package/lib/loop.js

@@ -58,6 +58,11 @@ function start() {
  * @returns {*} the native return value, or undefined when deferred
  */
 function runLoopEntry(run) {
+  // The loop integration must be active before we block in a native main loop,
+  // so start it automatically on the first run. Calling startLoop() explicitly
+  // still works and is no longer required (start() is idempotent).
+  start()
+
   if (internal.IsRunningMicrotasks()) {
     setImmediate(run)
     return undefined

package/lib/module.js

@@ -129,6 +129,12 @@ function listAvailableModules() {
 // Helpers
 
 function parseModuleFilename(filename) {
-  const [name, version] = filename.replace('.typelib', '').split('-')
-  return { name, version }
+  // Typelibs are named `Name-Version.typelib`; the version is the trailing
+  // `-X.Y`, so split on the LAST dash — namespaces themselves may contain dashes
+  // (e.g. `GUPnP-DLNA-2.0` -> name `GUPnP-DLNA`, version `2.0`).
+  const base = filename.replace(/\.typelib$/, '')
+  const dash = base.lastIndexOf('-')
+  if (dash === -1)
+    return { name: base, version: '' }
+  return { name: base.slice(0, dash), version: base.slice(dash + 1) }
 }

package/lib/register-class.js

@@ -11,17 +11,50 @@ const GObject = module_.require('GObject')
 
 module.exports = registerClass
 
+// Make registerClass() optional: the first `new Subclass()` of an unregistered
+// JS subclass lazily registers it through this hook (see GObjectConstructor in
+// src/gobject.cc). registerClass() stays available for callers that need the
+// GType before constructing (e.g. getGType, GtkBuilder templates).
+internal.SetLazyClassRegister(registerClass)
+
+// A registered class owns its `__gtype__` (native classes via the prototype
+// template, JS classes via registerClass below); an unregistered subclass only
+// inherits one. Used to make registration idempotent and to find ancestors that
+// still need registering.
+function isRegistered(klass) {
+  return Object.prototype.hasOwnProperty.call(klass.prototype, '__gtype__')
+}
+
 /**
- * Create a new GObject type
+ * Create a new GObject type.
+ *
+ * To override a virtual function, define a method named `virtual_` + the
+ * camelCase vfunc name (e.g. `virtual_sizeAllocate` overrides
+ * `size_allocate`, `virtual_getRequestMode` overrides `get_request_mode`).
+ * Only `virtual_*`-prefixed methods are wired into the vtable; plain methods are
+ * never treated as overrides. Chain up to the parent implementation with
+ * `super.virtual_sizeAllocate(...)`. See doc/index.md "Inheritance".
+ *
  * @param {Class} klass - The class to register
  * @param {string} [klass.GTypeName] - The name of the GType (klass.name by default)
+ * @returns {Class} the same class (so it can be assigned or used as a decorator)
  */
 function registerClass(klass) {
+  // Idempotent: a class that already owns a GType is registered. This also makes
+  // the lazy-on-first-construct path a no-op for explicitly-registered classes.
+  if (isRegistered(klass))
+    return klass
+
   const parent = Object.getPrototypeOf(klass.prototype).constructor
 
   if (!(klass.prototype instanceof GObject.Object))
     throw new Error(`Invalid base class (${parent.name})`)
 
+  // Register any unregistered ancestor first, so a subclass can be constructed
+  // (or registered) without its superclass having been registered by hand.
+  if (!isRegistered(parent))
+    registerClass(parent)
+
   const name = createGTypeName(klass)
   const gtype = GObject.typeFromName(name)
   const parentName = getGTypeName(parent)
@@ -41,26 +74,51 @@ function registerClass(klass) {
 
   // Setup virtual functions
   setupVirtualFunctions(klass, klassGtype, parentGtype)
+
+  return klass
 }
 
 // Helpers
 
+/* Methods whose name starts with `virtual_` are treated as virtual-function
+ * overrides — and *only* those. This makes overriding explicit and opt-in: a
+ * plain method named `dispose`, `getProperty`, `sizeAllocate`, … can no longer
+ * silently hijack the matching GObject vfunc (issue #457). The prefix also keeps
+ * the override name distinct from the public invoker method of the same vfunc
+ * (e.g. `widget.sizeAllocate(...)` the method vs. the `virtual_sizeAllocate`
+ * override), so the two no longer collide. */
+const VIRTUAL_PREFIX = /^virtual_/
+
+/* `virtual_getRequestMode` -> `get_request_mode` (drop the prefix, snake_case the
+ * rest). snakeCase('virtual_getRequestMode') === 'virtual_get_request_mode'. */
+function vfuncNativeName(key) {
+  return snakeCase(key).replace(/^virtual_/, '')
+}
+
 function setupVirtualFunctions(klass, klassGtype, parentGtype) {
   const parentInfo = findInfoByGtype(parentGtype)
   if (!parentInfo)
     throw new Error(`Could not find GIR data in inheritance chain`)
 
+  const parentPrototype = Object.getPrototypeOf(klass.prototype)
+
   Object.getOwnPropertyNames(klass.prototype).forEach(key => {
     if (key === 'constructor')
       return
+    if (!VIRTUAL_PREFIX.test(key))
+      return
     if (typeof klass.prototype[key] !== 'function')
       return
 
-    const nativeName = snakeCase(key)
+    const nativeName = vfuncNativeName(key)
     const vfuncInfo = findVFunc(klassGtype, parentInfo, nativeName)
 
     if (!vfuncInfo)
-     return
+      throw new Error(
+        `${klass.name}.${key}: no virtual function '${nativeName}' on ` +
+        `'${GObject.typeName(parentGtype)}' or its interfaces. A 'virtual_*' ` +
+        `method must name an existing vfunc (e.g. 'virtual_sizeAllocate' for ` +
+        `'size_allocate'); rename it if it is a plain method.`)
 
     internal.RegisterVFunc(
       vfuncInfo,
@@ -68,6 +126,31 @@ function setupVirtualFunctions(klass, klassGtype, parentGtype) {
       nativeName,
       klass.prototype[key]
     )
+
+    installParentVFunc(parentPrototype, parentGtype, key, vfuncInfo)
+  })
+}
+
+/* Make `super.<vfunc>(...)` reachable from an override. The override replaces
+ * the parent's implementation in the class vtable, so a JS subclass otherwise
+ * has no way to call the implementation it overrode. We install, on the parent
+ * GI class's prototype, a method that invokes the *parent's* native vfunc impl
+ * (resolved through `parentGtype`'s vtable, not the overriding subclass's).
+ *
+ * Only the native boundary needs bridging: if the parent prototype already owns
+ * `key` — i.e. the parent is itself a registered JS class that overrode this
+ * vfunc — then `super.<vfunc>()` resolves to that JS method on its own. */
+function installParentVFunc(parentPrototype, parentGtype, key, vfuncInfo) {
+  if (Object.prototype.hasOwnProperty.call(parentPrototype, key))
+    return
+
+  Object.defineProperty(parentPrototype, key, {
+    value: function (...args) {
+      return internal.CallVFunc(vfuncInfo, parentGtype, this, args)
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
   })
 }
 

package/lib/styles.d.ts

@@ -0,0 +1,81 @@
+/*
+ * Type declarations for node-gtk/styles (see lib/styles.js).
+ *
+ * The public surface deals only in strings, URLs, and plain handles, so these
+ * types are self-contained — they don't reference the GTK typings.
+ */
+
+/** Options shared by the style sheets. */
+export interface StyleOptions {
+  /** Provider priority; defaults to `Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION`. */
+  priority?: number
+}
+
+/** Options for {@link StyleManager.add}. */
+export interface StyleAddOptions extends StyleOptions {
+  /**
+   * Watch the calling module for hot-reload (defaults to on in development).
+   * Pass `false` for a programmatic sheet whose source can't be re-imported
+   * safely (built inside a method, or owned by a stateful module); the handle
+   * still supports `update`/`refresh`/`remove`.
+   */
+  watch?: boolean
+}
+
+/** Options for {@link StyleManager.addFile}. */
+export interface StyleFileOptions extends StyleOptions {
+  /** Watch the file for hot-reload (defaults to on in development). */
+  watch?: boolean
+}
+
+/** A handle to an installed (or queued) stylesheet. */
+export interface StyleSheet {
+  /**
+   * Replace the CSS (or, for a file sheet, re-read the path) in place. For an
+   * inline sheet a string replaces any render function — it becomes fixed CSS.
+   */
+  update(next: string): void
+  /**
+   * Re-apply the sheet from its current source: re-run the render function
+   * (inline) or re-read the path (file). Call it when the state a render reads
+   * changes. A no-op for a queued sheet (not yet installed).
+   */
+  refresh(): void
+  /** Remove the sheet from the display. */
+  remove(): void
+}
+
+/**
+ * Applies CSS to a GTK app and, in development, hot-reloads it. The module
+ * exports a shared {@link styles} instance; constructing your own is rarely
+ * needed.
+ */
+export declare class StyleManager {
+  /**
+   * Queue (or, once the display exists, install) inline CSS. The source file it
+   * is called from is watched for hot-reload (unless `watch` is false).
+   *
+   * `css` may be a `() => string` *render* function instead of a string, for a
+   * dynamic stylesheet built from live state (theme, fonts, …). The render runs
+   * now and again on every hot-reload of its module, and on demand via the
+   * handle's {@link StyleSheet.refresh}. Keep such a module side-effect-free at
+   * its top level (a re-import re-runs it).
+   */
+  add(css: string | (() => string), options?: StyleAddOptions): StyleSheet
+
+  /**
+   * Queue (or install) a `.css` file. Unless `watch` is false, the file is
+   * watched and re-read into its provider on every edit. Idempotent per path.
+   * @param path A path, a `file://` URL string, or a `URL`.
+   */
+  addFile(path: string | URL, options?: StyleFileOptions): StyleSheet
+
+  /**
+   * Install everything queued before the display existed, and start the file
+   * watcher. Call once from your `activate` handler. Safe to call repeatedly.
+   */
+  install(): void
+}
+
+/** The application's shared StyleManager. */
+export declare const styles: StyleManager