novac 2.1.1 → 2.2.0

package/kits/kitclippy/kitdef.js

@@ -0,0 +1,925 @@
+// kitdef.js — kitClipboard
+// Cross-platform clipboard management: read, write, file copy, format detection,
+// history, monitoring, paste detection, and more.
+//
+// Platform support: Windows, macOS, Linux (X11/Wayland), Android (Termux), iOS
+// Backends: pbcopy/pbpaste (macOS), xclip/xsel/wl-clipboard (Linux),
+//           clip/powershell (Windows), Termux API (Android)
+//
+// const { kitClipboard } = require('./kitdef').kitdef;
+
+const { execSync, execFileSync, spawn } = require("child_process");
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+
+// ── Platform detection ───────────────────────────────────────────────────────
+
+function _platform() {
+  const p = process.platform;
+  if (p === "darwin") return "macos";
+  if (p === "win32")  return "windows";
+  if (p === "android" || process.env.TERMUX_VERSION) return "android";
+  // Linux: detect Wayland vs X11
+  if (process.env.WAYLAND_DISPLAY) return "wayland";
+  if (process.env.DISPLAY)         return "x11";
+  return "linux"; // fallback
+}
+
+function _hasCmd(cmd) {
+  try { execSync(`command -v ${cmd}`, { stdio: "pipe" }); return true; }
+  catch { return false; }
+}
+
+function _linuxBackend() {
+  if (_platform() === "wayland" && _hasCmd("wl-copy")) return "wayland";
+  if (_hasCmd("xclip"))  return "xclip";
+  if (_hasCmd("xsel"))   return "xsel";
+  if (_hasCmd("wl-copy")) return "wayland";
+  throw new Error("No clipboard backend found. Install xclip, xsel, or wl-clipboard.");
+}
+
+// ── Bracketed Paste Mode (terminal escape sequence) ──────────────────────────
+//
+// When a terminal supports bracketed paste mode (\x1b[?2004h), pasted text is
+// wrapped between \x1b[200~ ... \x1b[201~, making it unambiguously distinct
+// from keyboard input.  We enable it on stdin when it's a TTY, listen for the
+// markers, and set a flag that detectSource() can read.
+//
+// References:
+//   https://cirw.in/blog/bracketed-paste
+//   https://invisible-island.net/xterm/ctlseqs/ctlseqs.html  (DEC mode 2004)
+
+const PASTE_START = "\x1b[200~";
+const PASTE_END   = "\x1b[201~";
+const BP_ENABLE   = "\x1b[?2004h";
+const BP_DISABLE  = "\x1b[?2004l";
+
+let _bracketedPasteSupported = false;
+let _lastInputSource         = "unknown"; // "paste" | "typed" | "unknown"
+let _bpBuffer                = "";        // accumulates raw stdin bytes
+
+function _enableBracketedPaste() {
+  if (!process.stdin.isTTY) return;
+  try {
+    process.stdout.write(BP_ENABLE);
+    _bracketedPasteSupported = true;
+
+    if (process.stdin.setRawMode) process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    process.stdin.on("data", (chunk) => {
+      _bpBuffer += chunk;
+
+      // Consume all complete bracketed-paste sequences
+      let start;
+      while ((start = _bpBuffer.indexOf(PASTE_START)) !== -1) {
+        const end = _bpBuffer.indexOf(PASTE_END, start + PASTE_START.length);
+        if (end === -1) break; // incomplete sequence — wait for more data
+        // Everything between the markers is pasted text
+        _lastInputSource = "paste";
+        _bpBuffer = _bpBuffer.slice(0, start) + _bpBuffer.slice(end + PASTE_END.length);
+      }
+
+      // Anything left in the buffer (outside markers) is typed
+      if (_bpBuffer.length > 0 && !_bpBuffer.includes(PASTE_START)) {
+        _lastInputSource = "typed";
+        _bpBuffer = "";
+      }
+    });
+
+    // Restore terminal on exit
+    const _restore = () => {
+      try { process.stdout.write(BP_DISABLE); } catch {}
+    };
+    process.once("exit",   _restore);
+    process.once("SIGINT",  () => { _restore(); process.exit(130); });
+    process.once("SIGTERM", () => { _restore(); process.exit(143); });
+  } catch {
+    // Non-TTY or terminal doesn't support bracketed paste — fall through to
+    // the content-fingerprint fallback in detectSource().
+    _bracketedPasteSupported = false;
+  }
+}
+
+// Attempt to enable bracketed paste immediately.
+_enableBracketedPaste();
+
+// ── Internal state ───────────────────────────────────────────────────────────
+
+const _history   = [];   // { text, timestamp, source }
+const _MAX_HIST  = 100;
+let   _lastWrite = null; // timestamp of last kitClipboard.write() call
+let   _lastWriteContent = null; // exact string written — used by content-fingerprint fallback
+let   _watchTimer = null;
+let   _watchLast  = null;
+
+function _pushHistory(text, source = "external") {
+  _history.unshift({ text, timestamp: Date.now(), source });
+  if (_history.length > _MAX_HIST) _history.pop();
+}
+
+// ── Low-level read/write ─────────────────────────────────────────────────────
+
+function _read() {
+  const plat = _platform();
+  switch (plat) {
+    case "macos":
+      return execSync("pbpaste", { encoding: "utf8" });
+
+    case "windows":
+      // PowerShell gives us Unicode-safe clipboard access
+      return execSync(
+        `powershell -NoProfile -NonInteractive -Command "Get-Clipboard"`,
+        { encoding: "utf8" }
+      ).replace(/\r\n/g, "\n");
+
+    case "android":
+      return execSync("termux-clipboard-get", { encoding: "utf8" });
+
+    case "wayland": {
+      const backend = _linuxBackend();
+      if (backend === "wayland") return execSync("wl-paste --no-newline", { encoding: "utf8" });
+      // fallthrough to x11 backends
+    }
+    // eslint-disable-next-line no-fallthrough
+    case "x11":
+    case "linux": {
+      const backend = _linuxBackend();
+      if (backend === "xclip")   return execSync("xclip -selection clipboard -o", { encoding: "utf8" });
+      if (backend === "xsel")    return execSync("xsel --clipboard --output", { encoding: "utf8" });
+      if (backend === "wayland") return execSync("wl-paste --no-newline", { encoding: "utf8" });
+      throw new Error("No clipboard backend available.");
+    }
+
+    default:
+      throw new Error(`Unsupported platform: ${plat}`);
+  }
+}
+
+function _write(text) {
+  const plat = _platform();
+  switch (plat) {
+    case "macos":
+      execSync("pbcopy", { input: text, stdio: ["pipe", "ignore", "ignore"] });
+      break;
+
+    case "windows":
+      // Use clip.exe for simple text; PowerShell for Unicode safety
+      execSync(
+        `powershell -NoProfile -NonInteractive -Command "Set-Clipboard -Value @'\n${text.replace(/'/g, "''")}\n'@"`,
+        { stdio: "pipe" }
+      );
+      break;
+
+    case "android":
+      execSync(`termux-clipboard-set`, { input: text, stdio: ["pipe", "ignore", "ignore"] });
+      break;
+
+    case "wayland":
+    case "x11":
+    case "linux": {
+      const backend = _linuxBackend();
+      if (backend === "xclip")
+        execSync("xclip -selection clipboard", { input: text, stdio: ["pipe", "ignore", "ignore"] });
+      else if (backend === "xsel")
+        execSync("xsel --clipboard --input", { input: text, stdio: ["pipe", "ignore", "ignore"] });
+      else if (backend === "wayland")
+        execSync("wl-copy", { input: text, stdio: ["pipe", "ignore", "ignore"] });
+      break;
+    }
+
+    default:
+      throw new Error(`Unsupported platform: ${plat}`);
+  }
+}
+
+// ── Export ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+
+    name: "kitClipboard",
+    version: "1.0.0",
+    description: "Cross-platform clipboard management: read, write, file copy, history, monitoring, format detection, and paste detection.",
+
+    // ──────────────────────────────────────────────────────────────────────
+    // READ
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Read the current clipboard contents as a string.
+     * @returns {string}
+     *
+     * @example
+     *   const text = kitClipboard.read();
+     */
+    read() {
+      return _read();
+    },
+
+    /**
+     * Read clipboard and return trimmed text.
+     * @returns {string}
+     */
+    readTrimmed() {
+      return _read().trim();
+    },
+
+    /**
+     * Read clipboard and parse as JSON.
+     * Throws if content is not valid JSON.
+     * @returns {any}
+     */
+    readJSON() {
+      const text = _read().trim();
+      try { return JSON.parse(text); }
+      catch { throw new Error("Clipboard content is not valid JSON."); }
+    },
+
+    /**
+     * Read clipboard and split into lines.
+     * @param {{ keepEmpty?: boolean }} [options]
+     * @returns {string[]}
+     */
+    readLines(options = {}) {
+      const lines = _read().split("\n");
+      return options.keepEmpty ? lines : lines.filter(l => l.trim().length > 0);
+    },
+
+    /**
+     * Read clipboard and return as a Buffer.
+     * @returns {Buffer}
+     */
+    readBuffer() {
+      return Buffer.from(_read(), "utf8");
+    },
+
+    /**
+     * Read clipboard and return as a base64 string.
+     * @returns {string}
+     */
+    readBase64() {
+      return Buffer.from(_read(), "utf8").toString("base64");
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // WRITE
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Write text to the clipboard.
+     * @param {string} text
+     * @returns {{ written: string, length: number }}
+     *
+     * @example
+     *   kitClipboard.write("Hello, world!");
+     */
+    write(text) {
+      const str = String(text);
+      _lastWrite = Date.now();
+      _lastWriteContent = str;    // fingerprint fallback: remember exact content
+      _lastInputSource  = "unknown"; // clear TTY source — clipboard is now ours
+      _write(str);
+      _pushHistory(str, "write");
+      return { written: str, length: str.length };
+    },
+
+    /**
+     * Write JSON to the clipboard (pretty-printed).
+     * @param {any} value
+     * @param {number} [indent=2]
+     * @returns {{ written: string }}
+     */
+    writeJSON(value, indent = 2) {
+      return this.write(JSON.stringify(value, null, indent));
+    },
+
+    /**
+     * Append text to existing clipboard content.
+     * @param {string} text
+     * @param {string} [separator="\n"]
+     * @returns {{ written: string }}
+     */
+    append(text, separator = "\n") {
+      const current = _read();
+      return this.write(current + separator + text);
+    },
+
+    /**
+     * Prepend text to existing clipboard content.
+     * @param {string} text
+     * @param {string} [separator="\n"]
+     * @returns {{ written: string }}
+     */
+    prepend(text, separator = "\n") {
+      const current = _read();
+      return this.write(text + separator + current);
+    },
+
+    /**
+     * Clear the clipboard.
+     * @returns {{ status: string }}
+     */
+    clear() {
+      _write("");
+      _lastWrite = Date.now();
+      return { status: "CLEARED" };
+    },
+
+    /**
+     * Write from a Buffer or base64 string.
+     * @param {Buffer|string} data
+     * @returns {{ written: number }}
+     */
+    writeBuffer(data) {
+      const str = Buffer.isBuffer(data)
+        ? data.toString("utf8")
+        : Buffer.from(data, "base64").toString("utf8");
+      _write(str);
+      _lastWrite = Date.now();
+      _pushHistory(str, "writeBuffer");
+      return { written: str.length };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // FILE OPERATIONS
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Copy the contents of a file to the clipboard.
+     * @param {string} filePath
+     * @param {BufferEncoding} [encoding="utf8"]
+     * @returns {{ file: string, length: number }}
+     *
+     * @example
+     *   kitClipboard.copyFile("./README.md");
+     */
+    copyFile(filePath, encoding = "utf8") {
+      const resolved = filePath.replace(/^~/, os.homedir());
+      const content  = fs.readFileSync(resolved, encoding);
+      this.write(content);
+      return { file: resolved, length: content.length };
+    },
+
+    /**
+     * Save the current clipboard content to a file.
+     * @param {string} filePath
+     * @param {BufferEncoding} [encoding="utf8"]
+     * @returns {{ file: string, length: number }}
+     *
+     * @example
+     *   kitClipboard.saveToFile("./output.txt");
+     */
+    saveToFile(filePath, encoding = "utf8") {
+      const resolved = filePath.replace(/^~/, os.homedir());
+      const content  = _read();
+      fs.writeFileSync(resolved, content, encoding);
+      return { file: resolved, length: content.length };
+    },
+
+    /**
+     * Append the current clipboard content to a file.
+     * @param {string} filePath
+     * @returns {{ file: string, appended: number }}
+     */
+    appendToFile(filePath) {
+      const resolved = filePath.replace(/^~/, os.homedir());
+      const content  = _read();
+      fs.appendFileSync(resolved, content, "utf8");
+      return { file: resolved, appended: content.length };
+    },
+
+    /**
+     * Copy multiple files' contents to clipboard, joined by a separator.
+     * @param {string[]} filePaths
+     * @param {string} [separator="\n---\n"]
+     * @returns {{ files: string[], totalLength: number }}
+     */
+    copyFiles(filePaths, separator = "\n---\n") {
+      const contents = filePaths.map(f => {
+        const resolved = f.replace(/^~/, os.homedir());
+        return `// ${path.basename(resolved)}\n` + fs.readFileSync(resolved, "utf8");
+      });
+      const joined = contents.join(separator);
+      this.write(joined);
+      return { files: filePaths, totalLength: joined.length };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // PASTE DETECTION
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Detect whether the current clipboard content was written programmatically
+     * (via kitClipboard.write()) or pasted/typed by a human.
+     *
+     * Three-tier detection strategy (most → least reliable):
+     *
+     *   TIER 1 — Terminal bracketed paste mode (exact, ~100%)
+     *     If the process is running in a TTY that supports DEC mode 2004
+     *     (\x1b[?2004h), pasted text arrives wrapped between \x1b[200~ and
+     *     \x1b[201~.  The stdin listener set up by _enableBracketedPaste()
+     *     records whether the last input event was a paste or a keypress and
+     *     stores it in _lastInputSource.  When this information is available
+     *     we trust it unconditionally — it comes straight from the terminal.
+     *
+     *   TIER 2 — Content fingerprint (exact, ~100%)
+     *     Every kitClipboard.write() call stores the exact string it wrote in
+     *     _lastWriteContent.  We read the clipboard right now and compare.  If
+     *     the live content === _lastWriteContent we know it is still our write.
+     *     If it differs, something external changed it (human paste, another
+     *     program).  This is purely observational — no timing, no races.
+     *     It fails only in the astronomically unlikely event that a human
+     *     happens to paste the exact same string we last wrote (still detected
+     *     as "programmatic" — an acceptable false-negative).
+     *
+     *   TIER 3 — Timing heuristic (fallback, ~95%)
+     *     If we have never written anything (_lastWrite === null) we return
+     *     "unknown".  Otherwise we use the age of the last write: if the last
+     *     write happened very recently (< 200 ms) we call it "programmatic";
+     *     otherwise "typed".  This is the weakest tier and is only reached
+     *     when _lastWriteContent is unavailable (e.g. after a process restart
+     *     that re-uses an existing clipboard value).
+     *
+     * @returns {{
+     *   source:       'programmatic'|'typed'|'unknown',
+     *   method:       'bracketed-paste'|'content-fingerprint'|'timing-heuristic'|'no-data',
+     *   lastWriteMs:  number|null,
+     *   ageMs:        number|null,
+     * }}
+     */
+    detectSource() {
+      // ── Tier 1: bracketed paste ──────────────────────────────────────────
+      if (_bracketedPasteSupported && _lastInputSource !== "unknown") {
+        return {
+          source:      _lastInputSource === "paste" ? "typed" : "programmatic",
+          method:      "bracketed-paste",
+          lastWriteMs: _lastWrite,
+          ageMs:       _lastWrite !== null ? Date.now() - _lastWrite : null,
+        };
+      }
+
+      // ── Tier 2: content fingerprint ─────────────────────────────────────
+      // Read the live clipboard and compare to what we last wrote.
+      if (_lastWriteContent !== null) {
+        let liveContent;
+        try { liveContent = _read(); } catch { liveContent = null; }
+
+        if (liveContent !== null) {
+          const isOurs = liveContent === _lastWriteContent;
+          return {
+            source:      isOurs ? "programmatic" : "typed",
+            method:      "content-fingerprint",
+            lastWriteMs: _lastWrite,
+            ageMs:       _lastWrite !== null ? Date.now() - _lastWrite : null,
+          };
+        }
+      }
+
+      // ── Tier 3: timing heuristic (last resort) ───────────────────────────
+      if (_lastWrite === null) {
+        return { source: "unknown", method: "no-data", lastWriteMs: null, ageMs: null };
+      }
+      const age = Date.now() - _lastWrite;
+      return {
+        source:      age < 200 ? "programmatic" : "typed",
+        method:      "timing-heuristic",
+        lastWriteMs: _lastWrite,
+        ageMs:       age,
+      };
+    },
+
+    /**
+     * Returns true if the clipboard was most recently written by a human
+     * (pasted or typed), not by kitClipboard.write().
+     * @returns {boolean}
+     */
+    wasPasted() {
+      return this.detectSource().source !== "programmatic";
+    },
+
+    /**
+     * Returns true if the clipboard was most recently written programmatically.
+     * @returns {boolean}
+     */
+    wasProgrammatic() {
+      return this.detectSource().source === "programmatic";
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // FORMAT DETECTION
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Detect the format/type of the current clipboard content.
+     * @returns {{ format: string, confidence: 'high'|'medium'|'low', details: object }}
+     *
+     * Possible formats: "json", "url", "email", "html", "csv", "code",
+     *   "markdown", "base64", "hex", "uuid", "number", "date", "empty", "text"
+     */
+    detectFormat() {
+      const text = _read().trim();
+
+      if (!text) return { format: "empty", confidence: "high", details: {} };
+
+      // JSON
+      try {
+        const parsed = JSON.parse(text);
+        return { format: "json", confidence: "high", details: { type: typeof parsed, isArray: Array.isArray(parsed) } };
+      } catch {}
+
+      // UUID
+      if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(text)) {
+        return { format: "uuid", confidence: "high", details: { version: parseInt(text[14]) || null } };
+      }
+
+      // URL
+      try {
+        const url = new URL(text);
+        return { format: "url", confidence: "high", details: { protocol: url.protocol, host: url.host } };
+      } catch {}
+
+      // Email
+      if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(text)) {
+        return { format: "email", confidence: "high", details: {} };
+      }
+
+      // Hex color
+      if (/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(text)) {
+        return { format: "hex-color", confidence: "high", details: { value: text } };
+      }
+
+      // Pure hex string
+      if (/^[0-9a-f]+$/i.test(text) && text.length % 2 === 0 && text.length >= 8) {
+        return { format: "hex", confidence: "medium", details: { bytes: text.length / 2 } };
+      }
+
+      // Base64
+      if (/^[A-Za-z0-9+/]+=*$/.test(text) && text.length % 4 === 0 && text.length >= 16) {
+        return { format: "base64", confidence: "medium", details: { decodedLength: Math.floor(text.length * 0.75) } };
+      }
+
+      // Number
+      if (!isNaN(Number(text)) && text.length > 0) {
+        return { format: "number", confidence: "high", details: { value: Number(text) } };
+      }
+
+      // Date
+      const d = new Date(text);
+      if (!isNaN(d.getTime()) && text.length > 5) {
+        return { format: "date", confidence: "medium", details: { iso: d.toISOString() } };
+      }
+
+      // HTML
+      if (/<[a-z][\s\S]*>/i.test(text)) {
+        return { format: "html", confidence: "medium", details: { tags: (text.match(/<[a-z][a-z0-9]*/gi) || []).slice(0, 5) } };
+      }
+
+      // CSV (has commas and newlines or consistent comma count per line)
+      const lines = text.split("\n").filter(Boolean);
+      if (lines.length > 1) {
+        const commasPerLine = lines.map(l => (l.match(/,/g) || []).length);
+        const consistent = commasPerLine.every(c => c === commasPerLine[0] && c > 0);
+        if (consistent) return { format: "csv", confidence: "medium", details: { rows: lines.length, cols: commasPerLine[0] + 1 } };
+      }
+
+      // Markdown (has #, **, __, -, ```)
+      if (/^#{1,6} |^\*\*|^__|^- |\`\`\`/m.test(text)) {
+        return { format: "markdown", confidence: "medium", details: {} };
+      }
+
+      // Code heuristic (has braces, semicolons, keywords)
+      const codeScore = [
+        /[{};]/.test(text),
+        /\b(function|const|let|var|if|for|while|return|import|export|class|def|fn|pub)\b/.test(text),
+        /\/\/|\/\*|#/.test(text),
+      ].filter(Boolean).length;
+      if (codeScore >= 2) {
+        return { format: "code", confidence: "medium", details: { codeScore } };
+      }
+
+      return { format: "text", confidence: "high", details: { length: text.length, lines: lines.length } };
+    },
+
+    /**
+     * Check if the clipboard contains a specific format.
+     * @param {'json'|'url'|'email'|'html'|'csv'|'code'|'markdown'|'base64'|'hex'|'uuid'|'number'|'date'|'empty'|'text'} format
+     * @returns {boolean}
+     */
+    isFormat(format) {
+      return this.detectFormat().format === format;
+    },
+
+    /**
+     * Check if the clipboard is empty.
+     * @returns {boolean}
+     */
+    isEmpty() {
+      return _read().trim().length === 0;
+    },
+
+    /**
+     * Get the byte size of the current clipboard content.
+     * @returns {number}
+     */
+    size() {
+      return Buffer.byteLength(_read(), "utf8");
+    },
+
+    /**
+     * Get the character count of the current clipboard content.
+     * @returns {number}
+     */
+    length() {
+      return _read().length;
+    },
+
+    /**
+     * Get the line count of the current clipboard content.
+     * @returns {number}
+     */
+    lineCount() {
+      return _read().split("\n").length;
+    },
+
+    /**
+     * Get the word count of the current clipboard content.
+     * @returns {number}
+     */
+    wordCount() {
+      return _read().trim().split(/\s+/).filter(Boolean).length;
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // TRANSFORM
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Transform the clipboard content with a function and write it back.
+     * @param {function} fn - (text: string) => string
+     * @returns {{ before: string, after: string }}
+     *
+     * @example
+     *   kitClipboard.transform(text => text.toUpperCase());
+     */
+    transform(fn) {
+      const before = _read();
+      const after  = fn(before);
+      this.write(after);
+      return { before, after };
+    },
+
+    /** Uppercase the clipboard content. */
+    toUpperCase()  { return this.transform(t => t.toUpperCase()); },
+
+    /** Lowercase the clipboard content. */
+    toLowerCase()  { return this.transform(t => t.toLowerCase()); },
+
+    /** Trim whitespace from clipboard content. */
+    trim()         { return this.transform(t => t.trim()); },
+
+    /** Reverse the clipboard content. */
+    reverse()      { return this.transform(t => t.split("").reverse().join("")); },
+
+    /** Sort lines in the clipboard alphabetically. */
+    sortLines()    { return this.transform(t => t.split("\n").sort().join("\n")); },
+
+    /** Deduplicate lines in the clipboard. */
+    dedupeLines()  { return this.transform(t => [...new Set(t.split("\n"))].join("\n")); },
+
+    /** URL-encode the clipboard content. */
+    urlEncode()    { return this.transform(t => encodeURIComponent(t)); },
+
+    /** URL-decode the clipboard content. */
+    urlDecode()    { return this.transform(t => decodeURIComponent(t)); },
+
+    /** Base64-encode the clipboard content. */
+    base64Encode() { return this.transform(t => Buffer.from(t).toString("base64")); },
+
+    /** Base64-decode the clipboard content. */
+    base64Decode() { return this.transform(t => Buffer.from(t, "base64").toString("utf8")); },
+
+    /** Strip all HTML tags from the clipboard content. */
+    stripHTML()    { return this.transform(t => t.replace(/<[^>]+>/g, "")); },
+
+    /**
+     * Find and replace in clipboard content.
+     * @param {string|RegExp} search
+     * @param {string} replace
+     * @returns {{ before, after }}
+     */
+    replace(search, replace) {
+      return this.transform(t => t.replace(search, replace));
+    },
+
+    /**
+     * Find and replace all occurrences in clipboard content.
+     * @param {string|RegExp} search
+     * @param {string} replace
+     */
+    replaceAll(search, replace) {
+      return this.transform(t => t.replaceAll(search, replace));
+    },
+
+    /**
+     * Wrap clipboard content in a string on both sides.
+     * @param {string} prefix
+     * @param {string} [suffix] - Defaults to prefix.
+     */
+    wrap(prefix, suffix) {
+      return this.transform(t => `${prefix}${t}${suffix ?? prefix}`);
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // HISTORY
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Get the clipboard history (most recent first).
+     * History is tracked for writes made through kitClipboard.write() only.
+     * @param {number} [limit] - Max entries to return.
+     * @returns {Array<{ text, timestamp, source }>}
+     */
+    history(limit) {
+      return limit ? _history.slice(0, limit) : _history.slice();
+    },
+
+    /**
+     * Get a specific history entry by index (0 = most recent).
+     * @param {number} index
+     * @returns {{ text, timestamp, source } | undefined}
+     */
+    historyAt(index) {
+      return _history[index];
+    },
+
+    /**
+     * Restore a previous clipboard entry by index.
+     * @param {number} index
+     * @returns {{ restored: string }}
+     */
+    restore(index) {
+      const entry = _history[index];
+      if (!entry) throw new Error(`No history entry at index ${index}.`);
+      this.write(entry.text);
+      return { restored: entry.text };
+    },
+
+    /**
+     * Clear the clipboard history.
+     * @returns {{ cleared: number }}
+     */
+    clearHistory() {
+      const count = _history.length;
+      _history.length = 0;
+      return { cleared: count };
+    },
+
+    /**
+     * Search history for entries matching a string or regex.
+     * @param {string|RegExp} query
+     * @returns {Array<{ index, text, timestamp, source }>}
+     */
+    searchHistory(query) {
+      return _history
+        .map((entry, index) => ({ index, ...entry }))
+        .filter(e => typeof query === "string"
+          ? e.text.includes(query)
+          : query.test(e.text));
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // MONITORING / WATCHING
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Watch the clipboard for changes and call a callback when it changes.
+     * @param {function} onChange - Called with { text, previous, timestamp, format }
+     * @param {number} [intervalMs=500] - Polling interval.
+     * @returns {{ stop: function }}
+     *
+     * @example
+     *   const watcher = kitClipboard.watch(({ text }) => console.log("Clipboard:", text));
+     *   // later:
+     *   watcher.stop();
+     */
+    watch(onChange, intervalMs = 500) {
+      if (_watchTimer) clearInterval(_watchTimer);
+      _watchLast = _read();
+
+      _watchTimer = setInterval(() => {
+        try {
+          const current = _read();
+          if (current !== _watchLast) {
+            const previous = _watchLast;
+            _watchLast = current;
+            _pushHistory(current, "external");
+            onChange({
+              text: current,
+              previous,
+              timestamp: Date.now(),
+              format: this.detectFormat().format,
+            });
+          }
+        } catch { /* clipboard may be temporarily unavailable */ }
+      }, intervalMs);
+
+      return { stop: () => { clearInterval(_watchTimer); _watchTimer = null; } };
+    },
+
+    /**
+     * Wait for the clipboard to change and resolve with the new value.
+     * @param {number} [timeoutMs=30000]
+     * @returns {Promise<{ text, previous, format }>}
+     */
+    waitForChange(timeoutMs = 30000) {
+      return new Promise((resolve, reject) => {
+        const initial = _read();
+        const start   = Date.now();
+
+        const timer = setInterval(() => {
+          if (Date.now() - start > timeoutMs) {
+            clearInterval(timer);
+            reject(new Error("Clipboard watch timed out."));
+            return;
+          }
+          try {
+            const current = _read();
+            if (current !== initial) {
+              clearInterval(timer);
+              resolve({ text: current, previous: initial, format: this.detectFormat().format });
+            }
+          } catch {}
+        }, 200);
+      });
+    },
+
+    /**
+     * Stop any active clipboard watcher.
+     * @returns {{ stopped: boolean }}
+     */
+    stopWatch() {
+      if (_watchTimer) { clearInterval(_watchTimer); _watchTimer = null; return { stopped: true }; }
+      return { stopped: false };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // PLATFORM & DIAGNOSTICS
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Get information about the current platform and clipboard backend.
+     * @returns {object}
+     */
+    platformInfo() {
+      const plat = _platform();
+      let backend = "native";
+      if (["x11", "wayland", "linux"].includes(plat)) {
+        try { backend = _linuxBackend(); } catch { backend = "unavailable"; }
+      }
+      return {
+        platform: plat,
+        backend,
+        nodeVersion: process.version,
+        supported: ["macos", "windows", "android", "x11", "wayland", "linux"].includes(plat),
+      };
+    },
+
+    /**
+     * Check if the clipboard is accessible (backend available).
+     * @returns {boolean}
+     */
+    isAvailable() {
+      try { _read(); return true; }
+      catch { return false; }
+    },
+
+    /**
+     * Run a full diagnostic on the clipboard system.
+     * @returns {object}
+     */
+    diagnose() {
+      const info = this.platformInfo();
+      let canRead  = false;
+      let canWrite = false;
+      let readValue = null;
+
+      try { readValue = _read(); canRead = true; } catch {}
+      try { _write("kitClipboard-diagnostic-test"); canWrite = true; } catch {}
+      // Restore
+      if (readValue !== null) try { _write(readValue); } catch {}
+
+      return {
+        ...info,
+        canRead,
+        canWrite,
+        historyEntries: _history.length,
+        watcherActive: _watchTimer !== null,
+        lastWriteMs: _lastWrite,
+      };
+    },
+
+  }
+};