ntk 4.2.0 → 5.0.0

package/lib/index.js

@@ -4,6 +4,7 @@ import App from './app.js';
 import Clipboard from './clipboard.js';
 import { BLANK_CURSOR, CursorCache, cursorNames, cursorShapes, resolveCursorShape } from './cursor.js';
 import Window from './window.js';
+import { loadLayout } from './yoga.js';
 import { decodeKey, groupForState } from './keyboard.js';
 import Pixmap from './pixmap.js';
 import Picture from './picture.js';
@@ -31,6 +32,16 @@ import './renderingcontext_x11.js';
 import './renderingcontext_2d.js';
 import './renderingcontext_opengl.js';
 
+// One socket write per frame instead of one per request (x11 >= 3.6). A frame
+// is emitted in one synchronous run of _runFrame() and ends with the frame
+// fence's GetInputFocus, which x11 flushes on because it expects a reply — so
+// the batch goes out at the frame boundary without ntk flushing anything by
+// hand. 64 KB holds a heavy frame (a 72 KB frame is 2 writes, a typical one
+// is 1); the client's own gates — the size cap, a 5 ms age limit and a flush
+// before the event loop polls — bound how long anything can wait, so this
+// cannot delay a frame or a reply. `bufferRequests: false` opts out.
+const DEFAULT_BUFFER_REQUESTS = { maxSize: 64 * 1024 };
+
 /**
  * Connect to the X server and resolve with an App.
  *
@@ -46,7 +57,9 @@ import './renderingcontext_opengl.js';
  *   { glxVisual } — a visual id for getContext('opengl') to use instead of
  *   querying the server for one — and
  *   { onXError } — called with X protocol errors no request callback
- *   claimed (default: console.warn)
+ *   claimed (default: console.warn).
+ *   x11's { bufferRequests } defaults to a 64 KB output buffer here, which
+ *   makes a frame one socket write; pass false to write per request.
  * @param {function} [callback] optional node-style callback
  * @returns {Promise<App>}
  */
@@ -56,8 +69,15 @@ export function createClient(options, callback) {
     options = {};
   }
 
-  const promise = new Promise((resolve, reject) => {
-    x11.createClient(options || {}, (error, display) => {
+  const x11Options = { ...(options || {}) };
+  if (x11Options.bufferRequests === undefined) x11Options.bufferRequests = DEFAULT_BUFFER_REQUESTS;
+
+  // the layout engine's WASM loads alongside the connection, so widgets are
+  // usable synchronously by the time the App exists (see lib/yoga.js)
+  const layout = loadLayout();
+
+  const connecting = new Promise((resolve, reject) => {
+    x11.createClient(x11Options, (error, display) => {
       if (error) return reject(error);
 
       display.client.require('glx', (glxError, GLX) => {
@@ -98,6 +118,8 @@ export function createClient(options, callback) {
     });
   });
 
+  const promise = Promise.all([connecting, layout]).then(([app]) => app);
+
   if (callback) {
     promise.then(
       (app) => callback(null, app),
@@ -145,8 +167,11 @@ export {
   decodeKey,
   groupForState
 };
-// the yoga-layout instance ntk lays HtmlView out with — downstream layout
-// consumers (e.g. the react-x11 renderer) must share it to avoid loading a
-// second WASM copy with potentially mismatched enums
-export { default as Yoga } from 'yoga-layout';
+// The layout engine ntk lays HtmlView out with — downstream layout consumers
+// (e.g. the react-x11 renderer) must import it from here rather than from
+// `yoga-layout`, or they get a second WASM instance whose Nodes cannot be
+// mixed with ntk's. Its enum constants are readable as soon as ntk is
+// imported; `Node`/`Config` need the WASM, which `createClient()` loads —
+// `loadLayout()` is there for widgets used without an App.
+export { default as Yoga, loadLayout, layoutLoaded } from './yoga.js';
 export default { createClient };

package/lib/widgets/htmlview.js

@@ -1,7 +1,7 @@
 import { selectAll } from 'css-select';
 import { textContent } from 'domutils';
 import { parseDocument } from 'htmlparser2';
-import Yoga from 'yoga-layout';
+import Yoga from '../yoga.js';
 
 import { decodeImage, Image } from '../image.js';
 import { TextLayout } from '../text/layout.js';

package/lib/window.js

@@ -693,6 +693,66 @@ export default class Window extends Drawable {
     });
   }
 
+  /**
+   * Scroll the pixels of `rect` (window coordinates, `{x, y, width, height}`)
+   * by (dx, dy) within the retained backing store, server-side: one CopyArea
+   * of the band that survives the shift, in place of the caller re-drawing
+   * everything that merely moved. Returns true when the blit was issued;
+   * false means "not possible here", and the caller repaints `rect` exactly
+   * as it would have without this method — every refusal is the status quo.
+   *
+   * Refused when there is no (valid) backing store, when the delta is
+   * fractional (a sub-pixel shift changes every pixel, so there is nothing
+   * to copy), when it is zero, or when nothing of `rect` survives the shift
+   * after clamping to window ∩ backing.
+   *
+   * Backing-store only, deliberately: pixmap contents cannot be occluded, so
+   * an overlapping self-copy is fully defined (the server fetches the source
+   * region before storing) and the GraphicsExpose handling a window-drawable
+   * scroll would need never exists. The copy goes out with the present GC —
+   * graphicsExposures: 0, where the 2d context's GC would emit a NoExposure
+   * packet per copy — and in-order with the caller's follow-up drawing of
+   * the exposed strip on the same connection.
+   *
+   * The whole of `rect` is marked dirty, so the next present shows the
+   * scrolled band through the normal fence-aware path; the caller only has
+   * to draw the strip the shift exposed, plus any chrome that moved with
+   * the content (a scrollbar thumb, say).
+   */
+  scrollRegion(rect, dx, dy) {
+    if (!this._backing || !this._backingValid) return false;
+    if (!Number.isInteger(dx) || !Number.isInteger(dy) || (dx === 0 && dy === 0)) return false;
+    // clamp like a present: the backing is grow-only, so it can be larger
+    // than the window after a shrink
+    const w = Math.min(this.width, this._backing.width);
+    const h = Math.min(this.height, this._backing.height);
+    const x0 = Math.max(0, Math.floor(rect.x));
+    const y0 = Math.max(0, Math.floor(rect.y));
+    const x1 = Math.min(w, Math.ceil(rect.x + rect.width));
+    const y1 = Math.min(h, Math.ceil(rect.y + rect.height));
+    // the band that survives: dest = clamped rect ∩ (clamped rect + delta)
+    const dstX0 = Math.max(x0, x0 + dx);
+    const dstY0 = Math.max(y0, y0 + dy);
+    const dstX1 = Math.min(x1, x1 + dx);
+    const dstY1 = Math.min(y1, y1 + dy);
+    if (dstX1 <= dstX0 || dstY1 <= dstY0) return false;
+    safeRelease(this.X, () => {
+      this.X.CopyArea(
+        this._backing.id,
+        this._backing.id,
+        this._presentGc,
+        dstX0 - dx,
+        dstY0 - dy,
+        dstX0,
+        dstY0,
+        dstX1 - dstX0,
+        dstY1 - dstY0
+      );
+    });
+    this._markDirty({ x: x0, y: y0, w: x1 - x0, h: y1 - y0 });
+    return true;
+  }
+
   /*
    * Frame clock. Noisy events (see events_map coalesce), synthetic redraws
    * and requestAnimationFrame callbacks are delivered in "frames", paced by

package/lib/yoga.js

@@ -0,0 +1,119 @@
+// The layout engine, without a top-level await.
+//
+// `yoga-layout`'s default entry is `const Yoga = wrapAssembly(await
+// loadYoga())`. That one `await` is contagious: every bundle containing ntk
+// inherits it, esbuild then refuses to emit CommonJS ("Top-level await is
+// currently not supported with the cjs output format"), and Node's single
+// executable format runs its embedded main as CommonJS — so an ntk app could
+// not be shipped as one binary at all.
+//
+// So ntk imports the half of the package that has no WASM in it —
+// `yoga-layout/load` exports the enums as plain JavaScript and the assembly
+// behind an async function — and loads the assembly during `createClient()`,
+// which is already asynchronous.
+//
+// The object exported here keeps yoga's own shape, and that is the point:
+// the flat SCREAMING_CASE constants are present from the first tick, so a
+// consumer that builds a lookup table at module scope (ntk's own HtmlView,
+// react-x11's styles.js) still reads them at import time. `Node`, `Config`
+// and the rest of the assembly appear when `loadLayout()` resolves.
+
+import {
+  loadYoga,
+  Align,
+  BoxSizing,
+  Dimension,
+  Direction,
+  Display,
+  Edge,
+  Errata,
+  ExperimentalFeature,
+  FlexDirection,
+  Gutter,
+  Justify,
+  LogLevel,
+  MeasureMode,
+  NodeType,
+  Overflow,
+  PositionType,
+  Unit,
+  Wrap
+} from 'yoga-layout/load';
+
+const ENUMS = {
+  Align,
+  BoxSizing,
+  Dimension,
+  Direction,
+  Display,
+  Edge,
+  Errata,
+  ExperimentalFeature,
+  FlexDirection,
+  Gutter,
+  Justify,
+  LogLevel,
+  MeasureMode,
+  NodeType,
+  Overflow,
+  PositionType,
+  Unit,
+  Wrap
+};
+
+// yoga's generator names each constant <ENUM>_<MEMBER>, both snake-cased from
+// PascalCase: FlexDirection.ColumnReverse -> FLEX_DIRECTION_COLUMN_REVERSE.
+// yoga-export.test.js pins every name against the real assembly, so a rename
+// upstream fails loudly instead of yielding an undefined constant.
+const screamingSnake = (name) => name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+
+/** The layout engine: enums now, assembly after `loadLayout()`. */
+const Yoga = {};
+for (const [enumName, members] of Object.entries(ENUMS)) {
+  // a bundler may stub yoga out entirely — the browser playground does,
+  // since no demo uses HtmlView — and importing ntk must still work
+  if (!members || typeof members !== 'object') continue;
+  const prefix = screamingSnake(enumName);
+  for (const [member, value] of Object.entries(members)) {
+    if (typeof value === 'number') Yoga[`${prefix}_${screamingSnake(member)}`] = value;
+  }
+}
+
+const notLoaded = (what) => () => {
+  throw new Error(
+    `ntk: the layout engine is not loaded, so Yoga.${what} is not available yet. ` +
+      'createClient() loads it; widgets used without an App need `await loadLayout()` first.'
+  );
+};
+
+// A useful message instead of "Cannot read properties of undefined"
+for (const name of ['Node', 'Config']) {
+  Object.defineProperty(Yoga, name, { configurable: true, get: notLoaded(name) });
+}
+
+let loading = null;
+
+/**
+ * Load the layout engine's WebAssembly. Idempotent, and resolves with the
+ * same `Yoga` object this module exports — `createClient()` awaits it, so
+ * applications rarely call it themselves. Widgets used without an App
+ * (`new HtmlView(null, …)`) need it.
+ */
+export function loadLayout() {
+  if (!loading) {
+    loading = loadYoga().then((assembly) => {
+      for (const name of ['Node', 'Config']) delete Yoga[name]; // drop the throwing getters
+      Object.assign(Yoga, assembly);
+      return Yoga;
+    });
+  }
+  return loading;
+}
+
+/** Whether the assembly is in place — layout will not throw. */
+export function layoutLoaded() {
+  return Object.getOwnPropertyDescriptor(Yoga, 'Node')?.value !== undefined;
+}
+
+export { Yoga };
+export default Yoga;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",
@@ -48,7 +48,7 @@
     "parse-color": "^1.0.0",
     "pngjs": "^7.0.0",
     "postcss": "^8.5.23",
-    "x11": "^3.4.0",
+    "x11": "^3.6.0",
     "yoga-layout": "^3.2.1"
   },
   "scripts": {