quickwin 2.0.0 → 2.1.1

package/lib/ffi/struct.ts

@@ -214,13 +214,18 @@ export type StructDef<T extends { '#': 'struct' | 'union' }, N extends string =
     // 数组元素含必填 ⇒ 该键必给，值后序合成到内层）。带 buf = 写入调用方既有
     // PtrArrayBuffer（返回其本身，供链式读回）——encode 出口一律 PAB，裸 ArrayBuffer
     // 不出 codec（与 CodecMap 同约束）。动态调用方无参 encode 由运行时 throw 兜底。
-    alloc(): PtrArrayBuffer<N>
+    /** n（默认 1）= 按本布局 size 步长连续分配 n 个元素的零填充缓冲（出参数组场景，
+     *  品牌 .ptr 直接喂 <N>ptr 位）。n < 1 / 非整数运行时 throw ——
+     *  任何路径都不产出 PAB(0)（其 .ptr 是"非 0 的 1 字节堆指针"，会骗过 C 的 NULL
+     *  防御；空位语义由调用方显式传 NULL）。 */
+    alloc(n?: number): PtrArrayBuffer<N>
     encode(v: EncodeIn<T>): PtrArrayBuffer<N>
-    // 带 buf = 写入调用方既有 PtrArrayBuffer（复用/预分配形态，返回其本身供链式读回）。
-    // 刻意没有 offset —— 与 decode 同理（bind.ts CodecMap 注释）：PAB 的 .ptr 恒指向起点，
-    // 顶层再收 offset 只会掩盖"写错位置"且返回值 .ptr 对不上写入点；嵌套偏移由布局字段
-    // （doEncode 的 base）承担。
-    encode(v: EncodeIn<T>, buf: PtrArrayBuffer<any>): PtrArrayBuffer<any>
+    // 带 buf = 写入调用方既有 PtrArrayBuffer（复用/预分配形态）；带 offset = 写入点
+    // 相对 buf 起点的字节偏移（数组物化/自定义内存管理的底层写入原语，内部即 doEncode
+    // 的 base）。返回值仍是 buf 本身 —— offset 形态下其 .ptr 对不上写入点，写入点地址
+    // = buf.ptr + offset（自算术，品牌随算术丢失同 CreatePipe 先例）；越界写由 DataView
+    // RangeError 兜底，无需额外校验。
+    encode(v: EncodeIn<T>, buf: PtrArrayBuffer<any>, offset?: number): PtrArrayBuffer<any>
     offsetOf(name: string): number
 }
 
@@ -592,27 +597,31 @@ function createStruct(t: C_Struct | C_Union): any {
         size,
         structAlign: maxEffectiveAlign,
         decode: (p: ArrayBuffer | number) => {
-            // number = native 拥有的品牌指针（Codec 的 decode(p) 形态）：按布局 size
-            // 逐字节拷进临时 buffer 再解码；ArrayBuffer = 调用方持有的 out buffer 直读。
+            // number = native 拥有的品牌指针（Codec 的 decode(p) 形态）：readBytes 一次
+            // native memcpy 拷出 size 字节再解码（替代逐字节 readByte 循环，N 次跨语言
+            // 调用降为 1 次）；ArrayBuffer = 调用方持有的 out buffer 直读。
             // 顶层不收 offset——out 参数恒从起点读，嵌套偏移由字段布局（doDecode 的 base）承担。
-            if (typeof p === 'number') {
-                const buf = new ArrayBuffer(size)
-                const u8 = new Uint8Array(buf)
-                for (let i = 0; i < size; i++) u8[i] = ffi.readByte(p + i)
-                return doDecode(new DataView(buf), 0, fields)
-            }
+            if (typeof p === 'number')
+                return doDecode(new DataView(ffi.readBytes(p, size)), 0, fields)
             return doDecode(new DataView(p), 0, fields)
         },
-        alloc: (() => new PtrArrayBuffer(size)) as StructDef<any, any>['alloc'],
-        encode: ((v: any, buf?: PtrArrayBuffer<any>) => {
+        alloc: ((n?: number) => {
+            // fail-loud：n < 1 / 非整数绝不静默产出 PAB(0)（其 .ptr 是"非 0 的 1 字节
+            // 堆指针"，会骗过 C 的 NULL 防御）—— 空位语义由调用方显式传 NULL。
+            if (n !== undefined && (!Number.isInteger(n) || n < 1))
+                throw new Error(`ffi-struct: alloc(n) requires an integer n >= 1 ` +
+                    `(PAB(0) never escapes — pass NULL for an empty pointer position)`)
+            return new PtrArrayBuffer(size * (n ?? 1))
+        }) as StructDef<any, any>['alloc'],
+        encode: ((v: any, buf?: PtrArrayBuffer<any>, offset?: number) => {
             // fail-loud：无参 = 分配语义，走 alloc()；这里绝不静默零填充 —— 类型层由
-            // EncodeIn 拦 '!' 字段省略，动态/JS 调用方由本 throw 兜住。顶层不收 offset
-            // （与 decode 对齐，见 StructDef 注释），恒从 buffer 起点写。
+            // EncodeIn 拦 '!' 字段省略，动态/JS 调用方由本 throw 兜住。顶层默认从起点写，
+            // offset 显式给写入点（数组物化原语，见接口注释）。
             if (v === undefined || v === null)
                 throw new Error(`ffi-struct: encode(v) requires an argument; ` +
                     `use alloc() for a zeroed out-param slot`)
             const out = buf ?? new PtrArrayBuffer(size)
-            doEncode(new DataView(out), 0, fields, v)
+            doEncode(new DataView(out), offset ?? 0, fields, v)
             return out
         }) as StructDef<any, any>['encode'],
         offsetOf: (name: string) => {
@@ -640,6 +649,86 @@ function buildDecl(kind: 'struct' | 'union', member: Record<string, unknown>, pa
     return decl as unknown as C_Struct | C_Union
 }
 
+/** decode 双态重载：有 byteLength 的 buffer 形 count 可缺省（自算）；裸地址无长度
+ *  信息，count 必填（类型层拦，缺省调用编译红）。 */
+type StructArrayDecode<T extends { '#': 'struct' | 'union' }, N extends string> = {
+    (p: ArrayBuffer, count?: number): ShapeOfC<T>[]
+    (p: Ptr<N>, count: number): ShapeOfC<T>[]
+}
+
+/** 结构/联合体的数组编解码对工厂：返回 `{ encode, decode }`。
+ *  encode —— 单值 encoder 的数组版：收元素数组 → 按本布局 size 步长紧密排列
+ *  （stride = size，已含尾部对齐 padding），返回带品牌 .ptr 的 PAB —— 与 C 的
+ *  `const T apt[]` 同构。值域刻意收普通数组（调用方持有的 `const pts = [...]` 变量
+ *  直传，非空元组会拒之）；[] / 非数组 / 单对象运行时 throw —— 任何路径都不产出
+ *  PAB(0)（其 .ptr 是"非 0 的 1 字节堆指针"，会骗过 C 的 NULL 防御；空位语义由
+ *  调用方显式传 NULL）。注册进 bind 的 encoders 表（`{ POINT: structArray(POINT) }`）
+ *  后，普通 `<POINT>ptr` 位的值域即元素数组（值域由 encoder 推导，token/引擎/类型层
+ *  零数组概念）；直接调用 `.encode(els).ptr` 亦可。
+ *  decode —— 出参数组读回（与 def.decode 的 ArrayBuffer/地址双态对称）：
+ *  - buffer 形（含 PAB）：count? 缺省自算 byteLength/size —— 要求整数倍，% ≠ 0
+ *    throw（混合缓冲如 EnumPrinters 的"结构 + 尾部字符串"必须显式 count）；显式
+ *    count 校验 count*size ≤ byteLength（写错 count → 越界读的防线，buf 形可校才
+ *    校；不验品牌，与 def.decode 的 buffer 形同款）。
+ *  - 裸地址形：count 必填（地址无长度信息），逐字节拷读（def.decode 的 number 形
+ *    同机制）；长度不可校 → 信任 C 的 count。
+ *  - count = 0 → []（读 0 个真空安全，与 encode 禁空的 PAB(0) 理由刻意不对称）。
+ *  实现：encode 走纯公开 API（alloc + encode offset 循环）；decode 在本文件内复用
+ *  computeStructLayout/doDecode。 */
+export function structArray<T extends { '#': 'struct' | 'union' }, N extends string = ''>(
+    def: StructDef<T, N>,
+) {
+    const { fields, size } = computeStructLayout(def.__struct)
+    const readN = (dv: DataView, n: number): unknown[] => {
+        const out: unknown[] = []
+        for (let i = 0; i < n; i++) out.push(doDecode(dv, i * size, fields))
+        return out
+    }
+    return {
+        encode: (els: readonly EncodeIn<T>[]): PtrArrayBuffer<N> => {
+            if (!Array.isArray(els) || els.length === 0)
+                throw new Error(`ffi-struct: structArray(def).encode(els) requires a ` +
+                    `non-empty element array (pass NULL for an empty pointer position)`)
+            const out = def.alloc(els.length)
+            for (let i = 0; i < els.length; i++) def.encode(els[i], out, i * def.size)
+            return out
+        },
+        decode: ((p: ArrayBuffer | number, count?: number): unknown[] => {
+            // fail-loud 校验矩阵（见 JSDoc）：显式 count 信调用方但拦越界；缺省只对
+            // 有 byteLength 的 buffer 形自算；裸地址必带 count。
+            if (count !== undefined && (!Number.isInteger(count) || count < 0))
+                throw new Error(`ffi-struct: structArray.decode(p, count) requires a ` +
+                    `non-negative integer count, got ${count}`)
+            if (typeof p === 'number') {
+                if (count === undefined)
+                    throw new Error(`ffi-struct: structArray.decode(address, count) ` +
+                        `requires an explicit count (a bare address carries no length)`)
+                if (count === 0) return []
+                // readBytes 一次 native memcpy 拷出整段再解码（def.decode 的 number 形同机制）。
+                return readN(new DataView(ffi.readBytes(p, count * size)), count)
+            }
+            let n: number
+            if (count !== undefined) {
+                n = count
+                // 越界防线：写错 count 是越界读的唯一入口，buf 形有 byteLength 就校死。
+                if (n * size > p.byteLength)
+                    throw new Error(`ffi-struct: structArray.decode: count ${n} × ` +
+                        `size ${size} = ${n * size} exceeds buffer byteLength ${p.byteLength}`)
+            } else {
+                // 自算形态：byteLength 必须是纯元素序列（size = 0 的退化布局同样落此
+                // throw —— 0 % 0 = NaN），混合缓冲显式传 count。
+                if (p.byteLength % size !== 0)
+                    throw new Error(`ffi-struct: structArray.decode: byteLength ` +
+                        `${p.byteLength} is not a multiple of size ${size} ` +
+                        `(mixed buffer? pass count explicitly)`)
+                n = p.byteLength / size
+            }
+            if (n === 0) return []
+            return readN(new DataView(p), n)
+        }) as StructArrayDecode<T, N>,
+    }
+}
+
 /** 平铺字段表定义结构体（token/`X[n]`/`unit:width`/`'#'` 声明均可，见 ctype.ts §4）。
  *  给 name 则 alloc().ptr 与 decode 入参带 Ptr<name> 品牌。 */
 type StructOf<M, N extends string = ''> = StructDef<{ '#': 'struct', '#pack'?: number } & M, N>

package/lib/react-qw/components/ListView.js

@@ -47,6 +47,7 @@ function getCellFont(hwnd, style) {
     const cur = gui.SendMessage(hwnd, 49 /* gui.WmMsg.GETFONT */, 0, 0);
     if (cur) {
         const lf = LOGFONTW.alloc();
+        // GETFONT 的 LRESULT 断言为 HFONT（gdi32 <HGDIOBJ>ptr 位）
         if (!GetObject(cur, LOGFONTW.size, lf))
             return null;
         base = LOGFONTW.decode(lf);

package/lib/react-qw/components/PathPicker.js

@@ -23,7 +23,7 @@ function openFileDialog(owner, filter, title, multiple) {
         lpstrTitle: titleWide?.ptr ?? 0,
         Flags: flags,
     });
-    const ret = GetOpenFileName(ofn);
+    const ret = GetOpenFileName(ofn.ptr);
     if (!ret)
         return null;
     if (!multiple) {
@@ -42,7 +42,7 @@ function openFolderDialog(owner, title) {
         lpszTitle: titleWide?.ptr ?? 0,
         ulFlags: 0x00000041,
     });
-    const pidl = SHBrowseForFolder(bi);
+    const pidl = SHBrowseForFolder(bi.ptr);
     if (!pidl)
         return null;
     const pathBuf = WCHAR.alloc(260);

package/lib/react-qw/index.js

@@ -50,7 +50,7 @@ export function createRoot(container) {
     else {
         hwnd = container;
     }
-    const root = reconciler.createContainer(hwnd, 0, null, false, null, '', noop, noop, noop, noop);
+    const root = reconciler.createContainer(hwnd, 0, null, false, null, '', (error, info) => console.log('[React uncaught]', error, error.stack, info.componentStack), (error, info) => console.log('[React caught]', error, error.stack, info.componentStack), (error, info) => console.log('[React recoverable]', error, error.stack, info.componentStack), noop);
     const rootInst = { hwnd, type: '_root', props: { type: '_root', style: { flexDirection: 'column', alignItems: 'stretch' } }, children: [] };
     instancesByHwnd.set(hwnd, rootInst);
     if (typeof container === 'object')

package/lib/react-qw/index.ts

@@ -64,7 +64,10 @@ export function createRoot(container: gui.HWND | RootWindowConfig) {
   }
   const root = reconciler.createContainer(
     hwnd, 0, null, false, null, '',
-    noop, noop, noop, noop,
+    (error, info) => console.log('[React uncaught]', error, error.stack, info.componentStack),
+    (error, info) => console.log('[React caught]', error, error.stack, info.componentStack),
+    (error, info) => console.log('[React recoverable]', error, error.stack, info.componentStack),
+    noop,
   )
   const rootInst: Instance = { hwnd, type: '_root', props: { type: '_root', style: { flexDirection: 'column', alignItems: 'stretch' } }, children: [] }
   instancesByHwnd.set(hwnd, rootInst)

package/lib/text-measure.js

@@ -1,3 +1,4 @@
+import { NULL } from './ffi/ctype.js';
 import * as gui from 'gui';
 import { DrawText, GetDC, ReleaseDC } from './windows/user32.js';
 import { SelectObject } from './windows/gdi32.js';
@@ -21,8 +22,9 @@ export function measureTextForHwnd(hwnd, text) {
     const hdc = GetDC(hwnd);
     if (!hdc)
         return { width: 0, height: 0 };
+    // SendMessage 返回 LRESULT 裸数；GETFONT 语义为 HFONT——断言进 GDI 对象品牌链
     const hFont = gui.SendMessage(hwnd, 49 /* gui.WmMsg.GETFONT */, 0, 0);
-    const oldFont = hFont ? SelectObject(hdc, hFont) : 0;
+    const oldFont = hFont ? SelectObject(hdc, hFont) : NULL;
     const result = measureText(hdc, text, 0);
     if (hFont)
         SelectObject(hdc, oldFont);

package/lib/text-measure.ts

@@ -1,4 +1,4 @@
-import type { Ptr } from './ffi/ctype.js'
+import { NULL, type Ptr } from './ffi/ctype.js'
 import * as gui from 'gui'
 import { DrawText, GetDC, ReleaseDC } from './windows/user32.js'
 import { SelectObject } from './windows/gdi32.js'
@@ -24,8 +24,9 @@ export function getButtonIdealSize(hwnd: gui.HWND): { width: number; height: num
 export function measureTextForHwnd(hwnd: gui.HWND, text: string): { width: number; height: number } {
     const hdc = GetDC(hwnd)
     if (!hdc) return { width: 0, height: 0 }
-    const hFont = gui.SendMessage(hwnd, gui.WmMsg.GETFONT, 0, 0)
-    const oldFont = hFont ? SelectObject(hdc, hFont) : 0
+    // SendMessage 返回 LRESULT 裸数；GETFONT 语义为 HFONT——断言进 GDI 对象品牌链
+    const hFont = gui.SendMessage(hwnd, gui.WmMsg.GETFONT, 0, 0) as Ptr<'HGDIOBJ'>
+    const oldFont = hFont ? SelectObject(hdc, hFont) : NULL
     const result = measureText(hdc, text, 0)
     if (hFont) SelectObject(hdc, oldFont)
     ReleaseDC(hwnd, hdc)

package/lib/websocket.js

@@ -345,7 +345,21 @@ class WebSocketImpl {
                     while (true) {
                         let data;
                         if (isWSS && this._ssl) {
-                            data = wolfssl.wolfSSL_read(this._ssl, 8192);
+                            const buf = new ArrayBuffer(8192);
+                            const n = wolfssl.wolfSSL_read(this._ssl, buf);
+                            if (n > 0) {
+                                data = buf.slice(0, n);
+                            }
+                            else {
+                                const err = wolfssl.wolfSSL_get_error(this._ssl, n);
+                                if (err === 2 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ */ ||
+                                    err === 3 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE */)
+                                    break;
+                                if (n === 0 || err === 6 /* wolfssl.ErrorCode.WOLFSSL_ERROR_ZERO_RETURN */)
+                                    break;
+                                doError(new Error('TLS read failed: ' + err));
+                                return;
+                            }
                         }
                         else if (this._sock !== null && this._sock >= 0) {
                             data = sock.recv(this._sock, 8192);
@@ -443,7 +457,23 @@ class WebSocketImpl {
         while (true) {
             let data;
             if (this._ssl) {
-                data = wolfssl.wolfSSL_read(this._ssl, 8192);
+                const buf = new ArrayBuffer(8192);
+                const n = wolfssl.wolfSSL_read(this._ssl, buf);
+                if (n > 0) {
+                    data = buf.slice(0, n);
+                }
+                else {
+                    const err = wolfssl.wolfSSL_get_error(this._ssl, n);
+                    if (err === 2 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ */ ||
+                        err === 3 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE */)
+                        break;
+                    if (n === 0 || err === 6 /* wolfssl.ErrorCode.WOLFSSL_ERROR_ZERO_RETURN */)
+                        break;
+                    this._fireError(new Error('TLS read failed: ' + err));
+                    if (this._state !== State.CLOSED)
+                        this._setState(State.CLOSED);
+                    return;
+                }
             }
             else if (this._sock !== null && this._sock >= 0) {
                 data = sock.recv(this._sock, 8192);

package/lib/websocket.ts

@@ -363,7 +363,18 @@ class WebSocketImpl {
                     while (true) {
                         let data: ArrayBuffer | null
                         if (isWSS && this._ssl) {
-                            data = wolfssl.wolfSSL_read(this._ssl, 8192)
+                            const buf = new ArrayBuffer(8192)
+                            const n = wolfssl.wolfSSL_read(this._ssl, buf)
+                            if (n > 0) {
+                                data = buf.slice(0, n)
+                            } else {
+                                const err = wolfssl.wolfSSL_get_error(this._ssl, n)
+                                if (err === wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ ||
+                                    err === wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE) break
+                                if (n === 0 || err === wolfssl.ErrorCode.WOLFSSL_ERROR_ZERO_RETURN) break
+                                doError(new Error('TLS read failed: ' + err))
+                                return
+                            }
                         } else if (this._sock !== null && this._sock >= 0) {
                             data = sock.recv(this._sock, 8192)
                         } else { break }
@@ -460,7 +471,19 @@ class WebSocketImpl {
         while (true) {
             let data: ArrayBuffer | null
             if (this._ssl) {
-                data = wolfssl.wolfSSL_read(this._ssl, 8192)
+                const buf = new ArrayBuffer(8192)
+                const n = wolfssl.wolfSSL_read(this._ssl, buf)
+                if (n > 0) {
+                    data = buf.slice(0, n)
+                } else {
+                    const err = wolfssl.wolfSSL_get_error(this._ssl, n)
+                    if (err === wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ ||
+                        err === wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE) break
+                    if (n === 0 || err === wolfssl.ErrorCode.WOLFSSL_ERROR_ZERO_RETURN) break
+                    this._fireError(new Error('TLS read failed: ' + err))
+                    if (this._state !== State.CLOSED) this._setState(State.CLOSED)
+                    return
+                }
             } else if (this._sock !== null && this._sock >= 0) {
                 data = sock.recv(this._sock, 8192)
             } else { break }

package/lib/windows/advapi32.js

@@ -0,0 +1,53 @@
+// advapi32 绑定（注册表 API；键名/值名一律 W 版 UTF-16）
+import { bind } from '../ffi/bind.js';
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = (name, sig) => bind('advapi32.dll', name, sig);
+/** 创建/打开子键（子键不存在则创建，含中间层级）
+ *  @returns 0 = ERROR_SUCCESS
+ *  @param args_0 hKey 父键：gui.HKey.CURRENT_USER / LOCAL_MACHINE 预定义键，或本族
+ *                Open/Create 返回的真实句柄（此位双来源，不标 @HKey——裸位收两种）
+ *  @param args_1 lpSubKey 子键路径（'Software\\X\\Y'，可 NULL = 打开 hKey 自身副本）
+ *  @param args_2 Reserved 保留，恒 0
+ *  @param args_3 lpClass 键类名（一般 NULL）
+ *  @param args_4 dwOptions 保留属性（恒 0）
+ *  @param args_5 samDesired 访问掩码 gui.RegAccess.READ / SET_VALUE（标准组合常量按成员收录）
+ *  @param args_6 lpSecurityAttributes 安全描述符（一般 NULL）
+ *  @param args_7 phkResult 出参：键句柄（PtrArrayBuffer(8)，readPtr 按架构读回）
+ *  @param args_8 lpdwDisposition 出参：新建/已存在标记（可 NULL） */
+export const RegCreateKeyEx = /*@__PURE__*/ b('RegCreateKeyExW', '<>ptr <WCHAR>ptr u32 <WCHAR>ptr u32 u32@RegAccess <>ptr <BYTE>ptr <BYTE>ptr -> i32');
+/** 打开已有子键（不创建）
+ *  @returns 0 = ERROR_SUCCESS；2 = ERROR_FILE_NOT_FOUND（子键不存在）
+ *  @param args_0 hKey 父键（同 RegCreateKeyEx 的双来源语义）
+ *  @param args_1 lpSubKey 子键路径（NULL = 打开 hKey 自身副本）
+ *  @param args_2 ulOptions 保留，恒 0
+ *  @param args_3 samDesired 访问掩码 gui.RegAccess.READ / SET_VALUE
+ *  @param args_4 phkResult 出参：键句柄 */
+export const RegOpenKeyEx = /*@__PURE__*/ b('RegOpenKeyExW', '<>ptr <WCHAR>ptr u32 u32@RegAccess <BYTE>ptr -> i32');
+/** 关闭键句柄；只关 Open/Create 返回的真实句柄——预定义键（HKEY_CURRENT_USER 等）
+ *  不要关
+ *  @returns 0 = ERROR_SUCCESS */
+export const RegCloseKey = /*@__PURE__*/ b('RegCloseKey', '<>ptr -> i32');
+/** 写键值
+ *  @returns 0 = ERROR_SUCCESS
+ *  @param args_0 hKey 键句柄（须 KEY_SET_VALUE 权限，含于 gui.RegAccess.SET_VALUE）
+ *  @param args_1 lpValueName 值名（NULL = 键的默认值）
+ *  @param args_2 Reserved 保留，恒 0
+ *  @param args_3 dwType 值类型 gui.RegType.SZ（UTF-16 字符串）
+ *  @param args_4 lpData 数据缓冲（REG_SZ：UTF-16LE 含结尾 NUL）
+ *  @param args_5 cbData 数据字节数（REG_SZ = (字符数+1)*2） */
+export const RegSetValueEx = /*@__PURE__*/ b('RegSetValueExW', '<>ptr <WCHAR>ptr u32 u32@RegType <BYTE>ptr u32 -> i32');
+/** 读键值（两跳模式：第一跳 lpData=NULL 取尺寸/类型，第二跳按尺寸带缓冲读数据）
+ *  @returns 0 = ERROR_SUCCESS；2 = ERROR_FILE_NOT_FOUND（值不存在）
+ *  @param args_0 hKey 键句柄（须 KEY_QUERY_VALUE 权限，含于 gui.RegAccess.READ）
+ *  @param args_1 lpValueName 值名（NULL = 键的默认值）
+ *  @param args_2 lpReserved 保留，恒 NULL
+ *  @param args_3 lpType 出参：值类型（可 NULL）
+ *  @param args_4 lpData 数据缓冲（可 NULL = 只查尺寸）
+ *  @param args_5 lpcbData 双向：入 = lpData 缓冲字节数（须预写）、出 = 实际字节数 */
+export const RegQueryValueEx = /*@__PURE__*/ b('RegQueryValueExW', '<>ptr <WCHAR>ptr <>ptr <BYTE>ptr <BYTE>ptr <BYTE>ptr -> i32');
+/** 删除子键（连值一起删）；须父键 KEY_CREATE_SUB_KEY 权限——自己的 HKCU 直接传
+ *  gui.HKey.CURRENT_USER 即可
+ *  @returns 0 = ERROR_SUCCESS；2 = 子键不存在
+ *  @param args_0 hKey 父键
+ *  @param args_1 lpSubKey 要删的子键路径（不可 NULL） */
+export const RegDeleteKey = /*@__PURE__*/ b('RegDeleteKeyW', '<>ptr <WCHAR>ptr -> i32');

package/lib/windows/advapi32.ts

@@ -0,0 +1,64 @@
+// advapi32 绑定（注册表 API；键名/值名一律 W 版 UTF-16）
+import { bind } from '../ffi/bind.js'
+
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
+const b = <const S extends string>(name: string, sig: S) => bind('advapi32.dll', name, sig)
+
+/** 创建/打开子键（子键不存在则创建，含中间层级）
+ *  @returns 0 = ERROR_SUCCESS
+ *  @param args_0 hKey 父键：gui.HKey.CURRENT_USER / LOCAL_MACHINE 预定义键，或本族
+ *                Open/Create 返回的真实句柄（此位双来源，不标 @HKey——裸位收两种）
+ *  @param args_1 lpSubKey 子键路径（'Software\\X\\Y'，可 NULL = 打开 hKey 自身副本）
+ *  @param args_2 Reserved 保留，恒 0
+ *  @param args_3 lpClass 键类名（一般 NULL）
+ *  @param args_4 dwOptions 保留属性（恒 0）
+ *  @param args_5 samDesired 访问掩码 gui.RegAccess.READ / SET_VALUE（标准组合常量按成员收录）
+ *  @param args_6 lpSecurityAttributes 安全描述符（一般 NULL）
+ *  @param args_7 phkResult 出参：键句柄（PtrArrayBuffer(8)，readPtr 按架构读回）
+ *  @param args_8 lpdwDisposition 出参：新建/已存在标记（可 NULL） */
+export const RegCreateKeyEx = /*@__PURE__*/ b('RegCreateKeyExW',
+    '<>ptr <WCHAR>ptr u32 <WCHAR>ptr u32 u32@RegAccess <>ptr <BYTE>ptr <BYTE>ptr -> i32')
+
+/** 打开已有子键（不创建）
+ *  @returns 0 = ERROR_SUCCESS；2 = ERROR_FILE_NOT_FOUND（子键不存在）
+ *  @param args_0 hKey 父键（同 RegCreateKeyEx 的双来源语义）
+ *  @param args_1 lpSubKey 子键路径（NULL = 打开 hKey 自身副本）
+ *  @param args_2 ulOptions 保留，恒 0
+ *  @param args_3 samDesired 访问掩码 gui.RegAccess.READ / SET_VALUE
+ *  @param args_4 phkResult 出参：键句柄 */
+export const RegOpenKeyEx = /*@__PURE__*/ b('RegOpenKeyExW',
+    '<>ptr <WCHAR>ptr u32 u32@RegAccess <BYTE>ptr -> i32')
+
+/** 关闭键句柄；只关 Open/Create 返回的真实句柄——预定义键（HKEY_CURRENT_USER 等）
+ *  不要关
+ *  @returns 0 = ERROR_SUCCESS */
+export const RegCloseKey = /*@__PURE__*/ b('RegCloseKey', '<>ptr -> i32')
+
+/** 写键值
+ *  @returns 0 = ERROR_SUCCESS
+ *  @param args_0 hKey 键句柄（须 KEY_SET_VALUE 权限，含于 gui.RegAccess.SET_VALUE）
+ *  @param args_1 lpValueName 值名（NULL = 键的默认值）
+ *  @param args_2 Reserved 保留，恒 0
+ *  @param args_3 dwType 值类型 gui.RegType.SZ（UTF-16 字符串）
+ *  @param args_4 lpData 数据缓冲（REG_SZ：UTF-16LE 含结尾 NUL）
+ *  @param args_5 cbData 数据字节数（REG_SZ = (字符数+1)*2） */
+export const RegSetValueEx = /*@__PURE__*/ b('RegSetValueExW',
+    '<>ptr <WCHAR>ptr u32 u32@RegType <BYTE>ptr u32 -> i32')
+
+/** 读键值（两跳模式：第一跳 lpData=NULL 取尺寸/类型，第二跳按尺寸带缓冲读数据）
+ *  @returns 0 = ERROR_SUCCESS；2 = ERROR_FILE_NOT_FOUND（值不存在）
+ *  @param args_0 hKey 键句柄（须 KEY_QUERY_VALUE 权限，含于 gui.RegAccess.READ）
+ *  @param args_1 lpValueName 值名（NULL = 键的默认值）
+ *  @param args_2 lpReserved 保留，恒 NULL
+ *  @param args_3 lpType 出参：值类型（可 NULL）
+ *  @param args_4 lpData 数据缓冲（可 NULL = 只查尺寸）
+ *  @param args_5 lpcbData 双向：入 = lpData 缓冲字节数（须预写）、出 = 实际字节数 */
+export const RegQueryValueEx = /*@__PURE__*/ b('RegQueryValueExW',
+    '<>ptr <WCHAR>ptr <>ptr <BYTE>ptr <BYTE>ptr <BYTE>ptr -> i32')
+
+/** 删除子键（连值一起删）；须父键 KEY_CREATE_SUB_KEY 权限——自己的 HKCU 直接传
+ *  gui.HKey.CURRENT_USER 即可
+ *  @returns 0 = ERROR_SUCCESS；2 = 子键不存在
+ *  @param args_0 hKey 父键
+ *  @param args_1 lpSubKey 要删的子键路径（不可 NULL） */
+export const RegDeleteKey = /*@__PURE__*/ b('RegDeleteKeyW', '<>ptr <WCHAR>ptr -> i32')

package/lib/windows/comctl32.js

@@ -1,18 +1,18 @@
-// comctl32 绑定（ImageList 系列；HIMAGELIST 为不透明句柄保持 <>ptr）
+// comctl32 绑定（ImageList 系列；HIMAGELIST 不透明句柄走 <HIMAGELIST>ptr 自产自收，
+// Add 的 hbm 位与 gdi32 的 <HGDIOBJ>ptr 同型互认——CreateBitmap 产物直传）
 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');
+/** 建图像列表；配对 ImageListDestroy
+ *  @returns 图像列表句柄；失败 → NULL
+ *  @param args_0 cx/cy 图像尺寸  @param args_2 flags ILC_* 组合
+ *  @param args_3 cInitial 初始容量  @param args_4 cGrow 增长步长 */
+export const ImageListCreate = /*@__PURE__*/ b('ImageList_Create', 'i32 i32 u32 i32 i32 -> <HIMAGELIST>ptr');
+/** 加位图进图像列表
+ *  @returns 新索引（-1 失败）
+ *  @param args_0 himl 图像列表句柄
+ *  @param args_1 hbm 位图句柄（gdi32 <HGDIOBJ>ptr 产物，如 CreateCompatibleBitmap） */
+export const ImageListAdd = /*@__PURE__*/ b('ImageList_Add', '<HIMAGELIST>ptr <HGDIOBJ>ptr -> i32');
+/** 销毁图像列表
+ *  @returns 成功 → 非 0 */
+export const ImageListDestroy = /*@__PURE__*/ b('ImageList_Destroy', '<HIMAGELIST>ptr -> i32');

package/lib/windows/comctl32.ts

@@ -1,20 +1,19 @@
-// comctl32 绑定（ImageList 系列；HIMAGELIST 为不透明句柄保持 <>ptr）
+// comctl32 绑定（ImageList 系列；HIMAGELIST 不透明句柄走 <HIMAGELIST>ptr 自产自收，
+// Add 的 hbm 位与 gdi32 的 <HGDIOBJ>ptr 同型互认——CreateBitmap 产物直传）
 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')
+/** 建图像列表；配对 ImageListDestroy
+ *  @returns 图像列表句柄；失败 → NULL
+ *  @param args_0 cx/cy 图像尺寸  @param args_2 flags ILC_* 组合
+ *  @param args_3 cInitial 初始容量  @param args_4 cGrow 增长步长 */
+export const ImageListCreate = /*@__PURE__*/ b('ImageList_Create', 'i32 i32 u32 i32 i32 -> <HIMAGELIST>ptr')
+/** 加位图进图像列表
+ *  @returns 新索引（-1 失败）
+ *  @param args_0 himl 图像列表句柄
+ *  @param args_1 hbm 位图句柄（gdi32 <HGDIOBJ>ptr 产物，如 CreateCompatibleBitmap） */
+export const ImageListAdd = /*@__PURE__*/ b('ImageList_Add', '<HIMAGELIST>ptr <HGDIOBJ>ptr -> i32')
+/** 销毁图像列表
+ *  @returns 成功 → 非 0 */
+export const ImageListDestroy = /*@__PURE__*/ b('ImageList_Destroy', '<HIMAGELIST>ptr -> i32')

package/lib/windows/comdlg32.js

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

package/lib/windows/comdlg32.ts

@@ -4,6 +4,7 @@ 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
+/** 打开/保存文件对话框
+ *  @returns 用户确认 → 非 0（lpstrFile 缓冲即选中路径），取消/出错 → 0
  *  @param args_0 pOpenfn OPENFILENAMEW.encode(...).ptr（lStructSize 必须 = OPENFILENAMEW.size，见 structs.ts） */
-export const GetOpenFileName = /*@__PURE__*/ b('GetOpenFileNameW', '<BYTE>ptr -> u32')
+export const GetOpenFileName = /*@__PURE__*/ b('GetOpenFileNameW', '<OPENFILENAMEW>ptr -> u32')