@tobq/boardclip 0.0.0-stage → 2.1.107

package/lib/sync-paths.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const path = require('path');
+const { probePath } = require('./fs-probe');
+
+// A custom sync folder may be a network share, and a wedged one never answers a
+// synchronous existence check - the same failure that froze the app on
+// 2026-09-13. Every provider path, including this one, gets a deadline.
+const MOUNT_PROBE_TIMEOUT_MS = 2000;
+const exists = target => probePath(target, { timeoutMs: MOUNT_PROBE_TIMEOUT_MS });
+
+function normalizeSyncPath(syncPath) {
+  const normalized = path.normalize(String(syncPath || '').trim());
+  if (!normalized || !path.isAbsolute(normalized)) return '';
+  return normalized;
+}
+
+function migrateSyncSettings(settings) {
+  if (!settings) return settings;
+  const customPaths = [
+    settings.sync_path,
+    ...(Array.isArray(settings.sync_custom_paths) ? settings.sync_custom_paths : []),
+  ].map(normalizeSyncPath).filter(Boolean);
+  settings.sync_custom_paths = [...new Set(customPaths)];
+  settings.sync_path = settings.sync_custom_paths[0] || '';
+  if (!Array.isArray(settings.sync_disabled_paths)) settings.sync_disabled_paths = [];
+  settings.sync_disabled_paths = [...new Set(settings.sync_disabled_paths.map(normalizeSyncPath).filter(Boolean))];
+  return settings;
+}
+
+function customSyncPaths(settings) {
+  migrateSyncSettings(settings);
+  return settings.sync_custom_paths || [];
+}
+
+function addCustomSyncPath(settings, syncPath) {
+  const normalized = normalizeSyncPath(syncPath);
+  if (!normalized) return '';
+  const paths = new Set(customSyncPaths(settings));
+  paths.add(normalized);
+  settings.sync_custom_paths = [...paths];
+  settings.sync_path = settings.sync_custom_paths[0] || '';
+  return normalized;
+}
+
+function syncDisabledPathSet(settings) {
+  migrateSyncSettings(settings);
+  return new Set((settings.sync_disabled_paths || []).map(normalizeSyncPath).filter(Boolean));
+}
+
+async function syncAccountsWithCustom(settings, accounts) {
+  const result = [...(accounts || [])];
+  for (const customPath of customSyncPaths(settings)) {
+    const available = (await exists(customPath)) || (await exists(path.dirname(customPath)));
+    if (!available || result.some(acc => normalizeSyncPath(acc.path) === customPath)) continue;
+    result.push({
+      provider: 'custom',
+      label: path.basename(customPath) || customPath,
+      email: '',
+      path: customPath,
+    });
+  }
+  return result;
+}
+
+module.exports = {
+  normalizeSyncPath,
+  migrateSyncSettings,
+  customSyncPaths,
+  addCustomSyncPath,
+  syncDisabledPathSet,
+  syncAccountsWithCustom,
+};

package/lib/tailscale.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// Tailscale peer enrichment for P2P discovery. When the tailscale CLI is
+// installed, `tailscale status --json` lists every device on the tailnet with
+// its 100.64/10 address and online state; the app unicasts its discovery
+// announcement to the online ones, so two devices on different networks pair
+// over the (already encrypted) tailnet with no relay of our own. No CLI -> the
+// synced endpoint registry and manual pins still work.
+
+const fs = require('fs');
+const path = require('path');
+const { execFile } = require('child_process');
+
+const CANDIDATES = {
+  win32: ['C:\\Program Files\\Tailscale\\tailscale.exe', 'C:\\Program Files (x86)\\Tailscale\\tailscale.exe'],
+  darwin: [
+    '/Applications/Tailscale.app/Contents/MacOS/Tailscale',
+    '/opt/homebrew/bin/tailscale',
+    '/usr/local/bin/tailscale',
+  ],
+  linux: ['/usr/bin/tailscale', '/usr/local/bin/tailscale'],
+};
+
+const IPV4_RE = /^\d{1,3}(\.\d{1,3}){3}$/;
+
+function findBinary({ platform = process.platform, exists = fs.existsSync, pathEnv = process.env.PATH || '' } = {}) {
+  for (const candidate of CANDIDATES[platform] || []) {
+    if (exists(candidate)) return candidate;
+  }
+  const exe = platform === 'win32' ? 'tailscale.exe' : 'tailscale';
+  const sep = platform === 'win32' ? ';' : ':';
+  const join = platform === 'win32' ? path.win32.join : path.posix.join;
+  for (const dir of pathEnv.split(sep).filter(Boolean)) {
+    const candidate = join(dir, exe);
+    if (exists(candidate)) return candidate;
+  }
+  return '';
+}
+
+function ipv4Of(list) {
+  return (Array.isArray(list) ? list : []).map(String).filter(ip => IPV4_RE.test(ip));
+}
+
+function parseStatus(status) {
+  if (!status || typeof status !== 'object') return { available: false, self: null, peers: [] };
+  const self = status.Self && typeof status.Self === 'object' ? {
+    name: String(status.Self.HostName || ''),
+    dnsName: String(status.Self.DNSName || '').replace(/\.$/, ''),
+    ips: ipv4Of(status.Self.TailscaleIPs || status.TailscaleIPs),
+    online: !!status.Self.Online,
+  } : null;
+  const peers = [];
+  for (const raw of Object.values(status.Peer && typeof status.Peer === 'object' ? status.Peer : {})) {
+    if (!raw || typeof raw !== 'object') continue;
+    peers.push({
+      id: String(raw.ID || raw.NodeID || raw.PublicKey || ''),
+      name: String(raw.HostName || ''),
+      dnsName: String(raw.DNSName || '').replace(/\.$/, ''),
+      os: String(raw.OS || ''),
+      ips: ipv4Of(raw.TailscaleIPs),
+      online: !!raw.Online,
+    });
+  }
+  peers.sort((a, b) => a.name.localeCompare(b.name));
+  return { available: true, backend: String(status.BackendState || ''), self, peers };
+}
+
+function readStatus({ binary = findBinary(), timeoutMs = 5000, exec = execFile } = {}) {
+  if (!binary) return Promise.resolve({ available: false, self: null, peers: [] });
+  return new Promise(resolve => {
+    exec(binary, ['status', '--json'], { timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, windowsHide: true }, (error, stdout) => {
+      if (error) { resolve({ available: false, error: error.message, self: null, peers: [] }); return; }
+      try { resolve(parseStatus(JSON.parse(String(stdout)))); } catch (parseError) {
+        resolve({ available: false, error: parseError.message, self: null, peers: [] });
+      }
+    });
+  });
+}
+
+module.exports = { findBinary, parseStatus, readStatus, CANDIDATES };

package/lib/text-blob-store.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const clipboardModel = require('./clipboard-model');
+const clipBlobStore = require('./clip-blob-store');
+
+// The text payload's blob store. The mechanics (hashing, atomic write, hydrate,
+// externalize-above-threshold, sync filter, unreferenced cleanup) live once in
+// lib/blob-field-store.js and are instantiated per clipboard format in
+// lib/clip-blob-store.js — this module is the text instance's public face, kept
+// under its original name and signatures so every existing caller and test is
+// unaffected by the generalisation.
+const store = clipBlobStore.text;
+
+function setInlineText(item, text) {
+  if (!item || item.type === 'image') return item;
+  // Deliberately the MODEL's setInlineText, not the field store's: an edit must
+  // also drop the html/rtf payloads, which describe the pre-edit text. The
+  // field store only knows about its own field.
+  clipboardModel.setInlineText(item, text);
+  store.setInlineValue(item, item.text);
+  return item;
+}
+
+module.exports = {
+  TEXT_BLOB_DIRNAME: clipBlobStore.TEXT_BLOB_DIRNAME,
+  TEXT_BLOB_THRESHOLD_BYTES: store.thresholdBytes,
+  TEXT_PREVIEW_CHARS: clipBlobStore.TEXT_PREVIEW_CHARS,
+  textRefForHash: store.refForHash,
+  safeTextRef: store.safeRef,
+  textPreview: store.preview,
+  hydrateTextItem: (item, baseDir) => store.hydrateItem(item, baseDir),
+  hydrateHistory: (items, baseDir) => store.hydrateHistory(items, baseDir),
+  prepareTextItemForStorage: (item, baseDir, options) => store.prepareItemForStorage(item, baseDir, options),
+  prepareHistoryForStorage: (items, baseDir, options) => store.prepareHistoryForStorage(items, baseDir, options),
+  syncTextBlobs: (localDir, remoteDir) => store.syncBlobs(localDir, remoteDir),
+  removeLocalBlobIfUnreferenced: (item, items, baseDir) => store.removeLocalBlobIfUnreferenced(item, items, baseDir),
+  setInlineText,
+};

package/lib/windows-clipboard.js

@@ -0,0 +1,213 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+if (process.platform !== 'win32') {
+  module.exports = {
+    getSequenceNumber() { return 0; },
+    readImageCandidate() { return null; },
+    dibToBmpBuffer,
+  };
+  return;
+}
+
+const koffi = require('koffi');
+
+const user32 = koffi.load('user32.dll');
+const kernel32 = koffi.load('kernel32.dll');
+const shell32 = koffi.load('shell32.dll');
+
+const OpenClipboard = user32.func('int __stdcall OpenClipboard(void *hWndNewOwner)');
+const CloseClipboard = user32.func('int __stdcall CloseClipboard()');
+const GetClipboardData = user32.func('void * __stdcall GetClipboardData(uint32 uFormat)');
+const IsClipboardFormatAvailable = user32.func('int __stdcall IsClipboardFormatAvailable(uint32 format)');
+const RegisterClipboardFormatW = user32.func('uint32 __stdcall RegisterClipboardFormatW(str16 lpszFormat)');
+const GetClipboardSequenceNumber = user32.func('uint32 __stdcall GetClipboardSequenceNumber()');
+
+const GlobalLock = kernel32.func('void * __stdcall GlobalLock(void *hMem)');
+const GlobalUnlock = kernel32.func('int __stdcall GlobalUnlock(void *hMem)');
+const GlobalSize = kernel32.func('uintptr_t __stdcall GlobalSize(void *hMem)');
+
+const DragQueryFileW = shell32.func('uint32 __stdcall DragQueryFileW(void *hDrop, uint32 iFile, void *lpszFile, uint32 cch)');
+
+const CF_BITMAP = 2;
+const CF_DIB = 8;
+const CF_HDROP = 15;
+const MAX_IMAGE_FILE_BYTES = 100 * 1024 * 1024;
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.bmp', '.gif', '.webp', '.tif', '.tiff', '.heic', '.heif']);
+const registeredFormats = new Map();
+
+function getSequenceNumber() {
+  try { return GetClipboardSequenceNumber() >>> 0; } catch { return 0; }
+}
+
+function registeredFormat(name) {
+  if (!registeredFormats.has(name)) registeredFormats.set(name, RegisterClipboardFormatW(name) >>> 0);
+  return registeredFormats.get(name);
+}
+
+function pointerToBuffer(ptr, size) {
+  const length = Number(size) || 0;
+  if (!ptr || length <= 0) return null;
+  try {
+    return Buffer.from(koffi.decode(ptr, 'uint8_t', length));
+  } catch { return null; }
+}
+
+function readGlobalMemory(format) {
+  if (!format || !IsClipboardFormatAvailable(format)) return null;
+  const handle = GetClipboardData(format);
+  if (!handle) return null;
+  const size = Number(GlobalSize(handle)) || 0;
+  if (size <= 0) return null;
+  const ptr = GlobalLock(handle);
+  if (!ptr) return null;
+  try {
+    return pointerToBuffer(ptr, size);
+  } finally {
+    try { GlobalUnlock(handle); } catch {}
+  }
+}
+
+function withOpenClipboard(fn) {
+  if (!OpenClipboard(null)) return null;
+  try { return fn(); } finally { try { CloseClipboard(); } catch {} }
+}
+
+function hasPngSignature(buffer) {
+  return Buffer.isBuffer(buffer)
+    && buffer.length >= 8
+    && buffer[0] === 0x89
+    && buffer[1] === 0x50
+    && buffer[2] === 0x4e
+    && buffer[3] === 0x47
+    && buffer[4] === 0x0d
+    && buffer[5] === 0x0a
+    && buffer[6] === 0x1a
+    && buffer[7] === 0x0a;
+}
+
+function stringFromUtf16Buffer(buffer) {
+  if (!Buffer.isBuffer(buffer)) return '';
+  let end = 0;
+  while (end + 1 < buffer.length && buffer.readUInt16LE(end) !== 0) end += 2;
+  return buffer.toString('utf16le', 0, end).trim();
+}
+
+function stringFromAnsiBuffer(buffer) {
+  if (!Buffer.isBuffer(buffer)) return '';
+  const nul = buffer.indexOf(0);
+  return buffer.toString('latin1', 0, nul >= 0 ? nul : buffer.length).trim();
+}
+
+function isImagePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return false;
+  const ext = path.extname(filePath).toLowerCase();
+  if (!IMAGE_EXTENSIONS.has(ext)) return false;
+  try {
+    const stat = fs.statSync(filePath);
+    return stat.isFile() && stat.size > 0 && stat.size <= MAX_IMAGE_FILE_BYTES;
+  } catch {
+    return false;
+  }
+}
+
+function readHdropPathsOpen() {
+  if (!IsClipboardFormatAvailable(CF_HDROP)) return [];
+  const hDrop = GetClipboardData(CF_HDROP);
+  if (!hDrop) return [];
+  const count = DragQueryFileW(hDrop, 0xffffffff, null, 0);
+  const paths = [];
+  for (let i = 0; i < count; i += 1) {
+    const chars = DragQueryFileW(hDrop, i, null, 0);
+    if (!chars) continue;
+    const buffer = Buffer.alloc((chars + 1) * 2);
+    const written = DragQueryFileW(hDrop, i, buffer, chars + 1);
+    if (written) paths.push(buffer.toString('utf16le', 0, written * 2));
+  }
+  return paths;
+}
+
+function readNamedFilePathsOpen() {
+  const paths = [];
+  const fileNameW = readGlobalMemory(registeredFormat('FileNameW'));
+  const fileNameA = readGlobalMemory(registeredFormat('FileName'));
+  const wide = stringFromUtf16Buffer(fileNameW);
+  const ansi = stringFromAnsiBuffer(fileNameA);
+  if (wide) paths.push(wide);
+  if (ansi) paths.push(ansi);
+  return paths;
+}
+
+function readImageFileCandidateOpen() {
+  const paths = [...readHdropPathsOpen(), ...readNamedFilePathsOpen()];
+  const imagePath = paths.find(isImagePath);
+  if (!imagePath) return null;
+  try {
+    return { buffer: fs.readFileSync(imagePath), source: 'win32-file', path: imagePath };
+  } catch {
+    return null;
+  }
+}
+
+function readPngCandidateOpen() {
+  for (const name of ['PNG', 'image/png']) {
+    const buffer = readGlobalMemory(registeredFormat(name));
+    if (hasPngSignature(buffer)) return { buffer, source: `win32-${name}` };
+  }
+  return null;
+}
+
+function dibToBmpBuffer(dib) {
+  if (!Buffer.isBuffer(dib) || dib.length < 40) return null;
+  const headerSize = dib.readUInt32LE(0);
+  if (headerSize < 12 || headerSize > dib.length) return null;
+
+  let bitCount = 0;
+  let compression = 0;
+  let colorsUsed = 0;
+  if (headerSize >= 40 && dib.length >= 36) {
+    bitCount = dib.readUInt16LE(14);
+    compression = dib.readUInt32LE(16);
+    colorsUsed = dib.readUInt32LE(32);
+  }
+
+  const paletteEntries = colorsUsed || (bitCount > 0 && bitCount <= 8 ? 2 ** bitCount : 0);
+  const bitfieldBytes = compression === 3 && headerSize === 40 ? 12 : 0;
+  const pixelOffset = 14 + headerSize + bitfieldBytes + paletteEntries * 4;
+  if (pixelOffset > 14 + dib.length) return null;
+
+  const fileHeader = Buffer.alloc(14);
+  fileHeader.write('BM', 0, 'ascii');
+  fileHeader.writeUInt32LE(fileHeader.length + dib.length, 2);
+  fileHeader.writeUInt32LE(0, 6);
+  fileHeader.writeUInt32LE(pixelOffset, 10);
+  return Buffer.concat([fileHeader, dib]);
+}
+
+function readDibCandidateOpen() {
+  const dib = readGlobalMemory(CF_DIB);
+  const bmp = dibToBmpBuffer(dib);
+  return bmp ? { buffer: bmp, source: 'win32-dib' } : null;
+}
+
+function readImageCandidate() {
+  return withOpenClipboard(() => (
+    readImageFileCandidateOpen()
+    || readPngCandidateOpen()
+    || readDibCandidateOpen()
+    || (IsClipboardFormatAvailable(CF_BITMAP) ? { source: 'win32-bitmap-unreadable' } : null)
+  ));
+}
+
+module.exports = {
+  getSequenceNumber,
+  readImageCandidate,
+  dibToBmpBuffer,
+  _private: {
+    hasPngSignature,
+    stringFromUtf16Buffer,
+    isImagePath,
+  },
+};

package/lib/windows-console.js

@@ -0,0 +1,63 @@
+'use strict';
+
+// Detach from a console this process merely INHERITED on Windows.
+//
+// electron.exe attaches to whatever console its parent had. Launched from an
+// agent tool shell, a scheduled task or a helper cmd, the tray app then lives or
+// dies with that console: when it is closed, Windows sends a console control
+// event to every attached process and the whole tree stops within a second,
+// with no crash record (2026-09-03: two "random crashes" 26 and 58 min after
+// such launches; the Network Service child logged exit code 0xC000013A =
+// STATUS_CONTROL_C_EXIT). FreeConsole() makes the process independent of that
+// console for good.
+//
+// Policy (pure, unit-tested): if OTHER processes share the console it is
+// somebody else's (a shell that may close it) -> detach. If we are the only
+// process attached, the console is ours (the Startup VBS / start.bat path,
+// where cmd has already exited) and harmless -> keep. BOARDCLIP_KEEP_CONSOLE=1
+// keeps any console; a developer who wants `npx electron .` output in the
+// terminal sets it. A "visible window" heuristic was tried first and is WRONG:
+// an agent shell's hidden console still reports WS_VISIBLE. main.js guards
+// process.stdout/stderr against write errors and logs only via logSafe, so a
+// freed console never throws back into JS.
+
+function decideConsoleDetach({ platform = process.platform, env = process.env, hwnd = null, attached = 0 } = {}) {
+  if (platform !== 'win32') return { action: 'none', reason: 'not-windows' };
+  if (env && env.BOARDCLIP_KEEP_CONSOLE === '1') return { action: 'kept', reason: 'env' };
+  if (!hwnd) return { action: 'none', reason: 'no-console' };
+  if (attached > 1) return { action: 'detach', reason: 'shared-console' };
+  return { action: 'kept', reason: 'own-console' };
+}
+
+function loadNative() {
+  const koffi = require('koffi');
+  const kernel32 = koffi.load('kernel32.dll');
+  const getConsoleProcessList = kernel32.func('uint32 __stdcall GetConsoleProcessList(_Out_ uint32 *list, uint32 count)');
+  return {
+    getConsoleWindow: kernel32.func('void * __stdcall GetConsoleWindow()'),
+    freeConsole: kernel32.func('int __stdcall FreeConsole()'),
+    attachedProcessCount: () => {
+      const list = new Uint32Array(64);
+      return getConsoleProcessList(list, list.length);
+    },
+  };
+}
+
+// Returns what was done, for the app.start diagnostic. Never throws.
+function detachInheritedConsole({ platform = process.platform, env = process.env, native = null } = {}) {
+  if (platform !== 'win32') return { action: 'none', reason: 'not-windows' };
+  let api = native;
+  try {
+    if (!api) api = loadNative();
+    const hwnd = api.getConsoleWindow();
+    const attached = hwnd ? Number(api.attachedProcessCount()) || 0 : 0;
+    const decision = decideConsoleDetach({ platform, env, hwnd, attached });
+    if (decision.action !== 'detach') return { ...decision, attached };
+    const ok = !!api.freeConsole();
+    return { action: ok ? 'detached' : 'detach-failed', reason: decision.reason, attached };
+  } catch (error) {
+    return { action: 'error', reason: error && error.message };
+  }
+}
+
+module.exports = { decideConsoleDetach, detachInheritedConsole, loadNative };

package/lib/windows-dwm.js

@@ -0,0 +1,183 @@
+'use strict';
+
+// Windows only: PARK a window instead of hiding it. A parked window is cloaked
+// (DWMWA_CLOAK): it stays "shown" to Windows and Chromium - so its content stays
+// painted - but is not drawn, is not hit-tested (clicks go to the windows
+// beneath) and is not in Alt-Tab. It also gets WS_EX_NOACTIVATE while parked,
+// so Windows never hands it the focus when the foreground window closes or
+// minimizes (keystrokes would vanish into an invisible window). Unparking clears
+// both, and the window appears complete in ONE frame.
+//
+// Why (measured 2026-10-07 with a ~100 fps screen recording of the open): every
+// ShowWindow of the acrylic popup drew the glass backdrop at full size at once
+// while Windows scaled + faded the web CONTENT in ~130-200 ms later - the "opens
+// twice" rim the owner kept seeing. Neither DWMWA_TRANSITIONS_FORCEDISABLED nor
+// switching acrylic to mica changed it.
+//
+// Also here: the layered-window alpha a SOLID popup fades in with
+// (setWindowAlpha, then clearLayered) - see setWindowAlpha below.
+
+const DWMWA_CLOAK = 13;
+const GWL_EXSTYLE = -20;
+const WS_EX_NOACTIVATE = 0x08000000;
+const WS_EX_LAYERED = 0x00080000;
+const LWA_ALPHA = 0x2;
+const RDW_INVALIDATE = 0x1;
+const RDW_ERASE = 0x4;
+const RDW_ALLCHILDREN = 0x80;
+const RDW_FRAME = 0x400;
+// Predefined HKEYs are sign-extended LONGs: 64-bit needs the full pointer value.
+const HKEY_CURRENT_USER = process.arch === 'x64' || process.arch === 'arm64' ? 0xFFFFFFFF80000001n : 0x80000001;
+const RRF_RT_REG_DWORD = 0x10;
+let api = null;
+
+function loadNative() {
+  const koffi = require('koffi');
+  const dwmapi = koffi.load('dwmapi.dll');
+  const user32 = koffi.load('user32.dll');
+  // 64-bit user32 has the *Ptr variants; 32-bit only exports the plain ones.
+  let getLong;
+  let setLong;
+  try {
+    getLong = user32.func('intptr_t __stdcall GetWindowLongPtrW(uintptr_t hwnd, int index)');
+    setLong = user32.func('intptr_t __stdcall SetWindowLongPtrW(uintptr_t hwnd, int index, intptr_t value)');
+  } catch {
+    getLong = user32.func('long __stdcall GetWindowLongW(uintptr_t hwnd, int index)');
+    setLong = user32.func('long __stdcall SetWindowLongW(uintptr_t hwnd, int index, long value)');
+  }
+  const setLayered = user32.func('int __stdcall SetLayeredWindowAttributes(uintptr_t hwnd, uint32 key, uint8 alpha, uint32 flags)');
+  const getLayered = user32.func('int __stdcall GetLayeredWindowAttributes(uintptr_t hwnd, _Out_ uint32 *key, _Out_ uint8 *alpha, _Out_ uint32 *flags)');
+  const redraw = user32.func('int __stdcall RedrawWindow(uintptr_t hwnd, void *rect, void *region, uint32 flags)');
+  const regGetValue = koffi.load('advapi32.dll').func('int32 __stdcall RegGetValueW(uintptr_t hkey, str16 subKey, str16 value, uint32 flags, void *type, _Out_ uint32 *data, _Inout_ uint32 *size)');
+  return {
+    setAttribute: dwmapi.func('int32 __stdcall DwmSetWindowAttribute(uintptr_t hwnd, uint32 attr, void *value, uint32 size)'),
+    getExStyle: (hwnd) => Number(getLong(hwnd, GWL_EXSTYLE)),
+    setExStyle: (hwnd, style) => setLong(hwnd, GWL_EXSTYLE, style),
+    setLayeredAlpha: (hwnd, alpha) => setLayered(hwnd, 0, alpha, LWA_ALPHA) !== 0,
+    getLayeredAlpha: (hwnd) => {
+      const key = [0];
+      const alpha = [0];
+      const flags = [0];
+      if (!getLayered(hwnd, key, alpha, flags)) return null;
+      return (flags[0] & LWA_ALPHA) ? alpha[0] : 255;
+    },
+    redraw: (hwnd) => redraw(hwnd, null, null, RDW_ERASE | RDW_INVALIDATE | RDW_FRAME | RDW_ALLCHILDREN) !== 0,
+    // HKCU DWORD value, or null when it is missing.
+    readDword: (key, name) => {
+      const data = [0];
+      const size = [4];
+      return regGetValue(HKEY_CURRENT_USER, key, name, RRF_RT_REG_DWORD, null, data, size) === 0 ? data[0] >>> 0 : null;
+    },
+  };
+}
+
+// Electron's getNativeWindowHandle() is a Buffer holding the HWND value.
+function hwndFromHandle(buf) {
+  if (!buf || !buf.length) return 0n;
+  return buf.length >= 8 ? buf.readBigUInt64LE(0) : BigInt(buf.readUInt32LE(0));
+}
+
+// -> { ok, hr?, noActivate?, reason? }. `ok` is the cloak result (the part that
+// matters); the focus guard is best effort. Never throws: a caller that gets
+// !ok falls back to an ordinary hide/show.
+function setParked(win, parked, { platform = process.platform, native = null } = {}) {
+  if (platform !== 'win32') return { ok: false, reason: 'not-win32' };
+  if (!win || (typeof win.isDestroyed === 'function' && win.isDestroyed())) return { ok: false, reason: 'no-window' };
+  try {
+    const n = native || api || (api = loadNative());
+    const hwnd = hwndFromHandle(win.getNativeWindowHandle());
+    let noActivate = false;
+    try {
+      const style = n.getExStyle(hwnd);
+      n.setExStyle(hwnd, parked ? (style | WS_EX_NOACTIVATE) : (style & ~WS_EX_NOACTIVATE));
+      noActivate = true;
+    } catch {}
+    const value = Buffer.alloc(4);
+    value.writeInt32LE(parked ? 1 : 0, 0);
+    const hr = n.setAttribute(hwnd, DWMWA_CLOAK, value, 4);
+    return { ok: hr === 0, hr, noActivate };
+  } catch (error) {
+    return { ok: false, reason: error && error.message };
+  }
+}
+
+// The open fade of a SOLID window (plan I): a constant window alpha through
+// WS_EX_LAYERED, done here rather than with BrowserWindow.setOpacity, which
+// sets the style once and records it as set for good - after clearLayered()
+// its next setOpacity would quietly do nothing. Electron never learns of the
+// style, so its own opacity stays 1. Never on glass: a layered window drops
+// the acrylic (recorded frame by frame 2026-10-07).
+// -> { ok, alpha?, reason? }; alpha 0..1. Never throws.
+function setWindowAlpha(win, alpha, { platform = process.platform, native = null } = {}) {
+  if (platform !== 'win32') return { ok: false, reason: 'not-win32' };
+  if (!win || (typeof win.isDestroyed === 'function' && win.isDestroyed())) return { ok: false, reason: 'no-window' };
+  try {
+    const n = native || api || (api = loadNative());
+    const hwnd = hwndFromHandle(win.getNativeWindowHandle());
+    const byte = Math.max(0, Math.min(255, Math.round((Number(alpha) || 0) * 255)));
+    const style = n.getExStyle(hwnd);
+    if (!(style & WS_EX_LAYERED)) n.setExStyle(hwnd, style | WS_EX_LAYERED);
+    return { ok: !!n.setLayeredAlpha(hwnd, byte), alpha: byte };
+  } catch (error) {
+    return { ok: false, reason: error && error.message };
+  }
+}
+
+// Ends a fade: drops WS_EX_LAYERED (the alpha goes with it, the window is a
+// normal opaque window again) and invalidates it, the documented way out of
+// layering. -> { ok, wasLayered?, reason? }. Never throws.
+function clearLayered(win, { platform = process.platform, native = null } = {}) {
+  if (platform !== 'win32') return { ok: false, reason: 'not-win32' };
+  if (!win || (typeof win.isDestroyed === 'function' && win.isDestroyed())) return { ok: false, reason: 'no-window' };
+  try {
+    const n = native || api || (api = loadNative());
+    const hwnd = hwndFromHandle(win.getNativeWindowHandle());
+    const style = n.getExStyle(hwnd);
+    if (!(style & WS_EX_LAYERED)) return { ok: true, wasLayered: false };
+    n.setExStyle(hwnd, style & ~WS_EX_LAYERED);
+    n.redraw(hwnd);
+    return { ok: !(n.getExStyle(hwnd) & WS_EX_LAYERED), wasLayered: true };
+  } catch (error) {
+    return { ok: false, reason: error && error.message };
+  }
+}
+
+// -> { layered, alpha (0-255; 255 when not layered) } or null. For QA checks.
+function layeredState(win, { platform = process.platform, native = null } = {}) {
+  if (platform !== 'win32' || !win || (typeof win.isDestroyed === 'function' && win.isDestroyed())) return null;
+  try {
+    const n = native || api || (api = loadNative());
+    const hwnd = hwndFromHandle(win.getNativeWindowHandle());
+    const layered = !!(n.getExStyle(hwnd) & WS_EX_LAYERED);
+    return { layered, alpha: layered ? n.getLayeredAlpha(hwnd) : 255 };
+  } catch {
+    return null;
+  }
+}
+
+// The Windows accent colour as Settings > Personalization > Colors shows it.
+// Electron's systemPreferences.getAccentColor() returns DwmGetColorizationColor,
+// a BLENDED title-bar colorization (measured 2026-10-08: 0xe3006fc4 for the
+// 0078d4 accent the Settings palette shows), so the value Settings writes is
+// read instead. The DWORDs are 0xAABBGGRR. -> '#rrggbb' | null. Never throws.
+const ACCENT_VALUES = [
+  ['Software\\Microsoft\\Windows\\DWM', 'AccentColor'],
+  ['Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Accent', 'AccentColorMenu'],
+];
+function abgrToHex(dword) {
+  const n = Number(dword) >>> 0;
+  return `#${[n & 0xff, (n >>> 8) & 0xff, (n >>> 16) & 0xff].map((c) => c.toString(16).padStart(2, '0')).join('')}`;
+}
+function readAccentColor({ platform = process.platform, native = null } = {}) {
+  if (platform !== 'win32') return null;
+  try {
+    const n = native || api || (api = loadNative());
+    for (const [key, name] of ACCENT_VALUES) {
+      const dword = n.readDword(key, name);
+      if (dword != null) return abgrToHex(dword);
+    }
+  } catch {}
+  return null;
+}
+
+module.exports = { setParked, setWindowAlpha, clearLayered, layeredState, readAccentColor, abgrToHex, hwndFromHandle, DWMWA_CLOAK, WS_EX_NOACTIVATE, WS_EX_LAYERED };