@gjsify/gtk-runtime-win32-arm64 0.0.0-stage → 0.64.6

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 gjsify contributors
+
+This license covers the SOURCE of this package (index.js, index.d.ts) and the
+build script in the gjsify repository that assembles the bundle. It does NOT
+cover the third-party GTK / GObject-Introspection binaries under `gtk/`: those
+keep the terms of their own projects, reproduced in
+`gtk/THIRD-PARTY-NOTICES.md` and `gtk/licenses/` inside the published tarball.
+
+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.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @gjsify/gtk-runtime-win32-arm64
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Batteries-included GTK / GObject-Introspection runtime bundle for **Windows arm64**.
+It lets [`@gjsify/node-gi`](../node-gi) load `gi://` namespaces (GLib · GObject ·
+Gio · cairo · Pango · Graphene · Gdk) with **no gvsbuild / system GTK** installed on
+the host — the arm64 sibling of [`@gjsify/gtk-runtime-win32-x64`](../gtk-runtime-win32-x64).
+
+Platform-gated (`os: ["win32"]`, `cpu: ["arm64"]`), tier 3 (experimental). On any
+other platform npm skips it and `@gjsify/node-gi` falls back to a system/gvsbuild
+GTK. The heavy `gtk/` payload is **not committed** — it is built on a
+`windows-11-arm` CI runner and shipped via the package tarball / staged into
+node-gi's `prebuilds/win32-arm64/gtk/`.
+
+## Where the arm64 prefix comes from — there is no upstream ZIP
+
+`wingtk/gvsbuild` hardcodes `self.platform = "x64"` and publishes only an x64
+release ZIP, so unlike the x64 sibling there is nothing to download here. The
+prefix is **built from source** in CI by our MSVC fork, `gjsify/gvsbuild`
+(`.github/actions/gvsbuild-arm64-prefix`, pinned by commit SHA and cached), the
+whole route recorded in
+[ADR 0089](../../../docs/adr/0089-win32-arm64-gtk-is-built-from-source-by-our-msvc-gvsbuild-fork.md).
+MSVC end to end, never MSYS2/`CLANGARM64`, so the x64 addon recipe
+(`binding.gyp`, `win-gi-gyp-flags.mjs`) and this package's builder transfer
+unchanged — only the `--prefix` path and the toolset (`vcvarsarm64`) differ.
+Exit: when upstream gvsbuild ships an arm64 target, this switches to the
+version pin and the fork is retired.
+
+**Still out of scope on arm64 today** (ADR 0089, `status/open-todos/windows.md`
+§ win32-arm64): the two-pass gst-plugins-good build for `gstsoup.dll` /
+`souphttpsrc` (an arm64 bundle therefore has no http(s) media source yet), plus
+webgl (`gwebgl.dll`), gamepad and WebView2 — none of those are built against
+the arm64 prefix yet.
+
+## The builder is shared with the x64 sibling
+
+`packages/node-gi/scripts/build-gtk-runtime-win32.mjs` serves both win32
+targets — the DLL closure walk (`dumpbin`), the typelib set, the `--windowing`
+superset and the license corpus are arch-agnostic; the only arch-dependent
+inputs are `--prefix` (the gvsbuild zip extraction on x64, the fork-built
+prefix at `C:\gtk-build\gtk\ARM64\release` on arm64) and the MSVC toolset
+(`vcvarsarm64.bat`). See that script and
+[`@gjsify/gtk-runtime-win32-x64`'s README](../gtk-runtime-win32-x64/README.md)
+for the full build/layout/loader documentation — it applies here unchanged,
+down to the DLL layout (`gtk/bin`, not `gtk/lib`), the `--windowing` superset,
+the typelib-API floor and the license-coverage gate. Built on the Windows-on-ARM
+runner:
+
+```
+node ..\scripts\build-gtk-runtime-win32.mjs --windowing --prefix C:\gtk-build\gtk\ARM64\release --out gtk ^
+  --addon <node_gi.node built for arm64>
+```
+
+## How node-gi finds + activates it
+
+Identical to the x64 sibling: node-gi's loader (`gtk-runtime.js`) resolves
+`@gjsify/gtk-runtime-win32-arm64` by name (and the usual override/dev-sibling
+candidates), prepends `gtk/bin` to `PATH` before the addon loads, and prepends
+`gtk/girepository-1.0` to the GIRepository search path — no relocation, no
+re-exec, the same mechanism the x64 README documents in full.

package/index.d.ts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+/** Absolute path to the bundle root (contains `bin/` + `girepository-1.0/`). */
+export const bundleDir: string;
+/** Absolute path to the bundled DLL dir (prepend to PATH so LoadLibrary finds it). */
+export const binDir: string;
+/** Absolute path to the typelib dir (feed to GIRepository.prepend_search_path). */
+export const typelibDir: string;
+/** Whether the bundle payload is actually present on disk (it is built on CI). */
+export const isPresent: boolean;
+declare const _default: { bundleDir: string; binDir: string; typelibDir: string; isPresent: boolean };
+export default _default;

package/index.js

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/gtk-runtime-win32-arm64 — path helpers for the bundled GTK runtime. @gjsify/node-gi
+// resolves this package (optional, os/cpu-gated) to find the bundled typelib + DLL dirs when no
+// gvsbuild/system GTK is present. Unlike macOS, Windows needs NO relocation: DLLs resolve by
+// SEARCH PATH at LoadLibrary time, so node-gi just prepends `gtk/bin` to PATH before the addon
+// loads. The heavy `gtk/` payload is produced by ../scripts/build-gtk-runtime-win32.mjs on a
+// Windows-on-ARM runner, against the arm64 prefix our `gjsify/gvsbuild` fork builds (ADR 0089).
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the bundle root (contains `bin/` + `girepository-1.0/`). */
+export const bundleDir = join(here, 'gtk');
+
+/** Absolute path to the bundled DLL dir (prepend to PATH so LoadLibrary finds it). */
+export const binDir = join(bundleDir, 'bin');
+
+/** Absolute path to the typelib dir (feed to GIRepository.prepend_search_path). */
+export const typelibDir = join(bundleDir, 'girepository-1.0');
+
+/** Whether the bundle payload is actually present on disk (it is built on CI). */
+export const isPresent = existsSync(typelibDir) && existsSync(binDir);
+
+export default { bundleDir, binDir, typelibDir, isPresent };

package/package.json

@@ -1,6 +1,122 @@
 {
   "name": "@gjsify/gtk-runtime-win32-arm64",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.64.6",
+  "description": "Batteries-included GTK/GObject-Introspection runtime bundle for Windows arm64 — lets @gjsify/node-gi load gi:// namespaces (GLib/GObject/Gio/cairo/Pango/Graphene/Gdk) with NO gvsbuild/system GTK. Platform-gated (win32/arm64 only). GTK is built from source by our MSVC gjsify/gvsbuild fork (ADR 0089) — upstream gvsbuild publishes no arm64 ZIP.",
+  "type": "module",
+  "license": "SEE LICENSE IN gtk/THIRD-PARTY-NOTICES.md",
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./gtk/girepository-1.0": "./gtk/girepository-1.0",
+    "./gtk/bin": "./gtk/bin"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "gtk"
+  ],
+  "gjsify": {
+    "runtimes": {
+      "gjs": "none",
+      "node": "polyfill",
+      "browser": "none",
+      "nativescript": "none"
+    },
+    "tier": 3,
+    "mediaCapabilities": {
+      "gstPluginDir": "gtk/lib/gstreamer-1.0",
+      "audioDecode": [
+        {
+          "format": "WAV / PCM",
+          "plugin": "wavparse",
+          "element": "wavparse"
+        },
+        {
+          "format": "MP3",
+          "plugin": "mediafoundation",
+          "element": "mfmp3dec"
+        },
+        {
+          "format": "AAC (M4A)",
+          "plugin": "mediafoundation",
+          "element": "mfaacdec"
+        },
+        {
+          "format": "Ogg / Vorbis",
+          "plugin": "vorbis",
+          "element": "vorbisdec",
+          "upstream": {
+            "catalogue": "gvsbuild",
+            "library": "libvorbis"
+          }
+        },
+        {
+          "format": "Opus",
+          "plugin": "opus",
+          "element": "opusdec",
+          "upstream": {
+            "catalogue": "gvsbuild",
+            "library": "opus"
+          }
+        },
+        {
+          "format": "A-law",
+          "plugin": "alaw",
+          "element": "alawdec"
+        },
+        {
+          "format": "µ-law",
+          "plugin": "mulaw",
+          "element": "mulawdec"
+        }
+      ],
+      "gaps": [
+        {
+          "plugin": "mpg123",
+          "element": "mpg123audiodec",
+          "upstream": {
+            "catalogue": "gvsbuild",
+            "library": "mpg123"
+          },
+          "why": "MP3 is DECODED on this target, by `mfmp3dec` out of the `mediafoundation` plugin (gst-plugins-bad), which wraps the MP3 decoder Windows itself ships — see the `MP3` claim. This entry is the OTHER decoder, the one the darwin bundles use: gst-plugins-good's `mpg123` links libmpg123, and the gvsbuild version this bundle is built from defines no project for that library, so the element cannot be built here. It stays declared, with `upstream`, so the day gvsbuild gains the project this bundle can ship the same decoder as darwin and stop depending on the OS component. What the OS route costs, stated because it is not nothing: Media Foundation is absent from Windows N editions until the Media Feature Pack is installed, and is the optional Server-Media-Foundation feature on Windows Server — where mfplat.dll is missing the plugin does not load and MP3 is the gap it was before (ADR 0056 § 7)."
+        },
+        {
+          "format": "FLAC",
+          "plugin": "flac",
+          "element": "flacdec",
+          "upstream": {
+            "catalogue": "gvsbuild",
+            "library": "flac"
+          },
+          "why": "the gst-plugins-good element links libFLAC and gvsbuild defines no project for that library either — the same absence as MP3, read off the same project list, and neither is a licensing decision: libmpg123 is LGPL-2.1 and libFLAC is BSD-3-Clause. Unlike MP3 this one has a route out of the pinned catalogue and is therefore a COSTED decision rather than an absence: gvsbuild builds gst-plugins-rs under the project name `gst-plugin-gtk4`, and that tree's `claxon` feature is a pure-Rust FLAC decoder (`claxondec`, MPL-2.0). It is not taken — ADR 0056 § Alternatives rejected carries the price. A libFLAC project in gvsbuild closes it in one word instead."
+        },
+        {
+          "plugin": "wasapi2",
+          "why": "the modern Windows sink, and the one absence here that costs no format: `directsound` ships and `autoaudiosink` resolves to it. Declared because it is the same silent absence, not because anything breaks."
+        },
+        {
+          "format": "AAC (ADTS)",
+          "why": "the same `mfaacdec` that decodes the M4A shape (see the `AAC (M4A)` claim) does not decode a bare ADTS stream through `decodebin3` on the x64 bundle (measured on CI); the same gvsbuild-built GStreamer closure backs this arch, so the gap is assumed shared until measured separately on arm64."
+        }
+      ]
+    }
+  },
+  "scripts": {
+    "build:bundle": "node ../scripts/build-gtk-runtime-win32.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gjsify/gjsify.git",
+    "directory": "packages/node-gi/gtk-runtime-win32-arm64"
+  }
+}