react-x11 2.15.1 → 2.15.3

package/src/trayhooks.js

@@ -1,25 +1,72 @@
 // `useTray()` — an icon in the system tray for as long as a component is
 // mounted, on the backends that have one.
 //
-// Today that is the cocoa backend's menu-bar extra (`NSStatusItem`,
-// src/cocoa/statusitem.js). The freedesktop counterpart, StatusNotifierItem
-// over D-Bus, is react-x11#353's open question; until it lands the hook is
-// inert on X11 and says so — `available: false`, and a one-time development
-// note — rather than pretending, so an app can keep the feature behind the
-// answer. The inert-props policy of docs/macos.md, for a hook.
+// Two rungs, found by capability and never by naming a platform:
+//
+//   1. **the app's own status bar** — the cocoa backend's menu-bar extra
+//      (`NSStatusItem`, src/cocoa/statusitem.js), found by the app carrying
+//      `createStatusItem`.
+//   2. **`org.kde.StatusNotifierItem`** over the session bus
+//      (`statusnotifier.js`) — the freedesktop tray, and the same protocol
+//      under X11, XWayland and Wayland. Used when a **live**
+//      `org.kde.StatusNotifierWatcher` is hosting one.
+//
+// Where neither answers there is no tray, and `available` is `false` — a
+// stock GNOME session with no AppIndicator extension is the common case, and
+// it is a configuration rather than a fault. An app reads `available` and
+// keeps its tray feature behind it; nothing is logged, because "this desktop
+// has no tray" is not news.
+//
+// ## What the hook returns, and why it is not just a boolean
+//
+// `{ available, backend, features, error }` — the same shape
+// `useDesktopCapability('tray')` resolves to, and built from the same probe so the
+// two can never disagree. The difference is which question they answer:
+//
+//   - **this hook measures.** `available` is whether *this item* was taken by
+//     a host. It tried; it knows.
+//   - **`useDesktopCapability` predicts.** It answers "would a tray icon be taken if
+//     one were asked for", which is what a settings screen needs — a "Show
+//     tray icon" checkbox must render correctly *without* putting an icon in
+//     the tray to find out.
+//
+// Prefer this one wherever the feature is actually mounted. `features` is the
+// portable vocabulary from `capabilities.js` — `features.clickModifiers` is
+// false on the freedesktop rung, because the protocol carries no modifier
+// state, and an app that dims a shift-click affordance reads it here rather
+// than testing the platform.
+//
+// `error` is the fourth field because "no tray on this desktop" and "there is
+// a tray and it refused me" are different facts with different fixes, and
+// collapsing them into `available: false` loses the one an app could act on.
+//
+// ## `available` settles, it does not start true
+//
+// The cocoa rung can be answered synchronously — the method is either on the
+// app object or it is not. The freedesktop one cannot: it takes a bus
+// connection and a `NameHasOwner` round trip. So `available` is **render
+// state that settles**, false on the first frame and true a tick later if a
+// watcher is there, and it follows the watcher for the life of the item —
+// a panel that exits takes the icon with it and flips this back to false.
+//
+// That is the shape every capability in this family should have, and
+// docs/desktop.md says so: a synchronous "can I?" that is honest on the first
+// frame is not available for anything that has to ask the desktop.
 
 import { useEffect, useRef, useState } from 'react';
+import { decodeImage } from 'ntk';
 
 import { useAppOrNull } from './appcontext.js';
-
-let warnedInert = false;
+import { currentRegistration } from './application.js';
+import { NO_CAPABILITY, desktopCapability } from './capabilities.js';
+import { StatusNotifierItem, allocateItemSlot } from './statusnotifier.js';
 
 /**
  * An icon in the system tray while this component is mounted.
  *
  * ```jsx
  * const { available } = useTray({
- *   icon: 'bell.badge',              // an SF Symbol name, or PNG bytes
+ *   icon: 'bell.badge',              // a themed icon name (an SF Symbol on macOS), or PNG bytes
  *   tooltip: 'Notifications',
  *   menu: [{ label: 'Open', onSelect: open }, { label: 'Quit', onSelect: quit }],
  * });
@@ -27,37 +74,52 @@ let warnedInert = false;
  *
  * With `menu`, a click opens it — the same `items` vocabulary `MenuBar` and
  * `useDockMenu` take, an item's `onSelect` firing when picked. Without one,
- * `onClick` is called with the button and the item's screen rect, which is
- * where to anchor a popup of your own. `null` means no item. Every field
- * follows its value while mounted; the item is removed on unmount.
+ * `onClick` is called with the button and, where the backend knows it, the
+ * item's screen rect. `null` means no item. Every field follows its value
+ * while mounted; the item is removed on unmount.
  *
- * `available` is whether this backend has a tray at all: false on X11
- * today (#353), and the honest answer to branch on.
+ * `available` is whether this backend has a tray at all, and it **settles**:
+ * false on the first frame, true once a tray has been found. Branch on it for
+ * a "show tray icon" setting; do not branch on it to decide whether to call
+ * the hook, which would break the rules of hooks the moment it changed.
  */
 export function useTray(options) {
   const app = useAppOrNull();
-  const available = typeof app?.createStatusItem === 'function';
+  const native = typeof app?.createStatusItem === 'function';
   const itemRef = useRef(null);
   const [rect] = useState(null);
+  const [remote, setRemote] = useState(false);
+  const [error, setError] = useState(null);
+  // The feature vocabulary for whichever rung answered. Probed once per
+  // backend rather than per render — it describes the mechanism, not the
+  // item — and for *both* rungs: the cocoa one is synchronous about whether
+  // it has a tray, but not about what that tray can do, and an app reading
+  // `features.clickModifiers` to dim a shift-click affordance would
+  // otherwise be told `undefined` on the one backend that has modifiers.
+  const [caps, setCaps] = useState(NO_CAPABILITY);
+
+  useEffect(() => {
+    if (!options) return undefined;
+    let cancelled = false;
+    // `app` explicitly rather than letting the probe find the sole one: a
+    // process with several connections has several trays, and this hook
+    // belongs to one of them.
+    void desktopCapability('tray', { app }).then((c) => {
+      if (!cancelled) setCaps(c);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, native, options == null]);
 
   // the options a click or a pick reads are the current render's, not the
   // ones the item was created with three minutes ago
   const live = useRef(options);
   live.current = options;
 
+  // ------------------------------------------------------- rung 1: the app's
   useEffect(() => {
-    if (!available) {
-      if (process.env.NODE_ENV !== 'production' && !warnedInert && app) {
-        warnedInert = true;
-        console.warn(
-          'react-x11: useTray() is inert on this backend — the freedesktop ' +
-            'tray (StatusNotifierItem) is not implemented yet (#353). Read ' +
-            '`available` to keep the feature behind the answer.',
-        );
-      }
-      return undefined;
-    }
-    if (!options) return undefined;
+    if (!native || !options) return undefined;
     const item = app.createStatusItem({
       ...options,
       onClick: (ev) => live.current?.onClick?.(ev),
@@ -70,7 +132,7 @@ export function useTray(options) {
     // Recreated only when the item comes or goes: the fields patch in
     // place below, and an `options` object rebuilt every render must not
     // rebuild the item every render.
-  }, [app, available, options == null]);
+  }, [app, native, options == null]);
 
   useEffect(() => {
     const item = itemRef.current;
@@ -86,5 +148,91 @@ export function useTray(options) {
     options?.menu,
   ]);
 
-  return { available, rect };
+  // ------------------------------------------- rung 2: the freedesktop tray
+  const sniRef = useRef(null);
+  const previous = useRef(options ?? {});
+  // One slot for the life of this hook, **not** per item object. Passing
+  // `null` and then options again is the same tray icon going away and coming
+  // back; on a fresh path the host has no way to know that and draws a second
+  // one beside the first. See `StatusNotifierItem.announcePassive`.
+  const slotRef = useRef(null);
+  slotRef.current ??= allocateItemSlot();
+
+  useEffect(() => {
+    if (native || !options) return undefined;
+    let cancelled = false;
+    // The id hosts key their hidden-icons setting on. The app's registered id
+    // when it has one, so the choice survives a restart.
+    const appId = currentRegistration()?.appId ?? 'react-x11';
+    const item = new StatusNotifierItem({
+      getOptions: () => live.current,
+      appId,
+      slot: slotRef.current,
+      decodeIcon: decodeIconBytes,
+      // A host that answered the bus and then refused the registration is a
+      // fact worth reporting; a desktop with no tray at all is not, and does
+      // not come through here.
+      onError: (err) => {
+        if (!cancelled)
+          setError(err instanceof Error ? err : new Error(String(err)));
+      },
+    });
+    sniRef.current = item;
+    previous.current = { ...live.current };
+    void item.start().then((ok) => {
+      if (!cancelled) setRemote(ok);
+    });
+    return () => {
+      cancelled = true;
+      sniRef.current = null;
+      setRemote(false);
+      setError(null);
+      void item.stop();
+    };
+  }, [native, options == null]);
+
+  // The item reads its fields through `getOptions`, so a render only has to
+  // say *which* of them moved — see `StatusNotifierItem.update`.
+  useEffect(() => {
+    const item = sniRef.current;
+    if (!item) return;
+    item.update(previous.current);
+    previous.current = { ...live.current };
+  }, [
+    options?.icon,
+    options?.overlayIcon,
+    options?.attentionIcon,
+    options?.title,
+    options?.tooltip,
+    options?.visible,
+    options?.attention,
+    options?.menu,
+  ]);
+
+  // The cocoa rung is synchronous and always itself; the freedesktop one
+  // reports whatever the probe found. `features` is empty until one settles,
+  // which is the same "render the fallback first" order `available` has.
+  const backend = native ? 'cocoa' : remote ? caps.backend : null;
+  return {
+    available: native || remote,
+    backend,
+    features: native || remote ? caps.features : NO_CAPABILITY.features,
+    error,
+    rect,
+  };
+}
+
+/**
+ * PNG/JPEG bytes → raw RGBA, through ntk's decoder.
+ *
+ * Defensive: a corrupt or unsupported image should cost the tray its *icon*,
+ * not its tray. The pixmap ends up empty and the item still registers with
+ * its name, tooltip and menu intact.
+ */
+function decodeIconBytes(bytes) {
+  try {
+    return decodeImage(bytes);
+  } catch {
+    return null;
+  }
 }

package/src/types/capabilities.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Feature discovery for the things an app does outside its own windows.
+ * See docs/desktop.md "Feature discovery".
+ */
+
+/** Which mechanism answered. Named after the mechanism, never the platform. */
+export type DesktopBackend =
+  | 'dbus'
+  | 'cocoa'
+  | 'osascript'
+  | 'notify-send'
+  | 'statusnotifier'
+  | 'launcherentry';
+
+/** The capabilities {@link desktopCapability} can be asked about. */
+export type DesktopCapabilityName = 'notifications' | 'tray' | 'launcher';
+
+/**
+ * What a notification can carry here.
+ *
+ * `actions`/`events` are the pair that decide whether a notification is a
+ * conversation or a sign: false on the shell-out rungs and on a freedesktop
+ * daemon that does not advertise `actions`, where buttons silently never
+ * appear and nothing is ever reported back.
+ */
+export interface NotificationFeatures {
+  actions: boolean;
+  /** `onAction`/`onClose` will fire. Tracks `actions` on every rung. */
+  events: boolean;
+  /** `update()` replaces the banner in place rather than posting a new one. */
+  update: boolean;
+  close: boolean;
+  body: boolean;
+  bodyMarkup: boolean;
+  bodyImage: boolean;
+  icon: boolean;
+  sound: boolean;
+  /** The banner survives in a tray or centre rather than expiring unseen. */
+  persistence: boolean;
+  urgency: boolean;
+}
+
+export interface TrayFeatures {
+  menu: boolean;
+  /** An icon named in the desktop's theme (an SF Symbol on the cocoa rung). */
+  iconName: boolean;
+  iconBytes: boolean;
+  attention: boolean;
+  overlay: boolean;
+  tooltip: boolean;
+  title: boolean;
+  click: boolean;
+  clickPosition: boolean;
+  /** The item's screen rect. False on the freedesktop rung, which has none. */
+  clickRect: boolean;
+  /** Modifier state on a click. False on the freedesktop rung. */
+  clickModifiers: boolean;
+  scroll: boolean;
+}
+
+export interface LauncherFeatures {
+  badge: boolean;
+  /** A string badge. macOS only — the launcher protocol carries a count. */
+  badgeText: boolean;
+  progress: boolean;
+  urgent: boolean;
+  /** The Dock menu / quicklist. */
+  menu: boolean;
+  /** The launcher needs an installed `.desktop` file to attach this to. */
+  needsDesktopFile: boolean;
+}
+
+export interface DesktopCapabilityResult<F = Record<string, boolean>> {
+  /** Whether there is any mechanism at all. Branch on `features` for detail. */
+  available: boolean;
+  backend: DesktopBackend | null;
+  /** Empty when `available` is false. */
+  features: Partial<F>;
+  /**
+   * Why not, when the `false` has a cause worth naming.
+   *
+   * `'no-app-id'` — the launcher needs `registerApplication({ appId })`, and
+   * this one is a mistake in the source.
+   * `'not-primary'` — it was called, and another copy of the app owns the
+   * identity. Correct single-instance behaviour, not a bug: the first copy
+   * owns the badge and the quicklist.
+   */
+  reason?: 'no-app-id' | 'not-primary';
+}
+
+export type DesktopCapabilityFor<N extends DesktopCapabilityName> =
+  N extends 'notifications'
+    ? DesktopCapabilityResult<NotificationFeatures>
+    : N extends 'tray'
+      ? DesktopCapabilityResult<TrayFeatures>
+      : DesktopCapabilityResult<LauncherFeatures>;
+
+export declare const CAPABILITIES: readonly DesktopCapabilityName[];
+
+/** The "nothing here" answer: available false, no backend, no features. */
+export declare const NO_CAPABILITY: DesktopCapabilityResult;
+
+/**
+ * What this desktop can do for one feature.
+ *
+ * Never cached — a panel restarting or an extension being enabled changes the
+ * answer, and a cached `false` would outlive the fix. Throws only for an
+ * unknown name, which is a mistake in the source.
+ */
+export declare function desktopCapability<N extends DesktopCapabilityName>(
+  name: N,
+  options?: { app?: unknown },
+): Promise<DesktopCapabilityFor<N>>;
+
+/**
+ * {@link desktopCapability} as render state: {@link NO_CAPABILITY} on the
+ * first frame, settling a tick later, and re-probed whenever a name appears
+ * or vanishes on the session bus.
+ *
+ * Use it for the *pre-flight* question — a settings screen that must render a
+ * "Show tray icon" checkbox without putting an icon in the tray. Where the
+ * feature is actually mounted, the feature hook's own status is a measurement
+ * rather than a prediction and should be preferred.
+ */
+export declare function useDesktopCapability<N extends DesktopCapabilityName>(
+  name: N,
+): DesktopCapabilityFor<N>;

package/src/types/launcher.d.ts

@@ -35,9 +35,55 @@ export declare function setBadge(
 export declare function useBadge(value: BadgeValue): void;
 
 /**
- * The menu behind a right-click on the Dock icon, from the same item
- * vocabulary `MenuBar` takes; an item's `onSelect` fires when picked.
- * Installed while mounted, replaced when `items` changes, taken down on
- * unmount. Inert off the cocoa backend.
+ * The menu behind a right-click on the app's icon in the Dock or launcher,
+ * from the same item vocabulary `MenuBar` takes; an item's `onSelect` fires
+ * when picked. Installed while mounted, replaced when `items` changes, taken
+ * down on unmount.
+ *
+ * `NSDockTile`'s menu on the cocoa backend; the launcher protocol's
+ * **quicklist** on Linux — a `com.canonical.dbusmenu` tree, the same menu
+ * protocol the tray and the global menu speak. Needs the identity
+ * `registerApplication({ appId })` establishes and a `.desktop` file of that
+ * name, like the badge.
  */
 export declare function useDockMenu(items: MenuItem[] | null): void;
+
+/**
+ * A progress bar across the app's icon, `0`…`1`. `null` clears it; values
+ * outside the range are clamped rather than refused.
+ *
+ * The launcher protocol's `progress`. **Linux launchers only** — `NSDockTile`
+ * has no progress bar, so this is inert on the cocoa backend and
+ * `useDesktopCapability('launcher').features.progress` is the honest answer.
+ */
+export declare function setProgress(
+  value: number | null | false | undefined,
+  options?: SetBadgeOptions,
+): Promise<boolean>;
+
+/** {@link setProgress} while mounted; cleared on unmount. */
+export declare function useProgress(
+  value: number | null | false | undefined,
+): void;
+
+/**
+ * Ask the launcher for the user's attention, or stop asking.
+ *
+ * Distinct from `<window states={['demands_attention']}>`, which is the
+ * *window's* urgency hint: this marks the app's icon in the launcher whether
+ * or not any window is open. Inert on the cocoa backend, where the window
+ * state is the mechanism.
+ */
+export declare function setUrgent(
+  urgent: boolean,
+  options?: SetBadgeOptions,
+): Promise<boolean>;
+
+/**
+ * {@link useDockMenu}'s imperative twin, for code with no component. `null`
+ * takes the menu down.
+ */
+export declare function setQuicklist(
+  items: MenuItem[] | null,
+  options?: SetBadgeOptions,
+): Promise<boolean>;

package/src/types/tray.d.ts

@@ -3,16 +3,22 @@
  */
 
 import type { MenuItem } from './components.js';
+import type { DesktopBackend, TrayFeatures } from './capabilities.js';
 
 export interface TrayClickEvent {
   button: 'left' | 'right' | 'middle';
-  /** The item's screen rect, global top-left coordinates in points — the
-   * anchor for a popup of your own. */
+  /** Where the click was, in global top-left screen coordinates — the anchor
+   * for a popup of your own. */
   x: number;
   y: number;
+  /** The item's rect. `0` on the freedesktop rung, whose protocol has none —
+   * read `features.clickRect` rather than testing for zero. */
   width: number;
   height: number;
+  /** `1` on the freedesktop rung, which does not count clicks. */
   clickCount: number;
+  /** All `false` on the freedesktop rung, which carries no modifier state.
+   * `features.clickModifiers` is the honest answer. */
   shift: boolean;
   control: boolean;
   option: boolean;
@@ -20,9 +26,27 @@ export interface TrayClickEvent {
 }
 
 export interface TrayOptions {
-  /** An SF Symbol name (`'bell.badge'`), or the bytes of a PNG. Drawn as a
-   * template image so it follows the bar's light and dark. */
+  /** A themed icon name — an SF Symbol on the cocoa rung (`'bell.badge'`),
+   * an icon-theme name on a freedesktop one (`'mail-unread'`) — or the bytes
+   * of a PNG. On the cocoa rung bytes are drawn as a template image so they
+   * follow the bar's light and dark. */
   icon?: string | Uint8Array | null;
+  /** Shown instead of `icon` while `attention` is set. Freedesktop only. */
+  attentionIcon?: string | Uint8Array | null;
+  /** A small badge drawn over the icon. Freedesktop only. */
+  overlayIcon?: string | Uint8Array | null;
+  /** Ask the panel to mark the item — `Status = NeedsAttention`.
+   * Freedesktop only; `features.attention` says so. */
+  attention?: boolean;
+  /** The spec's item category: `'ApplicationStatus'` (default),
+   * `'Communications'`, `'SystemServices'` or `'Hardware'`. Freedesktop
+   * only, and mostly affects where a panel sorts the icon. */
+  category?: string;
+  /** A directory to look `icon` up in, for icons shipped beside the app
+   * rather than installed in a theme. Freedesktop only. */
+  iconThemePath?: string;
+  /** A scroll over the icon. Freedesktop only. */
+  onScroll?: (event: { delta: number; orientation: string }) => void;
   /** Text beside the icon, or alone. */
   title?: string | null;
   tooltip?: string | null;
@@ -40,8 +64,25 @@ export interface TrayOptions {
 }
 
 export interface TrayState {
-  /** Whether this backend has a tray at all — false on X11 today (#353). */
+  /**
+   * Whether **this item** was taken by a tray.
+   *
+   * A measurement, not a prediction: the hook tried. It **settles** — false
+   * on the first frame, true a tick later if a host is there — so render the
+   * fallback first and upgrade. It follows the host, so a panel that exits
+   * flips it back.
+   */
   available: boolean;
+  /** Which mechanism took it, or null. */
+  backend: DesktopBackend | null;
+  /** What that mechanism can do. Empty until `available` settles. */
+  features: Partial<TrayFeatures>;
+  /**
+   * A tray that answered and then **refused**, which is a different fact from
+   * a desktop with no tray — and the only one of the two with a fix. Null
+   * when there is simply no tray.
+   */
+  error: Error | null;
   /** Reserved. */
   rect: null;
 }
@@ -49,6 +90,11 @@ export interface TrayState {
 /**
  * An icon in the system tray while this component is mounted; every field
  * follows its value, and the item is removed on unmount. `null` means no
- * item. Inert off the cocoa backend, with `available: false`.
+ * item.
+ *
+ * `NSStatusItem` on the cocoa backend; `org.kde.StatusNotifierItem` over
+ * D-Bus on a freedesktop session, which needs something hosting a tray —
+ * Plasma and most panels do, GNOME needs an AppIndicator extension. Where
+ * neither answers, `available` stays false and nothing is logged.
  */
 export declare function useTray(options: TrayOptions | null): TrayState;

package/src/wayland/context2d.js

@@ -532,7 +532,7 @@ export class WaylandContext2D {
    */
   begin(width, height, timestamp = 0) {
     this.init();
-    this._device.owner = this;
+    this._take();
     const t = this._target;
     if (t) {
       t.bind();
@@ -612,7 +612,7 @@ export class WaylandContext2D {
     // Mid stencil-then-cover the state is set up for the pass, not for a
     // plain batch, and the device cannot have changed hands under it.
     if (this._device.owner === this || this._stencilling) return;
-    this._device.owner = this;
+    this._take();
     this._makeCurrent?.();
     this.init();
     // As `begin()` has it: a target's size *is* the projection.
@@ -624,6 +624,26 @@ export class WaylandContext2D {
     this._applyState();
   }
 
+  /**
+   * Take the device, drawing whatever the last owner still had buffered.
+   *
+   * A context batches: its quads sit in a vertex buffer until the mode
+   * changes, the buffer fills, or someone flushes. So the handover is where
+   * the outgoing owner's batch is drawn — otherwise a frame's worth of work
+   * can sit there while the pixels it was meant to produce are read by
+   * whoever comes next, and stay there until that context happens to draw
+   * something of a different kind (#578). The state is still the outgoing
+   * owner's at this point, which is what the flush needs.
+   *
+   * It is also what device.js's invariant rests on: the owner is the only
+   * context that can be holding anything.
+   */
+  _take() {
+    const previous = this._device.owner;
+    if (previous && previous !== this) previous._flush();
+    this._device.owner = this;
+  }
+
   /** Give the device up, so the next draw through this context re-takes it. */
   _release() {
     if (this._device.owner === this) this._device.owner = null;
@@ -1950,6 +1970,11 @@ export class WaylandContext2D {
 
   /** Two triangles from four corners, in order TL, TR, BR, BL. */
   _quad(pos, uv, color, params) {
+    // Buffering is taking the device, not a step before it: the quad is GL
+    // work that has been decided on and not yet issued, and the handover in
+    // `_take` is the only thing that can get it issued before someone reads
+    // the pixels it makes. A property compare in the common case.
+    this._claim();
     if (this._n + 6 > MAX_VERTS) this._flush();
     const v = this._verts;
     let o = this._n * STRIDE;
@@ -1974,6 +1999,7 @@ export class WaylandContext2D {
 
   /** One triangle, for the stencil pass. Colour and params are irrelevant. */
   _tri(x0, y0, x1, y1, x2, y2) {
+    this._claim();
     if (this._n + 3 > MAX_VERTS) this._flush();
     const v = this._verts;
     let o = this._n * STRIDE;

package/src/wayland/device.js

@@ -16,6 +16,15 @@
 // back. Whoever drew in between does not have to know who comes next, and a
 // caller does not have to know there is a device at all.
 //
+// Claiming is also a *batch boundary*: a 2d context buffers its quads and
+// draws them in one call later, so the outgoing owner is flushed on the way
+// out. That is what makes the invariant this module offers true — **only the
+// owner can have work still buffered** — and the invariant is what lets
+// anyone about to read a target's pixels get them by flushing one context
+// (`flushDevice`) rather than by knowing which one drew them. Without it a
+// held surface context's whole frame could sit in a vertex buffer while the
+// `drawImage` that should show it sampled the texture behind it (#578).
+//
 // One record per `gl`, keyed weakly: a GPU that goes away takes its record
 // with it.
 const devices = new WeakMap();
@@ -53,3 +62,17 @@ export function releaseDevice(gl) {
   const device = shared(gl) ? devices.get(gl) : null;
   if (device) device.owner = null;
 }
+
+/**
+ * Draw what is still buffered, so that a target's texture holds everything
+ * that has been drawn into it.
+ *
+ * The owner is the only context that can be holding anything (see above), so
+ * flushing it is flushing the device. Call before *reading* a target's pixels
+ * behind the contexts' backs — a framebuffer blit, a scroll copy — the way
+ * `releaseDevice` is called after writing them.
+ */
+export function flushDevice(gl) {
+  const device = shared(gl) ? devices.get(gl) : null;
+  device?.owner?.flush();
+}

package/src/wayland/target.js

@@ -21,7 +21,7 @@
 // asking EGL for it means the window's own config no longer has to carry
 // stencil bits at all; the request in glcontext.js stays as belt and braces.
 
-import { releaseDevice } from './device.js';
+import { flushDevice, releaseDevice } from './device.js';
 
 export class GLTarget {
   /**
@@ -133,6 +133,9 @@ export class GLTarget {
    */
   blitTo(drawFbo, rects, dstWidth = this.width, dstHeight = this.height) {
     const gl = this.gl;
+    // Reading these pixels, so everything drawn into them has to be in the
+    // texture and not still in a context's vertex buffer (device.js).
+    flushDevice(gl);
     gl.bindFramebuffer(gl.READ_FRAMEBUFFER, this.fbo);
     gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, drawFbo);
     gl.disable(gl.SCISSOR_TEST);
@@ -201,6 +204,11 @@ export class GLTarget {
     const sy = dstY0 - dy;
 
     const gl = this.gl;
+    // A scroll reads this target before it writes it, so anything a context
+    // still has buffered has to land first — or the band that moves is the
+    // frame before last's, and the buffered quads arrive afterwards at the
+    // position the scroll just left (device.js).
+    flushDevice(gl);
     const scratch = scratchFor(gl, bw, bh);
     // out: this[sx,sy,bw,bh] -> scratch[0,0]
     gl.bindFramebuffer(gl.READ_FRAMEBUFFER, this.fbo);