windraw 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db764078067f634ec0cedfab09263f585de8ddf731e47296e3c01471dcaf488f
+  data.tar.gz: 9ebc3074ddbbf78b48b3e80689616fa002475962d1fbf73580dae387393a86e0
+SHA512:
+  metadata.gz: e8ff7ea96f7c957ac95ec973480e82f3cf1d0b2a0ead223a4fc5b5746ba7b4ac1c16b58fad2a1bf9b5637202cdf942bdf0b5ae2cccd08ac72abb90178861e36c
+  data.tar.gz: fb1f3b325e7b1934ffd0d7479f7297264e907b48128f4475c81aba4c3ef9b0b0835aad35bb209400d02eb6a8669dd868805ea82874b95ba0b63a136984eb2c8c

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 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
+- `Windraw.surface(width, height) { |c| ... }` — create an off-screen Direct2D
+  surface, draw, and (with a block) auto-finish.
+- `Surface#clear`, `#rectangle`/`#rect` (with `radius:` for rounded corners),
+  `#ellipse`, `#circle`, `#line`, `#polygon`, `#polyline`, and `#text`, all with
+  hex-color (`#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa`) fill/stroke keywords.
+- `Surface#save(path)` — write a PNG via WIC.
+- `Surface#to_png` — return the PNG bytes as a binary String.
+- `Surface#close`/`#dispose` — release COM resources deterministically.
+- `Windraw::Color.parse` — CSS-style hex color to straight RGBA floats.
+- DirectWrite text with font family, size, bold, and italic.
+
+[Unreleased]: https://github.com/main-path/windraw/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/main-path/windraw/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,107 @@
+# windraw
+
+**Headless 2D drawing for Windows — Direct2D + DirectWrite + WIC, straight to PNG.**
+
+`windraw` is a small Cairo-style 2D canvas built entirely on the graphics stack
+that already ships with Windows: **Direct2D** for vector shapes, **DirectWrite**
+for text, and **WIC** for PNG encoding. It renders into an off-screen bitmap —
+**no window, no message loop** — so it's perfect for generating images from
+scripts, jobs, and tests.
+
+```ruby
+require "windraw"
+
+Windraw.surface(800, 600) do |c|
+  c.clear("#1e1e2e")
+  c.rectangle(50, 50, 200, 120, fill: "#89b4fa", stroke: "#ffffff", width: 3)
+  c.ellipse(400, 300, 120, 80, fill: "#a6e3a1aa")
+  c.circle(650, 150, 60, fill: "#f38ba8")
+  c.line(50, 550, 750, 450, color: "#fab387", width: 6)
+  c.text("Hello, Direct2D!", 60, 220, font: "Segoe UI", size: 40, color: "#cdd6f4", bold: true)
+end.save("hello.png")
+```
+
+## Requirements
+
+- **Windows** with a native **MSVC (mswin)** Ruby (`x64-mswin64`). On a
+  MinGW/UCRT Ruby this gem is not supported — its `extconf.rb` will say so.
+- Visual Studio 2017+ or the Build Tools with the **Desktop development with
+  C++** workload (for `cl.exe` + the Windows SDK headers/libs).
+
+> Building uses [`vcvars`](https://rubygems.org/gems/vcvars) to load the MSVC
+> toolchain automatically — no "Developer Command Prompt" needed.
+
+## Install
+
+```sh
+gem install windraw
+```
+
+## API
+
+### `Windraw.surface(width, height) { |c| ... } → Surface`
+
+Creates an off-screen surface (pixels; origin top-left). With a block, it yields
+the surface, finishes drawing when the block returns, and returns the surface so
+you can chain `#save` / `#to_png`. All drawing methods return `self`.
+
+### Drawing
+
+```ruby
+c.clear("#1e1e2e")                                              # fill the whole canvas
+c.rectangle(x, y, w, h, fill:, stroke:, width: 1.0, radius: nil) # alias: c.rect; radius rounds corners
+c.ellipse(cx, cy, rx, ry, fill:, stroke:, width: 1.0)
+c.circle(cx, cy, radius, fill:, stroke:, width: 1.0)
+c.line(x1, y1, x2, y2, color: "#000000", width: 1.0)
+c.polygon([[x, y], ...], fill:, stroke:, width: 1.0)            # closed
+c.polyline([[x, y], ...], color: "#000000", width: 1.0)         # open
+c.text(str, x, y, color:, font: "Segoe UI", size: 16, bold: false, italic: false)
+```
+
+`radius:` takes a single Numeric (`rx == ry`) or an `[rx, ry]` pair.
+
+### Output & lifecycle
+
+```ruby
+surface.save("out.png")   # => "out.png"
+surface.to_png            # => String (PNG bytes, ASCII-8BIT)
+surface.size              # => [width, height]
+surface.close             # release COM resources now (alias: dispose; GC also frees)
+```
+
+> **Roadmap (0.2):** gradient brushes, arcs/bezier paths, and image compositing
+> (load + draw existing PNGs).
+
+`fill:` and `stroke:` take hex colors and are optional; passing both draws the
+fill first, then the stroke.
+
+### Colors
+
+Any CSS-style hex string: `#rgb`, `#rgba`, `#rrggbb`, or `#rrggbbaa` (the `#` is
+optional). Alpha is supported everywhere.
+
+```ruby
+Windraw::Color.parse("#ff8800")   # => [1.0, 0.533..., 0.0, 1.0]
+Windraw::Color.parse("#0af5")     # => [0.0, 0.666..., 1.0, 0.333...]
+```
+
+### Output
+
+```ruby
+surface.save("out.png")   # => "out.png"  (writes a PNG via WIC)
+surface.to_png            # => String     (PNG bytes, ASCII-8BIT)
+surface.size              # => [width, height]
+```
+
+## How it works
+
+A `Surface` creates a WIC bitmap and a Direct2D **WIC bitmap render target** at
+96 DPI (so 1 unit == 1 pixel). Drawing calls go straight to Direct2D /
+DirectWrite; `save`/`to_png` flush the render target (`EndDraw`) and encode the
+bitmap to PNG with WIC — to a file stream or an in-memory stream. COM is
+initialized per surface; drawing is intended to happen on the thread that
+created the surface.
+
+## License
+
+[MIT](LICENSE.txt).

data/ext/windraw/extconf.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+#
+# extconf.rb for the windraw C++ extension (Direct2D + DirectWrite + WIC).
+#
+# windraw is Windows-MSVC-only: it links the Direct2D/DirectWrite/WIC system
+# import libraries and uses the MSVC C++ compiler. mkmf auto-discovers the .cpp
+# source and compiles it as C++ (its CXX_EXT list includes "cpp").
+
+require "mkmf"
+
+unless RbConfig::CONFIG["target_os"] =~ /mswin/
+  abort <<~MSG
+    windraw requires a native Windows MSVC (mswin) Ruby — it builds against
+    Direct2D, DirectWrite, and WIC with cl.exe. Your Ruby is
+    "#{RbConfig::CONFIG['arch']}". On a MinGW/UCRT Ruby this gem is not supported.
+  MSG
+end
+
+# C++ exceptions are not enabled by the stock mswin CXXFLAGS; the extension uses
+# std::wstring (and C++ COM patterns), so turn them on.
+$CXXFLAGS << " -EHsc"
+
+# System import libraries. On mswin, mkmf expects bare "NAME.lib" tokens in
+# $libs (no -l prefix); they land on the link line after the Ruby import lib.
+#   d2d1          - Direct2D (D2D1CreateFactory, render target, brushes, shapes)
+#   dwrite        - DirectWrite (text formats + DrawText)
+#   windowscodecs - WIC (imaging factory, bitmap, PNG encoder, WIC CLSIDs)
+#   ole32         - COM (CoInitializeEx / CoCreateInstance / CoUninitialize)
+#   uuid          - additional CLSID/IID definitions
+#   shlwapi       - SHCreateMemStream (in-memory PNG for #to_png)
+$libs = [$libs, "d2d1.lib", "dwrite.lib", "windowscodecs.lib",
+         "ole32.lib", "uuid.lib", "shlwapi.lib"].join(" ")
+
+# Produces lib/windraw/windraw.so, required as "windraw/windraw".
+create_makefile("windraw/windraw")

data/ext/windraw/windraw.cpp

@@ -0,0 +1,635 @@
+/*
+ * windraw — headless 2D drawing for Windows via Direct2D + DirectWrite + WIC.
+ *
+ * Renders shapes and text into an off-screen WIC bitmap through a Direct2D
+ * render target, and encodes the result to PNG (to a file or an in-memory
+ * Ruby string). No window / message pump required.
+ *
+ * Build notes (verified on Ruby 3.4 x64-mswin64_140, MSVC cl 19.5):
+ *   - <ruby.h> MUST come before <windows.h> (winsock2 ordering / macro hygiene).
+ *   - <windows.h> #defines DrawText as DrawTextW (a GDI macro) and OUT/IN as SAL
+ *     markers; we #undef DrawText so rt->DrawText resolves to the D2D method, and
+ *     we never use OUT/IN as identifiers.
+ *   - All COM calls are checked; failures are released-then-raised so an rb_raise
+ *     longjmp never skips a Release. Numeric/string args are converted up front,
+ *     before any COM object exists, for the same reason.
+ */
+
+#include <ruby.h>
+#include <ruby/encoding.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <d2d1.h>
+#include <d2d1helper.h>
+#include <dwrite.h>
+#include <wincodec.h>
+#include <shlwapi.h>
+
+#include <string>
+#include <cstdlib>  /* malloc / free for the longjmp-safe PNG buffer */
+#include <climits>  /* LONG_MAX */
+
+/* NOTE on DrawText: <windows.h> defines `DrawText` as the GDI macro `DrawTextW`.
+ * Because that macro is active when <d2d1.h> is parsed, ID2D1RenderTarget's
+ * method is actually declared as `DrawTextW`, and our call site is rewritten the
+ * same way — so they match. Do NOT #undef DrawText here: that would desync the
+ * call (DrawText) from the real member (DrawTextW) -> C2039. */
+
+template <class T>
+static void SafeRelease(T** pp) {
+    if (*pp) { (*pp)->Release(); *pp = nullptr; }
+}
+
+typedef struct WindrawSurface {
+    UINT width;
+    UINT height;
+    DWORD thread_id;  /* thread that ran CoInitializeEx (teardown must match) */
+    bool com_owned;   /* did our CoInitializeEx succeed (so we must CoUninitialize)? */
+    bool draw_open;   /* BeginDraw issued, EndDraw not yet */
+    bool finished;    /* EndDraw done; drawing no longer allowed */
+    bool closed;      /* COM objects released + CoUninitialize done */
+    ID2D1Factory*        d2d;
+    IWICImagingFactory*  wic;
+    IWICBitmap*          bitmap;
+    ID2D1RenderTarget*   rt;
+    IDWriteFactory*      dwrite; /* created lazily on first text() */
+} WindrawSurface;
+
+/* ---- TypedData plumbing -------------------------------------------------- */
+
+/* Release every COM object and balance CoInitializeEx. MUST run on the thread
+ * that created the surface (COM init is per-thread; the D2D factory is
+ * single-threaded). */
+static void surface_teardown(WindrawSurface* s) {
+    if (s->draw_open && s->rt) { s->rt->EndDraw(); s->draw_open = false; }
+    SafeRelease(&s->dwrite);
+    SafeRelease(&s->rt);
+    SafeRelease(&s->bitmap);
+    SafeRelease(&s->wic);
+    SafeRelease(&s->d2d);
+    if (s->com_owned) { CoUninitialize(); s->com_owned = false; }
+    s->closed = true;
+}
+
+static void surface_free(void* p) {
+    WindrawSurface* s = static_cast<WindrawSurface*>(p);
+    if (!s) return;
+    if (!s->closed) {
+        /* COM init/uninit is per-thread and the D2D factory is single-threaded,
+         * so we can only tear down safely on the creating thread. GC may run
+         * this free on another thread; if so, skip COM teardown (a small leak)
+         * rather than corrupt COM state. Use #close on the creating thread for
+         * deterministic cleanup in multi-threaded programs. */
+        if (GetCurrentThreadId() == s->thread_id) surface_teardown(s);
+    }
+    xfree(s);
+}
+
+static size_t surface_memsize(const void* p) {
+    (void)p;
+    return sizeof(WindrawSurface);
+}
+
+static const rb_data_type_t surface_type = {
+    "Windraw::Surface",
+    { 0, surface_free, surface_memsize },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static VALUE surface_alloc(VALUE klass) {
+    WindrawSurface* s;
+    return TypedData_Make_Struct(klass, WindrawSurface, &surface_type, s);
+}
+
+static WindrawSurface* get_surface(VALUE self) {
+    WindrawSurface* s;
+    TypedData_Get_Struct(self, WindrawSurface, &surface_type, s);
+    return s;
+}
+
+/* ---- helpers ------------------------------------------------------------- */
+
+static void raise_hr(const char* what, HRESULT hr) {
+    rb_raise(rb_eRuntimeError, "windraw: %s failed (hr=0x%08lX)", what,
+             static_cast<unsigned long>(hr));
+}
+
+static void ensure_drawable(WindrawSurface* s) {
+    if (!s->rt) rb_raise(rb_eRuntimeError, "windraw: surface is not initialized");
+    if (s->finished || !s->draw_open)
+        rb_raise(rb_eRuntimeError, "windraw: surface is finished; cannot draw on it");
+}
+
+/* Convert a Ruby String (any encoding) to a UTF-16 std::wstring. */
+static std::wstring to_utf16(VALUE str) {
+    str = rb_str_export_to_enc(StringValue(str), rb_utf8_encoding());
+    long bytelen = RSTRING_LEN(str);
+    if (bytelen <= 0) return std::wstring();
+    const char* p = RSTRING_PTR(str);
+    int need = MultiByteToWideChar(CP_UTF8, 0, p, static_cast<int>(bytelen), nullptr, 0);
+    if (need <= 0) return std::wstring();
+    std::wstring w(static_cast<size_t>(need), L'\0');
+    MultiByteToWideChar(CP_UTF8, 0, p, static_cast<int>(bytelen), &w[0], need);
+    return w;
+}
+
+/* WIC-encode the surface's bitmap to a PNG written into `out`. Releases its own
+ * locals and returns the HRESULT; never raises (caller raises after cleanup). */
+static HRESULT encode_png(WindrawSurface* s, IStream* out) {
+    IWICBitmapEncoder*     encoder = nullptr;
+    IWICBitmapFrameEncode* frame   = nullptr;
+
+    HRESULT hr = s->wic->CreateEncoder(GUID_ContainerFormatPng, nullptr, &encoder);
+    if (SUCCEEDED(hr)) hr = encoder->Initialize(out, WICBitmapEncoderNoCache);
+    if (SUCCEEDED(hr)) hr = encoder->CreateNewFrame(&frame, nullptr);
+    if (SUCCEEDED(hr)) hr = frame->Initialize(nullptr);
+    if (SUCCEEDED(hr)) hr = frame->SetSize(s->width, s->height);
+    if (SUCCEEDED(hr)) {
+        WICPixelFormatGUID pf = GUID_WICPixelFormat32bppPBGRA;
+        hr = frame->SetPixelFormat(&pf);
+    }
+    if (SUCCEEDED(hr)) hr = frame->WriteSource(s->bitmap, nullptr);
+    if (SUCCEEDED(hr)) hr = frame->Commit();
+    if (SUCCEEDED(hr)) hr = encoder->Commit();
+
+    SafeRelease(&frame);
+    SafeRelease(&encoder);
+    return hr;
+}
+
+/* ---- methods ------------------------------------------------------------- */
+
+static VALUE surface_initialize(VALUE self, VALUE vw, VALUE vh) {
+    WindrawSurface* s = get_surface(self);
+    int w = NUM2INT(vw);
+    int h = NUM2INT(vh);
+    if (w <= 0 || h <= 0) rb_raise(rb_eArgError, "width and height must be positive");
+    s->width  = static_cast<UINT>(w);
+    s->height = static_cast<UINT>(h);
+    s->thread_id = GetCurrentThreadId();
+
+    HRESULT hr = CoInitializeEx(nullptr, COINIT_MULTITHREADED);
+    if (hr == S_OK || hr == S_FALSE) {
+        s->com_owned = true;          /* we incremented the init count; balance it */
+    } else if (hr == RPC_E_CHANGED_MODE) {
+        s->com_owned = false;         /* thread already in another apartment; usable, not ours */
+    } else {
+        raise_hr("CoInitializeEx", hr);
+    }
+
+    hr = D2D1CreateFactory(D2D1_FACTORY_TYPE_SINGLE_THREADED, __uuidof(ID2D1Factory),
+                           reinterpret_cast<void**>(&s->d2d));
+    if (FAILED(hr)) raise_hr("D2D1CreateFactory", hr);
+
+    hr = CoCreateInstance(CLSID_WICImagingFactory, nullptr, CLSCTX_INPROC_SERVER,
+                          IID_PPV_ARGS(&s->wic));
+    if (FAILED(hr)) raise_hr("CoCreateInstance(WICImagingFactory)", hr);
+
+    hr = s->wic->CreateBitmap(s->width, s->height, GUID_WICPixelFormat32bppPBGRA,
+                              WICBitmapCacheOnLoad, &s->bitmap);
+    if (FAILED(hr)) raise_hr("CreateBitmap", hr);
+
+    /* DPI 96 => 1 DIP == 1 pixel, so all coordinates are exact pixels. */
+    D2D1_RENDER_TARGET_PROPERTIES props = D2D1::RenderTargetProperties(
+        D2D1_RENDER_TARGET_TYPE_DEFAULT,
+        D2D1::PixelFormat(DXGI_FORMAT_B8G8R8A8_UNORM, D2D1_ALPHA_MODE_PREMULTIPLIED),
+        96.0f, 96.0f);
+    hr = s->d2d->CreateWicBitmapRenderTarget(s->bitmap, props, &s->rt);
+    if (FAILED(hr)) raise_hr("CreateWicBitmapRenderTarget", hr);
+
+    s->rt->BeginDraw();
+    s->draw_open = true;
+    s->rt->Clear(D2D1::ColorF(0.0f, 0.0f, 0.0f, 0.0f)); /* transparent canvas */
+    return self;
+}
+
+static VALUE surface_clear(VALUE self, VALUE vr, VALUE vg, VALUE vb, VALUE va) {
+    WindrawSurface* s = get_surface(self);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    ensure_drawable(s);
+    s->rt->Clear(D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                              static_cast<float>(b), static_cast<float>(a)));
+    return self;
+}
+
+static VALUE surface_fill_rect(VALUE self, VALUE vx, VALUE vy, VALUE vw, VALUE vh,
+                               VALUE vr, VALUE vg, VALUE vb, VALUE va) {
+    WindrawSurface* s = get_surface(self);
+    double x = NUM2DBL(vx), y = NUM2DBL(vy), w = NUM2DBL(vw), h = NUM2DBL(vh);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    ensure_drawable(s);
+
+    ID2D1SolidColorBrush* brush = nullptr;
+    HRESULT hr = s->rt->CreateSolidColorBrush(
+        D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                     static_cast<float>(b), static_cast<float>(a)), &brush);
+    if (SUCCEEDED(hr)) {
+        s->rt->FillRectangle(
+            D2D1::RectF(static_cast<float>(x), static_cast<float>(y),
+                        static_cast<float>(x + w), static_cast<float>(y + h)), brush);
+    }
+    SafeRelease(&brush);
+    if (FAILED(hr)) raise_hr("CreateSolidColorBrush", hr);
+    return self;
+}
+
+static VALUE surface_stroke_rect(VALUE self, VALUE vx, VALUE vy, VALUE vw, VALUE vh,
+                                 VALUE vr, VALUE vg, VALUE vb, VALUE va, VALUE vwidth) {
+    WindrawSurface* s = get_surface(self);
+    double x = NUM2DBL(vx), y = NUM2DBL(vy), w = NUM2DBL(vw), h = NUM2DBL(vh);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    double sw = NUM2DBL(vwidth);
+    ensure_drawable(s);
+
+    ID2D1SolidColorBrush* brush = nullptr;
+    HRESULT hr = s->rt->CreateSolidColorBrush(
+        D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                     static_cast<float>(b), static_cast<float>(a)), &brush);
+    if (SUCCEEDED(hr)) {
+        s->rt->DrawRectangle(
+            D2D1::RectF(static_cast<float>(x), static_cast<float>(y),
+                        static_cast<float>(x + w), static_cast<float>(y + h)),
+            brush, static_cast<float>(sw));
+    }
+    SafeRelease(&brush);
+    if (FAILED(hr)) raise_hr("CreateSolidColorBrush", hr);
+    return self;
+}
+
+static VALUE surface_fill_ellipse(VALUE self, VALUE vcx, VALUE vcy, VALUE vrx, VALUE vry,
+                                  VALUE vr, VALUE vg, VALUE vb, VALUE va) {
+    WindrawSurface* s = get_surface(self);
+    double cx = NUM2DBL(vcx), cy = NUM2DBL(vcy), rx = NUM2DBL(vrx), ry = NUM2DBL(vry);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    ensure_drawable(s);
+
+    ID2D1SolidColorBrush* brush = nullptr;
+    HRESULT hr = s->rt->CreateSolidColorBrush(
+        D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                     static_cast<float>(b), static_cast<float>(a)), &brush);
+    if (SUCCEEDED(hr)) {
+        s->rt->FillEllipse(
+            D2D1::Ellipse(D2D1::Point2F(static_cast<float>(cx), static_cast<float>(cy)),
+                          static_cast<float>(rx), static_cast<float>(ry)), brush);
+    }
+    SafeRelease(&brush);
+    if (FAILED(hr)) raise_hr("CreateSolidColorBrush", hr);
+    return self;
+}
+
+static VALUE surface_stroke_ellipse(VALUE self, VALUE vcx, VALUE vcy, VALUE vrx, VALUE vry,
+                                    VALUE vr, VALUE vg, VALUE vb, VALUE va, VALUE vwidth) {
+    WindrawSurface* s = get_surface(self);
+    double cx = NUM2DBL(vcx), cy = NUM2DBL(vcy), rx = NUM2DBL(vrx), ry = NUM2DBL(vry);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    double sw = NUM2DBL(vwidth);
+    ensure_drawable(s);
+
+    ID2D1SolidColorBrush* brush = nullptr;
+    HRESULT hr = s->rt->CreateSolidColorBrush(
+        D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                     static_cast<float>(b), static_cast<float>(a)), &brush);
+    if (SUCCEEDED(hr)) {
+        s->rt->DrawEllipse(
+            D2D1::Ellipse(D2D1::Point2F(static_cast<float>(cx), static_cast<float>(cy)),
+                          static_cast<float>(rx), static_cast<float>(ry)),
+            brush, static_cast<float>(sw));
+    }
+    SafeRelease(&brush);
+    if (FAILED(hr)) raise_hr("CreateSolidColorBrush", hr);
+    return self;
+}
+
+static VALUE surface_line(VALUE self, VALUE vx1, VALUE vy1, VALUE vx2, VALUE vy2,
+                          VALUE vr, VALUE vg, VALUE vb, VALUE va, VALUE vwidth) {
+    WindrawSurface* s = get_surface(self);
+    double x1 = NUM2DBL(vx1), y1 = NUM2DBL(vy1), x2 = NUM2DBL(vx2), y2 = NUM2DBL(vy2);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    double sw = NUM2DBL(vwidth);
+    ensure_drawable(s);
+
+    ID2D1SolidColorBrush* brush = nullptr;
+    HRESULT hr = s->rt->CreateSolidColorBrush(
+        D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                     static_cast<float>(b), static_cast<float>(a)), &brush);
+    if (SUCCEEDED(hr)) {
+        s->rt->DrawLine(
+            D2D1::Point2F(static_cast<float>(x1), static_cast<float>(y1)),
+            D2D1::Point2F(static_cast<float>(x2), static_cast<float>(y2)),
+            brush, static_cast<float>(sw));
+    }
+    SafeRelease(&brush);
+    if (FAILED(hr)) raise_hr("CreateSolidColorBrush", hr);
+    return self;
+}
+
+static VALUE surface_fill_round_rect(VALUE self, VALUE vx, VALUE vy, VALUE vw, VALUE vh,
+                                     VALUE vrx, VALUE vry,
+                                     VALUE vr, VALUE vg, VALUE vb, VALUE va) {
+    WindrawSurface* s = get_surface(self);
+    double x = NUM2DBL(vx), y = NUM2DBL(vy), w = NUM2DBL(vw), h = NUM2DBL(vh);
+    double rx = NUM2DBL(vrx), ry = NUM2DBL(vry);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    ensure_drawable(s);
+
+    ID2D1SolidColorBrush* brush = nullptr;
+    HRESULT hr = s->rt->CreateSolidColorBrush(
+        D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                     static_cast<float>(b), static_cast<float>(a)), &brush);
+    if (SUCCEEDED(hr)) {
+        D2D1_ROUNDED_RECT rr = D2D1::RoundedRect(
+            D2D1::RectF(static_cast<float>(x), static_cast<float>(y),
+                        static_cast<float>(x + w), static_cast<float>(y + h)),
+            static_cast<float>(rx), static_cast<float>(ry));
+        s->rt->FillRoundedRectangle(rr, brush);
+    }
+    SafeRelease(&brush);
+    if (FAILED(hr)) raise_hr("CreateSolidColorBrush", hr);
+    return self;
+}
+
+static VALUE surface_stroke_round_rect(VALUE self, VALUE vx, VALUE vy, VALUE vw, VALUE vh,
+                                       VALUE vrx, VALUE vry,
+                                       VALUE vr, VALUE vg, VALUE vb, VALUE va, VALUE vwidth) {
+    WindrawSurface* s = get_surface(self);
+    double x = NUM2DBL(vx), y = NUM2DBL(vy), w = NUM2DBL(vw), h = NUM2DBL(vh);
+    double rx = NUM2DBL(vrx), ry = NUM2DBL(vry);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    double sw = NUM2DBL(vwidth);
+    ensure_drawable(s);
+
+    ID2D1SolidColorBrush* brush = nullptr;
+    HRESULT hr = s->rt->CreateSolidColorBrush(
+        D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                     static_cast<float>(b), static_cast<float>(a)), &brush);
+    if (SUCCEEDED(hr)) {
+        D2D1_ROUNDED_RECT rr = D2D1::RoundedRect(
+            D2D1::RectF(static_cast<float>(x), static_cast<float>(y),
+                        static_cast<float>(x + w), static_cast<float>(y + h)),
+            static_cast<float>(rx), static_cast<float>(ry));
+        s->rt->DrawRoundedRectangle(rr, brush, static_cast<float>(sw));
+    }
+    SafeRelease(&brush);
+    if (FAILED(hr)) raise_hr("CreateSolidColorBrush", hr);
+    return self;
+}
+
+/* Build a closed/open path geometry from a flat [x0,y0,x1,y1,...] Ruby array.
+ * Returns the geometry (caller Releases) or raises. All point values are
+ * validated and extracted into a malloc'd buffer up front, so no rb_raise can
+ * longjmp while a COM object or the buffer is held un-freed. */
+static ID2D1PathGeometry* build_polygon_geometry(WindrawSurface* s, VALUE arr,
+                                                 bool closed, bool filled) {
+    Check_Type(arr, T_ARRAY);
+    long n = RARRAY_LEN(arr);
+    if (n < 4 || (n % 2) != 0) {
+        rb_raise(rb_eArgError,
+                 "windraw: polygon/polyline needs an even, >= 2 list of x,y coordinates");
+    }
+    for (long i = 0; i < n; i++) {
+        VALUE e = rb_ary_entry(arr, i);
+        if (!RTEST(rb_obj_is_kind_of(e, rb_cNumeric)))
+            rb_raise(rb_eTypeError, "windraw: polygon points must be numbers");
+        /* Force the float conversion now: a Numeric that can't become a Float
+         * (e.g. a Complex with imaginary part) raises HERE, before malloc, so
+         * the longjmp can't skip free(pts). */
+        (void)NUM2DBL(e);
+    }
+
+    long npoints = n / 2;
+    D2D1_POINT_2F* pts =
+        static_cast<D2D1_POINT_2F*>(malloc(sizeof(D2D1_POINT_2F) * static_cast<size_t>(npoints)));
+    if (!pts) rb_raise(rb_eNoMemError, "windraw: out of memory building polygon");
+    for (long i = 0; i < npoints; i++) {
+        pts[i].x = static_cast<float>(NUM2DBL(rb_ary_entry(arr, 2 * i)));
+        pts[i].y = static_cast<float>(NUM2DBL(rb_ary_entry(arr, 2 * i + 1)));
+    }
+
+    ID2D1PathGeometry* geo  = nullptr;
+    ID2D1GeometrySink* sink = nullptr;
+    HRESULT hr = s->d2d->CreatePathGeometry(&geo);
+    if (SUCCEEDED(hr)) hr = geo->Open(&sink);
+    if (SUCCEEDED(hr)) {
+        sink->BeginFigure(pts[0],
+                          filled ? D2D1_FIGURE_BEGIN_FILLED : D2D1_FIGURE_BEGIN_HOLLOW);
+        if (npoints > 1) sink->AddLines(pts + 1, static_cast<UINT32>(npoints - 1));
+        sink->EndFigure(closed ? D2D1_FIGURE_END_CLOSED : D2D1_FIGURE_END_OPEN);
+        hr = sink->Close();
+    }
+    SafeRelease(&sink);
+    free(pts);
+    if (FAILED(hr)) { SafeRelease(&geo); raise_hr("path geometry", hr); }
+    return geo;
+}
+
+static VALUE surface_fill_polygon(VALUE self, VALUE arr,
+                                  VALUE vr, VALUE vg, VALUE vb, VALUE va) {
+    WindrawSurface* s = get_surface(self);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    ensure_drawable(s);
+
+    ID2D1PathGeometry* geo = build_polygon_geometry(s, arr, /*closed*/ true, /*filled*/ true);
+    ID2D1SolidColorBrush* brush = nullptr;
+    HRESULT hr = s->rt->CreateSolidColorBrush(
+        D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                     static_cast<float>(b), static_cast<float>(a)), &brush);
+    if (SUCCEEDED(hr)) s->rt->FillGeometry(geo, brush);
+    SafeRelease(&brush);
+    SafeRelease(&geo);
+    if (FAILED(hr)) raise_hr("CreateSolidColorBrush", hr);
+    return self;
+}
+
+static VALUE surface_stroke_polygon(VALUE self, VALUE arr,
+                                    VALUE vr, VALUE vg, VALUE vb, VALUE va,
+                                    VALUE vwidth, VALUE vclosed) {
+    WindrawSurface* s = get_surface(self);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    double sw = NUM2DBL(vwidth);
+    bool closed = RTEST(vclosed);
+    ensure_drawable(s);
+
+    ID2D1PathGeometry* geo = build_polygon_geometry(s, arr, closed, /*filled*/ false);
+    ID2D1SolidColorBrush* brush = nullptr;
+    HRESULT hr = s->rt->CreateSolidColorBrush(
+        D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                     static_cast<float>(b), static_cast<float>(a)), &brush);
+    if (SUCCEEDED(hr)) s->rt->DrawGeometry(geo, brush, static_cast<float>(sw));
+    SafeRelease(&brush);
+    SafeRelease(&geo);
+    if (FAILED(hr)) raise_hr("CreateSolidColorBrush", hr);
+    return self;
+}
+
+static VALUE surface_text(VALUE self, VALUE vstr, VALUE vx, VALUE vy,
+                          VALUE vr, VALUE vg, VALUE vb, VALUE va,
+                          VALUE vfont, VALUE vsize, VALUE vbold, VALUE vitalic) {
+    WindrawSurface* s = get_surface(self);
+    double x = NUM2DBL(vx), y = NUM2DBL(vy), size = NUM2DBL(vsize);
+    double r = NUM2DBL(vr), g = NUM2DBL(vg), b = NUM2DBL(vb), a = NUM2DBL(va);
+    DWRITE_FONT_WEIGHT weight = RTEST(vbold) ? DWRITE_FONT_WEIGHT_BOLD
+                                             : DWRITE_FONT_WEIGHT_NORMAL;
+    DWRITE_FONT_STYLE style = RTEST(vitalic) ? DWRITE_FONT_STYLE_ITALIC
+                                             : DWRITE_FONT_STYLE_NORMAL;
+    /* Coerce both strings up front: if either is not String-convertible, the
+     * TypeError must raise before any std::wstring exists (rb_raise longjmps
+     * past C++ destructors, which would otherwise leak the first wstring). */
+    StringValue(vfont);
+    StringValue(vstr);
+    ensure_drawable(s);
+
+    /* Lazily create the DirectWrite factory (shared). */
+    if (!s->dwrite) {
+        HRESULT hr = DWriteCreateFactory(DWRITE_FACTORY_TYPE_SHARED, __uuidof(IDWriteFactory),
+                                         reinterpret_cast<IUnknown**>(&s->dwrite));
+        if (FAILED(hr)) raise_hr("DWriteCreateFactory", hr);
+    }
+
+    HRESULT hr;
+    IDWriteTextFormat*    format = nullptr;
+    ID2D1SolidColorBrush* brush  = nullptr;
+    {
+        std::wstring wfont = to_utf16(vfont);
+        std::wstring wtext = to_utf16(vstr);
+        hr = s->dwrite->CreateTextFormat(wfont.c_str(), nullptr, weight, style,
+                 DWRITE_FONT_STRETCH_NORMAL, static_cast<float>(size), L"", &format);
+        if (SUCCEEDED(hr)) {
+            hr = s->rt->CreateSolidColorBrush(
+                D2D1::ColorF(static_cast<float>(r), static_cast<float>(g),
+                             static_cast<float>(b), static_cast<float>(a)), &brush);
+        }
+        if (SUCCEEDED(hr)) {
+            D2D1_RECT_F rect = D2D1::RectF(static_cast<float>(x), static_cast<float>(y),
+                                           static_cast<float>(s->width),
+                                           static_cast<float>(s->height));
+            s->rt->DrawText(wtext.c_str(), static_cast<UINT32>(wtext.length()),
+                            format, rect, brush);
+        }
+    } /* wfont/wtext destroyed here, before any possible raise */
+
+    SafeRelease(&brush);
+    SafeRelease(&format);
+    if (FAILED(hr)) raise_hr("CreateTextFormat/DrawText", hr);
+    return self;
+}
+
+static void ensure_encodable(WindrawSurface* s) {
+    if (s->closed || !s->wic) rb_raise(rb_eRuntimeError, "windraw: surface is closed");
+}
+
+static VALUE surface_finish(VALUE self) {
+    WindrawSurface* s = get_surface(self);
+    if (s->draw_open && s->rt) {
+        HRESULT hr = s->rt->EndDraw();
+        s->draw_open = false;
+        s->finished  = true;
+        if (FAILED(hr)) raise_hr("EndDraw", hr);
+    }
+    s->finished = true;
+    return self;
+}
+
+/* Release all COM resources now, on the calling (creating) thread. Idempotent.
+ * After #close the surface can no longer draw or encode. */
+static VALUE surface_close(VALUE self) {
+    WindrawSurface* s = get_surface(self);
+    if (!s->closed) surface_teardown(s);
+    return self;
+}
+
+static VALUE surface_save(VALUE self, VALUE vpath) {
+    WindrawSurface* s = get_surface(self);
+    ensure_encodable(s);
+    surface_finish(self); /* flush drawing before encoding */
+
+    IWICStream* stream = nullptr;
+    HRESULT hr;
+    {
+        std::wstring wpath = to_utf16(vpath);
+        hr = s->wic->CreateStream(&stream);
+        if (SUCCEEDED(hr)) hr = stream->InitializeFromFilename(wpath.c_str(), GENERIC_WRITE);
+    } /* wpath destroyed before any raise */
+    if (SUCCEEDED(hr)) hr = encode_png(s, stream);
+    SafeRelease(&stream);
+    if (FAILED(hr)) raise_hr("save", hr);
+    return vpath;
+}
+
+static VALUE surface_to_png(VALUE self) {
+    WindrawSurface* s = get_surface(self);
+    ensure_encodable(s);
+    surface_finish(self);
+
+    IStream* mem = SHCreateMemStream(nullptr, 0);
+    if (!mem) rb_raise(rb_eRuntimeError, "windraw: SHCreateMemStream failed");
+
+    /* Drain the encoded PNG into a plain C buffer while the stream is alive,
+     * then Release the stream BEFORE building the Ruby string. rb_str_new can
+     * raise (NoMemError) via longjmp, which would otherwise skip mem->Release()
+     * and leak the COM stream. We also reject >LONG_MAX sizes up front (on
+     * LLP64 a cast to `long` would otherwise go negative). */
+    char* buf = nullptr;
+    long  buflen = 0;
+    HRESULT hr = encode_png(s, mem);
+    if (SUCCEEDED(hr)) {
+        STATSTG st;
+        hr = mem->Stat(&st, STATFLAG_NONAME);
+        if (SUCCEEDED(hr)) {
+            ULONGLONG full = st.cbSize.QuadPart;
+            if (full > static_cast<ULONGLONG>(LONG_MAX)) {
+                hr = E_OUTOFMEMORY; /* PNG too large to hand to Ruby */
+            } else if (full > 0) {
+                LARGE_INTEGER zero;
+                zero.QuadPart = 0;
+                hr = mem->Seek(zero, STREAM_SEEK_SET, nullptr);
+                if (SUCCEEDED(hr)) {
+                    buf = static_cast<char*>(malloc(static_cast<size_t>(full)));
+                    if (!buf) {
+                        hr = E_OUTOFMEMORY;
+                    } else {
+                        ULONG got = 0;
+                        hr = mem->Read(buf, static_cast<ULONG>(full), &got);
+                        if (SUCCEEDED(hr)) buflen = static_cast<long>(got);
+                    }
+                }
+            }
+        }
+    }
+    mem->Release();
+    if (FAILED(hr)) { free(buf); raise_hr("to_png", hr); }
+
+    VALUE result = rb_str_new(buf, buflen); /* copies; buf may be null when 0 */
+    free(buf);
+    rb_enc_associate(result, rb_ascii8bit_encoding());
+    return result;
+}
+
+static VALUE surface_width(VALUE self)  { return UINT2NUM(get_surface(self)->width); }
+static VALUE surface_height(VALUE self) { return UINT2NUM(get_surface(self)->height); }
+
+extern "C" void Init_windraw(void) {
+    VALUE mWindraw = rb_define_module("Windraw");
+    VALUE cSurface = rb_define_class_under(mWindraw, "Surface", rb_cObject);
+
+    rb_define_alloc_func(cSurface, surface_alloc);
+    rb_define_method(cSurface, "initialize", RUBY_METHOD_FUNC(surface_initialize), 2);
+    rb_define_method(cSurface, "_clear",          RUBY_METHOD_FUNC(surface_clear),          4);
+    rb_define_method(cSurface, "_fill_rect",      RUBY_METHOD_FUNC(surface_fill_rect),      8);
+    rb_define_method(cSurface, "_stroke_rect",    RUBY_METHOD_FUNC(surface_stroke_rect),    9);
+    rb_define_method(cSurface, "_fill_ellipse",   RUBY_METHOD_FUNC(surface_fill_ellipse),   8);
+    rb_define_method(cSurface, "_stroke_ellipse", RUBY_METHOD_FUNC(surface_stroke_ellipse), 9);
+    rb_define_method(cSurface, "_line",           RUBY_METHOD_FUNC(surface_line),           9);
+    rb_define_method(cSurface, "_fill_round_rect",   RUBY_METHOD_FUNC(surface_fill_round_rect),   10);
+    rb_define_method(cSurface, "_stroke_round_rect", RUBY_METHOD_FUNC(surface_stroke_round_rect), 11);
+    rb_define_method(cSurface, "_fill_polygon",   RUBY_METHOD_FUNC(surface_fill_polygon),   5);
+    rb_define_method(cSurface, "_stroke_polygon", RUBY_METHOD_FUNC(surface_stroke_polygon), 7);
+    rb_define_method(cSurface, "_text",           RUBY_METHOD_FUNC(surface_text),          11);
+    rb_define_method(cSurface, "finish",          RUBY_METHOD_FUNC(surface_finish),         0);
+    rb_define_method(cSurface, "close",           RUBY_METHOD_FUNC(surface_close),          0);
+    rb_define_method(cSurface, "save",            RUBY_METHOD_FUNC(surface_save),           1);
+    rb_define_method(cSurface, "to_png",          RUBY_METHOD_FUNC(surface_to_png),         0);
+    rb_define_method(cSurface, "width",           RUBY_METHOD_FUNC(surface_width),          0);
+    rb_define_method(cSurface, "height",          RUBY_METHOD_FUNC(surface_height),         0);
+    rb_define_alias(cSurface, "dispose", "close");
+}

data/lib/windraw/color.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Windraw
+  # Parses CSS-style hex colors into straight (non-premultiplied) RGBA floats in
+  # 0.0..1.0, the form Direct2D's D2D1::ColorF expects.
+  module Color
+    module_function
+
+    # Accepts "#rgb", "#rgba", "#rrggbb", "#rrggbbaa" (leading "#" optional).
+    # Returns [r, g, b, a] as floats in 0.0..1.0. Raises ArgumentError otherwise.
+    def parse(spec, default_alpha: 1.0)
+      unless spec.is_a?(String) || spec.respond_to?(:to_str)
+        raise ArgumentError, "invalid hex color: #{spec.inspect} (expected a String)"
+      end
+      s = spec.to_s.strip
+      s = s[1..] if s.start_with?("#")
+
+      unless s.match?(/\A\h+\z/)
+        raise ArgumentError, "invalid hex color: #{spec.inspect} (non-hex characters)"
+      end
+
+      case s.length
+      when 3 # rgb
+        r, g, b = s.chars.map { |c| (c * 2).to_i(16) }
+        a = (default_alpha * 255).round
+      when 4 # rgba
+        r, g, b, a = s.chars.map { |c| (c * 2).to_i(16) }
+      when 6 # rrggbb
+        r, g, b = s.scan(/../).map { |h| h.to_i(16) }
+        a = (default_alpha * 255).round
+      when 8 # rrggbbaa
+        r, g, b, a = s.scan(/../).map { |h| h.to_i(16) }
+      else
+        raise ArgumentError,
+              "invalid hex color: #{spec.inspect} (use #rgb, #rgba, #rrggbb, or #rrggbbaa)"
+      end
+
+      [r / 255.0, g / 255.0, b / 255.0, a / 255.0]
+    end
+  end
+end

data/lib/windraw/surface.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "windraw/color"
+
+module Windraw
+  # Ergonomic, hex-color-aware drawing API layered over the native Surface
+  # primitives (defined in the C++ extension). Coordinates are in pixels; the
+  # origin (0, 0) is the top-left corner.
+  #
+  # Every drawing method returns self, so calls can be chained.
+  class Surface
+    # Fill the whole surface with a single color (default fully transparent).
+    def clear(color = "#00000000")
+      r, g, b, a = Color.parse(color)
+      _clear(r, g, b, a)
+      self
+    end
+
+    # Axis-aligned rectangle from (x, y) with the given width/height.
+    # Pass fill: and/or stroke: hex colors; with both, fill is drawn first.
+    # radius: rounds the corners — a single Numeric (rx == ry) or a [rx, ry] pair.
+    def rectangle(x, y, w, h, fill: nil, stroke: nil, width: 1.0, radius: nil)
+      if radius
+        rx, ry =
+          if radius.is_a?(Array)
+            unless radius.length == 2
+              raise ArgumentError, "radius: must be a Numeric or an [rx, ry] pair, got #{radius.inspect}"
+            end
+            radius
+          else
+            [radius, radius]
+          end
+        if fill
+          r, g, b, a = Color.parse(fill)
+          _fill_round_rect(x, y, w, h, rx, ry, r, g, b, a)
+        end
+        if stroke
+          r, g, b, a = Color.parse(stroke)
+          _stroke_round_rect(x, y, w, h, rx, ry, r, g, b, a, width)
+        end
+      else
+        if fill
+          r, g, b, a = Color.parse(fill)
+          _fill_rect(x, y, w, h, r, g, b, a)
+        end
+        if stroke
+          r, g, b, a = Color.parse(stroke)
+          _stroke_rect(x, y, w, h, r, g, b, a, width)
+        end
+      end
+      self
+    end
+    alias rect rectangle
+
+    # Ellipse centered at (cx, cy) with radii rx, ry.
+    def ellipse(cx, cy, rx, ry, fill: nil, stroke: nil, width: 1.0)
+      if fill
+        r, g, b, a = Color.parse(fill)
+        _fill_ellipse(cx, cy, rx, ry, r, g, b, a)
+      end
+      if stroke
+        r, g, b, a = Color.parse(stroke)
+        _stroke_ellipse(cx, cy, rx, ry, r, g, b, a, width)
+      end
+      self
+    end
+
+    # Circle centered at (cx, cy) — convenience for an ellipse with equal radii.
+    def circle(cx, cy, radius, fill: nil, stroke: nil, width: 1.0)
+      ellipse(cx, cy, radius, radius, fill: fill, stroke: stroke, width: width)
+    end
+
+    # Straight line from (x1, y1) to (x2, y2).
+    def line(x1, y1, x2, y2, color: "#000000", width: 1.0)
+      r, g, b, a = Color.parse(color)
+      _line(x1, y1, x2, y2, r, g, b, a, width)
+      self
+    end
+
+    # Closed polygon through the given points (an Array of [x, y] pairs).
+    # fill: and/or stroke: hex colors; with both, fill is drawn first.
+    def polygon(points, fill: nil, stroke: nil, width: 1.0)
+      flat = flatten_points(points)
+      if fill
+        r, g, b, a = Color.parse(fill)
+        _fill_polygon(flat, r, g, b, a)
+      end
+      if stroke
+        r, g, b, a = Color.parse(stroke)
+        _stroke_polygon(flat, r, g, b, a, width, true)
+      end
+      self
+    end
+
+    # Open connected line segments through the given points (Array of [x, y]).
+    def polyline(points, color: "#000000", width: 1.0)
+      r, g, b, a = Color.parse(color)
+      _stroke_polygon(flatten_points(points), r, g, b, a, width, false)
+      self
+    end
+
+    # Draw a string with its top-left at (x, y).
+    def text(string, x, y, color: "#000000", font: "Segoe UI", size: 16.0,
+             bold: false, italic: false)
+      r, g, b, a = Color.parse(color)
+      _text(string.to_s, x, y, r, g, b, a, font.to_s, size, bold, italic)
+      self
+    end
+
+    # [width, height] in pixels.
+    def size
+      [width, height]
+    end
+
+    def inspect
+      "#<Windraw::Surface #{width}x#{height}>"
+    end
+
+    private
+
+    # Convert an Array of [x, y] pairs into a flat [x0, y0, x1, y1, ...] Array of
+    # Floats. Raises ArgumentError on non-numeric coords or fewer than 2 points.
+    def flatten_points(points)
+      flat = Array(points).flat_map do |p|
+        unless p.is_a?(Array) && p.length == 2
+          raise ArgumentError, "each point must be an [x, y] pair, got #{p.inspect}"
+        end
+        [Float(p[0]), Float(p[1])]
+      end
+      if flat.length < 4
+        raise ArgumentError, "need at least 2 [x, y] points, got #{points.inspect}"
+      end
+      flat
+    end
+  end
+end

data/lib/windraw/version.rb

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

data/lib/windraw.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "windraw/version"
+require "windraw/windraw"  # native C++ extension: defines Windraw::Surface
+require "windraw/color"
+require "windraw/surface"  # reopens Windraw::Surface with the ergonomic API
+
+# windraw — headless 2D drawing for Windows using Direct2D + DirectWrite + WIC.
+#
+#   Windraw.surface(800, 600) do |c|
+#     c.clear("#1e1e2e")
+#     c.rectangle(50, 50, 200, 120, fill: "#89b4fa")
+#     c.ellipse(400, 300, 80, 50, fill: "#a6e3a1")
+#     c.text("Hello, Direct2D!", 60, 200, font: "Segoe UI", size: 32, color: "#cdd6f4")
+#   end.save("out.png")
+module Windraw
+  # Create a drawing surface of the given pixel size. With a block, yields the
+  # surface, finishes drawing when the block returns, and returns the surface
+  # (so you can chain #save / #to_png). Without a block, returns an open surface.
+  #
+  # width/height are whole pixels; a Float is truncated toward zero (NUM2INT).
+  def self.surface(width, height)
+    surface = Surface.new(width, height)
+    if block_given?
+      yield surface
+      surface.finish
+    end
+    surface
+  end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: windraw
+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: |
+  windraw renders shapes and text into an off-screen bitmap using the graphics
+  stack that already ships with Windows — Direct2D for vector drawing,
+  DirectWrite for text, and WIC for PNG encoding — then saves a PNG to a file
+  or returns the bytes as a string. A Cairo-style 2D canvas with no window or
+  message loop required. Windows MSVC (mswin) Ruby only.
+executables: []
+extensions:
+- ext/windraw/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/windraw/extconf.rb
+- ext/windraw/windraw.cpp
+- lib/windraw.rb
+- lib/windraw/color.rb
+- lib/windraw/surface.rb
+- lib/windraw/version.rb
+homepage: https://github.com/main-path/windraw
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-path/windraw
+  changelog_uri: https://github.com/main-path/windraw/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/windraw/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: Headless 2D drawing for Windows (Direct2D + DirectWrite + WIC) to PNG.
+test_files: []