quickwin 2.0.0 → 2.1.0

package/lib/ffi/ctype.ts

@@ -29,28 +29,53 @@ const C_BASIC_TYPE = [
 export type C_BasicType = (typeof C_BASIC_TYPE)[number]
 export type C_BasicType_No_Void = Exclude<C_BasicType, 'void'>
 
-// '!' 形随 token 走（normToken 只剥运行时不理解的 '@'，运行时要执法的 '!' 保留——
-// token 即契约，callPacked/closure 按尾缀做 0 检查，无独立 flag 可丢）。
-export type C_BasicType_Token = Exclude<C_BasicType, 'ptr'> | `<${string}>ptr` | `<${string}>ptr!`
+// '!' / '*' 形随 token 走（normToken 只剥运行时不理解的 '@'，运行时要执法的 '!'（0 检查）
+// 与 '*'（数组分派）保留在 token 上——token 即契约，callPacked 按尾缀执法，无独立 flag
+// 可丢）。'<N*>ptr' 数组位无需新词形：品牌段含 '*'，整 token 仍在 <${string}>ptr 模板内。
+export type C_BasicType_Token = Exclude<C_BasicType, 'ptr'> | `<${string}>ptr` | `<${string}>ptr!` | `<${string}>`
 export type C_BasicType_Token_No_Void = Exclude<C_BasicType_Token, 'void'>
 
 // 尾缀修饰：'!' = 非空担保（见 Arg/RetJsTypeOfToken 的 ! 分支与 callPacked 的运行时 0 检查），
 // '@Name' = 枚举值域标注（类型层启用前先由 Norm 归一剥掉）。两者语义正交但作用面不相交
 // （! 主品牌位、@ 主裸档整数位，@ 枚举不含 0 时已蕴含 !），故每 token 至多一个修饰。
 // 组 1 恒为名字（归一名），组 2 为修饰；槽宽/ABI 只看归一形式。
-const PTR_TOKEN_RE = /^<([^<>\s]*)>ptr(!|@[A-Za-z_]\w*)?$/
+// 名字形收紧为标识符（[A-Za-z_]\w*）∪ 空串（<>ptr 裸地址档），尾部可挂数组字形：
+// '*' = 零或多（<N*>ptr 入参连续数组位，元素形 = 单对象位 codec）。其余非标识符
+// 字符（'+'/'-'/'1' 开头等）不进词法 —— 与 <1abc>ptr/<X-y>ptr 同策略：正则不匹配、
+// 绑定时落通用 Unknown token，类型层不设专属禁分支（运行时兜底，无静默通过）。旧版
+// ([^<>\s]*) 通配曾使 <FOO+>ptr 被静默当品牌 'FOO+' 接受——语义字形必须结构可见。
+const PTR_TOKEN_RE = /^<([A-Za-z_]\w*|)>ptr(!|@[A-Za-z_]\w*)?$/
 
 export function isCPtrToken(t: string): t is `<${string}>ptr` | `${string}ptr!` | `${string}ptr@${string}` { return PTR_TOKEN_RE.test(t) }
+
+// '<N>' 裸品牌形 = 按值传参位（<N>ptr 传地址 / <N> 传值）。名字形同指针形（标识符，
+// 空名 <> 仅 ptr 档有），不带任何修饰 —— 按值位无 '!'（值不为 NULL）、无 '@'（值域由
+// codec 推导、不标枚举）、无 '*'（数组走 structArray encoder 的值域）：含修饰的形
+// 正则不匹配，落绑定时通用 Unknown token（与 '<X+>ptr' 同策略，运行时兜底）。
+const VAL_TOKEN_RE = /^<([A-Za-z_]\w*)>$/
+
+export function isCValToken(t: string): t is `<${string}>` { return VAL_TOKEN_RE.test(t) }
+export function valName<const N extends string>(t: `<${N}>`): N {
+    const m = VAL_TOKEN_RE.exec(t)
+    return (m?.[1] || "") as N
+}
 export function ptrName<const N extends string>(t: `<${N}>ptr` | `<${N}>ptr!`): N {
     const m = PTR_TOKEN_RE.exec(t)
     return (m?.[1] || "") as N
 }
 /**
- * @description `<${string}>ptr` / `<${string}>ptr!` -> 'ptr'
+ * @description `<${string}>ptr` / `<${string}>ptr!` -> 'ptr'。按值形 `<${string}>` 无
+ * 标量槽等价物 —— 运行时 throw（返回位由 parseSig 拒、closure 入参位由 closure() 拒，
+ * 正常路径不可达），返回类型同时 Exclude 掉按值形：消费方（readRet / dispatchClosure
+ * 的 IA32_ARG_SIZE 索引）拿不到会误导编译期的标量误判。
  */
-export const cTokenToType = <const T extends string>(t: T): Exclude<T, `<${string}>ptr` | `<${string}>ptr!`> | 'ptr' => {
+export const cTokenToType = <const T extends string>(
+    t: T,
+): Exclude<T, `<${string}>ptr` | `<${string}>ptr!` | `<${string}>`> | 'ptr' => {
     if (isCPtrToken(t)) return 'ptr'
-    else return t as Exclude<T, `<${string}>ptr` | `<${string}>ptr!`>
+    if (isCValToken(t))
+        throw new Error(`ffi: cTokenToType: by-value token "${t}" has no scalar slot type`)
+    return t as Exclude<T, `<${string}>ptr` | `<${string}>ptr!` | `<${string}>`>
 }
 
 // C 的数字类型档：可作结构体字段 / bind 签名 token。排除项理由见 §1。
@@ -202,9 +227,16 @@ declare global {
 // 泛型体内）由 `string & keyof map` = 全键联合兜底成非 never —— 否则 BindFn 塌
 // (never)=>never 使内层强转失去可比性。
 export type ArgJsTypeOfToken<K extends string, L> =
+    // 非标识符名字形（'<X+>ptr'/'<X*>ptr'/'<1abc>ptr'）不设专属分支：落 '<N>ptr'
+    // 通配、运行时 Unknown token 兜底（'*' 已非 token 字形 —— 数组物化走
+    // structArray(def) encoder 的值域推导，token/引擎/类型层零数组概念）。
     K extends `<${infer N}>ptr!` ? Ptr<N> | L[N & keyof L] :
     K extends `<${string}>ptr@${infer E extends keyof EnumMap}` ? EnumMap[E] :
     K extends `<${infer N}>ptr` ? MaybePtr<N> | L[N & keyof L] :
+    // '<N>' 按值位：值域 = 注册布局的 encode 入参形（对象直传），无 MaybePtr —— 按值
+    // 位不收 NULL / 地址（引擎按值语义编码，地址进位是必然错位）。未注册布局 →
+    // L[never] → 整位塌 never（与拼错 token 同策略）。
+    K extends `<${infer N}>` ? L[N & keyof L] :
     K extends `${C_Number}@${infer E extends keyof EnumMap}` ? EnumMap[E] :
     TokenArgJsTypeMap[K & keyof TokenArgJsTypeMap] extends never ? never
     : TokenArgJsTypeMap[K & keyof TokenArgJsTypeMap]
@@ -234,11 +266,17 @@ export type RetJsTypeOfToken<K extends string, D> =
 export function normToken(t: string): C_BasicType_Token {
     if (isCPtrToken(t)) {
         // 只剥 '@Name'（枚举标注是纯类型层语义，运行时不校验、不理解）；'!' 保留在
-        // token 上——运行时要执法的语义（0 检查）跟着 token 走到 callPacked/closure，
-        // 无独立 flag 可被解构丢失。槽宽/ABI 判型走 isCPtrToken，带 '!' 不受影响。
+        // token 上——运行时要执法的语义（0 检查）跟着 token 走到 callPacked，
+        // 无独立 flag 可被解构丢失。槽宽/ABI 判型走 isCPtrToken，带修饰不受影响。
         const m = PTR_TOKEN_RE.exec(t)
-        return (m?.[2]?.startsWith('@') ? `<${m[1]}>ptr` : t) as C_BasicType_Token
+        const name = m?.[1] || ''
+        const mod = m?.[2]
+        // 剥 '@'（纯类型层语义）；'!' 形随 token 走。（'*' 等词法外字符不设专属分支：
+        // 不匹配正则，落末尾 Unknown token —— 与 '<X+>ptr' 同待遇。）
+        return (mod?.startsWith('@') ? `<${name}>ptr` : t) as C_BasicType_Token
     }
+    // 按值形 '<N>' 无修饰可剥（见 VAL_TOKEN_RE 注释），原样归一。
+    if (isCValToken(t)) return t
     // 整数档尾缀 '@Name'（枚举值域标注，与 ptr 位的 '@' 同源）：剥掉归一到原 token，
     // 槽宽/ABI 只看归一形式。@ 后缀须为纯枚举名形 —— 'u32@WmMsg:3' 这类混进位域/数组
     // 串的直接 throw，不静默吞成纯标量（布局会错）；名 ∈ EnumMap 的语义校验留给类型层

package/lib/ffi/struct.js

@@ -354,28 +354,31 @@ function createStruct(t) {
         size,
         structAlign: maxEffectiveAlign,
         decode: (p) => {
-            // 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)),
-        encode: ((v, buf) => {
+        alloc: ((n) => {
+            // 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));
+        }),
+        encode: ((v, buf, offset) => {
             // 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;
         }),
         offsetOf: (name) => {
@@ -398,6 +401,81 @@ function buildDecl(kind, member, pack) {
             decl[k] = v;
     return decl;
 }
+/** 结构/联合体的数组编解码对工厂：返回 `{ 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(def) {
+    const { fields, size } = computeStructLayout(def.__struct);
+    const readN = (dv, n) => {
+        const out = [];
+        for (let i = 0; i < n; i++)
+            out.push(doDecode(dv, i * size, fields));
+        return out;
+    };
+    return {
+        encode: (els) => {
+            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, count) => {
+            // 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;
+            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);
+        }),
+    };
+}
 export function struct(a, b, c) {
     const isNamed = typeof a === 'string';
     const raw = (isNamed ? b : a);

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');