wintoast 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a5ffc4e1ef7ddebe12e6096aa293b1d70f96a8bb8c7fdba4e6c807dc80578f6
+  data.tar.gz: d7d1357b903a3582b4e51b5616a83e13f4a1c0dbbc94c273c9bf3d8234c1daef
+SHA512:
+  metadata.gz: 1f0271faa0e9e3ee302a7e54d74eff648c75538432ae821b58fc338b2eb25c5da1f0cff9e034da31ad94ad44c515967975b05d420ee9784e1cdd7f106c90e14c
+  data.tar.gz: 48714a218686fdfb01849299231162881f70302e8ae9278ce1dc3f6858ab8505da5a88fdcc87aa4acff32ab287effe9844d0f1234f5c5ff32411ad1282adfa91

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# 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-06-27
+
+Initial release.
+
+- `Wintoast.toast(title, body = nil, ...)` — fire-and-forget toast notification
+  via the inbox WinRT API (no App SDK, no packaging, no COM server). Supports
+  `aumid:`, `attribution:`, `image:`/`hero:` (local absolute paths) with
+  `circle:`, `audio:` (system sounds or `false` for silent), `duration:`,
+  `scenario:` (`:alarm`/`:incoming_call`/`:urgent`), `expires_at:`/`expires_in:`,
+  and `tag:`/`group:` replacement keys. Returns `nil` (accepted, not necessarily
+  displayed — silent suppression is undetectable by design of the platform).
+- `Wintoast.register!(aumid:, display_name:, icon: nil)` /
+  `Wintoast.unregister!(aumid:)` — opt-in, reversible, per-user branding that
+  writes only `HKCU\Software\Classes\AppUserModelId\<aumid>`. No elevation, no
+  Start-Menu shortcut, no HKLM, no COM activator. `unregister!` is idempotent
+  (`false` when the key was absent).
+- `Wintoast.progress(value = nil, of: 100, state: nil)` /
+  `Wintoast.progress_clear` — taskbar (`ITaskbarList3`) and Windows Terminal tab
+  (OSC 9;4) progress on every call; exactly one renders per host. Returns
+  `true`/`false` (accepted, not necessarily visible); environmental failure is a
+  `false`, never an exception. Never writes OSC bytes to a redirected stdout.
+- `Wintoast::Payload.build(title, body = nil, ...)` — the pure-Ruby
+  `ToastGeneric` XML builder, exposed for debugging and as the escaping /
+  audio-mapping test seam.
+- `Wintoast::POWERSHELL_AUMID` — the registered-everywhere default AUMID, so
+  `Wintoast.toast("hi")` works on a stock machine (branded "Windows PowerShell").
+- `Wintoast::Error` / `Wintoast::OSError` (with `#code`) error hierarchy.
+
+Windows MSVC (mswin) Ruby only; Windows 10 1809+ / Windows 11, x64.
+
+[Unreleased]: https://github.com/main-path/wintoast/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/main-path/wintoast/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,335 @@
+# wintoast
+
+**Fire-and-forget Windows toast notifications and taskbar/terminal progress for Ruby — inbox WinRT and shell APIs only, no App SDK, no packaging, no COM server.**
+
+Scripts deserve native notifications. When a backup finishes, a build breaks, or
+a long job crosses 50%, a plain `ruby.exe` should be able to pop a real Windows
+toast and light up the taskbar — without bundling a runtime or registering a COM
+activation server.
+
+That gap is real. PowerShell's [BurntToast] exists, but there is nothing
+native-and-thin for Ruby; the [Windows App SDK] notification path drags in a
+NuGet runtime, an MSIX singleton package, and a bootstrapper — against this
+suite's OS-libraries-only rule. `wintoast` uses the **inbox** WinRT notification
+API (`Windows.UI.Notifications`, shipped with Windows since 10240) via
+`RoGetActivationFactory`, plus `ITaskbarList3` and the terminal OSC 9;4 progress
+sequence. Nothing to install but the gem.
+
+> Not to be confused with [mohabouje/WinToast], a C++ library — different
+> ecosystem, same idea.
+
+```ruby
+require "wintoast"
+
+Wintoast.toast("Backup finished", "1,204 files in 38 s")
+# => nil  (a banner pops; it persists in the Notification Center)
+```
+
+| What | API |
+|---|---|
+| Pop a toast | `Wintoast.toast(title, body, ...)` |
+| Brand it (opt-in) | `Wintoast.register!` / `Wintoast.unregister!` |
+| Taskbar + tab progress | `Wintoast.progress` / `Wintoast.progress_clear` |
+| Inspect the XML | `Wintoast::Payload.build` |
+
+## Requirements
+
+- **Windows 10 1809+ or Windows 11** 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).
+- x64. arm64-mswin is expected to work (all code is arch-neutral) but is
+  untested and unsupported until an arm64-mswin Ruby distribution exists.
+
+> Building uses [`vcvars`](https://rubygems.org/gems/vcvars) to load the MSVC
+> toolchain automatically — no "Developer Command Prompt" needed. If a build
+> fails, run `vcvars doctor`.
+
+## Install
+
+```sh
+gem install wintoast
+```
+
+## Quick start
+
+**Zero setup — works on a stock machine (branded "Windows PowerShell"):**
+
+```ruby
+require "wintoast"
+
+Wintoast.toast("Backup finished", "1,204 files in 38 s")
+# => nil  (a banner pops; it persists in the Notification Center)
+
+# Soften the borrowed branding with an attribution line:
+Wintoast.toast("Backup finished", "1,204 files in 38 s", attribution: "via backup.rb")
+```
+
+**Own branding — one-time, per-user, reversible, no admin:**
+
+```ruby
+AUMID = Wintoast.register!(aumid: "Acme.BackupTool", display_name: "Acme Backup",
+                           icon: "C:/Acme/backup.png")  # => "Acme.BackupTool"
+
+Wintoast.toast("Backup finished", aumid: AUMID,
+               image: "C:/Acme/backup.png", circle: true,
+               audio: :mail, duration: :long,
+               expires_in: 3600, tag: "backup", group: "acme")
+# A later toast with tag: "backup", group: "acme" REPLACES this one in Action Center.
+
+Wintoast.unregister!(aumid: "Acme.BackupTool")  # => true
+```
+
+**Progress around a work loop (taskbar under conhost, tab ring under Windows Terminal):**
+
+```ruby
+begin
+  files.each_with_index do |f, i|
+    process(f)
+    Wintoast.progress(i + 1, of: files.size)
+  end
+  Wintoast.toast("Done", "#{files.size} files processed")
+rescue => e
+  Wintoast.progress(100, state: :error)   # red bar
+  Wintoast.toast("Failed", e.message, audio: :reminder)
+  raise
+ensure
+  Wintoast.progress_clear
+end
+```
+
+**Failure paths, demonstrated:**
+
+```ruby
+Wintoast.toast("hi", image: "logo.png")
+# => ArgumentError: wintoast: image: must be an absolute path to an existing file
+
+Wintoast.toast("hi", aumid: "Not.Registered.Anywhere")
+# => nil — and NOTHING is displayed. Unregistered AUMIDs are silently dropped by
+#    Windows (no error, no Action Center entry). Use register! or the default AUMID.
+
+Wintoast.progress(50, state: :indeterminate)
+# => ArgumentError: wintoast: state: :indeterminate ignores value — pass value nil
+```
+
+## The one trap you must know about
+
+**An unregistered AUMID is silently dropped by Windows.** `Show()` returns
+success, but no banner pops, nothing lands in the Notification Center, and there
+is no error, no event-log breadcrumb — nothing. This is the platform's behavior,
+not the gem's, and it is structurally undetectable.
+
+What "registered" means — one of:
+
+- a **Start-Menu shortcut** carrying an `AppUserModelID` (what most installed
+  apps have), **or**
+- a per-user **registry key** `HKCU\Software\Classes\AppUserModelId\<aumid>`
+  with a `DisplayName` — exactly what `Wintoast.register!` writes, **or**
+- **package identity** (MSIX) — out of scope here.
+
+`SetCurrentProcessExplicitAppUserModelID` is **not** registration: it stamps the
+process AUMID for taskbar grouping / Jump Lists, and does nothing for
+notifications. (A future `winshell` concern, not this gem's.)
+
+That is why `Wintoast.toast` defaults to **Windows PowerShell's** AUMID
+(`Wintoast::POWERSHELL_AUMID`): it is registered on every Windows box via
+PowerShell's Start-Menu shortcut, so `Wintoast.toast("hi")` visibly works on a
+stock machine. The trade-offs of borrowing it:
+
+- the toast header reads **"Windows PowerShell"** (soften it with
+  `attribution:`, or switch to your own AUMID via `register!`);
+- the per-app Settings toggle is **shared** — turning off "Windows PowerShell"
+  notifications kills every tool borrowing the default. `register!` gives you a
+  private toggle.
+
+`Wintoast.toast` **never touches the registry.** Registration is an explicit,
+consented, reversible act. There is deliberately **no `registered?`** query: it
+could only check the registry route and would lie `false` for the common
+shortcut-registered case (including the default AUMID).
+
+## Toasts
+
+```ruby
+Wintoast.toast(title, body = nil,
+               aumid:       Wintoast::POWERSHELL_AUMID,
+               attribution: nil,        # small "via ..." line
+               image:       nil,        # absolute path -> appLogoOverride
+               hero:        nil,        # absolute path -> hero (364x180 @100%)
+               circle:      false,      # hint-crop="circle" on image:
+               audio:       :default,   # see table; false => silent
+               duration:    :short,     # :short | :long
+               scenario:    nil,        # nil | :alarm | :incoming_call | :urgent
+               expires_at:  nil,        # Time  -> ExpirationTime (OS caps at 3 days)
+               expires_in:  nil,        # Numeric seconds from now (mutually exclusive)
+               tag:         nil,        # String <= 64 chars (dedup/replace key)
+               group:       nil) -> nil # String <= 64 chars
+```
+
+**A normal return (`nil`) means the OS ACCEPTED the toast — NOT that it was
+displayed.** Banners can be suppressed undetectably by Focus Assist /
+Do-Not-Disturb (the toast still lands in the Notification Center), the per-app
+toggle, or the `NoToastApplicationNotification` group policy. The return value is
+`nil`, not `true`/`self`, precisely because the gem cannot honestly promise
+display.
+
+**Audio** (`audio:`) — only the system sounds Windows honors for unpackaged
+apps; arbitrary file paths silently fall back to the default sound and are not
+accepted:
+
+| value | effect |
+|---|---|
+| `:default` | OS default sound (no `<audio>` element) |
+| `false` | silent |
+| `:im` `:mail` `:reminder` `:sms` | the matching `ms-winsoundevent` sound |
+| `:alarm`, `:alarm2`..`:alarm10` | looping alarm sounds |
+| `:call`, `:call2`..`:call10` | looping call sounds |
+
+Looping sounds only *audibly* loop when the toast is pinned by
+`scenario: :alarm` / `:incoming_call` (a short alarm sound is still valid).
+
+**Scenario** (`scenario:`) — `:alarm` and `:incoming_call` pin the toast and
+loop audio; `:urgent` breaks through Do-Not-Disturb (Windows 11 build 22546+;
+older builds ignore the attribute and show a normal toast). `:reminder` is
+deliberately **not** accepted — without a button it is ignored by Windows, i.e.
+useless for fire-and-forget.
+
+**Expiration** (`expires_at:` Time / `expires_in:` seconds, mutually exclusive)
+maps to `ExpirationTime` (removal from the Notification Center). Local toasts are
+retained **at most 3 days** regardless; larger values pass through and are
+clamped by the OS. `expires_in <= 0` raises; a past `expires_at` passes through
+(the OS treats it as already expired).
+
+**Tag / group** (`tag:`, `group:`, each ≤ 64 chars) map to
+`IToastNotification2.Tag/Group`: a later toast with the same tag (+ group) under
+the same AUMID **replaces** the earlier one in the Action Center. Pure
+pass-through; there is no history/removal API in v1.
+
+**Images** (`image:`, `hero:`) are **local absolute paths only** (http(s) images
+need package identity and are rejected by the absolute-path check). A
+relative/missing path raises `ArgumentError` so a typo fails loudly instead of
+rendering an imageless toast. Paths are emitted as plain absolute paths (no
+`file://` URI), sidestepping percent-encoding of spaces and Unicode.
+
+Desktop apps **cannot schedule** toasts (`ScheduledToastNotification` needs
+package identity) — out of scope.
+
+## Progress
+
+```ruby
+Wintoast.progress(value = nil, of: 100, state: nil) -> true | false
+Wintoast.progress_clear                             -> true | false
+```
+
+Every call drives **both** progress surfaces, unconditionally — exactly one
+takes effect per host, the other no-ops (the strategy blessed in
+[microsoft/terminal#14268]):
+
+1. **OSC 9;4** written to the console — the Windows Terminal tab ring + WT-window
+   taskbar progress (also ConEmu and a growing set of terminals). Emitted **only
+   when STDOUT is a real console** (never pollutes redirected/piped output).
+2. **`ITaskbarList3`** on `GetConsoleWindow()` — classic-conhost taskbar
+   progress.
+
+| call | meaning |
+|---|---|
+| `progress(50)` / `progress(7, of: 23)` | determinate, green |
+| `progress(50, state: :error)` | determinate, red |
+| `progress(50, state: :paused)` | determinate, yellow |
+| `progress(state: :indeterminate)` | marquee / ring (value must be nil) |
+| `progress(nil)` / `progress(:clear)` / `progress_clear` | remove |
+
+Host matrix:
+
+| host | taskbar (ITaskbarList3) | tab/taskbar (OSC 9;4) |
+|---|---|---|
+| classic conhost | ✓ | swallowed |
+| Windows Terminal | accepts, invisible (hidden ConPTY window) | ✓ |
+| Windows Terminal + redirected stdout | accepts, invisible | ✗ (no OSC to a pipe) |
+| ConEmu | — | ✓ |
+| no console (rubyw / detached) | — | — → returns `false` |
+
+**The return value means accepted, not visible** — the same honesty rule as
+`toast`'s `nil`. `true` means at least one OS surface accepted the update (OSC
+bytes reached a real console, or every `ITaskbarList3` call succeeded against a
+non-NULL console window). Under a ConPTY host the taskbar leg accepts against a
+hidden window that can never render, so e.g. running under Windows Terminal with
+stdout redirected returns `true` with nothing visible. `false` is guaranteed
+only when no surface accepted at all.
+
+**Environmental failure is a `false`, never an exception** — a progress bar must
+not be able to crash the app. Only argument misuse raises `ArgumentError`
+(`of: 0`, a missing value for a determinate state, a value for `:indeterminate`,
+an unknown state, a non-Numeric value). Overshoot like `progress(101)` is
+**clamped**, not raised.
+
+**Clearing on exit is the caller's job** — put `Wintoast.progress_clear` in an
+`ensure`. v1 installs no `at_exit` hook.
+
+Two console side effects, both standard CLI behavior: progress enables
+`ENABLE_VIRTUAL_TERMINAL_PROCESSING` once when missing and leaves it on
+(per-call restore would race other writers); and under a **classic conhost in
+select mode** (the user is holding a text selection) the OSC write can block.
+The GVL is released so every *other* Ruby thread keeps running, but the parked
+write itself is **not interruptible** (`Thread#kill` / `Timeout` will not break
+it) — exact parity with `Kernel#puts`, whose console write is equally stuck.
+
+## Library API
+
+```ruby
+Wintoast.toast(title, body = nil, **opts)        # => nil  (accepted, not necessarily shown)
+Wintoast.register!(aumid:, display_name:, icon: nil) # => aumid String (HKCU branding)
+Wintoast.unregister!(aumid:)                     # => true | false (false = wasn't there)
+Wintoast.progress(value = nil, of: 100, state: nil)  # => true | false (accepted, not visible)
+Wintoast.progress_clear                          # => true | false
+Wintoast::Payload.build(title, body = nil, **opts)   # => String (debugging: the exact XML sent)
+Wintoast::VERSION                                # => "0.1.0"
+Wintoast::POWERSHELL_AUMID                        # the registered-everywhere default AUMID
+```
+
+## How it works
+
+Toasts are sent through the **inbox** WinRT API activated directly via
+`RoGetActivationFactory` — no Windows App SDK, no C++/WinRT codegen, no NuGet.
+The C++ extension assembles the `ToastGeneric` XML in Ruby, hands it to
+`Windows.Data.Xml.Dom.XmlDocument.LoadXml`, builds a `ToastNotification`, and
+calls `ToastNotifier.Show` — all synchronous, milliseconds.
+
+`register!` writes **only** `HKCU\Software\Classes\AppUserModelId\<aumid>`
+(`DisplayName`, optional `IconUri`) — per-user, no elevation, no Start-Menu
+shortcut, no HKLM, no COM activator. `unregister!` deletes that key tree.
+
+Progress drives both `ITaskbarList3` and OSC 9;4 every call.
+
+Every native operation is **stateless and complete within one call** — WinRT/COM
+is initialized and uninitialized per call, owning no resources across calls. That
+makes every API **idempotent and thread-safe**: call them from any thread,
+concurrently, with no locks.
+
+## Errors
+
+```
+StandardError
+└─ Wintoast::Error      misuse / non-OS failures (e.g. invalid UTF-8)
+   └─ Wintoast::OSError OS API failures; #code => Integer
+                        (HRESULT for COM/WinRT, Win32 code for registry)
+```
+
+Plain argument-shape problems raise Ruby's own `ArgumentError` / `TypeError`.
+
+These are **not** errors (by design — the platform cannot report them):
+
+- a toast sent to an unregistered AUMID is silently dropped;
+- Focus Assist / Do-Not-Disturb suppresses the banner (the toast still reaches
+  the Notification Center);
+- a per-app or policy toggle disables toasts;
+- `progress` returns `false` when no console surface accepted.
+
+## License
+
+[MIT](LICENSE.txt).
+
+[BurntToast]: https://github.com/Windos/BurntToast
+[Windows App SDK]: https://learn.microsoft.com/windows/apps/windows-app-sdk/
+[mohabouje/WinToast]: https://github.com/mohabouje/WinToast
+[microsoft/terminal#14268]: https://github.com/microsoft/terminal/discussions/14268

data/ext/wintoast/extconf.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+#
+# extconf.rb for the wintoast C++ extension (WinRT toasts + ITaskbarList3 +
+# OSC 9;4 progress + HKCU AppUserModelId registration).
+#
+# wintoast is Windows-MSVC-only: it activates the inbox WinRT notification API
+# via RoGetActivationFactory, drives COM (ITaskbarList3), and writes the registry
+# — all with cl.exe. mkmf auto-discovers the .cpp source and compiles it as C++
+# (its CXX_EXT list includes "cpp"). The guard is arch-neutral (/mswin/ only), so
+# it passes unchanged on a future arm64-mswin Ruby (target_os stays "mswin64").
+
+require "mkmf"
+
+unless RbConfig::CONFIG["target_os"] =~ /mswin/
+  abort <<~MSG
+    wintoast requires a native Windows MSVC (mswin) Ruby — it binds the inbox
+    WinRT toast notification API (RoGetActivationFactory), ITaskbarList3, the
+    console VT/OSC path, and the registry, and is built with cl.exe. Your Ruby
+    is "#{RbConfig::CONFIG['arch']}". On a MinGW/UCRT Ruby this gem is not supported.
+  MSG
+end
+
+# C++ (WinRT ABI interfaces, std::wstring, COM patterns); enable exceptions.
+$CXXFLAGS << " -EHsc"
+
+# System import libs (bare "NAME.lib" tokens on mswin; no -l prefix):
+#   runtimeobject - WinRT (RoInitialize / RoGetActivationFactory /
+#                   WindowsCreateStringReference / WindowsCreateString)
+#   ole32         - COM (CoInitializeEx / CoCreateInstance for ITaskbarList3)
+#   uuid          - CLSID_TaskbarList / interface IIDs
+#   advapi32      - registry (RegCreateKeyExW / RegSetValueExW / RegDeleteTreeW)
+# kernel32 (console APIs, GetConsoleWindow) is linked by default and not listed.
+$libs = [$libs, "runtimeobject.lib", "ole32.lib", "uuid.lib", "advapi32.lib"].join(" ")
+
+# Produces lib/wintoast/wintoast.so, required as "wintoast/wintoast".
+create_makefile("wintoast/wintoast")