flea-qml 0.0.0-stage → 0.2.0

package/src/watch.js

@@ -0,0 +1,98 @@
+// The `changed` line: a watched directory changed under another program (docs/protocol.md
+// "changed"). Upstream uses inotify directly; node:fs watch is inotify on Linux and
+// ReadDirectoryChangesW on Windows, so one module serves every platform.
+//
+// Two sets, as upstream keeps them apart: the listed directory, and the columns' directories a
+// watching `peek` names in `keep`. A burst is one line: after a line, a directory waits 100 ms
+// before it can send another.
+import { watch } from "node:fs";
+import { resolve } from "node:path";
+
+const QUIET = 100,
+  COLUMN_GUARD = 8;
+
+let send = () => {};
+export function onChanged(sender) {
+  send = sender;
+}
+
+function arm(path) {
+  let timer = null,
+    pending = false;
+  const fire = () => {
+    if (timer) {
+      pending = true;
+      return;
+    }
+    send({ t: "changed", path });
+    timer = setTimeout(() => {
+      timer = null;
+      if (pending) {
+        pending = false;
+        fire();
+      }
+    }, QUIET);
+    timer.unref?.();
+  };
+  let watcher;
+  try {
+    watcher = watch(path || ".", { persistent: false }, fire);
+  } catch (e) {
+    console.error(`flea-qml backend: cannot watch ${path}: ${e.message}`);
+    return null;
+  }
+  // A watched directory deleted or unmounted ends its watch after its last line.
+  watcher.on("error", () => {
+    fire();
+    watcher.close();
+  });
+  return {
+    close() {
+      clearTimeout(timer);
+      watcher.close();
+    },
+  };
+}
+
+// ---- the listed directory ----
+
+let listed = null;
+
+// Armed before the read, beside the current watch, so a change during the read is reported and a
+// failed list leaves the old watch standing. Returns what `listDone` or `listFailed` settles.
+export function watchList(path) {
+  return { path, watch: listed && resolve(listed.path || ".") === resolve(path || ".") ? null : arm(path) };
+}
+export function listDone(armed) {
+  if (!armed.watch) return;
+  listed?.watch.close();
+  listed = armed;
+}
+export function listFailed(armed) {
+  armed.watch?.close();
+}
+
+// ---- the columns ----
+
+const columns = new Map();
+
+export function watchColumn(path, keep) {
+  const kept = new Set((Array.isArray(keep) ? keep : [path]).map((p) => resolve(String(p))));
+  kept.add(resolve(path));
+  for (const [key, watcher] of columns)
+    if (!kept.has(key)) {
+      watcher.close();
+      columns.delete(key);
+    }
+  const key = resolve(path);
+  if (!columns.has(key)) {
+    const watcher = arm(path);
+    if (watcher) columns.set(key, watcher);
+  }
+  // A client that sends no keep keeps at most eight, the oldest dropped first.
+  while (columns.size > COLUMN_GUARD) {
+    const [oldest, watcher] = columns.entries().next().value;
+    watcher.close();
+    columns.delete(oldest);
+  }
+}

package/src/wayland/client.js

@@ -0,0 +1,109 @@
+// A windowless Wayland client: the display, the registry and round trips, nothing to draw.
+// Adapted from buninu-browser frontends/wayland/client.js (MIT, Dr. John), without the
+// compositor, shm and xdg_wm_base binds a window needs; the clipboard binds what it uses.
+import { discoverSocket } from "./socket-discovery.js";
+import { connectUnix } from "./transport.js";
+import { interfaces, decode, encodeRequest } from "./protocol.js";
+
+export class WaylandClient {
+  constructor(path) {
+    this.socketPath = path;
+    this.objects = new Map();
+    this.nextId = 2;
+    this.globals = new Map();
+    this.waiters = new Set();
+    this.closed = false;
+    this.objects.set(1, {
+      iface: "wl_display",
+      event: (name, args) => {
+        if (name === "error") throw Error(`Wayland error ${args.join(": ")}`);
+        if (name === "delete_id") this.objects.delete(args[0]);
+      },
+    });
+  }
+  object(iface, event = () => {}) {
+    const id = this.nextId++;
+    this.objects.set(id, { iface, event });
+    return id;
+  }
+  request(id, name, ...args) {
+    const object = this.objects.get(id);
+    if (!object) throw Error(`Unknown object ${id}`);
+    const packet = encodeRequest(id, object.iface, name, args);
+    this.connection.send(packet.data, packet.fds);
+    this.connection.flush();
+  }
+  receive() {
+    const c = this.connection;
+    while (!c.closed && c.input.length >= 8) {
+      const id = c.input.readUInt32LE(0),
+        header = c.input.readUInt32LE(4),
+        size = header >>> 16,
+        opcode = header & 65535;
+      if (size < 8 || size % 4) throw Error("Invalid event size");
+      if (c.input.length < size) return;
+      const object = this.objects.get(id),
+        spec = interfaces.get(object?.iface)?.events[opcode];
+      if (!spec) throw Error(`Unknown event ${id}:${opcode}`);
+      const args = decode(spec, c.input.subarray(0, size), c.fds);
+      if (args === null) return;
+      c.input = c.input.subarray(size);
+      object.event(spec.name, args);
+    }
+  }
+  sync() {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.waiters.delete(fail);
+        reject(Error("Wayland roundtrip timeout"));
+      }, 5000);
+      const fail = (e) => {
+        clearTimeout(timer);
+        reject(e);
+      };
+      this.waiters.add(fail);
+      const id = this.object("wl_callback", () => {
+        clearTimeout(timer);
+        this.waiters.delete(fail);
+        resolve();
+      });
+      this.request(1, "sync", id);
+    });
+  }
+  async initialize() {
+    this.connection = await discoverSocket(connectUnix, this.socketPath);
+    if (this.closed) {
+      this.connection.close();
+      throw Error("Wayland client closed");
+    }
+    this.connection.onData = () => this.receive();
+    this.connection.onClose = () => {
+      clearInterval(this.timer);
+      this.closed = true;
+      for (const reject of this.waiters) reject(this.connection.error ?? Error("Wayland disconnected"));
+      this.waiters.clear();
+      this.onClose?.();
+    };
+    // Polled, as buninu-browser does; unref'd so the connection alone never keeps the backend alive.
+    this.timer = setInterval(() => this.connection.poll(), 8);
+    this.timer.unref?.();
+    this.registry = this.object("wl_registry", (event, [name, iface, version]) => {
+      if (event === "global") this.globals.set(iface, { name, version });
+      else for (const [key, value] of this.globals) if (value.name === name) this.globals.delete(key);
+    });
+    this.request(1, "get_registry", this.registry);
+    await this.sync();
+    return this;
+  }
+  bind(iface, version, event) {
+    const global = this.globals.get(iface);
+    if (!global) throw Error(`Compositor lacks ${iface}`);
+    const id = this.object(iface, event);
+    this.request(this.registry, "bind", global.name, iface, Math.min(version, global.version), id);
+    return id;
+  }
+  close() {
+    this.closed = true;
+    this.connection?.close();
+  }
+}

package/src/wayland/protocol.js

@@ -0,0 +1,55 @@
+// Adapted from buninu-browser frontends/wayland@7fe8cc3, itself from buninu-land (MIT, Dr. John); XML files unchanged.
+// Interpret upstream XML with Bun's built-in parser at runtime; no generated bindings.
+import { readFileSync } from 'node:fs';
+const list = value => value == null ? [] : Array.isArray(value) ? value : [value];
+const attrs = node => Object.fromEntries(Object.entries(node).filter(([k]) => k.startsWith('@')).map(([k,v]) => [k.slice(1), v]));
+export const interfaces = new Map();
+for (const file of ['wayland', 'ext-data-control-v1', 'wlr-data-control-unstable-v1']) {
+  const xml = Bun.XML.parse(readFileSync(new URL(`./protocols/${file}.xml`, import.meta.url), 'utf8'));
+  for (const node of list(xml.protocol.interface)) {
+    const spec = { ...attrs(node) };
+    for (const [tag, key] of [['request', 'requests'], ['event', 'events']])
+      spec[key] = list(node[tag]).map(message => ({ ...attrs(message), args: list(message.arg).map(attrs) }));
+    interfaces.set(spec.name, spec);
+  }
+}
+export function decode(spec, bytes, fds) {
+  let offset = 8, fdOffset = 0;
+  const values = [];
+  const word = () => { if (offset + 4 > bytes.length) throw Error('Truncated argument'); const v = bytes.readUInt32LE(offset); offset += 4; return v; };
+  for (const arg of spec.args) {
+    if (arg.type === 'fd') { if (fdOffset === fds.length) return null; values.push(fds[fdOffset++]); continue; }
+    if (arg.type === 'new_id' && !arg.interface) {
+      const n = word(); if (!n || offset + n > bytes.length || bytes[offset + n - 1]) throw Error('Invalid interface string');
+      values.push(bytes.toString('utf8', offset, offset + n - 1)); offset += (n + 3) & ~3;
+      values.push(word(), word()); continue;
+    }
+    const v = word();
+    if (arg.type === 'string' || arg.type === 'array') {
+      if (offset + v > bytes.length) throw Error('Truncated array/string');
+      if (arg.type === 'string' && v && bytes[offset + v - 1]) throw Error('Unterminated string');
+      values.push(arg.type === 'string' ? (v ? bytes.toString('utf8', offset, offset + v - 1) : null) : bytes.subarray(offset, offset + v));
+      offset += (v + 3) & ~3;
+    } else values.push(arg.type === 'fixed' ? (v | 0) / 256 : arg.type === 'int' ? v | 0 : v);
+  }
+  if (offset !== bytes.length) throw Error('Invalid message size');
+  fds.splice(0, fdOffset);
+  return values;
+}
+export function encodeRequest(id, iface, name, values) {
+  const requests=interfaces.get(iface).requests, opcode=requests.findIndex(e=>e.name===name);
+  if(opcode<0)throw Error(`Unknown request ${iface}.${name}`);
+  const parts=[Buffer.alloc(8)],fds=[];
+  const word=v=>{const b=Buffer.alloc(4);b.writeUInt32LE(Number(v)>>>0);parts.push(b);};
+  const bytes=(value,string)=>{const b=string?Buffer.from(value==null?'':value+'\0'):Buffer.from(value);const p=Buffer.alloc(4+((b.length+3)&~3));p.writeUInt32LE(b.length);b.copy(p,4);parts.push(p);};
+  let i=0;
+  for(const arg of requests[opcode].args){
+    const v=values[i++];
+    if(arg.type==='fd'){fds.push(v);continue;}
+    if(arg.type==='new_id'&&!arg.interface){bytes(v,true);word(values[i++]);word(values[i++]);}
+    else if(arg.type==='string'||arg.type==='array')bytes(v,arg.type==='string');
+    else word(arg.type==='fixed'?Math.round(v*256):v);
+  }
+  const data=Buffer.concat(parts);if(data.length>65535)throw Error('Wayland message too large');
+  data.writeUInt32LE(id);data.writeUInt32LE((data.length<<16)|opcode,4);return {data,fds};
+}

package/src/wayland/protocols/ext-data-control-v1.xml

@@ -0,0 +1,276 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_data_control_v1">
+  <copyright>
+    Copyright © 2018 Simon Ser
+    Copyright © 2019 Ivan Molodetskikh
+    Copyright © 2024 Neal Gompa
+
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation for any purpose is hereby granted
+    without fee, provided that the above copyright notice appear in
+    all copies and that both that copyright notice and this permission
+    notice appear in supporting documentation, and that the name of
+    the copyright holders not be used in advertising or publicity
+    pertaining to distribution of the software without specific,
+    written prior permission.  The copyright holders make no
+    representations about the suitability of this software for any
+    purpose.  It is provided "as is" without express or implied
+    warranty.
+
+    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+    THIS SOFTWARE.
+  </copyright>
+
+  <description summary="control data devices">
+    This protocol allows a privileged client to control data devices. In
+    particular, the client will be able to manage the current selection and take
+    the role of a clipboard manager.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="ext_data_control_manager_v1" version="1">
+    <description summary="manager to control data devices">
+      This interface is a manager that allows creating per-seat data device
+      controls.
+    </description>
+
+    <request name="create_data_source">
+      <description summary="create a new data source">
+        Create a new data source.
+      </description>
+      <arg name="id" type="new_id" interface="ext_data_control_source_v1"
+        summary="data source to create"/>
+    </request>
+
+    <request name="get_data_device">
+      <description summary="get a data device for a seat">
+        Create a data device that can be used to manage a seat's selection.
+      </description>
+      <arg name="id" type="new_id" interface="ext_data_control_device_v1"/>
+      <arg name="seat" type="object" interface="wl_seat"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        All objects created by the manager will still remain valid, until their
+        appropriate destroy request has been called.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_data_control_device_v1" version="1">
+    <description summary="manage a data device for a seat">
+      This interface allows a client to manage a seat's selection.
+
+      When the seat is destroyed, this object becomes inert.
+    </description>
+
+    <request name="set_selection">
+      <description summary="copy data to the selection">
+        This request asks the compositor to set the selection to the data from
+        the source on behalf of the client.
+
+        The given source may not be used in any further set_selection or
+        set_primary_selection requests. Attempting to use a previously used
+        source triggers the used_source protocol error.
+
+        To unset the selection, set the source to NULL.
+      </description>
+      <arg name="source" type="object" interface="ext_data_control_source_v1"
+        allow-null="true"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy this data device">
+        Destroys the data device object.
+      </description>
+    </request>
+
+    <event name="data_offer">
+      <description summary="introduce a new ext_data_control_offer">
+        The data_offer event introduces a new ext_data_control_offer object,
+        which will subsequently be used in either the
+        ext_data_control_device.selection event (for the regular clipboard
+        selections) or the ext_data_control_device.primary_selection event (for
+        the primary clipboard selections). Immediately following the
+        ext_data_control_device.data_offer event, the new data_offer object
+        will send out ext_data_control_offer.offer events to describe the MIME
+        types it offers.
+      </description>
+      <arg name="id" type="new_id" interface="ext_data_control_offer_v1"/>
+    </event>
+
+    <event name="selection">
+      <description summary="advertise new selection">
+        The selection event is sent out to notify the client of a new
+        ext_data_control_offer for the selection for this device. The
+        ext_data_control_device.data_offer and the ext_data_control_offer.offer
+        events are sent out immediately before this event to introduce the data
+        offer object. The selection event is sent to a client when a new
+        selection is set. The ext_data_control_offer is valid until a new
+        ext_data_control_offer or NULL is received. The client must destroy the
+        previous selection ext_data_control_offer, if any, upon receiving this
+        event. Regardless, the previous selection will be ignored once a new
+        selection ext_data_control_offer is received.
+
+        The first selection event is sent upon binding the
+        ext_data_control_device object.
+      </description>
+      <arg name="id" type="object" interface="ext_data_control_offer_v1"
+        allow-null="true"/>
+    </event>
+
+    <event name="finished">
+      <description summary="this data control is no longer valid">
+        This data control object is no longer valid and should be destroyed by
+        the client.
+      </description>
+    </event>
+
+    <event name="primary_selection">
+      <description summary="advertise new primary selection">
+        The primary_selection event is sent out to notify the client of a new
+        ext_data_control_offer for the primary selection for this device. The
+        ext_data_control_device.data_offer and the ext_data_control_offer.offer
+        events are sent out immediately before this event to introduce the data
+        offer object. The primary_selection event is sent to a client when a
+        new primary selection is set. The ext_data_control_offer is valid until
+        a new ext_data_control_offer or NULL is received. The client must
+        destroy the previous primary selection ext_data_control_offer, if any,
+        upon receiving this event. Regardless, the previous primary selection
+        will be ignored once a new primary selection ext_data_control_offer is
+        received.
+
+        If the compositor supports primary selection, the first
+        primary_selection event is sent upon binding the
+        ext_data_control_device object.
+      </description>
+      <arg name="id" type="object" interface="ext_data_control_offer_v1"
+        allow-null="true"/>
+    </event>
+
+    <request name="set_primary_selection">
+      <description summary="copy data to the primary selection">
+        This request asks the compositor to set the primary selection to the
+        data from the source on behalf of the client.
+
+        The given source may not be used in any further set_selection or
+        set_primary_selection requests. Attempting to use a previously used
+        source triggers the used_source protocol error.
+
+        To unset the primary selection, set the source to NULL.
+
+        The compositor will ignore this request if it does not support primary
+        selection.
+      </description>
+      <arg name="source" type="object" interface="ext_data_control_source_v1"
+        allow-null="true"/>
+    </request>
+
+    <enum name="error">
+      <entry name="used_source" value="1"
+        summary="source given to set_selection or set_primary_selection was already used before"/>
+    </enum>
+  </interface>
+
+  <interface name="ext_data_control_source_v1" version="1">
+    <description summary="offer to transfer data">
+      The ext_data_control_source object is the source side of a
+      ext_data_control_offer. It is created by the source client in a data
+      transfer and provides a way to describe the offered data and a way to
+      respond to requests to transfer the data.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_offer" value="1"
+        summary="offer sent after ext_data_control_device.set_selection"/>
+    </enum>
+
+    <request name="offer">
+      <description summary="add an offered MIME type">
+        This request adds a MIME type to the set of MIME types advertised to
+        targets. Can be called several times to offer multiple types.
+
+        Calling this after ext_data_control_device.set_selection is a protocol
+        error.
+      </description>
+      <arg name="mime_type" type="string"
+        summary="MIME type offered by the data source"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy this source">
+        Destroys the data source object.
+      </description>
+    </request>
+
+    <event name="send">
+      <description summary="send the data">
+        Request for data from the client. Send the data as the specified MIME
+        type over the passed file descriptor, then close it.
+      </description>
+      <arg name="mime_type" type="string" summary="MIME type for the data"/>
+      <arg name="fd" type="fd" summary="file descriptor for the data"/>
+    </event>
+
+    <event name="cancelled">
+      <description summary="selection was cancelled">
+        This data source is no longer valid. The data source has been replaced
+        by another data source.
+
+        The client should clean up and destroy this data source.
+      </description>
+    </event>
+  </interface>
+
+  <interface name="ext_data_control_offer_v1" version="1">
+    <description summary="offer to transfer data">
+      A ext_data_control_offer represents a piece of data offered for transfer
+      by another client (the source client). The offer describes the different
+      MIME types that the data can be converted to and provides the mechanism
+      for transferring the data directly from the source client.
+    </description>
+
+    <request name="receive">
+      <description summary="request that the data is transferred">
+        To transfer the offered data, the client issues this request and
+        indicates the MIME type it wants to receive. The transfer happens
+        through the passed file descriptor (typically created with the pipe
+        system call). The source client writes the data in the MIME type
+        representation requested and then closes the file descriptor.
+
+        The receiving client reads from the read end of the pipe until EOF and
+        then closes its end, at which point the transfer is complete.
+
+        This request may happen multiple times for different MIME types.
+      </description>
+      <arg name="mime_type" type="string"
+        summary="MIME type desired by receiver"/>
+      <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy this offer">
+        Destroys the data offer object.
+      </description>
+    </request>
+
+    <event name="offer">
+      <description summary="advertise offered MIME type">
+        Sent immediately after creating the ext_data_control_offer object.
+        One event per offered MIME type.
+      </description>
+      <arg name="mime_type" type="string" summary="offered MIME type"/>
+    </event>
+  </interface>
+</protocol>