react-x11 2.50.0 → 2.51.1

package/README.md

@@ -464,6 +464,10 @@ npx react-devtools                                # 1. start the standalone UI
 REACT_X11_DEVTOOLS=1 npm run examples:dashboard   # 2. run any example with the bridge on
 ```
 
+Under `npx react-x11 dev` the bridge is on by default (with
+`react-devtools-core` installed): run `npx react-devtools`, before or after,
+and the app shows up.
+
 The component tree, props and hook state show up live in the DevTools
 window, and editing any of them re-renders the app. Hovering an element in
 the tree tints its rect in the app's window; the toolbar's crosshair picks
@@ -498,7 +502,7 @@ Alt+Click any rendered element (Option+Click on macOS, either backend) to
 open the JSX line that created it in your editor. `REACT_X11_EDITOR` picks
 the CLI and enables the feature in one go; `REACT_X11_CLICK_TO_COMPONENT=1`
 does the same with the default editor
-(`cursor`). See [docs/click-to-component.md](docs/click-to-component.md).
+(`cursor`), and `npx react-x11 dev` turns it on by default. See [docs/click-to-component.md](docs/click-to-component.md).
 
 ## TypeScript
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.50.0",
+  "version": "2.51.1",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "bin": {
@@ -112,7 +112,7 @@
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.29.0",
+    "@windowkit/appkit": "^0.30.1",
     "@windowkit/wayland": "^3.1.1",
     "@windowkit/win32": "^0.0.9",
     "dbus-native": "^0.16.0",

package/src/DevToolsIntegration.js

@@ -1,7 +1,8 @@
 // Opt-in React DevTools bridge. Enabled by setting REACT_X11_DEVTOOLS=1 in
-// the environment; requires the `react-devtools-core` and `ws` dev
-// dependencies. Start the standalone UI first (`npx react-devtools`), then
-// run the app: REACT_X11_DEVTOOLS=1 npm run examples:dashboard
+// the environment, and on by default under `react-x11 dev`; requires the
+// `react-devtools-core` dev dependency. Run the standalone UI
+// (`npx react-devtools`) and the app, in either order:
+// REACT_X11_DEVTOOLS=1 npm run examples:dashboard
 //
 // Most of what DevTools can do costs this file nothing: the component tree,
 // props/state/hooks, and every edit the frontend makes go through the
@@ -12,12 +13,14 @@
 // Each of those is an agent listener or an option below.
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 import { setInspectHandler } from './events.js';
 import { flattenStyle, isStyleProp, STYLE_PROP_NAMES } from './styles.js';
 
 let api = null;
+let prepared = null;
 let connected = false;
 
 // ---------------------------------------------------------------------------
@@ -107,9 +110,16 @@ export function createStorage(persist) {
 /**
  * Install the DevTools global hook. Must run before the first React commit
  * so mounted roots are observed — Reconciler.js awaits this at module load
- * when REACT_X11_DEVTOOLS is set.
+ * when REACT_X11_DEVTOOLS is set — and before React Refresh patches the
+ * hook, which `react-x11 dev` calls it early for: the backend installs no
+ * hook where one exists, and Refresh's is a stub. Once per process.
  */
-export async function prepare() {
+export function prepare() {
+  prepared ??= install();
+  return prepared;
+}
+
+async function install() {
   try {
     // Each hook's source location is read off a stack captured at the hook
     // dispatch, and V8 keeps ten frames — fewer than a loader leaves
@@ -122,9 +132,6 @@ export async function prepare() {
     // react-devtools-core's backend bundle expects browser-ish globals
     global.self ??= global;
     global.window ??= global;
-    if (!global.WebSocket) {
-      global.WebSocket = (await import('ws')).default;
-    }
     // The update-tracing overlay schedules its redraws on animation
     // frames, which Node does not have; without these the first traced
     // commit throws inside the backend. Unref'd, because an overlay must
@@ -162,6 +169,7 @@ export async function prepare() {
     const mod = await import('react-devtools-core');
     // v7 exposes the API on the default export under node ESM interop
     api = mod.default?.initialize ? mod.default : mod;
+    HostSocket = hostSocketClass();
     // The hook settings the user last chose in the DevTools UI — console
     // patching and friends. `initialize()` takes them, `onSettingsUpdated`
     // (below) records them, so a setting survives a restart.
@@ -170,7 +178,7 @@ export async function prepare() {
     api = null;
     console.warn(
       'react-x11: REACT_X11_DEVTOOLS is set but devtools could not be loaded. ' +
-        'Install react-devtools-core and ws. Original error: ' +
+        'Install react-devtools-core. Original error: ' +
         err.message,
     );
   }
@@ -254,6 +262,80 @@ export function reloadAndProfile(recordChangeDescriptions, recordTimeline) {
 // Connect
 // ---------------------------------------------------------------------------
 
+// The backend keeps trying to connect for as long as the process lives — a
+// timer every two seconds while no UI is listening, and an open socket while
+// one is — and either is enough to keep a Node process up after the app's
+// last window closed. Under `react-x11 dev`, where it is on by default, that
+// was every session hanging on close. Neither is reachable from the options:
+// so the backend's own code runs in a scope where the timers it starts are
+// unref'd and the sockets it opens are, too. The scope is entered where the
+// backend is — our connect call, its socket's close and error handlers that
+// schedule the retry, and the timers it set in the scope — and swaps the
+// globals only for that synchronous stretch, so the app's own `setTimeout`
+// and `WebSocket` are never the ones changed.
+let HostSocket = null;
+
+function inBackend(fn) {
+  const { setTimeout: appSetTimeout, WebSocket: appWebSocket } = globalThis;
+  globalThis.setTimeout = (callback, ...rest) => {
+    const timer = appSetTimeout(
+      typeof callback === 'function'
+        ? (...args) => inBackend(() => callback(...args))
+        : callback,
+      ...rest,
+    );
+    timer?.unref?.();
+    return timer;
+  };
+  if (HostSocket) globalThis.WebSocket = HostSocket;
+  try {
+    return fn();
+  } finally {
+    globalThis.setTimeout = appSetTimeout;
+    globalThis.WebSocket = appWebSocket;
+  }
+}
+
+/**
+ * The backend's WebSocket: `ws`, from react-devtools-core's own
+ * dependencies, with its socket unref'd once open and its close and error
+ * handlers run in the backend's scope. Falls back to the platform's
+ * WebSocket, which works and holds the process open.
+ */
+function hostSocketClass() {
+  let WS;
+  try {
+    WS = createRequire(import.meta.resolve('react-devtools-core'))('ws');
+  } catch {
+    return globalThis.WebSocket ?? null;
+  }
+  class Socket extends WS {
+    constructor(...args) {
+      super(...args);
+      this.on('open', () => this._socket?.unref?.());
+    }
+  }
+  for (const name of ['onclose', 'onerror']) {
+    const base = Object.getOwnPropertyDescriptor(WS.prototype, name);
+    if (!base?.set) continue;
+    Object.defineProperty(Socket.prototype, name, {
+      configurable: true,
+      get() {
+        return base.get.call(this);
+      },
+      set(handler) {
+        base.set.call(
+          this,
+          typeof handler === 'function'
+            ? (...args) => inBackend(() => handler(...args))
+            : handler,
+        );
+      },
+    });
+  }
+  return Socket;
+}
+
 /** Connect the backend to the standalone DevTools app and register the
  * renderer. Called by Reconciler.js right after the renderer is created. */
 export function connect(renderer) {
@@ -261,39 +343,41 @@ export function connect(renderer) {
   connected = true;
   const profiling = readProfilingOnStart();
 
-  api.connectToDevTools({
-    isAppActive: () => true,
-    host: process.env.REACT_X11_DEVTOOLS_HOST || 'localhost',
-    port: Number(process.env.REACT_X11_DEVTOOLS_PORT) || 8097,
-    // The style editor: `style` is a react-x11 style prop (an object, or a
-    // nested array of them), which is the shape DevTools' own resolver
-    // expects to be handed flat. `validAttributes` is what it offers to
-    // add to an element.
-    resolveRNStyle: resolveStyle,
-    nativeStyleEditorValidAttributes: STYLE_PROP_NAMES,
-    // Hook settings (console patching and so on) are the user's, not the
-    // run's: keep them where the next run will find them.
-    onSettingsUpdated: (settings) => {
-      try {
-        global.localStorage?.setItem(
-          HOOK_SETTINGS_KEY,
-          JSON.stringify(settings),
-        );
-      } catch {
-        // an unwritable store is not worth a warning per keystroke
-      }
-    },
-    // The backend's own check for this asks whether synchronous XHR works,
-    // which is a browser question — the honest answer for a node process
-    // that can re-exec itself is yes.
-    isReloadAndProfileSupported: true,
-    isProfiling: profiling != null,
-    onReloadAndProfile: reloadAndProfile,
-    onReloadAndProfileFlagsReset: () => {
-      delete process.env.REACT_X11_DEVTOOLS_PROFILING;
-      delete process.env.REACT_X11_DEVTOOLS_SESSION;
-    },
-  });
+  inBackend(() =>
+    api.connectToDevTools({
+      isAppActive: () => true,
+      host: process.env.REACT_X11_DEVTOOLS_HOST || 'localhost',
+      port: Number(process.env.REACT_X11_DEVTOOLS_PORT) || 8097,
+      // The style editor: `style` is a react-x11 style prop (an object, or a
+      // nested array of them), which is the shape DevTools' own resolver
+      // expects to be handed flat. `validAttributes` is what it offers to
+      // add to an element.
+      resolveRNStyle: resolveStyle,
+      nativeStyleEditorValidAttributes: STYLE_PROP_NAMES,
+      // Hook settings (console patching and so on) are the user's, not the
+      // run's: keep them where the next run will find them.
+      onSettingsUpdated: (settings) => {
+        try {
+          global.localStorage?.setItem(
+            HOOK_SETTINGS_KEY,
+            JSON.stringify(settings),
+          );
+        } catch {
+          // an unwritable store is not worth a warning per keystroke
+        }
+      },
+      // The backend's own check for this asks whether synchronous XHR works,
+      // which is a browser question — the honest answer for a node process
+      // that can re-exec itself is yes.
+      isReloadAndProfileSupported: true,
+      isProfiling: profiling != null,
+      onReloadAndProfile: reloadAndProfile,
+      onReloadAndProfileFlagsReset: () => {
+        delete process.env.REACT_X11_DEVTOOLS_PROFILING;
+        delete process.env.REACT_X11_DEVTOOLS_SESSION;
+      },
+    }),
+  );
 
   // No argument: react-reconciler 0.33 takes none, and the object this used
   // to pass was discarded in silence. The renderer's name and version now

package/src/Reconciler.js

@@ -592,16 +592,15 @@ let integrationsSettled = false;
 function loadIntegrations() {
   if (integrationsSettled) return null;
   if (
-    !process.env.REACT_X11_DEVTOOLS &&
-    !process.env.REACT_X11_CLICK_TO_COMPONENT &&
-    !process.env.REACT_X11_EDITOR &&
+    !envFlag('REACT_X11_DEVTOOLS') &&
+    !clickToComponentWanted() &&
     !process.env.REACT_X11_TRACE
   ) {
     return null;
   }
   if (integrations) return integrations;
   integrations = (async () => {
-    if (process.env.REACT_X11_DEVTOOLS) {
+    if (envFlag('REACT_X11_DEVTOOLS')) {
       // Install the DevTools hook before any React commit, and register the
       // renderer with the standalone DevTools app.
       const devtools = await import('./DevToolsIntegration.js');
@@ -609,12 +608,7 @@ function loadIntegrations() {
       devtools.connect(Renderer);
     }
 
-    if (
-      process.env.REACT_X11_CLICK_TO_COMPONENT ||
-      process.env.REACT_X11_EDITOR
-    ) {
-      // Naming an editor already means you want the feature on — no need to
-      // also set REACT_X11_CLICK_TO_COMPONENT=1 just to pick one.
+    if (clickToComponentWanted()) {
       const clickToComponent = await import('./ClickToComponent.js');
       clickToComponent.install();
     }
@@ -632,6 +626,28 @@ function loadIntegrations() {
   return integrations;
 }
 
+/**
+ * Whether to install click-to-component. Naming an editor already means you
+ * want the feature on — no need to also set REACT_X11_CLICK_TO_COMPONENT=1
+ * just to pick one — and `0` turns it off whatever else is set, which is
+ * the way out of `react-x11 dev`, where it is on by default and
+ * REACT_X11_EDITOR also picks the error window's editor.
+ */
+function clickToComponentWanted() {
+  if (process.env.REACT_X11_CLICK_TO_COMPONENT === '0') return false;
+  return (
+    envFlag('REACT_X11_CLICK_TO_COMPONENT') ||
+    Boolean(process.env.REACT_X11_EDITOR)
+  );
+}
+
+/** A switch in the environment: set, and not `0` — the way out of a
+ * default `react-x11 dev` turns on. */
+function envFlag(name) {
+  const value = process.env[name];
+  return Boolean(value) && value !== '0';
+}
+
 /**
  * Open a connection this process owns. The wrapper is here for one reason:
  * to say what is wrong when there is no server, which is the first thing

package/src/cli/dev.js

@@ -27,12 +27,26 @@
 //    missing, names them with the versions the loader is written against, and
 //    installs them with the project's own package manager when the developer
 //    says yes. Without a terminal to ask on it prints the command instead.
+//  - **It turns click-to-component on.** Alt+Click (Option+Click on macOS)
+//    opens the JSX line an element came from (docs/click-to-component.md):
+//    a development tool, and this is the command a developer runs, so it is
+//    on unless REACT_X11_CLICK_TO_COMPONENT=0 says otherwise. Set here, in
+//    the environment, because that is where the renderer reads it when the
+//    first root is made — and where a toolchain restart inherits it from.
+//  - **It connects to React DevTools** whenever `npx react-devtools` is
+//    running, before or after the app started, the way a browser with the
+//    extension does: on by default where react-devtools-core is installed,
+//    unless REACT_X11_DEVTOOLS=0. Where it is not, and a DevTools UI is
+//    listening at start, it says what to install. Prepared before React
+//    Refresh loads, because Refresh installs a stub hook where it finds none,
+//    and the backend installs none where it finds one.
 //  - **It runs the project's react-x11.** A second copy of the renderer is a
 //    second React root nobody refreshes, so a global or npx-cached
 //    `react-x11` hands over to the copy the file itself imports.
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import * as nodeModule from 'node:module';
+import { connect } from 'node:net';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -122,6 +136,18 @@ export async function runDev(file, options = {}) {
     return null;
   }
 
+  process.env.REACT_X11_CLICK_TO_COMPONENT ??= '1';
+  if (process.env.REACT_X11_DEVTOOLS === undefined) {
+    if (resolves('react-devtools-core')) {
+      process.env.REACT_X11_DEVTOOLS = '1';
+    } else {
+      suggestDevTools({ projectDir, log });
+    }
+  }
+  if (envFlag(process.env.REACT_X11_DEVTOOLS)) {
+    await (await import('../DevToolsIntegration.js')).prepare();
+  }
+
   // Before anything below loads: a module's source maps are read when it
   // loads, and only once this is on.
   process.setSourceMapsEnabled(true);
@@ -386,6 +412,48 @@ function rootContent(node) {
   return { windows, drawn };
 }
 
+/** Whether `specifier` resolves from react-x11, which is where it is
+ * imported from. */
+function resolves(specifier) {
+  try {
+    import.meta.resolve(specifier);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The renderer's rule for a switch: set, and not `0`. */
+function envFlag(value) {
+  return Boolean(value) && value !== '0';
+}
+
+/**
+ * Where react-devtools-core is missing: if a DevTools UI is listening (one
+ * TCP connect, in the background, never holding the process), say what to
+ * install for the app to show up in it. Silent otherwise — no DevTools
+ * running is the usual case, not one to print about.
+ */
+function suggestDevTools({ projectDir, log }) {
+  const host = process.env.REACT_X11_DEVTOOLS_HOST || 'localhost';
+  const port = Number(process.env.REACT_X11_DEVTOOLS_PORT) || 8097;
+  const socket = connect({ host, port });
+  socket.unref();
+  socket.setTimeout(1000, () => socket.destroy());
+  socket.on('error', () => {});
+  socket.on('connect', () => {
+    socket.destroy();
+    const line = shellLine(
+      installCommand(packageManagerFor(projectDir), ['react-devtools-core']),
+    );
+    log(
+      `React DevTools is listening on ${host}:${port}, and this project ` +
+        'cannot connect to it without react-devtools-core. Install it, and ' +
+        `the next run shows up there:\n\n  ${line}\n`,
+    );
+  });
+}
+
 /** The react-x11 package `path` imports, or null when it imports none. */
 export function reactX11For(path) {
   let entry;

package/src/cli/index.js

@@ -17,6 +17,10 @@ Commands:
                  export is mounted, inside a window of its own when it
                  renders none; a file that mounts its own root runs as it is.
                  Arguments after the file are the app's.
+                 Alt+Click (Option+Click on macOS) an element to open its
+                 source; REACT_X11_CLICK_TO_COMPONENT=0 turns that off.
+                 Connects to React DevTools (npx react-devtools) whenever
+                 it runs; REACT_X11_DEVTOOLS=0 turns that off.
 
 Options:
   -h, --help     Show this help.

package/src/cocoa/app.js

@@ -1447,6 +1447,9 @@ export class CocoaApp {
         return this._animationEnds.get(ev.id)?.(ev);
       case 'window-live-resize':
         return this._routeLiveResize(ev);
+      case 'window-fullscreen':
+      case 'window-miniaturize':
+        return this._routeWindowState(ev);
       case 'window-created':
         // a worker's window, made on the UI thread after the call that
         // answered its handle
@@ -1611,6 +1614,8 @@ export class CocoaApp {
     // this is the only thing the bridge says about it (`_recheckScreens`).
     this._recheckScreens();
     wnd._nativeResized(ev);
+    // AppKit says nothing of a zoom but the resize it makes
+    if (ev.type === 'window-resize') wnd._refreshStates();
     wnd.emit('resize', {
       width: wnd.width,
       height: wnd.height,
@@ -1676,6 +1681,22 @@ export class CocoaApp {
     wnd.emit('liveresize', { live: wnd.liveResizing });
   }
 
+  /**
+   * `window-fullscreen { fullscreen, phase }` and `window-miniaturize`
+   * (@windowkit/appkit 0.30.0): the title bar's green button, the Dock, and
+   * the same asked for through `setWmState`. The bridge has published the
+   * state already — a full-screen transition's target from its `begin`,
+   * before the animation, which is the moment an app takes its chrome away
+   * — so the window reads it back and says `statechange` if it moved. A
+   * user's own act, so it is input: its render goes out like a click's.
+   */
+  _routeWindowState(ev) {
+    const wnd = this._window(ev);
+    if (!wnd || wnd.destroyed) return;
+    wnd._refreshStates();
+    this._afterInput();
+  }
+
   /**
    * `surface-released`: a worker's frame took an IOSurface off a layer and
    * the frame that replaced it has committed (windowkit/appkit#52). The
@@ -1759,6 +1780,7 @@ export class CocoaApp {
     const wnd = this._window(ev);
     if (!wnd) return;
     if (name === 'focus') this._lastKeyWindow = wnd;
+    wnd._refreshStates();
     wnd.emit(name, { buttons: 0, time: ev.time });
     this._afterInput();
   }

package/src/cocoa/relaunch.js

@@ -246,8 +246,10 @@ export function describeProcess(moduleUrl) {
     platform: process.platform,
     env: process.env,
     execArgv: process.execArgv,
-    // Node's major version; Bun answers with one of its own choosing
-    node: bun ? null : Number(process.versions.node.split('.')[0]),
+    // Node's major version; Bun answers with one of its own choosing, and a
+    // web page's `process` (the playground's) names no node at all — read
+    // here before any veto, so a throw would end every import of react-x11
+    node: bun ? null : Number(process.versions?.node?.split('.')[0]) || null,
     entry: typeof entry === 'string' && fs.existsSync(entry) ? entry : null,
     compiled: compiledExecutable(bun),
     late: startedRunning(bun, moduleUrl, entry),

package/src/cocoa/window.js

@@ -11,6 +11,15 @@ import { CocoaDropTransport, dragSpec } from './dnd.js';
 import { CocoaLayerPresenter } from './presenter.js';
 import { CocoaPromotion } from './promotion.js';
 
+/** The bridge verb each `_NET_WM_STATE` name maps onto (`setWmState`). */
+const STATE_VERBS = {
+  fullscreen: 'setWindowFullScreen',
+  maximized: 'setWindowZoomed',
+  maximized_vert: 'setWindowZoomed',
+  maximized_horz: 'setWindowZoomed',
+  hidden: 'setWindowMiniaturized',
+};
+
 let nextWindowId = 1;
 // The slack a frame clock allows under its interval, in ms: a timer's drift
 // and no more (`CocoaApp._frameDue`, `_frameWait`, `nextFrameAt`). It lives
@@ -275,6 +284,10 @@ export class CocoaWindow {
   // --- events --------------------------------------------------------------
 
   on(name, fn) {
+    // what a change is measured from: the states when the first listener
+    // came, which it reads for itself with getWmStates
+    if (name === 'statechange' && !this._lastStates)
+      this._lastStates = this.getWmStatesNow();
     let list = this._handlers.get(name);
     if (!list) this._handlers.set(name, (list = []));
     list.push(fn);
@@ -286,6 +299,14 @@ export class CocoaWindow {
     };
   }
 
+  /** ntk's spelling of the function `on` answers, for a listener held by
+   * the function it added (`useWindowState`'s `statechange`). */
+  off(name, fn) {
+    const list = this._handlers.get(name);
+    const at = list ? list.indexOf(fn) : -1;
+    if (at >= 0) list.splice(at, 1);
+  }
+
   emit(name, ev) {
     const list = this._handlers.get(name);
     if (!list) return;
@@ -449,33 +470,95 @@ export class CocoaWindow {
   setActions() {}
 
   /**
-   * `_NET_WM_STATE` requests, as far as this backend has verbs for them:
-   * `demands_attention` is the Dock bounce (`requestUserAttention`), held
-   * until the state is removed or the window goes. Every other name resolves
-   * `false` — ntk's own contract for a state the server cannot honour —
-   * because the bridge has no zoom/miniaturize/fullscreen verbs yet
-   * (windowkit/appkit#15 scoped them out); WindowNode swallows the false.
+   * `_NET_WM_STATE` requests, with the verb AppKit has for each:
+   *
+   * | name | verb |
+   * | --- | --- |
+   * | `fullscreen` | the green button's full-screen Space (`setWindowFullScreen`) |
+   * | `maximized`, `maximized_vert`, `maximized_horz` | the zoom to the standard frame (`setWindowZoomed`) — AppKit zooms both axes or neither |
+   * | `hidden` | to the Dock and back (`setWindowMiniaturized`) |
+   * | `demands_attention` | the Dock bounce (`requestUserAttention`), held until the state is removed or the window goes |
+   *
+   * Every other name resolves `false` — ntk's own contract for a state the
+   * server cannot honour — and so does a name whose verb a bridge older than
+   * @windowkit/appkit 0.30.0 does not have; WindowNode swallows the false.
+   * A transition is AppKit's to animate, and what happened comes back as
+   * `statechange` (`_refreshStates`).
    */
   setWmState(names, action = 'add') {
     const list = Array.isArray(names) ? names : [names];
+    const held = action === 'toggle' ? new Set(this.getWmStatesNow()) : null;
+    const wants = (name) => (held ? !held.has(name) : action !== 'remove');
     let honoured = true;
     for (const name of list) {
-      if (name !== 'demands_attention') {
-        honoured = false;
+      if (name === 'demands_attention') {
+        const holding = this._attentionRequest != null;
+        const on = action === 'toggle' ? !holding : action === 'add';
+        if (on && !holding && !this.destroyed) {
+          this._attentionRequest = this.app.requestAttention();
+        } else if (!on && holding) {
+          this.app.cancelAttention(this._attentionRequest);
+          this._attentionRequest = null;
+        }
         continue;
       }
-      const held = this._attentionRequest != null;
-      const wants = action === 'add' || (action === 'toggle' && !held);
-      if (wants && !held && !this.destroyed) {
-        this._attentionRequest = this.app.requestAttention();
-      } else if (!wants && held) {
-        this.app.cancelAttention(this._attentionRequest);
-        this._attentionRequest = null;
+      const verb = STATE_VERBS[name];
+      const fn = verb && this._native[verb];
+      if (typeof fn !== 'function' || this.destroyed) {
+        honoured = false;
+        continue;
       }
+      // a toggle of an axis reads the pair: zoomed is both or neither
+      const on =
+        held && verb === 'setWindowZoomed'
+          ? !held.has('maximized_vert')
+          : wants(name);
+      fn.call(this._native, this._h, on);
     }
     return Promise.resolve(honoured);
   }
 
+  /**
+   * What AppKit has done with the window, in `_NET_WM_STATE` names — the
+   * names the X11 and Wayland windows report, so `useWindowState()` and
+   * `onStatesChange` read them the same way: `fullscreen`, the zoom as
+   * `maximized_vert` + `maximized_horz`, the Dock as `hidden`, the key
+   * window as `focused`. Read from the bridge's published window state, so
+   * a worker answers without a hop; `fullscreen` there says where a
+   * transition is going from the moment it starts, which is when an app
+   * hides its chrome. A bridge older than 0.30.0 publishes only `key`.
+   */
+  getWmStatesNow() {
+    const f = this._h != null ? this._native.getWindowFrame?.(this._h) : null;
+    if (!f) return [];
+    const out = [];
+    if (f.fullscreen) out.push('fullscreen');
+    if (f.zoomed) out.push('maximized_vert', 'maximized_horz');
+    if (f.miniaturized) out.push('hidden');
+    if (f.key) out.push('focused');
+    return out;
+  }
+
+  getWmStates() {
+    return Promise.resolve(this.getWmStatesNow());
+  }
+
+  /**
+   * Something that can change the states happened — a full-screen
+   * transition, the Dock, a resize (AppKit says nothing of a zoom but the
+   * resize), the key window moving — so read them again and say so if they
+   * moved. Free for a window nobody asked: no listener, no read.
+   */
+  _refreshStates() {
+    if (this.destroyed || !this._handlers.get('statechange')?.length) return;
+    const next = this.getWmStatesNow();
+    const was = this._lastStates ?? [];
+    this._lastStates = next;
+    if (was.length === next.length && was.every((n, i) => n === next[i]))
+      return;
+    this.emit('statechange', next);
+  }
+
   // --- drag and drop (src/cocoa/dnd.js) ------------------------------------
 
   /**

package/src/nodes/scrollable.js

@@ -247,7 +247,10 @@ export const Scrollable = (Base) =>
         // NaN, which a scroll pane in there measured its content from and
         // threw on, out of the frame. The box itself has its empty rect;
         // what is inside is placed when it is shown and laid out again.
-        if (this.style.display !== 'none') {
+        // Both routes to it: the style, and the `hidden` React sets for
+        // `<Activity>` and `<Suspense>` (`setHidden`), which reaches yoga
+        // without touching the style.
+        if (this.style.display !== 'none' && !this.hidden) {
           this._absolutizeChildren(
             this.abs.x,
             this.abs.y,

package/src/types/elements.d.ts

@@ -429,9 +429,12 @@ export interface WindowProps
    * Applied before the window is mapped, which is the only way to open
    * already fullscreen rather than flashing at the normal size first.
    *
-   * On the cocoa backend `demands_attention` bounces the Dock icon until
+   * On the cocoa backend `fullscreen` is the green button's full-screen
+   * Space, `maximized` (either axis) the zoom to the standard frame,
+   * `hidden` the Dock, and `demands_attention` bounces the Dock icon until
    * the app is activated and is cancelled when the state is removed; the
-   * other names have no verb in the bridge yet and resolve to nothing.
+   * other names have no AppKit equivalent and resolve to nothing, as the
+   * first three do on a bridge older than @windowkit/appkit 0.30.0.
    */
   states?: WindowStateName[];
   /** Sugar for `states={['fullscreen']}`; they union. */

package/src/types/system.d.ts

@@ -127,7 +127,10 @@ export interface WindowState {
   /** Both axes. One axis alone shows up in `states`. */
   readonly maximized: boolean;
   /** What the window manager actually did, not what `<window fullscreen>`
-   *  asked for. */
+   *  asked for — the title bar's button included. On the cocoa backend it
+   *  turns as AppKit's transition begins, before the animation, so chrome
+   *  an app hides in full screen goes while the window grows rather than
+   *  after. */
   readonly fullscreen: boolean;
   /** The raw `_NET_WM_STATE` names, e.g. `['maximized_vert', 'focused']` —
    *  what the window manager put there, where `<window states>` is what was