react-x11 2.51.1 → 2.53.0

package/src/wayland/seat.js

@@ -26,7 +26,7 @@
 
 import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
-import { XkbKeymap } from './xkb.js';
+import { XkbKeymap, REAL_MODS, layoutsFromKeymap } from './xkb.js';
 
 /** `wl_seat.capability` bits. */
 export const SEAT_CAP = { POINTER: 1, KEYBOARD: 2, TOUCH: 4 };
@@ -185,7 +185,10 @@ export class WaylandSeat extends EventEmitter {
     this.xkb = null;
     /** X-style modifier mask: depressed | latched | locked */
     this.mods = 0;
+    /** the locked half alone — Caps Lock and Num Lock (keyboardState) */
+    this.locked = 0;
     this.group = 0;
+    this._layouts = null;
     /** pointer buttons currently held, as an X state mask */
     this.buttonMask = 0;
     this.repeat = { rate: 25, delay: 600 };
@@ -437,6 +440,7 @@ export class WaylandSeat extends EventEmitter {
             : null;
         this.keymap = { format, size, text };
         this.xkb = text ? XkbKeymap.parse(text) : null;
+        this._layouts = null;
         this.emit('keymap', this.keymap, this.xkb);
       } catch (err) {
         this.emit(
@@ -473,6 +477,7 @@ export class WaylandSeat extends EventEmitter {
     k.on('modifiers', (serial, depressed, latched, locked, group) => {
       this.lastSerial = serial;
       this.mods = (depressed | latched | locked) & 0xff;
+      this.locked = locked;
       this.group = group;
       this.emit('modifiers', {
         mods: this.mods,
@@ -501,6 +506,28 @@ export class WaylandSeat extends EventEmitter {
     });
   }
 
+  /**
+   * The locks and the layout, in `useKeyboardState()`'s shape
+   * (src/keyboardstate.js). Caps Lock is Lock, which no keymap can move;
+   * Num Lock is wherever this keymap binds the virtual `NumLock`, with the
+   * X convention's Mod2 where it does not say.
+   *
+   * Only as fresh as the last `wl_keyboard.modifiers`, and a compositor sends
+   * those to the client with keyboard focus alone: a lock toggled while
+   * another app has the keyboard arrives when focus comes back. That is the
+   * protocol, not a shortcut — X11's StateNotify reaches every client.
+   */
+  keyboardState() {
+    const numLock = this.xkb?.maskOf('NumLock') || REAL_MODS.Mod2;
+    this._layouts ??= Object.freeze(layoutsFromKeymap(this.keymap?.text));
+    return {
+      capsLock: Boolean(this.locked & REAL_MODS.Lock),
+      numLock: Boolean(this.locked & numLock),
+      group: this.group,
+      layouts: this._layouts,
+    };
+  }
+
   /** A key event in the shape events.js reads, decoded against the keymap. */
   _keyEvent(type, keycode, time, serial, repeat = false) {
     const state = XkbKeymap.stateOf(this.mods, this.group);

package/src/wayland/swapchain.js

@@ -191,6 +191,17 @@ export class WaylandSwapchain {
 
   /** Give the chain buffers of this size, keeping its GBM surface. */
   _resize(w, h) {
+    // The size they already are keeps them: x11-dri makes nothing again and
+    // moves no generation, so the wl_buffers stay too. Dropped, the next
+    // swap answered a buffer the compositor already had — `isNew: false`, no
+    // descriptor — that this chain no longer knew, and imported it with
+    // none. A small surface asks for this on every change of size: `slackFor`
+    // rounds both sides up to the same 128. What each buffer holds is of the
+    // old size, so all of it is owed.
+    if (w === this.allocWidth && h === this.allocHeight) {
+      for (const entry of this.buffers.values()) entry.damage = 'all';
+      return;
+    }
     // In place: the handle stays valid, the context keeps its GL objects and
     // stays current. Buffers from the old generation are gone, so their
     // `wl_buffer`s go with them — the compositor may still be showing one, so
@@ -299,6 +310,18 @@ export class WaylandSwapchain {
       return true;
     }
     this._swapsSinceNew = 0;
+    if (!out.isNew) {
+      // GBM exported this one already, so it carries no descriptor, and the
+      // chain has no wl_buffer for it: the two have lost track of each
+      // other, which no compositor did.
+      this._fail(
+        new Error(
+          `GPU buffer ${id} came round again with no wl_buffer for it ` +
+            '(react-x11 bug: the swapchain dropped a buffer GBM still holds)',
+        ),
+      );
+      return false;
+    }
     return await this._import(id, out, generation, damage);
   }
 

package/src/wayland/video.js

@@ -0,0 +1,376 @@
+// `<video frames>` on Wayland: a frame's planes go up as textures as the
+// decoder made them, and the colour conversion is a fragment shader drawing
+// into the `<video>`'s own surface (design/architecture/video.md §5).
+//
+// The backend's 2D context is already a GLES rasterizer, so this is the GLX
+// transport of §2.3 made native: no conversion in JavaScript for any format,
+// and NV12 and I420 cross into the GPU at 1.5 bytes a pixel. Y is an R8
+// texture; NV12's chroma one RG8 texture at half size, I420's two R8 ones;
+// BGRA one RGBA8 texture read back to front. The shader applies the sink's
+// matrix and range exactly as `frameToRGBA` does — no transfer function,
+// because nothing else on this backend is colour-managed either — so a frame
+// drawn here and one converted in JavaScript are the same picture, chroma
+// apart: sampled bilinearly here, as a player does, and by nearest there.
+//
+// What it writes into is the surface the drawn presentation already keeps
+// (src/nodes/video.js): a render target, which the window's context then
+// composites at the picture's rect like any `drawImage`. Nothing lifts on
+// Wayland — no subsurfaces, by the backend's own design — so this is the
+// whole presentation.
+//
+// The GL is shared with every 2D context on the app (device.js): whatever
+// the device's owner still has buffered is drawn before the target is
+// written, the shader's vertex state lives in a vertex array of its own,
+// and the device is released afterwards so the next context to draw puts
+// its own state back. `UNPACK_ROW_LENGTH`, which a decoder's padded rows
+// need, is set back to 0 for the uploads that assume it.
+
+import { flushDevice, releaseDevice } from './device.js';
+
+const VERT = `
+attribute vec2 aPos;
+attribute vec2 aUV;
+varying vec2 vUV;
+void main() {
+  vUV = aUV;
+  gl_Position = vec4(aPos, 0.0, 1.0);
+}`;
+
+const FRAG = `
+#ifdef GL_FRAGMENT_PRECISION_HIGH
+precision highp float;
+#else
+precision mediump float;
+#endif
+varying vec2 vUV;
+uniform int uLayout;
+uniform sampler2D uY;
+uniform sampler2D uC;
+uniform sampler2D uV;
+uniform vec2 uChroma;
+uniform mat3 uMatrix;
+uniform vec3 uOffset;
+void main() {
+  if (uLayout == 0) {
+    // BGRA bytes uploaded as RGBA: blue is in r. Opaque, whatever the
+    // fourth byte held.
+    gl_FragColor = vec4(texture2D(uY, vUV).bgr, 1.0);
+    return;
+  }
+  float y = texture2D(uY, vUV).r;
+  vec2 cuv = vUV * uChroma;
+  vec2 c = uLayout == 1
+    ? texture2D(uC, cuv).rg
+    : vec2(texture2D(uC, cuv).r, texture2D(uV, cuv).r);
+  vec3 rgb = uMatrix * (vec3(y, c) - uOffset);
+  gl_FragColor = vec4(clamp(rgb, 0.0, 1.0), 1.0);
+}`;
+
+const LAYOUT = { BGRA: 0, NV12: 1, I420: 2 };
+
+// Kr and Kb, as src/videoframes.js has them
+const MATRIX = {
+  bt709: [0.2126, 0.0722],
+  bt601: [0.299, 0.114],
+  bt2020: [0.2627, 0.0593],
+};
+
+const matrices = new Map();
+
+/**
+ * The column-major mat3 and the offset that take normalized Y'CbCr to
+ * R'G'B' for a matrix and a range — the same numbers `frameToRGBA`'s tables
+ * are made of, in units of 1 rather than of 255.
+ */
+export function videoMatrix(colorSpace, range) {
+  const key = `${colorSpace}/${range}`;
+  let m = matrices.get(key);
+  if (m) return m;
+  const [kr, kb] = MATRIX[colorSpace];
+  const kg = 1 - kr - kb;
+  const full = range === 'full';
+  const ys = full ? 1 : 255 / 219;
+  const cs = full ? 1 : 255 / 224;
+  m = {
+    matrix: Float32Array.of(
+      // the column Y' multiplies
+      ys,
+      ys,
+      ys,
+      // Cb
+      0,
+      -cs * ((2 * kb * (1 - kb)) / kg),
+      cs * 2 * (1 - kb),
+      // Cr
+      cs * 2 * (1 - kr),
+      -cs * ((2 * kr * (1 - kr)) / kg),
+      0,
+    ),
+    offset: Float32Array.of(full ? 0 : 16 / 255, 128 / 255, 128 / 255),
+  };
+  matrices.set(key, m);
+  return m;
+}
+
+/** The planes of a frame as textures: format, size and the bytes per texel
+ *  `UNPACK_ROW_LENGTH` counts a decoder's stride in. */
+function planesOf(gl, format, width, height) {
+  const cw = Math.ceil(width / 2);
+  const ch = Math.ceil(height / 2);
+  const r8 = { internal: gl.R8, format: gl.RED, texel: 1 };
+  switch (format) {
+    case 'NV12':
+      return [
+        { ...r8, width, height },
+        { internal: gl.RG8, format: gl.RG, texel: 2, width: cw, height: ch },
+      ];
+    case 'I420':
+      return [
+        { ...r8, width, height },
+        { ...r8, width: cw, height: ch },
+        { ...r8, width: cw, height: ch },
+      ];
+    case 'BGRA':
+      return [{ internal: gl.RGBA, format: gl.RGBA, texel: 4, width, height }];
+  }
+  return null;
+}
+
+/** One per GL device: the program, and the quad it draws. */
+const programs = new WeakMap();
+
+function programFor(gl) {
+  let p = programs.get(gl);
+  if (p) return p;
+  const vs = compile(gl, gl.VERTEX_SHADER, VERT, 'video vertex');
+  let fs;
+  try {
+    fs = compile(gl, gl.FRAGMENT_SHADER, FRAG, 'video fragment');
+  } catch (err) {
+    gl.deleteShader(vs);
+    throw err;
+  }
+  const program = gl.createProgram();
+  gl.attachShader(program, vs);
+  gl.attachShader(program, fs);
+  gl.linkProgram(program);
+  const linked = gl.getProgramParameter(program, gl.LINK_STATUS);
+  const log = linked ? '' : gl.getProgramInfoLog(program);
+  gl.deleteShader(vs);
+  gl.deleteShader(fs);
+  if (!linked) {
+    gl.deleteProgram(program);
+    throw new Error(`video program failed to link: ${log}`);
+  }
+  const u = (name) => gl.getUniformLocation(program, name);
+  const aPos = gl.getAttribLocation(program, 'aPos');
+  const aUV = gl.getAttribLocation(program, 'aUV');
+  // A strip over the whole target. The 2D context draws device row 0 at the
+  // top of clip space, so the frame's first row — texture row 0 — goes
+  // there: v = 0 at clip y = +1.
+  const buffer = gl.createBuffer();
+  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+  gl.bufferData(
+    gl.ARRAY_BUFFER,
+    Float32Array.of(-1, 1, 0, 0, -1, -1, 0, 1, 1, 1, 1, 0, 1, -1, 1, 1),
+    gl.STATIC_DRAW,
+  );
+  // its own vertex array, so the 2D contexts' attribute state — on the
+  // default one, re-pointed every batch — is never this program's
+  const vao = gl.createVertexArray();
+  gl.bindVertexArray(vao);
+  gl.enableVertexAttribArray(aPos);
+  gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 16, 0);
+  gl.enableVertexAttribArray(aUV);
+  gl.vertexAttribPointer(aUV, 2, gl.FLOAT, false, 16, 8);
+  gl.bindVertexArray(null);
+  p = {
+    program,
+    buffer,
+    vao,
+    maxSize: gl.getParameter(gl.MAX_TEXTURE_SIZE),
+    loc: {
+      uLayout: u('uLayout'),
+      uY: u('uY'),
+      uC: u('uC'),
+      uV: u('uV'),
+      uChroma: u('uChroma'),
+      uMatrix: u('uMatrix'),
+      uOffset: u('uOffset'),
+    },
+  };
+  programs.set(gl, p);
+  return p;
+}
+
+/** Each surface's plane textures, kept across frames of one size. */
+const uploads = new WeakMap();
+
+function texturesFor(gl, surface, format, width, height) {
+  let kept = uploads.get(surface);
+  if (
+    kept &&
+    kept.format === format &&
+    kept.width === width &&
+    kept.height === height
+  ) {
+    return kept;
+  }
+  if (kept) deleteTextures(gl, kept);
+  const planes = planesOf(gl, format, width, height);
+  kept = {
+    format,
+    width,
+    height,
+    planes,
+    textures: planes.map(() => gl.createTexture()),
+    fresh: true,
+  };
+  uploads.set(surface, kept);
+  return kept;
+}
+
+function deleteTextures(gl, kept) {
+  for (const tex of kept.textures) gl.deleteTexture(tex);
+  kept.textures = [];
+}
+
+/**
+ * A plane's rows at a stride `UNPACK_ROW_LENGTH` cannot say — one that is
+ * not a whole number of texels — packed tight. Every decoder pads to whole
+ * pixels, so this is the case that should never come.
+ */
+function tight(data, stride, rowBytes, rows) {
+  const out = new Uint8Array(rowBytes * rows);
+  for (let r = 0; r < rows; r++) {
+    out.set(data.subarray(r * stride, r * stride + rowBytes), r * rowBytes);
+  }
+  return out;
+}
+
+/**
+ * `frame` from `sink` into `surface` (a WaylandSurface at the frame's size).
+ * False — and the frame is converted in JavaScript instead — where the
+ * surface is not one of this backend's, the app has no GL, or the frame is
+ * larger than a texture can be.
+ */
+export function writeVideoFrame(app, surface, sink, frame) {
+  const gl = app?.gl;
+  const target = surface?.target;
+  if (!gl || !target?.fbo || target.destroyed) return false;
+  if (!(sink.format in LAYOUT)) return false;
+  app.makeCurrent();
+  const p = programFor(gl);
+  if (sink.width > p.maxSize || sink.height > p.maxSize) return false;
+  // Anything a context still has buffered is drawn first: one of its draws
+  // may read this target, and must read the frame it was given (device.js).
+  flushDevice(gl);
+  const kept = texturesFor(gl, surface, sink.format, sink.width, sink.height);
+  try {
+    gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+    kept.planes.forEach((plane, i) => {
+      const rowBytes = plane.width * plane.texel;
+      const stride = frame.strides[i];
+      let data = frame.planes[i];
+      let rowLength = 0;
+      if (stride !== rowBytes) {
+        if (stride % plane.texel === 0) rowLength = stride / plane.texel;
+        else data = tight(data, stride, rowBytes, plane.height);
+      }
+      gl.pixelStorei(gl.UNPACK_ROW_LENGTH, rowLength);
+      gl.activeTexture(gl.TEXTURE0 + i);
+      gl.bindTexture(gl.TEXTURE_2D, kept.textures[i]);
+      if (kept.fresh) {
+        // Y and BGRA meet the target texel for texel; chroma is half size,
+        // and read between its samples as a player reads it
+        const filter = i === 0 ? gl.NEAREST : gl.LINEAR;
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.texImage2D(
+          gl.TEXTURE_2D,
+          0,
+          plane.internal,
+          plane.width,
+          plane.height,
+          0,
+          plane.format,
+          gl.UNSIGNED_BYTE,
+          data,
+        );
+      } else {
+        gl.texSubImage2D(
+          gl.TEXTURE_2D,
+          0,
+          0,
+          0,
+          plane.width,
+          plane.height,
+          plane.format,
+          gl.UNSIGNED_BYTE,
+          data,
+        );
+      }
+    });
+    kept.fresh = false;
+
+    target.bind();
+    gl.disable(gl.BLEND);
+    gl.disable(gl.SCISSOR_TEST);
+    gl.disable(gl.STENCIL_TEST);
+    gl.disable(gl.DEPTH_TEST);
+    gl.disable(gl.CULL_FACE);
+    gl.colorMask(true, true, true, true);
+    gl.useProgram(p.program);
+    const { loc } = p;
+    gl.uniform1i(loc.uLayout, LAYOUT[sink.format]);
+    gl.uniform1i(loc.uY, 0);
+    gl.uniform1i(loc.uC, 1);
+    gl.uniform1i(loc.uV, 2);
+    // full-size texture coordinates onto a chroma plane rounded up: an odd
+    // frame's last chroma column covers one picture column, not two
+    gl.uniform2f(
+      loc.uChroma,
+      sink.width / (2 * Math.ceil(sink.width / 2)),
+      sink.height / (2 * Math.ceil(sink.height / 2)),
+    );
+    const { matrix, offset } = videoMatrix(sink.colorSpace, sink.range);
+    gl.uniformMatrix3fv(loc.uMatrix, false, matrix);
+    gl.uniform3fv(loc.uOffset, offset);
+    gl.bindVertexArray(p.vao);
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+    gl.bindVertexArray(null);
+  } finally {
+    gl.pixelStorei(gl.UNPACK_ROW_LENGTH, 0);
+    gl.activeTexture(gl.TEXTURE0);
+    // the program, the blend and the framebuffer were the 2D contexts' to
+    // say: the next one to draw says them again
+    releaseDevice(gl);
+    app.rebindWindowTarget?.();
+  }
+  return true;
+}
+
+/** `surface` is let go: its plane textures with it. */
+export function releaseVideoFrame(app, surface) {
+  const kept = uploads.get(surface);
+  if (!kept) return;
+  uploads.delete(surface);
+  const gl = app?.gl;
+  if (!gl) return;
+  app.makeCurrent();
+  deleteTextures(gl, kept);
+}
+
+function compile(gl, type, src, what) {
+  const sh = gl.createShader(type);
+  gl.shaderSource(sh, src);
+  gl.compileShader(sh);
+  if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(sh);
+    gl.deleteShader(sh);
+    throw new Error(`${what} shader failed to compile: ${log}`);
+  }
+  return sh;
+}

package/src/wayland/xkb.js

@@ -331,6 +331,14 @@ export class XkbKeymap {
     }
   }
 
+  /**
+   * A modifier by name, as the real mask the compositor reports it under —
+   * `'NumLock'` is whichever ModN this keymap binds it to, `'Lock'` is Lock.
+   */
+  maskOf(name) {
+    return this._modMask(name);
+  }
+
   /** A modifier name (real or virtual) as a real mask. */
   _modMask(name) {
     if (name in REAL_MODS) return REAL_MODS[name];
@@ -461,6 +469,135 @@ export class XkbKeymap {
   }
 }
 
+/**
+ * Files the rules add to `xkb_symbols` that are not a layout: the model's
+ * extras (`inet(evdev)`) and every option's (`group(alt_shift_toggle)`,
+ * `compose(rctrl)`). Only consulted where a keymap has one group and so no
+ * group suffix to anchor on.
+ */
+const NOT_LAYOUTS = new Set([
+  'altwin',
+  'capslock',
+  'compose',
+  'ctrl',
+  'eurosign',
+  'fkeys',
+  'grab',
+  'group',
+  'hyper',
+  'inet',
+  'keypad',
+  'kpdl',
+  'level2',
+  'level3',
+  'level5',
+  'nbsp',
+  'parens',
+  'rupeesign',
+  'scrolllock',
+  'shift',
+  'srvr_ctrl',
+  'srvrkeys',
+  'terminate',
+  'typo',
+]);
+
+/** `macintosh_vndr/us(alt)` → `us`: the file, without directory or variant. */
+const fileOf = (token) => token.replace(/\(.*$/, '').replace(/^.*\//, '');
+
+/**
+ * The layout codes a keymap was compiled from — `['us', 'ru']`, what X11
+ * reads out of `_XKB_RULES_NAMES` and what a Wayland client has nothing
+ * like. Pure, and exported for the test.
+ *
+ * The one place a compositor's keymap still says is the **name** of its
+ * `xkb_symbols` section. libxkbcommon names it after the include string the
+ * rules built — `pc+us+ru:2+inet(evdev)+group(alt_shift_toggle)` — with both
+ * `+` and `:` written as `_`:
+ *
+ *     xkb_symbols "pc_us_ru_2_inet(evdev)_group(alt_shift_toggle)" {
+ *       name[1]="English (US)";
+ *       name[2]="Russian";
+ *
+ * The rules put the model's file first, then the layouts in order — each one
+ * after the first followed by its group number — then the model's extras and
+ * the options. So group N is the file right before the bare `N`, group 1 is
+ * the file right before group 2, and with a single group it is the file
+ * before the first extra. `name[N]` is how many groups there are, and an
+ * answer that cannot account for every one of them is no answer: the list
+ * comes back empty, which is what "not known" means in src/keyboardstate.js.
+ *
+ * The `name[N]` strings are not the answer themselves: they are
+ * descriptions, `"Russian"`, where an indicator wants `ru` — the same reason
+ * the X11 path reads the rules rather than XKB's group names.
+ */
+export function layoutsFromKeymap(text) {
+  if (typeof text !== 'string') return [];
+  const at = text.search(/xkb_symbols\s+"/);
+  if (at < 0) return [];
+  const section = text.slice(at);
+  const name = /^xkb_symbols\s+"([^"]*)"/.exec(section)?.[1];
+  let groups = 0;
+  for (const m of section.matchAll(/\bname\[(?:group)?(\d+)\]\s*=/gi)) {
+    groups = Math.max(groups, Number(m[1]));
+  }
+  if (!name || !groups || groups > 4) return [];
+
+  const tokens = splitIncludes(name);
+  const layouts = [];
+  if (groups === 1) {
+    let i = tokens.findIndex((t, n) => n > 0 && NOT_LAYOUTS.has(fileOf(t)));
+    if (i < 0) i = tokens.length;
+    if (i < 2) return [];
+    layouts.push(tokens[i - 1]);
+  } else {
+    let prev = -1;
+    for (let g = 2; g <= groups; g++) {
+      const i = tokens.indexOf(String(g), prev + 1);
+      if (i < 2) return [];
+      if (g === 2) layouts.push(tokens[i - 2]);
+      layouts.push(tokens[i - 1]);
+      prev = i;
+    }
+  }
+  const codes = layouts.map(fileOf);
+  if (codes.some((c) => !/^[a-z][a-z0-9-]*$/i.test(c) || NOT_LAYOUTS.has(c))) {
+    return [];
+  }
+  // `empty` is what a keymap with no layout to name is built from; reporting
+  // it would put "EMPTY" in an indicator (the X11 path drops it too)
+  return codes.every((c) => c === 'empty') ? [] : codes;
+}
+
+/**
+ * `pc_us(dvorak)_ru(phonetic_winkeys)_2` → `['pc', 'us(dvorak)',
+ * 'ru(phonetic_winkeys)', '2']`. Split where a `_`, `+` or `:` stands outside
+ * parentheses — the raw include string spells them that way, and a
+ * variant's own underscores are inside them. Two file names have an
+ * underscore of their own, the `*_vndr/` directories and `srvr_ctrl`, and are
+ * kept whole.
+ */
+function splitIncludes(name) {
+  const guarded = name
+    .replace(/([a-z0-9]+)_vndr\//gi, '$1\u0001vndr/')
+    .replace(/srvr_ctrl/g, 'srvr\u0001ctrl');
+  const out = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of guarded) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth = Math.max(0, depth - 1);
+    if (depth === 0 && (ch === '_' || ch === '+' || ch === ':')) {
+      if (cur) out.push(cur);
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur) out.push(cur);
+  return out.map((t) => t.replaceAll('\u0001', '_'));
+}
+
 /**
  * `XkbKSIsKeypad`: the one run of keysyms the keypad produces, `KP_Space`
  * through `KP_Equal`. Every keypad key is in it on both of its levels — the

package/src/win32/a11y.js

@@ -7,7 +7,7 @@
 // property reads — so answering from JS would pace the screen reader by the
 // application's busiest moment. The bridge therefore *pushes*, and
 // `windows/src/uia.cc` answers from its copy. The reasoning is
-// docs/windows.md §"Accessibility: UI Automation"; what matters here is the
+// design/windows.md §"Accessibility: UI Automation"; what matters here is the
 // consequence: **this file's job is a diff, not an answer.**
 //
 // Everything it pushes comes from `src/a11y.js`, which is pure functions over

package/src/win32/app.js

@@ -362,7 +362,7 @@ export class Win32App {
     // `embeddable` is "created, not shown; somebody else will place me", and
     // on this backend that cannot be a window: a composition target stops
     // presenting the moment its window becomes a child, so an HWND is not
-    // something another process can take (docs/windows-embedding.md). What a
+    // something another process can take (design/windows-embedding.md). What a
     // host can take is the **buffer**, so an embeddable window here is the
     // same shared surface a `<Frame>` pane draws into — whether this process
     // was forked as a pane or is a guest somebody else started.
@@ -825,7 +825,7 @@ export class Win32App {
         break;
       }
       case 'dpichanged':
-        // The renderer cannot re-scale a live window yet (docs/windows.md
+        // The renderer cannot re-scale a live window yet (design/windows.md
         // §Layout, open question 8), so this is recorded and not acted on.
         wnd.emit('statechange', { scale: event.a / 96 });
         break;

package/src/win32/fonts.js

@@ -1,6 +1,6 @@
 // The Windows text engine: DirectWrite behind the same `app.fonts` contract
 // ntk's FontManager answers on X11 and CoreText answers on macOS. The renderer
-// touches exactly this surface (docs/windows.md §"Text"):
+// touches exactly this surface (design/windows.md §"Text"):
 //
 //   fonts.layout(spans, base, { maxWidth, align, lineHeight, maxLines,
 //                               overflow, direction })