herdr-remote 0.2.17 → 0.2.18

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "herdr.remote.web"
 name = "Herdr Remote Web"
-version = "0.2.17"
+version = "0.2.18"
 min_herdr_version = "0.9.1"
 description = "Browser access to Herdr workspaces via local or self-hosted relay"
 platforms = ["linux", "macos"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-remote",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "Browser access to Herdr workspaces: plugin, host connector, and configuration TUI",
   "license": "MIT",
   "repository": {
@@ -43,7 +43,8 @@
     "start": "node bin/herdr-remote.js"
   },
   "dependencies": {
-    "herdr-remote-relay": "^0.2.1",
+    "harfbuzzjs": "^1.6.2",
+    "herdr-remote-relay": "^0.3.9",
     "ink": "^7.1.1",
     "node-pty": "^1.1.0",
     "qrcode": "^1.5.4",

package/src/binary-plist.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * Reads Apple binary property lists (`bplist00`), the format macOS writes its
+ * preference files in, and the NSKeyedArchiver graphs stored inside them.
+ *
+ * Terminal.app keeps each profile's font as an archived NSFont — a binary
+ * plist nested in a binary plist — and there is no command-line tool that
+ * turns that into something readable without asking Terminal itself (an
+ * AppleScript that prompts for Automation access). A reader this small is
+ * less intrusive than any of those.
+ */
+
+/** A reference to another object in a keyed archive (`CF$UID`). */
+class Uid {
+  constructor(value) {
+    this.value = value;
+  }
+}
+
+function readSizedInt(buffer, offset, size) {
+  let value = 0;
+  for (let i = 0; i < size; i += 1) value = value * 256 + buffer[offset + i];
+  return value;
+}
+
+/**
+ * Parses a whole `bplist00` buffer into plain values: objects, arrays,
+ * strings, numbers, booleans, Buffers (data), Dates and `Uid`s. Throws on
+ * anything malformed; callers treat that as "no answer".
+ */
+function parseBinaryPlist(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 40 || buffer.toString('latin1', 0, 8) !== 'bplist00') {
+    throw new Error('not a binary plist');
+  }
+  const trailer = buffer.length - 32;
+  const offsetSize = buffer[trailer + 6];
+  const refSize = buffer[trailer + 7];
+  const count = readSizedInt(buffer, trailer + 8, 8);
+  const top = readSizedInt(buffer, trailer + 16, 8);
+  const tableOffset = readSizedInt(buffer, trailer + 24, 8);
+  if (!offsetSize || !refSize || count > 1_000_000 || tableOffset + count * offsetSize > trailer) {
+    throw new Error('corrupt binary plist trailer');
+  }
+  const offsets = [];
+  for (let i = 0; i < count; i += 1) offsets.push(readSizedInt(buffer, tableOffset + i * offsetSize, offsetSize));
+
+  const parsing = new Set();
+  const parse = (index) => {
+    if (index >= count || parsing.has(index)) throw new Error('corrupt binary plist reference');
+    parsing.add(index);
+    try {
+      return parseObject(offsets[index]);
+    } finally {
+      parsing.delete(index);
+    }
+  };
+
+  // A length stored in the marker's low nibble, or as the int object after it.
+  const lengthAt = (offset) => {
+    const low = buffer[offset] & 0x0f;
+    if (low !== 0x0f) return { length: low, start: offset + 1 };
+    const marker = buffer[offset + 1];
+    if ((marker & 0xf0) !== 0x10) throw new Error('corrupt binary plist length');
+    const size = 1 << (marker & 0x0f);
+    return { length: readSizedInt(buffer, offset + 2, size), start: offset + 2 + size };
+  };
+
+  const parseObject = (offset) => {
+    const marker = buffer[offset];
+    const type = marker >> 4;
+    const low = marker & 0x0f;
+    switch (type) {
+      case 0x0:
+        if (marker === 0x08) return false;
+        if (marker === 0x09) return true;
+        return null;
+      case 0x1: {
+        const size = 1 << low;
+        if (size === 8) return Number(buffer.readBigInt64BE(offset + 1));
+        return readSizedInt(buffer, offset + 1, size);
+      }
+      case 0x2:
+        return low === 2 ? buffer.readFloatBE(offset + 1) : buffer.readDoubleBE(offset + 1);
+      case 0x3:
+        return new Date(Date.UTC(2001, 0, 1) + buffer.readDoubleBE(offset + 1) * 1000);
+      case 0x4: {
+        const { length, start } = lengthAt(offset);
+        return buffer.subarray(start, start + length);
+      }
+      case 0x5: {
+        const { length, start } = lengthAt(offset);
+        return buffer.toString('latin1', start, start + length);
+      }
+      case 0x6: {
+        const { length, start } = lengthAt(offset);
+        return Buffer.from(buffer.subarray(start, start + length * 2)).swap16().toString('utf16le');
+      }
+      case 0x8:
+        return new Uid(readSizedInt(buffer, offset + 1, low + 1));
+      case 0xa:
+      case 0xc: {
+        const { length, start } = lengthAt(offset);
+        const items = [];
+        for (let i = 0; i < length; i += 1) items.push(parse(readSizedInt(buffer, start + i * refSize, refSize)));
+        return items;
+      }
+      case 0xd: {
+        const { length, start } = lengthAt(offset);
+        const result = {};
+        for (let i = 0; i < length; i += 1) {
+          const key = parse(readSizedInt(buffer, start + i * refSize, refSize));
+          result[String(key)] = parse(readSizedInt(buffer, start + (length + i) * refSize, refSize));
+        }
+        return result;
+      }
+      default:
+        throw new Error(`unsupported binary plist object 0x${marker.toString(16)}`);
+    }
+  };
+
+  return parse(top);
+}
+
+/**
+ * The root object of an NSKeyedArchiver plist, with every `Uid` replaced by
+ * the object it points at (to a bounded depth; archives may be cyclic).
+ */
+function unarchiveKeyed(archive, depth = 6) {
+  const objects = archive?.$objects;
+  const rootRef = archive?.$top?.root;
+  if (!Array.isArray(objects) || !(rootRef instanceof Uid)) throw new Error('not a keyed archive');
+  const resolve = (value, level) => {
+    if (value instanceof Uid) return level > depth ? null : resolve(objects[value.value], level + 1);
+    if (Array.isArray(value)) return value.map((item) => resolve(item, level));
+    if (value && typeof value === 'object' && !Buffer.isBuffer(value) && !(value instanceof Date)) {
+      const result = {};
+      for (const [key, item] of Object.entries(value)) result[key] = resolve(item, level);
+      return result;
+    }
+    return value === '$null' ? null : value;
+  };
+  return resolve(rootRef, 0);
+}
+
+module.exports = { Uid, parseBinaryPlist, unarchiveKeyed };

package/src/font-subset.js

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * Cuts the characters a browser needs out of a large font.
+ *
+ * A CJK face is 16–20 MB — too much to send a phone whole — but a terminal
+ * only ever shows a few thousand distinct characters. HarfBuzz's subsetter
+ * (the same code Google Fonts slices its CJK families with) produces a small,
+ * valid font holding exactly the requested characters: 3,755 common Hanzi in
+ * about 1.7 MB and 50 ms, a handful of rare ones in a few KB and milliseconds.
+ *
+ * The WebAssembly build has no imports and runs synchronously. A loaded face
+ * costs its file size twice over (the file and the wasm heap), so the whole
+ * instance is dropped after a quiet minute; wasm memory never shrinks, only
+ * a new instance gives it back.
+ */
+
+const fs = require('node:fs');
+
+/** How long a loaded font may sit unused before its memory is released. */
+const IDLE_RELEASE_MS = 60_000;
+/** Never cut more than this many characters in one go. */
+const MAX_CODEPOINTS = 16_384;
+const HB_MEMORY_MODE_READONLY = 1;
+
+let wasmModule = null;
+function loadModule() {
+  if (!wasmModule) {
+    const file = require.resolve('harfbuzzjs/dist/harfbuzz-subset.wasm');
+    wasmModule = new WebAssembly.Module(fs.readFileSync(file));
+  }
+  return wasmModule;
+}
+
+class FontSubsetter {
+  constructor({ idleMs = IDLE_RELEASE_MS } = {}) {
+    this.idleMs = idleMs;
+    this.instance = null;
+    /** Loaded faces by source key: `{ pointer, face }` in the current instance. */
+    this.faces = new Map();
+    this.idleTimer = null;
+  }
+
+  exports() {
+    if (!this.instance) {
+      this.instance = new WebAssembly.Instance(loadModule(), {}).exports;
+      // An Emscripten reactor: static constructors run here, before any call.
+      this.instance._initialize();
+    }
+    return this.instance;
+  }
+
+  face(source) {
+    const key = `${source.path}\0${source.index || 0}`;
+    const loaded = this.faces.get(key);
+    if (loaded) return loaded.face;
+    const hb = this.exports();
+    const data = fs.readFileSync(source.path);
+    const pointer = hb.malloc(data.length);
+    if (!pointer) throw new Error('out of memory loading font');
+    new Uint8Array(hb.memory.buffer).set(data, pointer);
+    const blob = hb.hb_blob_create(pointer, data.length, HB_MEMORY_MODE_READONLY, 0, 0);
+    const face = hb.hb_face_create(blob, source.index || 0);
+    hb.hb_blob_destroy(blob);
+    this.faces.set(key, { pointer, face });
+    return face;
+  }
+
+  /** A standalone font with just `codepoints` from `source` (`{ path, index }`). */
+  subset(source, codepoints) {
+    const hb = this.exports();
+    const face = this.face(source);
+    const input = hb.hb_subset_input_create_or_fail();
+    if (!input) throw new Error('font subsetting is unavailable');
+    let result = 0;
+    let subsetFace = 0;
+    try {
+      const set = hb.hb_subset_input_unicode_set(input);
+      for (const codepoint of codepoints.slice(0, MAX_CODEPOINTS)) hb.hb_set_add(set, codepoint);
+      subsetFace = hb.hb_subset_or_fail(face, input);
+      if (!subsetFace) throw new Error('the font could not be subset');
+      result = hb.hb_face_reference_blob(subsetFace);
+      const length = hb.hb_blob_get_length(result);
+      const pointer = hb.hb_blob_get_data(result, 0);
+      // Copied out: the heap may grow (and move) on the next call.
+      return Buffer.from(new Uint8Array(hb.memory.buffer, pointer, length));
+    } finally {
+      if (result) hb.hb_blob_destroy(result);
+      if (subsetFace) hb.hb_face_destroy(subsetFace);
+      hb.hb_subset_input_destroy(input);
+      this.scheduleRelease();
+    }
+  }
+
+  scheduleRelease() {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => this.release(), this.idleMs);
+    this.idleTimer.unref?.();
+  }
+
+  /** Drop every loaded face and the instance holding them. */
+  release() {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+    this.faces.clear();
+    this.instance = null;
+  }
+}
+
+module.exports = { FontSubsetter, MAX_CODEPOINTS };

package/src/host-connector.js

@@ -24,8 +24,11 @@ const {
   packStreamFrameV2,
   FRAME_TYPE_OUTPUT,
   PROTOCOL_VERSION,
+  TERMINAL_FONT_CHUNK_BYTES,
 } = require('herdr-remote-relay/protocol');
 const { resolveHostPalette } = require('./terminal-palette');
+const { loadHostTerminalFont, publicTerminalFont, readFontChunk } = require('./terminal-font');
+const { FontSubsetter } = require('./font-subset');
 const { requestHerdr, subscribeHerdr } = require('./herdr-api');
 const { sameSummary, summarizeAgents } = require('./agent-status');
 const { EXIT_REPLACED, EXIT_AUTH_FAILED } = require('./exit-codes');
@@ -42,6 +45,9 @@ const {
 /** Windows opening within this long of a check reuse its answer. */
 const UPDATE_RECHECK_MS = 60_000;
 
+/** Cut fonts kept for the slices a browser has yet to fetch, by total size. */
+const FONT_SUBSET_CACHE_BYTES = 48 * 1024 * 1024;
+
 /** How often the agent summary is re-read while a browser is watching. */
 const AGENT_STATUS_POLL_MS = 5_000;
 const AGENT_STATUS_EVENT_DEBOUNCE_MS = 150;
@@ -125,6 +131,19 @@ class HostConnector {
     this.terminalPalette = options.terminalPalette !== undefined
       ? options.terminalPalette
       : resolveHostPalette();
+    /**
+     * The terminal's font, with the local files behind it. Only the family,
+     * size and file hashes leave this process; a browser that lacks the font
+     * fetches the files by hash, one chunk at a time. Injectable for tests.
+     */
+    this.loadTerminalFont = options.loadTerminalFont || loadHostTerminalFont;
+    this.terminalFont = options.terminalFont !== undefined
+      ? options.terminalFont
+      : this.loadTerminalFont();
+    /** Cuts characters out of large fonts; see font-subset.js. */
+    this.fontSubsetter = options.fontSubsetter || new FontSubsetter();
+    /** Subsets too large for one message, by hash, until fetched. */
+    this.fontSubsets = new Map();
     this.ws = null;
     this.sessions = new Map();
     this.streamIndexToId = new Map();
@@ -277,6 +296,7 @@ class HostConnector {
         platform: process.platform,
         arch: process.arch,
         terminalPalette: this.terminalPalette || null,
+        terminalFont: publicTerminalFont(this.terminalFont),
         capabilities: ['host_handoff', 'idle_heartbeat', 'binary_frame_v2'],
       });
       // The relay sends host_ready with the current browser count. No business
@@ -386,6 +406,127 @@ class HostConnector {
     if (message.type === 'session_stop') this.stopSession(message.clientId || message.streamId);
     else if (message.type === 'resize') this.resizeSession(message);
     else if (message.type === 'paste_file') this.handlePasteFile(message);
+    else if (message.type === 'host_font_chunk_request') this.handleFontChunkRequest(message);
+    else if (message.type === 'host_font_subset_request') this.handleFontSubsetRequest(message);
+    else if (message.type === 'host_font_refresh') this.handleFontRefresh();
+  }
+
+  /**
+   * A service started at boot runs before anything has seen a terminal, so it
+   * starts with no font. The first `herdr-remote start` from a terminal (or
+   * from Herdr's plugin hook) writes one down; the next window to open picks
+   * it up here instead of waiting for a restart.
+   */
+  pickUpTerminalFont() {
+    if (this.terminalFont) return;
+    let next = null;
+    try {
+      next = this.loadTerminalFont();
+    } catch {
+      return;
+    }
+    if (!next) return;
+    this.terminalFont = next;
+    sendJson(this.ws, { type: 'terminal_font', terminalFont: publicTerminalFont(next) });
+  }
+
+  /** One slice of a terminal font file, for the window that asked for it. */
+  handleFontChunkRequest(message) {
+    const streamId = message.clientId || message.streamId;
+    const chunk = this.subsetChunk(message.sha256, message.index)
+      || readFontChunk(this.terminalFont, message.sha256, message.index);
+    if (!chunk) {
+      sendJson(this.ws, {
+        type: 'error',
+        clientId: streamId,
+        code: 'host_font_unavailable',
+        message: 'The terminal font changed or is no longer on this workstation',
+      });
+      return;
+    }
+    sendJson(this.ws, {
+      type: 'host_font_chunk',
+      clientId: streamId,
+      sha256: message.sha256,
+      index: message.index,
+      total: chunk.total,
+      dataBase64: chunk.data.toString('base64'),
+    });
+  }
+
+  /** A slice of a cut font still held for the browser that asked for it. */
+  subsetChunk(sha256, index) {
+    const data = this.fontSubsets.get(sha256);
+    if (!data) return null;
+    const total = Math.ceil(data.length / TERMINAL_FONT_CHUNK_BYTES);
+    if (!Number.isInteger(index) || index < 0 || index >= total) return null;
+    const start = index * TERMINAL_FONT_CHUNK_BYTES;
+    return { data: data.subarray(start, start + TERMINAL_FONT_CHUNK_BYTES), total };
+  }
+
+  /**
+   * The characters a window is about to draw, cut out of a large font (CJK).
+   * A small result travels in the answer itself; a large one (the common
+   * characters fetched up front) is held here and pulled in slices.
+   */
+  handleFontSubsetRequest(message) {
+    const streamId = message.clientId || message.streamId;
+    const source = this.terminalFont?.subsets?.find((candidate) => candidate.sha256 === message.sha256);
+    const fail = (code, text) => sendJson(this.ws, { type: 'error', clientId: streamId, code, message: text });
+    if (!source) {
+      fail('host_font_unavailable', 'The terminal font changed or is no longer on this workstation');
+      return;
+    }
+    let stat;
+    try { stat = fs.statSync(source.path); } catch {}
+    if (!stat || stat.size !== source.bytes || stat.mtimeMs !== source.mtimeMs) {
+      fail('host_font_unavailable', 'The terminal font changed or is no longer on this workstation');
+      return;
+    }
+    const codepoints = [...new Set(Array.from(String(message.text || ''), (char) => char.codePointAt(0)))];
+    let data;
+    try {
+      data = this.fontSubsetter.subset(source, codepoints);
+    } catch (error) {
+      fail('host_font_subset_failed', error.message || 'The font could not be subset');
+      return;
+    }
+    const subsetSha = crypto.createHash('sha256').update(data).digest('hex');
+    const answer = {
+      type: 'host_font_subset_ready',
+      clientId: streamId,
+      requestId: message.requestId,
+      sha256: source.sha256,
+      subsetSha,
+      bytes: data.length,
+    };
+    if (data.length <= TERMINAL_FONT_CHUNK_BYTES) {
+      answer.dataBase64 = data.toString('base64');
+    } else {
+      this.fontSubsets.delete(subsetSha);
+      this.fontSubsets.set(subsetSha, data);
+      let held = [...this.fontSubsets.values()].reduce((sum, item) => sum + item.length, 0);
+      for (const [key, item] of this.fontSubsets) {
+        if (held <= FONT_SUBSET_CACHE_BYTES || key === subsetSha) break;
+        this.fontSubsets.delete(key);
+        held -= item.length;
+      }
+    }
+    sendJson(this.ws, answer);
+  }
+
+  /**
+   * Read the terminal's font settings again, at a browser's request. Every
+   * window of this workstation hears the answer, since they all draw with it.
+   */
+  handleFontRefresh() {
+    try {
+      const next = this.loadTerminalFont({ refresh: true });
+      if (next) this.terminalFont = next;
+    } catch (error) {
+      process.stderr.write(`herdr-remote host connector: could not read the terminal font: ${error.message}\n`);
+    }
+    sendJson(this.ws, { type: 'terminal_font', terminalFont: publicTerminalFont(this.terminalFont) });
   }
 
   /**
@@ -438,6 +579,7 @@ class HostConnector {
     this.stopSession(streamId);
     // A window opening is when a person is looking; that is when to ask.
     this.reportUpdateStatus();
+    this.pickUpTerminalFont();
     const missingHerdr = this.ensureHerdrCommand();
     if (missingHerdr) {
       process.stderr.write(`herdr-remote host connector: ${missingHerdr}\n`);

package/src/service.js

@@ -24,6 +24,7 @@ const {
   rememberTerminalPalette,
   rememberedTerminalPalette,
 } = require('./terminal-palette');
+const { resolveHostFont } = require('./terminal-font');
 const { resolveSocketPath } = require('./socket-discovery');
 const { preferredLanAddress } = require('./net-interfaces');
 const { MIN_HERDR_VERSION, findHerdrCommand, herdrVersion, resolveHerdrCommand } = require('./herdr-command');
@@ -120,6 +121,16 @@ function hostTerminalPalette({ refresh = false } = {}) {
   return cachedTerminalPalette;
 }
 
+/**
+ * The terminal font a service start hands its connector: what this command
+ * detected at its entry point, else what an earlier start with a terminal
+ * wrote down. Only the family, size and terminal travel here; the connector
+ * finds the files itself, on the machine that has them.
+ */
+function hostTerminalFont() {
+  return resolveHostFont();
+}
+
 function logPath(name) {
   return path.join(stateDir(), `${name}.log`);
 }
@@ -175,6 +186,7 @@ function serviceSpecs(config = loadConfig(), state = ensureRuntime()) {
   }
 
   const terminalPalette = hostTerminalPalette();
+  const terminalFont = hostTerminalFont();
 
   specs.push({
     name: 'host',
@@ -184,6 +196,7 @@ function serviceSpecs(config = loadConfig(), state = ensureRuntime()) {
       // Captured here, where a terminal may still be attached, because the
       // connector itself usually runs detached with no terminal to ask.
       ...(terminalPalette ? { HERDR_TERM_PALETTE_JSON: JSON.stringify(terminalPalette) } : {}),
+      ...(terminalFont ? { HERDR_TERM_FONT_JSON: JSON.stringify(terminalFont) } : {}),
       RELAY_URL: resolveHostRelayUrl(config),
       RELAY_HOST_ID: state.hostId,
       RELAY_HOST_TOKEN: state.hostToken,
@@ -500,6 +513,7 @@ module.exports = {
   serviceSpecs,
   baseEnvironment,
   hostTerminalPalette,
+  hostTerminalFont,
   startServices,
   stopServices,
   restartServices,