quickwin 2.0.0 → 2.1.1

package/test/test_ffi_abi.js

@@ -1,7 +1,10 @@
 import * as std from 'std';
 import * as win from 'win';
+import * as os from 'os';
 import { bind } from '../lib/ffi/bind.js';
+import { struct } from '../lib/ffi/struct.js';
 import { NULL, PtrArrayBuffer } from '../lib/ffi/ctype.js';
+import { POINT, RECT } from '../lib/windows/structs.js';
 // ABI 边界回归：覆盖 REMOVE_LIBFFI_PLAN.md §4.2 的维度，全部用真实 Win32/CRT
 // 函数（不新增测试专用导出）。缺函数的平台记 SKIP 而非 FAIL，避免环境差异误报。
 //
@@ -231,5 +234,57 @@ export const suite = {
         }
         else
             t.skipCase('GetDC/IsWindow missing');
+        t.section('by-value struct arg: <POINT> (slot value, not a pointer)');
+        if (has(usr, 'PtInRect') && has(usr, 'WindowFromPoint') && has(usr, 'ChildWindowFromPointEx')) {
+            // PtInRect(rect, pt)：RECT 按指针、POINT 按值（x64 位置寄存器 / ia32 压 8 字节上栈）。
+            // 非对称矩形 {0,0,10,100} —— 若 x/y 在打包中交换，(99,5) 与 (5,99) 的判定会互换，
+            // 本段即可抓出「槽内是地址而非值」「字段顺序/位置错」两类 ABI 错误。
+            const ptInRect = bind('user32.dll', 'PtInRect', '<RECT>ptr <POINT> -> i32', { RECT, POINT });
+            const rectOut = RECT.alloc();
+            const rdv = new DataView(rectOut);
+            rdv.setInt32(8, 10, true); // right（left/top = 0，零填充）
+            rdv.setInt32(12, 100, true); // bottom
+            t.check('PtInRect inside (5,5)', 1, ptInRect(rectOut.ptr, { x: 5, y: 5 }));
+            t.check('PtInRect inside (5,99)', 1, ptInRect(rectOut.ptr, { x: 5, y: 99 }));
+            t.check('PtInRect outside (99,5) — swap-sensitive', 0, ptInRect(rectOut.ptr, { x: 99, y: 5 }));
+            t.check('PtInRect outside x=10 (right edge exclusive)', 0, ptInRect(rectOut.ptr, { x: 10, y: 5 }));
+            // 位置 1（首参即结构）：WindowFromPoint(POINT) → 屏内必非 NULL
+            const getSystemMetrics = bind('user32.dll', 'GetSystemMetrics', 'i32 -> i32');
+            const cx = getSystemMetrics(0); // SM_CXSCREEN
+            const cy = getSystemMetrics(1); // SM_CYSCREEN
+            const windowFromPoint = bind('user32.dll', 'WindowFromPoint', '<POINT> -> <>ptr', { POINT });
+            t.checkTrue('WindowFromPoint(screen center) non-null', !!windowFromPoint({ x: cx >> 1, y: cy >> 1 }));
+            // 位置 2 + 其后参数推移（POINT 之后还有 UINT flags —— 槽宽算错会把 flags 读错位）
+            const childFromPointEx = bind('user32.dll', 'ChildWindowFromPointEx', '<>ptr <POINT> u32 -> <>ptr', { POINT });
+            const getDesktopWindow = bind('user32.dll', 'GetDesktopWindow', ' -> <>ptr');
+            const desk = getDesktopWindow();
+            t.checkTrue('ChildWindowFromPointEx inside → non-null', !!childFromPointEx(desk, { x: 1, y: 1 }, 0 /* CWP_ALL */));
+            t.check('ChildWindowFromPointEx outside → NULL', 0, childFromPointEx(desk, { x: cx + 100, y: cy + 100 }, 0 /* CWP_ALL */));
+        }
+        else
+            t.skipCase('PtInRect/WindowFromPoint/ChildWindowFromPointEx missing');
+        t.section('by-value struct >8B / odd size: x64 by-reference (caller temp)');
+        if (os.arch === 'x64' && has(crt, 'memcpy')) {
+            // MS x64：size ∉ {1,2,4,8} 的聚合体按引用传 —— 槽内是指向 caller 分配的
+            // 16 字节对齐临时副本的指针（单参数永不跨寄存器）。memcpy 第 2 参语义即
+            // 「源地址」，借它白盒验证整条 by-ref 路径：若槽内不是合法副本地址、或
+            // 字节未写进副本，拷回内容必错。ia32 按值恒把字节压栈（callee 读地址会
+            // 拿到垃圾值），故本段 x64 限定；ia32 侧由上面真实 API 段覆盖栈上传值。
+            const BYVAL12 = struct('BYVAL12', { a: 'u32', b: 'u32', c: 'u32' });
+            const BYVAL3 = struct('BYVAL3', { p: 'u8', q: 'u8', r: 'u8' });
+            const cp12 = bind('msvcrt.dll', 'memcpy', '<BYTE>ptr <BYVAL12> u32 -> <>ptr', { BYVAL12 });
+            const cp3 = bind('msvcrt.dll', 'memcpy', '<BYTE>ptr <BYVAL3> u32 -> <>ptr', { BYVAL3 });
+            const d12 = new PtrArrayBuffer(12);
+            cp12(d12, { a: 1, b: 0x11223344, c: 0x7fffffff }, 12);
+            const dv12 = new DataView(d12);
+            t.check('12B (>8B) by-ref word 0', 1, dv12.getUint32(0, true));
+            t.check('12B (>8B) by-ref word 1', 0x11223344, dv12.getUint32(4, true));
+            t.check('12B (>8B) by-ref word 2', 0x7fffffff, dv12.getUint32(8, true));
+            const d3 = new PtrArrayBuffer(3);
+            cp3(d3, { p: 0xaa, q: 0xbb, r: 0xcc }, 3);
+            t.check('3B (odd size) by-ref bytes', 'AA,BB,CC', Array.from(new Uint8Array(d3)).map(x => x.toString(16).toUpperCase()).join(','));
+        }
+        else
+            t.skipCase('by-ref path: x64-only whitebox (ia32 pushes value bytes verbatim)');
     },
 };

package/test/test_ffi_abi.ts

@@ -1,7 +1,10 @@
 import * as std from 'std'
 import * as win from 'win'
+import * as os from 'os'
 import { bind } from '../lib/ffi/bind.js'
+import { struct } from '../lib/ffi/struct.js'
 import { NULL, PtrArrayBuffer } from '../lib/ffi/ctype.js'
+import { POINT, RECT } from '../lib/windows/structs.js'
 import { Tester } from './test_helper.js'
 
 // ABI 边界回归：覆盖 REMOVE_LIBFFI_PLAN.md §4.2 的维度，全部用真实 Win32/CRT
@@ -214,5 +217,58 @@ export const suite = {
             t.checkTrue('GetDC(undefined) rejected', errUndef.includes('undefined'))
             t.check('IsWindow(NULL) = FALSE', 0, isWindow(NULL))
         } else t.skipCase('GetDC/IsWindow missing')
+
+        t.section('by-value struct arg: <POINT> (slot value, not a pointer)')
+        if (has(usr, 'PtInRect') && has(usr, 'WindowFromPoint') && has(usr, 'ChildWindowFromPointEx')) {
+            // PtInRect(rect, pt)：RECT 按指针、POINT 按值（x64 位置寄存器 / ia32 压 8 字节上栈）。
+            // 非对称矩形 {0,0,10,100} —— 若 x/y 在打包中交换，(99,5) 与 (5,99) 的判定会互换，
+            // 本段即可抓出「槽内是地址而非值」「字段顺序/位置错」两类 ABI 错误。
+            const ptInRect = bind('user32.dll', 'PtInRect', '<RECT>ptr <POINT> -> i32', { RECT, POINT })
+            const rectOut = RECT.alloc()
+            const rdv = new DataView(rectOut)
+            rdv.setInt32(8, 10, true)     // right（left/top = 0，零填充）
+            rdv.setInt32(12, 100, true)   // bottom
+            t.check('PtInRect inside (5,5)', 1, ptInRect(rectOut.ptr, { x: 5, y: 5 }))
+            t.check('PtInRect inside (5,99)', 1, ptInRect(rectOut.ptr, { x: 5, y: 99 }))
+            t.check('PtInRect outside (99,5) — swap-sensitive', 0, ptInRect(rectOut.ptr, { x: 99, y: 5 }))
+            t.check('PtInRect outside x=10 (right edge exclusive)', 0, ptInRect(rectOut.ptr, { x: 10, y: 5 }))
+
+            // 位置 1（首参即结构）：WindowFromPoint(POINT) → 屏内必非 NULL
+            const getSystemMetrics = bind('user32.dll', 'GetSystemMetrics', 'i32 -> i32')
+            const cx = getSystemMetrics(0)      // SM_CXSCREEN
+            const cy = getSystemMetrics(1)      // SM_CYSCREEN
+            const windowFromPoint = bind('user32.dll', 'WindowFromPoint', '<POINT> -> <>ptr', { POINT })
+            t.checkTrue('WindowFromPoint(screen center) non-null', !!windowFromPoint({ x: cx >> 1, y: cy >> 1 }))
+
+            // 位置 2 + 其后参数推移（POINT 之后还有 UINT flags —— 槽宽算错会把 flags 读错位）
+            const childFromPointEx = bind('user32.dll', 'ChildWindowFromPointEx', '<>ptr <POINT> u32 -> <>ptr', { POINT })
+            const getDesktopWindow = bind('user32.dll', 'GetDesktopWindow', ' -> <>ptr')
+            const desk = getDesktopWindow()
+            t.checkTrue('ChildWindowFromPointEx inside → non-null', !!childFromPointEx(desk, { x: 1, y: 1 }, 0 /* CWP_ALL */))
+            t.check('ChildWindowFromPointEx outside → NULL', 0, childFromPointEx(desk, { x: cx + 100, y: cy + 100 }, 0 /* CWP_ALL */))
+        } else t.skipCase('PtInRect/WindowFromPoint/ChildWindowFromPointEx missing')
+
+        t.section('by-value struct >8B / odd size: x64 by-reference (caller temp)')
+        if (os.arch === 'x64' && has(crt, 'memcpy')) {
+            // MS x64：size ∉ {1,2,4,8} 的聚合体按引用传 —— 槽内是指向 caller 分配的
+            // 16 字节对齐临时副本的指针（单参数永不跨寄存器）。memcpy 第 2 参语义即
+            // 「源地址」，借它白盒验证整条 by-ref 路径：若槽内不是合法副本地址、或
+            // 字节未写进副本，拷回内容必错。ia32 按值恒把字节压栈（callee 读地址会
+            // 拿到垃圾值），故本段 x64 限定；ia32 侧由上面真实 API 段覆盖栈上传值。
+            const BYVAL12 = struct('BYVAL12', { a: 'u32', b: 'u32', c: 'u32' })
+            const BYVAL3 = struct('BYVAL3', { p: 'u8', q: 'u8', r: 'u8' })
+            const cp12 = bind('msvcrt.dll', 'memcpy', '<BYTE>ptr <BYVAL12> u32 -> <>ptr', { BYVAL12 })
+            const cp3 = bind('msvcrt.dll', 'memcpy', '<BYTE>ptr <BYVAL3> u32 -> <>ptr', { BYVAL3 })
+            const d12 = new PtrArrayBuffer(12)
+            cp12(d12, { a: 1, b: 0x11223344, c: 0x7fffffff }, 12)
+            const dv12 = new DataView(d12)
+            t.check('12B (>8B) by-ref word 0', 1, dv12.getUint32(0, true))
+            t.check('12B (>8B) by-ref word 1', 0x11223344, dv12.getUint32(4, true))
+            t.check('12B (>8B) by-ref word 2', 0x7fffffff, dv12.getUint32(8, true))
+            const d3 = new PtrArrayBuffer(3)
+            cp3(d3, { p: 0xaa, q: 0xbb, r: 0xcc }, 3)
+            t.check('3B (odd size) by-ref bytes', 'AA,BB,CC',
+                Array.from(new Uint8Array(d3)).map(x => x.toString(16).toUpperCase()).join(','))
+        } else t.skipCase('by-ref path: x64-only whitebox (ia32 pushes value bytes verbatim)')
     },
 }

package/test/test_ffi_array.js

@@ -0,0 +1,116 @@
+import { bind } from '../lib/ffi/bind.js';
+import { struct, structArray } from '../lib/ffi/struct.js';
+import { NULL, normToken, PtrArrayBuffer } from '../lib/ffi/ctype.js';
+function expectType(_value) { }
+// 运行时 throw 捕获：返回错误文本（无异常 → 空串）
+function throws(fn) {
+    try {
+        fn();
+        return '';
+    }
+    catch (e) {
+        return String(e);
+    }
+}
+const POINT = struct('POINT', { x: 'i32', y: 'i32' });
+const RECT = struct('RECT', { l: 'i32', t: 'i32', r: 'i32', b: 'i32' });
+// 数组编解码对：encode 注册进 encoders 表后 <POINT>ptr 位收元素数组；
+// decode 是出参数组读回（双态：buffer 自算/显式 count、裸地址 count 必填）
+const POINTArr = structArray(POINT);
+export const suite = {
+    name: 'ffi-array',
+    run: (t) => {
+        t.section("normToken: '*' is an ordinary out-of-lexicon char (same as '+')");
+        t.checkTrue("'<X*>ptr' rejected", throws(() => normToken('<POINT*>ptr')).includes('Unknown token'));
+        t.checkTrue("'*'+'!' rejected", throws(() => normToken('<POINT*>ptr!')).includes('Unknown token'));
+        t.checkTrue("'*'+'@' rejected", throws(() => normToken('<POINT*>ptr@Foo')).includes('Unknown token'));
+        t.checkTrue('bare <*>ptr rejected', throws(() => normToken('<*>ptr')).includes('Unknown token'));
+        t.checkTrue("'+' not in lexicon: generic Unknown token", throws(() => normToken('<POINT+>ptr')).includes('Unknown token'));
+        t.checkTrue('name charset tightened (non-identifier rejected)', throws(() => normToken('<1abc>ptr')).includes('Unknown token'));
+        t.check('plain <X>ptr unchanged', '<X>ptr', normToken('<X>ptr'));
+        t.check('!-form unchanged', '<X>ptr!', normToken('<X>ptr!'));
+        t.check('@-suffix stripped (enum annotation is type-layer only)', '<X>ptr', normToken('<X>ptr@Foo'));
+        t.section('type layer: registered encoder derives the array value domain');
+        // 注册数组 encoder 后：<POINT>ptr 位 = 非空元素数组（值域由 encoder 推导）∪ number 直通
+        const PolylineT = bind('gdi32.dll', 'Polyline', '<HDC>ptr! <POINT>ptr i32 -> i32', { POINT: POINTArr });
+        expectType();
+        expectType();
+        // 类型专用块（只过 tsc、不执行）
+        const typeOnly = () => {
+            // @ts-expect-error 单对象不是元素数组（encoder 值域收数组，不收裸 POINT）
+            PolylineT(0, { x: 1, y: 2 }, 1);
+            // @ts-expect-error 品牌拦错布局直传（RECT PAB 不是 POINT 位的值域——传 .ptr 走 number 直通）
+            PolylineT(0, RECT.alloc(), 1);
+            // @ts-expect-error decode 的裸地址形 count 必填（地址无长度信息）
+            POINTArr.decode(POINT.alloc().ptr);
+        };
+        t.checkTrue('type-only block wired', typeof typeOnly === 'function');
+        t.section('structArray.encode: contiguous branded materialization');
+        const pab = POINTArr.encode([{ x: 1, y: 2 }, { x: -3, y: 4 }]);
+        t.check('byteLength = n * size', 16, pab.byteLength);
+        const pdv = new DataView(pab);
+        t.check('[0].x', 1, pdv.getInt32(0, true));
+        t.check('[0].y', 2, pdv.getInt32(4, true));
+        t.check('[1].x', -3, pdv.getInt32(8, true));
+        t.check('[1].y', 4, pdv.getInt32(12, true));
+        t.checkTrue('PAB .ptr non-null (branded)', pab.ptr !== 0);
+        // fail-loud：值域刻意收普通数组（直传变量），空/非数组/单对象全靠运行时
+        // throw —— 任何路径都不产出 PAB(0)（其 .ptr 是"非 0 的 1 字节堆指针"，会骗过
+        // C 的 NULL 防御）。
+        t.checkTrue('[] fail-loud (never produces PAB(0))', throws(() => POINTArr.encode([])).includes('non-empty'));
+        t.checkTrue('non-array fail-loud', throws(() => POINTArr.encode(123)).includes('non-empty'));
+        t.section('structArray.decode: self-evident / explicit count / address form');
+        // 自算形态：纯元素序列 buffer（alloc）byteLength/size 整除自证
+        t.check('self-computed n = byteLength/size', 3, POINTArr.decode(POINT.alloc(3)).length);
+        const rt = POINTArr.decode(POINTArr.encode([{ x: 1, y: -2 }, { x: 3, y: 4 }]));
+        t.check('roundtrip [0].x', 1, rt[0].x);
+        t.check('roundtrip [1].y', 4, rt[1].y);
+        // 混合缓冲（byteLength 非整数倍，如 EnumPrinters 的结构 + 尾部字符串）自算 fail-loud
+        t.checkTrue('non-multiple byteLength fail-loud', throws(() => POINTArr.decode(new PtrArrayBuffer(7))).includes('multiple'));
+        // 显式 count 越界防线：count*size 超 byteLength → 拦死（写错 count 的越界读入口）
+        t.checkTrue('count beyond byteLength fail-loud', throws(() => POINTArr.decode(new PtrArrayBuffer(12), 2)).includes('exceeds'));
+        t.checkTrue('negative count fail-loud', throws(() => POINTArr.decode(new PtrArrayBuffer(16), -1)).includes('non-negative'));
+        t.check('count = 0 → []', 0, POINTArr.decode(POINT.alloc(), 0).length);
+        // 裸地址形（C 返回的 T* / 预建缓冲 .ptr）：count 必填，逐字节拷读
+        const addrBack = POINTArr.decode(pab.ptr, 2);
+        t.check('address form count', 2, addrBack.length);
+        t.check('address form [0].x', 1, addrBack[0].x);
+        t.checkTrue('address without count throws at runtime (dynamic path)', throws(() => POINTArr.decode(pab.ptr)).includes('count'));
+        t.section('StructDef.alloc(n): n-slot zero-filled (default 1)');
+        t.check('alloc() default = 1 slot', POINT.size, POINT.alloc().byteLength);
+        t.check('alloc(3) = 3 slots', POINT.size * 3, POINT.alloc(3).byteLength);
+        t.checkTrue('alloc slots zero-filled', new Int32Array(POINT.alloc(2))[3] === 0);
+        t.checkTrue('alloc(0) fail-loud (PAB(0) never escapes)', throws(() => POINT.alloc(0)).includes('n >= 1'));
+        t.checkTrue('alloc(-1) fail-loud', throws(() => POINT.alloc(-1)).includes('n >= 1'));
+        t.checkTrue('alloc(1.5) fail-loud', throws(() => POINT.alloc(1.5)).includes('n >= 1'));
+        t.section('StructDef.encode(v, buf, offset): positioned write primitive');
+        const big = POINT.alloc(2);
+        POINT.encode({ x: 7, y: -8 }, big, POINT.size); // 写入第 2 槽
+        const bdv = new DataView(big);
+        t.check('slot 0 stays zero', 0, bdv.getInt32(0, true));
+        t.check('slot 1.x written at offset', 7, bdv.getInt32(POINT.size, true));
+        t.check('slot 1.y written at offset', -8, bdv.getInt32(POINT.size + 4, true));
+        t.checkTrue('offset form returns the buf itself', POINT.encode({ x: 1, y: 2 }, big, 0) === big);
+        t.section('registered encoder dispatch: kernel32!IsBadReadPtr observes the pointer C gets');
+        const isBad = bind('kernel32.dll', 'IsBadReadPtr', '<POINT>ptr u64 -> i32', { POINT: POINTArr });
+        t.check('3-point array: whole 24-byte region readable', 0, isBad([{ x: 1, y: 2 }, { x: 3, y: 4 }, { x: 5, y: 6 }], 24n));
+        t.check('number passthrough: prebuilt PAB .ptr', 0, isBad(pab.ptr, 16n));
+        t.check('number passthrough: NULL literal', 1, isBad(NULL, 1n));
+        t.checkTrue('bare object rejected at encoder', throws(() => isBad({ x: 1, y: 2 }, 8n)).includes('non-empty'));
+        t.checkTrue('[] rejected at encoder (NULL stays explicit)', throws(() => isBad([], 8n)).includes('non-empty'));
+        t.checkTrue('null rejected with NULL hint', throws(() => isBad(null, 8n)).includes('NULL'));
+        t.section('content fidelity: msvcrt!memcpy reads encoder array source');
+        const memcpy = bind('msvcrt.dll', 'memcpy', '<POINT>ptr <POINT>ptr u64 -> <>ptr', { POINT: POINTArr });
+        const dst = POINT.alloc();
+        memcpy(dst.ptr, [{ x: 7, y: -8 }], 8n);
+        const back = POINT.decode(dst.ptr);
+        t.check('copied x', 7, back.x);
+        t.check('copied y', -8, back.y);
+        t.section("decode(alloc()): '!' unfilled field fails (C did not fill)");
+        const OutH = struct('OutH', { h: '<HANDLE>ptr!' });
+        t.checkTrue("'!' 0 slot throws on decode", throws(() => OutH.decode(OutH.alloc())).includes("'!'"));
+        t.section('bind-time lexicon checks (fail at module load)');
+        t.checkTrue('<POINT+>ptr rejected at bind (not in lexicon)', throws(() => bind('kernel32.dll', 'IsBadReadPtr', '<POINT+>ptr u64 -> i32', { POINT: POINTArr })).includes('Unknown token'));
+        t.checkTrue('<POINT*>ptr rejected at bind (out-of-lexicon)', throws(() => bind('kernel32.dll', 'IsBadReadPtr', '<POINT*>ptr u64 -> i32', { POINT: POINTArr })).includes('Unknown token'));
+    }
+};

package/test/test_ffi_array.ts

@@ -0,0 +1,141 @@
+import { Tester } from './test_helper.js'
+import { bind } from '../lib/ffi/bind.js'
+import { struct, structArray } from '../lib/ffi/struct.js'
+import { NULL, normToken, PtrArrayBuffer, type MaybePtr, type Ptr } from '../lib/ffi/ctype.js'
+
+// 编译期断言工具（仅类型层，运行时无开销）
+type Equal<A, B> = (<G>() => G extends A ? 1 : 2) extends (<G>() => G extends B ? 1 : 2) ? true : false
+function expectType<T extends true>(_value?: T): void {}
+
+// 运行时 throw 捕获：返回错误文本（无异常 → 空串）
+function throws(fn: () => unknown): string {
+    try { fn(); return '' } catch (e) { return String(e) }
+}
+
+const POINT = struct('POINT', { x: 'i32', y: 'i32' })
+const RECT = struct('RECT', { l: 'i32', t: 'i32', r: 'i32', b: 'i32' })
+// 数组编解码对：encode 注册进 encoders 表后 <POINT>ptr 位收元素数组；
+// decode 是出参数组读回（双态：buffer 自算/显式 count、裸地址 count 必填）
+const POINTArr = structArray(POINT)
+
+export const suite = {
+    name: 'ffi-array',
+    run: (t: Tester) => {
+        t.section("normToken: '*' is an ordinary out-of-lexicon char (same as '+')")
+        t.checkTrue("'<X*>ptr' rejected", throws(() => normToken('<POINT*>ptr')).includes('Unknown token'))
+        t.checkTrue("'*'+'!' rejected", throws(() => normToken('<POINT*>ptr!')).includes('Unknown token'))
+        t.checkTrue("'*'+'@' rejected", throws(() => normToken('<POINT*>ptr@Foo')).includes('Unknown token'))
+        t.checkTrue('bare <*>ptr rejected', throws(() => normToken('<*>ptr')).includes('Unknown token'))
+        t.checkTrue("'+' not in lexicon: generic Unknown token", throws(() => normToken('<POINT+>ptr')).includes('Unknown token'))
+        t.checkTrue('name charset tightened (non-identifier rejected)',
+            throws(() => normToken('<1abc>ptr')).includes('Unknown token'))
+        t.check('plain <X>ptr unchanged', '<X>ptr', normToken('<X>ptr'))
+        t.check('!-form unchanged', '<X>ptr!', normToken('<X>ptr!'))
+        t.check('@-suffix stripped (enum annotation is type-layer only)', '<X>ptr', normToken('<X>ptr@Foo'))
+
+        t.section('type layer: registered encoder derives the array value domain')
+        // 注册数组 encoder 后：<POINT>ptr 位 = 非空元素数组（值域由 encoder 推导）∪ number 直通
+        const PolylineT = bind('gdi32.dll', 'Polyline', '<HDC>ptr! <POINT>ptr i32 -> i32', { POINT: POINTArr })
+        expectType<Equal<Parameters<typeof PolylineT>[1],
+            readonly { readonly x?: number | undefined; readonly y?: number | undefined }[] | MaybePtr<'POINT'>>>()
+        expectType<Equal<Parameters<typeof PolylineT>[0], Ptr<'HDC'>>>()
+        // 类型专用块（只过 tsc、不执行）
+        const typeOnly: unknown = () => {
+            // @ts-expect-error 单对象不是元素数组（encoder 值域收数组，不收裸 POINT）
+            PolylineT(0 as Ptr<'HDC'>, { x: 1, y: 2 }, 1)
+            // @ts-expect-error 品牌拦错布局直传（RECT PAB 不是 POINT 位的值域——传 .ptr 走 number 直通）
+            PolylineT(0 as Ptr<'HDC'>, RECT.alloc(), 1)
+            // @ts-expect-error decode 的裸地址形 count 必填（地址无长度信息）
+            POINTArr.decode(POINT.alloc().ptr)
+        }
+        t.checkTrue('type-only block wired', typeof typeOnly === 'function')
+
+        t.section('structArray.encode: contiguous branded materialization')
+        const pab = POINTArr.encode([{ x: 1, y: 2 }, { x: -3, y: 4 }])
+        t.check('byteLength = n * size', 16, pab.byteLength)
+        const pdv = new DataView(pab)
+        t.check('[0].x', 1, pdv.getInt32(0, true))
+        t.check('[0].y', 2, pdv.getInt32(4, true))
+        t.check('[1].x', -3, pdv.getInt32(8, true))
+        t.check('[1].y', 4, pdv.getInt32(12, true))
+        t.checkTrue('PAB .ptr non-null (branded)', pab.ptr !== 0)
+        // fail-loud：值域刻意收普通数组（直传变量），空/非数组/单对象全靠运行时
+        // throw —— 任何路径都不产出 PAB(0)（其 .ptr 是"非 0 的 1 字节堆指针"，会骗过
+        // C 的 NULL 防御）。
+        t.checkTrue('[] fail-loud (never produces PAB(0))',
+            throws(() => POINTArr.encode([])).includes('non-empty'))
+        t.checkTrue('non-array fail-loud',
+            throws(() => POINTArr.encode(123 as never)).includes('non-empty'))
+
+        t.section('structArray.decode: self-evident / explicit count / address form')
+        // 自算形态：纯元素序列 buffer（alloc）byteLength/size 整除自证
+        t.check('self-computed n = byteLength/size', 3, POINTArr.decode(POINT.alloc(3)).length)
+        const rt = POINTArr.decode(POINTArr.encode([{ x: 1, y: -2 }, { x: 3, y: 4 }]))
+        t.check('roundtrip [0].x', 1, rt[0]!.x)
+        t.check('roundtrip [1].y', 4, rt[1]!.y)
+        // 混合缓冲（byteLength 非整数倍，如 EnumPrinters 的结构 + 尾部字符串）自算 fail-loud
+        t.checkTrue('non-multiple byteLength fail-loud',
+            throws(() => POINTArr.decode(new PtrArrayBuffer(7))).includes('multiple'))
+        // 显式 count 越界防线：count*size 超 byteLength → 拦死（写错 count 的越界读入口）
+        t.checkTrue('count beyond byteLength fail-loud',
+            throws(() => POINTArr.decode(new PtrArrayBuffer(12), 2)).includes('exceeds'))
+        t.checkTrue('negative count fail-loud',
+            throws(() => POINTArr.decode(new PtrArrayBuffer(16), -1)).includes('non-negative'))
+        t.check('count = 0 → []', 0, POINTArr.decode(POINT.alloc(), 0).length)
+        // 裸地址形（C 返回的 T* / 预建缓冲 .ptr）：count 必填，逐字节拷读
+        const addrBack = POINTArr.decode(pab.ptr, 2)
+        t.check('address form count', 2, addrBack.length)
+        t.check('address form [0].x', 1, addrBack[0]!.x)
+        t.checkTrue('address without count throws at runtime (dynamic path)',
+            throws(() => (POINTArr.decode as unknown as (p: number) => unknown[])(pab.ptr)).includes('count'))
+
+        t.section('StructDef.alloc(n): n-slot zero-filled (default 1)')
+        t.check('alloc() default = 1 slot', POINT.size, POINT.alloc().byteLength)
+        t.check('alloc(3) = 3 slots', POINT.size * 3, POINT.alloc(3).byteLength)
+        t.checkTrue('alloc slots zero-filled', new Int32Array(POINT.alloc(2))[3] === 0)
+        t.checkTrue('alloc(0) fail-loud (PAB(0) never escapes)',
+            throws(() => POINT.alloc(0)).includes('n >= 1'))
+        t.checkTrue('alloc(-1) fail-loud', throws(() => POINT.alloc(-1)).includes('n >= 1'))
+        t.checkTrue('alloc(1.5) fail-loud', throws(() => POINT.alloc(1.5)).includes('n >= 1'))
+
+        t.section('StructDef.encode(v, buf, offset): positioned write primitive')
+        const big = POINT.alloc(2)
+        POINT.encode({ x: 7, y: -8 }, big, POINT.size)   // 写入第 2 槽
+        const bdv = new DataView(big)
+        t.check('slot 0 stays zero', 0, bdv.getInt32(0, true))
+        t.check('slot 1.x written at offset', 7, bdv.getInt32(POINT.size, true))
+        t.check('slot 1.y written at offset', -8, bdv.getInt32(POINT.size + 4, true))
+        t.checkTrue('offset form returns the buf itself', POINT.encode({ x: 1, y: 2 }, big, 0) === big)
+
+        t.section('registered encoder dispatch: kernel32!IsBadReadPtr observes the pointer C gets')
+        const isBad = bind('kernel32.dll', 'IsBadReadPtr', '<POINT>ptr u64 -> i32', { POINT: POINTArr })
+        t.check('3-point array: whole 24-byte region readable', 0, isBad([{ x: 1, y: 2 }, { x: 3, y: 4 }, { x: 5, y: 6 }], 24n))
+        t.check('number passthrough: prebuilt PAB .ptr', 0, isBad(pab.ptr, 16n))
+        t.check('number passthrough: NULL literal', 1, isBad(NULL, 1n))
+        t.checkTrue('bare object rejected at encoder',
+            throws(() => isBad({ x: 1, y: 2 } as never, 8n)).includes('non-empty'))
+        t.checkTrue('[] rejected at encoder (NULL stays explicit)',
+            throws(() => isBad([], 8n)).includes('non-empty'))
+        t.checkTrue('null rejected with NULL hint',
+            throws(() => isBad(null as never, 8n)).includes('NULL'))
+
+        t.section('content fidelity: msvcrt!memcpy reads encoder array source')
+        const memcpy = bind('msvcrt.dll', 'memcpy', '<POINT>ptr <POINT>ptr u64 -> <>ptr', { POINT: POINTArr })
+        const dst = POINT.alloc()
+        memcpy(dst.ptr, [{ x: 7, y: -8 }], 8n)
+        const back = POINT.decode(dst.ptr)
+        t.check('copied x', 7, back.x)
+        t.check('copied y', -8, back.y)
+
+        t.section("decode(alloc()): '!' unfilled field fails (C did not fill)")
+        const OutH = struct('OutH', { h: '<HANDLE>ptr!' })
+        t.checkTrue("'!' 0 slot throws on decode",
+            throws(() => OutH.decode(OutH.alloc())).includes("'!'"))
+
+        t.section('bind-time lexicon checks (fail at module load)')
+        t.checkTrue('<POINT+>ptr rejected at bind (not in lexicon)',
+            throws(() => bind('kernel32.dll', 'IsBadReadPtr', '<POINT+>ptr u64 -> i32', { POINT: POINTArr })).includes('Unknown token'))
+        t.checkTrue('<POINT*>ptr rejected at bind (out-of-lexicon)',
+            throws(() => bind('kernel32.dll', 'IsBadReadPtr', '<POINT*>ptr u64 -> i32', { POINT: POINTArr })).includes('Unknown token'))
+    }
+}

package/test/test_ffi_bind.js

@@ -289,6 +289,63 @@ export const suite = {
         t.checkTrue('GetWindowRect(hwnd, RECT.alloc().ptr) succeeds', getWindowRect(desktop, rectOut.ptr) !== 0);
         const rectV = RECT.decode(rectOut);
         t.checkTrue('RECT.decode(encode()) decodes out-param', rectV.right > rectV.left && rectV.bottom > rectV.top);
+        t.section('by-value struct <N>: lexicon / type layer / bind-time fail-loud');
+        // '<N>' 裸品牌 = 按值传参位（<N>ptr 传地址）。无修饰可剥：带 ! / 尾缀 / 空名 /
+        // 数字开头的形正则不匹配，落绑定期通用 Unknown token（与 '<X+>ptr' 同策略）。
+        t.checkTrue("normToken('<POINT>') 原样归一", normToken('<POINT>') === '<POINT>');
+        for (const bad of ['<POINT>!', '<POINT>x', '<>', '<1abc>']) {
+            try {
+                normToken(bad);
+                t.checkTrue(`normToken 拒 '${bad}'`, false);
+            }
+            catch (e) {
+                t.checkTrue(`normToken 拒 '${bad}'`, String(e).includes('Unknown token'));
+            }
+        }
+        // 类型层：未注册布局的按值位塌 never（LE={} → L['POINT'] = never，同拼错 token 策略）
+        expectType();
+        // 注册布局：值域 = encode 入参形（对象），无 number 地址直通；ptr 位对照有
+        const typeOnly = () => {
+            const byVal = bind('user32.dll', 'PtInRect', '<RECT>ptr <POINT> -> i32', { RECT, POINT });
+            expectType();
+            const byPtr = bind('user32.dll', 'PtInRect', '<RECT>ptr <POINT>ptr -> i32', { RECT, POINT });
+            expectType();
+            // @ts-expect-error 按值位不收 number（地址词汇属 <N>ptr 位）
+            byVal(NULL, 42);
+            // @ts-expect-error 按值位收对象、不收数组
+            byVal(NULL, [1, 2]);
+            return 0;
+        };
+        t.checkTrue('type-only block wired', typeof typeOnly === 'function');
+        // 绑定期 fail-loud：模块加载即炸，不留到首个调用
+        try {
+            bind('gdi32.dll', 'DeleteObject', '<PTMISS> -> i32');
+            t.checkTrue('by-value 未注册布局 fail-loud', false);
+        }
+        catch (e) {
+            t.checkTrue('by-value 未注册布局 fail-loud', String(e).includes('<PTMISS>'));
+        }
+        try {
+            bind('gdi32.dll', 'DeleteObject', '<WCHAR> -> i32', { WCHAR });
+            t.checkTrue('by-value 非结构 codec (无 size) fail-loud', false);
+        }
+        catch (e) {
+            t.checkTrue('by-value 非结构 codec (无 size) fail-loud', String(e).includes('size'));
+        }
+        try {
+            bind('gdi32.dll', 'DeleteObject', 'i32 -> <POINT>', { POINT });
+            t.checkTrue('by-value 返回位 fail-loud', false);
+        }
+        catch (e) {
+            t.checkTrue('by-value 返回位 fail-loud', String(e).includes('return position'));
+        }
+        try {
+            closure('<POINT> -> i32', () => 0);
+            t.checkTrue('by-value 位 closure fail-loud', false);
+        }
+        catch (e) {
+            t.checkTrue('by-value 位 closure fail-loud', String(e).includes('closure'));
+        }
         // 成员 '<RECT>ptr'：decode 得到 Ptr<'RECT'>，可直接喂 <RECT>ptr 形参（品牌在类型层流动）。
         const RECTPTR = struct('RECTPTR', { r: '<RECT>ptr' });
         const box = RECTPTR.decode(RECTPTR.encode({ r: rectOut.ptr }));
@@ -334,6 +391,10 @@ export const suite = {
         // （返回若含 Ptr<'TM'> 分支——无 decode 的旧行为——此访问编译不过）
         if (tmObj !== 0)
             expectType(true);
+        // gmtime 同构第二例：UTC 锚点确定（time_t=0 → 1970-01-01，不依赖 TZ 环境）
+        const gmtimeDec = bind('msvcrt.dll', 'gmtime', '<BYTE>ptr -> <TM>ptr', undefined, { TM });
+        const gmObj = gmtimeDec(tbuf);
+        t.checkTrue('gmtime + decoders auto-decodes (UTC anchor tm_year=70, tm_mday=1)', gmObj !== 0 && gmObj.tm_year === 70 && gmObj.tm_mday === 1);
         expectType(true);
         expectType(true);
         expectType(true);
@@ -362,6 +423,27 @@ export const suite = {
             outOnlyErr = String(e);
         }
         t.checkTrue('out-only codec rejected at encode time', outOnlyErr.includes('no encoder'));
+        // native readBytes：批量 memcpy 往返 + fail-loud 守卫（decode 指针分支的新底层）
+        const rbB = new PtrArrayBuffer(8);
+        new Uint8Array(rbB).set([1, 2, 3, 4, 250, 251, 252, 253]);
+        const rbCopy = ffi.readBytes(rbB.ptr, 8);
+        t.check('readBytes(ptr, 8) memcpy roundtrip', '1,2,3,4,250,251,252,253', new Uint8Array(rbCopy).join(','));
+        let rbNullErr = '';
+        try {
+            ffi.readBytes(0, 4);
+        }
+        catch (e) {
+            rbNullErr = String(e);
+        }
+        t.checkTrue('readBytes(0, n) fails loud (null pointer)', rbNullErr.includes('null pointer'));
+        let rbNegErr = '';
+        try {
+            ffi.readBytes(rbB.ptr, -1);
+        }
+        catch (e) {
+            rbNegErr = String(e);
+        }
+        t.checkTrue('readBytes(p, -1) fails loud (RangeError)', rbNegErr.includes('RangeError'));
         t.section('closures: direct ABI drive via ffiCall');
         const addClos = closure('i32 i32 -> i32', (a, b) => a + b);
         const r1 = new ArrayBuffer(8);

package/test/test_ffi_bind.ts

@@ -286,6 +286,58 @@ export const suite = {
         const rectV = RECT.decode(rectOut)
         t.checkTrue('RECT.decode(encode()) decodes out-param', rectV.right > rectV.left && rectV.bottom > rectV.top)
 
+        t.section('by-value struct <N>: lexicon / type layer / bind-time fail-loud')
+        // '<N>' 裸品牌 = 按值传参位（<N>ptr 传地址）。无修饰可剥：带 ! / 尾缀 / 空名 /
+        // 数字开头的形正则不匹配，落绑定期通用 Unknown token（与 '<X+>ptr' 同策略）。
+        t.checkTrue("normToken('<POINT>') 原样归一", normToken('<POINT>') === '<POINT>')
+        for (const bad of ['<POINT>!', '<POINT>x', '<>', '<1abc>']) {
+            try { normToken(bad); t.checkTrue(`normToken 拒 '${bad}'`, false) }
+            catch (e) { t.checkTrue(`normToken 拒 '${bad}'`, String(e).includes('Unknown token')) }
+        }
+
+        // 类型层：未注册布局的按值位塌 never（LE={} → L['POINT'] = never，同拼错 token 策略）
+        expectType<Equal<ParamsOf<'<POINT> -> i32'>[0], never>>()
+        // 注册布局：值域 = encode 入参形（对象），无 number 地址直通；ptr 位对照有
+        const typeOnly: unknown = () => {
+            const byVal = bind('user32.dll', 'PtInRect', '<RECT>ptr <POINT> -> i32', { RECT, POINT })
+            expectType<Equal<Extract<Parameters<typeof byVal>[1], number>, never>>()
+            const byPtr = bind('user32.dll', 'PtInRect', '<RECT>ptr <POINT>ptr -> i32', { RECT, POINT })
+            expectType<Extract<Parameters<typeof byPtr>[1], number> extends never ? false : true>()
+            // @ts-expect-error 按值位不收 number（地址词汇属 <N>ptr 位）
+            byVal(NULL, 42)
+            // @ts-expect-error 按值位收对象、不收数组
+            byVal(NULL, [1, 2])
+            return 0
+        }
+        t.checkTrue('type-only block wired', typeof typeOnly === 'function')
+
+        // 绑定期 fail-loud：模块加载即炸，不留到首个调用
+        try {
+            bind('gdi32.dll', 'DeleteObject', '<PTMISS> -> i32')
+            t.checkTrue('by-value 未注册布局 fail-loud', false)
+        } catch (e) {
+            t.checkTrue('by-value 未注册布局 fail-loud', String(e).includes('<PTMISS>'))
+        }
+        try {
+            bind('gdi32.dll', 'DeleteObject', '<WCHAR> -> i32', { WCHAR })
+            t.checkTrue('by-value 非结构 codec (无 size) fail-loud', false)
+        } catch (e) {
+            t.checkTrue('by-value 非结构 codec (无 size) fail-loud', String(e).includes('size'))
+        }
+        try {
+            bind('gdi32.dll', 'DeleteObject', 'i32 -> <POINT>', { POINT })
+            t.checkTrue('by-value 返回位 fail-loud', false)
+        } catch (e) {
+            t.checkTrue('by-value 返回位 fail-loud', String(e).includes('return position'))
+        }
+        try {
+            closure('<POINT> -> i32', () => 0)
+            t.checkTrue('by-value 位 closure fail-loud', false)
+        } catch (e) {
+            t.checkTrue('by-value 位 closure fail-loud', String(e).includes('closure'))
+        }
+
+
         // 成员 '<RECT>ptr'：decode 得到 Ptr<'RECT'>，可直接喂 <RECT>ptr 形参（品牌在类型层流动）。
         const RECTPTR = struct('RECTPTR', {r: '<RECT>ptr'})
         const box = RECTPTR.decode(RECTPTR.encode({ r: rectOut.ptr }))
@@ -336,6 +388,12 @@ export const suite = {
         // （返回若含 Ptr<'TM'> 分支——无 decode 的旧行为——此访问编译不过）
         if (tmObj !== 0) expectType<Equal<typeof tmObj.tm_sec, number>>(true)
 
+        // gmtime 同构第二例：UTC 锚点确定（time_t=0 → 1970-01-01，不依赖 TZ 环境）
+        const gmtimeDec = bind('msvcrt.dll', 'gmtime', '<BYTE>ptr -> <TM>ptr', undefined, { TM })
+        const gmObj = gmtimeDec(tbuf)
+        t.checkTrue('gmtime + decoders auto-decodes (UTC anchor tm_year=70, tm_mday=1)',
+            gmObj !== 0 && gmObj.tm_year === 70 && gmObj.tm_mday === 1)
+
         // Codec：返回位类型断言（decoders 显式 / 缺省回退 encoders）
         // 断言「替换语义」两半：解码结果 = 结构对象 | 0（Ptr 品牌被替换掉）；
         // 无 decode 保留 0 | Ptr 品牌形态。
@@ -377,6 +435,19 @@ export const suite = {
         }
         t.checkTrue('out-only codec rejected at encode time', outOnlyErr.includes('no encoder'))
 
+        // native readBytes：批量 memcpy 往返 + fail-loud 守卫（decode 指针分支的新底层）
+        const rbB = new PtrArrayBuffer(8)
+        new Uint8Array(rbB).set([1, 2, 3, 4, 250, 251, 252, 253])
+        const rbCopy = ffi.readBytes(rbB.ptr, 8)
+        t.check('readBytes(ptr, 8) memcpy roundtrip',
+            '1,2,3,4,250,251,252,253', new Uint8Array(rbCopy).join(','))
+        let rbNullErr = ''
+        try { ffi.readBytes(0, 4) } catch (e) { rbNullErr = String(e) }
+        t.checkTrue('readBytes(0, n) fails loud (null pointer)', rbNullErr.includes('null pointer'))
+        let rbNegErr = ''
+        try { ffi.readBytes(rbB.ptr, -1) } catch (e) { rbNegErr = String(e) }
+        t.checkTrue('readBytes(p, -1) fails loud (RangeError)', rbNegErr.includes('RangeError'))
+
         t.section('closures: direct ABI drive via ffiCall')
         const addClos = closure('i32 i32 -> i32', (a, b) => a + b)
         const r1 = new ArrayBuffer(8)