quickwin 1.3.0 → 2.1.0

package/test/test_ffi_user32.ts

@@ -0,0 +1,113 @@
+import { Tester } from './test_helper.js'
+import { closure, WCHAR } from '../lib/ffi/bind.js'
+import { NULL, PtrArrayBuffer } from '../lib/ffi/ctype.js'
+import {
+    GetDesktopWindow, IsWindow, IsWindowVisible, GetSystemMetrics, GetClientRect,
+    GetWindowTextLength, GetClassName, FindWindow, SetTimer, KillTimer,
+    GetKeyState, LoadCursor, SetCursor, GetMenu, DestroyMenu, GetForegroundWindow,
+    GetDC, ReleaseDC, EnumWindows, FindWindowEx,
+} from '../lib/windows/user32.js'
+import { RECT } from '../lib/windows/structs.js'
+
+export const suite = {
+    run(t: Tester) {
+        t.section('user32: 窗口 / 度量')
+        const desk = GetDesktopWindow()
+        t.checkTrue('GetDesktopWindow 非 0', desk !== 0)
+        if (desk === 0) return
+        t.check('IsWindow(desktop)', 1, IsWindow(desk))
+        t.check('IsWindowVisible(desktop)', 1, IsWindowVisible(desk))
+        t.checkTrue('GetSystemMetrics(SM_CXSCREEN) > 0', GetSystemMetrics(0) > 0)
+        t.checkTrue('GetForegroundWindow 形态 number',
+            typeof GetForegroundWindow() === 'number')
+
+        t.section('user32: RECT 出参（encode → call → decode 字段直读）')
+        const rectOut = RECT.alloc()
+        t.check('GetClientRect(desktop)', 1, GetClientRect(desk, rectOut.ptr))
+        const rect = RECT.decode(rectOut)
+        t.check('客户区宽 = SM_CXSCREEN', GetSystemMetrics(0), rect.right - rect.left)
+        t.check('客户区高 = SM_CYSCREEN', GetSystemMetrics(1), rect.bottom - rect.top)
+
+        t.section('user32: 字符串出参（宽字符 buffer 读回）')
+        t.checkTrue('GetWindowTextLength ≥ 0', GetWindowTextLength(desk) >= 0)
+        const cls = new PtrArrayBuffer(64)
+        const n = GetClassName(desk, cls, 32)
+        t.checkTrue('GetClassName 写入长度 > 0', n > 0)
+        const cdv = new DataView(cls)
+        let clsName = ''
+        for (let i = 0; i < n; i++) clsName += String.fromCharCode(cdv.getUint16(i * 2, true))
+        t.checkTrue('类名非空', clsName.length > 0)
+        // JSDoc 文档化流（L4）：WCHAR.alloc(n) 当 out buffer、WCHAR.decode(buf) 读回
+        const clsH = WCHAR.alloc(32)
+        t.checkTrue('WCHAR.alloc out 写入长度 > 0', GetClassName(desk, clsH, 32) > 0)
+        t.check('WCHAR.decode(buf) 读回类名', clsName, WCHAR.decode(clsH))
+
+        t.section('user32: FindWindow（<WCHAR>ptr 的 NULL 与 string 双形态）')
+        const fw = FindWindow(NULL, NULL)
+        t.checkTrue('FindWindow(NULL, NULL) 形态 number（NULL 实参不 throw）',
+            typeof fw === 'number')
+        t.check('FindWindow(不存在类名, NULL)', 0, FindWindow('qw_no_such_class_xyz', NULL))
+
+        t.section('user32: 计时器')
+        const tid = SetTimer(NULL, 0, 50, NULL)
+        t.checkTrue('SetTimer 返回非 0 id', tid !== 0)
+        if (tid !== 0) t.checkTrue('KillTimer 成功', KillTimer(NULL, tid) !== 0)
+
+        t.section('user32: 输入 / 光标 / 菜单')
+        t.checkTrue('GetKeyState 返回整数', Number.isInteger(GetKeyState(0x1b)))
+        t.checkTrue('LoadCursor(NULL, IDC_ARROW=32512) 非 0', LoadCursor(NULL, 32512) !== 0)
+        // 品牌流动（正例）：LoadCursor 返回 MaybePtr<'HCURSOR'> 直接喂 SetCursor 形参（先收窄空位）
+        const arrow = LoadCursor(NULL, 32512)
+        const prevCur = arrow !== 0 ? SetCursor(arrow) : null
+        t.checkTrue('SetCursor(LoadCursor(...)) 返回句柄形态',
+            arrow !== 0 && (prevCur === null || typeof prevCur === 'number'))
+        t.check('GetMenu(desktop) 无菜单 → 0', 0, GetMenu(desk))
+
+        t.section('user32: GetDC / ReleaseDC 配对')
+        const hdc = GetDC(NULL)
+        t.checkTrue('GetDC(NULL) 非 0', hdc !== 0)
+        t.checkTrue('ReleaseDC(NULL, hdc) 成功', hdc !== 0 && ReleaseDC(NULL, hdc) !== 0)
+
+        // 仅类型层反例（不执行）：异种句柄互传、<>ptr 误传品牌位都应编译不过
+        const _typeOnly = () => {
+            // @ts-expect-error Ptr<>（number）不是 Ptr<'HDC'>，误传桌面句柄应编译不过
+            ReleaseDC(NULL, GetDesktopWindow())
+            // @ts-expect-error Ptr<'HWND'> 不是 Ptr<'HCURSOR'>，窗口句柄喂 SetCursor 应编译不过
+            SetCursor(GetDesktopWindow())
+            // @ts-expect-error Ptr<'HWND'> 不是 Ptr<'HMENU'>，窗口句柄喂 DestroyMenu 应编译不过
+            DestroyMenu(GetDesktopWindow())
+            // @ts-expect-error Ptr<'HMENU'> 不是 Ptr<'HWND'>，菜单句柄喂 IsWindow 应编译不过
+            IsWindow(GetMenu(desk))
+            // @ts-expect-error 出参位未注册 encoder：<RECT>ptr 只收 MaybePtr<'RECT'>（NULL|Ptr），裸 ArrayBuffer 编译不过
+            GetClientRect(desk, new ArrayBuffer(16))
+            // @ts-expect-error 裸 number 缺 Ptr<'RECT'> 品牌
+            GetClientRect(desk, 123)
+            // 正例：同种品牌流动（GetMenu → DestroyMenu）通过——上面反例的成立依赖这层区分
+            const m = GetMenu(desk)
+            if (m !== 0) DestroyMenu(m)
+        }
+        void _typeOnly
+
+        t.section('user32: EnumWindows（<>ptr 回调端到端）')
+        let count = 0
+        const enumClos = closure('<>ptr <>ptr -> i32', () => { count++; return 1 })
+        t.check('EnumWindows 返回 1（枚举完成）', 1, EnumWindows(enumClos.ptr, NULL))
+        t.checkTrue('回调计数 ≥ 1', count >= 1)
+        enumClos.dispose()
+
+        // EnumWindows（快照）与 FindWindowEx(NULL, prev) 链式遍历应得到同一组顶层窗口（实测两者顺序不同，
+        // 所以只比集合，不比顺序）。
+        // 回调只收集：回调内抛异常会被吞成返回 0（枚举静默提前结束），所以不在回调里做别的。
+        t.section('user32: EnumWindows ≡ FindWindowEx 链遍历（顶层窗口集合）')
+        const viaEnum: number[] = []
+        const collect = closure('<HWND>ptr <>ptr -> i32', (h) => { viaEnum.push(h); return 1 })
+        try { EnumWindows(collect.ptr, NULL) } finally { collect.dispose() }
+        const viaChain: number[] = []
+        for (let h = FindWindowEx(NULL, NULL, NULL, NULL); h && viaChain.length < 100000;
+            h = FindWindowEx(NULL, h, NULL, NULL)) viaChain.push(h)
+        t.checkTrue('两种遍历都非空', viaEnum.length > 0 && viaChain.length > 0)
+        t.check('窗口数量一致', viaEnum.length, viaChain.length)
+        const sorted = (a: number[]): string => a.slice().sort((x, y) => x - y).join(',')
+        t.check('窗口集合一致（忽略顺序）', sorted(viaEnum), sorted(viaChain))
+    },
+}

package/test/test_ffi_windows.js

@@ -0,0 +1,101 @@
+import { NULL } from '../lib/ffi/ctype.js';
+import { GetDesktopWindow, CreatePopupMenu, DestroyMenu, GetDC, ReleaseDC, LoadImage, LoadImageOrdinal, SetScrollInfo, GetScrollInfo, } from '../lib/windows/user32.js';
+import { GetDeviceCaps, CreateSolidBrush, DeleteObject, CreateFontIndirect, GetObject, SelectObject, CreateCompatibleDC, DeleteDC, } from '../lib/windows/gdi32.js';
+import { ImageListCreate, ImageListDestroy } from '../lib/windows/comctl32.js';
+import { LOGFONTW, SCROLLINFO } from '../lib/windows/structs.js';
+export const suite = {
+    run(t) {
+        // 本文件 import 三个 dll 模块即在加载时执行全部 bind：proc 名错误 → GetProcAddress 失败 →
+        // 模块加载 throw → run.ts 静默跳过本 suite → 总计数低于基线（判据链对比计数即暴露）
+        t.section('gdi32: 画刷 / 字体 创建-删除往返（LOGFONTW 对象直传）');
+        const brush = CreateSolidBrush(0x3366ff);
+        t.checkTrue('CreateSolidBrush 非 0', brush !== 0);
+        if (brush !== 0)
+            t.checkTrue('DeleteObject(brush) 成功', DeleteObject(brush) !== 0);
+        // DeepPartial 缺省字段跳过：lfHeight + lfFaceName 必给，其余标量保持 0（FW_DONTCARE 等合法零值）
+        const font = CreateFontIndirect({ lfHeight: -16, lfWeight: 400, lfCharSet: 1, lfFaceName: 'Arial' });
+        t.checkTrue('CreateFontIndirect(DeepPartial LOGFONTW) 非 0', font !== 0);
+        if (font !== 0)
+            t.checkTrue('DeleteObject(font) 成功', DeleteObject(font) !== 0);
+        // react-qw ListView.getCellFont 的流程：GetObject 读出现有字体 → decode → 叠加粗/斜/下划线 → 重建 → 回读
+        t.section('gdi32: 字体读出-改写-重建往返（GetObject → decode → CreateFontIndirect → GetObject）');
+        const base = CreateFontIndirect({ lfHeight: -18, lfWeight: 400, lfCharSet: 1, lfFaceName: 'Arial' });
+        if (base !== 0) {
+            const lf0 = LOGFONTW.alloc();
+            t.checkTrue('GetObject(font) 写入 LOGFONTW.size 字节', GetObject(base, LOGFONTW.size, lf0) === LOGFONTW.size);
+            const b0 = LOGFONTW.decode(lf0);
+            t.check('读出 lfHeight', -18, b0.lfHeight);
+            t.check('读出 lfWeight', 400, b0.lfWeight);
+            t.check('读出 lfItalic（未设）', 0, b0.lfItalic);
+            const styled = CreateFontIndirect({ ...b0, lfWeight: 700, lfItalic: 1, lfUnderline: 1 });
+            t.checkTrue('叠加样式后重建非 0', styled !== 0);
+            if (styled !== 0) {
+                const lf1 = LOGFONTW.alloc();
+                GetObject(styled, LOGFONTW.size, lf1);
+                const b1 = LOGFONTW.decode(lf1);
+                t.check('重建后 lfWeight', 700, b1.lfWeight);
+                t.check('重建后 lfItalic', 1, b1.lfItalic);
+                t.check('重建后 lfUnderline', 1, b1.lfUnderline);
+                t.check('底字体的 lfHeight 保留', -18, b1.lfHeight);
+                t.check('底字体的 lfCharSet 保留', 1, b1.lfCharSet);
+                t.check('底字体的字体名保留', b0.lfFaceName, b1.lfFaceName);
+                t.checkTrue('DeleteObject(styled) 成功', DeleteObject(styled) !== 0);
+            }
+            t.checkTrue('DeleteObject(base) 成功', DeleteObject(base) !== 0);
+        }
+        // 内存 DC 选入字体：SelectObject 返回被替换的旧对象，选回后可删除新对象（截屏与 ListView 自绘共用）
+        t.section('gdi32: CreateCompatibleDC / SelectObject 往返');
+        const memDc = CreateCompatibleDC(NULL);
+        t.checkTrue('CreateCompatibleDC(NULL) 非 0', memDc !== 0);
+        if (memDc !== 0) {
+            const f2 = CreateFontIndirect({ lfHeight: -12, lfFaceName: 'Arial' });
+            if (f2 !== 0) {
+                const old = SelectObject(memDc, f2);
+                t.checkTrue('SelectObject 返回旧对象非 0', old !== 0);
+                t.check('再选回旧对象，返回刚选入的字体', f2, SelectObject(memDc, old));
+                t.checkTrue('DeleteObject(f2) 成功', DeleteObject(f2) !== 0);
+            }
+            t.checkTrue('DeleteDC 成功', DeleteDC(memDc) !== 0);
+        }
+        t.section('gdi32: GetDeviceCaps（<HDC>ptr 跨 user32 品牌互认）');
+        const hdc = GetDC(NULL);
+        t.checkTrue('GetDC(NULL) 非 0', hdc !== 0);
+        if (hdc !== 0)
+            t.checkTrue('GetDeviceCaps(hdc, LOGPIXELSX) > 0', GetDeviceCaps(hdc, 88) > 0);
+        t.checkTrue('ReleaseDC(NULL, hdc) 成功', hdc !== 0 && ReleaseDC(NULL, hdc) !== 0);
+        t.section('user32: 弹出菜单往返');
+        const pm = CreatePopupMenu();
+        t.checkTrue('CreatePopupMenu 非 0', pm !== 0);
+        if (pm !== 0)
+            t.checkTrue('DestroyMenu(pm) 成功', DestroyMenu(pm) !== 0);
+        t.section('comctl32: ImageList 创建-销毁往返');
+        const himl = ImageListCreate(16, 16, 4, 0, 0); // ILC_COLOR32=4；initial/grow=0 默认
+        t.checkTrue('ImageListCreate(16, 16, ILC_COLOR32) 非 0', himl !== 0);
+        if (himl !== 0)
+            t.checkTrue('ImageListDestroy(himl) 成功', ImageListDestroy(himl) !== 0);
+        t.section('user32: LoadImage 双变体（string 自动编码 / ordinal MAKEINTRESOURCE）');
+        // Win32 IMAGE_* 真值：BITMAP=0 CURSOR=1 ICON=2；LR_SHARED=0x8000（注意 gui.ImageType d.ts 当前值与此不一致）
+        t.checkTrue('LoadImageOrdinal(NULL, IDI_APPLICATION, IMAGE_ICON, LR_SHARED) 非 0', LoadImageOrdinal(NULL, 32512, 2, 0, 0, 0x8000) !== 0);
+        t.check('LoadImage(LOADFROMFILE, 不存在文件) → 0', 0, LoadImage(NULL, 'qw_no_such_icon_xyz.ico', 2, 0, 0, 0x10));
+        t.section('user32: 滚动条（入参对象直传 / 出参 encode → call → decode）');
+        const desk = GetDesktopWindow();
+        t.checkTrue('GetDesktopWindow 非 0', desk !== 0);
+        if (desk === 0)
+            return;
+        // 入参位（注册 encoder）：DeepPartial 对象直传；cbSize 必须显式 = 结构自描述要求。
+        // 桌面窗口无 WS_VSCROLL 样式 → Set/GetScrollInfo 返回 0 是 Win32 合法行为（.NET 的
+        // WindowsScroll 包装同样先查样式再调用），故断言形态而非成功。
+        t.checkTrue('SetScrollInfo 对象直传 形态 number', typeof SetScrollInfo(desk, 1, { cbSize: SCROLLINFO.size, fMask: 0x0001, nMin: 0, nMax: 100 }, 0) === 'number');
+        // 出参位（不注册 encoder）：encode() 新建 + 初值一步 → 传 .ptr → decode 字段直读。
+        // GetScrollInfo 失败（无滚动条）不写 buffer → decode 回读 = encode 初值；成功时 Win32
+        // 覆写 cbSize/fMask 为同值 —— 两条路径下回环断言都稳定。
+        const si = SCROLLINFO.encode({ cbSize: SCROLLINFO.size, fMask: 0x0001 });
+        t.checkTrue('GetScrollInfo 调用形态 number', typeof GetScrollInfo(desk, 1, si.ptr) === 'number');
+        const info = SCROLLINFO.decode(si);
+        t.check('decode 回读 cbSize = encode 初值', SCROLLINFO.size, info.cbSize);
+        t.check('decode 回读 fMask = encode 初值', 0x0001, info.fMask);
+        t.checkTrue('读回字段为 number 形态', typeof info.nMin === 'number' && typeof info.nMax === 'number');
+        // CallWindowProc / ShowScrollBar / ImageListAdd 仅由 import 的模块加载覆盖 proc 名：
+        // CallWindowProc 跨线程窗口过程不安全、ShowScrollBar 有副作用、ImageListAdd 需位图源
+    },
+};

package/test/test_ffi_windows.ts

@@ -0,0 +1,113 @@
+import { Tester } from './test_helper.js'
+import { NULL } from '../lib/ffi/ctype.js'
+import {
+    GetDesktopWindow, CreatePopupMenu, DestroyMenu, GetDC, ReleaseDC,
+    LoadImage, LoadImageOrdinal, SetScrollInfo, GetScrollInfo,
+} from '../lib/windows/user32.js'
+import {
+    GetDeviceCaps, CreateSolidBrush, DeleteObject, CreateFontIndirect, GetObject, SelectObject, CreateCompatibleDC, DeleteDC,
+} from '../lib/windows/gdi32.js'
+import { ImageListCreate, ImageListDestroy } from '../lib/windows/comctl32.js'
+import { LOGFONTW, SCROLLINFO } from '../lib/windows/structs.js'
+
+export const suite = {
+    run(t: Tester) {
+        // 本文件 import 三个 dll 模块即在加载时执行全部 bind：proc 名错误 → GetProcAddress 失败 →
+        // 模块加载 throw → run.ts 静默跳过本 suite → 总计数低于基线（判据链对比计数即暴露）
+        t.section('gdi32: 画刷 / 字体 创建-删除往返（LOGFONTW 对象直传）')
+        const brush = CreateSolidBrush(0x3366ff)
+        t.checkTrue('CreateSolidBrush 非 0', brush !== 0)
+        if (brush !== 0) t.checkTrue('DeleteObject(brush) 成功', DeleteObject(brush) !== 0)
+
+        // DeepPartial 缺省字段跳过：lfHeight + lfFaceName 必给，其余标量保持 0（FW_DONTCARE 等合法零值）
+        const font = CreateFontIndirect({ lfHeight: -16, lfWeight: 400, lfCharSet: 1, lfFaceName: 'Arial' })
+        t.checkTrue('CreateFontIndirect(DeepPartial LOGFONTW) 非 0', font !== 0)
+        if (font !== 0) t.checkTrue('DeleteObject(font) 成功', DeleteObject(font) !== 0)
+
+        // react-qw ListView.getCellFont 的流程：GetObject 读出现有字体 → decode → 叠加粗/斜/下划线 → 重建 → 回读
+        t.section('gdi32: 字体读出-改写-重建往返（GetObject → decode → CreateFontIndirect → GetObject）')
+        const base = CreateFontIndirect({ lfHeight: -18, lfWeight: 400, lfCharSet: 1, lfFaceName: 'Arial' })
+        if (base !== 0) {
+            const lf0 = LOGFONTW.alloc()
+            t.checkTrue('GetObject(font) 写入 LOGFONTW.size 字节', GetObject(base, LOGFONTW.size, lf0) === LOGFONTW.size)
+            const b0 = LOGFONTW.decode(lf0)
+            t.check('读出 lfHeight', -18, b0.lfHeight)
+            t.check('读出 lfWeight', 400, b0.lfWeight)
+            t.check('读出 lfItalic（未设）', 0, b0.lfItalic)
+            const styled = CreateFontIndirect({ ...b0, lfWeight: 700, lfItalic: 1, lfUnderline: 1 })
+            t.checkTrue('叠加样式后重建非 0', styled !== 0)
+            if (styled !== 0) {
+                const lf1 = LOGFONTW.alloc()
+                GetObject(styled, LOGFONTW.size, lf1)
+                const b1 = LOGFONTW.decode(lf1)
+                t.check('重建后 lfWeight', 700, b1.lfWeight)
+                t.check('重建后 lfItalic', 1, b1.lfItalic)
+                t.check('重建后 lfUnderline', 1, b1.lfUnderline)
+                t.check('底字体的 lfHeight 保留', -18, b1.lfHeight)
+                t.check('底字体的 lfCharSet 保留', 1, b1.lfCharSet)
+                t.check('底字体的字体名保留', b0.lfFaceName, b1.lfFaceName)
+                t.checkTrue('DeleteObject(styled) 成功', DeleteObject(styled) !== 0)
+            }
+            t.checkTrue('DeleteObject(base) 成功', DeleteObject(base) !== 0)
+        }
+
+        // 内存 DC 选入字体：SelectObject 返回被替换的旧对象，选回后可删除新对象（截屏与 ListView 自绘共用）
+        t.section('gdi32: CreateCompatibleDC / SelectObject 往返')
+        const memDc = CreateCompatibleDC(NULL)
+        t.checkTrue('CreateCompatibleDC(NULL) 非 0', memDc !== 0)
+        if (memDc !== 0) {
+            const f2 = CreateFontIndirect({ lfHeight: -12, lfFaceName: 'Arial' })
+            if (f2 !== 0) {
+                const old = SelectObject(memDc, f2)
+                t.checkTrue('SelectObject 返回旧对象非 0', old !== 0)
+                t.check('再选回旧对象，返回刚选入的字体', f2, SelectObject(memDc, old))
+                t.checkTrue('DeleteObject(f2) 成功', DeleteObject(f2) !== 0)
+            }
+            t.checkTrue('DeleteDC 成功', DeleteDC(memDc) !== 0)
+        }
+
+        t.section('gdi32: GetDeviceCaps（<HDC>ptr 跨 user32 品牌互认）')
+        const hdc = GetDC(NULL)
+        t.checkTrue('GetDC(NULL) 非 0', hdc !== 0)
+        if (hdc !== 0) t.checkTrue('GetDeviceCaps(hdc, LOGPIXELSX) > 0', GetDeviceCaps(hdc, 88) > 0)
+        t.checkTrue('ReleaseDC(NULL, hdc) 成功', hdc !== 0 && ReleaseDC(NULL, hdc) !== 0)
+
+        t.section('user32: 弹出菜单往返')
+        const pm = CreatePopupMenu()
+        t.checkTrue('CreatePopupMenu 非 0', pm !== 0)
+        if (pm !== 0) t.checkTrue('DestroyMenu(pm) 成功', DestroyMenu(pm) !== 0)
+
+        t.section('comctl32: ImageList 创建-销毁往返')
+        const himl = ImageListCreate(16, 16, 4, 0, 0)   // ILC_COLOR32=4；initial/grow=0 默认
+        t.checkTrue('ImageListCreate(16, 16, ILC_COLOR32) 非 0', himl !== 0)
+        if (himl !== 0) t.checkTrue('ImageListDestroy(himl) 成功', ImageListDestroy(himl) !== 0)
+
+        t.section('user32: LoadImage 双变体（string 自动编码 / ordinal MAKEINTRESOURCE）')
+        // Win32 IMAGE_* 真值：BITMAP=0 CURSOR=1 ICON=2；LR_SHARED=0x8000（注意 gui.ImageType d.ts 当前值与此不一致）
+        t.checkTrue('LoadImageOrdinal(NULL, IDI_APPLICATION, IMAGE_ICON, LR_SHARED) 非 0',
+            LoadImageOrdinal(NULL, 32512, 2, 0, 0, 0x8000) !== 0)
+        t.check('LoadImage(LOADFROMFILE, 不存在文件) → 0', 0,
+            LoadImage(NULL, 'qw_no_such_icon_xyz.ico', 2, 0, 0, 0x10))
+
+        t.section('user32: 滚动条（入参对象直传 / 出参 encode → call → decode）')
+        const desk = GetDesktopWindow()
+        t.checkTrue('GetDesktopWindow 非 0', desk !== 0)
+        if (desk === 0) return
+        // 入参位（注册 encoder）：DeepPartial 对象直传；cbSize 必须显式 = 结构自描述要求。
+        // 桌面窗口无 WS_VSCROLL 样式 → Set/GetScrollInfo 返回 0 是 Win32 合法行为（.NET 的
+        // WindowsScroll 包装同样先查样式再调用），故断言形态而非成功。
+        t.checkTrue('SetScrollInfo 对象直传 形态 number',
+            typeof SetScrollInfo(desk, 1, { cbSize: SCROLLINFO.size, fMask: 0x0001, nMin: 0, nMax: 100 }, 0) === 'number')
+        // 出参位（不注册 encoder）：encode() 新建 + 初值一步 → 传 .ptr → decode 字段直读。
+        // GetScrollInfo 失败（无滚动条）不写 buffer → decode 回读 = encode 初值；成功时 Win32
+        // 覆写 cbSize/fMask 为同值 —— 两条路径下回环断言都稳定。
+        const si = SCROLLINFO.encode({ cbSize: SCROLLINFO.size, fMask: 0x0001 })
+        t.checkTrue('GetScrollInfo 调用形态 number', typeof GetScrollInfo(desk, 1, si.ptr) === 'number')
+        const info = SCROLLINFO.decode(si)
+        t.check('decode 回读 cbSize = encode 初值', SCROLLINFO.size, info.cbSize)
+        t.check('decode 回读 fMask = encode 初值', 0x0001, info.fMask)
+        t.checkTrue('读回字段为 number 形态', typeof info.nMin === 'number' && typeof info.nMax === 'number')
+        // CallWindowProc / ShowScrollBar / ImageListAdd 仅由 import 的模块加载覆盖 proc 名：
+        // CallWindowProc 跨线程窗口过程不安全、ShowScrollBar 有副作用、ImageListAdd 需位图源
+    },
+}

package/test/test_files.js

@@ -0,0 +1,102 @@
+import { WCHAR } from '../lib/ffi/bind.js';
+import { NULL, PtrArrayBuffer } from '../lib/ffi/ctype.js';
+import { CloseHandle, CopyFile, CreateDirectory, CreateFile, DeleteFile, FindClose, FindFirstFile, FindNextFile, GetFileAttributes, GetFileSize, GetTempPath, MoveFileEx, ReadFile, RemoveDirectory, SetFilePointer, WriteFile, } from '../lib/windows/kernel32.js';
+import { WIN32_FIND_DATAW } from '../lib/windows/structs.js';
+const GENERIC_READ = 0x80000000;
+const GENERIC_WRITE = 0x40000000;
+const FILE_ATTRIBUTE_DIRECTORY = 0x10;
+const INVALID32 = 0xffffffff;
+// ASCII payload ↔ UTF-16LE 缓冲互转（REG_SZ 同型，测试内联）
+function toWide(s) {
+    const p = new PtrArrayBuffer(s.length * 2);
+    const dv = new DataView(p);
+    for (let i = 0; i < s.length; i++)
+        dv.setUint16(i * 2, s.charCodeAt(i), true);
+    return p;
+}
+function fromWide(p, chars) {
+    const dv = new DataView(p);
+    let out = '';
+    for (let i = 0; i < chars; i++)
+        out += String.fromCharCode(dv.getUint16(i * 2, true));
+    return out;
+}
+export const suite = {
+    name: 'files',
+    run: (t) => {
+        t.section('GetTempPath + CreateDirectory');
+        const tmpW = WCHAR.alloc(260);
+        const tmpLen = GetTempPath(260, tmpW);
+        t.checkTrue(`temp path non-empty (${tmpLen})`, tmpLen > 0);
+        const dir = `${WCHAR.decode(tmpW)}QuickWinTest`; // GetTempPath 尾带反斜杠
+        // 目录可能残留自上次中断的 run：已存在（且是目录）则静默复用
+        if (CreateDirectory(dir, NULL) === 0 &&
+            (GetFileAttributes(dir) & FILE_ATTRIBUTE_DIRECTORY) === 0) {
+            t.checkTrue('CreateDirectory', false);
+            return;
+        }
+        const pathA = `${dir}\\a.txt`;
+        const pathB = `${dir}\\b.txt`;
+        const pathC = `${dir}\\c.txt`;
+        const pathCn = `${dir}\\中文文件.txt`;
+        t.section('CreateFile + WriteFile: write payload');
+        const hW = CreateFile(pathA, GENERIC_WRITE, 0, NULL, 2 /* gui.FileCreation.CREATE_ALWAYS */, 0x80 /* FILE_ATTRIBUTE_NORMAL */, NULL);
+        t.checkTrue(`write handle valid (${hW})`, hW !== -1); // 失败 = INVALID_HANDLE_VALUE(-1)
+        const payload = 'hello files';
+        const wData = toWide(payload);
+        const pWr = new PtrArrayBuffer(4);
+        t.checkTrue('WriteFile ok', WriteFile(hW, wData, payload.length * 2, pWr, NULL) !== 0);
+        t.check('bytes written', payload.length * 2, new DataView(pWr).getUint32(0, true));
+        t.checkTrue('CloseHandle (writer)', CloseHandle(hW) !== 0);
+        t.section('CreateFile(READ) + GetFileSize + SetFilePointer + ReadFile');
+        const hR = CreateFile(pathA, GENERIC_READ, 0, NULL, 3 /* gui.FileCreation.OPEN_EXISTING */, 0x80, NULL);
+        t.checkTrue(`read handle valid (${hR})`, hR !== -1);
+        t.check('GetFileSize', payload.length * 2, GetFileSize(hR, NULL));
+        t.check('SetFilePointer BEGIN → 0', 0, SetFilePointer(hR, 0, NULL, 0 /* gui.FileSeekFrom.BEGIN */));
+        const rData = new PtrArrayBuffer(payload.length * 2);
+        const pRd = new PtrArrayBuffer(4);
+        t.checkTrue('ReadFile ok', ReadFile(hR, rData, payload.length * 2, pRd, NULL) !== 0);
+        t.check('read roundtrip', payload, fromWide(rData, payload.length));
+        // seek 到 END-4 验证负偏移 + 读尾 4 字节
+        t.check('SetFilePointer END-4', payload.length * 2 - 4, SetFilePointer(hR, -4, NULL, 2 /* gui.FileSeekFrom.END */));
+        const rTail = new PtrArrayBuffer(8);
+        ReadFile(hR, rTail, 4, pRd, NULL);
+        t.check('seeked tail', payload.slice(-2), fromWide(rTail, 2));
+        CloseHandle(hR);
+        t.section('CopyFile + MoveFileEx + GetFileAttributes');
+        const hB = CreateFile(pathB, GENERIC_WRITE, 0, NULL, 2 /* gui.FileCreation.CREATE_ALWAYS */, 0x80, NULL);
+        const bData = toWide('bb');
+        WriteFile(hB, bData, 4, pWr, NULL);
+        CloseHandle(hB);
+        t.checkTrue('CopyFile ok', CopyFile(pathB, pathC, 0) !== 0);
+        const hC = CreateFile(pathC, GENERIC_READ, 0, NULL, 3 /* gui.FileCreation.OPEN_EXISTING */, 0x80, NULL);
+        t.check('copied size', 4, GetFileSize(hC, NULL));
+        t.checkTrue('CloseHandle (copy reader)', CloseHandle(hC) !== 0);
+        t.checkTrue('MoveFileEx replace ok', MoveFileEx(pathB, pathC, 0x1 /* MOVEFILE_REPLACE_EXISTING */) !== 0);
+        t.check('moved: source gone', INVALID32, GetFileAttributes(pathB));
+        t.checkTrue('dest is file (not dir)', (GetFileAttributes(pathC) & FILE_ATTRIBUTE_DIRECTORY) === 0);
+        t.section('FindFirstFile/FindNextFile: enumerate *.txt incl. CJK name');
+        const hCn = CreateFile(pathCn, GENERIC_WRITE, 0, NULL, 2 /* gui.FileCreation.CREATE_ALWAYS */, 0x80, NULL);
+        CloseHandle(hCn); // 0 字节中文名文件
+        const fd = WIN32_FIND_DATAW.alloc();
+        const hFind = FindFirstFile(`${dir}\\a.txt`, fd.ptr);
+        t.checkTrue(`FindFirstFile ok (${hFind})`, hFind !== -1);
+        t.check('found name', 'a.txt', WIN32_FIND_DATAW.decode(fd).cFileName);
+        t.checkTrue('FindNextFile exhausted = 0', FindNextFile(hFind, fd.ptr) === 0);
+        t.checkTrue('FindClose', FindClose(hFind) !== 0);
+        let count = 0;
+        const hEnum = FindFirstFile(`${dir}\\*.txt`, fd.ptr);
+        if (hEnum !== -1) {
+            count = 1;
+            while (FindNextFile(hEnum, fd.ptr) !== 0)
+                count++;
+            FindClose(hEnum);
+        }
+        t.check('enum *.txt count (a/c/CJK)', 3, count);
+        t.section('DeleteFile + RemoveDirectory: cleanup');
+        t.checkTrue('DeleteFile ×3', DeleteFile(pathA) !== 0 && DeleteFile(pathC) !== 0
+            && DeleteFile(pathCn) !== 0);
+        t.checkTrue('RemoveDirectory', RemoveDirectory(dir) !== 0);
+        t.check('dir gone', INVALID32, GetFileAttributes(dir));
+    },
+};

package/test/test_files.ts

@@ -0,0 +1,121 @@
+import * as gui from 'gui'
+import { WCHAR } from '../lib/ffi/bind.js'
+import { NULL, PtrArrayBuffer } from '../lib/ffi/ctype.js'
+import {
+    CloseHandle, CopyFile, CreateDirectory, CreateFile, DeleteFile,
+    FindClose, FindFirstFile, FindNextFile, GetFileAttributes, GetFileSize,
+    GetTempPath, MoveFileEx, ReadFile, RemoveDirectory, SetFilePointer, WriteFile,
+} from '../lib/windows/kernel32.js'
+import { WIN32_FIND_DATAW } from '../lib/windows/structs.js'
+import { Tester } from './test_helper.js'
+
+const GENERIC_READ = 0x80000000
+const GENERIC_WRITE = 0x40000000
+const FILE_ATTRIBUTE_DIRECTORY = 0x10
+const INVALID32 = 0xffffffff
+
+// ASCII payload ↔ UTF-16LE 缓冲互转（REG_SZ 同型，测试内联）
+function toWide(s: string): PtrArrayBuffer<string> {
+    const p = new PtrArrayBuffer(s.length * 2)
+    const dv = new DataView(p)
+    for (let i = 0; i < s.length; i++) dv.setUint16(i * 2, s.charCodeAt(i), true)
+    return p
+}
+function fromWide(p: PtrArrayBuffer<string>, chars: number): string {
+    const dv = new DataView(p)
+    let out = ''
+    for (let i = 0; i < chars; i++) out += String.fromCharCode(dv.getUint16(i * 2, true))
+    return out
+}
+
+export const suite = {
+    name: 'files',
+    run: (t: Tester) => {
+        t.section('GetTempPath + CreateDirectory')
+        const tmpW = WCHAR.alloc(260)
+        const tmpLen = GetTempPath(260, tmpW)
+        t.checkTrue(`temp path non-empty (${tmpLen})`, tmpLen > 0)
+        const dir = `${WCHAR.decode(tmpW)}QuickWinTest`    // GetTempPath 尾带反斜杠
+        // 目录可能残留自上次中断的 run：已存在（且是目录）则静默复用
+        if (CreateDirectory(dir, NULL) === 0 &&
+            (GetFileAttributes(dir) & FILE_ATTRIBUTE_DIRECTORY) === 0) {
+            t.checkTrue('CreateDirectory', false)
+            return
+        }
+        const pathA = `${dir}\\a.txt`
+        const pathB = `${dir}\\b.txt`
+        const pathC = `${dir}\\c.txt`
+        const pathCn = `${dir}\\中文文件.txt`
+
+        t.section('CreateFile + WriteFile: write payload')
+        const hW = CreateFile(pathA, GENERIC_WRITE, 0, NULL,
+            gui.FileCreation.CREATE_ALWAYS, 0x80 /* FILE_ATTRIBUTE_NORMAL */, NULL)
+        t.checkTrue(`write handle valid (${hW})`, hW !== -1) // 失败 = INVALID_HANDLE_VALUE(-1)
+        const payload = 'hello files'
+        const wData = toWide(payload)
+        const pWr = new PtrArrayBuffer(4)
+        t.checkTrue('WriteFile ok', WriteFile(hW, wData, payload.length * 2, pWr, NULL) !== 0)
+        t.check('bytes written', payload.length * 2, new DataView(pWr).getUint32(0, true))
+        t.checkTrue('CloseHandle (writer)', CloseHandle(hW) !== 0)
+
+        t.section('CreateFile(READ) + GetFileSize + SetFilePointer + ReadFile')
+        const hR = CreateFile(pathA, GENERIC_READ, 0, NULL,
+            gui.FileCreation.OPEN_EXISTING, 0x80, NULL)
+        t.checkTrue(`read handle valid (${hR})`, hR !== -1)
+        t.check('GetFileSize', payload.length * 2, GetFileSize(hR, NULL))
+        t.check('SetFilePointer BEGIN → 0', 0, SetFilePointer(hR, 0, NULL, gui.FileSeekFrom.BEGIN))
+        const rData = new PtrArrayBuffer(payload.length * 2)
+        const pRd = new PtrArrayBuffer(4)
+        t.checkTrue('ReadFile ok', ReadFile(hR, rData, payload.length * 2, pRd, NULL) !== 0)
+        t.check('read roundtrip', payload, fromWide(rData, payload.length))
+        // seek 到 END-4 验证负偏移 + 读尾 4 字节
+        t.check('SetFilePointer END-4', payload.length * 2 - 4,
+            SetFilePointer(hR, -4, NULL, gui.FileSeekFrom.END))
+        const rTail = new PtrArrayBuffer(8)
+        ReadFile(hR, rTail, 4, pRd, NULL)
+        t.check('seeked tail', payload.slice(-2), fromWide(rTail, 2))
+        CloseHandle(hR)
+
+        t.section('CopyFile + MoveFileEx + GetFileAttributes')
+        const hB = CreateFile(pathB, GENERIC_WRITE, 0, NULL,
+            gui.FileCreation.CREATE_ALWAYS, 0x80, NULL)
+        const bData = toWide('bb')
+        WriteFile(hB, bData, 4, pWr, NULL)
+        CloseHandle(hB)
+        t.checkTrue('CopyFile ok', CopyFile(pathB, pathC, 0) !== 0)
+        const hC = CreateFile(pathC, GENERIC_READ, 0, NULL,
+            gui.FileCreation.OPEN_EXISTING, 0x80, NULL)
+        t.check('copied size', 4, GetFileSize(hC, NULL))
+        t.checkTrue('CloseHandle (copy reader)', CloseHandle(hC) !== 0)
+        t.checkTrue('MoveFileEx replace ok',
+            MoveFileEx(pathB, pathC, 0x1 /* MOVEFILE_REPLACE_EXISTING */) !== 0)
+        t.check('moved: source gone', INVALID32, GetFileAttributes(pathB))
+        t.checkTrue('dest is file (not dir)',
+            (GetFileAttributes(pathC) & FILE_ATTRIBUTE_DIRECTORY) === 0)
+
+        t.section('FindFirstFile/FindNextFile: enumerate *.txt incl. CJK name')
+        const hCn = CreateFile(pathCn, GENERIC_WRITE, 0, NULL,
+            gui.FileCreation.CREATE_ALWAYS, 0x80, NULL)
+        CloseHandle(hCn)                                      // 0 字节中文名文件
+        const fd = WIN32_FIND_DATAW.alloc()
+        const hFind = FindFirstFile(`${dir}\\a.txt`, fd.ptr)
+        t.checkTrue(`FindFirstFile ok (${hFind})`, hFind !== -1)
+        t.check('found name', 'a.txt', WIN32_FIND_DATAW.decode(fd).cFileName)
+        t.checkTrue('FindNextFile exhausted = 0', FindNextFile(hFind, fd.ptr) === 0)
+        t.checkTrue('FindClose', FindClose(hFind) !== 0)
+        let count = 0
+        const hEnum = FindFirstFile(`${dir}\\*.txt`, fd.ptr)
+        if (hEnum !== -1) {
+            count = 1
+            while (FindNextFile(hEnum, fd.ptr) !== 0) count++
+            FindClose(hEnum)
+        }
+        t.check('enum *.txt count (a/c/CJK)', 3, count)
+
+        t.section('DeleteFile + RemoveDirectory: cleanup')
+        t.checkTrue('DeleteFile ×3', DeleteFile(pathA) !== 0 && DeleteFile(pathC) !== 0
+            && DeleteFile(pathCn) !== 0)
+        t.checkTrue('RemoveDirectory', RemoveDirectory(dir) !== 0)
+        t.check('dir gone', INVALID32, GetFileAttributes(dir))
+    },
+}