ntk 2.1.1 → 3.0.0

package/README.md

@@ -1,9 +1,20 @@
 ntk
 ===
 
-node.js desktop UI toolkit
+node.js desktop UI toolkit for X11
 
-A set of wrappers around low level [node-x11](https://github.com/sidorares/node-x11) module to simplify X Window UI progamming - windows creation, event handling, 2d/3d graphics etc.
+A set of wrappers around the low level [node-x11](https://github.com/sidorares/node-x11)
+module to simplify X Window UI programming — window creation, DOM-style event
+handling, 2d/3d graphics — using API concepts you already know from the web.
+
+Everything, including font rasterization, is pure JavaScript: `npm install`
+never compiles anything.
+
+**Docs & live playground:** <https://sidorares.github.io/ntk/> — the
+playground runs ordinary ntk code in your browser against node-x11's
+in-browser pure-JS X server (XRender included) with bundled fonts. The same server also works headless in node — see
+[docs/xserver.md](docs/xserver.md) — so ntk apps and tests can run with no
+real X server at all.
 
 # Installation
 
@@ -11,141 +22,135 @@ A set of wrappers around low level [node-x11](https://github.com/sidorares/node-
 npm install ntk
 ```
 
+Requires Node.js >= 20.19 and an X server. Full documentation lives in
+[docs/](docs/README.md).
+
 ## Basic usage
 
 ```js
-require('ntk').createClient( (err, app) => {
-  var mainWnd = app.createWindow({ width: 500, height: 300, title: 'Hello' });
-  mainWnd.on('mousedown', (ev) => { mainWnd.setTitle('click: ' + [ev.x, ev.y].join(',')); });
-  mainWnd.map();
-});
+import { createClient } from 'ntk';
+
+const app = await createClient();
+const wnd = app.createWindow({ width: 500, height: 300, title: 'Hello' });
+wnd.on('mousedown', (ev) => wnd.setTitle(`click: ${ev.x},${ev.y}`));
+wnd.map();
 ```
 
 ## 2d graphics
 
-Each window ( or pixmap ) can be used to create 2d and 3d canvas. 2d canvas implements HTML [context2d api](https://html.spec.whatwg.org/multipage/scripting.html#2dcontext) ( some features not yet supported ) via [XRender extension](http://www.x.org/releases/X11R7.7/doc/renderproto/renderproto.txt), and most operations are performed on the X Server side ( image composition, scaling, blur, text composition, gradients etc ). Initial font rendering is performed by ntk using [freetype2](https://github.com/ericfreese/node-freetype2) module and fonts names mapped to file names using [font-manager](https://github.com/devongovett/font-manager) module.
+Each window (or pixmap) can create a 2d canvas implementing the HTML
+[context2d api](https://html.spec.whatwg.org/multipage/canvas.html#2dcontext)
+via the
+[XRender extension](https://www.x.org/releases/X11R7.7/doc/renderproto/renderproto.txt) —
+paths (arcs, beziers, `Path2D` with SVG path data, non-zero/even-odd fill
+rules), transforms with `save()`/`restore()`, clipping, `globalAlpha` and
+Porter-Duff composite ops ([docs/context-2d.md](docs/context-2d.md)).
+Most operations are performed on the X server side (image composition,
+scaling, blur, text composition, gradients etc). Text is fully shaped in
+pure JS — OpenType kerning/ligatures and complex scripts (fontkit), bidi
+(bidi-js), automatic font fallback — rasterized by a built-in scanline
+rasterizer and cached server-side as XRender glyphs, so drawing a line of
+text costs about a byte per glyph on the wire. Font names resolve through
+fontconfig (`fc-match`). Very large and continuously animated sizes render
+as server-side trapezoids instead of cached bitmaps. A `TextLayout` engine
+wraps styled text to a target width, a `MarkdownView` widget renders
+markdown (with syntax-highlighted code fences, mermaid flowchart/sequence
+diagrams, and KaTeX math via `TexView`) on top of it — see
+[docs/text.md](docs/text.md), [docs/mermaid.md](docs/mermaid.md) and
+[docs/tex.md](docs/tex.md).
+
+PNG/JPEG images decode client-side (`loadImage`) and composite server-side
+via `ctx.drawImage` ([docs/images.md](docs/images.md)). An `HtmlView`
+widget renders a static HTML + CSS subset — block flow and flexbox laid
+out by yoga-layout, no scripts, no network — with app-controlled link
+navigation ([docs/html.md](docs/html.md)). An `SvgView` widget renders
+static SVG (shapes, gradients, transforms, `use`) through the same 2d
+pipeline ([docs/svg.md](docs/svg.md)).
 
 ```js
-var ntk = require('ntk');
-
-ntk.createClient( (err, app) => {
-  var wnd = app.createWindow({ width: 800, height: 600});
-  var ctx = wnd.getContext('2d');
-
-  wnd.on('mousemove', (ev) => {
-    var gradient = ctx.createRadialGradient(0, 0, 10, ev.x, ev.y, 500);
-    gradient.addColorStop(0, "red");
-    gradient.addColorStop(0.5, "green");
-    gradient.addColorStop(1, "rgba(255, 255, 255, 0)");
-    ctx.fillStyle = gradient;
-    ctx.fillRect(0, 0, ctx.width, ctx.height);
-  });
-
-  wnd.map();
+import { createClient } from 'ntk';
+
+const app = await createClient();
+const wnd = app.createWindow({ width: 800, height: 600 });
+const ctx = wnd.getContext('2d');
+
+wnd.on('mousemove', (ev) => {
+  const gradient = ctx.createRadialGradient(0, 0, 10, ev.x, ev.y, 500);
+  gradient.addColorStop(0, 'red');
+  gradient.addColorStop(0.5, 'green');
+  gradient.addColorStop(1, 'rgba(255, 255, 255, 0)');
+  ctx.fillStyle = gradient;
+  ctx.fillRect(0, 0, ctx.width, ctx.height);
 });
+
+wnd.map();
 ```
 
-`ctx.drawImage()` also accepts [node-canvas](https://github.com/Automattic/node-canvas) as a source, for images with lot's of drawing calls it might be more efficient to perform all drawing locally and transfer pixels to server when ready:
+`ctx.drawImage()` also accepts a [node-canvas](https://github.com/Automattic/node-canvas)
+canvas as a source — for images with lots of drawing calls it might be more
+efficient to draw locally and transfer pixels to the server when ready.
 
-```js
-var ntk = require('ntk');
-var Canvas = require('canvas');
+## Frame pacing & networked displays
 
-var canvas = new Canvas(800, 800);
-var canvasCtx = canvas.getContext('2d');
+Noisy events (`resize`, `mousemove`, `expose`) are coalesced into paced
+frames — the latest state wins, nothing queues up — and each frame is
+fenced with a server round-trip, so rendering automatically slows to the
+connection's real throughput instead of drawing a trail of stale updates
+over ssh-forwarded displays. Animation uses the DOM-style
+`requestAnimationFrame`:
 
-function drawSomething(ctx) {
-  // ...
+```js
+function frame(now) {
+  // ... draw ...
+  wnd.requestAnimationFrame(frame); // ~60fps locally, RTT-paced remotely
 }
+wnd.requestAnimationFrame(frame);
+```
 
-ntk.createClient( (err, app) => {
-  var wnd = app.createWindow({ width: 800, height: 800});
+See [docs/window.md](docs/window.md) for the knobs (`frameInterval`,
+`frameSync`, `coalesceEvents`) and the raw uncoalesced event stream.
 
-  var ctx = wnd.getContext('2d');
+## Resource management
 
-  setInterval(function() {
-    drawSomething(canvasCtx);
-    ctx.drawImage(canvas);
-  }, 20);
+Server-side resources support `using` / `await using` (Node 24+):
 
-  wnd.map();
-});
+```js
+{
+  await using app = await createClient();
+  using pixmap = app.createPixmap({ width: 256, height: 256, depth: 24 });
+  // ... draw ...
+} // pixmap freed, connection closed
 ```
 
 ## 3d graphics
 
-At the moment only indirect GLX is supported with most of OpenGL 1.4 api implemented. Note that on some systems indirect GLX might be disabled by default, [you'll need to enable it for gl to work](https://github.com/sidorares/node-x11/issues/117#issuecomment-214762185).
+Only indirect GLX is supported, with most of the OpenGL 1.4 api implemented.
+Note that on many systems indirect GLX is disabled by default —
+[you'll need to enable it for gl to work](https://github.com/sidorares/node-x11/issues/117#issuecomment-214762185).
 
 ```js
-var ntk = require('ntk');
-
-var width = 300;
-var height = 300;
-var angle = 0;
-
-function resize(gl) {
-  gl.Viewport(0, 0, width, height);
-  gl.MatrixMode(gl.PROJECTION);
-  gl.LoadIdentity();
-  if (width < height)
-    gl.Frustum(-1.0, 1.0, -height/width, height/width, -35.0, 20);
-  else
-    gl.Frustum(-width/height, width/height, -1.0, 1.0, -35.0, 20);
-}
-
-function draw(gl) {
-    gl.MatrixMode(gl.MODELVIEW);
-
-    gl.ClearColor(0.3,0.3,0.3,0.0);
-    gl.Clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
-
-    gl.LoadIdentity();
-    gl.Rotatef(-90 + 360*angle/width, 0, 0, 1);
-    gl.Begin(gl.TRIANGLE_STRIP);
-      gl.TexCoord2f(0.0,0.0);
-      gl.Vertex3f(-1, -1, 0);
-
-      gl.TexCoord2f(1.0, 0.0);
-      gl.Vertex3f(1, -1, 0);
-
-      gl.TexCoord2f(0.0, 1.0);
-      gl.Vertex3f(-1, 1, 0);
-
-      gl.TexCoord2f(1.0,1.0);
-      gl.Vertex3f(1, 1, 0);
-    gl.End();
-    gl.SwapBuffers();
-}
-
-var texture = require('baboon-image');
-
-ntk.createClient(function(err, app) {
-
-  var wnd = app.createWindow({width: width, height: height});
-  wnd.map();
-  var gl = wnd.getContext('opengl');
-  gl.Enable(gl.TEXTURE_2D);
-  gl.GenTextures(1, function(err, textures) {
-    gl.BindTexture(gl.TEXTURE_2D, textures[0]);
-    gl.TexParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
-    gl.TexParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
-    gl.TexImage2D(gl.TEXTURE_2D, 0, gl.RGB, 512, 512, 0, gl.RGB, gl.UNSIGNED_BYTE, texture.data);
-    draw(gl);
-
-    wnd.on('resize', function(ev) {
-       width = ev.width;
-       height = ev.height;
-       resize(gl);
-       draw(gl);
-    }).on('mousemove', function(ev) {
-      angle = ev.x;
-      draw(gl);
-    });
-  });
-});
-
+import { createClient } from 'ntk';
+
+const app = await createClient();
+const wnd = app.createWindow({ width: 300, height: 300 });
+wnd.map();
+
+const gl = wnd.getContext('opengl');
+gl.ClearColor(0.3, 0.3, 0.3, 0.0);
+gl.Clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+gl.Begin(gl.TRIANGLES);
+gl.Color3f(1, 0, 0);
+gl.Vertex3f(-1, -1, 0);
+gl.Vertex3f(1, -1, 0);
+gl.Vertex3f(0, 1, 0);
+gl.End();
+gl.SwapBuffers();
 ```
 
+See [examples/](examples/) for more (teapot, GL clock, textures, text
+rendering).
+
 ## High level widgets / layout management etc
 
-Likely to be implemented outside as part of [react-x11](https://github.com/sidorares/react-x11)
+Likely to be implemented outside as part of a react renderer
+([react-x11](https://github.com/sidorares/react-x11)).

package/lib/app.js

@@ -1,21 +1,54 @@
-var Window = require('./window');
-var Pixmap = require('./pixmap');
+import Pixmap from './pixmap.js';
+import FontManager from './text/fontmanager.js';
+import Window from './window.js';
 
-module.exports = App;
+/**
+ * A connection to an X server. Owns the underlying node-x11 client
+ * (`app.X`) and acts as a factory for windows and pixmaps.
+ */
+export default class App {
+  /**
+   * @param {object} display node-x11 display
+   * @param {object} [options] environment hooks: { fontSource (see
+   *   text/fontsource.js), glxVisual (visual id for getContext('opengl')
+   *   when glxinfo can't be shelled out to) }
+   */
+  constructor(display, options = {}) {
+    this.display = display;
+    this.X = display.client;
+    this.options = options;
+    this._fonts = null;
+  }
 
-function App(display) {
-  this.display = display;
-  this.X = display.client;
-}
+  /** the text API entry point: font matching/loading, shaping, layout */
+  get fonts() {
+    if (!this._fonts) this._fonts = new FontManager({ source: this.options.fontSource });
+    return this._fonts;
+  }
 
-App.prototype.createWindow = function(args) {
-  return new Window(this, args);
-}
+  createWindow(args) {
+    return new Window(this, args);
+  }
 
-App.prototype.rootWindow = function() {
-  return new Window(this, { id: this.display.screen[0].root} );
-}
+  rootWindow() {
+    return new Window(this, { id: this.display.screen[0].root });
+  }
+
+  createPixmap(args) {
+    return new Pixmap(this, args);
+  }
+
+  // flush pending requests and close the connection
+  close() {
+    return new Promise((resolve) => this.X.close(resolve));
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
 
-App.prototype.createPixmap = function(args) {
-  return new Pixmap(this, args);
+  // sync variant: terminates without waiting for a flush round-trip
+  [Symbol.dispose]() {
+    this.X.terminate();
+  }
 }

package/lib/cleanup.js

@@ -0,0 +1,14 @@
+// Release a server-side resource, tolerating a connection that is closing or
+// already gone — the X server frees all of a client's resources on disconnect,
+// so there is nothing left to do and nothing worth throwing about. This
+// matters for FinalizationRegistry callbacks, which run after app.close() if
+// wrappers get garbage collected late and have no user code around them to
+// catch.
+export function safeRelease(X, fn) {
+  if (X._closing || !X.stream || X.stream.destroyed || X.stream.writableEnded) return;
+  try {
+    fn();
+  } catch {
+    // connection raced shut between the check and the request
+  }
+}

package/lib/drawable.js

@@ -1,18 +1,12 @@
-var EventEmitter = require('events').EventEmitter;
-var util = require('util');
-
-module.exports = Drawable;
-
-function Drawable() {
-    EventEmitter.call(this);
+import { EventEmitter } from 'node:events';
+
+export default class Drawable extends EventEmitter {
+  getContext(name, ...args) {
+    const factory = Drawable.renderingContextFactory[name];
+    if (!factory) throw new Error(`Unknown rendering context: ${name}`);
+    return factory(this, ...args);
+  }
 }
-util.inherits(Drawable, EventEmitter);
 
-Drawable.prototype.renderingContextFactory = {};
-
-Drawable.prototype.getContext = function(name, arg1, arg2, arg3) {
-	var renderingContextFactory = this.renderingContextFactory[name];
-	if (!renderingContextFactory)
-		throw new Error('Unknown rendering context:', name);
-  return renderingContextFactory(this, arg1, arg2, arg3);
-}
+// populated by the renderingcontext_* modules on import
+Drawable.renderingContextFactory = {};

package/lib/events_map.js

@@ -1,98 +1,92 @@
-var x11 = require('x11');
+import x11 from 'x11';
 
 // todo: move event names to node-x11, it should be part of event object
-var eventIdToName = module.exports.eventName = [];
-eventIdToName[2]  = 'keydown';
-eventIdToName[3]  = 'keyup';
-eventIdToName[4]  = 'mousedown';
-eventIdToName[5]  = 'mouseup';
-eventIdToName[6]  = 'mousemove';
-eventIdToName[7]  = 'mouseover';
-eventIdToName[8]  = 'mouseout';
-eventIdToName[12] = 'expose';
-eventIdToName[17] = 'destroy';
-eventIdToName[18] = 'unmap';
-eventIdToName[19] = 'map';
-eventIdToName[20] = 'map_request';
-eventIdToName[21] = 'reparent';
-eventIdToName[22] = 'resize';
-eventIdToName[23] = 'configure_request';
+export const eventName = [];
+eventName[2] = 'keydown';
+eventName[3] = 'keyup';
+eventName[4] = 'mousedown';
+eventName[5] = 'mouseup';
+eventName[6] = 'mousemove';
+eventName[7] = 'mouseover';
+eventName[8] = 'mouseout';
+eventName[12] = 'expose';
+eventName[17] = 'destroy';
+eventName[18] = 'unmap';
+eventName[19] = 'map';
+eventName[20] = 'map_request';
+eventName[21] = 'reparent';
+eventName[22] = 'resize';
+eventName[23] = 'configure_request';
 // 25 - gravity
-eventIdToName[25] = 'resize_request';
-eventIdToName[26] = 'circulate';
-eventIdToName[27] = 'circulate_request';
-eventIdToName[28] = 'property';
-eventIdToName[29] = 'selection_clear';
-eventIdToName[30] = 'selection_request';
-eventIdToName[31] = 'selection';
-eventIdToName[33] = 'message';
+eventName[25] = 'resize_request';
+eventName[26] = 'circulate';
+eventName[27] = 'circulate_request';
+eventName[28] = 'property';
+eventName[29] = 'selection_clear';
+eventName[30] = 'selection_request';
+eventName[31] = 'selection';
+eventName[33] = 'message';
 
 // event mask you need to select to receive event
 // 0 = no need to express interest, event is sent regardless of mask
-module.exports.mask = {
-	'mousemove': x11.eventMask.PointerMotion,
-	'mouseover': x11.eventMask.EnterWindow,
-	'mouseout': x11.eventMask.LeaveWindow,
-	'mousedown': x11.eventMask.ButtonPress,
-	'mouseup': x11.eventMask.ButtonRelease,
-	'map'  : x11.eventMask.StructureNotify,
-	'unmap': x11.eventMask.StructureNotify,
-	'resize': x11.eventMask.StructureNotify,
-  'reparent': x11.eventMask.StructureNotify,
-	'keydown': x11.eventMask.KeyPress,
-	'expose': x11.eventMask.Exposure,
-	'map_request': x11.eventMask.SubstructureRedirect,
-	'configure_request': x11.eventMask.SubstructureRedirect,
-	'destroy': x11.eventMask.StructureNotify,
-	'keyup': x11.eventMask.KeyRelease,
-	'property': x11.eventMask.PropertyChange,
-	'selection': 0,
-	'selection_request': 0,
-	'message': 0
+export const mask = {
+  mousemove: x11.eventMask.PointerMotion,
+  mouseover: x11.eventMask.EnterWindow,
+  mouseout: x11.eventMask.LeaveWindow,
+  mousedown: x11.eventMask.ButtonPress,
+  mouseup: x11.eventMask.ButtonRelease,
+  map: x11.eventMask.StructureNotify,
+  unmap: x11.eventMask.StructureNotify,
+  resize: x11.eventMask.StructureNotify,
+  reparent: x11.eventMask.StructureNotify,
+  keydown: x11.eventMask.KeyPress,
+  expose: x11.eventMask.Exposure,
+  map_request: x11.eventMask.SubstructureRedirect,
+  configure_request: x11.eventMask.SubstructureRedirect,
+  destroy: x11.eventMask.StructureNotify,
+  keyup: x11.eventMask.KeyRelease,
+  property: x11.eventMask.PropertyChange,
+  selection: 0,
+  selection_request: 0,
+  message: 0
 };
 
-module.exports.maskCamelCase = {
-	'onMouseMove': x11.eventMask.PointerMotion,
-	'onMouseOver': x11.eventMask.EnterWindow,
-	'onMouseOut': x11.eventMask.LeaveWindow,
-	'onMouseDown': x11.eventMask.ButtonPress,
-	'onMouseUp': x11.eventMask.ButtonRelease,
-	'onMap'  : x11.eventMask.StructureNotify,
-	'onUnmap': x11.eventMask.StructureNotify,
-	'onResize': x11.eventMask.StructureNotify,
-  'onReparent': x11.eventMask.StructureNotify,
-	'onKeyDown': x11.eventMask.KeyPress,
-	'onExpose': x11.eventMask.Exposure,
-	'onMapRequest': x11.eventMask.SubstructureRedirect,
-	'onConfigureRequest': x11.eventMask.SubstructureRedirect,
-	'onDestroy': x11.eventMask.StructureNotify,
-	'onKeyUp': x11.eventMask.KeyRelease,
-	'onPropertyChange': x11.eventMask.PropertyChange,
-	// TODO
-	'onSelection': 0,
-	'onSelectionRequest': 0,
-	'onMessage': 0
+// events that are noisy by nature: intermediate occurrences carry no
+// information the final one doesn't, so Window merges bursts into a single
+// event per paced frame (see docs/window.md). 'last' — the newest event
+// wins (older ones ride along in ev.coalesced); 'union' — damage
+// rectangles accumulate (bounding box in ev.x/y/width/height, every rect
+// in ev.rects).
+export const coalesce = {
+  mousemove: 'last',
+  resize: 'last',
+  expose: 'union'
 };
 
-module.exports.toSnake = {
-	'onMouseMove': 'mousemove',
-	'onMouseOver': 'mouseover',
-	'onMouseOut': 'mouseout',
-	'onMouseDown': 'mousedown',
-	'onMouseUp': 'mouseup',
-	'onMap'  : 'map',
-	'onUnmap': 'unmap',
-	'onResize': 'resize',
-  'onReparent': 'reparent',
-	'onKeyDown': 'keydown',
-	'onExpose': 'expose',
-	'onMapRequest': 'map_request',
-	'onConfigureRequest': 'configure_request',
-	'onDestroy': 'destroy',
-	'onKeyUp': 'keyup',
-	'onPropertyChange': 'property',
-	// TODO
-	'onSelection': 'selection',
-	'onSelectionRequest': 'selection_request',
-	'onMessage': 'message'
+export const toSnake = {
+  onMouseMove: 'mousemove',
+  onMouseOver: 'mouseover',
+  onMouseOut: 'mouseout',
+  onMouseDown: 'mousedown',
+  onMouseUp: 'mouseup',
+  onMap: 'map',
+  onUnmap: 'unmap',
+  onResize: 'resize',
+  onReparent: 'reparent',
+  onKeyDown: 'keydown',
+  onExpose: 'expose',
+  onMapRequest: 'map_request',
+  onConfigureRequest: 'configure_request',
+  onDestroy: 'destroy',
+  onKeyUp: 'keyup',
+  onPropertyChange: 'property',
+  onSelection: 'selection',
+  onSelectionRequest: 'selection_request',
+  onMessage: 'message'
 };
+
+export const maskCamelCase = Object.fromEntries(
+  Object.entries(toSnake).map(([camel, snake]) => [camel, mask[snake]])
+);
+
+export default { eventName, mask, maskCamelCase, toSnake, coalesce };