quickwin 1.2.1 → 2.0.0

package/lib/websocket.js

@@ -295,7 +295,13 @@ class WebSocketImpl {
                         doError(new Error('SSL_CTX_new failed'));
                         return;
                     }
-                    wolfssl.wolfSSL_CTX_set_verify(this._ctx, 0 /* wolfssl.VerifyMode.SSL_VERIFY_NONE */);
+                    if (this._options.rejectUnauthorized === false) {
+                        wolfssl.wolfSSL_CTX_set_verify(this._ctx, 0 /* wolfssl.VerifyMode.SSL_VERIFY_NONE */);
+                    }
+                    else {
+                        wolfssl.wolfSSL_CTX_set_verify(this._ctx, 1 /* wolfssl.VerifyMode.SSL_VERIFY_PEER */);
+                        wolfssl.loadTrustedCerts(this._ctx);
+                    }
                     this._ssl = wolfssl.wolfSSL_new(this._ctx);
                     if (!this._ssl) {
                         doError(new Error('SSL_new failed'));
@@ -303,8 +309,12 @@ class WebSocketImpl {
                     }
                     wolfssl.wolfSSL_set_fd(this._ssl, sock.get_fd(fd));
                     const sniHost = host;
-                    if (sniHost)
+                    if (sniHost) {
                         wolfssl.wolfSSL_UseSNI(this._ssl, 0 /* wolfssl.SniType.WOLFSSL_SNI_HOST_NAME */, sniHost);
+                        if (this._options.rejectUnauthorized !== false) {
+                            wolfssl.wolfSSL_check_domain_name(this._ssl, sniHost);
+                        }
+                    }
                     state = 'handshake';
                 }
                 else {

package/lib/websocket.ts

@@ -151,6 +151,9 @@ function tryParseFrame(buffer: Uint8Array): ParsedFrame | null {
 
 interface WebSocketOptions {
     headers?: Record<string, string>
+    /** Non-standard: when false, TLS certificate verification is skipped
+     *  (mirrors Node's tls.connect rejectUnauthorized option). */
+    rejectUnauthorized?: boolean
 }
 
 
@@ -318,12 +321,22 @@ class WebSocketImpl {
                     const method = wolfssl.wolfTLSv1_2_client_method()
                     this._ctx = wolfssl.wolfSSL_CTX_new(method)
                     if (!this._ctx) { doError(new Error('SSL_CTX_new failed')); return }
-                    wolfssl.wolfSSL_CTX_set_verify(this._ctx, wolfssl.VerifyMode.SSL_VERIFY_NONE)
+                    if (this._options.rejectUnauthorized === false) {
+                        wolfssl.wolfSSL_CTX_set_verify(this._ctx, wolfssl.VerifyMode.SSL_VERIFY_NONE)
+                    } else {
+                        wolfssl.wolfSSL_CTX_set_verify(this._ctx, wolfssl.VerifyMode.SSL_VERIFY_PEER)
+                        wolfssl.loadTrustedCerts(this._ctx)
+                    }
                     this._ssl = wolfssl.wolfSSL_new(this._ctx)
                     if (!this._ssl) { doError(new Error('SSL_new failed')); return }
                     wolfssl.wolfSSL_set_fd(this._ssl, sock.get_fd(fd))
                     const sniHost = host
-                    if (sniHost) wolfssl.wolfSSL_UseSNI(this._ssl, wolfssl.SniType.WOLFSSL_SNI_HOST_NAME, sniHost)
+                    if (sniHost) {
+                        wolfssl.wolfSSL_UseSNI(this._ssl, wolfssl.SniType.WOLFSSL_SNI_HOST_NAME, sniHost)
+                        if (this._options.rejectUnauthorized !== false) {
+                            wolfssl.wolfSSL_check_domain_name(this._ssl, sniHost)
+                        }
+                    }
                     state = 'handshake'
                 } else {
                     this._sendRawStr(request)

package/lib/windows/comctl32.js

@@ -0,0 +1,18 @@
+// comctl32 绑定（ImageList 系列；HIMAGELIST 为不透明句柄保持 <>ptr）
+import { bind } from '../ffi/bind.js';
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = (name, sig) => bind('comctl32.dll', name, sig);
+/** 创建图像列表；失败 → 0
+ *  @param args_0 cx 图像宽度（像素）
+ *  @param args_1 cy 图像高度（像素）
+ *  @param args_2 flags ILC_* 标志（ILC_COLOR32 = 4）
+ *  @param args_3 initial 初始图像数，0 = 默认
+ *  @param args_4 grow 扩容步长，0 = 默认 */
+export const ImageListCreate = /*@__PURE__*/ b('ImageList_Create', 'i32 i32 u32 i32 i32 -> <>ptr');
+/** 追加位图到图像列表；返回新图像索引（-1 失败）
+ *  @param args_0 himl
+ *  @param args_1 hbmImage 源位图句柄（HBITMAP） */
+export const ImageListAdd = /*@__PURE__*/ b('ImageList_Add', '<>ptr <>ptr -> i32');
+/** 销毁图像列表；成功 → 非 0
+ *  @param args_0 himl */
+export const ImageListDestroy = /*@__PURE__*/ b('ImageList_Destroy', '<>ptr -> i32');

package/lib/windows/comctl32.ts

@@ -0,0 +1,20 @@
+// comctl32 绑定（ImageList 系列；HIMAGELIST 为不透明句柄保持 <>ptr）
+import { bind } from '../ffi/bind.js'
+
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = <const S extends string>(name: string, sig: S) => bind('comctl32.dll', name, sig)
+
+/** 创建图像列表；失败 → 0
+ *  @param args_0 cx 图像宽度（像素）
+ *  @param args_1 cy 图像高度（像素）
+ *  @param args_2 flags ILC_* 标志（ILC_COLOR32 = 4）
+ *  @param args_3 initial 初始图像数，0 = 默认
+ *  @param args_4 grow 扩容步长，0 = 默认 */
+export const ImageListCreate = /*@__PURE__*/ b('ImageList_Create', 'i32 i32 u32 i32 i32 -> <>ptr')
+/** 追加位图到图像列表；返回新图像索引（-1 失败）
+ *  @param args_0 himl
+ *  @param args_1 hbmImage 源位图句柄（HBITMAP） */
+export const ImageListAdd = /*@__PURE__*/ b('ImageList_Add', '<>ptr <>ptr -> i32')
+/** 销毁图像列表；成功 → 非 0
+ *  @param args_0 himl */
+export const ImageListDestroy = /*@__PURE__*/ b('ImageList_Destroy', '<>ptr -> i32')

package/lib/windows/comdlg32.js

@@ -0,0 +1,7 @@
+// comdlg32 绑定（通用文件对话框；GetOpenFileName 无 A/W 混用——一律 W 版）
+import { bind } from '../ffi/bind.js';
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = (name, sig) => bind('comdlg32.dll', name, sig);
+/** 打开/保存文件对话框；用户确认 → 非 0（lpstrFile 缓冲即选中路径），取消/出错 → 0
+ *  @param args_0 pOpenfn OPENFILENAMEW.encode(...).ptr（lStructSize 必须 = OPENFILENAMEW.size，见 structs.ts） */
+export const GetOpenFileName = /*@__PURE__*/ b('GetOpenFileNameW', '<BYTE>ptr -> u32');

package/lib/windows/comdlg32.ts

@@ -0,0 +1,9 @@
+// comdlg32 绑定（通用文件对话框；GetOpenFileName 无 A/W 混用——一律 W 版）
+import { bind } from '../ffi/bind.js'
+
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = <const S extends string>(name: string, sig: S) => bind('comdlg32.dll', name, sig)
+
+/** 打开/保存文件对话框；用户确认 → 非 0（lpstrFile 缓冲即选中路径），取消/出错 → 0
+ *  @param args_0 pOpenfn OPENFILENAMEW.encode(...).ptr（lStructSize 必须 = OPENFILENAMEW.size，见 structs.ts） */
+export const GetOpenFileName = /*@__PURE__*/ b('GetOpenFileNameW', '<BYTE>ptr -> u32')

package/lib/windows/gdi32.js

@@ -0,0 +1,90 @@
+// gdi32 绑定（品牌约定见 lib/windows/user32.ts 头注释）：
+//   - HDC 出入参用 <HDC>ptr（品牌指针 Ptr<'HDC'>，与 user32 的 GetDC/ReleaseDC 同型互认）
+//   - GDI 对象通用句柄（HBRUSH/HPEN/HFONT/HBITMAP 在 Win32 同为 HGDIOBJ）保持 <>ptr——
+//     异种对象互传由运行时句柄有效性判定，类型层不设品牌
+//   - 结构位按方向分流：CreateFontIndirect 的 LOGFONTW 是纯入参位，注册 encoder 收
+//     DeepPartial 对象直传（缺省字段跳过 = 保持 0 合法零值语义）
+import { bind } from '../ffi/bind.js';
+import { LOGFONTW } from './structs.js';
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释；第三参透传 encoders）
+const b = (name, sig, encoders) => bind('gdi32.dll', name, sig, encoders);
+/** 创建实心画刷；失败 → 0；配对 DeleteObject
+ *  @param args_0 crColor 画刷颜色 0x00BBGGRR */
+export const CreateSolidBrush = /*@__PURE__*/ b('CreateSolidBrush', 'u32 -> <>ptr');
+/** 删除 GDI 对象（画刷/画笔/字体/位图等通用句柄，传 CreateXxx 返回的 number）；成功 → 非 0
+ *  @param args_0 hGdiObj */
+export const DeleteObject = /*@__PURE__*/ b('DeleteObject', '<>ptr -> i32');
+/** 取设备能力值
+ *  @param args_0 hdc
+ *  @param args_1 index 能力索引（LOGPIXELSX = 88，LOGPIXELSY = 90，BITSPIXEL = 12 等） */
+export const GetDeviceCaps = /*@__PURE__*/ b('GetDeviceCaps', '<HDC>ptr! i32@DeviceCap -> i32');
+/** 按 LOGFONTW 创建字体（入参位对象直传 DeepPartial：至少给 lfHeight 与 lfFaceName，其余缺省
+ *  跳过保持 0）；失败 → 0；配对 DeleteObject
+ *  @param args_0 lplf LOGFONTW 对象 */
+export const CreateFontIndirect = /*@__PURE__*/ b('CreateFontIndirectW', '<LOGFONTW>ptr -> <>ptr', { LOGFONTW });
+// ============ 内存 DC / 位图（截屏类流程：CreateCompatibleDC → SelectObject → BitBlt → GetDIBits）============
+/** 建与 hdc 兼容的内存 DC；失败 → NULL；配对 DeleteDC
+ *  @param args_0 hdc 参考 DC，NULL = 与屏幕兼容 */
+export const CreateCompatibleDC = /*@__PURE__*/ b('CreateCompatibleDC', '<HDC>ptr -> <HDC>ptr');
+/** 建与 hdc 兼容的位图（尺寸取决于 hdc 当前选中对象：内存 DC 刚建时选中 1×1 单色图，
+ *  所以要传屏幕 DC）；失败 → NULL；配对 DeleteObject
+ *  @param args_0 hdc 参考 DC（决定位图格式，须为屏幕或真实 DC）
+ *  @param args_1 cx 宽度（像素）
+ *  @param args_2 cy 高度（像素） */
+export const CreateCompatibleBitmap = /*@__PURE__*/ b('CreateCompatibleBitmap', '<HDC>ptr! i32 i32 -> <>ptr');
+/** 把 GDI 对象选进 hdc，返回被替换的旧对象（用完选回去再删除新对象）；失败 → NULL
+ *  @param args_0 hdc 目标 DC
+ *  @param args_1 h 新对象句柄（HGDIOBJ 通称） */
+export const SelectObject = /*@__PURE__*/ b('SelectObject', '<HDC>ptr! <>ptr -> <>ptr');
+/** 位块传送；成功 → 非 0
+ *  @param args_0 hdcDest 目标 DC
+ *  @param args_1 xDest 目标左上角 x
+ *  @param args_2 yDest 目标左上角 y
+ *  @param args_3 cx 传送宽度
+ *  @param args_4 cy 传送高度
+ *  @param args_5 hdcSrc 源 DC
+ *  @param args_6 x1 源起始 x
+ *  @param args_7 y1 源起始 y
+ *  @param args_8 dwRop 光栅操作码（SRCCOPY = 0x00CC0020） */
+// hdcDest 非空（!）；hdcSrc 在 PATCOPY 等特定 rop 下 C 允许 NULL，保持可空档。
+export const BitBlt = /*@__PURE__*/ b('BitBlt', '<HDC>ptr! i32 i32 i32 i32 <HDC>ptr i32 i32 u32 -> i32');
+/** 取位图像素到 lpvBits（lpbmi 为 BITMAPINFO，32bpp BI_RGB 无颜色表时头部即全部：
+ *  有颜色表的格式由调用方自备更大的缓冲）；返回成功取到的扫描行数，失败 → 0
+ *  @param args_0 hdc
+ *  @param args_1 hbm 位图句柄
+ *  @param args_2 uStartScan 起始扫描行
+ *  @param args_3 cLines 扫描行数
+ *  @param args_4 lpvBits 像素接收缓冲（ArrayBuffer）
+ *  @param args_5 lpbmi BITMAPINFO 缓冲（BITMAPINFOHEADER.encode({...}).ptr）
+ *  @param args_6 uUsage DIB_RGB_COLORS(0) */
+export const GetDIBits = /*@__PURE__*/ b('GetDIBits', '<HDC>ptr! <>ptr u32 u32 <BYTE>ptr <>ptr u32 -> i32');
+/** 取 GDI 对象信息到 lpv（hFont → LOGFONTW 等）；返回写入的字节数，失败 → 0
+ *  @param args_0 h GDI 对象句柄（字体/画笔/位图等）
+ *  @param args_1 cb 输出缓冲字节数（如 LOGFONTW.size）
+ *  @param args_2 lpv 输出缓冲（LOGFONTW.alloc() 等） */
+export const GetObject = /*@__PURE__*/ b('GetObjectW', '<>ptr i32 <BYTE>ptr -> i32');
+/** 删除内存 DC（CreateCompatibleDC 建的）；成功 → 非 0
+ *  @param args_0 hdc 要删的 DC */
+export const DeleteDC = /*@__PURE__*/ b('DeleteDC', '<HDC>ptr! -> i32');
+/** 用画刷图案填充矩形；成功 → 非 0
+ *  @param args_0 hdc 目标 DC
+ *  @param args_1 x 左上角 x
+ *  @param args_2 y 左上角 y
+ *  @param args_3 w 宽度
+ *  @param args_4 h 高度
+ *  @param args_5 rop 光栅操作码（PATCOPY 等） */
+export const PatBlt = /*@__PURE__*/ b('PatBlt', '<HDC>ptr! i32 i32 i32 i32 u32 -> i32');
+/** 把 DIB 位图画到目标 DC；返回扫描行数，失败 → 0
+ *  @param args_0 hdc 目标 DC
+ *  @param args_1 xDest 目标左上角 x
+ *  @param args_2 yDest 目标左上角 y
+ *  @param args_3 DestWidth 目标宽度
+ *  @param args_4 DestHeight 目标高度
+ *  @param args_5 xSrc 源起始 x
+ *  @param args_6 ySrc 源起始 y
+ *  @param args_7 uStartScan 起始扫描行
+ *  @param args_8 uNumScans 扫描行数
+ *  @param args_9 lpvBits 像素缓冲（ArrayBuffer）
+ *  @param args_10 lpbmi BITMAPINFO 缓冲
+ *  @param args_11 iUsage DIB_RGB_COLORS(0) */
+export const SetDIBitsToDevice = /*@__PURE__*/ b('SetDIBitsToDevice', '<HDC>ptr! i32 i32 u32 u32 i32 i32 u32 u32 <BYTE>ptr <BYTE>ptr u32 -> i32');

package/lib/windows/gdi32.ts

@@ -0,0 +1,97 @@
+// gdi32 绑定（品牌约定见 lib/windows/user32.ts 头注释）：
+//   - HDC 出入参用 <HDC>ptr（品牌指针 Ptr<'HDC'>，与 user32 的 GetDC/ReleaseDC 同型互认）
+//   - GDI 对象通用句柄（HBRUSH/HPEN/HFONT/HBITMAP 在 Win32 同为 HGDIOBJ）保持 <>ptr——
+//     异种对象互传由运行时句柄有效性判定，类型层不设品牌
+//   - 结构位按方向分流：CreateFontIndirect 的 LOGFONTW 是纯入参位，注册 encoder 收
+//     DeepPartial 对象直传（缺省字段跳过 = 保持 0 合法零值语义）
+import { bind, type CodecMap } from '../ffi/bind.js'
+import { LOGFONTW } from './structs.js'
+
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释；第三参透传 encoders）
+const b = <const S extends string, const LE extends CodecMap = {}>(name: string, sig: S, encoders?: LE) =>
+    bind('gdi32.dll', name, sig, encoders)
+
+/** 创建实心画刷；失败 → 0；配对 DeleteObject
+ *  @param args_0 crColor 画刷颜色 0x00BBGGRR */
+export const CreateSolidBrush = /*@__PURE__*/ b('CreateSolidBrush', 'u32 -> <>ptr')
+/** 删除 GDI 对象（画刷/画笔/字体/位图等通用句柄，传 CreateXxx 返回的 number）；成功 → 非 0
+ *  @param args_0 hGdiObj */
+export const DeleteObject = /*@__PURE__*/ b('DeleteObject', '<>ptr -> i32')
+/** 取设备能力值
+ *  @param args_0 hdc
+ *  @param args_1 index 能力索引（LOGPIXELSX = 88，LOGPIXELSY = 90，BITSPIXEL = 12 等） */
+export const GetDeviceCaps = /*@__PURE__*/ b('GetDeviceCaps', '<HDC>ptr! i32@DeviceCap -> i32')
+/** 按 LOGFONTW 创建字体（入参位对象直传 DeepPartial：至少给 lfHeight 与 lfFaceName，其余缺省
+ *  跳过保持 0）；失败 → 0；配对 DeleteObject
+ *  @param args_0 lplf LOGFONTW 对象 */
+export const CreateFontIndirect = /*@__PURE__*/ b('CreateFontIndirectW', '<LOGFONTW>ptr -> <>ptr', { LOGFONTW })
+
+// ============ 内存 DC / 位图（截屏类流程：CreateCompatibleDC → SelectObject → BitBlt → GetDIBits）============
+
+/** 建与 hdc 兼容的内存 DC；失败 → NULL；配对 DeleteDC
+ *  @param args_0 hdc 参考 DC，NULL = 与屏幕兼容 */
+export const CreateCompatibleDC = /*@__PURE__*/ b('CreateCompatibleDC', '<HDC>ptr -> <HDC>ptr')
+/** 建与 hdc 兼容的位图（尺寸取决于 hdc 当前选中对象：内存 DC 刚建时选中 1×1 单色图，
+ *  所以要传屏幕 DC）；失败 → NULL；配对 DeleteObject
+ *  @param args_0 hdc 参考 DC（决定位图格式，须为屏幕或真实 DC）
+ *  @param args_1 cx 宽度（像素）
+ *  @param args_2 cy 高度（像素） */
+export const CreateCompatibleBitmap = /*@__PURE__*/ b('CreateCompatibleBitmap', '<HDC>ptr! i32 i32 -> <>ptr')
+/** 把 GDI 对象选进 hdc，返回被替换的旧对象（用完选回去再删除新对象）；失败 → NULL
+ *  @param args_0 hdc 目标 DC
+ *  @param args_1 h 新对象句柄（HGDIOBJ 通称） */
+export const SelectObject = /*@__PURE__*/ b('SelectObject', '<HDC>ptr! <>ptr -> <>ptr')
+/** 位块传送；成功 → 非 0
+ *  @param args_0 hdcDest 目标 DC
+ *  @param args_1 xDest 目标左上角 x
+ *  @param args_2 yDest 目标左上角 y
+ *  @param args_3 cx 传送宽度
+ *  @param args_4 cy 传送高度
+ *  @param args_5 hdcSrc 源 DC
+ *  @param args_6 x1 源起始 x
+ *  @param args_7 y1 源起始 y
+ *  @param args_8 dwRop 光栅操作码（SRCCOPY = 0x00CC0020） */
+// hdcDest 非空（!）；hdcSrc 在 PATCOPY 等特定 rop 下 C 允许 NULL，保持可空档。
+export const BitBlt = /*@__PURE__*/ b('BitBlt', '<HDC>ptr! i32 i32 i32 i32 <HDC>ptr i32 i32 u32 -> i32')
+/** 取位图像素到 lpvBits（lpbmi 为 BITMAPINFO，32bpp BI_RGB 无颜色表时头部即全部：
+ *  有颜色表的格式由调用方自备更大的缓冲）；返回成功取到的扫描行数，失败 → 0
+ *  @param args_0 hdc
+ *  @param args_1 hbm 位图句柄
+ *  @param args_2 uStartScan 起始扫描行
+ *  @param args_3 cLines 扫描行数
+ *  @param args_4 lpvBits 像素接收缓冲（ArrayBuffer）
+ *  @param args_5 lpbmi BITMAPINFO 缓冲（BITMAPINFOHEADER.encode({...}).ptr）
+ *  @param args_6 uUsage DIB_RGB_COLORS(0) */
+export const GetDIBits = /*@__PURE__*/ b('GetDIBits', '<HDC>ptr! <>ptr u32 u32 <BYTE>ptr <>ptr u32 -> i32')
+/** 取 GDI 对象信息到 lpv（hFont → LOGFONTW 等）；返回写入的字节数，失败 → 0
+ *  @param args_0 h GDI 对象句柄（字体/画笔/位图等）
+ *  @param args_1 cb 输出缓冲字节数（如 LOGFONTW.size）
+ *  @param args_2 lpv 输出缓冲（LOGFONTW.alloc() 等） */
+export const GetObject = /*@__PURE__*/ b('GetObjectW', '<>ptr i32 <BYTE>ptr -> i32')
+/** 删除内存 DC（CreateCompatibleDC 建的）；成功 → 非 0
+ *  @param args_0 hdc 要删的 DC */
+export const DeleteDC = /*@__PURE__*/ b('DeleteDC', '<HDC>ptr! -> i32')
+
+/** 用画刷图案填充矩形；成功 → 非 0
+ *  @param args_0 hdc 目标 DC
+ *  @param args_1 x 左上角 x
+ *  @param args_2 y 左上角 y
+ *  @param args_3 w 宽度
+ *  @param args_4 h 高度
+ *  @param args_5 rop 光栅操作码（PATCOPY 等） */
+export const PatBlt = /*@__PURE__*/ b('PatBlt', '<HDC>ptr! i32 i32 i32 i32 u32 -> i32')
+/** 把 DIB 位图画到目标 DC；返回扫描行数，失败 → 0
+ *  @param args_0 hdc 目标 DC
+ *  @param args_1 xDest 目标左上角 x
+ *  @param args_2 yDest 目标左上角 y
+ *  @param args_3 DestWidth 目标宽度
+ *  @param args_4 DestHeight 目标高度
+ *  @param args_5 xSrc 源起始 x
+ *  @param args_6 ySrc 源起始 y
+ *  @param args_7 uStartScan 起始扫描行
+ *  @param args_8 uNumScans 扫描行数
+ *  @param args_9 lpvBits 像素缓冲（ArrayBuffer）
+ *  @param args_10 lpbmi BITMAPINFO 缓冲
+ *  @param args_11 iUsage DIB_RGB_COLORS(0) */
+export const SetDIBitsToDevice = /*@__PURE__*/ b('SetDIBitsToDevice',
+    '<HDC>ptr! i32 i32 u32 u32 i32 i32 u32 u32 <BYTE>ptr <BYTE>ptr u32 -> i32')

package/lib/windows/kernel32.js

@@ -0,0 +1,66 @@
+// kernel32.dll 绑定（进程 / 管道 / 系统信息子集；品牌约定见 lib/windows/user32.ts 头注释）：
+//   - 内核对象句柄按用途分品牌：管道/文件 <HFILE>ptr、进程 <HPROCESS>ptr、线程
+//     <HTHREAD>ptr（CreatePipe 的 HANDLE* 出参槽是缓冲地址非句柄值，仍 <>ptr）；
+//     CloseHandle/WaitForSingleObject 全家族位保持 <>ptr 收宽（品牌 number 子类型可
+//     直传），异种对象深层互传由运行时句柄有效性判定兜底
+//   - 结构位按方向分流（结构定义见 ./structs.ts，布局随进程位宽，struct 按 os.arch 推）：
+//       STARTUPINFOW 纯入参位注册 encoder → DeepPartial 对象直传；
+//       PROCESS_INFORMATION 出参位不注册 → 只收 def 分配的 .ptr，读回走 decode
+//   - 缓冲区 / DWORD 出参位用 <BYTE>ptr 直接收 PtrArrayBuffer（DataView / TypedArray 原地读回）
+//   - 空指针位（lpApplicationName / lpProcessAttributes 等）传 NULL（来自 ../ffi/ctype.js）；
+//     传 JS null/undefined 会在参数槽 fail-loud
+//   - 返回值 0 保真（C→JS 不做 0→null）；BOOL 型返回 i32，成功 → 非 0，失败 → 0（原因见 GetLastError）
+import { bind } from '../ffi/bind.js';
+import { STARTUPINFOW } from './structs.js';
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = (name, sig, encoders) => bind('kernel32.dll', name, sig, encoders);
+// ============ 管道 / 进程 ============
+/** 建匿名管道；成功 → 非 0
+ *  @param args_0 hReadPipe 出参槽（读端句柄写回，<>ptr 缓冲地址）
+ *  @param args_1 hWritePipe 出参槽（写端句柄写回，<>ptr 缓冲地址）
+ *  @param args_2 lpPipeAttributes 安全属性，传 NULL
+ *  @param args_3 nSize 管道缓冲字节数，0 = 系统默认 */
+export const CreatePipe = /*@__PURE__*/ b('CreatePipe', '<>ptr <>ptr <>ptr u32 -> i32');
+/** 设句柄标志；成功 → 非 0
+ *  @param args_0 hHandle 文件/管道句柄
+ *  @param args_1 dwMask 要改的标志位掩码（HANDLE_FLAG_*）
+ *  @param args_2 dwFlags 标志新值（继承 = 1，不继承 = 0） */
+export const SetHandleInformation = /*@__PURE__*/ b('SetHandleInformation', '<HFILE>ptr! u32 u32 -> i32');
+/** 建进程；成功 → 非 0
+ *  @param args_0 lpApplicationName 可执行文件路径 string 或 NULL
+ *  @param args_1 lpCommandLine 命令行 string（含参数）或 NULL
+ *  @param args_2 lpProcessAttributes 进程安全属性，传 NULL
+ *  @param args_3 lpThreadAttributes 线程安全属性，传 NULL
+ *  @param args_4 bInheritHandles 非 0 继承父进程句柄
+ *  @param args_5 dwCreationFlags 创建标志（CREATE_NO_WINDOW = 0x08000000 等）
+ *  @param args_6 lpEnvironment 环境块，传 NULL 继承当前环境
+ *  @param args_7 lpCurrentDirectory 工作目录 string 或 NULL
+ *  @param args_8 lpStartupInfo STARTUPINFOW 对象（cb 必填）
+ *  @param args_9 lpProcessInformation 出参槽，传 PROCESS_INFORMATION.alloc().ptr */
+export const CreateProcess = /*@__PURE__*/ b('CreateProcessW', '<WCHAR>ptr <WCHAR>ptr <>ptr <>ptr i32 u32 <>ptr <WCHAR>ptr <STARTUPINFOW>ptr <PROCESS_INFORMATION>ptr -> i32', { STARTUPINFOW });
+/** 等内核对象就绪；返回 WAIT_* 码
+ *  @param args_0 hHandle 内核对象句柄
+ *  @param args_1 dwMilliseconds 超时毫秒，0xffffffff = 无限等 */
+export const WaitForSingleObject = /*@__PURE__*/ b('WaitForSingleObject', '<>ptr u32 -> u32');
+/** 取进程退出码（带符号读）；成功 → 非 0
+ *  @param args_0 hProcess 进程句柄
+ *  @param args_1 lpExitCode 出参槽，传 Int32Array(1).buffer 读回退出码 */
+export const GetExitCodeProcess = /*@__PURE__*/ b('GetExitCodeProcess', '<HPROCESS>ptr! <BYTE>ptr -> i32');
+/** 关闭内核对象句柄；成功 → 非 0
+ *  @param args_0 hObject 任意内核对象 */
+export const CloseHandle = /*@__PURE__*/ b('CloseHandle', '<>ptr -> i32');
+// ============ 文件 I/O ============
+/** 同步读文件 / 管道；成功 → 非 0，管道写端全部关闭后读返回 0（EOF）
+ *  @param args_0 hFile 文件/管道句柄
+ *  @param args_1 lpBuffer 接收缓冲（<BYTE>ptr，PtrArrayBuffer 原地读回）
+ *  @param args_2 nNumberOfBytesToRead 请求读取的字节数
+ *  @param args_3 lpNumberOfBytesRead 出参槽，传 Uint32Array(1).buffer 读实际字节数
+ *  @param args_4 lpOverlapped 重叠结构，传 NULL（同步读） */
+export const ReadFile = /*@__PURE__*/ b('ReadFile', '<HFILE>ptr! <BYTE>ptr u32 <BYTE>ptr <>ptr -> i32');
+// ============ 系统 / 错误 ============
+/** 取调用线程最近一次 Win32 错误码 */
+export const GetLastError = /*@__PURE__*/ b('GetLastError', ' -> u32');
+/** 取 System32 目录路径（宽字符）；返回写入的字符数（不含 NUL，0 失败）
+ *  @param args_0 lpBuffer 接收缓冲，传 WCHAR.alloc(n)
+ *  @param args_1 uSize 缓冲容量（WCHAR 个数，含 NUL 余量） */
+export const GetSystemDirectory = /*@__PURE__*/ b('GetSystemDirectoryW', '<BYTE>ptr u32 -> u32');

package/lib/windows/kernel32.ts

@@ -0,0 +1,76 @@
+// kernel32.dll 绑定（进程 / 管道 / 系统信息子集；品牌约定见 lib/windows/user32.ts 头注释）：
+//   - 内核对象句柄按用途分品牌：管道/文件 <HFILE>ptr、进程 <HPROCESS>ptr、线程
+//     <HTHREAD>ptr（CreatePipe 的 HANDLE* 出参槽是缓冲地址非句柄值，仍 <>ptr）；
+//     CloseHandle/WaitForSingleObject 全家族位保持 <>ptr 收宽（品牌 number 子类型可
+//     直传），异种对象深层互传由运行时句柄有效性判定兜底
+//   - 结构位按方向分流（结构定义见 ./structs.ts，布局随进程位宽，struct 按 os.arch 推）：
+//       STARTUPINFOW 纯入参位注册 encoder → DeepPartial 对象直传；
+//       PROCESS_INFORMATION 出参位不注册 → 只收 def 分配的 .ptr，读回走 decode
+//   - 缓冲区 / DWORD 出参位用 <BYTE>ptr 直接收 PtrArrayBuffer（DataView / TypedArray 原地读回）
+//   - 空指针位（lpApplicationName / lpProcessAttributes 等）传 NULL（来自 ../ffi/ctype.js）；
+//     传 JS null/undefined 会在参数槽 fail-loud
+//   - 返回值 0 保真（C→JS 不做 0→null）；BOOL 型返回 i32，成功 → 非 0，失败 → 0（原因见 GetLastError）
+import { bind, type CodecMap } from '../ffi/bind.js'
+import { STARTUPINFOW } from './structs.js'
+
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = <const S extends string, const LE extends CodecMap = {}>(name: string, sig: S, encoders?: LE) =>
+    bind('kernel32.dll', name, sig, encoders)
+
+// ============ 管道 / 进程 ============
+
+/** 建匿名管道；成功 → 非 0
+ *  @param args_0 hReadPipe 出参槽（读端句柄写回，<>ptr 缓冲地址）
+ *  @param args_1 hWritePipe 出参槽（写端句柄写回，<>ptr 缓冲地址）
+ *  @param args_2 lpPipeAttributes 安全属性，传 NULL
+ *  @param args_3 nSize 管道缓冲字节数，0 = 系统默认 */
+export const CreatePipe = /*@__PURE__*/ b('CreatePipe', '<>ptr <>ptr <>ptr u32 -> i32')
+/** 设句柄标志；成功 → 非 0
+ *  @param args_0 hHandle 文件/管道句柄
+ *  @param args_1 dwMask 要改的标志位掩码（HANDLE_FLAG_*）
+ *  @param args_2 dwFlags 标志新值（继承 = 1，不继承 = 0） */
+export const SetHandleInformation = /*@__PURE__*/ b('SetHandleInformation', '<HFILE>ptr! u32 u32 -> i32')
+/** 建进程；成功 → 非 0
+ *  @param args_0 lpApplicationName 可执行文件路径 string 或 NULL
+ *  @param args_1 lpCommandLine 命令行 string（含参数）或 NULL
+ *  @param args_2 lpProcessAttributes 进程安全属性，传 NULL
+ *  @param args_3 lpThreadAttributes 线程安全属性，传 NULL
+ *  @param args_4 bInheritHandles 非 0 继承父进程句柄
+ *  @param args_5 dwCreationFlags 创建标志（CREATE_NO_WINDOW = 0x08000000 等）
+ *  @param args_6 lpEnvironment 环境块，传 NULL 继承当前环境
+ *  @param args_7 lpCurrentDirectory 工作目录 string 或 NULL
+ *  @param args_8 lpStartupInfo STARTUPINFOW 对象（cb 必填）
+ *  @param args_9 lpProcessInformation 出参槽，传 PROCESS_INFORMATION.alloc().ptr */
+export const CreateProcess = /*@__PURE__*/ b('CreateProcessW',
+    '<WCHAR>ptr <WCHAR>ptr <>ptr <>ptr i32 u32 <>ptr <WCHAR>ptr <STARTUPINFOW>ptr <PROCESS_INFORMATION>ptr -> i32',
+    { STARTUPINFOW })
+/** 等内核对象就绪；返回 WAIT_* 码
+ *  @param args_0 hHandle 内核对象句柄
+ *  @param args_1 dwMilliseconds 超时毫秒，0xffffffff = 无限等 */
+export const WaitForSingleObject = /*@__PURE__*/ b('WaitForSingleObject', '<>ptr u32 -> u32')
+/** 取进程退出码（带符号读）；成功 → 非 0
+ *  @param args_0 hProcess 进程句柄
+ *  @param args_1 lpExitCode 出参槽，传 Int32Array(1).buffer 读回退出码 */
+export const GetExitCodeProcess = /*@__PURE__*/ b('GetExitCodeProcess', '<HPROCESS>ptr! <BYTE>ptr -> i32')
+/** 关闭内核对象句柄；成功 → 非 0
+ *  @param args_0 hObject 任意内核对象 */
+export const CloseHandle = /*@__PURE__*/ b('CloseHandle', '<>ptr -> i32')
+
+// ============ 文件 I/O ============
+
+/** 同步读文件 / 管道；成功 → 非 0，管道写端全部关闭后读返回 0（EOF）
+ *  @param args_0 hFile 文件/管道句柄
+ *  @param args_1 lpBuffer 接收缓冲（<BYTE>ptr，PtrArrayBuffer 原地读回）
+ *  @param args_2 nNumberOfBytesToRead 请求读取的字节数
+ *  @param args_3 lpNumberOfBytesRead 出参槽，传 Uint32Array(1).buffer 读实际字节数
+ *  @param args_4 lpOverlapped 重叠结构，传 NULL（同步读） */
+export const ReadFile = /*@__PURE__*/ b('ReadFile', '<HFILE>ptr! <BYTE>ptr u32 <BYTE>ptr <>ptr -> i32')
+
+// ============ 系统 / 错误 ============
+
+/** 取调用线程最近一次 Win32 错误码 */
+export const GetLastError = /*@__PURE__*/ b('GetLastError', ' -> u32')
+/** 取 System32 目录路径（宽字符）；返回写入的字符数（不含 NUL，0 失败）
+ *  @param args_0 lpBuffer 接收缓冲，传 WCHAR.alloc(n)
+ *  @param args_1 uSize 缓冲容量（WCHAR 个数，含 NUL 余量） */
+export const GetSystemDirectory = /*@__PURE__*/ b('GetSystemDirectoryW', '<BYTE>ptr u32 -> u32')

package/lib/windows/ntdll.js

@@ -0,0 +1,8 @@
+// ntdll 绑定（仅 RtlGetVersion——绕过 GetVersionEx 的兼容性谎言取真实版本）
+import { bind } from '../ffi/bind.js';
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = (name, sig) => bind('ntdll.dll', name, sig);
+/** 取真实 OS 版本（成功 → 0）；缓冲必须用 OSVERSIONINFO_148（148B 特制布局，
+ *  标准 OSVERSIONINFOW 会越界写坏调用方堆，见 structs.ts）
+ *  @param args_0 lpVersionInformation OSVERSIONINFO_148.encode(...).ptr 出参缓冲 */
+export const RtlGetVersion = /*@__PURE__*/ b('RtlGetVersion', '<BYTE>ptr -> i32');

package/lib/windows/ntdll.ts

@@ -0,0 +1,10 @@
+// ntdll 绑定（仅 RtlGetVersion——绕过 GetVersionEx 的兼容性谎言取真实版本）
+import { bind } from '../ffi/bind.js'
+
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = <const S extends string>(name: string, sig: S) => bind('ntdll.dll', name, sig)
+
+/** 取真实 OS 版本（成功 → 0）；缓冲必须用 OSVERSIONINFO_148（148B 特制布局，
+ *  标准 OSVERSIONINFOW 会越界写坏调用方堆，见 structs.ts）
+ *  @param args_0 lpVersionInformation OSVERSIONINFO_148.encode(...).ptr 出参缓冲 */
+export const RtlGetVersion = /*@__PURE__*/ b('RtlGetVersion', '<BYTE>ptr -> i32')

package/lib/windows/ole32.js

@@ -0,0 +1,7 @@
+// ole32 绑定（COM 内存管理；仅 CoTaskMemFree——shell 对话框返回的 PIDL 需它释放）
+import { bind } from '../ffi/bind.js';
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = (name, sig) => bind('ole32.dll', name, sig);
+/** 释放 CoTaskMemAlloc 分配的内存（SHBrowseForFolder 返回的 PIDL 等）；无返回值
+ *  @param args_0 pv CoTaskMem 分配的指针（0/NULL 安全） */
+export const CoTaskMemFree = /*@__PURE__*/ b('CoTaskMemFree', '<>ptr -> void');

package/lib/windows/ole32.ts

@@ -0,0 +1,9 @@
+// ole32 绑定（COM 内存管理；仅 CoTaskMemFree——shell 对话框返回的 PIDL 需它释放）
+import { bind } from '../ffi/bind.js'
+
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = <const S extends string>(name: string, sig: S) => bind('ole32.dll', name, sig)
+
+/** 释放 CoTaskMemAlloc 分配的内存（SHBrowseForFolder 返回的 PIDL 等）；无返回值
+ *  @param args_0 pv CoTaskMem 分配的指针（0/NULL 安全） */
+export const CoTaskMemFree = /*@__PURE__*/ b('CoTaskMemFree', '<>ptr -> void')

package/lib/windows/shell32.js

@@ -0,0 +1,11 @@
+// shell32 绑定（shell 对话框 / PIDL→路径）
+import { bind } from '../ffi/bind.js';
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = (name, sig) => bind('shell32.dll', name, sig);
+/** 文件夹浏览对话框；返回 PIDL，取消 → 0；PIDL 用 ole32.CoTaskMemFree 释放
+ *  @param args_0 pbi BROWSEINFOW.encode(...).ptr（见 structs.ts） */
+export const SHBrowseForFolder = /*@__PURE__*/ b('SHBrowseForFolderW', '<BYTE>ptr -> <>ptr');
+/** PIDL → 文件系统全路径；PIDL 在文件系统中 → 非 0，否则 0（缓冲内容未定义）
+ *  @param args_0 pidl SHBrowseForFolder 等返回的 PIDL
+ *  @param args_1 pszPath 出参缓冲，WCHAR.alloc(260)（MAX_PATH=260）、WCHAR.decode 读回 */
+export const SHGetPathFromIDList = /*@__PURE__*/ b('SHGetPathFromIDListW', '<>ptr <BYTE>ptr -> u32');

package/lib/windows/shell32.ts

@@ -0,0 +1,14 @@
+// shell32 绑定（shell 对话框 / PIDL→路径）
+import { bind } from '../ffi/bind.js'
+
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = <const S extends string>(name: string, sig: S) => bind('shell32.dll', name, sig)
+
+/** 文件夹浏览对话框；返回 PIDL，取消 → 0；PIDL 用 ole32.CoTaskMemFree 释放
+ *  @param args_0 pbi BROWSEINFOW.encode(...).ptr（见 structs.ts） */
+export const SHBrowseForFolder = /*@__PURE__*/ b('SHBrowseForFolderW', '<BYTE>ptr -> <>ptr')
+
+/** PIDL → 文件系统全路径；PIDL 在文件系统中 → 非 0，否则 0（缓冲内容未定义）
+ *  @param args_0 pidl SHBrowseForFolder 等返回的 PIDL
+ *  @param args_1 pszPath 出参缓冲，WCHAR.alloc(260)（MAX_PATH=260）、WCHAR.decode 读回 */
+export const SHGetPathFromIDList = /*@__PURE__*/ b('SHGetPathFromIDListW', '<>ptr <BYTE>ptr -> u32')