Flat Win32 ([DllImport]) support: generated natural wrappers + Registry (stacks on #65)

.github/skills/classic-com-abi/SKILL.md

@@ -9,9 +9,13 @@ Use this skill for changes under:
 
 - `crates/dynwinrt/src/com.rs`, `signature.rs`, `native_call.rs`, or `call.rs`;
 - `bindings/js/src/com.rs`;
+- `crates/dynwinrt/src/win32.rs`;
+- `bindings/js/src/win32.rs`;
 - `tools/dynwinrt-codegen/src/com_metadata.rs`;
 - `tools/dynwinrt-codegen/src/codegen/com/`; or
-- Classic COM runners in `tests/runners/com/`.
+- `tools/dynwinrt-codegen/src/codegen/win32/`;
+- Classic COM runners in `tests/runners/com/`; or
+- flat Win32 runners in `tests/runners/flat/`.
 
 Read [`docs/classic-com-support.md`](../../../docs/classic-com-support.md)
 before changing supported types or claiming support for an interface.
@@ -32,6 +36,20 @@ Windows.Win32.winmd facts
 `Buffer`, `bigint`, `string`, and generated wrappers are projection choices.
 They must not determine native semantics.
 
+Flat Win32 is a third semantic frontend:
+
+```text
+Windows.Win32.winmd [DllImport]
+  -> flat-local metadata and validated ABI plan
+  -> flat JavaScript projection
+  -> @microsoft/dynwinrt/win32
+  -> System32 DLL export
+```
+
+Keep it out of `DynWinRt*`, the npm root, and `DynCom*`. Preserve P/Invoke
+calling convention, architecture, pointer depth, native-array size
+relationships, `SupportsLastError`, and return lifetime before rendering.
+
 ## Required semantic model
 
 Preserve these facts before rendering:

.github/workflows/build.yml

@@ -161,3 +161,5 @@ jobs:
             bindings/js/dist/winrt.d.ts
             bindings/js/dist/com.js
             bindings/js/dist/com.d.ts
+            bindings/js/dist/win32.js
+            bindings/js/dist/win32.d.ts

.gitignore

@@ -25,6 +25,8 @@ mono_crash.*
 x64/
 x86/
 [Ww][Ii][Nn]32/
+!tools/dynwinrt-codegen/src/codegen/win32/
+!tools/dynwinrt-codegen/src/codegen/win32/**
 [Aa][Rr][Mm]/
 [Aa][Rr][Mm]64/
 [Aa][Rr][Mm]64[Ee][Cc]/

README.md

@@ -56,6 +56,13 @@ package root remains the WinRT-only API. See
 [Classic COM support](docs/classic-com-support.md) for the supported ABI,
 common-interface test matrix, unsupported native types, and ownership rules.
 
+Flat Win32 bindings use the separate `@microsoft/dynwinrt/win32` runtime
+entrypoint and are generated into namespace-specific modules. Generation is
+fail-closed for native shapes whose pointer depth, size, architecture, calling
+convention, lifetime, or ownership is not modeled. See
+[Flat Win32 support](docs/flat-win32-support.md) for the supported subset and
+limitations.
+
 Generated bindings project unambiguous public WinRT activation metadata as JavaScript
 constructors, including overloads such as `new Uri(base, relative)`. Existing
 static factory methods remain available. Classes that can only be returned by

bindings/js/README.md

@@ -55,6 +55,16 @@ native output that transfers an existing `+1` reference; numeric pointers and
 typed-array pointers are borrowed and cannot be adopted. Win32 handles are not
 COM references and require their own type-specific cleanup function.
 
+Flat Win32 DLL exports use a third entrypoint:
+
+```js
+const { DynWin32 } = require('@microsoft/dynwinrt/win32');
+```
+
+Use generated flat Win32 wrappers rather than calling `DynWin32.invoke`
+directly. Generated wrappers encode the validated native signature and capture
+`GetLastError` when required.
+
 Unambiguous public WinRT activation metadata is projected as JavaScript constructors.
 Parameterized and composable activations support idiomatic forms such as
 `new Uri(base, relative)` and `new StackPanel()`. The generated static factory

bindings/js/__test__/index.spec.ts

@@ -20,6 +20,7 @@ import {
 } from '../dist/winrt.js'
 import * as winrtRuntime from '../dist/winrt.js'
 import { DynCom, DynComMethodSig } from '../dist/com.js'
+import { DynWin32 } from '../dist/win32.js'
 
 test('Classic COM is isolated from the WinRT root entrypoint', (t) => {
   t.false(Object.prototype.hasOwnProperty.call(winrtRuntime, 'DynCom'))
@@ -58,6 +59,55 @@ test('Classic COM is isolated from the WinRT root entrypoint', (t) => {
   t.regex(esm.stdout, /runtime-entrypoints-ok/)
 })
 
+test('flat Win32 is isolated from the WinRT root entrypoint', (t) => {
+  t.false(Object.prototype.hasOwnProperty.call(winrtRuntime, 'DynWin32'))
+  t.truthy(DynWin32)
+
+  const assertion =
+    "const assert = require('node:assert/strict');" +
+    "const winrt = require('@microsoft/dynwinrt');" +
+    "const win32 = require('@microsoft/dynwinrt/win32');" +
+    "assert.equal(Object.prototype.hasOwnProperty.call(winrt, 'DynWin32'), false);" +
+    "assert.equal(typeof win32.DynWin32, 'function');" +
+    "console.log('win32-entrypoint-ok')"
+  const cjs = spawnSync(process.execPath, ['--eval', assertion], {
+    cwd: resolve(process.cwd()),
+    encoding: 'utf8',
+    windowsHide: true,
+  })
+  t.is(cjs.status, 0, cjs.stderr)
+  t.regex(cjs.stdout, /win32-entrypoint-ok/)
+})
+
+test('DynWin32 validates scalar widths and retained pointer storage', (t) => {
+  t.notThrows(() => DynWin32.i64(-(2n ** 63n)))
+  t.notThrows(() => DynWin32.i64(Number.MAX_SAFE_INTEGER))
+  t.throws(() => DynWin32.i64(2n ** 63n), { message: /signed 64-bit/ })
+  t.throws(() => DynWin32.i64(1.5), { message: /safe integer/ })
+  t.throws(() => DynWin32.i8(128), { message: /range/ })
+  t.throws(() => DynWin32.i8(4_294_967_297), { message: /range/ })
+  t.throws(() => DynWin32.i32(4_294_967_296), { message: /range/ })
+  t.throws(() => DynWin32.u32(-1), { message: /range/ })
+  t.throws(() => DynWin32.u16(1.5), { message: /integer/ })
+  t.is(DynWin32.toPointerBigint(DynWin32.handle(-1n)), (2n ** 64n) - 1n)
+  t.is(DynWin32.toPointerBigint(DynWin32.handle(-2)), (2n ** 64n) - 2n)
+
+  const bytes = new Uint8Array(8)
+  const pointer = DynWin32.pointer(bytes)
+  structuredClone(bytes.buffer, { transfer: [bytes.buffer] })
+  const error = t.throws(() => DynWin32.toPointerBigint(pointer))
+  t.regex(error.message, /backing ArrayBuffer is detached/)
+})
+
+test('DynWinRtValue accepts lossless UInt64 bigint inputs', (t) => {
+  const max = (2n ** 64n) - 1n
+  t.is(DynCom.toU64Bigint(DynWinRtValue.u64(max)), max)
+  t.throws(() => DynWinRtValue.u64(-1n), { message: /unsigned 64-bit/ })
+  t.throws(() => DynWinRtValue.u64(Number.MAX_SAFE_INTEGER + 1), {
+    message: /safe integer/,
+  })
+})
+
 test('DynCom rejects pointers after their TypedArray backing store is detached', (t) => {
   const bytes = new Uint8Array(16)
   const pointer = DynCom.pointer(bytes)

bindings/js/package.json

@@ -17,12 +17,21 @@
       "require": "./dist/com.js",
       "default": "./dist/com.js"
     },
+    "./win32": {
+      "types": "./dist/win32.d.ts",
+      "import": "./dist/win32.js",
+      "require": "./dist/win32.js",
+      "default": "./dist/win32.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
     "*": {
       "com": [
         "dist/com.d.ts"
+      ],
+      "win32": [
+        "dist/win32.d.ts"
       ]
     }
   },

bindings/js/scripts/generate-entrypoints.mjs

@@ -27,18 +27,24 @@ const comExports = new Set([
   'WinGuid',
   'WinGUID',
 ])
+const win32Exports = new Set(['DynWin32', 'DynWin32CallResult', 'DynWin32Value'])
 
 writeFacade(
   'winrt',
-  nativeExports.filter((name) => !name.startsWith('DynCom')),
+  nativeExports.filter((name) => !name.startsWith('DynCom') && !name.startsWith('DynWin32')),
 )
 writeFacade(
   'com',
   nativeExports.filter((name) => comExports.has(name)),
 )
+writeFacade(
+  'win32',
+  nativeExports.filter((name) => win32Exports.has(name)),
+)
 
 function writeFacade(name, exports) {
-  const missing = name === 'com' ? [...comExports].filter((value) => !exports.includes(value)) : []
+  const required = name === 'com' ? comExports : name === 'win32' ? win32Exports : new Set()
+  const missing = [...required].filter((value) => !exports.includes(value))
   if (missing.length > 0) {
     throw new Error(`Missing required ${name} exports: ${missing.join(', ')}`)
   }

bindings/js/src/com.rs

@@ -206,7 +206,7 @@ fn uint8_array_info(
   }))
 }
 
-fn pointer(value: Unknown) -> napi::Result<DynWinRTValue> {
+pub(super) fn pointer(value: Unknown) -> napi::Result<DynWinRTValue> {
   use napi::sys;
 
   let env = value.value().env;
@@ -364,7 +364,7 @@ fn adopt_co_task_mem_pointer(value: &mut DynWinRTValue) -> napi::Result<DynWinRT
   ))
 }
 
-fn as_pointer_bigint(value: &DynWinRTValue) -> napi::Result<BigInt> {
+pub(super) fn as_pointer_bigint(value: &DynWinRTValue) -> napi::Result<BigInt> {
   validate_pointer_owner(value)?;
   let bits = match &value.0 {
     dynwinrt::WinRTValue::Object(_) => {
@@ -414,7 +414,7 @@ fn take_bstr(value: &mut DynWinRTValue) -> napi::Result<String> {
   String::try_from(&value).map_err(|error| napi::Error::from_reason(error.to_string()))
 }
 
-fn validate_pointer_owner(value: &DynWinRTValue) -> napi::Result<()> {
+pub(super) fn validate_pointer_owner(value: &DynWinRTValue) -> napi::Result<()> {
   if let Some(owner) = &value.1 {
     owner.validate()?;
   }

bindings/js/src/lib.rs

@@ -12,13 +12,15 @@ use std::{
 
 use dynwinrt;
 use napi::Env;
-use napi::bindgen_prelude::{BigInt, PromiseRaw};
+use napi::bindgen_prelude::{BigInt, Either, PromiseRaw};
 use napi::threadsafe_function::ThreadsafeFunctionCallMode;
 use napi_derive::napi;
 use windows::core::{HSTRING, IUnknown, Interface};
 
 mod com;
 pub use com::{DynCom, DynComInterface, DynComMethodHandle, DynComMethodSig, DynComType};
+mod win32;
+pub use win32::{DynWin32, DynWin32CallResult, DynWin32Value};
 mod async_promise;
 mod scheduled_start;
 
@@ -693,8 +695,33 @@ impl DynWinRTValue {
     DynWinRTValue::new(dynwinrt::WinRTValue::I64(value))
   }
   #[napi]
-  pub fn u64(value: i64) -> DynWinRTValue {
-    DynWinRTValue::new(dynwinrt::WinRTValue::U64(value as u64))
+  pub fn u64(
+    #[napi(ts_arg_type = "number | bigint")] value: Either<BigInt, f64>,
+  ) -> napi::Result<DynWinRTValue> {
+    let value = match value {
+      Either::A(value) => {
+        let (negative, value, lossless) = value.get_u64();
+        if negative || !lossless {
+          return Err(napi::Error::from_reason(
+            "DynWinRtValue.u64(): value must fit in an unsigned 64-bit integer",
+          ));
+        }
+        value
+      }
+      Either::B(value) => {
+        if !value.is_finite()
+          || value < 0.0
+          || value.fract() != 0.0
+          || value > 9_007_199_254_740_991.0
+        {
+          return Err(napi::Error::from_reason(
+            "DynWinRtValue.u64(): number must be a non-negative safe integer",
+          ));
+        }
+        value as u64
+      }
+    };
+    Ok(DynWinRTValue::new(dynwinrt::WinRTValue::U64(value)))
   }
   #[napi]
   pub fn f32(value: f64) -> DynWinRTValue {