winclip 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6d5df273deafae1f60beee563bf2c2e98b1485f858be569b2201e35eedf91c1
+  data.tar.gz: acd8ef65e6cc2b4435ddbc36be9af15fdc4cf8717f05f39d961319bf32132175
+SHA512:
+  metadata.gz: 9570a2bc063aa31b16d252d04465a5d03deea83e7d8f9e0a86a7c2ce1c9e38801038e6d1e9d2ab12d3f405703d23bb9f467814cd4f546549a8ca86ab51bcdcb4
+  data.tar.gz: 80080336d80b9de4d1630f6c47a3a6b99d5ed1eb4be6b19f64b12a6c4d046f5e6d8381268bce45a9813f751a006de28cac0d3cebc8e4682bc2ccd1fa85acae9d

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-30
+
+### Added
+- `Winclip.text` / `Winclip.text=` — get/set Unicode clipboard text (UTF-8).
+- `Winclip.image` / `Winclip.image=` — get/set the clipboard image as PNG bytes
+  (CF_DIBV5 + CF_DIB via WIC; handles 24/32bpp, top-down/bottom-up on read).
+- `Winclip.files` / `Winclip.files=` — get/set the clipboard file list (CF_HDROP).
+- `Winclip.copy` / `Winclip.paste` — text convenience aliases.
+- `Winclip.clear` — empty the clipboard.
+- `Winclip.formats` — list available clipboard format names.
+- `Winclip.has_text?` / `has_image?` / `has_files?` and `available?(fmt)`.
+
+### Security / robustness
+- `Winclip.image` fully validates an untrusted clipboard DIB (minimum header
+  size, header size, and that the claimed pixels fit the actual handle) before
+  reading, and bounds allocation against the real data — preventing OOB reads
+  and runaway allocations from a malformed/hostile clipboard image. No C++
+  exception can unwind while the clipboard is held open. An undecodable image
+  returns `nil` rather than raising. Image size math is 64-bit (no overflow).
+- `available?(name)` resolves custom format names without registering them.
+
+[Unreleased]: https://github.com/main-path/winclip/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/main-path/winclip/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ned
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# winclip
+
+**Read and write the Windows clipboard from Ruby: text, images, and file lists.**
+
+`winclip` is a native Windows clipboard library. It gets and sets:
+
+- **text** — Unicode, as UTF-8 Strings;
+- **images** — as **PNG bytes** (converted to/from `CF_DIB`/`CF_DIBV5` via WIC);
+- **file lists** — as arrays of paths (`CF_HDROP`).
+
+The PNG image interface pairs directly with [windraw](https://rubygems.org/gems/windraw) —
+draw something and drop it on the clipboard, or grab a copied screenshot and save it.
+
+## Requirements
+
+- **Windows** with a native **MSVC (mswin)** Ruby (`x64-mswin64`). Not supported
+  on MinGW/UCRT Ruby (the `extconf.rb` will say so).
+- Visual Studio 2017+ / Build Tools with the **Desktop development with C++**
+  workload. Building uses [`vcvars`](https://rubygems.org/gems/vcvars) to load
+  the toolchain automatically — no Developer Command Prompt needed.
+
+## Install
+
+```sh
+gem install winclip
+```
+
+## Usage
+
+```ruby
+require "winclip"
+
+# --- text ---
+Winclip.text = "héllo ✓ 日本"
+Winclip.text            # => "héllo ✓ 日本"  (UTF-8)
+Winclip.copy("quick")   # alias for text=
+Winclip.paste           # alias for text
+
+# --- images (PNG bytes) ---
+Winclip.image = File.binread("logo.png")
+File.binwrite("pasted.png", Winclip.image) if Winclip.has_image?
+
+# straight from windraw:
+require "windraw"
+Winclip.image = Windraw.surface(200, 80) { |c| c.clear("#1e1e2e"); c.text("hi", 10, 20, color: "#fff") }.to_png
+
+# --- file lists ---
+Winclip.files = ["C:/a.txt", "C:/b.txt"]   # also accepts a single path String
+Winclip.files                              # => ["C:/a.txt", "C:/b.txt"]
+
+# --- queries & management ---
+Winclip.has_text?       # => true / false
+Winclip.has_image?      # => true / false
+Winclip.has_files?      # => true / false
+Winclip.formats         # => ["CF_UNICODETEXT", "CF_TEXT", "CF_LOCALE", ...]
+Winclip.available?(:image)            # => true / false
+Winclip.available?("PNG")             # registered format by name
+Winclip.available?("CF_HDROP")        # standard format by name
+Winclip.clear           # empty the clipboard
+```
+
+All getters return `nil` when that kind of content isn't on the clipboard, so
+you can write `Winclip.text or abort "nothing copied"`.
+
+## Notes
+
+- Images are exchanged as **PNG bytes** (binary `ASCII-8BIT` Strings). On set,
+  winclip publishes both `CF_DIBV5` (alpha-aware) and `CF_DIB` for the widest
+  app compatibility; on get it reads `CF_DIBV5`/`CF_DIB` (24- or 32-bit) and
+  encodes PNG. Palette (1/4/8-bit) DIBs are not decoded.
+- Clipboard work happens on the calling thread; do clipboard operations from one
+  thread.
+
+## License
+
+[MIT](LICENSE.txt).

data/ext/winclip/extconf.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+#
+# extconf.rb for the winclip C++ extension (Windows clipboard via Win32 + WIC).
+
+require "mkmf"
+
+unless RbConfig::CONFIG["target_os"] =~ /mswin/
+  abort <<~MSG
+    winclip requires a native Windows MSVC (mswin) Ruby — it uses the Win32
+    clipboard APIs and WIC (cl.exe). Your Ruby is "#{RbConfig::CONFIG['arch']}".
+  MSG
+end
+
+# C++ (WIC/COM uses IID_PPV_ARGS, BITMAPV5HEADER, std::vector); enable exceptions.
+$CXXFLAGS << " -EHsc"
+
+# System import libs (bare "NAME.lib" tokens on mswin):
+#   user32        - clipboard APIs (Open/Empty/Set/Get/Enum/IsAvailable)
+#   shell32       - DragQueryFileW / DROPFILES (CF_HDROP)
+#   windowscodecs - WIC (PNG <-> DIB for images)
+#   ole32         - COM (CoInitializeEx / CoCreateInstance)
+#   shlwapi       - SHCreateMemStream (in-memory PNG streams)
+$libs = [$libs, "user32.lib", "shell32.lib", "windowscodecs.lib",
+         "ole32.lib", "shlwapi.lib"].join(" ")
+
+create_makefile("winclip/winclip")

data/ext/winclip/winclip.cpp

@@ -0,0 +1,576 @@
+/*
+ * winclip — Windows clipboard access for Ruby: text, images (PNG), and file
+ * lists, get and set.
+ *
+ * Text  -> CF_UNICODETEXT (UTF-8 <-> UTF-16).
+ * Files -> CF_HDROP (DROPFILES + double-NUL UTF-16 path list).
+ * Image -> CF_DIBV5 + CF_DIB on set; CF_DIBV5/CF_DIB -> PNG on get, via WIC.
+ *
+ * Discipline (verified): the clipboard is ALWAYS closed before any rb_raise
+ * (rb_raise longjmps and would otherwise leave the clipboard locked for every
+ * other app). Win32 work happens in helper functions that return status codes
+ * and never call into Ruby; the Ruby-facing wrappers raise only after the
+ * clipboard is closed and C buffers are freed. After a successful
+ * SetClipboardData the system owns the HGLOBAL — we only GlobalFree on failure.
+ *
+ * Build: <ruby.h> before <windows.h>; C++ with -EHsc; never name a var OUT/IN.
+ * Link: user32 shell32 windowscodecs ole32 shlwapi.
+ */
+
+#include <ruby.h>
+#include <ruby/encoding.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <shlobj.h>     /* DROPFILES */
+#include <shellapi.h>   /* DragQueryFileW */
+#include <wincodec.h>   /* WIC */
+#include <shlwapi.h>    /* SHCreateMemStream */
+#include <objbase.h>    /* CoInitializeEx */
+
+#include <vector>
+#include <cstring>
+#include <cstdint>
+
+static VALUE eWinclipError; /* Winclip::Error */
+
+/* ---------- UTF-8 <-> UTF-16 (LocalAlloc'd results) ---------------------- */
+
+static wchar_t *utf8_to_utf16(const char *utf8, int len /* -1 = NUL-terminated */) {
+    int need = MultiByteToWideChar(CP_UTF8, 0, utf8, len, NULL, 0);
+    if (need <= 0) return NULL;
+    wchar_t *w = (wchar_t *)LocalAlloc(LPTR, (size_t)need * sizeof(wchar_t));
+    if (!w) return NULL;
+    if (MultiByteToWideChar(CP_UTF8, 0, utf8, len, w, need) <= 0) { LocalFree(w); return NULL; }
+    return w;
+}
+
+static char *utf16_to_utf8(const wchar_t *w, int len /* -1 = NUL-terminated */) {
+    int need = WideCharToMultiByte(CP_UTF8, 0, w, len, NULL, 0, NULL, NULL);
+    if (need <= 0) return NULL;
+    char *s = (char *)LocalAlloc(LPTR, (size_t)need);
+    if (!s) return NULL;
+    if (WideCharToMultiByte(CP_UTF8, 0, w, len, s, need, NULL, NULL) <= 0) { LocalFree(s); return NULL; }
+    return s;
+}
+
+/* OpenClipboard with a short retry loop (another app may briefly hold it). */
+static int clip_open_retry(void) {
+    for (int i = 0; i < 20; i++) {        /* ~200 ms worst case */
+        if (OpenClipboard(NULL)) return 1;
+        Sleep(10);
+    }
+    return 0;
+}
+
+/* ---------- text -------------------------------------------------------- */
+
+/* 1 ok / 0 fail. */
+static int clip_set_text(const wchar_t *w) {
+    size_t bytes = (wcslen(w) + 1) * sizeof(wchar_t); /* include NUL */
+    HGLOBAL hMem = GlobalAlloc(GMEM_MOVEABLE, bytes);
+    if (!hMem) return 0;
+    void *dst = GlobalLock(hMem);
+    if (!dst) { GlobalFree(hMem); return 0; }
+    memcpy(dst, w, bytes);
+    GlobalUnlock(hMem);
+    if (!clip_open_retry()) { GlobalFree(hMem); return 0; }
+    EmptyClipboard();
+    if (SetClipboardData(CF_UNICODETEXT, hMem) == NULL) {
+        GlobalFree(hMem); CloseClipboard(); return 0;   /* failure: we own it */
+    }
+    CloseClipboard();                                   /* success: system owns it */
+    return 1;
+}
+
+/* LocalAlloc'd UTF-8 (caller LocalFree) or NULL if absent/failure. */
+static char *clip_get_text(void) {
+    if (!IsClipboardFormatAvailable(CF_UNICODETEXT)) return NULL;
+    if (!clip_open_retry()) return NULL;
+    HANDLE h = GetClipboardData(CF_UNICODETEXT);        /* clipboard-owned */
+    char *utf8 = NULL;
+    if (h) {
+        wchar_t *w = (wchar_t *)GlobalLock(h);
+        if (w) { utf8 = utf16_to_utf8(w, -1); GlobalUnlock(h); }
+    }
+    CloseClipboard();
+    return utf8;
+}
+
+/* ---------- files (CF_HDROP) -------------------------------------------- */
+
+static int clip_set_files(const wchar_t **wp, int count) {
+    size_t list_cch = 1;                                 /* trailing extra NUL */
+    for (int i = 0; i < count; i++) list_cch += wcslen(wp[i]) + 1;
+    size_t bytes = sizeof(DROPFILES) + list_cch * sizeof(wchar_t);
+    HGLOBAL hMem = GlobalAlloc(GMEM_MOVEABLE, bytes);
+    if (!hMem) return 0;
+    BYTE *base = (BYTE *)GlobalLock(hMem);
+    if (!base) { GlobalFree(hMem); return 0; }
+    DROPFILES *df = (DROPFILES *)base;
+    df->pFiles = sizeof(DROPFILES);
+    df->pt.x = 0; df->pt.y = 0;
+    df->fNC = FALSE;
+    df->fWide = TRUE;
+    wchar_t *list = (wchar_t *)(base + sizeof(DROPFILES));
+    size_t pos = 0;
+    for (int i = 0; i < count; i++) {
+        size_t n = wcslen(wp[i]) + 1;
+        memcpy(list + pos, wp[i], n * sizeof(wchar_t));
+        pos += n;
+    }
+    list[pos] = L'\0';                                   /* double-NUL terminate */
+    GlobalUnlock(hMem);
+    if (!clip_open_retry()) { GlobalFree(hMem); return 0; }
+    EmptyClipboard();
+    if (SetClipboardData(CF_HDROP, hMem) == NULL) { GlobalFree(hMem); CloseClipboard(); return 0; }
+    CloseClipboard();
+    return 1;
+}
+
+/* On success *out = LocalAlloc'd array of LocalAlloc'd UTF-8 strings; returns
+ * count (>=0). Returns -1 when no CF_HDROP / on failure. */
+static int clip_get_files(char ***out) {
+    *out = NULL;
+    if (!IsClipboardFormatAvailable(CF_HDROP)) return -1;
+    if (!clip_open_retry()) return -1;
+    HANDLE h = GetClipboardData(CF_HDROP);
+    if (!h) { CloseClipboard(); return -1; }
+    HDROP hDrop = (HDROP)h;
+    UINT n = DragQueryFileW(hDrop, 0xFFFFFFFF, NULL, 0);
+    char **arr = (char **)LocalAlloc(LPTR, (size_t)(n ? n : 1) * sizeof(char *));
+    if (!arr) { CloseClipboard(); return -1; }
+    for (UINT i = 0; i < n; i++) {
+        UINT cch = DragQueryFileW(hDrop, i, NULL, 0);
+        wchar_t *wbuf = (wchar_t *)LocalAlloc(LPTR, (size_t)(cch + 1) * sizeof(wchar_t));
+        if (!wbuf) { for (UINT j = 0; j < i; j++) LocalFree(arr[j]); LocalFree(arr); CloseClipboard(); return -1; }
+        DragQueryFileW(hDrop, i, wbuf, cch + 1);
+        arr[i] = utf16_to_utf8(wbuf, -1);
+        LocalFree(wbuf);
+        if (!arr[i]) { for (UINT j = 0; j < i; j++) LocalFree(arr[j]); LocalFree(arr); CloseClipboard(); return -1; }
+    }
+    CloseClipboard();
+    *out = arr;
+    return (int)n;
+}
+
+/* ---------- image (WIC) ------------------------------------------------- */
+
+static HRESULT png_to_bgra(const BYTE *png, size_t pnglen,
+                           std::vector<BYTE> &outBgra, UINT &w, UINT &h) {
+    IStream *stream = SHCreateMemStream(png, (UINT)pnglen);
+    if (!stream) return E_OUTOFMEMORY;
+    IWICImagingFactory *factory = NULL; IWICBitmapDecoder *decoder = NULL;
+    IWICBitmapFrameDecode *frame = NULL; IWICFormatConverter *conv = NULL;
+    HRESULT hr = CoCreateInstance(CLSID_WICImagingFactory, NULL, CLSCTX_INPROC_SERVER,
+                                  IID_PPV_ARGS(&factory));
+    if (SUCCEEDED(hr)) hr = factory->CreateDecoderFromStream(stream, NULL, WICDecodeMetadataCacheOnDemand, &decoder);
+    if (SUCCEEDED(hr)) hr = decoder->GetFrame(0, &frame);
+    if (SUCCEEDED(hr)) hr = factory->CreateFormatConverter(&conv);
+    if (SUCCEEDED(hr)) hr = conv->Initialize(frame, GUID_WICPixelFormat32bppBGRA,
+                                             WICBitmapDitherTypeNone, NULL, 0.0, WICBitmapPaletteTypeCustom);
+    if (SUCCEEDED(hr)) hr = conv->GetSize(&w, &h);
+    if (SUCCEEDED(hr)) {
+        uint64_t stride64 = (uint64_t)w * 4;
+        uint64_t total = stride64 * h;
+        if (w == 0 || h == 0 || stride64 > 0xFFFFFFFFu || total > 0xFFFFFFFFu) {
+            hr = E_OUTOFMEMORY; /* WIC's CopyPixels uses UINT sizes */
+        } else {
+            UINT stride = (UINT)stride64;
+            outBgra.resize((size_t)total);
+            WICRect rc = { 0, 0, (INT)w, (INT)h };
+            hr = conv->CopyPixels(&rc, stride, (UINT)outBgra.size(), outBgra.data());
+        }
+    }
+    if (conv) conv->Release();
+    if (frame) frame->Release();
+    if (decoder) decoder->Release();
+    if (factory) factory->Release();
+    if (stream) stream->Release();
+    return hr;
+}
+
+static HRESULT bgra_to_png(const BYTE *bgra, UINT w, UINT h, UINT stride, std::vector<BYTE> &outPng) {
+    IWICImagingFactory *factory = NULL; IWICStream *stream = NULL;
+    IWICBitmapEncoder *encoder = NULL; IWICBitmapFrameEncode *frame = NULL;
+    IStream *memstream = SHCreateMemStream(NULL, 0);
+    if (!memstream) return E_OUTOFMEMORY;
+    HRESULT hr = CoCreateInstance(CLSID_WICImagingFactory, NULL, CLSCTX_INPROC_SERVER,
+                                  IID_PPV_ARGS(&factory));
+    if (SUCCEEDED(hr)) hr = factory->CreateStream(&stream);
+    if (SUCCEEDED(hr)) hr = stream->InitializeFromIStream(memstream);
+    if (SUCCEEDED(hr)) hr = factory->CreateEncoder(GUID_ContainerFormatPng, NULL, &encoder);
+    if (SUCCEEDED(hr)) hr = encoder->Initialize(stream, WICBitmapEncoderNoCache);
+    if (SUCCEEDED(hr)) hr = encoder->CreateNewFrame(&frame, NULL);
+    if (SUCCEEDED(hr)) hr = frame->Initialize(NULL);
+    if (SUCCEEDED(hr)) hr = frame->SetSize(w, h);
+    WICPixelFormatGUID fmt = GUID_WICPixelFormat32bppBGRA;
+    if (SUCCEEDED(hr)) hr = frame->SetPixelFormat(&fmt);
+    if (SUCCEEDED(hr)) {
+        uint64_t cb = (uint64_t)stride * h;
+        if (cb > 0xFFFFFFFFu) hr = E_OUTOFMEMORY;
+        else hr = frame->WritePixels(h, stride, (UINT)cb, (BYTE *)bgra);
+    }
+    if (SUCCEEDED(hr)) hr = frame->Commit();
+    if (SUCCEEDED(hr)) hr = encoder->Commit();
+    if (SUCCEEDED(hr)) {
+        STATSTG st; memset(&st, 0, sizeof(st));
+        hr = memstream->Stat(&st, STATFLAG_NONAME);
+        if (SUCCEEDED(hr)) {
+            ULONG size = (ULONG)st.cbSize.QuadPart;
+            outPng.resize(size);
+            LARGE_INTEGER zero; zero.QuadPart = 0;
+            memstream->Seek(zero, STREAM_SEEK_SET, NULL);
+            ULONG read = 0;
+            if (size) hr = memstream->Read(outPng.data(), size, &read);
+            if (SUCCEEDED(hr)) outPng.resize(read);
+        }
+    }
+    if (frame) frame->Release();
+    if (encoder) encoder->Release();
+    if (stream) stream->Release();
+    if (factory) factory->Release();
+    if (memstream) memstream->Release();
+    return hr;
+}
+
+/* PNG bytes -> clipboard (sets CF_DIBV5 + CF_DIB). Caller must have COM init'd. */
+static HRESULT clip_set_image(const BYTE *png, size_t pnglen) {
+    std::vector<BYTE> bgra; UINT w = 0, h = 0;
+    HRESULT hr = png_to_bgra(png, pnglen, bgra, w, h);
+    if (FAILED(hr)) return hr;
+
+    /* Compute the DIB byte size in 64-bit and reject images too large to encode
+     * as a clipboard DIB (avoids the w*4*h 32-bit wrap that would corrupt it). */
+    uint64_t imgSize64 = (uint64_t)w * 4 * h;
+    if (imgSize64 == 0 || imgSize64 + sizeof(BITMAPV5HEADER) > 0xFFFFFFFFu)
+        return E_OUTOFMEMORY;
+    const DWORD imgSize = (DWORD)imgSize64;
+
+    HGLOBAL hV5 = GlobalAlloc(GMEM_MOVEABLE, sizeof(BITMAPV5HEADER) + imgSize);
+    if (!hV5) return E_OUTOFMEMORY;
+    {
+        BYTE *p = (BYTE *)GlobalLock(hV5);
+        if (!p) { GlobalFree(hV5); return E_OUTOFMEMORY; }
+        BITMAPV5HEADER *bi = (BITMAPV5HEADER *)p; memset(bi, 0, sizeof(*bi));
+        bi->bV5Size = sizeof(BITMAPV5HEADER);
+        bi->bV5Width = (LONG)w; bi->bV5Height = -(LONG)h;   /* top-down */
+        bi->bV5Planes = 1; bi->bV5BitCount = 32;
+        bi->bV5Compression = BI_BITFIELDS; bi->bV5SizeImage = imgSize;
+        bi->bV5RedMask = 0x00FF0000; bi->bV5GreenMask = 0x0000FF00;
+        bi->bV5BlueMask = 0x000000FF; bi->bV5AlphaMask = 0xFF000000;
+        bi->bV5CSType = LCS_sRGB; bi->bV5Intent = LCS_GM_IMAGES;
+        memcpy(p + sizeof(BITMAPV5HEADER), bgra.data(), imgSize);
+        GlobalUnlock(hV5);
+    }
+    HGLOBAL hDib = GlobalAlloc(GMEM_MOVEABLE, sizeof(BITMAPINFOHEADER) + imgSize);
+    if (!hDib) { GlobalFree(hV5); return E_OUTOFMEMORY; }
+    {
+        BYTE *p = (BYTE *)GlobalLock(hDib);
+        if (!p) { GlobalFree(hV5); GlobalFree(hDib); return E_OUTOFMEMORY; }
+        BITMAPINFOHEADER *bi = (BITMAPINFOHEADER *)p; memset(bi, 0, sizeof(*bi));
+        bi->biSize = sizeof(BITMAPINFOHEADER);
+        bi->biWidth = (LONG)w; bi->biHeight = -(LONG)h;     /* top-down */
+        bi->biPlanes = 1; bi->biBitCount = 32;
+        bi->biCompression = BI_RGB; bi->biSizeImage = imgSize;
+        memcpy(p + sizeof(BITMAPINFOHEADER), bgra.data(), imgSize);
+        GlobalUnlock(hDib);
+    }
+    if (!clip_open_retry()) { GlobalFree(hV5); GlobalFree(hDib); return E_FAIL; }
+    EmptyClipboard();
+    bool ok = true;
+    if (!SetClipboardData(CF_DIBV5, hV5)) { ok = false; GlobalFree(hV5); }
+    if (!SetClipboardData(CF_DIB, hDib)) { ok = false; GlobalFree(hDib); }
+    CloseClipboard();
+    return ok ? S_OK : E_FAIL;
+}
+
+/* clipboard image -> PNG bytes. Caller must have COM init'd.
+ *
+ * The DIB is UNTRUSTED data placed by another app, so every field and offset is
+ * validated against the real handle size before use, and the pixel-copy region
+ * runs inside a try/catch so a std::bad_alloc can never unwind out while the
+ * clipboard is held open (which would wedge the clipboard system-wide).
+ * Returns E_FAIL for absent / malformed / unsupported (e.g. palettized) DIBs. */
+static HRESULT clip_get_image(std::vector<BYTE> &outPng) {
+    if (!clip_open_retry()) return E_FAIL;
+    HANDLE h = GetClipboardData(CF_DIBV5);
+    if (!h) h = GetClipboardData(CF_DIB);
+    if (!h) { CloseClipboard(); return E_FAIL; }
+    BYTE *dib = (BYTE *)GlobalLock(h);
+    if (!dib) { CloseClipboard(); return E_FAIL; }
+    SIZE_T dibSize = GlobalSize(h);
+
+    HRESULT hr = S_OK;
+    std::vector<BYTE> bgra;
+    UINT w = 0, hh = 0;
+    try {
+        /* The block must be at least a BITMAPINFOHEADER before we read fields. */
+        if (dibSize < sizeof(BITMAPINFOHEADER)) throw E_FAIL;
+
+        BITMAPINFOHEADER *bih = (BITMAPINFOHEADER *)dib;
+        DWORD biSize = bih->biSize, comp = bih->biCompression;
+        LONG rawH = bih->biHeight;
+        WORD bpp = bih->biBitCount;
+        bool topDown = (rawH < 0);
+        w  = (UINT)(bih->biWidth < 0 ? -bih->biWidth : bih->biWidth);
+        hh = (UINT)(rawH < 0 ? -rawH : rawH);
+        if (w == 0 || hh == 0) throw E_FAIL;
+        if (biSize < sizeof(BITMAPINFOHEADER) || biSize > dibSize) throw E_FAIL;
+
+        SIZE_T pixOffset = biSize;
+        if (comp == BI_BITFIELDS && biSize == sizeof(BITMAPINFOHEADER)) pixOffset += 3 * sizeof(DWORD);
+        if (pixOffset > dibSize) throw E_FAIL;
+        BYTE *pixels = dib + pixOffset;
+        SIZE_T pixBytes = dibSize - pixOffset;
+
+        /* Bound the source against the bytes actually present BEFORE allocating,
+         * so untrusted dimensions can't drive a huge allocation. */
+        uint64_t srcStride = (bpp == 32) ? (uint64_t)w * 4
+                           : (bpp == 24) ? (((uint64_t)w * 3 + 3) & ~3ull)
+                           : 0;
+        if (srcStride == 0) throw E_FAIL;                       /* unsupported bpp */
+        if (srcStride * hh > (uint64_t)pixBytes) throw E_FAIL;  /* claims more than it carries */
+
+        bgra.resize((size_t)w * hh * 4);
+        DWORD ss = (DWORD)srcStride;
+        if (bpp == 32) {
+            for (UINT y = 0; y < hh; y++) {
+                UINT sr = topDown ? y : (hh - 1 - y);
+                memcpy(&bgra[(size_t)y * w * 4], pixels + (size_t)sr * ss, (size_t)w * 4);
+            }
+        } else { /* bpp == 24 */
+            for (UINT y = 0; y < hh; y++) {
+                UINT sr = topDown ? y : (hh - 1 - y);
+                BYTE *srow = pixels + (size_t)sr * ss;
+                BYTE *drow = &bgra[(size_t)y * w * 4];
+                for (UINT x = 0; x < w; x++) {
+                    drow[x * 4 + 0] = srow[x * 3 + 0];
+                    drow[x * 4 + 1] = srow[x * 3 + 1];
+                    drow[x * 4 + 2] = srow[x * 3 + 2];
+                    drow[x * 4 + 3] = 255;
+                }
+            }
+        }
+    } catch (HRESULT e) {
+        hr = e;
+    } catch (...) {
+        hr = E_OUTOFMEMORY; /* e.g. std::bad_alloc — never escape with clipboard open */
+    }
+    GlobalUnlock(h);
+    CloseClipboard();
+    if (FAILED(hr)) return hr;
+    return bgra_to_png(bgra.data(), w, hh, w * 4, outPng);
+}
+
+/* ---------- format names ------------------------------------------------ */
+
+static const char *clip_std_name(UINT f) {
+    switch (f) {
+    case CF_TEXT: return "CF_TEXT";
+    case CF_BITMAP: return "CF_BITMAP";
+    case CF_METAFILEPICT: return "CF_METAFILEPICT";
+    case CF_SYLK: return "CF_SYLK";
+    case CF_DIF: return "CF_DIF";
+    case CF_TIFF: return "CF_TIFF";
+    case CF_OEMTEXT: return "CF_OEMTEXT";
+    case CF_DIB: return "CF_DIB";
+    case CF_PALETTE: return "CF_PALETTE";
+    case CF_PENDATA: return "CF_PENDATA";
+    case CF_RIFF: return "CF_RIFF";
+    case CF_WAVE: return "CF_WAVE";
+    case CF_UNICODETEXT: return "CF_UNICODETEXT";
+    case CF_ENHMETAFILE: return "CF_ENHMETAFILE";
+    case CF_HDROP: return "CF_HDROP";
+    case CF_LOCALE: return "CF_LOCALE";
+    case CF_DIBV5: return "CF_DIBV5";
+    default: return NULL;
+    }
+}
+
+/* ====================== Ruby-facing methods ============================= */
+
+static VALUE wc_get_text(VALUE self) {
+    char *u8 = clip_get_text();
+    if (!u8) return Qnil;
+    VALUE s = rb_utf8_str_new_cstr(u8);
+    LocalFree(u8);
+    return s;
+}
+
+static VALUE wc_set_text(VALUE self, VALUE str) {
+    VALUE u8 = rb_str_export_to_enc(StringValue(str), rb_utf8_encoding());
+    wchar_t *w = utf8_to_utf16(RSTRING_PTR(u8), -1);
+    if (!w) rb_raise(eWinclipError, "winclip: could not encode text");
+    int ok = clip_set_text(w);
+    LocalFree(w);
+    if (!ok) rb_raise(eWinclipError, "winclip: failed to set clipboard text");
+    return Qnil;
+}
+
+static VALUE wc_get_files(VALUE self) {
+    char **arr = NULL;
+    int n = clip_get_files(&arr);
+    if (n < 0) return Qnil;
+    VALUE rary = rb_ary_new_capa(n);
+    for (int i = 0; i < n; i++) {
+        rb_ary_push(rary, rb_utf8_str_new_cstr(arr[i]));
+        LocalFree(arr[i]);
+    }
+    LocalFree(arr);
+    return rary;
+}
+
+static VALUE wc_set_files(VALUE self, VALUE ary) {
+    Check_Type(ary, T_ARRAY);
+    long n = RARRAY_LEN(ary);
+    if (n <= 0) rb_raise(rb_eArgError, "winclip: files list must not be empty");
+
+    /* Convert all paths to UTF-16 up front (raises here, before any clipboard
+     * work or HGLOBAL exists). */
+    wchar_t **wp = (wchar_t **)LocalAlloc(LPTR, (size_t)n * sizeof(wchar_t *));
+    if (!wp) rb_raise(rb_eNoMemError, "winclip: out of memory");
+    int built = 0;
+    int failed = 0;
+    for (long i = 0; i < n; i++) {
+        VALUE e = rb_ary_entry(ary, i);
+        if (!RB_TYPE_P(e, T_STRING)) { failed = 1; break; }
+        VALUE u8 = rb_str_export_to_enc(e, rb_utf8_encoding());
+        wp[i] = utf8_to_utf16(RSTRING_PTR(u8), -1);
+        if (!wp[i]) { failed = 1; break; }
+        built++;
+    }
+    int ok = 0;
+    if (!failed) ok = clip_set_files((const wchar_t **)wp, (int)n);
+    for (int i = 0; i < built; i++) LocalFree(wp[i]);
+    LocalFree(wp);
+    if (failed) rb_raise(rb_eArgError, "winclip: every file path must be a String");
+    if (!ok) rb_raise(eWinclipError, "winclip: failed to set clipboard files");
+    return Qnil;
+}
+
+static VALUE wc_get_image(VALUE self) {
+    if (!IsClipboardFormatAvailable(CF_DIBV5) && !IsClipboardFormatAvailable(CF_DIB))
+        return Qnil;
+
+    HRESULT cohr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
+    bool com_owned = (cohr == S_OK || cohr == S_FALSE);
+
+    std::vector<BYTE> png;
+    HRESULT hr = E_FAIL;
+    bool threw = false;
+    try { hr = clip_get_image(png); }
+    catch (...) { threw = true; } /* e.g. bad_alloc in bgra_to_png (clipboard already closed) */
+    if (com_owned) CoUninitialize();
+
+    if (threw) rb_raise(eWinclipError, "winclip: out of memory decoding the clipboard image");
+    /* Format present but not decodable (palettized / malformed) -> nil, matching
+     * the "getters return nil when there's no usable content" contract. */
+    if (FAILED(hr)) return Qnil;
+
+    VALUE s = rb_str_new((char *)png.data(), (long)png.size());
+    rb_enc_associate(s, rb_ascii8bit_encoding());
+    return s;
+}
+
+static VALUE wc_set_image(VALUE self, VALUE png) {
+    StringValue(png);
+    HRESULT cohr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
+    bool com_owned = (cohr == S_OK || cohr == S_FALSE);
+
+    HRESULT hr = E_FAIL;
+    bool threw = false;
+    try {
+        std::vector<BYTE> in((BYTE *)RSTRING_PTR(png), (BYTE *)RSTRING_PTR(png) + RSTRING_LEN(png));
+        hr = clip_set_image(in.data(), in.size());
+    } catch (...) { threw = true; } /* e.g. bad_alloc decoding a huge PNG (no clipboard held) */
+    if (com_owned) CoUninitialize();
+
+    if (threw) rb_raise(eWinclipError, "winclip: out of memory encoding the clipboard image");
+    if (FAILED(hr))
+        rb_raise(eWinclipError, "winclip: failed to set clipboard image "
+                 "(not a valid PNG?) (hr=0x%08lX)", (unsigned long)hr);
+    return Qnil;
+}
+
+static VALUE wc_clear(VALUE self) {
+    if (!clip_open_retry()) rb_raise(eWinclipError, "winclip: could not open the clipboard");
+    EmptyClipboard();
+    CloseClipboard();
+    return Qnil;
+}
+
+static VALUE wc_formats(VALUE self) {
+    if (!clip_open_retry()) rb_raise(eWinclipError, "winclip: could not open the clipboard");
+
+    /* Collect ids while open; build Ruby objects only after closing (so an
+     * allocation that raises can't leave the clipboard open). std::vector grows
+     * as needed — no silent cap on the number of formats reported. */
+    std::vector<UINT> ids;
+    UINT f = 0;
+    while ((f = EnumClipboardFormats(f)) != 0) ids.push_back(f);
+    CloseClipboard();
+
+    VALUE ary = rb_ary_new_capa((long)ids.size());
+    for (size_t i = 0; i < ids.size(); i++) {
+        const char *nm = clip_std_name(ids[i]);
+        if (nm) {
+            rb_ary_push(ary, rb_str_new_cstr(nm));
+        } else {
+            wchar_t wbuf[256];
+            int wn = GetClipboardFormatNameW(ids[i], wbuf, 256);  /* no open needed */
+            if (wn > 0) {
+                char *u8 = utf16_to_utf8(wbuf, wn);
+                if (u8) { rb_ary_push(ary, rb_utf8_str_new_cstr(u8)); LocalFree(u8); }
+            }
+        }
+    }
+    return ary;
+}
+
+static VALUE wc_available(VALUE self, VALUE vid) {
+    UINT id = (UINT)NUM2UINT(vid);
+    return IsClipboardFormatAvailable(id) ? Qtrue : Qfalse;
+}
+
+static VALUE wc_register_format(VALUE self, VALUE name) {
+    VALUE u8 = rb_str_export_to_enc(StringValue(name), rb_utf8_encoding());
+    wchar_t *w = utf8_to_utf16(RSTRING_PTR(u8), -1);
+    if (!w) rb_raise(eWinclipError, "winclip: could not encode format name");
+    UINT id = RegisterClipboardFormatW(w);
+    LocalFree(w);
+    if (id == 0) rb_raise(eWinclipError, "winclip: could not register clipboard format");
+    return UINT2NUM(id);
+}
+
+static VALUE wc_has_text(VALUE self) {
+    return (IsClipboardFormatAvailable(CF_UNICODETEXT) ||
+            IsClipboardFormatAvailable(CF_TEXT)) ? Qtrue : Qfalse;
+}
+static VALUE wc_has_image(VALUE self) {
+    return (IsClipboardFormatAvailable(CF_DIBV5) ||
+            IsClipboardFormatAvailable(CF_DIB) ||
+            IsClipboardFormatAvailable(CF_BITMAP)) ? Qtrue : Qfalse;
+}
+static VALUE wc_has_files(VALUE self) {
+    return IsClipboardFormatAvailable(CF_HDROP) ? Qtrue : Qfalse;
+}
+
+extern "C" void Init_winclip(void) {
+    VALUE mWinclip = rb_define_module("Winclip");
+    eWinclipError = rb_define_class_under(mWinclip, "Error", rb_eStandardError);
+
+    rb_define_singleton_method(mWinclip, "_get_text", RUBY_METHOD_FUNC(wc_get_text), 0);
+    rb_define_singleton_method(mWinclip, "_set_text", RUBY_METHOD_FUNC(wc_set_text), 1);
+    rb_define_singleton_method(mWinclip, "_get_image", RUBY_METHOD_FUNC(wc_get_image), 0);
+    rb_define_singleton_method(mWinclip, "_set_image", RUBY_METHOD_FUNC(wc_set_image), 1);
+    rb_define_singleton_method(mWinclip, "_get_files", RUBY_METHOD_FUNC(wc_get_files), 0);
+    rb_define_singleton_method(mWinclip, "_set_files", RUBY_METHOD_FUNC(wc_set_files), 1);
+    rb_define_singleton_method(mWinclip, "clear", RUBY_METHOD_FUNC(wc_clear), 0);
+    rb_define_singleton_method(mWinclip, "formats", RUBY_METHOD_FUNC(wc_formats), 0);
+    rb_define_singleton_method(mWinclip, "_available?", RUBY_METHOD_FUNC(wc_available), 1);
+    rb_define_singleton_method(mWinclip, "_register_format", RUBY_METHOD_FUNC(wc_register_format), 1);
+    rb_define_singleton_method(mWinclip, "has_text?", RUBY_METHOD_FUNC(wc_has_text), 0);
+    rb_define_singleton_method(mWinclip, "has_image?", RUBY_METHOD_FUNC(wc_has_image), 0);
+    rb_define_singleton_method(mWinclip, "has_files?", RUBY_METHOD_FUNC(wc_has_files), 0);
+}

data/lib/winclip/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Winclip
+  VERSION = "0.1.0"
+end

data/lib/winclip.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "winclip/version"
+require "winclip/winclip" # native extension: defines the Winclip module + primitives
+
+# winclip — read and write the Windows clipboard: text, images (PNG), and file
+# lists.
+#
+#   Winclip.text = "hello"
+#   Winclip.text                 # => "hello"
+#   Winclip.image = File.binread("pic.png")
+#   File.binwrite("out.png", Winclip.image) if Winclip.has_image?
+#   Winclip.files = ["C:/a.txt", "C:/b.txt"]
+#   Winclip.files                # => ["C:/a.txt", "C:/b.txt"]
+#   Winclip.clear
+module Winclip
+  # Standard clipboard format ids, for Winclip.available?("CF_...").
+  STANDARD_FORMATS = {
+    "CF_TEXT" => 1, "CF_BITMAP" => 2, "CF_METAFILEPICT" => 3, "CF_SYLK" => 4,
+    "CF_DIF" => 5, "CF_TIFF" => 6, "CF_OEMTEXT" => 7, "CF_DIB" => 8,
+    "CF_PALETTE" => 9, "CF_PENDATA" => 10, "CF_RIFF" => 11, "CF_WAVE" => 12,
+    "CF_UNICODETEXT" => 13, "CF_ENHMETAFILE" => 14, "CF_HDROP" => 15,
+    "CF_LOCALE" => 16, "CF_DIBV5" => 17
+  }.freeze
+
+  class << self
+    # Clipboard text as a UTF-8 String, or nil if no text is present.
+    def text
+      _get_text
+    end
+
+    # Set the clipboard to the given text (coerced with #to_s). Returns the value.
+    def text=(value)
+      _set_text(value.to_s)
+      value
+    end
+
+    # The clipboard image as PNG bytes (binary String), or nil if no image is
+    # present. Pairs with windraw: `File.binwrite("x.png", Winclip.image)`.
+    def image
+      _get_image
+    end
+
+    # Put an image on the clipboard from PNG bytes (a binary String). Returns the
+    # value. Sets both CF_DIBV5 (alpha-aware) and CF_DIB for broad compatibility.
+    def image=(png)
+      _set_image(png)
+      png
+    end
+
+    # The clipboard file list as an Array<String> of paths, or nil if none.
+    def files
+      _get_files
+    end
+
+    # Put a file list on the clipboard (CF_HDROP). Accepts an Array of paths or a
+    # single path String. Returns the value.
+    def files=(paths)
+      list = Array(paths).map(&:to_s)
+      raise ArgumentError, "winclip: provide at least one file path" if list.empty?
+      _set_files(list)
+      paths
+    end
+
+    # Copy text to the clipboard (alias for text=). Returns the string.
+    def copy(string)
+      self.text = string
+    end
+
+    # Read text from the clipboard (alias for #text).
+    def paste
+      text
+    end
+
+    # Is the given clipboard format present? Accepts an Integer format id, a
+    # standard format name ("CF_UNICODETEXT"), a registered format name ("PNG"),
+    # or one of :text / :image / :files.
+    def available?(format)
+      case format
+      when Integer then _available?(format)
+      when :text   then has_text?
+      when :image  then has_image?
+      when :files  then has_files?
+      else
+        name = format.to_s
+        if (id = STANDARD_FORMATS[name])
+          _available?(id)
+        else
+          # Resolve a custom/registered format by name WITHOUT registering it as a
+          # side effect (RegisterClipboardFormat would create unknown names).
+          # `formats` reports what's actually present — exactly the answer needed.
+          formats.include?(name)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: winclip
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ned
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: vcvars
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+description: |
+  winclip is a native Windows clipboard library for Ruby. It gets and sets
+  Unicode text, images (as PNG bytes, converted to/from CF_DIB/CF_DIBV5 via
+  WIC), and file lists (CF_HDROP), plus clear, format introspection, and
+  has_text?/has_image?/has_files? queries. The PNG image interface pairs
+  directly with the windraw gem. Windows MSVC (mswin) Ruby only.
+executables: []
+extensions:
+- ext/winclip/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/winclip/extconf.rb
+- ext/winclip/winclip.cpp
+- lib/winclip.rb
+- lib/winclip/version.rb
+homepage: https://github.com/main-path/winclip
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-path/winclip
+  changelog_uri: https://github.com/main-path/winclip/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/winclip/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Read and write the Windows clipboard: text, images (PNG), and file lists.'
+test_files: []