quickwin 2.0.0 → 2.1.1

package/lib/ffi/bind.ts

@@ -3,7 +3,7 @@ import * as os from 'os'
 import * as std from 'std'
 import * as win from 'win'
 import '../text-codec.js'
-import { type C_BasicType, C_BasicType_No_Void, C_BasicType_Token, C_BasicType_Token_No_Void, cTokenToType, isCPtrToken, ArgJsTypeOfToken, RetJsTypeOfToken, normToken, PTR_SIZE, ptrName, type Ptr, readScalar, writeSlot, PtrArrayBuffer } from './ctype.js'
+import { type C_BasicType, C_BasicType_No_Void, C_BasicType_Token, C_BasicType_Token_No_Void, cTokenToType, isCPtrToken, isCValToken, valName, ArgJsTypeOfToken, RetJsTypeOfToken, normToken, PTR_SIZE, ptrName, type Ptr, readScalar, writeSlot, PtrArrayBuffer } from './ctype.js'
 
 // 形状刻意是「方法」而非裸函数：ffi-struct 的 struct()/union() 结果（StructDef）
 // 结构上即满足 encode 重载（无 buf 新建带品牌 .ptr 的 PtrArrayBuffer / 带 buf 写入既有
@@ -18,20 +18,35 @@ import { type C_BasicType, C_BasicType_No_Void, C_BasicType_Token, C_BasicType_T
 // .ptr 又带品牌直接喂 <N>ptr 形参——不再有 { buf, ptr } 结构包装。
 type Codec<N extends string = string, V = unknown, T = unknown> = {
     // encode 顶层不收 offset（与 decode 对齐）：PAB 的 .ptr 恒指向起点，写入位置由
-    // buf 自身表达；嵌套偏移由布局字段承担。
+    // buf 自身表达；偏移写入（数组物化原语）由 StructDef.encode(v, buf, offset) 承担。
     encode?(v: V, buf?: PtrArrayBuffer<any>): PtrArrayBuffer<any>
     decode?(p: Ptr<N>| ArrayBuffer): V
     alloc?(a: T): PtrArrayBuffer<N>
 }
 // 约束层三件与 StructDef 形状一致，def 可整体透传；提取层按键存在性走（见下）。
-// 类型层硬约束：encode/alloc 只返回 PtrArrayBuffer——裸 ArrayBuffer 出不了 codec
-// （callPacked 参数位统一取 .ptr，调用方拿到的也是 .ptr，.buf 词汇从 codec 出口消失）。
+// 类型层硬约束：encode/alloc 只返回 PtrArrayBuffer —— 裸 ArrayBuffer 出不了
+// codec（callPacked 参数位统一取 .ptr，调用方拿到的也是 .ptr，.buf 词汇从 codec 出口消失）；
+// NULL（0）是引擎层词汇（number 直通世界），不作为 codec 出口形态。
 export type CodecMap = Record<string, {
     encode?(v: any, buf?: PtrArrayBuffer<any>): PtrArrayBuffer<any>
     decode?(p: any): any
     alloc?(a: any): PtrArrayBuffer<any>
 }>
 
+// 按值位（'<N>'）消费的布局形态：size（决定槽宽与「传值 / 按引用」分派）+
+// encode(v, buf, offset)（写入任意 buffer 的既有偏移——argFrame 槽内写入、
+// 16 对齐临时副本两条路径共用）。StructDef 结构上即满足，内建 WCHAR/BYTE 无 size。
+type StructValCodec = {
+    size: number
+    encode(v: unknown, buf: ArrayBuffer, offset: number): unknown
+}
+
+// CodecMap 的值是结构形（size 只在 StructDef 上、不属 Codec 契约），统一走 unknown
+// 二跳提取；存在性与 size 由 makeFn 绑定期校验。
+function valCodec(name: string, encoders: CodecMap): StructValCodec | undefined {
+    return encoders[name] as unknown as StructValCodec | undefined
+}
+
 const _dllCache: Map<string, win.HMODULE> = new Map()
 
 function loadDll(dll: string): win.HMODULE {
@@ -75,15 +90,36 @@ function parseSig(sig: string): ParsedSig {
 
     // 裸 'ptr'/非法 token 由类型层拦截（C_BasicType_Token 已 Exclude 'ptr'、拼错 token 塌成 never）；
     // 运行时再比较只会得到 TS2367「两类型无重叠」——类型已表达的约束不重复校验。
+    const retToken = normToken(parts[1]!)
+    // 按值形 '<N>' 仅支持入参位：大结构返回需要隐藏指针/sret 级 ABI（本运行时的
+    // retBuf 恒 8 字节，只支持标量/浮点/指针返回），绑定期 throw 而非静默降级。
+    // 类型层对返回位的 '<N>' 不设专门分支（fallthrough），本 throw 是唯一防线。
+    if (isCValToken(retToken))
+        throw new Error(`ffi-bind: "${sig}": by-value struct at the return position ` +
+            `(<${valName(retToken)}>) is not supported — argument positions only; ` +
+            `pass a struct out through an out-param slot instead (<N>ptr + caller buffer)`)
     return {
         argTokens,
-        retToken: normToken(parts[1]!),
+        retToken,
         sig,
     }
 }
 
 function makeFn(proc: number, sig: string, encoders: CodecMap, decoders: CodecMap): (...a: unknown[]) => unknown {
     const ps = parseSig(sig)
+    // 按值位的能力校验前移到绑定期（模块加载即炸，不留到首个调用）：布局缺位 / 非结构
+    // 布局（无 size）/ 退化 size 都是签名层面的错误，报错指向具体位与可用布局清单。
+    for (const t of ps.argTokens) {
+        if (!isCValToken(t)) continue
+        const name = valName(t)
+        const codec = valCodec(name, encoders)
+        if (!codec || typeof codec.encode !== 'function')
+            throw new Error(`ffi-bind: ${sig}: by-value position <${name}> has no registered layout ` +
+                `(available: ${Object.keys(encoders).join(', ') || 'none'})`)
+        if (typeof codec.size !== 'number' || codec.size < 1)
+            throw new Error(`ffi-bind: ${sig}: by-value position <${name}> requires a struct ` +
+                `layout with size >= 1 (got ${codec.size}; non-struct codecs expose no size)`)
+    }
     return (...a: unknown[]) => callPacked(proc, ps, a, encoders, decoders)
 }
 
@@ -102,13 +138,34 @@ function callPacked(proc: number, { argTokens, retToken, sig }: ParsedSig, args:
     const is64 = os.arch === 'x64'
 
     const getWidth = (t: C_BasicType_Token_No_Void, is64: boolean): number => {
+        // 按值形由 widthOf 分派（槽宽依赖布局 size），此处只认标量/指针档；守卫同时
+        // 收窄类型（IA32_ARG_SIZE 索引不认 val 形）。
+        if (isCValToken(t))
+            throw new Error(`ffi-bind: getWidth: by-value token "${t}" (dispatched by widthOf)`)
         if (is64) return 8
         if (isCPtrToken(t)) return PTR_SIZE
         return IA32_ARG_SIZE[t]
     }
 
+    // 按值位的槽宽：x64 恒 8 字节（尺寸 ∈{1,2,4,8} 按「同尺寸整数」进槽，其余尺寸进
+    // 槽的是指向临时副本的指针）；ia32 = ALIGN(size, 4) —— 结构字节原样压栈，无按
+    // 引用一说（libffi ffi.c 的 ia32 分支同规则，桩只做一次 rep movsb 搬运）。
+    const widthOf = (t: C_BasicType_Token_No_Void): number => {
+        if (isCValToken(t)) {
+            if (is64) return 8
+            const layout = valCodec(valName(t), encoders)
+            // 绑定期 makeFn 已校验（存在 + size >= 1）；此处兜动态/无类型路径。
+            if (!layout)
+                throw new Error(`ffi-bind: <${valName(t)}> by-value position has no registered layout`)
+            const size = layout.size
+            return size % 4 === 0 ? size : size + 4 - (size % 4)
+        }
+        // val 形已在上分支 return，此处恒为标量/指针形（类型层收窄，见 C_BasicType_Token）。
+        return getWidth(t, is64)
+    }
+
     let total = 0
-    for (const t of argTokens) total += getWidth(t, is64)
+    for (const t of argTokens) total += widthOf(t)
     if (is64 && argTokens.length < X64_MIN_SLOTS) total = X64_MIN_SLOTS * 8
 
     const argFrame = new ArrayBuffer(total)
@@ -160,10 +217,39 @@ function callPacked(proc: number, { argTokens, retToken, sig }: ParsedSig, args:
                 writeSlot(dv, off, { k: 'ptr', v: p })
             }
         }
+        else if (isCValToken(argToken)) {
+            // 按值位：对象直传（值域由注册布局推导），无地址词汇 —— NULL / number
+            // 进这里是必然错位（引擎按值语义，指针位请写 <N>ptr），fail-loud。
+            const name = valName(argToken)
+            const codec = valCodec(name, encoders)
+            if (!codec)
+                throw new Error(`ffi-bind: ${sig}: arg#${i + 1} <${name}> by-value position ` +
+                    `has no registered layout`)
+            if (arg === null || arg === undefined)
+                throw new Error(`ffi-bind: <${name}> value position got ${String(arg)}; ` +
+                    `pass a struct object (use <${name}>ptr to pass a pointer)`)
+            const size = codec.size
+            if (!is64 || (size <= 8 && (size & (size - 1)) === 0)) {
+                // 字节直接落槽：ia32 结构按值压栈（任意尺寸）；x64 尺寸 ∈{1,2,4,8}
+                // 按「同尺寸整数」传值——字节在 8 字节槽低位，callee 右对齐读。
+                // argFrame 构造时即零填充，槽高位为 0（callee 忽略高位，无歧义）。
+                codec.encode(arg, argFrame, off)
+            } else {
+                // x64 其余尺寸（>8 或非 2 的幂）按引用：槽放指针，指向 caller 分配的
+                // 16 字节对齐临时副本（MS x64 官方规则：单参数永不跨多个寄存器；对齐
+                // 偏移自算，不依赖分配器的对齐保证）。held 保持引用直到调用返回。
+                const buf = new ArrayBuffer(size + 15)
+                const base = ffi.bufferPtr(buf)
+                const pad = (16 - (base % 16)) % 16
+                codec.encode(arg, buf, pad)
+                held.push(buf)
+                writeSlot(dv, off, { k: 'ptr', v: base + pad })
+            }
+        }
         else {
             writeSlot(dv, off, { k: argToken, v: arg })
         }
-        off += getWidth(argToken, is64)
+        off += widthOf(argToken)
     }
 
     const retBuf = new ArrayBuffer(8)
@@ -231,8 +317,9 @@ type BindFn<S extends string, E, D> =
  *  品牌指针逐字节读到 NUL（野指针无终止 4MiB 上限 fail-fast）、ArrayBuffer 直读到
  *  NUL 或末尾（out 参数未写 NUL 时按读满处理）；alloc 预分配返回带 .ptr 的
  *  PtrArrayBuffer（a = 字符数，缺省 256）。类型取必需形态——
- *  内建三件齐备，调用无需空断言。 */
-export const WCHAR: Required<Codec<'WCHAR', string, number>> = {
+ *  内建三件齐备，调用无需空断言。刻意 Pick 而非 Required<Codec>：只声明消费的
+ *  三件（encode/decode/alloc），新增可选能力位不被拉成必填。 */
+export const WCHAR: Required<Pick<Codec<'WCHAR', string, number>, 'encode' | 'decode' | 'alloc'>> = {
     encode: (v: string) => {
         // TextEncoder 没有 encodeInto：先编码再拷入带 .ptr 的 buffer（单次 memcpy，
         // 编码逻辑仍全局唯一——这行是全部 UTF-16 字符串编码的唯一实现）。
@@ -407,7 +494,17 @@ function dispatchClosure(
 export function closure<S extends string>(sig: S, fn: BindFn<S, {}, {}>,
     opts?: { stdcall?: boolean }): { ptr: number; dispose(): void } {
     const { argTokens, retToken } = parseSig(sig)
-    const argSpecs = argTokens.map(t => ({ tok: cTokenToType(t), nonnull: t.endsWith('!') }))
+    // 按值位仅支持 bind 的入参方向：closure 的 C→JS 方向由 quickjs-ffi-closure-*.S
+    // 按固定槽宽读参数（x64 固定 8 字节槽、ia32 IA32_ARG_SIZE 表），不区分「槽内是
+    // 结构字节还是指向临时副本的指针」——该分派未实现，创建期 fail-fast。
+    for (const t of argTokens)
+        if (isCValToken(t))
+            throw new Error(`ffi-bind: closure signature cannot take a by-value struct ` +
+                `(<${valName(t)}>); by-value is bind-only — the C→JS direction has no ` +
+                `struct slot decoding (pass a pointer and decode on the JS side)`)
+    // 上方已拒 '<N>' 按值形：此处 tok 恒为标量/指针档（cTokenToType 对 val 形原样返回，
+    // 但那条路径不可达——IA32_ARG_SIZE 索引与 dispatchClosure 只认标量档）。
+    const argSpecs = argTokens.map(t => ({ tok: cTokenToType(t) as C_BasicType_No_Void, nonnull: t.endsWith('!') }))
     const retSpec = { tok: cTokenToType(retToken), nonnull: retToken.endsWith('!') }
     const is64 = os.arch === 'x64'
     const stackCapture = argSpecs.reduce((s, x) => s + IA32_ARG_SIZE[x.tok], 0)

package/lib/ffi/ctype.js

@@ -27,20 +27,39 @@ const C_BASIC_TYPE = [
 // '@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) { 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) { return VAL_TOKEN_RE.test(t); }
+export function valName(t) {
+    const m = VAL_TOKEN_RE.exec(t);
+    return (m?.[1] || "");
+}
 export function ptrName(t) {
     const m = PTR_TOKEN_RE.exec(t);
     return (m?.[1] || "");
 }
 /**
- * @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 = (t) => {
     if (isCPtrToken(t))
         return 'ptr';
-    else
-        return t;
+    if (isCValToken(t))
+        throw new Error(`ffi: cTokenToType: by-value token "${t}" has no scalar slot type`);
+    return t;
 };
 export const PTR_SIZE = os.arch === 'x64' ? 8 : 4;
 export const SizeAlign = {
@@ -56,11 +75,18 @@ export const NULL = 0;
 export function normToken(t) {
     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);
+        const name = m?.[1] || '';
+        const mod = m?.[2];
+        // 剥 '@'（纯类型层语义）；'!' 形随 token 走。（'*' 等词法外字符不设专属分支：
+        // 不匹配正则，落末尾 Unknown token —— 与 '<X+>ptr' 同待遇。）
+        return (mod?.startsWith('@') ? `<${name}>ptr` : t);
     }
+    // 按值形 '<N>' 无修饰可剥（见 VAL_TOKEN_RE 注释），原样归一。
+    if (isCValToken(t))
+        return t;
     // 整数档尾缀 '@Name'（枚举值域标注，与 ptr 位的 '@' 同源）：剥掉归一到原 token，
     // 槽宽/ABI 只看归一形式。@ 后缀须为纯枚举名形 —— 'u32@WmMsg:3' 这类混进位域/数组
     // 串的直接 throw，不静默吞成纯标量（布局会错）；名 ∈ EnumMap 的语义校验留给类型层

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