native-dawn 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "native-dawn",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Prebuilt Dawn WebGPU for Node.js and native code: shared library, C headers, and Node-API bindings",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./paths": {
+      "types": "./paths.d.ts",
+      "import": "./paths.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "native-dawn": "bin/native-dawn.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "paths.js",
+    "paths.d.ts",
+    "bin",
+    "include",
+    "src",
+    "scripts/*.mjs",
+    "scripts/*.py",
+    "CMakeLists.txt",
+    "upstream.json",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "install": "node scripts/install.mjs",
+    "build": "node scripts/build.mjs",
+    "test": "node scripts/test.mjs",
+    "test:c": "node scripts/test-c.mjs",
+    "test:window": "node test/window.mjs",
+    "test:package": "node scripts/test-package.mjs",
+    "package:binary": "node scripts/package-binary.mjs",
+    "test:types": "tsc -p test/tsconfig.json",
+    "test:android": "node scripts/test-android.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monteslu/native-dawn.git"
+  },
+  "author": "Luis Montes",
+  "license": "MIT",
+  "keywords": [
+    "webgpu",
+    "dawn",
+    "wgsl",
+    "gpu",
+    "native",
+    "vulkan",
+    "metal",
+    "d3d12"
+  ],
+  "dependencies": {
+    "@webgpu/types": "0.1.72",
+    "tar": "7.5.22"
+  },
+  "devDependencies": {
+    "@kmamal/sdl": "0.11.13",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/paths.d.ts

@@ -0,0 +1,18 @@
+export interface NativeDawnPaths {
+  /** `${process.platform}-${process.arch}` */
+  readonly target: string
+  /** Install prefix: pass it as CMAKE_PREFIX_PATH to find_package(Dawn). */
+  readonly prefix: string
+  readonly include: string
+  readonly lib: string
+  readonly bin: string
+  readonly cmake: string
+  /** The shared library: libwebgpu_dawn.so, libwebgpu_dawn.dylib or webgpu_dawn.dll. */
+  readonly library: string
+  readonly addon: string
+  /** Dawn's machine-readable description of the WebGPU API. */
+  readonly dawnJson: string
+  readonly licenses: string
+}
+export declare const paths: NativeDawnPaths
+export default paths

package/paths.js

@@ -0,0 +1,22 @@
+// Locations inside the installed native build. Importing this module does not
+// load the Node addon, so build scripts for C and C++ code can use it.
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const target = `${process.platform}-${process.arch}`
+const prefix = fileURLToPath(new URL(`./dist/${target}/`, import.meta.url))
+const binaries = path.join(prefix, process.platform === 'win32' ? 'bin' : 'lib')
+
+export const paths = Object.freeze({
+  target,
+  prefix,
+  include: path.join(prefix, 'include'),
+  lib: path.join(prefix, 'lib'),
+  bin: path.join(prefix, 'bin'),
+  cmake: path.join(prefix, 'lib', 'cmake'),
+  library: path.join(binaries, { win32: 'webgpu_dawn.dll', darwin: 'libwebgpu_dawn.dylib' }[process.platform] ?? 'libwebgpu_dawn.so'),
+  addon: path.join(binaries, 'dawn.node'),
+  dawnJson: path.join(prefix, 'share', 'native-dawn', 'dawn.json'),
+  licenses: path.join(prefix, 'share', 'native-dawn', 'licenses'),
+})
+export default paths

package/scripts/build.mjs

@@ -0,0 +1,187 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { spawnSync } from 'node:child_process'
+import { root, run, upstream, target, targets, pkg, distDir, binDir, assertTarget, isAndroid, hasAddon, insertText } from './common.mjs'
+
+assertTarget()
+const dawn = path.join(root, '.cache/dawn')
+
+// The NDK: ANDROID_NDK_HOME or ANDROID_NDK_ROOT, else the newest under the SDK.
+function androidNdk() {
+  for (const name of ['ANDROID_NDK_HOME', 'ANDROID_NDK_ROOT', 'ANDROID_NDK_LATEST_HOME']) {
+    if (process.env[name] && fs.existsSync(process.env[name])) return process.env[name]
+  }
+  const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT
+  const dir = sdk && path.join(sdk, 'ndk')
+  const versions = dir && fs.existsSync(dir) ? fs.readdirSync(dir).sort((a, b) => a.localeCompare(b, undefined, { numeric: true })) : []
+  if (!versions.length) throw new Error('Android builds need the NDK: set ANDROID_NDK_HOME')
+  return path.join(dir, versions.at(-1))
+}
+
+// A Go toolchain unpacked into .cache/go is used when none is on PATH.
+const env = { ...process.env }
+const localGo = path.join(root, '.cache/go/bin')
+if (fs.existsSync(localGo)) env.PATH = `${localGo}${path.delimiter}${env.PATH}`
+
+fs.mkdirSync(dawn, { recursive: true })
+if (!fs.existsSync(path.join(dawn, '.git'))) run('git', ['init', '-q'], { cwd: dawn })
+const rev = spawnSync('git', ['rev-parse', '--verify', 'HEAD'], { cwd: dawn, encoding: 'utf8' }).stdout?.trim()
+if (rev !== upstream.dawn.revision) {
+  run('git', ['fetch', '--depth', '1', upstream.dawn.url, upstream.dawn.revision], { cwd: dawn })
+  run('git', ['checkout', '--detach', upstream.dawn.revision], { cwd: dawn })
+}
+run(process.platform === 'win32' ? 'python' : 'python3', [path.join(root, 'scripts/fetch-dependencies.py'), dawn])
+
+// Small, checked hooks into Dawn's Node bindings. Everything else lives in src/node.
+function insert(relative, needle, replacement) {
+  const file = path.join(dawn, relative)
+  const text = fs.readFileSync(file, 'utf8')
+  const patched = insertText(text, needle, replacement)
+  if (patched === null) throw new Error(`Dawn changed around a native-dawn hook in ${relative}; update scripts/build.mjs`)
+  if (patched !== text) fs.writeFileSync(file, patched)
+}
+
+insert('src/dawn/node/Module.cpp', '#include "dawn/dawn_proc.h"', '#include "dawn/dawn_proc.h"\n#include "extensions.h"')
+// The addon calls webgpu_dawn's exported functions directly, so Dawn's proc
+// table (and the dawn_proc library behind it) is not used.
+insert('src/dawn/node/Module.cpp', '    dawnProcSetProcs(&dawn::native::GetProcs());', '    // native-dawn: wgpu* calls go straight to the shared webgpu_dawn library.')
+insert('src/dawn/node/Module.cpp', '    return exports;', '    native_dawn::Initialize(env, exports);\n    return exports;')
+insert('src/dawn/node/binding/GPUDevice.h', '    ~GPUDevice() override;', '    ~GPUDevice() override;\n    wgpu::Device GetNativeDawnDevice() const { return device_; }')
+// Lifetime fixes for Dawn's Node bindings.
+//
+// The polling runner shares the instance with GPU. Upstream it holds a raw
+// pointer, while adapters, devices, buffers and queues keep the runner alive,
+// so once the JavaScript GPU object is collected the next poll reads a freed
+// instance and the process dies.
+insert('src/dawn/node/binding/AsyncRunner.h', '    static std::shared_ptr<AsyncRunner> Create(dawn::native::Instance* instance);', '    static std::shared_ptr<AsyncRunner> Create(std::shared_ptr<dawn::native::Instance> instance);')
+insert('src/dawn/node/binding/AsyncRunner.h', '    explicit AsyncRunner(dawn::native::Instance* instance);', '    explicit AsyncRunner(std::shared_ptr<dawn::native::Instance> instance);')
+insert('src/dawn/node/binding/AsyncRunner.h', '    const dawn::native::Instance* const instance_;', '    // native-dawn: shared with GPU, so a poll never outlives the instance.\n    const std::shared_ptr<dawn::native::Instance> instance_;')
+insert('src/dawn/node/binding/AsyncRunner.cpp', 'std::shared_ptr<AsyncRunner> AsyncRunner::Create(dawn::native::Instance* instance) {\n    auto runner = std::make_shared<AsyncRunner>(instance);', 'std::shared_ptr<AsyncRunner> AsyncRunner::Create(std::shared_ptr<dawn::native::Instance> instance) {\n    auto runner = std::make_shared<AsyncRunner>(std::move(instance));')
+insert('src/dawn/node/binding/AsyncRunner.cpp', 'AsyncRunner::AsyncRunner(dawn::native::Instance* instance) : instance_(instance) {}', 'AsyncRunner::AsyncRunner(std::shared_ptr<dawn::native::Instance> instance)\n    : instance_(std::move(instance)) {}')
+insert('src/dawn/node/binding/GPU.h', '    std::unique_ptr<dawn::native::Instance> instance_;', '    std::shared_ptr<dawn::native::Instance> instance_;')
+insert('src/dawn/node/binding/GPU.cpp', '    instance_ = std::make_unique<dawn::native::Instance>(', '    instance_ = std::make_shared<dawn::native::Instance>(')
+insert('src/dawn/node/binding/GPU.cpp', '    async_ = AsyncRunner::Create(instance_.get());', '    async_ = AsyncRunner::Create(instance_);')
+// A live device is not pending work. Upstream counts the device.lost promise
+// as a pending task, so every device keeps setImmediate polling for as long
+// as it exists: a full CPU core while idle, and Node never exits on its own.
+insert('src/dawn/node/binding/AsyncRunner.h', '    inline ~AsyncContext() { runner_->End(); }', '    inline ~AsyncContext() {\n        if (!detached_) {\n            runner_->End();\n        }\n    }\n\n    // native-dawn: stop counting this context as pending work. For promises\n    // that may never settle (device.lost), so they do not keep the event\n    // loop polling for the life of the object.\n    inline void Detach() {\n        if (!detached_) {\n            detached_ = true;\n            runner_->End();\n        }\n    }')
+insert('src/dawn/node/binding/AsyncRunner.h', '    std::shared_ptr<AsyncRunner> runner_;\n};', '    std::shared_ptr<AsyncRunner> runner_;\n    bool detached_ = false;\n};')
+insert('src/dawn/node/binding/GPUAdapter.cpp', '    auto device_lost_ctx = new DeviceLostContext(env, PROMISE_INFO, async_);', '    auto device_lost_ctx = new DeviceLostContext(env, PROMISE_INFO, async_);\n    device_lost_ctx->Detach();')
+// With no standing poll, destroy() asks for one so the device-lost callback
+// queued by Dawn is delivered.
+insert('src/dawn/node/binding/GPUDevice.cpp', '"device was destroyed"));\n    }\n    device_.Destroy();\n    destroyed_ = true;', '"device was destroyed"));\n    }\n    device_.Destroy();\n    destroyed_ = true;\n    // native-dawn: deliver the queued device-lost callback.\n    async_->Begin(env);\n    async_->End();')
+
+const build = path.join(root, 'build', target)
+const args = ['-S', root, '-B', build, '-DCMAKE_BUILD_TYPE=Release', `-DNATIVE_DAWN_NODE=${hasAddon ? 'ON' : 'OFF'}`]
+// Ninja when a compiler environment is already set up (always on Linux and
+// macOS, and on Windows inside a developer prompt); Visual Studio otherwise.
+if (process.platform !== 'win32' || process.env.VSCMD_VER) args.push('-G', 'Ninja')
+else args.push('-A', process.arch === 'arm64' ? 'ARM64' : 'x64')
+const ndk = isAndroid ? androidNdk() : null
+if (isAndroid) {
+  args.push(
+    `-DCMAKE_TOOLCHAIN_FILE=${path.join(ndk, 'build/cmake/android.toolchain.cmake')}`,
+    '-DANDROID_ABI=arm64-v8a',
+    '-DANDROID_PLATFORM=android-26',
+    '-DANDROID_STL=c++_static',
+  )
+} else if (target !== `${process.platform}-${process.arch}` || !targets.includes(target)) {
+  throw new Error(`Cross-compiling ${target} is not supported; build it on a ${target} machine`)
+}
+if (process.platform === 'darwin') args.push(`-DCMAKE_OSX_ARCHITECTURES=${process.arch === 'arm64' ? 'arm64' : 'x86_64'}`, '-DCMAKE_OSX_DEPLOYMENT_TARGET=11.0')
+if (process.env.NATIVE_DAWN_COMPILER_LAUNCHER) {
+  const launcher = process.env.NATIVE_DAWN_COMPILER_LAUNCHER
+  args.push(`-DCMAKE_C_COMPILER_LAUNCHER=${launcher}`, `-DCMAKE_CXX_COMPILER_LAUNCHER=${launcher}`)
+  // sccache cannot cache MSVC's /Zi program databases.
+  if (process.platform === 'win32') args.push('-DCMAKE_POLICY_DEFAULT_CMP0141=NEW', '-DCMAKE_MSVC_DEBUG_INFORMATION_FORMAT=Embedded')
+}
+run('cmake', args, { env })
+const jobs = process.env.NATIVE_DAWN_BUILD_JOBS || String(Math.min(8, os.availableParallelism()))
+// Dawn loads dxcompiler.dll at runtime; upstream only builds it as a dependency
+// of the static dawn_native, so ask for it by name.
+const buildTargets = ['webgpu_dawn', ...(hasAddon ? ['dawn_node'] : []), ...(target.startsWith('win32-') ? ['dxcompiler'] : [])]
+run('cmake', ['--build', build, '--config', 'Release', '--target', ...buildTargets, '--parallel', jobs], { env })
+
+fs.rmSync(distDir, { recursive: true, force: true })
+run('cmake', ['--install', build, '--config', 'Release', '--prefix', distDir], { env })
+
+// Installed static helper libraries and CMake files for them are not part of
+// the SDK: consumers link webgpu_dawn only.
+const libDir = path.join(distDir, 'lib')
+for (const name of fs.readdirSync(libDir)) {
+  if (/\.(a)$/.test(name) || (target.startsWith('win32-') && name.endsWith('.lib') && name !== 'webgpu_dawn.lib')) {
+    fs.rmSync(path.join(libDir, name))
+  }
+}
+
+// A file from the newest Windows 10/11 SDK, e.g. bin/<version>/arm64/dxil.dll.
+function windowsSdkFile(arch, name) {
+  const roots = [process.env.WindowsSdkDir, path.join(process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)', 'Windows Kits', '10')].filter(Boolean)
+  for (const root of roots) {
+    const bin = path.join(root, 'bin')
+    if (!fs.existsSync(bin)) continue
+    const preferred = process.env.WindowsSDKVersion?.replace(/[\\/]+$/, '')
+    const versions = fs.readdirSync(bin).filter(v => /^10\./.test(v)).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }))
+    for (const version of preferred ? [preferred, ...versions] : versions) {
+      const file = path.join(bin, version, arch, name)
+      if (fs.existsSync(file)) return file
+    }
+  }
+  throw new Error(`No ${arch} ${name} in the Windows SDK`)
+}
+
+function findFile(dir, name) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name)
+    if (entry.isFile() && entry.name === name) return file
+    if (entry.isDirectory()) { const found = findFile(file, name); if (found) return found }
+  }
+}
+if (target.startsWith('win32-')) {
+  const arch = target === 'win32-arm64' ? 'arm64' : 'x64'
+  const dxcompiler = findFile(build, 'dxcompiler.dll')
+  if (!dxcompiler) throw new Error('Build did not produce dxcompiler.dll')
+  fs.copyFileSync(dxcompiler, path.join(distDir, 'bin', 'dxcompiler.dll'))
+  // dxil.dll (the DXIL validator/signer) comes from the Windows SDK. Dawn's own
+  // copy step always takes the x64 one, so pick the target's architecture here.
+  fs.copyFileSync(windowsSdkFile(arch, 'dxil.dll'), path.join(distDir, 'bin', 'dxil.dll'))
+  // A DLL for the wrong architecture fails to load at runtime with a misleading
+  // error, so check every shipped binary's PE machine type.
+  const machine = { x64: 0x8664, arm64: 0xaa64 }[arch]
+  for (const name of fs.readdirSync(path.join(distDir, 'bin')).filter(n => /\.(dll|node)$/.test(n))) {
+    const pe = fs.readFileSync(path.join(distDir, 'bin', name))
+    const actual = pe.readUInt16LE(pe.readUInt32LE(0x3c) + 4)
+    if (actual !== machine) throw new Error(`${name} is for machine 0x${actual.toString(16)}, not ${arch}`)
+  }
+}
+if (isAndroid) {
+  const strip = path.join(ndk, 'toolchains/llvm/prebuilt', `${process.platform === 'darwin' ? 'darwin' : process.platform === 'win32' ? 'windows' : 'linux'}-x86_64`, 'bin', `llvm-strip${process.platform === 'win32' ? '.exe' : ''}`)
+  run(strip, ['--strip-unneeded', path.join(distDir, 'lib', 'libwebgpu_dawn.so')])
+} else if (process.platform === 'linux') {
+  for (const name of ['dawn.node', 'libwebgpu_dawn.so']) run('strip', ['--strip-unneeded', path.join(distDir, binDir, name)])
+}
+if (!isAndroid && process.platform === 'darwin') {
+  for (const name of ['dawn.node', 'libwebgpu_dawn.dylib']) run('strip', ['-x', path.join(distDir, binDir, name)])
+}
+
+// Licenses for everything compiled into the binaries, without the sources.
+const licenses = path.join(distDir, 'share/native-dawn/licenses')
+fs.mkdirSync(licenses, { recursive: true })
+fs.copyFileSync(path.join(dawn, 'LICENSE'), path.join(licenses, 'dawn-LICENSE'))
+for (const entry of fs.readdirSync(path.join(dawn, 'third_party'), { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue
+  for (const base of ['', 'src']) {
+    const dir = path.join(dawn, 'third_party', entry.name, base)
+    if (!fs.existsSync(dir)) continue
+    for (const name of fs.readdirSync(dir)) {
+      if (/^(LICENSE|COPYING|NOTICE|ThirdPartyNotices)(\.|$)/i.test(name) && fs.statSync(path.join(dir, name)).isFile()) {
+        fs.copyFileSync(path.join(dir, name), path.join(licenses, `${entry.name}-${name}`))
+      }
+    }
+  }
+}
+fs.copyFileSync(path.join(root, 'LICENSE'), path.join(licenses, 'native-dawn-LICENSE'))
+fs.copyFileSync(path.join(root, 'NOTICE'), path.join(distDir, 'share/native-dawn/NOTICE'))
+fs.writeFileSync(path.join(distDir, 'build.json'), JSON.stringify({ version: pkg.version, target, dawn: upstream.dawn.revision }, null, 2) + '\n')
+console.log(`Built ${distDir}`)

package/scripts/check-release.mjs

@@ -0,0 +1,13 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { root, pkg, targets } from './common.mjs'
+
+if (process.env.GITHUB_REF_NAME !== `v${pkg.version}`) throw new Error(`Tag ${process.env.GITHUB_REF_NAME} does not match package.json version ${pkg.version}`)
+for (const target of targets) {
+  const name = `native-dawn-v${pkg.version}-${target}.tar.gz`
+  const archive = await fs.readFile(path.join(root, 'artifacts', name))
+  const checksum = await fs.readFile(path.join(root, 'artifacts', `${name}.sha256`), 'utf8')
+  if (createHash('sha256').update(archive).digest('hex') !== checksum.trim().split(/\s+/)[0]) throw new Error(`Checksum mismatch: ${name}`)
+}
+console.log(`Verified v${pkg.version}: ${targets.length} archives and checksums`)

package/scripts/common.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+export const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+export const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json')))
+export const upstream = JSON.parse(fs.readFileSync(path.join(root, 'upstream.json')))
+export const targets = ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64', 'win32-x64', 'win32-arm64', 'android-arm64']
+// Android is cross-compiled and ships the C SDK only; the rest also get the Node addon.
+export const nodeTargets = targets.filter(t => !t.startsWith('android-'))
+// NATIVE_DAWN_TARGET selects a cross-compiled target; the default is this machine.
+export const target = process.env.NATIVE_DAWN_TARGET || `${process.platform}-${process.arch}`
+export const isAndroid = target.startsWith('android-')
+export const hasAddon = nodeTargets.includes(target)
+export const assetName = `native-dawn-v${pkg.version}-${target}.tar.gz`
+export const distDir = path.join(root, 'dist', target)
+export const binDir = target.startsWith('win32-') ? 'bin' : 'lib'
+
+export function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { cwd: root, stdio: 'inherit', ...options })
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new Error(`${command} exited with ${result.status ?? result.signal}`)
+  return result
+}
+
+export function assertTarget() {
+  if (!targets.includes(target)) throw new Error(`Unsupported platform ${target}; supported: ${targets.join(', ')}`)
+}
+
+export function manifestMatches(manifest) {
+  return manifest.version === pkg.version && manifest.target === target && manifest.dawn === upstream.dawn.revision
+}
+
+// Applies one source hook: inserts replacement for a needle that must occur
+// exactly once. Returns the new text, the same text if already applied, or
+// null if the needle is missing or ambiguous. Dawn is checked out with CRLF on
+// Windows (core.autocrlf), so multi-line hooks follow the file's line endings.
+export function insertText(text, needle, replacement) {
+  if (text.includes('\r\n')) {
+    needle = needle.replaceAll('\n', '\r\n')
+    replacement = replacement.replaceAll('\n', '\r\n')
+  }
+  if (text.includes(replacement)) return text
+  if (text.split(needle).length !== 2) return null
+  return text.replace(needle, () => replacement)
+}

package/scripts/fetch-dependencies.py

@@ -0,0 +1,47 @@
+"""Use Dawn's DEPS pins without installing Chromium's depot_tools or toolchains."""
+import importlib.util
+import pathlib
+import sys
+
+root = pathlib.Path(sys.argv[1]).resolve()
+spec = importlib.util.spec_from_file_location('dawn_fetch', root / 'tools/fetch_dawn_dependencies.py')
+fetch = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(fetch)
+deps = [
+    'third_party/abseil-cpp', 'third_party/jinja2', 'third_party/markupsafe',
+    'third_party/EGL-Registry/src', 'third_party/OpenGL-Registry/src',
+    'third_party/glslang/src', 'third_party/spirv-headers/src',
+    'third_party/spirv-tools/src', 'third_party/vulkan-headers/src',
+    'third_party/vulkan-utility-libraries/src', 'third_party/webgpu-headers/src',
+    'third_party/node-addon-api', 'third_party/node-api-headers', 'third_party/gpuweb',
+]
+if sys.platform == 'win32':
+    deps += ['third_party/directx-shader-compiler/src', 'third_party/directx-headers/src']
+# Read the upstream dependency pins, but check every subprocess result.
+import subprocess
+from concurrent.futures import ThreadPoolExecutor
+scope = {}
+exec((root / 'DEPS').read_text(), {'Var': fetch.Var, 'Str': str}, scope)
+def download(dep):
+    entry = scope['deps'].get(dep)
+    if not entry:
+        raise RuntimeError(f'Dawn no longer declares the required dependency {dep}')
+    url, pin = entry['url'].format(**scope['vars']).rsplit('@', 1)
+    folder = root / dep
+    folder.mkdir(parents=True, exist_ok=True)
+    def git(*args, capture=False):
+        return subprocess.run(['git', '-C', str(folder), *args], check=True,
+                              text=True, capture_output=capture)
+    if not (folder / '.git').exists():
+        git('init', '-q')
+    current = subprocess.run(['git', '-C', str(folder), 'rev-parse', 'HEAD'], capture_output=True, text=True)
+    if current.returncode == 0 and current.stdout.strip() == pin:
+        return
+    print(f'Fetching {dep} at {pin}', flush=True)
+    git('fetch', '--depth', '1', url, pin)
+    git('checkout', '--detach', pin)
+    actual = subprocess.check_output(['git', '-C', str(root / dep), 'rev-parse', 'HEAD'], text=True).strip()
+    if actual != pin:
+        raise RuntimeError(f'{dep}: expected {pin}, got {actual}')
+with ThreadPoolExecutor(max_workers=4) as pool:
+    list(pool.map(download, deps))

package/scripts/install.mjs

@@ -0,0 +1,82 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { createHash } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { x as extract } from 'tar'
+import { root, target, pkg, assetName, distDir, binDir, nodeTargets, hasAddon, manifestMatches, run } from './common.mjs'
+
+const addon = dir => path.join(dir, binDir, 'dawn.node')
+
+export async function install() {
+  if (process.env.NATIVE_DAWN_SKIP_INSTALL === '1') return
+  if (!hasAddon) throw new Error(`No Node build for ${target}; supported: ${nodeTargets.join(', ')}. Android SDK archives are on the GitHub releases.`)
+  if (process.env.NATIVE_DAWN_BUILD_FROM_SOURCE === '1') {
+    run(process.execPath, [path.join(root, 'scripts/build.mjs')])
+    return
+  }
+  if (!process.env.NATIVE_DAWN_BINARY) {
+    try {
+      if (manifestMatches(JSON.parse(await fs.readFile(path.join(distDir, 'build.json'))))) {
+        createRequire(import.meta.url)(addon(distDir))
+        return
+      }
+    } catch { /* No usable local build; install the release archive. */ }
+  }
+  const temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'native-dawn-install-'))
+  try {
+    let archive, checksum
+    if (process.env.NATIVE_DAWN_BINARY) {
+      const file = path.resolve(process.env.NATIVE_DAWN_BINARY)
+      archive = await fs.readFile(file)
+      checksum = await fs.readFile(`${file}.sha256`, 'utf8')
+    } else {
+      const base = `https://github.com/monteslu/native-dawn/releases/download/v${pkg.version}`
+      const responses = await Promise.all([
+        fetch(`${base}/${assetName}`, { signal: AbortSignal.timeout(300000) }),
+        fetch(`${base}/${assetName}.sha256`, { signal: AbortSignal.timeout(60000) }),
+      ])
+      for (const response of responses) if (!response.ok) throw new Error(`Release download failed: HTTP ${response.status} ${response.url}`)
+      archive = Buffer.from(await responses[0].arrayBuffer())
+      checksum = await responses[1].text()
+    }
+    const expected = checksum.trim().split(/\s+/)[0]
+    const actual = createHash('sha256').update(archive).digest('hex')
+    if (!/^[a-f0-9]{64}$/.test(expected) || actual !== expected) throw new Error('Native archive checksum mismatch')
+    const file = path.join(temporary, 'binary.tar.gz')
+    const staging = path.join(temporary, 'unpacked')
+    await fs.mkdir(staging)
+    await fs.writeFile(file, archive)
+    await extract({
+      file, cwd: staging, strict: true, preservePaths: false,
+      filter: (name, entry) => {
+        if (path.isAbsolute(name) || name.split(/[\\/]/).includes('..') || !['File', 'Directory', 'SymbolicLink'].includes(entry.type)) throw new Error(`Invalid native archive entry: ${name}`)
+        if (entry.type === 'SymbolicLink' && (path.isAbsolute(entry.linkpath) || entry.linkpath.split(/[\\/]/).includes('..'))) throw new Error(`Invalid native archive link: ${name}`)
+        return true
+      },
+    })
+    if (!manifestMatches(JSON.parse(await fs.readFile(path.join(staging, 'build.json'))))) {
+      throw new Error('Native archive does not match this package version, platform, or Dawn revision')
+    }
+    await fs.access(addon(staging))
+    await fs.rm(distDir, { recursive: true, force: true })
+    await fs.mkdir(path.dirname(distDir), { recursive: true })
+    await fs.cp(staging, distDir, { recursive: true, verbatimSymlinks: true })
+    createRequire(import.meta.url)(addon(distDir))
+    console.log(`Installed native-dawn for ${target}`)
+  } finally {
+    await fs.rm(temporary, { recursive: true, force: true })
+  }
+}
+
+// A failed install leaves native-dawn without a native build but never fails
+// the surrounding npm install: packages that depend on it (webgpu-node, and
+// through it wasmcart) must still install on platforms native-dawn does not
+// cover, and only error when WebGPU is actually used. A bad archive is never
+// installed either way. NATIVE_DAWN_STRICT_INSTALL=1 makes failures fatal.
+try {
+  await install()
+} catch (error) {
+  console.warn(`native-dawn: no native build installed: ${error.message}\nWebGPU will not be available on this machine; importing native-dawn will throw. To build from source, install the toolchain in README.md and set NATIVE_DAWN_BUILD_FROM_SOURCE=1.`)
+  if (process.env.NATIVE_DAWN_STRICT_INSTALL === '1') process.exitCode = 1
+}

package/scripts/package-binary.mjs

@@ -0,0 +1,14 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { c as tar } from 'tar'
+import { root, assetName, distDir, binDir, hasAddon, manifestMatches } from './common.mjs'
+
+if (!manifestMatches(JSON.parse(await fs.readFile(path.join(distDir, 'build.json'))))) throw new Error('Refusing to package a stale native build')
+await fs.access(path.join(distDir, binDir, hasAddon ? 'dawn.node' : 'libwebgpu_dawn.so'))
+await fs.mkdir(path.join(root, 'artifacts'), { recursive: true })
+const file = path.join(root, 'artifacts', assetName)
+await tar({ file, cwd: distDir, gzip: { level: 9 }, portable: true }, await fs.readdir(distDir))
+const hash = createHash('sha256').update(await fs.readFile(file)).digest('hex')
+await fs.writeFile(`${file}.sha256`, `${hash}  ${assetName}\n`)
+console.log(file)

package/scripts/test-android.mjs

@@ -0,0 +1,43 @@
+// Builds test/c with the NDK against an Android prefix, pushes it to the
+// device or emulator adb is connected to, and runs it there.
+//   NATIVE_DAWN_TARGET=android-arm64 node scripts/test-android.mjs [prefix]
+// On an x86_64 emulator, the arm64 binary runs through Android's ARM translation.
+// NATIVE_DAWN_TEST_* variables are passed through to the device.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { root, run, target, distDir, isAndroid } from './common.mjs'
+
+if (!isAndroid) throw new Error('Set NATIVE_DAWN_TARGET=android-arm64')
+const prefix = path.resolve(process.argv[2] || distDir)
+const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT
+function ndk() {
+  for (const name of ['ANDROID_NDK_HOME', 'ANDROID_NDK_ROOT', 'ANDROID_NDK_LATEST_HOME']) {
+    if (process.env[name] && fs.existsSync(process.env[name])) return process.env[name]
+  }
+  const dir = path.join(sdk, 'ndk')
+  return path.join(dir, fs.readdirSync(dir).sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).at(-1))
+}
+const adb = sdk && fs.existsSync(path.join(sdk, 'platform-tools/adb')) ? path.join(sdk, 'platform-tools/adb') : 'adb'
+
+const build = fs.mkdtempSync(path.join(os.tmpdir(), 'native-dawn-android-'))
+const remote = '/data/local/tmp/native-dawn'
+try {
+  run('cmake', ['-S', path.join(root, 'test/c'), '-B', build, '-G', 'Ninja', '-DCMAKE_BUILD_TYPE=Release',
+    `-DCMAKE_TOOLCHAIN_FILE=${path.join(ndk(), 'build/cmake/android.toolchain.cmake')}`,
+    '-DANDROID_ABI=arm64-v8a', '-DANDROID_PLATFORM=android-26',
+    `-DDawn_DIR=${path.join(prefix, 'lib/cmake/Dawn')}`, `-DCMAKE_FIND_ROOT_PATH=${prefix}`])
+  run('cmake', ['--build', build])
+  run(adb, ['shell', `rm -rf ${remote} && mkdir -p ${remote}`])
+  run(adb, ['push', path.join(build, 'compute'), path.join(prefix, 'lib/libwebgpu_dawn.so'), `${remote}/`])
+  const vars = Object.entries(process.env).filter(([k]) => k.startsWith('NATIVE_DAWN_TEST_')).map(([k, v]) => `${k}=${v}`).join(' ')
+  const result = spawnSync(adb, ['shell', `cd ${remote} && chmod 755 compute && ${vars} LD_LIBRARY_PATH=${remote} ./compute; echo "exit=$?"`], { encoding: 'utf8' })
+  process.stdout.write(result.stdout)
+  process.stderr.write(result.stderr)
+  if (!/exit=0\s*$/.test(result.stdout)) throw new Error(`compute failed on the device (${target})`)
+  console.log(`Android ${target}: C test passed on the device`)
+} finally {
+  spawnSync(adb, ['shell', `rm -rf ${remote}`])
+  fs.rmSync(build, { recursive: true, force: true })
+}

package/scripts/test-c.mjs

@@ -0,0 +1,29 @@
+// Builds test/c against an installed prefix with find_package(Dawn) and runs
+// it, the way a C or C++ project outside Node would consume native-dawn.
+//   node scripts/test-c.mjs [prefix]
+// NATIVE_DAWN_TEST_SDL2=1 also builds and runs the SDL2 window test.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { root, run, distDir } from './common.mjs'
+
+const prefix = path.resolve(process.argv[2] || distDir)
+const sdl2 = process.env.NATIVE_DAWN_TEST_SDL2 === '1'
+const build = fs.mkdtempSync(path.join(os.tmpdir(), 'native-dawn-c-'))
+try {
+  const args = ['-S', path.join(root, 'test/c'), '-B', build, '-DCMAKE_BUILD_TYPE=Release', `-DCMAKE_PREFIX_PATH=${prefix}`, `-DNATIVE_DAWN_TEST_SDL2=${sdl2 ? 'ON' : 'OFF'}`]
+  if (process.platform !== 'win32' || process.env.VSCMD_VER) args.push('-G', 'Ninja')
+  run('cmake', args)
+  run('cmake', ['--build', build, '--config', 'Release'])
+  const env = { ...process.env }
+  if (process.platform === 'win32') env.PATH = `${path.join(prefix, 'bin')}${path.delimiter}${env.PATH}`
+  const exe = name => {
+    const file = name + (process.platform === 'win32' ? '.exe' : '')
+    for (const dir of [build, path.join(build, 'Release')]) if (fs.existsSync(path.join(dir, file))) return path.join(dir, file)
+    throw new Error(`${file} was not built`)
+  }
+  run(exe('compute'), [], { env })
+  if (sdl2) run(exe('sdl2_window'), [], { env })
+} finally {
+  fs.rmSync(build, { recursive: true, force: true })
+}

package/scripts/test-package.mjs

@@ -0,0 +1,34 @@
+// Packs the npm tarball, installs it with the release archive into a scratch
+// project, and checks it from Node and from a C program built against it.
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { root, assetName, run } from './common.mjs'
+
+run(process.execPath, ['scripts/package-binary.mjs'])
+const npm = process.env.npm_execpath
+if (!npm) throw new Error('Run this through npm run test:package')
+function npmRun(args, options = {}) {
+  const result = spawnSync(process.execPath, [npm, ...args], { cwd: root, stdio: 'inherit', ...options })
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new Error(`npm ${args[0]} failed (${result.status})`)
+  return result
+}
+const temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'native-dawn-consumer-'))
+try {
+  const packed = npmRun(['pack', '--json', '--pack-destination', temporary], { stdio: 'pipe', encoding: 'utf8' })
+  const [metadata] = JSON.parse(packed.stdout)
+  const leaked = metadata.files.filter(f => /^(\.cache|node_modules|build|dist|artifacts|test)\//.test(f.path))
+  if (leaked.length) throw new Error(`npm package includes ${leaked.map(f => f.path).join(', ')}`)
+  await fs.writeFile(path.join(temporary, 'package.json'), '{"name":"native-dawn-consumer","private":true,"type":"module"}\n')
+  npmRun(['install', '--omit=dev', '--no-audit', '--no-fund', path.join(temporary, metadata.filename)], {
+    cwd: temporary,
+    env: { ...process.env, NATIVE_DAWN_BINARY: path.join(root, 'artifacts', assetName), NATIVE_DAWN_SKIP_INSTALL: '0', NATIVE_DAWN_BUILD_FROM_SOURCE: '0' },
+  })
+  await fs.copyFile(path.join(root, 'test/consumer.mjs'), path.join(temporary, 'consumer.mjs'))
+  run(process.execPath, ['consumer.mjs'], { cwd: temporary })
+  const prefix = spawnSync(process.execPath, [path.join(temporary, 'node_modules/native-dawn/bin/native-dawn.js'), 'prefix'], { encoding: 'utf8' }).stdout.trim()
+  run(process.execPath, ['scripts/test-c.mjs', prefix])
+  console.log('Packed package passed from Node and from C')
+} finally { await fs.rm(temporary, { recursive: true, force: true }) }

package/scripts/test.mjs

@@ -0,0 +1,11 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { root } from './common.mjs'
+
+// One process per file keeps each file's GPU devices and addon state separate.
+for (const file of fs.readdirSync(path.join(root, 'test')).filter(name => name.endsWith('.test.mjs')).sort()) {
+  const result = spawnSync(process.execPath, [path.join(root, 'test', file)], { cwd: root, stdio: 'inherit', timeout: 180000 })
+  if (result.error) throw result.error
+  if (result.status !== 0) process.exit(result.status || 1)
+}