react-x11 2.16.1 → 2.17.0

package/src/cocoa/panewindow.js

@@ -14,7 +14,7 @@
 // via emit. Geometry and input arrive as channel messages (the host owns
 // layout and hit-testing — this is CPU offloading, not isolation), and the
 // only outbound traffic is pane-present.
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 
 let nextPaneId = 1;
 
@@ -183,7 +183,7 @@ export class CocoaPaneWindow {
 
   getContext() {
     if (!this._ctx) {
-      this._ctx = new CocoaContext2D(
+      this._ctx = new BackendContext2D(
         this._native,
         () => this._ensureSurface(),
         () => {

package/src/cocoa/presenter.js

@@ -30,7 +30,7 @@ import { Node } from '../nodes/node.js';
 import { addDamageRect, damageToPaint } from '../nodes/damage.js';
 import { intersectRects } from '../nodes/rects.js';
 import { EASING_CONTROL_POINTS, TRANSITION_CONTROL_POINTS } from '../styles.js';
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 
 export const RASTER_PAD = 2; // antialiasing/italic overhang outside the ink bounds
 
@@ -431,7 +431,7 @@ export class RasterState {
       this.height = height;
       this.gen++;
       if (!this.ctx) {
-        this.ctx = new CocoaContext2D(
+        this.ctx = new BackendContext2D(
           presenter.native,
           () => this.surface,
           () => this.gen,

package/src/cocoa/surface.js

@@ -6,7 +6,7 @@
 // buffer the same way on both backends and names neither:
 //
 //   const surface = new Surface(app, { width, height });   // device pixels
-//   const ctx = surface.getContext('2d');                    // a CocoaContext2D
+//   const ctx = surface.getContext('2d');                    // a BackendContext2D
 //   ctx.fillRect(0, 0, width, height);
 //   surface.copyWithin({ x: 0, y: 0, width, height }, 0, -rowHeight);
 //   windowCtx.drawImage(surface, x, y);                      // one composite
@@ -43,7 +43,7 @@
 // one from `contentBox()` numbers, which are device pixels already
 // (docs/scale.md). The bridge is told the app's scale so the bitmap carries
 // it — inert for a `drawImage` source, right for a layer's contents.
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 
 export class CocoaSurface {
   constructor(app, { width, height, format = 'argb32' } = {}) {
@@ -113,7 +113,7 @@ export class CocoaSurface {
 
   _context() {
     if (!this._ctx) {
-      this._ctx = new CocoaContext2D(
+      this._ctx = new BackendContext2D(
         this._native,
         () => this._handle(),
         () => 1,

package/src/cocoa/window.js

@@ -6,7 +6,7 @@
 // an X window — attributes, reported width/height, event coordinates,
 // _screenOrigin. The divide-by-scale into Cocoa points happens against the
 // native layer and nowhere above it.
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 import { CocoaDropTransport, dragSpec } from './dnd.js';
 import { CocoaLayerPresenter } from './presenter.js';
 import { CocoaPromotion } from './promotion.js';
@@ -794,7 +794,7 @@ export class CocoaWindow {
 
   getContext() {
     if (!this._ctx) {
-      this._ctx = new CocoaContext2D(
+      this._ctx = new BackendContext2D(
         this._native,
         () => this._ensureSurface(),
         () => {

package/src/events.js

@@ -113,6 +113,27 @@ class SyntheticEvent {
     this.ctrlKey = Boolean(native?.buttons & MOD.Control);
     this.altKey = Boolean(native?.buttons & MOD.Alt);
     this.metaKey = Boolean(native?.buttons & MOD.Super);
+    // Where the pointer is on the **virtual screen**, in the same logical
+    // pixels `x`/`y` are in — the DOM's name for the DOM's quantity, and the
+    // one an app should reach for when it places something outside the
+    // window (a context menu at the pointer, a drag preview).
+    //
+    // `nativeEvent.rootx`/`rooty` is X11's name for it, is still there, and
+    // is still in *device* pixels: the same split as `ev.x` against
+    // `nativeEvent.x`. Defined exactly where the backend reported a position
+    // — an X11 KeyPress carries one too, so this is not pointer-events-only —
+    // and absent otherwise, because a made-up 0 would read as the screen's
+    // top-left corner rather than as "no answer".
+    if (native?.rootx !== undefined && native?.rootx !== null) {
+      // The **window's** scale, not the target's. `x`/`y` are in the target's
+      // unit on purpose, so a subtree zoomed by a `scale` prop reads its own
+      // — but a screen coordinate is not in that subtree's space at all, and
+      // dividing it by a zoom factor would put it somewhere nobody is. The
+      // drag events have always computed it this way (src/dnd.js).
+      const screen = manager.scale;
+      this.screenX = native.rootx / screen;
+      this.screenY = (native.rooty ?? 0) / screen;
+    }
     this.defaultPrevented = false;
     this.propagationStopped = false;
     if (extra) Object.assign(this, extra);

package/src/foreignnodes.js

@@ -192,10 +192,15 @@ export class ForeignNode extends Node {
    */
   _refuse() {
     this._refused = true;
+    // Named by the capability, not by the backend that happens to have it.
+    // An app cannot act on "use X11", and a second backend growing embedding
+    // would make that wording wrong as well as unhelpful; what an app *can*
+    // act on is the question the last sentence names (AGENTS.md,
+    // "Vocabulary").
     const err = new Error(
-      'react-x11: <foreign> needs the X11 backend — this one has no ' +
-        'cross-process window embedding, so nothing can be put in it. Ask ' +
-        "useSupports('embedding') before rendering one.",
+      'react-x11: <foreign> needs a backend with cross-process window ' +
+        'embedding, and this one has none — so nothing can be put in it. ' +
+        "Ask useSupports('embedding') before rendering one.",
     );
     this.error = err;
     // The client is the whole reason this node is a Tab stop by default, and

package/src/frame/index.js

@@ -44,6 +44,7 @@ import React, {
 } from 'react';
 
 import { useAppOrNull } from '../appcontext.js';
+import { canEmbed } from '../embedding.js';
 import { FrameEnv } from './env.js';
 import { CallbackTable, PROTOCOL } from './protocol.js';
 
@@ -221,11 +222,14 @@ export function Frame({
   ref,
 }) {
   const env = useContext(FrameEnv);
-  // A backend that composites panes from shared memory (Cocoa) declares
-  // itself with createPaneHost; everything else embeds the pane's real
-  // window through <foreign>, exactly as before.
+  // A backend that composites panes from a shared buffer (Cocoa, Windows)
+  // declares itself with createPaneHost; everything else embeds the pane's
+  // real window through <foreign>, exactly as before.
   const appOrNull = useAppOrNull();
   const paneApp = appOrNull?.createPaneHost ? appOrNull : null;
+  // Two mechanisms, one question: is there any way to *show* a pane here?
+  // Asked before the fork rather than after it — see the session effect.
+  const canShowPane = Boolean(paneApp) || canEmbed(appOrNull);
   const [state, setState] = useState({
     phase: 'starting',
     windowId: null,
@@ -262,6 +266,28 @@ export function Frame({
       setState({ phase: 'failed', windowId: null, error });
     };
 
+    // Before the fork, not after it. A backend with neither mechanism used
+    // to start the pane, let it load its module and mount, and only then
+    // discover at the embed that there was nowhere to put it — a whole
+    // process spawned and killed to reach a conclusion the app object had
+    // all along. The fallback it renders is the same one either way; what
+    // changes is that it renders at once and costs nothing.
+    if (!canShowPane) {
+      fail(
+        Object.assign(
+          new Error(
+            'react-x11: <Frame> needs a backend that can show a pane — one ' +
+              'that composites panes from a shared buffer, or one with ' +
+              'cross-process window embedding — and this one has neither, ' +
+              'so no pane was started. Ask ' +
+              "useSupports('embedding') before rendering one.",
+          ),
+          { phase: 'embed' },
+        ),
+      );
+      return undefined;
+    }
+
     let t;
     try {
       t = makeTransport({ src: source, display });
@@ -396,7 +422,7 @@ export function Frame({
       // ask, and everything is unref'd so nothing holds the host open
       if (session.current === s) session.current = null;
     };
-  }, [source, display, generation, makeTransport]);
+  }, [source, display, generation, makeTransport, canShowPane]);
 
   // One update per commit that changed the pane's inputs, props and env in
   // the same message — so a theme flip and the state change that caused it

package/src/glnodes.js

@@ -58,9 +58,20 @@ export function glxConfig(app, spec) {
         .chooseGLXConfig(spec)
         .then((config) => ({ backend: 'indirect', ...config }));
     } else {
+      // Which backend is asking decides what the honest answer is. Telling a
+      // Windows user to upgrade ntk sends them after a package that backend
+      // does not use, and an error a developer cannot act on is worse than
+      // the feature simply being absent (AGENTS.md, "An error you hit is an
+      // error an app developer will hit").
       promise = Promise.reject(
         new Error(
-          'react-x11: <glarea> needs ntk >= 3.6.0 (app.chooseGLConfig)',
+          process.platform === 'win32'
+            ? 'react-x11: <glarea> is not built on the win32 backend yet — it ' +
+                'needs ANGLE (EGL and GLES over Direct3D 11), which ' +
+                'docs/windows.md plans as an optional dependency the way ' +
+                'x11-dri is on X11. Everything else on this backend works ' +
+                'without it; for GL content today, use the X11 backend.'
+            : 'react-x11: <glarea> needs ntk >= 3.6.0 (app.chooseGLConfig)',
         ),
       );
     }

package/src/idle.js

@@ -186,6 +186,17 @@ class IdleWatcher {
  */
 async function armIdle(watcher) {
   const session = watcher.session;
+
+  // The Windows rung, first because it is the only one there: everything
+  // below this reaches into `app.X`, and a tree that is not on an X server
+  // has none. `GetLastInputInfo` answers for the whole session, which is what
+  // an idle timeout means, so the shape is the polling rung's — with the
+  // answer arriving synchronously instead of over a connection.
+  if (typeof session.app?.lastInputMs === 'function') {
+    pollLastInput(watcher);
+    return;
+  }
+
   const counter = await session.counter();
   if (watcher.stopped) return;
 
@@ -281,6 +292,31 @@ function poll(watcher, saver) {
   });
 }
 
+/**
+ * The same adaptive wait as {@link poll}, over a counter this process can read
+ * without asking anybody: `GetLastInputInfo` is a call, not a round trip.
+ *
+ * The two directions are still asymmetric for the same reason. Not idle yet:
+ * sleep for exactly the remainder. Idle: nothing says when the user will come
+ * back, and no input reaches this process while they are typing in another
+ * window, so poll on an interval scaled to the timeout.
+ */
+function pollLastInput(watcher) {
+  if (watcher.stopped) return;
+  const elapsed = watcher.session.app.lastInputMs?.();
+  if (typeof elapsed !== 'number') return;
+  const idle = elapsed >= watcher.timeout;
+  watcher.set(idle);
+  clearTimeout(watcher._timer);
+  watcher._timer = setTimeout(
+    () => pollLastInput(watcher),
+    idle
+      ? Math.min(30_000, Math.max(1_000, watcher.timeout / 4))
+      : Math.max(250, watcher.timeout - elapsed),
+  );
+  watcher._timer.unref?.();
+}
+
 function schedule(watcher, saver, delay) {
   clearTimeout(watcher._timer);
   watcher._timer = setTimeout(() => poll(watcher, saver), delay);
@@ -364,7 +400,12 @@ export function setIdleForTests(app, timeout, idle) {
  * code and for tests.
  */
 export async function keepAwake({ reason = 'Busy', app = null } = {}) {
-  for (const rung of [portalInhibit, screenSaverInhibit, xInhibit]) {
+  for (const rung of [
+    windowsInhibit,
+    portalInhibit,
+    screenSaverInhibit,
+    xInhibit,
+  ]) {
     try {
       const release = await rung(reason, app);
       if (release) return once(release);
@@ -375,6 +416,23 @@ export async function keepAwake({ reason = 'Busy', app = null } = {}) {
   return () => {};
 }
 
+/**
+ * Rung 0: `SetThreadExecutionState`, on Windows.
+ *
+ * Above the portal rungs because it is the only one a Windows session has,
+ * and below nothing: on a desktop with a portal this returns null on the
+ * first line and costs a property read.
+ *
+ * `reason` is dropped rather than passed. Windows takes no string with the
+ * call — `powercfg /requests` names the process, not a reason — and inventing
+ * somewhere to put it would be pretending the system shows it.
+ */
+async function windowsInhibit(reason, app) {
+  const hold = app?.keepAwake;
+  if (typeof hold !== 'function') return null;
+  return hold.call(app, true);
+}
+
 /** A release that runs once however many times it is called — a double
  *  release would drop somebody else's inhibition on the counted X rung. */
 function once(fn) {

package/src/index.d.ts

@@ -27,6 +27,7 @@ export * from './types/fonts.js';
 export * from './types/system.js';
 export * from './types/capabilities.js';
 export * from './types/launcher.js';
+export * from './types/taskbar.js';
 export * from './types/tray.js';
 export * from './types/permissions.js';
 export * from './types/notifications.js';
@@ -62,6 +63,46 @@ export function useWindowId(
   ref: RefObject<NtkWindow | DrawnNode | null>,
 ): () => number | null;
 
+/**
+ * The handle **another process** embeds to show this window, or `null` where
+ * this backend cannot hand one out.
+ *
+ * The companion to `<window embeddable>`, and deliberately not
+ * {@link windowIdOf}: on X11 the two are the same number, and everywhere
+ * else they are not.
+ *
+ * - **X11** — the window's XID, which means the same thing in every process
+ *   on the display.
+ * - **Windows** — a composition surface handle, already valid in the host
+ *   process. A window cannot be embedded here (a composition target stops
+ *   presenting once its window is a child), so the *buffer* crosses instead
+ *   and the host binds it to a visual of its own. The host is the parent
+ *   process unless `createRoot({ win32: { paneHostPid } })` says otherwise.
+ * - **Anything else** — `null`, which is the capability rather than a
+ *   failure.
+ *
+ * Pass it to the host out of band, as an XID is passed: argv, an environment
+ * variable, a message. What the host does with it differs per platform; what
+ * an app writes to get it does not.
+ */
+export function windowHandleOf(
+  target:
+    | NtkWindow
+    | DrawnNode
+    | RefObject<NtkWindow | DrawnNode | null>
+    | null
+    | undefined,
+): number | null;
+
+/**
+ * `windowHandleOf` bound to a ref. A **getter**, stable across renders, for
+ * {@link useWindowId}'s reason: the window is not realized on the render
+ * that declares it.
+ */
+export function useWindowHandle(
+  ref: RefObject<NtkWindow | DrawnNode | null>,
+): () => number | null;
+
 /**
  * Parse a `text/uri-list` payload (RFC 2483): CRLF-separated,
  * percent-encoded, `#` lines are comments. What `DropEvent.files` is made

package/src/index.js

@@ -4,7 +4,13 @@ import './bootstrap.js';
 
 export { createRoot, Renderer } from './Reconciler.js';
 export { createStyles, flattenStyle } from './styles.js';
-export { windowIdOf, useWindowId, useTopLevelWindow } from './windowid.js';
+export {
+  windowIdOf,
+  useWindowId,
+  windowHandleOf,
+  useWindowHandle,
+  useTopLevelWindow,
+} from './windowid.js';
 export { launchTimestamp, notifyStartupComplete } from './startup.js';
 export { activateWindow } from './activate.js';
 export { lastInputTime, serverTime } from './inputtime.js';
@@ -14,9 +20,30 @@ export {
   registerApplication,
 } from './application.js';
 export { useAppActivate, useAppOpen } from './apphooks.js';
-export { setBadge, setProgress, setQuicklist, setUrgent } from './launcher.js';
-export { useBadge, useDockMenu, useProgress } from './launcherhooks.js';
+export {
+  setBadge,
+  setLauncherMenu,
+  setProgress,
+  setQuicklist,
+  setUrgent,
+} from './launcher.js';
+export {
+  useBadge,
+  useDockMenu,
+  useLauncherMenu,
+  useProgress,
+} from './launcherhooks.js';
 export { useTray } from './trayhooks.js';
+// The Windows taskbar's own surfaces. Exported unconditionally and inert
+// where the backend has none — `useDesktopCapability('launcher').features`
+// carries `tasks`, `thumbnailToolbar` and `recentDocuments`, so an app
+// branches on what this desktop has rather than on the platform.
+export {
+  noteRecentDocument,
+  useJumpList,
+  useRecentDocument,
+  useThumbnailToolbar,
+} from './taskbarhooks.js';
 export {
   CAPABILITIES,
   NO_CAPABILITY,

package/src/launcher.js

@@ -6,7 +6,7 @@
 // desktops, two mechanisms, one call each:
 //
 //   1. **the app's own tile** — the cocoa backend's `NSDockTile`, reached
-//      through the app object (`setDockBadge`, `setDockMenu`, src/cocoa/
+//      through the app object (`setDockBadge`, `setLauncherMenu`, src/cocoa/
 //      app.js).
 //   2. **`com.canonical.Unity.LauncherEntry`** over the session bus — the
 //      protocol Unity defined and the KDE, elementary, Cairo-Dock and
@@ -34,13 +34,13 @@
 // is runtime, it follows state, and Dash-to-Dock/ubuntu-dock, Plank and the
 // Unity heritage launchers all render it.
 //
-// So `useDockMenu()` has a Linux rung after all, and the three menus an app
+// So `useLauncherMenu()` has a Linux rung after all, and the three menus an app
 // puts on the desktop — panel, tray, launcher — are now one authoring model
 // on both backends. `.desktop` actions are still the right place for entries
 // that must work *while the app is not running*; they are a different feature
 // wearing a similar hat.
 //
-// Nothing here imports react: `useBadge`/`useDockMenu` (launcherhooks.js) are
+// Nothing here imports react: `useBadge`/`useLauncherMenu` (launcherhooks.js) are
 // the hooks, and these are the functions under them, callable from host-side
 // code with no tree. The entry on the bus is held for as long as anything is
 // shown and released when the last of it is cleared — a held bus ref is a
@@ -300,7 +300,8 @@ export async function setUrgent(urgent, { app } = {}) {
 }
 
 /**
- * The menu behind a right-click on the app's launcher icon — the quicklist.
+ * The menu behind a right-click on the app's launcher icon — the Dock menu on
+ * macOS, the quicklist on Linux.
  *
  * Takes `MenuBar`'s item vocabulary and exports it as a `com.canonical.dbusmenu`
  * tree, exactly as the tray and the global menu do. `null` takes it down.
@@ -310,12 +311,12 @@ export async function setUrgent(urgent, { app } = {}) {
  * launcher that builds its client the instant it sees `quicklist` finds an
  * object there.
  */
-export async function setQuicklist(items, { app } = {}) {
+export async function setLauncherMenu(items, { app } = {}) {
   const target = app ?? soleApp();
 
-  // Rung 1: the app's own tile menu.
-  if (typeof target?.setDockMenu === 'function') {
-    target.setDockMenu(items ?? null);
+  // Rung 1: the app's own icon menu.
+  if (typeof target?.setLauncherMenu === 'function') {
+    target.setLauncherMenu(items ?? null);
     return true;
   }
 
@@ -367,6 +368,14 @@ export async function setQuicklist(items, { app } = {}) {
   return true;
 }
 
+/**
+ * @deprecated Renamed to {@link setLauncherMenu}. "Quicklist" is the Unity
+ * launcher's word for the menu macOS calls the Dock menu; this function
+ * always drove both, and the name only ever named one of them. Kept working
+ * and kept quiet.
+ */
+export const setQuicklist = setLauncherMenu;
+
 /** Test seam, not public: drop the exported entry without emitting. */
 export async function _resetLauncher() {
   await releaseEntry();

package/src/launcherhooks.js

@@ -1,4 +1,4 @@
-// `useBadge()`, `useProgress()` and `useDockMenu()` — the launcher's view of
+// `useBadge()`, `useProgress()` and `useLauncherMenu()` — the launcher's view of
 // the app, as things a component declares rather than manages.
 //
 // All three now have a rung on both backends except progress, which has one
@@ -7,7 +7,7 @@
 // feature an app should branch on, and a development warning for every
 // desktop that lacks one is a warning nobody can act on.
 //
-// The one that changed shape is `useDockMenu`. It used to be cocoa-only on
+// The one that changed shape is `useLauncherMenu`. It used to be cocoa-only on
 // the grounds that the freedesktop counterpart was an install step — see
 // `launcher.js`, where that reasoning is corrected: the launcher protocol
 // carries a `quicklist` dbusmenu, so the Dock menu is runtime code on both.
@@ -15,7 +15,7 @@
 import { useEffect, useRef } from 'react';
 
 import { useAppOrNull } from './appcontext.js';
-import { setBadge, setProgress, setQuicklist } from './launcher.js';
+import { setBadge, setLauncherMenu, setProgress } from './launcher.js';
 
 /**
  * Show `value` on the app's icon while this component is mounted, and clear
@@ -63,12 +63,12 @@ export function useProgress(value) {
 }
 
 /**
- * The menu behind a right-click on the app's icon in the Dock or launcher,
- * from the same `items` vocabulary `MenuBar` and `ContextMenu` take — an
- * item's `onSelect` fires when the user picks it.
+ * The menu behind a right-click on the app's **launcher icon** — the Dock on
+ * macOS, the launcher on Linux — from the same `items` vocabulary `MenuBar`
+ * and `ContextMenu` take. An item's `onSelect` fires when the user picks it.
  *
  * ```jsx
- * useDockMenu([
+ * useLauncherMenu([
  *   { label: 'New Window', onSelect: openWindow },
  *   { type: 'separator' },
  *   { label: 'Recent', items: recent.map(toItem) },
@@ -80,8 +80,14 @@ export function useProgress(value) {
  * backend; the launcher protocol's `quicklist` on Linux, which needs the
  * identity `registerApplication({ appId })` establishes and a `.desktop` file
  * of that name for a launcher to attach it to.
+ *
+ * It reads `useDesktopCapability('launcher').features.menu`, which is where
+ * the name comes from: every desktop has one icon standing for this
+ * application and calls it something different — Dock, taskbar, panel, dash —
+ * and `launcher` is the one word that is none of their words and all of their
+ * meanings (AGENTS.md, "Vocabulary").
  */
-export function useDockMenu(items) {
+export function useLauncherMenu(items) {
   const app = useAppOrNull();
   // read at activation time, so a pick three minutes from now runs the
   // handler from the current render rather than the mounting one
@@ -89,12 +95,20 @@ export function useDockMenu(items) {
   live.current = items;
 
   useEffect(() => {
-    setQuicklist(items ?? null, { app }).catch(() => {});
+    setLauncherMenu(items ?? null, { app }).catch(() => {});
   }, [items, app]);
 
   useEffect(() => {
     return () => {
-      setQuicklist(null, { app }).catch(() => {});
+      setLauncherMenu(null, { app }).catch(() => {});
     };
   }, [app]);
 }
+
+/**
+ * @deprecated Renamed to {@link useLauncherMenu}. "Dock" is one desktop's
+ * word for the icon every desktop has; this hook drove the Linux launcher's
+ * quicklist long before the name caught up. Kept working, and kept quiet —
+ * an alias that warned would punish an app for code that is still correct.
+ */
+export const useDockMenu = useLauncherMenu;

package/src/node.d.ts

@@ -40,7 +40,7 @@ export interface ImageDataLike {
 /**
  * The 2d context a node paints into — the canvas-shaped subset **both**
  * backends implement: ntk's `RenderingContext2D` over XRender on X11, and
- * `CocoaContext2D` over CoreGraphics on macOS. Declared as the contract an
+ * `BackendContext2D` over CoreGraphics on macOS. Declared as the contract an
  * element may rely on rather than as either class: what is here is on
  * both, and a member one backend has and the other does not is optional
  * here or absent. Coordinates are device pixels in the owning window's

package/src/nodes/cascade.js

@@ -422,6 +422,15 @@ export class NodeCascade {
   get placed() {
     const owner = this.isWindow ? this : this.root;
     if (!owner) return false;
+    // A window written under a root `<ThemeProvider>` is handed that palette
+    // when the scope inserts it, which is after it and its subtree were built
+    // and first resolved (nodes/scope.js `insertBefore`). Until then its
+    // ancestry is as incomplete as a popup's without its parent, and every
+    // token the provider defines would be reported as unknown — a warning for
+    // a style that then resolves correctly, and under
+    // `REACT_X11_STRICT_TOKENS=1` a throw that killed an app whose palette was
+    // fine.
+    if (owner._awaitsRootScope && owner._scope == null) return false;
     return owner.isPopup ? owner.parent != null : true;
   }
 

package/src/nodes/node.js

@@ -70,7 +70,12 @@ export class Node {
     return DEVTOOLS_FAKE_DOCUMENT;
   }
 
-  constructor(kind, props, app, { yoga = true } = {}) {
+  constructor(kind, props, app, { yoga = true, awaitsRootScope = false } = {}) {
+    // Set before anything resolves a style: a `<window>`'s own style is
+    // resolved by this constructor, and whether its ancestry is complete
+    // decides whether an unresolved `$token` is reported (cascade.js
+    // `placed`). A window under a root `<ThemeProvider>` has no palette yet.
+    this._awaitsRootScope = awaitsRootScope;
     this.kind = kind;
     this.props = props;
     this.app = app;

package/src/nodes/window/hints.js

@@ -232,6 +232,23 @@ export function windowAttributes(props, scale = 1) {
         : props[key];
   }
   if (Object.keys(hints).length > 0) attributes.sizeHints = hints;
+  // The desktop identity of this window, under the one name every desktop's
+  // own word maps onto: `WM_CLASS` on X11, `app_id` on Wayland,
+  // AppUserModelID on Windows. `wmClass` was X11's word for it and is still
+  // accepted, so both are normalised here and a backend reads one key.
+  //
+  // X11 carries a *pair* — an instance naming this window and a class naming
+  // the application — and everything since carries one string. The class is
+  // the application's, so the class is what a single-id backend is given; the
+  // pair itself still reaches `setClass` from the props (`applyWindowHints`).
+  const identity = attributes.appId ?? attributes.wmClass;
+  if (identity !== undefined) {
+    attributes.appId = Array.isArray(identity)
+      ? (identity[1] ?? identity[0])
+      : identity && typeof identity === 'object'
+        ? (identity.class ?? identity.instance)
+        : identity;
+  }
   if (props.style !== undefined) {
     const style = flattenStyle(props.style);
     if (style.backgroundColor !== undefined) {
@@ -325,8 +342,10 @@ export class WindowHints {
         this._sendSizeHints(next);
       }
     }
-    if (!shallowEqual(next.wmClass, prev.wmClass) && next.wmClass) {
-      const c = next.wmClass;
+    const identity = next.appId ?? next.wmClass;
+    const wasIdentity = prev.appId ?? prev.wmClass;
+    if (!shallowEqual(identity, wasIdentity) && identity) {
+      const c = identity;
       if (Array.isArray(c)) wnd.setClass?.(c[0], c[1]);
       else if (typeof c === 'object') wnd.setClass?.(c.instance, c.class);
       else wnd.setClass?.(c);

package/src/nodes/window/window.js

@@ -138,8 +138,8 @@ export function flushWindowRestacks() {
  * issue #4).
  */
 export class WindowNode extends Scrollable(Node) {
-  constructor(app, attributes, props) {
-    super('window', props, app, { yoga: true });
+  constructor(app, attributes, props, { awaitsRootScope = false } = {}) {
+    super('window', props, app, { yoga: true, awaitsRootScope });
     assertWindowSize(props, this.kind);
     this.root = this;
     this.attributes = attributes;