wintoast 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a5ffc4e1ef7ddebe12e6096aa293b1d70f96a8bb8c7fdba4e6c807dc80578f6
-  data.tar.gz: d7d1357b903a3582b4e51b5616a83e13f4a1c0dbbc94c273c9bf3d8234c1daef
+  metadata.gz: 779c2f38a8971d52dcd72fd4790bb390349e7e75bc121360d969cdef2726a7a7
+  data.tar.gz: 6bec442db8cfd2cf320198afe50feffb524d167382c96e08d4af87c94f9be467
 SHA512:
-  metadata.gz: 1f0271faa0e9e3ee302a7e54d74eff648c75538432ae821b58fc338b2eb25c5da1f0cff9e034da31ad94ad44c515967975b05d420ee9784e1cdd7f106c90e14c
-  data.tar.gz: 48714a218686fdfb01849299231162881f70302e8ae9278ce1dc3f6858ab8505da5a88fdcc87aa4acff32ab287effe9844d0f1234f5c5ff32411ad1282adfa91
+  metadata.gz: c2530fb41929d590ffdc3fd35e478c20f04ed27ce2cd96ca20bebbe698bcc25d26c95e3871055c1eb460f0f3a1b403b2c5f423d4052e0d7f1bef281c66a6727c
+  data.tar.gz: a9eecb5b2b46e459c8c83ac460fc6289d2749d032b95c281a8d8bd94569b0c9c0df96b4e10c8cc72b65ed8b1aa0709c1dc32e77d6402cca77e21d78de2c0be33

data/README.md

@@ -1,335 +1,11 @@
-# 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
+# wintoast (discontinued)
+
+**wintoast is no longer maintained.** This final release (0.1.1) contains no
+code: installing it compiles nothing, and `require "wintoast"` raises a
+`LoadError` explaining the discontinuation.
+
+Use win_toaster instead.
+
+Earlier releases remain on RubyGems only because RubyGems does not allow
+versions older than 30 days to be yanked. They are unmaintained and not
+recommended.

data/lib/wintoast.rb

@@ -1,270 +1,4 @@
-# frozen_string_literal: true
-
-require "wintoast/version"
-require "wintoast/wintoast"  # native ext: defines _show/_register/_unregister/_progress + errors
-require "wintoast/payload"
-
-# wintoast — fire-and-forget Windows toast notifications and taskbar/terminal
-# progress, built on the inbox WinRT and shell APIs that already ship with
-# Windows. No Windows App SDK, no packaging, no COM activation server, no
-# elevation, nothing to install but the gem.
-#
-#   require "wintoast"
-#
-#   Wintoast.toast("Backup finished", "1,204 files in 38 s")   # => nil (a banner pops)
-#   Wintoast.progress(50)                                       # => true/false
-#   Wintoast.progress_clear                                     # => true/false
-#
-# A normal return from #toast means the OS ACCEPTED the toast — NOT that it was
-# displayed. Silent suppression (unregistered AUMID, Focus Assist, per-app
-# toggle, group policy) is undetectable by design of the platform; the gem never
-# pretends otherwise. See the README "The one trap you must know about".
-module Wintoast
-  # Misuse / non-OS failures (e.g. invalid UTF-8). OS API failures are OSError.
-  class Error < StandardError; end
-
-  # OS API failure. #code is an Integer: the HRESULT for COM/WinRT, or the Win32
-  # error code for registry calls. Attached in C via rb_iv_set(exc, "@code", ...).
-  class OSError < Error
-    def code = @code
-  end
-
-  # The AUMID of Windows PowerShell's Start-Menu shortcut — registered on every
-  # supported Windows box, so toasts sent with it always render (branded
-  # "Windows PowerShell"). The zero-setup default for Wintoast.toast.
-  POWERSHELL_AUMID = "{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe"
-
-  module_function
-
-  # Fire-and-forget toast notification. Returns nil, always — a normal return
-  # means the OS accepted the toast, not that it was displayed (silent drops are
-  # undetectable). See §2.2 of the spec / the README for every kwarg.
-  #
-  # Raises ArgumentError / TypeError on bad arguments, Wintoast::Error on invalid
-  # UTF-8, and Wintoast::OSError (with #code = HRESULT) on a WinRT API failure.
-  def toast(title, body = nil,
-            aumid:       POWERSHELL_AUMID,
-            attribution: nil,
-            image:       nil,
-            hero:        nil,
-            circle:      false,
-            audio:       :default,
-            duration:    :short,
-            scenario:    nil,
-            expires_at:  nil,
-            expires_in:  nil,
-            tag:         nil,
-            group:       nil)
-    # Build the XML first: it validates title/body/attribution/image/hero/
-    # circle/audio/duration/scenario and normalizes + UTF-8-checks every text
-    # field, all in pure Ruby BEFORE any C bridge runs (the §3.5 regime).
-    xml = Payload.build(title, body,
-                        attribution: attribution, image: image, hero: hero,
-                        circle: circle, audio: audio, duration: duration,
-                        scenario: scenario)
-
-    aumid_u8 = validate_aumid_arg(aumid)
-    expire_ms = validate_expiry(expires_at, expires_in)
-    tag_u8   = validate_label(tag,   "tag")
-    group_u8 = validate_label(group, "group")
-
-    _show(aumid_u8, xml, expire_ms, tag_u8, group_u8)
-    nil
-  end
-
-  # Opt-in, reversible, per-user branding: writes ONLY
-  # HKCU\Software\Classes\AppUserModelId\<aumid> {DisplayName, IconUri?}.
-  # No elevation, no Start-Menu shortcut, no HKLM, no COM activator. Returns the
-  # aumid String. Raises ArgumentError on format violations, Wintoast::OSError
-  # (#code = Win32 error) on registry failures.
-  def register!(aumid:, display_name:, icon: nil)
-    aumid_u8 = validate_registry_aumid(aumid)
-
-    dn = String.try_convert(display_name)
-    raise TypeError, "wintoast: display_name: must be a String" if dn.nil?
-
-    dn = normalize_text(dn, "display_name")
-    raise ArgumentError, "wintoast: display_name: must be non-empty" if dn.empty?
-
-    icon_u8 =
-      if icon.nil?
-        nil
-      else
-        ic = normalize_text(icon, "icon")
-        unless File.absolute_path?(ic) && File.file?(ic)
-          raise ArgumentError, "wintoast: icon: must be an absolute path to an existing file"
-        end
-        ic
-      end
-
-    _register(aumid_u8, dn, icon_u8)
-    aumid_u8
-  end
-
-  # Delete the HKCU AppUserModelId key tree for the given aumid. Idempotent:
-  # returns false (no raise) when the key was not present. Only unregister AUMIDs
-  # YOU registered — deleting another app's HKCU key breaks its toasts.
-  def unregister!(aumid:)
-    _unregister(validate_registry_aumid(aumid))
-  end
-
-  # Drive taskbar + terminal progress. Returns true if at least one OS surface
-  # accepted the update, false if none did (no console at all, or a console whose
-  # taskbar leg also failed). Accepted != visible. Environmental failure is a
-  # false, never an exception — only argument misuse raises ArgumentError.
-  #
-  #   progress(50)                       determinate, green
-  #   progress(7, of: 23)                determinate from a ratio
-  #   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)   remove
-  def progress(value = nil, of: 100, state: nil)
-    unless of.is_a?(Numeric) && of.positive?
-      raise ArgumentError, "wintoast: of: must be a positive number, got #{of.inspect}"
-    end
-
-    # :indeterminate is value-less (the marquee ignores any percent). value must
-    # be nil; a supplied value (Numeric or :clear) is misuse. Checked first so
-    # progress(state: :indeterminate) is NOT mistaken for a clear.
-    if state == :indeterminate
-      unless value.nil?
-        raise ArgumentError, "wintoast: state: :indeterminate ignores value — pass value nil"
-      end
-      return _progress(3, 0)
-    end
-
-    # Clearing: value nil or :clear, and (because clear has no color) no state:.
-    if value.nil? || value == :clear
-      unless state.nil?
-        raise ArgumentError, "wintoast: clearing progress takes no state:, got #{state.inspect}"
-      end
-      return _progress(0, 0)
-    end
-
-    # Determinate: requires a Numeric value.
-    unless value.is_a?(Numeric)
-      raise ArgumentError, "wintoast: progress value must be a number, got #{value.inspect}"
-    end
-    state_int =
-      case state
-      when nil, :normal then 1
-      when :error       then 2
-      when :paused      then 4
-      else
-        raise ArgumentError, "wintoast: unknown state: #{state.inspect}"
-      end
-
-    _progress(state_int, pct(value, of))
-  end
-
-  # Remove progress. Equivalent to progress(nil).
-  def progress_clear = _progress(0, 0)
-
-  # ---- validation helpers (private) ----------------------------------------
-
-  # Normalize any String to UTF-8 and reject invalid UTF-8 in pure Ruby (§3.5).
-  def normalize_text(value, label)
-    str = String.try_convert(value)
-    raise TypeError, "wintoast: #{label} must be a String, got #{value.class}" if str.nil?
-
-    str = str.encode(Encoding::UTF_8) unless str.encoding == Encoding::UTF_8
-    unless str.valid_encoding?
-      raise Wintoast::Error, "wintoast: invalid UTF-8 in #{label}"
-    end
-    str
-  rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
-    raise Wintoast::Error, "wintoast: invalid UTF-8 in #{label}"
-  end
-
-  # aumid: for toast() — must be a non-empty String (StringValue semantics).
-  def validate_aumid_arg(aumid)
-    str = String.try_convert(aumid)
-    raise TypeError, "wintoast: aumid: must be a String, got #{aumid.class}" if str.nil?
-
-    str = normalize_text(str, "aumid")
-    raise ArgumentError, "wintoast: aumid: must not be empty" if str.empty?
-    str
-  end
-
-  # aumid: for register!/unregister! — the documented AUMID format: 1..128
-  # chars, no spaces, no control chars/NUL. Backslashes allowed (nested keys).
-  def validate_registry_aumid(aumid)
-    str = String.try_convert(aumid)
-    raise TypeError, "wintoast: aumid: must be a String, got #{aumid.class}" if str.nil?
-
-    str = normalize_text(str, "aumid")
-    if str.empty? || str.length > 128
-      raise ArgumentError, "wintoast: aumid: must be 1..128 characters, got #{str.length}"
-    end
-    if str.include?(" ")
-      raise ArgumentError, "wintoast: aumid: must not contain spaces"
-    end
-    if str.match?(/[\x00-\x1f]/)
-      raise ArgumentError, "wintoast: aumid: must not contain control characters"
-    end
-    str
-  end
-
-  # tag:/group: -> nil or a 1..64-char String. Empty or > 64 raises.
-  def validate_label(value, label)
-    return nil if value.nil?
-
-    str = String.try_convert(value)
-    raise TypeError, "wintoast: #{label}: must be a String, got #{value.class}" if str.nil?
-
-    str = normalize_text(str, label)
-    if str.empty? || str.length > 64
-      raise ArgumentError, "wintoast: #{label}: must be 1..64 characters, got #{str.length}"
-    end
-    str
-  end
-
-  # The epoch-ms whose WinRT DateTime tick — (ms + 11644473600000) * 10000, in
-  # 100-ns units since 1601 — still fits a signed int64. The C bridge performs
-  # exactly that multiply (wintoast.cpp), so any ms past this point would overflow
-  # int64 (undefined behavior) and hand the OS a garbage UniversalTime. The OS
-  # caps toast retention at 3 days anyway, so a far-future expiry is already
-  # meaningless; clamping here is observably correct and removes the UB window.
-  MAX_EXPIRE_MS = (2**63 - 1) / 10_000 - 11_644_473_600_000
-  private_constant :MAX_EXPIRE_MS
-
-  # expires_at:/expires_in: -> the absolute Unix epoch milliseconds, or nil.
-  # Mutually exclusive. expires_in must be a positive Numeric (seconds from now);
-  # expires_at must be a Time (past times pass through — the OS treats them as
-  # already expired; clocks skew, so we don't police it). The result is clamped
-  # to MAX_EXPIRE_MS so the C-side tick multiply can never overflow int64.
-  def validate_expiry(expires_at, expires_in)
-    if expires_at && expires_in
-      raise ArgumentError, "wintoast: pass only one of expires_at:/expires_in:"
-    end
-
-    if expires_in
-      unless expires_in.is_a?(Numeric) && expires_in.positive?
-        raise ArgumentError, "wintoast: expires_in: must be a positive number of seconds"
-      end
-      ms = ((Time.now.to_f + expires_in.to_f) * 1000.0).round
-      return ms.clamp(0, MAX_EXPIRE_MS)
-    end
-
-    if expires_at
-      unless expires_at.is_a?(Time)
-        raise ArgumentError, "wintoast: expires_at: must be a Time, got #{expires_at.class}"
-      end
-      ms = (expires_at.to_f * 1000.0).round
-      return ms.clamp(0, MAX_EXPIRE_MS)
-    end
-
-    nil
-  end
-
-  # Percent = round(value/of * 100), clamped 0..100. Overshoot is a routine
-  # rounding artifact in app loops, so it is clamped, not raised.
-  def pct(value, of)
-    ((value.to_f / of.to_f) * 100.0).round.clamp(0, 100)
-  end
-
-  private_class_method :_show, :_register, :_unregister, :_progress
-  private_class_method :normalize_text, :validate_aumid_arg, :validate_registry_aumid,
-                       :validate_label, :validate_expiry, :pct
-end
+# frozen_string_literal: true
+
+raise LoadError, "wintoast is discontinued and this release contains no code. Use win_toaster instead." \
+  " Earlier wintoast releases are unmaintained and not recommended."