novac 2.0.1 → 2.2.0

package/novac/kits/kitx11/kitx11_conn.js

@@ -0,0 +1,948 @@
+'use strict';
+// ============================================================
+//  kitx11_conn.js  —  Synchronous X11 connection + drawing API
+//
+//  Uses a Worker thread to own the async socket, then bridges
+//  back to the main thread with receiveMessageOnPort() so all
+//  calls appear synchronous to the caller.
+//
+//  Usage:
+//    const X11 = require('./kitx11_conn');
+//    const conn = X11.connect();               // sync
+//    const win  = conn.createWindow({...});    // sync
+//    conn.mapWindow(win);                      // sync
+//    conn.flush();                             // sync — sends queued packets
+//    const ev   = conn.nextEvent();            // sync — blocks until event
+// ============================================================
+
+const {
+  Worker,
+  MessageChannel,
+  receiveMessageOnPort,
+  isMainThread,
+} = require('worker_threads');
+const path = require('path');
+const os   = require('os');
+
+const { kitdef } = require('./kitx11');
+const {
+  Request, ByteOrder,
+  WindowClass, EventMask, EventType,
+  GCMask, GCFunction,
+  PropMode, PropFormat, Atom,
+  buildConnectionRequest,
+  buildCreateWindowRequest,
+  buildMapWindowRequest,
+  buildChangePropertyRequest,
+  buildInternAtomRequest,
+  buildQueryExtensionRequest,
+  parseQueryExtensionReply,
+  colorByName,
+} = kitdef;
+
+// ── Internal helpers ──────────────────────────────────────────
+
+/** Pad a byte length up to the next 4-byte boundary. */
+function pad4(n) { return (4 - (n % 4)) % 4; }
+
+/** Read a 32-bit unsigned int from a Uint8Array (host endian). */
+function u32(buf, off) {
+  const v = new DataView(buf.buffer, buf.byteOffset + off, 4);
+  return v.getUint32(0, kitdef.hostIsLittleEndian);
+}
+function u16(buf, off) {
+  const v = new DataView(buf.buffer, buf.byteOffset + off, 2);
+  return v.getUint16(0, kitdef.hostIsLittleEndian);
+}
+function u8(buf, off) { return buf[off]; }
+
+// ── SyncSocket ───────────────────────────────────────────────
+//
+// Wraps the socket worker with a fully synchronous read/write API.
+// Connect blocks via Atomics.wait on a SharedArrayBuffer signal.
+// Reads block via receiveMessageOnPort() on a per-request MessageChannel.
+
+class SyncSocket {
+  /**
+   * Synchronously create and connect a SyncSocket.
+   * Blocks the calling thread until the TCP/Unix connection is established.
+   * @param {string} display  e.g. ':0', 'hostname:1'
+   * @returns {SyncSocket}
+   */
+  static create(display) {
+    // SAB[0]: 0 = waiting, 1 = connected, 2 = error
+    const sab    = new SharedArrayBuffer(4);
+    const signal = new Int32Array(sab);
+
+    const worker = new Worker(path.join(__dirname, 'kitx11_worker.js'), {
+      workerData: { display, signalSab: sab },
+    });
+
+    // Block synchronously until the worker signals connect result
+    Atomics.wait(signal, 0, 0);
+
+    if (signal[0] === 2) {
+      // Worker posted an error message on parentPort before notifying
+      worker.terminate();
+      throw new Error(`X11 connection failed (DISPLAY=${display})`);
+    }
+
+    const sock    = Object.create(SyncSocket.prototype);
+    sock._worker  = worker;
+    return sock;
+  }
+
+  /** Write bytes WITHOUT transferring (buffer stays valid after call). */
+  writeCopy(uint8Array) {
+    const copy = uint8Array.slice();
+    this._worker.postMessage({ cmd: 'write', data: copy }, [copy.buffer]);
+  }
+
+  /** Synchronously read exactly n bytes. Blocks until available. */
+  read(n) {
+    const { port1, port2 } = new MessageChannel();
+    this._worker.postMessage({ cmd: 'read', n, port: port2 }, [port2]);
+    let msg;
+    // Spin on receiveMessageOnPort — this is the sync blocking point
+    do { msg = receiveMessageOnPort(port1); } while (!msg);
+    if (!msg.message.ok) throw new Error(`X11 read error: ${msg.message.error}`);
+    return msg.message.data; // Uint8Array
+  }
+
+  close() {
+    this._worker.postMessage({ cmd: 'close' });
+    this._worker.terminate();
+  }
+}
+
+// ── X11Connection ─────────────────────────────────────────────
+
+class X11Connection {
+  constructor(sock, info) {
+    this._sock        = sock;
+    this._seq         = 0;         // sequence number counter
+    this._xidBase     = info.resourceIdBase;
+    this._xidMask     = info.resourceIdMask;
+    this._xidNext     = 0;
+    this._rootWin     = info.rootWindow;
+    this._rootVisual  = info.rootVisual;
+    this._rootDepth   = info.rootDepth;
+    this._whitePixel  = info.whitePixel;
+    this._blackPixel  = info.blackPixel;
+    this._screen      = info;
+    this._writeQueue  = [];        // buffered packets for flush()
+    this._atoms       = {};        // intern cache name→id
+    this._extensions  = {};        // extension info cache
+  }
+
+  // ── Resource ID allocation ──────────────────────────────────
+  _newXid() {
+    const id = this._xidBase | (this._xidNext & this._xidMask);
+    this._xidNext++;
+    return id;
+  }
+
+  // ── Low-level I/O ───────────────────────────────────────────
+
+  /** Queue a packet for the next flush(). */
+  _queue(buf) {
+    this._writeQueue.push(buf);
+    this._seq++;
+  }
+
+  /** Send all queued packets to the server immediately. */
+  flush() {
+    for (const buf of this._writeQueue) {
+      this._sock.writeCopy(buf);
+    }
+    this._writeQueue = [];
+  }
+
+  /** Send one packet immediately (bypasses the queue). */
+  _send(buf) {
+    this._sock.writeCopy(buf);
+    this._seq++;
+  }
+
+  /**
+   * Send a request and synchronously read back the reply.
+   * X11 replies are at least 32 bytes; additional data is indicated
+   * by bytes 4-7 (length in 4-byte units beyond the first 32 bytes).
+   */
+  _roundTrip(buf) {
+    this.flush();           // flush any pending writes first
+    this._send(buf);
+    return this._readReply();
+  }
+
+  _readReply() {
+    const header = this._sock.read(32);
+    const type   = u8(header, 0);
+
+    if (type === 0) {
+      // Error reply
+      const code    = u8(header, 1);
+      const seq     = u16(header, 2);
+      const bad     = u32(header, 4);
+      const minorOp = u16(header, 8);
+      const majorOp = u8(header, 10);
+      throw new Error(
+        `X11 error ${code} (major=${majorOp} minor=${minorOp} bad_resource=0x${bad.toString(16)} seq=${seq})`
+      );
+    }
+
+    if (type === 1) {
+      // Normal reply
+      const extraWords = u32(header, 4);
+      if (extraWords > 0) {
+        const extra = this._sock.read(extraWords * 4);
+        const full  = new Uint8Array(32 + extra.length);
+        full.set(header, 0);
+        full.set(extra,  32);
+        return full;
+      }
+      return header;
+    }
+
+    // It's an event — push it aside and keep waiting for the reply
+    // (simplified: real client would queue events)
+    return this._readReply();
+  }
+
+  /** Read the next event from the server (blocks synchronously). */
+  nextEvent() {
+    this.flush();
+    const buf  = this._sock.read(32);
+    const type = u8(buf, 0) & 0x7F; // strip SendEvent bit
+    return this._parseEvent(type, buf);
+  }
+
+  _parseEvent(type, buf) {
+    const ev = { type, typeName: kitdef.EventTypeName[type] || `unknown(${type})` };
+
+    switch (type) {
+      case EventType.KEY_PRESS:
+      case EventType.KEY_RELEASE:
+        ev.detail    = u8(buf, 1);   // keycode
+        ev.time      = u32(buf, 4);
+        ev.root      = u32(buf, 8);
+        ev.event     = u32(buf, 12);
+        ev.child     = u32(buf, 16);
+        ev.rootX     = u16(buf, 20);
+        ev.rootY     = u16(buf, 22);
+        ev.eventX    = u16(buf, 24);
+        ev.eventY    = u16(buf, 26);
+        ev.state     = u16(buf, 28);
+        ev.keysym    = kitdef.keysymToChar(ev.detail) ?? ev.detail;
+        break;
+
+      case EventType.BUTTON_PRESS:
+      case EventType.BUTTON_RELEASE:
+        ev.button    = u8(buf, 1);
+        ev.time      = u32(buf, 4);
+        ev.event     = u32(buf, 12);
+        ev.eventX    = u16(buf, 24);
+        ev.eventY    = u16(buf, 26);
+        ev.state     = u16(buf, 28);
+        break;
+
+      case EventType.MOTION_NOTIFY:
+        ev.time      = u32(buf, 4);
+        ev.event     = u32(buf, 12);
+        ev.eventX    = u16(buf, 24);
+        ev.eventY    = u16(buf, 26);
+        ev.state     = u16(buf, 28);
+        break;
+
+      case EventType.EXPOSE:
+        ev.window    = u32(buf, 4);
+        ev.x         = u16(buf, 8);
+        ev.y         = u16(buf, 10);
+        ev.width     = u16(buf, 12);
+        ev.height    = u16(buf, 14);
+        ev.count     = u16(buf, 16);
+        break;
+
+      case EventType.CONFIGURE_NOTIFY:
+        ev.window    = u32(buf, 4);
+        ev.x         = u16(buf, 16);
+        ev.y         = u16(buf, 18);
+        ev.width     = u16(buf, 20);
+        ev.height    = u16(buf, 22);
+        break;
+
+      case EventType.DESTROY_NOTIFY:
+        ev.window    = u32(buf, 8);
+        break;
+
+      case EventType.CLIENT_MESSAGE:
+        ev.window    = u32(buf, 4);
+        ev.type      = u32(buf, 8);
+        ev.data      = buf.slice(12, 32);
+        break;
+
+      default:
+        ev.raw = buf;
+        break;
+    }
+    return ev;
+  }
+
+  // ── Atom interning ──────────────────────────────────────────
+
+  /** Synchronously intern an atom name, with local cache. */
+  internAtom(name, onlyIfExists = false) {
+    if (this._atoms[name] !== undefined) return this._atoms[name];
+    const reply = this._roundTrip(buildInternAtomRequest(name, onlyIfExists));
+    const id    = u32(reply, 8);
+    this._atoms[name] = id;
+    return id;
+  }
+
+  // ── Color resolution ────────────────────────────────────────
+
+  /**
+   * Resolve a color to a pixel value.
+   * Accepts:
+   *   - An X11 named color string  ('cornflowerblue')
+   *   - '#RRGGBB' hex string
+   *   - A pixel integer directly
+   */
+  color(spec) {
+    if (typeof spec === 'number') return spec;
+
+    const rgb = colorByName(spec) || kitdef.parseColor(spec);
+    if (!rgb) throw new Error(`Unknown color: ${spec}`);
+
+    const r = Array.isArray(rgb) ? rgb[0] : rgb.r;
+    const g = Array.isArray(rgb) ? rgb[1] : rgb.g;
+    const b = Array.isArray(rgb) ? rgb[2] : rgb.b;
+
+    // AllocColor request (opcode 84)
+    const colormapId = this._screen.defaultColormap;
+    const buf = new Uint8Array(16);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, 84); // ALLOC_COLOR
+    v.setUint8(1, 0);
+    v.setUint16(2, 4, le);
+    v.setUint32(4, colormapId, le);
+    v.setUint16(8,  r * 257, le); // 8-bit → 16-bit
+    v.setUint16(10, g * 257, le);
+    v.setUint16(12, b * 257, le);
+    v.setUint16(14, 0, le);
+    const reply = this._roundTrip(buf);
+    return u32(reply, 16); // pixel
+  }
+
+  // ── Window management ───────────────────────────────────────
+
+  /**
+   * Create a top-level window.
+   * @param {object} opts
+   * @param {number} [opts.x=0]
+   * @param {number} [opts.y=0]
+   * @param {number} [opts.width=400]
+   * @param {number} [opts.height=300]
+   * @param {string|number} [opts.background='white']
+   * @param {string} [opts.title]
+   * @param {number} [opts.eventMask]  defaults to common events
+   * @returns {number} window XID
+   */
+  createWindow(opts = {}) {
+    const {
+      x = 0, y = 0,
+      width = 400, height = 300,
+      background = 'white',
+      title,
+      eventMask = (
+        EventMask.EXPOSURE_MASK        |
+        EventMask.KEY_PRESS_MASK       |
+        EventMask.BUTTON_PRESS_MASK    |
+        EventMask.BUTTON_RELEASE_MASK  |
+        EventMask.POINTER_MOTION_MASK  |
+        EventMask.STRUCTURE_NOTIFY_MASK
+      ),
+    } = opts;
+
+    const wid   = this._newXid();
+    const bgPix = this.color(background);
+
+    const values    = [bgPix, eventMask];
+    const valueMask = kitdef.CW.BACK_PIXEL | kitdef.CW.EVENT_MASK;
+
+    const req = buildCreateWindowRequest({
+      wid, parent: this._rootWin,
+      x, y, width, height,
+      borderWidth: 0,
+      windowClass: WindowClass.INPUT_OUTPUT,
+      visual: 0,            // CopyFromParent
+      valueMask,
+      values,
+    });
+    this._queue(req);
+
+    if (title) this.setTitle(wid, title);
+
+    // Register WM_DELETE_WINDOW protocol so close button works
+    this._setupWMDelete(wid);
+
+    return wid;
+  }
+
+  _setupWMDelete(wid) {
+    const wmProto   = this.internAtom('WM_PROTOCOLS');
+    const wmDelete  = this.internAtom('WM_DELETE_WINDOW');
+    this._queue(buildChangePropertyRequest({
+      wid,
+      mode:     PropMode.REPLACE,
+      property: wmProto,
+      type:     Atom.ATOM,
+      format:   32,
+      data:     [wmDelete],
+    }));
+  }
+
+  /** Map (show) a window. */
+  mapWindow(wid) {
+    this._queue(buildMapWindowRequest(wid));
+  }
+
+  /** Unmap (hide) a window. */
+  unmapWindow(wid) {
+    const buf = new Uint8Array(8);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.UNMAP_WINDOW);
+    v.setUint8(1, 0);
+    v.setUint16(2, 2, le);
+    v.setUint32(4, wid, le);
+    this._queue(buf);
+  }
+
+  /** Destroy a window and free its resources. */
+  destroyWindow(wid) {
+    const buf = new Uint8Array(8);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.DESTROY_WINDOW);
+    v.setUint8(1, 0);
+    v.setUint16(2, 2, le);
+    v.setUint32(4, wid, le);
+    this._queue(buf);
+  }
+
+  /** Set a window's title (_NET_WM_NAME + WM_NAME). */
+  setTitle(wid, title) {
+    const enc  = new TextEncoder().encode(title);
+    const data = Array.from(enc);
+    // WM_NAME (legacy, Latin-1)
+    this._queue(buildChangePropertyRequest({
+      wid, mode: PropMode.REPLACE,
+      property: Atom.WM_NAME, type: Atom.STRING, format: 8, data,
+    }));
+    // _NET_WM_NAME (modern, UTF-8)
+    const netName   = this.internAtom('_NET_WM_NAME');
+    const utf8Atom  = this.internAtom('UTF8_STRING');
+    this._queue(buildChangePropertyRequest({
+      wid, mode: PropMode.REPLACE,
+      property: netName, type: utf8Atom, format: 8, data,
+    }));
+  }
+
+  /** Move and/or resize a window. */
+  configureWindow(wid, opts = {}) {
+    const fields = { x:1, y:2, width:4, height:8, borderWidth:16, sibling:32, stackMode:64 };
+    let mask = 0;
+    const values = [];
+    for (const [key, bit] of Object.entries(fields)) {
+      if (opts[key] !== undefined) { mask |= bit; values.push(opts[key]); }
+    }
+    const len = 3 + values.length;
+    const buf = new Uint8Array(len * 4);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.CONFIGURE_WINDOW);
+    v.setUint8(1, 0);
+    v.setUint16(2, len, le);
+    v.setUint32(4, wid, le);
+    v.setUint16(8, mask, le);
+    values.forEach((val, i) => v.setUint32(12 + i*4, val, le));
+    this._queue(buf);
+  }
+
+  // ── Graphics Context ────────────────────────────────────────
+
+  /**
+   * Create a Graphics Context.
+   * @param {number} drawable  window or pixmap XID
+   * @param {object} opts
+   * @param {string|number} [opts.foreground='black']
+   * @param {string|number} [opts.background='white']
+   * @param {number} [opts.lineWidth=1]
+   * @param {number} [opts.function]  GCFunction value
+   * @returns {number} GC XID
+   */
+  createGC(drawable, opts = {}) {
+    const gcid = this._newXid();
+    const le   = kitdef.hostIsLittleEndian;
+
+    const fg = this.color(opts.foreground ?? 'black');
+    const bg = this.color(opts.background ?? 'white');
+
+    let mask = GCMask.FOREGROUND | GCMask.BACKGROUND;
+    const values = [fg, bg];
+
+    if (opts.lineWidth !== undefined) {
+      mask |= GCMask.LINE_WIDTH; values.push(opts.lineWidth);
+    }
+    if (opts.function !== undefined) {
+      mask |= GCMask.FUNCTION; values.push(opts.function);
+    }
+    if (opts.lineStyle !== undefined) {
+      mask |= GCMask.LINE_STYLE; values.push(opts.lineStyle);
+    }
+    if (opts.fillStyle !== undefined) {
+      mask |= GCMask.FILL_STYLE; values.push(opts.fillStyle);
+    }
+    if (opts.graphicsExposures !== undefined) {
+      mask |= GCMask.GRAPHICS_EXPOSURES; values.push(opts.graphicsExposures ? 1 : 0);
+    }
+
+    const len = 4 + values.length;
+    const buf = new Uint8Array(len * 4);
+    const v   = new DataView(buf.buffer);
+    v.setUint8(0, Request.CREATE_GC);
+    v.setUint8(1, 0);
+    v.setUint16(2, len, le);
+    v.setUint32(4, gcid, le);
+    v.setUint32(8, drawable, le);
+    v.setUint32(12, mask, le);
+    values.forEach((val, i) => v.setUint32(16 + i*4, val, le));
+    this._queue(buf);
+    return gcid;
+  }
+
+  /** Change attributes of an existing GC. */
+  changeGC(gcid, opts = {}) {
+    const le = kitdef.hostIsLittleEndian;
+    let mask = 0;
+    const values = [];
+    const add = (flag, val) => { mask |= flag; values.push(val); };
+
+    if (opts.foreground !== undefined) add(GCMask.FOREGROUND,  this.color(opts.foreground));
+    if (opts.background !== undefined) add(GCMask.BACKGROUND,  this.color(opts.background));
+    if (opts.lineWidth  !== undefined) add(GCMask.LINE_WIDTH,  opts.lineWidth);
+    if (opts.function   !== undefined) add(GCMask.FUNCTION,    opts.function);
+    if (opts.lineStyle  !== undefined) add(GCMask.LINE_STYLE,  opts.lineStyle);
+    if (opts.fillStyle  !== undefined) add(GCMask.FILL_STYLE,  opts.fillStyle);
+
+    if (!values.length) return;
+    const len = 3 + values.length;
+    const buf = new Uint8Array(len * 4);
+    const v   = new DataView(buf.buffer);
+    v.setUint8(0, Request.CHANGE_GC);
+    v.setUint8(1, 0);
+    v.setUint16(2, len, le);
+    v.setUint32(4, gcid, le);
+    v.setUint32(8, mask, le);
+    values.forEach((val, i) => v.setUint32(12 + i*4, val, le));
+    this._queue(buf);
+  }
+
+  /** Free a GC. */
+  freeGC(gcid) {
+    const buf = new Uint8Array(8);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.FREE_GC);
+    v.setUint8(1, 0);
+    v.setUint16(2, 2, le);
+    v.setUint32(4, gcid, le);
+    this._queue(buf);
+  }
+
+  // ── Drawing primitives ──────────────────────────────────────
+
+  /** Fill a rectangle with the GC's foreground color. */
+  fillRect(drawable, gc, x, y, width, height) {
+    const buf = new Uint8Array(20);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.POLY_FILL_RECTANGLE);
+    v.setUint8(1, 0);
+    v.setUint16(2, 5, le);
+    v.setUint32(4, drawable, le);
+    v.setUint32(8, gc, le);
+    v.setInt16(12, x, le);
+    v.setInt16(14, y, le);
+    v.setUint16(16, width, le);
+    v.setUint16(18, height, le);
+    this._queue(buf);
+  }
+
+  /** Draw a rectangle outline. */
+  drawRect(drawable, gc, x, y, width, height) {
+    const buf = new Uint8Array(20);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.POLY_RECTANGLE);
+    v.setUint8(1, 0);
+    v.setUint16(2, 5, le);
+    v.setUint32(4, drawable, le);
+    v.setUint32(8, gc, le);
+    v.setInt16(12, x, le);
+    v.setInt16(14, y, le);
+    v.setUint16(16, width, le);
+    v.setUint16(18, height, le);
+    this._queue(buf);
+  }
+
+  /** Draw a line. */
+  drawLine(drawable, gc, x1, y1, x2, y2) {
+    const buf = new Uint8Array(20);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.POLY_LINE);
+    v.setUint8(1, 1); // CoordModeOrigin
+    v.setUint16(2, 5, le);
+    v.setUint32(4, drawable, le);
+    v.setUint32(8, gc, le);
+    v.setInt16(12, x1, le);
+    v.setInt16(14, y1, le);
+    v.setInt16(16, x2, le);
+    v.setInt16(18, y2, le);
+    this._queue(buf);
+  }
+
+  /** Draw a filled polygon. points = [{x,y}, ...] */
+  fillPoly(drawable, gc, points) {
+    const nPts  = points.length;
+    const len   = 4 + nPts;          // 4 header words + 1 word per point
+    const buf   = new Uint8Array(len * 4);
+    const v     = new DataView(buf.buffer);
+    const le    = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.FILL_POLY);
+    v.setUint8(1, 0);               // Complex shape
+    v.setUint16(2, len, le);
+    v.setUint32(4, drawable, le);
+    v.setUint32(8, gc, le);
+    v.setUint8(12, 0);              // shape: Complex
+    v.setUint8(13, 0);              // CoordModeOrigin
+    points.forEach(({ x, y }, i) => {
+      v.setInt16(16 + i*4, x, le);
+      v.setInt16(18 + i*4, y, le);
+    });
+    this._queue(buf);
+  }
+
+  /** Draw a filled arc (ellipse/circle segment). */
+  fillArc(drawable, gc, x, y, width, height, angle1 = 0, angle2 = 360 * 64) {
+    const buf = new Uint8Array(24);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.POLY_FILL_ARC);
+    v.setUint8(1, 0);
+    v.setUint16(2, 6, le);
+    v.setUint32(4, drawable, le);
+    v.setUint32(8, gc, le);
+    v.setInt16(12, x, le);
+    v.setInt16(14, y, le);
+    v.setUint16(16, width, le);
+    v.setUint16(18, height, le);
+    v.setInt16(20, angle1, le);
+    v.setInt16(22, angle2, le);
+    this._queue(buf);
+  }
+
+  /** Draw an arc outline. */
+  drawArc(drawable, gc, x, y, width, height, angle1 = 0, angle2 = 360 * 64) {
+    const buf = new Uint8Array(24);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.POLY_ARC);
+    v.setUint8(1, 0);
+    v.setUint16(2, 6, le);
+    v.setUint32(4, drawable, le);
+    v.setUint32(8, gc, le);
+    v.setInt16(12, x, le);
+    v.setInt16(14, y, le);
+    v.setUint16(16, width, le);
+    v.setUint16(18, height, le);
+    v.setInt16(20, angle1, le);
+    v.setInt16(22, angle2, le);
+    this._queue(buf);
+  }
+
+  /** Draw points. points = [{x,y}, ...] */
+  drawPoints(drawable, gc, points) {
+    const len = 3 + points.length;
+    const buf = new Uint8Array(len * 4);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.POLY_POINT);
+    v.setUint8(1, 0); // CoordModeOrigin
+    v.setUint16(2, len, le);
+    v.setUint32(4, drawable, le);
+    v.setUint32(8, gc, le);
+    points.forEach(({ x, y }, i) => {
+      v.setInt16(12 + i*4, x, le);
+      v.setInt16(14 + i*4, y, le);
+    });
+    this._queue(buf);
+  }
+
+  /**
+   * Draw text using X11's core (bitmap) fonts.
+   * For scalable fonts, use the RENDER extension instead.
+   */
+  drawText(drawable, gc, x, y, text) {
+    const enc = new TextEncoder().encode(text);
+    if (enc.length > 255) throw new Error('drawText: text too long (max 255 bytes; split it up)');
+    const itemLen  = 2 + enc.length;
+    const itemPad  = pad4(itemLen);
+    const len      = 4 + Math.ceil((itemLen + itemPad) / 4);
+    const buf      = new Uint8Array(len * 4);
+    const v        = new DataView(buf.buffer);
+    const le       = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.IMAGE_TEXT_8);
+    v.setUint8(1, enc.length);       // string length
+    v.setUint16(2, len, le);
+    v.setUint32(4, drawable, le);
+    v.setUint32(8, gc, le);
+    v.setInt16(12, x, le);
+    v.setInt16(14, y, le);
+    buf.set(enc, 16);
+    this._queue(buf);
+  }
+
+  /** Load a named X11 core font and return its font XID. */
+  loadFont(name) {
+    const fid = this._newXid();
+    const enc = new TextEncoder().encode(name);
+    const pad = pad4(enc.length);
+    const len = 3 + Math.ceil((enc.length + pad) / 4);
+    const buf = new Uint8Array(len * 4);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.OPEN_FONT);
+    v.setUint8(1, 0);
+    v.setUint16(2, len, le);
+    v.setUint32(4, fid, le);
+    v.setUint16(8, enc.length, le);
+    buf.set(enc, 12);
+    this._queue(buf);
+    return fid;
+  }
+
+  /** Assign a font to a GC. */
+  setFont(gcid, fontId) {
+    this.changeGC(gcid, {}); // no-op flush guard
+    const buf = new Uint8Array(16);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.CHANGE_GC);
+    v.setUint8(1, 0);
+    v.setUint16(2, 4, le);
+    v.setUint32(4, gcid, le);
+    v.setUint32(8, GCMask.FONT, le);
+    v.setUint32(12, fontId, le);
+    this._queue(buf);
+  }
+
+  /** Clear the entire window to its background. */
+  clearWindow(wid) {
+    const buf = new Uint8Array(16);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.CLEAR_AREA);
+    v.setUint8(1, 0); // exposures = false
+    v.setUint16(2, 4, le);
+    v.setUint32(4, wid, le);
+    // x=0, y=0, w=0, h=0 means entire window
+    v.setInt16(8,  0, le); v.setInt16(10, 0, le);
+    v.setUint16(12, 0, le); v.setUint16(14, 0, le);
+    this._queue(buf);
+  }
+
+  /** Copy a rectangle from one drawable to another (BitBlt). */
+  copyArea(src, dst, gc, srcX, srcY, dstX, dstY, width, height) {
+    const buf = new Uint8Array(28);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.COPY_AREA);
+    v.setUint8(1, 0);
+    v.setUint16(2, 7, le);
+    v.setUint32(4, src, le);
+    v.setUint32(8, dst, le);
+    v.setUint32(12, gc, le);
+    v.setInt16(16, srcX, le); v.setInt16(18, srcY, le);
+    v.setInt16(20, dstX, le); v.setInt16(22, dstY, le);
+    v.setUint16(24, width, le); v.setUint16(26, height, le);
+    this._queue(buf);
+  }
+
+  // ── Pixmap (off-screen buffer) ──────────────────────────────
+
+  /** Create an off-screen pixmap (for double-buffering etc.) */
+  createPixmap(drawable, width, height, depth = this._rootDepth) {
+    const pid = this._newXid();
+    const buf = new Uint8Array(16);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.CREATE_PIXMAP);
+    v.setUint8(1, depth);
+    v.setUint16(2, 4, le);
+    v.setUint32(4, pid, le);
+    v.setUint32(8, drawable, le);
+    v.setUint16(12, width, le);
+    v.setUint16(14, height, le);
+    this._queue(buf);
+    return pid;
+  }
+
+  /** Free a pixmap. */
+  freePixmap(pid) {
+    const buf = new Uint8Array(8);
+    const v   = new DataView(buf.buffer);
+    const le  = kitdef.hostIsLittleEndian;
+    v.setUint8(0, Request.FREE_PIXMAP);
+    v.setUint8(1, 0);
+    v.setUint16(2, 2, le);
+    v.setUint32(4, pid, le);
+    this._queue(buf);
+  }
+
+  // ── Extension probe ─────────────────────────────────────────
+
+  /** Synchronously query whether an extension is present. */
+  queryExtension(name) {
+    if (this._extensions[name] !== undefined) return this._extensions[name];
+    const reply  = this._roundTrip(buildQueryExtensionRequest(name));
+    const result = parseQueryExtensionReply(reply);
+    this._extensions[name] = result;
+    return result;
+  }
+
+  // ── Convenience ─────────────────────────────────────────────
+
+  /** Expose screen/root info. */
+  get root()       { return this._rootWin; }
+  get rootDepth()  { return this._rootDepth; }
+  get rootVisual() { return this._rootVisual; }
+  get whitePixel() { return this._whitePixel; }
+  get blackPixel() { return this._blackPixel; }
+
+  /** Disconnect from the X server. */
+  close() { this._sock.close(); }
+}
+
+// ── Connection setup (parse server greeting) ──────────────────
+
+function _parseSetupReply(sock, authName, authData) {
+  const req = buildConnectionRequest({ authName, authData });
+  sock.writeCopy(req);
+
+  // Read fixed 8-byte header first
+  const hdr    = sock.read(8);
+  const status = u8(hdr, 0);
+
+  if (status === 0) {
+    // Failed
+    const reasonLen = u8(hdr, 1);
+    const extra     = sock.read(Math.ceil((u16(hdr, 6) * 4)));
+    const reason    = new TextDecoder().decode(extra.slice(0, reasonLen));
+    throw new Error(`X11 connection refused: ${reason}`);
+  }
+  if (status === 2) {
+    // Authenticate — we don't support SASL etc.
+    throw new Error('X11 server requires additional authentication');
+  }
+
+  // Status 1 = success. Read the rest.
+  const additionalWords = u16(hdr, 6);
+  const rest = sock.read(additionalWords * 4);
+
+  // Parse screen info from the greeting
+  // Offsets are relative to `rest` (the 8-byte header is already consumed)
+  const le = kitdef.hostIsLittleEndian;
+  const dv = new DataView(rest.buffer, rest.byteOffset, rest.byteLength);
+
+  const releaseNum     = dv.getUint32(0,  le);
+  const resourceIdBase = dv.getUint32(4,  le);
+  const resourceIdMask = dv.getUint32(8,  le);
+  const imageByteOrder = u8(rest, 30);
+  const bitmapBitOrder = u8(rest, 31);
+
+  const vendorLen      = dv.getUint16(16, le);
+  const numFormats     = u8(rest, 21);
+  // Skip vendor + formats to get to screen list
+  const vendorPad      = pad4(vendorLen);
+  let off              = 32 + vendorLen + vendorPad + numFormats * 8; // FORMAT is 8 bytes each
+
+  // Screen structure
+  const rootWindow     = dv.getUint32(off,      le); off += 4;
+  const defaultColormap= dv.getUint32(off,      le); off += 4;
+  const whitePixel     = dv.getUint32(off,      le); off += 4;
+  const blackPixel     = dv.getUint32(off,      le); off += 4;
+  const currentInput   = dv.getUint32(off,      le); off += 4;
+  const widthPixels    = dv.getUint16(off,      le); off += 2;
+  const heightPixels   = dv.getUint16(off,      le); off += 2;
+  off += 4; // width/height in mm
+  off += 4; // min/max installed maps
+  const rootVisual     = dv.getUint32(off,      le); off += 4;
+  const backingStores  = u8(rest, off);              off += 1;
+  const saveUnders     = u8(rest, off);              off += 1;
+  const rootDepth      = u8(rest, off);              off += 1;
+  const numDepths      = u8(rest, off);              off += 1;
+
+  return {
+    releaseNum, resourceIdBase, resourceIdMask,
+    rootWindow, defaultColormap, whitePixel, blackPixel,
+    rootVisual, rootDepth, widthPixels, heightPixels,
+    imageByteOrder, bitmapBitOrder,
+  };
+}
+
+// ── Public API ────────────────────────────────────────────────
+
+/**
+ * Synchronously connect to an X11 server.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.display]     Defaults to $DISPLAY
+ * @param {string} [opts.authName]    e.g. 'MIT-MAGIC-COOKIE-1'
+ * @param {Uint8Array} [opts.authData]  Raw cookie bytes
+ * @returns {X11Connection}
+ *
+ * @example
+ * const X11  = require('./kitx11_conn');
+ * const conn = X11.connect();
+ * const win  = conn.createWindow({ width: 640, height: 480, title: 'Hello' });
+ * const gc   = conn.createGC(win, { foreground: 'cornflowerblue' });
+ * conn.mapWindow(win);
+ * conn.flush();
+ *
+ * // Event loop
+ * while (true) {
+ *   const ev = conn.nextEvent();
+ *   if (ev.typeName === 'EXPOSE') {
+ *     conn.fillRect(win, gc, 0, 0, 640, 480);
+ *     conn.drawText(win, gc, 50, 50, 'Hello X11!');
+ *     conn.flush();
+ *   }
+ *   if (ev.typeName === 'CLIENT_MESSAGE') break; // WM close
+ * }
+ * conn.close();
+ */
+function connect(opts = {}) {
+  const display  = opts.display || process.env.DISPLAY || ':0';
+  const authName = opts.authName  ?? '';
+  const authData = opts.authData  ?? new Uint8Array(0);
+
+  const sock = SyncSocket.create(display);
+  const info = _parseSetupReply(sock, authName, authData);
+  return new X11Connection(sock, info);
+}
+
+module.exports = { connect, X11Connection, kitdef };