quickwin 2.0.0 → 2.1.0

package/lib/fetch.js

@@ -56,6 +56,9 @@ const ST_DONE = 5;
 // ── Main fetch request ──
 async function fetchRequest(req) {
     const parsedUrl = new URL(req.url);
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        throw new TypeError('fetch: unsupported protocol "' + parsedUrl.protocol + '"');
+    }
     const method = req.method;
     const headers = new HeadersImpl(req.headers);
     const timeout = req.timeout || 30000;
@@ -241,7 +244,21 @@ async function fetchRequest(req) {
                             break;
                         let data;
                         if (isHTTPS && ssl) {
-                            data = wolfssl.wolfSSL_read(ssl, 8192);
+                            const buf = new ArrayBuffer(8192);
+                            const n = wolfssl.wolfSSL_read(ssl, buf);
+                            if (n > 0) {
+                                data = buf.slice(0, n);
+                            }
+                            else {
+                                const err = wolfssl.wolfSSL_get_error(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;
+                                doReject(new Error('TLS read failed: ' + err));
+                                return;
+                            }
                         }
                         else if (s !== null && s >= 0) {
                             data = sock.recv(s, 8192);
@@ -314,7 +331,31 @@ async function fetchRequest(req) {
                             break;
                         let data;
                         if (isHTTPS && ssl) {
-                            data = wolfssl.wolfSSL_read(ssl, 8192);
+                            const buf = new ArrayBuffer(8192);
+                            const n = wolfssl.wolfSSL_read(ssl, buf);
+                            if (n > 0) {
+                                data = buf.slice(0, n);
+                            }
+                            else {
+                                const err = wolfssl.wolfSSL_get_error(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;
+                                // Fatal TLS error mid-body: the response already
+                                // resolved, so fail the body stream instead of
+                                // silently waiting for an FD event that never comes.
+                                if (_controller) {
+                                    try {
+                                        _controller.error(new Error('TLS read failed: ' + err));
+                                    }
+                                    catch { /* already closed */ }
+                                }
+                                stream = null;
+                                cleanupSocket();
+                                return;
+                            }
                         }
                         else if (s !== null && s >= 0) {
                             data = sock.recv(s, 8192);
@@ -362,7 +403,14 @@ async function fetchRequest(req) {
                             break;
                         let data;
                         if (isHTTPS && ssl) {
-                            data = wolfssl.wolfSSL_read(ssl, 8192);
+                            const buf = new ArrayBuffer(8192);
+                            const n = wolfssl.wolfSSL_read(ssl, buf);
+                            // Best-effort drain: any non-data result (EOF, WANT_*,
+                            // late error) ends the drain — the stream closes below.
+                            if (n > 0)
+                                data = buf.slice(0, n);
+                            else
+                                break;
                         }
                         else if (s !== null && s >= 0) {
                             data = sock.recv(s, 8192);

package/lib/fetch.ts

@@ -78,6 +78,9 @@ const ST_DONE = 5
 
 async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
     const parsedUrl = new URL(req.url)
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        throw new TypeError('fetch: unsupported protocol "' + parsedUrl.protocol + '"')
+    }
     const method = req.method
     const headers = new HeadersImpl(req.headers)
     const timeout = req.timeout || 30000
@@ -225,7 +228,18 @@ async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
                         if (s !== null && s < 0 && !ssl) break
                         let data: ArrayBuffer | null
                         if (isHTTPS && ssl) {
-                            data = wolfssl.wolfSSL_read(ssl, 8192)
+                            const buf = new ArrayBuffer(8192)
+                            const n = wolfssl.wolfSSL_read(ssl, buf)
+                            if (n > 0) {
+                                data = buf.slice(0, n)
+                            } else {
+                                const err = wolfssl.wolfSSL_get_error(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
+                                doReject(new Error('TLS read failed: ' + err))
+                                return
+                            }
                         } else if (s !== null && s >= 0) {
                             data = sock.recv(s, 8192)
                         } else { break }
@@ -295,7 +309,23 @@ async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
                         if (s !== null && s < 0 && !ssl) break
                         let data: ArrayBuffer | null
                         if (isHTTPS && ssl) {
-                            data = wolfssl.wolfSSL_read(ssl, 8192)
+                            const buf = new ArrayBuffer(8192)
+                            const n = wolfssl.wolfSSL_read(ssl, buf)
+                            if (n > 0) {
+                                data = buf.slice(0, n)
+                            } else {
+                                const err = wolfssl.wolfSSL_get_error(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
+                                // Fatal TLS error mid-body: the response already
+                                // resolved, so fail the body stream instead of
+                                // silently waiting for an FD event that never comes.
+                                if (_controller) { try { _controller.error(new Error('TLS read failed: ' + err)) } catch { /* already closed */ } }
+                                stream = null
+                                cleanupSocket()
+                                return
+                            }
                         } else if (s !== null && s >= 0) {
                             data = sock.recv(s, 8192)
                         } else { break }
@@ -335,7 +365,12 @@ async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
                         if (s !== null && s < 0 && !ssl) break
                         let data: ArrayBuffer | null
                         if (isHTTPS && ssl) {
-                            data = wolfssl.wolfSSL_read(ssl, 8192)
+                            const buf = new ArrayBuffer(8192)
+                            const n = wolfssl.wolfSSL_read(ssl, buf)
+                            // Best-effort drain: any non-data result (EOF, WANT_*,
+                            // late error) ends the drain — the stream closes below.
+                            if (n > 0) data = buf.slice(0, n)
+                            else break
                         } else if (s !== null && s >= 0) {
                             data = sock.recv(s, 8192)
                         } else { break }

package/lib/ffi/bind.js

@@ -3,7 +3,12 @@ import * as os from 'os';
 import * as std from 'std';
 import * as win from 'win';
 import '../text-codec.js';
-import { cTokenToType, isCPtrToken, normToken, PTR_SIZE, ptrName, readScalar, writeSlot, PtrArrayBuffer } from './ctype.js';
+import { cTokenToType, isCPtrToken, isCValToken, valName, normToken, PTR_SIZE, ptrName, readScalar, writeSlot, PtrArrayBuffer } from './ctype.js';
+// CodecMap 的值是结构形（size 只在 StructDef 上、不属 Codec 契约），统一走 unknown
+// 二跳提取；存在性与 size 由 makeFn 绑定期校验。
+function valCodec(name, encoders) {
+    return encoders[name];
+}
 const _dllCache = new Map();
 function loadDll(dll) {
     const cached = _dllCache.get(dll);
@@ -36,14 +41,36 @@ function parseSig(sig) {
     }
     // 裸 '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, sig, encoders, decoders) {
     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) => callPacked(proc, ps, a, encoders, decoders);
 }
 // 每个参数在 argFrame 里占的字节数。与 quickjs-ffi-type.h 的 qwin_ffi_arg_size[]
@@ -59,15 +86,36 @@ const X64_MIN_SLOTS = 4;
 function callPacked(proc, { argTokens, retToken, sig }, args, encoders, decoders) {
     const is64 = os.arch === 'x64';
     const getWidth = (t, is64) => {
+        // 按值形由 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) => {
+        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);
+        total += widthOf(t);
     if (is64 && argTokens.length < X64_MIN_SLOTS)
         total = X64_MIN_SLOTS * 8;
     const argFrame = new ArrayBuffer(total);
@@ -118,10 +166,40 @@ function callPacked(proc, { argTokens, retToken, sig }, args, encoders, decoders
                 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);
     const retIsFp = retToken === 'f32' || retToken === 'f64';
@@ -155,7 +233,8 @@ function readRet(ret, retBuf) {
  *  品牌指针逐字节读到 NUL（野指针无终止 4MiB 上限 fail-fast）、ArrayBuffer 直读到
  *  NUL 或末尾（out 参数未写 NUL 时按读满处理）；alloc 预分配返回带 .ptr 的
  *  PtrArrayBuffer（a = 字符数，缺省 256）。类型取必需形态——
- *  内建三件齐备，调用无需空断言。 */
+ *  内建三件齐备，调用无需空断言。刻意 Pick 而非 Required<Codec>：只声明消费的
+ *  三件（encode/decode/alloc），新增可选能力位不被拉成必填。 */
 export const WCHAR = {
     encode: (v) => {
         // TextEncoder 没有 encodeInto：先编码再拷入带 .ptr 的 buffer（单次 memcpy，
@@ -316,6 +395,16 @@ function dispatchClosure(args, ret, fn, frameBuf, retBuf, sig) {
  *  → 打印泄漏警告（只警告、不自动释放，见 leakRegistry）。 */
 export function closure(sig, fn, opts) {
     const { argTokens, retToken } = parseSig(sig);
+    // 按值位仅支持 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), nonnull: t.endsWith('!') }));
     const retSpec = { tok: cTokenToType(retToken), nonnull: retToken.endsWith('!') };
     const is64 = os.arch === 'x64';

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 的语义校验留给类型层