react-x11 2.16.1 → 2.17.1

package/src/cocoa/app.js

@@ -38,10 +38,10 @@ import { CocoaPaneWindow } from './panewindow.js';
 import { CocoaColorSampler } from './screencolor.js';
 import { CocoaFilePanels } from './filepanels.js';
 import { CocoaFontManager } from './fonts.js';
-import { releaseImageUpload } from './context2d.js';
+import { releaseImageUpload } from '../backend/context2d.js';
 import { CocoaSurface } from './surface.js';
 import { CocoaSymbols } from './symbols.js';
-import { CocoaWindow } from './window.js';
+import { CocoaWindow, FRAME_SLACK_MS } from './window.js';
 import { decodeKey, modifierMask } from './keymap.js';
 import { loadNative } from './native.js';
 import { requestAppKit, threadedChannel } from './threaded.js';
@@ -55,9 +55,6 @@ import { requestAppKit, threadedChannel } from './threaded.js';
 // bridge that does not report it: a 60Hz floor every Mac clears.
 const RAF_INTERVAL_MS = 16;
 const PUMP_INTERVAL_MS = 8;
-// How early a pump tick may take a frame that is not quite due, in ms — the
-// drift of a timer, not a fraction of the pump (`_frameDue`).
-const FRAME_SLACK_MS = 1;
 // Threaded mode's live-resize handshake (windowkit/appkit#53): how long
 // AppKit may hold a resize tick for a frame painted at the new size, in ms.
 // The edge moves when the delegate returns, so the budget is how long a
@@ -204,7 +201,7 @@ export class CocoaApp {
       native.setAppName(String(appName));
     }
 
-    // The Dock menu (src/cocoa/dock.js), installed by `useDockMenu`.
+    // The Dock menu (src/cocoa/dock.js), installed by `useLauncherMenu`.
     this._dockMenu = new CocoaDockMenu(this);
     // The tray items (src/cocoa/statusitem.js), by the bridge's handle —
     // which is what a click event names them by.
@@ -703,8 +700,12 @@ export class CocoaApp {
     this._native.setDockBadge(label == null ? null : String(label));
   }
 
-  /** The menu behind a right-click on the Dock icon — `useDockMenu()`. */
-  setDockMenu(items) {
+  /**
+   * The menu behind a right-click on the launcher icon — `useLauncherMenu()`.
+   * Here the launcher is the Dock, which is why the AppKit call below keeps
+   * its own name: `_native.setDockMenu` *is* what Apple calls it.
+   */
+  setLauncherMenu(items) {
     this._dockMenu.update(items);
   }
 
@@ -902,6 +903,13 @@ export class CocoaApp {
    * tick alone still does is pump AppKit's events, which is what
    * `pumpInterval` stays the cadence of. With no pump at all — threaded
    * mode, where `_pumpInterval` is Infinity — every frame is one of these.
+   *
+   * The wait is rounded **up** to whole milliseconds, because `setTimeout`
+   * only counts those: a 120Hz panel's 8.333ms gate rounded to 8 fired
+   * before the clock would take the frame, which cost a second timer per
+   * frame to cover the last third of a millisecond. Rounding up costs the
+   * grid nothing — `_frameDue` anchors the next slot to the last one, not
+   * to when the frame ran — and lands on the first tick the clock accepts.
    */
   _armFrameTimer(wait, now) {
     if (!(wait > 0 && wait < this._pumpInterval)) return;
@@ -918,7 +926,7 @@ export class CocoaApp {
         this._tickFrames();
         this._presentAll();
       },
-      Math.max(1, Math.round(wait)),
+      Math.max(1, Math.ceil(wait)),
     );
   }
 

package/src/cocoa/fonts.js

@@ -846,7 +846,7 @@ export class CocoaFontManager {
   }
 
   /**
-   * The CTFont a glyph run draws with (`CocoaContext2D.drawGlyphs`): a face
+   * The CTFont a glyph run draws with (`BackendContext2D.drawGlyphs`): a face
    * of this engine's at the run's size, or an ntk `Font` — `openFont()`'s —
    * resolved to CoreText from the same bytes, so the glyph ids it shaped
    * with hold. Null for anything else, and the run is skipped.

package/src/cocoa/glarea.js

@@ -231,6 +231,16 @@ export class CocoaGLArea {
     return this.parent.requestAnimationFrame(cb);
   }
 
+  /**
+   * The owning window's clock, asked where a gate of `interval` ms lands
+   * on its grid (`CocoaWindow.nextFrameAt`) — the swap gate phase-locks to
+   * it so the two do not stack. A parent with no clock (a bare stub in a
+   * test) answers one interval from now, the old swap-relative wait.
+   */
+  nextFrameAt(interval) {
+    return this.parent.nextFrameAt?.(interval) ?? performance.now() + interval;
+  }
+
   getContext(kind, config) {
     if (kind !== 'opengl' || this.destroyed) return null;
     if (!this._context) {
@@ -262,7 +272,10 @@ function createGLAreaContext(runtime, area, config) {
   let back = null;
   let width = 0;
   let height = 0;
-  let gateClosed = false;
+  // The moment the swap gate reopens, on the window clock's grid — not a
+  // boolean a timer flips, so a frame that arrives a fraction of a
+  // millisecond before its own timer still reads the true state.
+  let gateOpenAt = -Infinity;
   let gateTimer = null;
   let destroyed = false;
 
@@ -289,7 +302,17 @@ function createGLAreaContext(runtime, area, config) {
   // one, so the honest gate is one display period per swap — the same
   // timer-reopened gate the XQuartz CGL flavor uses (no backpressure
   // exists on either).
-  ctx.canRender = () => !destroyed && !gateClosed;
+  //
+  // One period *per frame*, though, not per swap: timed from the swap the
+  // gate reopened at `slot + drawCost + period`, which overshoots the
+  // window clock's next slot however cheap the frame, and the clock then
+  // rounded it up to the slot after — two display periods, a 120Hz panel
+  // pinned at 60fps whatever the scene cost (issue #631). Anchored to the
+  // slot the frame was due at (`CocoaWindow.nextFrameAt`) the two gates
+  // are on one grid: the clock cannot take a frame the gate would refuse,
+  // because both are the same instant, and the gate still never lets two
+  // frames into one period.
+  ctx.canRender = (now = performance.now()) => !destroyed && now >= gateOpenAt;
 
   ctx.makeCurrent = () => {
     if (destroyed) return;
@@ -305,6 +328,26 @@ function createGLAreaContext(runtime, area, config) {
     runtime.gl.bindFramebuffer(target, fb == null ? (back?.fbo ?? 0) : fb);
   };
 
+  // A frame refused by the gate has nothing else to wake it, so the gate
+  // says when it opens. `setTimeout` counts whole milliseconds and a
+  // display period is rarely one (8.333 at 120Hz), so a timer that lands
+  // early re-arms rather than announcing a gate that is still shut.
+  const armGate = () => {
+    if (gateTimer || destroyed) return;
+    const wait = gateOpenAt - performance.now();
+    gateTimer = setTimeout(
+      () => {
+        gateTimer = null;
+        if (destroyed) return;
+        if (performance.now() < gateOpenAt) armGate();
+        else ctx.onFrameAvailable?.();
+      },
+      Math.max(1, Math.ceil(wait)),
+    );
+    // the timer must not hold the process open for an idle scene
+    gateTimer.unref?.();
+  };
+
   ctx.SwapBuffers = () => {
     if (destroyed || !back) return;
     runtime.gl.flush();
@@ -312,14 +355,9 @@ function createGLAreaContext(runtime, area, config) {
     const shown = back;
     back = front;
     front = shown;
-    gateClosed = true;
-    gateTimer = setTimeout(() => {
-      gateTimer = null;
-      gateClosed = false;
-      ctx.onFrameAvailable?.();
-    }, runtime.frameInterval);
-    // the timer must not hold the process open for an idle scene
-    gateTimer.unref?.();
+    // one display period from the frame's slot, not from this moment
+    gateOpenAt = area.nextFrameAt(runtime.frameInterval);
+    armGate();
   };
 
   ctx._resized = () => {

package/src/cocoa/overlay.js

@@ -14,7 +14,7 @@
 // `map`, `unmap`, `getContext`, `destroy` — plus `present`, which puts what
 // was painted on the layer: ntk blits an X window's backing store on its
 // own, where a layer's contents are a copy the bitmap has to be pushed to.
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 
 export const OVERLAY_Z = 1e7 + 1;
 
@@ -115,7 +115,7 @@ export class CocoaOverlayPane {
 
   getContext() {
     if (!this._ctx) {
-      this._ctx = new CocoaContext2D(
+      this._ctx = new BackendContext2D(
         this._native,
         () => this._ensureSurface(),
         () => {

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,12 +6,17 @@
 // 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';
 
 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
+// here because the window is the clock — `_rafLast` and `_frameInterval`
+// are its fields — and the app imports it from this side.
+export const FRAME_SLACK_MS = 1;
 // How long a worker's flip may hold its window's next frame (`_armFence`).
 // The release is reported once the replacing frame has committed, a
 // fraction of a millisecond later, and a window must not freeze on a report
@@ -794,7 +799,7 @@ export class CocoaWindow {
 
   getContext() {
     if (!this._ctx) {
-      this._ctx = new CocoaContext2D(
+      this._ctx = new BackendContext2D(
         this._native,
         () => this._ensureSurface(),
         () => {
@@ -910,6 +915,22 @@ export class CocoaWindow {
     return this.app._requestFrame(cb, this);
   }
 
+  /**
+   * The earliest moment this window's clock will hand out another frame,
+   * for a gate of `interval` ms — the display's period by default, which
+   * is the clock's own.
+   *
+   * It is the grid `_frameDue` decides on, not the wall clock: the anchor
+   * is the slot the running frame was *due* at, so the answer does not
+   * move with how long that frame took or how late its timer fired. A
+   * second gate that wants to compose with this clock rather than be
+   * rounded up by it has to land on this grid — which is what a
+   * `<glarea>`'s swap gate reads it for (src/cocoa/glarea.js).
+   */
+  nextFrameAt(interval = this._frameInterval) {
+    return this._rafLast + interval - FRAME_SLACK_MS;
+  }
+
   /**
    * Push the backing surface at the WindowServer, if anything drew — and
    * tell the window node what it cost. The flip itself is cheap, and the

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)',
         ),
       );
     }
@@ -365,18 +376,21 @@ export class GlAreaNode extends Node {
       typeof this.window.requestAnimationFrame === 'function'
         ? (cb) => this.window.requestAnimationFrame(cb)
         : (cb) => setImmediate(cb);
-    schedule(() => {
+    // the frame clock's own timestamp, not a fresh reading: a gate that
+    // composes with that clock is answered from the same moment it is
+    // (`canRender` on the Cocoa surface, issue #631)
+    schedule((now) => {
       this._frameScheduled = false;
-      this._drawFrame();
+      this._drawFrame(now);
     });
   }
 
-  _drawFrame() {
+  _drawFrame(now) {
     const pacer = this._pacer;
     pacer.began();
     let drawn = false;
     try {
-      drawn = this._drawFrameNow();
+      drawn = this._drawFrameNow(now);
     } finally {
       pacer.ended(undefined, drawn);
     }
@@ -386,14 +400,14 @@ export class GlAreaNode extends Node {
   }
 
   /** The frame itself; true when it drew. */
-  _drawFrameNow() {
+  _drawFrameNow(now) {
     const gl = this.gl;
     if (!gl || this.destroyed) return false;
     const direct = gl.backend === 'direct';
     // On the direct backend every buffer may still be held by the display,
     // and drawing into one before it comes back would paint what is on
     // screen. `onFrameAvailable` asks for this frame again when one frees.
-    if (direct && gl.canRender && !gl.canRender()) {
+    if (direct && gl.canRender && !gl.canRender(now)) {
       this._frameRefused = true;
       return false;
     }

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