quickwin 2.3.0 → 3.0.0

package/lib/react-qw/props.ts

@@ -1,5 +1,5 @@
 import * as gui from 'gui'
-import { SetWindowText, EnableWindow } from '../windows/user32.js'
+import { SetWindowText, EnableWindow, ShowWindow } from '../windows/user32.js'
 import type { Instance, Props } from './reconciler.js'
 import { EditMsg, ShowWindowCmd } from '../../constants'
 
@@ -33,9 +33,9 @@ export function applyProps(
     EnableWindow(hwnd, !newProps.disabled ? 1 : 0)
   }
   if ('hidden' in newProps) {
-    gui.ShowWindow(hwnd, newProps.hidden ? ShowWindowCmd.HIDE : ShowWindowCmd.SHOW)
+    ShowWindow(hwnd, newProps.hidden ? ShowWindowCmd.HIDE : ShowWindowCmd.SHOW)
   }
   if ('visible' in newProps) {
-    gui.ShowWindow(hwnd, newProps.visible ? ShowWindowCmd.SHOW : ShowWindowCmd.HIDE)
+    ShowWindow(hwnd, newProps.visible ? ShowWindowCmd.SHOW : ShowWindowCmd.HIDE)
   }
 }

package/lib/react-qw/reconciler.js

@@ -3,21 +3,15 @@ import { createContext } from 'react';
 import { DefaultEventPriority, NoEventPriority } from 'react-reconciler/constants';
 import * as gui from 'gui';
 import * as os from 'os';
-import { GetDC, ReleaseDC, GetWindowLongPtr, CallWindowProc, SetWindowPos, InvalidateRect, SetParent, SetWindowText } from '../windows/user32.js';
-import { GetDeviceCaps } from '../windows/gdi32.js';
+import { GetClientRect, GetWindowLongPtr, CallWindowProc, SetWindowPos, ShowWindow, InvalidateRect, SetParent, SetWindowText } from '../windows/user32.js';
+import { createSystemDpiFont, getScaleFactor } from '../dpi.js';
+import { RECT } from '../windows/structs.js';
 import { NULL } from '../ffi/ctype.js';
 import { applyProps } from './props.js';
 import { calculateFlexLayout } from './layout.js';
 import { getButtonIdealSize, measureTextForHwnd } from '../text-measure.js';
-const dpiFont = gui.CreateSystemDpiFont();
-// GetScaleFactor 等价内联：GetDC → GetDeviceCaps(LOGPIXELSX=88) → ReleaseDC 配对
-export const scaleFactor = (() => {
-    const hdc = GetDC(NULL);
-    const dpi = hdc ? GetDeviceCaps(hdc, 88) : 96;
-    if (hdc)
-        ReleaseDC(NULL, hdc);
-    return dpi / 96;
-})();
+const dpiFont = createSystemDpiFont();
+export const scaleFactor = getScaleFactor();
 const DELAYED_CONTROLS = new Set(['SysListView32', 'SysTreeView32', 'LISTBOX', 'COMBOBOX', 'msctls_trackbar32', 'SysDateTimePick32', 'SysLink']);
 function isDelayedControl(winClass) {
     return DELAYED_CONTROLS.has(winClass);
@@ -59,11 +53,12 @@ function runFlexLayout(inst) {
     const visible = children.filter(c => !c.props.hidden);
     if (visible.length === 0)
         return;
-    const rect = gui.GetClientRect(inst.hwnd);
-    if (!rect) {
+    const rcBuf = RECT.alloc();
+    if (!GetClientRect(inst.hwnd, rcBuf.ptr)) {
         console.log('flex: no rect for', inst.hwnd, inst.type);
         return;
     }
+    const rect = RECT.decode(rcBuf);
     const pw = (rect.right - rect.left) / scaleFactor;
     const ph = (rect.bottom - rect.top) / scaleFactor;
     if (pw <= 0 || ph <= 0) {
@@ -260,19 +255,19 @@ const hostConfig = {
     },
     hideInstance(instance) {
         if (instance.hwnd !== null)
-            gui.ShowWindow(instance.hwnd, 0 /* ShowWindowCmd.HIDE */);
+            ShowWindow(instance.hwnd, 0 /* ShowWindowCmd.HIDE */);
     },
     hideTextInstance(instance) {
         if (instance.hwnd !== null)
-            gui.ShowWindow(instance.hwnd, 0 /* ShowWindowCmd.HIDE */);
+            ShowWindow(instance.hwnd, 0 /* ShowWindowCmd.HIDE */);
     },
     unhideInstance(instance, _props) {
         if (instance.hwnd !== null)
-            gui.ShowWindow(instance.hwnd, 5 /* ShowWindowCmd.SHOW */);
+            ShowWindow(instance.hwnd, 5 /* ShowWindowCmd.SHOW */);
     },
     unhideTextInstance(instance, _text) {
         if (instance.hwnd !== null)
-            gui.ShowWindow(instance.hwnd, 5 /* ShowWindowCmd.SHOW */);
+            ShowWindow(instance.hwnd, 5 /* ShowWindowCmd.SHOW */);
     },
     shouldSetTextContent(_type, props) {
         return typeof props.children === 'string' || typeof props.children === 'number';

package/lib/react-qw/reconciler.ts

@@ -3,8 +3,9 @@ import { createContext } from 'react'
 import { DefaultEventPriority, NoEventPriority } from 'react-reconciler/constants'
 import * as gui from 'gui'
 import * as os from 'os'
-import { GetDC, ReleaseDC, GetWindowLongPtr, CallWindowProc, SetWindowPos, InvalidateRect, SetParent, SetWindowText } from '../windows/user32.js'
-import { GetDeviceCaps } from '../windows/gdi32.js'
+import { GetClientRect, GetWindowLongPtr, CallWindowProc, SetWindowPos, ShowWindow, InvalidateRect, SetParent, SetWindowText } from '../windows/user32.js'
+import { createSystemDpiFont, getScaleFactor } from '../dpi.js'
+import { RECT } from '../windows/structs.js'
 import { NULL } from '../ffi/ctype.js'
 import { applyProps } from './props.js'
 import { calculateFlexLayout, type FlexStyle } from './layout.js'
@@ -15,14 +16,8 @@ import { Gwlp, SetWindowPosFlag, SetWindowPosHwnd, ShowWindowCmd, WindowStyle, W
 // DEBUG 由 esbuild --define 在 bundle 时替换（见 build.ts），生产环境为 false
 declare const DEBUG: boolean
 
-const dpiFont = gui.CreateSystemDpiFont()
-// GetScaleFactor 等价内联：GetDC → GetDeviceCaps(LOGPIXELSX=88) → ReleaseDC 配对
-export const scaleFactor = (() => {
-    const hdc = GetDC(NULL)
-    const dpi = hdc ? GetDeviceCaps(hdc, 88) : 96
-    if (hdc) ReleaseDC(NULL, hdc)
-    return dpi / 96
-})()
+const dpiFont = createSystemDpiFont()
+export const scaleFactor = getScaleFactor()
 
 type Container = gui.HWND
 export type Props = WIntrinsicProps
@@ -83,8 +78,9 @@ function runFlexLayout(inst: Instance) {
   const flex: FlexStyle = s || {}
   const visible = children.filter(c => !c.props.hidden)
   if (visible.length === 0) return
-  const rect = gui.GetClientRect(inst.hwnd!)
-  if (!rect) { console.log('flex: no rect for', inst.hwnd, inst.type); return }
+  const rcBuf = RECT.alloc()
+  if (!GetClientRect(inst.hwnd!, rcBuf.ptr)) { console.log('flex: no rect for', inst.hwnd, inst.type); return }
+  const rect = RECT.decode(rcBuf)
   const pw = (rect.right - rect.left) / scaleFactor
   const ph = (rect.bottom - rect.top) / scaleFactor
   if (pw <= 0 || ph <= 0) { console.log('flex: zero size for', inst.hwnd, inst.type, pw, ph); return }
@@ -284,19 +280,19 @@ const hostConfig: QuickWinHostConfig = {
   },
 
   hideInstance(instance: Instance) {
-    if (instance.hwnd !== null) gui.ShowWindow(instance.hwnd, ShowWindowCmd.HIDE)
+    if (instance.hwnd !== null) ShowWindow(instance.hwnd, ShowWindowCmd.HIDE)
   },
 
   hideTextInstance(instance: Instance) {
-    if (instance.hwnd !== null) gui.ShowWindow(instance.hwnd, ShowWindowCmd.HIDE)
+    if (instance.hwnd !== null) ShowWindow(instance.hwnd, ShowWindowCmd.HIDE)
   },
 
   unhideInstance(instance: Instance, _props: Props) {
-    if (instance.hwnd !== null) gui.ShowWindow(instance.hwnd, ShowWindowCmd.SHOW)
+    if (instance.hwnd !== null) ShowWindow(instance.hwnd, ShowWindowCmd.SHOW)
   },
 
   unhideTextInstance(instance: Instance, _text: string) {
-    if (instance.hwnd !== null) gui.ShowWindow(instance.hwnd, ShowWindowCmd.SHOW)
+    if (instance.hwnd !== null) ShowWindow(instance.hwnd, ShowWindowCmd.SHOW)
   },
 
   shouldSetTextContent(_type: string, props: Props) {

package/lib/text-measure.js

@@ -1,6 +1,6 @@
 import { NULL } from './ffi/ctype.js';
 import * as gui from 'gui';
-import { DrawText, GetDC, ReleaseDC } from './windows/user32.js';
+import { DrawText, GetDC, GetClientRect, GetWindowRect, ReleaseDC } from './windows/user32.js';
 import { SelectObject } from './windows/gdi32.js';
 import { RECT, SIZE } from './windows/structs.js';
 export function measureText(hdc, text, maxWidth) {
@@ -29,11 +29,14 @@ export function measureTextForHwnd(hwnd, text) {
     if (hFont)
         SelectObject(hdc, oldFont);
     ReleaseDC(hwnd, hdc);
-    const wr = gui.GetWindowRect(hwnd);
-    const cr = gui.GetClientRect(hwnd);
-    if (wr && cr) {
-        result.width += (wr.right - wr.left) - (cr.right - cr.left);
-        result.height += (wr.bottom - wr.top) - (cr.bottom - cr.top);
+    const wr = RECT.alloc();
+    const cr = RECT.alloc();
+    const okWr = GetWindowRect(hwnd, wr.ptr);
+    const okCr = GetClientRect(hwnd, cr.ptr);
+    if (okWr && okCr) {
+        const w = RECT.decode(wr), c = RECT.decode(cr);
+        result.width += (w.right - w.left) - (c.right - c.left);
+        result.height += (w.bottom - w.top) - (c.bottom - c.top);
     }
     return result;
 }

package/lib/text-measure.ts

@@ -1,6 +1,6 @@
 import { NULL, type Ptr } from './ffi/ctype.js'
 import * as gui from 'gui'
-import { DrawText, GetDC, ReleaseDC } from './windows/user32.js'
+import { DrawText, GetDC, GetClientRect, GetWindowRect, ReleaseDC } from './windows/user32.js'
 import { SelectObject } from './windows/gdi32.js'
 import { RECT, SIZE } from './windows/structs.js'
 import { ButtonExtMsg, DrawTextFlag, WmMsg } from '../constants'
@@ -31,11 +31,14 @@ export function measureTextForHwnd(hwnd: gui.HWND, text: string): { width: numbe
     const result = measureText(hdc, text, 0)
     if (hFont) SelectObject(hdc, oldFont)
     ReleaseDC(hwnd, hdc)
-    const wr = gui.GetWindowRect(hwnd)
-    const cr = gui.GetClientRect(hwnd)
-    if (wr && cr) {
-        result.width += (wr.right - wr.left) - (cr.right - cr.left)
-        result.height += (wr.bottom - wr.top) - (cr.bottom - cr.top)
+    const wr = RECT.alloc()
+    const cr = RECT.alloc()
+    const okWr = GetWindowRect(hwnd, wr.ptr)
+    const okCr = GetClientRect(hwnd, cr.ptr)
+    if (okWr && okCr) {
+        const w = RECT.decode(wr), c = RECT.decode(cr)
+        result.width += (w.right - w.left) - (c.right - c.left)
+        result.height += (w.bottom - w.top) - (c.bottom - c.top)
     }
     return result
 }

package/lib/windows/comctl32.js

@@ -11,8 +11,9 @@ export const ImageListCreate = /*@__PURE__*/ b('ImageList_Create', 'i32 i32 u32
 /** 加位图进图像列表
  *  @returns 新索引（-1 失败）
  *  @param args_0 himl 图像列表句柄
- *  @param args_1 hbm 位图句柄（gdi32 <HGDIOBJ>ptr 产物，如 CreateCompatibleBitmap） */
-export const ImageListAdd = /*@__PURE__*/ b('ImageList_Add', '<HIMAGELIST>ptr <HGDIOBJ>ptr -> i32');
+ *  @param args_1 hbmImage 位图句柄（gdi32 <HGDIOBJ>ptr 产物，如 CreateCompatibleBitmap）
+ *  @param args_2 hbmMask 掩码位图；32bpp 图像传 NULL */
+export const ImageListAdd = /*@__PURE__*/ b('ImageList_Add', '<HIMAGELIST>ptr <HGDIOBJ>ptr <HGDIOBJ>ptr -> i32');
 /** 销毁图像列表
  *  @returns 成功 → 非 0 */
 export const ImageListDestroy = /*@__PURE__*/ b('ImageList_Destroy', '<HIMAGELIST>ptr -> i32');

package/lib/windows/comctl32.ts

@@ -12,8 +12,9 @@ export const ImageListCreate = /*@__PURE__*/ b('ImageList_Create', 'i32 i32 u32
 /** 加位图进图像列表
  *  @returns 新索引（-1 失败）
  *  @param args_0 himl 图像列表句柄
- *  @param args_1 hbm 位图句柄（gdi32 <HGDIOBJ>ptr 产物，如 CreateCompatibleBitmap） */
-export const ImageListAdd = /*@__PURE__*/ b('ImageList_Add', '<HIMAGELIST>ptr <HGDIOBJ>ptr -> i32')
+ *  @param args_1 hbmImage 位图句柄（gdi32 <HGDIOBJ>ptr 产物，如 CreateCompatibleBitmap）
+ *  @param args_2 hbmMask 掩码位图；32bpp 图像传 NULL */
+export const ImageListAdd = /*@__PURE__*/ b('ImageList_Add', '<HIMAGELIST>ptr <HGDIOBJ>ptr <HGDIOBJ>ptr -> i32')
 /** 销毁图像列表
  *  @returns 成功 → 非 0 */
 export const ImageListDestroy = /*@__PURE__*/ b('ImageList_Destroy', '<HIMAGELIST>ptr -> i32')

package/lib/windows/gdi32.js

@@ -80,8 +80,30 @@ export const BitBlt = /*@__PURE__*/ b('BitBlt', '<HDC>ptr! i32 i32 i32 i32 <HDC>
  *  @param args_3 cLines 扫描行数
  *  @param args_4 lpvBits 像素接收缓冲（ArrayBuffer）
  *  @param args_5 lpbmi BITMAPINFO 缓冲（BITMAPINFOHEADER.encode({...}).ptr）
- *  @param args_6 uUsage DIB_RGB_COLORS(0) */
-export const GetDIBits = /*@__PURE__*/ b('GetDIBits', '<HDC>ptr! <HGDIOBJ>ptr u32 u32 <BYTE>ptr <>ptr u32 -> i32');
+ *  @param args_6 uUsage ColorUse.RGB_COLORS */
+export const GetDIBits = /*@__PURE__*/ b('GetDIBits', '<HDC>ptr! <HGDIOBJ>ptr u32 u32 <BYTE>ptr <>ptr u32@ColorUse -> i32');
+/** 建 32bpp DIB 段位图（biHeight 负 = 自顶向下，像素内存由系统分配）——像素内容靠
+ *  SetDIBits 从调用方缓冲装入，故 ppvBits 出参槽可传 NULL 不取位地址（要直写像素
+ *  才需要非空槽）
+ *  @returns 位图句柄；失败 → 0（用完 DeleteObject）
+ *  @param args_0 hdc 参考 DC（NULL 即可，只取 DIB 格式）
+ *  @param args_1 pbmi BITMAPINFO 缓冲（BITMAPINFOHEADER.encode({...}).ptr，同 GetDIBits）
+ *  @param args_2 iUsage ColorUse.RGB_COLORS
+ *  @param args_3 ppvBits 收位地址的出参槽（NULL = 不取）
+ *  @param args_4 hSection NULL（无文件映射区）
+ *  @param args_5 offset 位数据在映射区内的偏移（无映射区恒 0） */
+export const CreateDIBSection = /*@__PURE__*/ b('CreateDIBSection', '<HDC>ptr <>ptr u32@ColorUse <>ptr <>ptr u32 -> <HGDIOBJ>ptr');
+/** 把 lpvBits 的像素装进位图（lpbmi 描述源的格式；ColorUse.RGB_COLORS 时 hdc 只定
+ *  目标格式，本仓传 NULL 实测可用——MSDN：仅 DIB_PAL_COLORS 才用 hdc）
+ *  @returns 成功复制的扫描行数；失败 → 0
+ *  @param args_0 hdc 参考 DC（NULL 即可，见上）
+ *  @param args_1 hbm 目标位图（DIB 段同可用）
+ *  @param args_2 uStartScan 起始扫描行
+ *  @param args_3 cLines 扫描行数
+ *  @param args_4 lpvBits 像素源缓冲（ArrayBuffer）
+ *  @param args_5 lpbmi BITMAPINFO 缓冲（同 GetDIBits）
+ *  @param args_6 iUsage ColorUse.RGB_COLORS */
+export const SetDIBits = /*@__PURE__*/ b('SetDIBits', '<HDC>ptr <HGDIOBJ>ptr! u32 u32 <BYTE>ptr <>ptr u32@ColorUse -> i32');
 /** 取 GDI 对象信息到 lpv（hFont → LOGFONTW 等）
  *  @returns 写入的字节数；失败 → 0
  *  @param args_0 h GDI 对象句柄（字体/画笔/位图等）
@@ -171,8 +193,8 @@ export const MaskBlt = /*@__PURE__*/ b('MaskBlt', '<HDC>ptr! i32 i32 i32 i32 <HD
  *  @param args_8 uNumScans 扫描行数
  *  @param args_9 lpvBits 像素缓冲（ArrayBuffer）
  *  @param args_10 lpbmi BITMAPINFO 缓冲
- *  @param args_11 iUsage DIB_RGB_COLORS(0) */
-export const SetDIBitsToDevice = /*@__PURE__*/ b('SetDIBitsToDevice', '<HDC>ptr! i32 i32 u32 u32 i32 i32 u32 u32 <BYTE>ptr <BYTE>ptr u32 -> i32');
+ *  @param args_11 iUsage ColorUse.RGB_COLORS */
+export const SetDIBitsToDevice = /*@__PURE__*/ b('SetDIBitsToDevice', '<HDC>ptr! i32 i32 u32 u32 i32 i32 u32 u32 <BYTE>ptr <BYTE>ptr u32@ColorUse -> i32');
 /** 拉伸 DIB 传送（内存像素缓冲直接放/缩到目标，免创建 HBITMAP 中转）；
  *  DestWidth/DestHeight 传 0 = 源自然尺寸；SrcWidth/SrcHeight 负 = 翻转
  *  @returns 成功 → 扫描行数；失败 → 0
@@ -186,9 +208,9 @@ export const SetDIBitsToDevice = /*@__PURE__*/ b('SetDIBitsToDevice', '<HDC>ptr!
  *  @param args_8 SrcHeight 源区高
  *  @param args_9 lpvBits 像素缓冲（ArrayBuffer）
  *  @param args_10 lpbmi BITMAPINFO 缓冲（BITMAPINFOHEADER.encode({...}).ptr）
- *  @param args_11 iUsage DIB_RGB_COLORS(0)
+ *  @param args_11 iUsage ColorUse.RGB_COLORS
  *  @param args_12 rop RasterOp.SRCCOPY 等互斥单选光栅操作码 */
-export const StretchDIBits = /*@__PURE__*/ b('StretchDIBits', '<HDC>ptr! i32 i32 i32 i32 i32 i32 i32 i32 <BYTE>ptr <BYTE>ptr u32 u32@RasterOp -> i32');
+export const StretchDIBits = /*@__PURE__*/ b('StretchDIBits', '<HDC>ptr! i32 i32 i32 i32 i32 i32 i32 i32 <BYTE>ptr <BYTE>ptr u32@ColorUse u32@RasterOp -> i32');
 // ============ 画图原语（笔 / 线 / 形状 / 文字） ============
 /** 取系统共享对象（笔/刷/字体/调色板）；共享句柄不要 DeleteObject——
  *  SelectObject 选入 hdc 生效（如 NULL_BRUSH 让形状只描边不填充）

package/lib/windows/gdi32.ts

@@ -89,8 +89,32 @@ export const BitBlt = /*@__PURE__*/ b('BitBlt', '<HDC>ptr! i32 i32 i32 i32 <HDC>
  *  @param args_3 cLines 扫描行数
  *  @param args_4 lpvBits 像素接收缓冲（ArrayBuffer）
  *  @param args_5 lpbmi BITMAPINFO 缓冲（BITMAPINFOHEADER.encode({...}).ptr）
- *  @param args_6 uUsage DIB_RGB_COLORS(0) */
-export const GetDIBits = /*@__PURE__*/ b('GetDIBits', '<HDC>ptr! <HGDIOBJ>ptr u32 u32 <BYTE>ptr <>ptr u32 -> i32')
+ *  @param args_6 uUsage ColorUse.RGB_COLORS */
+export const GetDIBits = /*@__PURE__*/ b('GetDIBits', '<HDC>ptr! <HGDIOBJ>ptr u32 u32 <BYTE>ptr <>ptr u32@ColorUse -> i32')
+/** 建 32bpp DIB 段位图（biHeight 负 = 自顶向下，像素内存由系统分配）——像素内容靠
+ *  SetDIBits 从调用方缓冲装入，故 ppvBits 出参槽可传 NULL 不取位地址（要直写像素
+ *  才需要非空槽）
+ *  @returns 位图句柄；失败 → 0（用完 DeleteObject）
+ *  @param args_0 hdc 参考 DC（NULL 即可，只取 DIB 格式）
+ *  @param args_1 pbmi BITMAPINFO 缓冲（BITMAPINFOHEADER.encode({...}).ptr，同 GetDIBits）
+ *  @param args_2 iUsage ColorUse.RGB_COLORS
+ *  @param args_3 ppvBits 收位地址的出参槽（NULL = 不取）
+ *  @param args_4 hSection NULL（无文件映射区）
+ *  @param args_5 offset 位数据在映射区内的偏移（无映射区恒 0） */
+export const CreateDIBSection = /*@__PURE__*/ b('CreateDIBSection',
+    '<HDC>ptr <>ptr u32@ColorUse <>ptr <>ptr u32 -> <HGDIOBJ>ptr')
+/** 把 lpvBits 的像素装进位图（lpbmi 描述源的格式；ColorUse.RGB_COLORS 时 hdc 只定
+ *  目标格式，本仓传 NULL 实测可用——MSDN：仅 DIB_PAL_COLORS 才用 hdc）
+ *  @returns 成功复制的扫描行数；失败 → 0
+ *  @param args_0 hdc 参考 DC（NULL 即可，见上）
+ *  @param args_1 hbm 目标位图（DIB 段同可用）
+ *  @param args_2 uStartScan 起始扫描行
+ *  @param args_3 cLines 扫描行数
+ *  @param args_4 lpvBits 像素源缓冲（ArrayBuffer）
+ *  @param args_5 lpbmi BITMAPINFO 缓冲（同 GetDIBits）
+ *  @param args_6 iUsage ColorUse.RGB_COLORS */
+export const SetDIBits = /*@__PURE__*/ b('SetDIBits',
+    '<HDC>ptr <HGDIOBJ>ptr! u32 u32 <BYTE>ptr <>ptr u32@ColorUse -> i32')
 /** 取 GDI 对象信息到 lpv（hFont → LOGFONTW 等）
  *  @returns 写入的字节数；失败 → 0
  *  @param args_0 h GDI 对象句柄（字体/画笔/位图等）
@@ -184,9 +208,9 @@ export const MaskBlt = /*@__PURE__*/ b('MaskBlt',
  *  @param args_8 uNumScans 扫描行数
  *  @param args_9 lpvBits 像素缓冲（ArrayBuffer）
  *  @param args_10 lpbmi BITMAPINFO 缓冲
- *  @param args_11 iUsage DIB_RGB_COLORS(0) */
+ *  @param args_11 iUsage ColorUse.RGB_COLORS */
 export const SetDIBitsToDevice = /*@__PURE__*/ b('SetDIBitsToDevice',
-    '<HDC>ptr! i32 i32 u32 u32 i32 i32 u32 u32 <BYTE>ptr <BYTE>ptr u32 -> i32')
+    '<HDC>ptr! i32 i32 u32 u32 i32 i32 u32 u32 <BYTE>ptr <BYTE>ptr u32@ColorUse -> i32')
 
 /** 拉伸 DIB 传送（内存像素缓冲直接放/缩到目标，免创建 HBITMAP 中转）；
  *  DestWidth/DestHeight 传 0 = 源自然尺寸；SrcWidth/SrcHeight 负 = 翻转
@@ -201,10 +225,10 @@ export const SetDIBitsToDevice = /*@__PURE__*/ b('SetDIBitsToDevice',
  *  @param args_8 SrcHeight 源区高
  *  @param args_9 lpvBits 像素缓冲（ArrayBuffer）
  *  @param args_10 lpbmi BITMAPINFO 缓冲（BITMAPINFOHEADER.encode({...}).ptr）
- *  @param args_11 iUsage DIB_RGB_COLORS(0)
+ *  @param args_11 iUsage ColorUse.RGB_COLORS
  *  @param args_12 rop RasterOp.SRCCOPY 等互斥单选光栅操作码 */
 export const StretchDIBits = /*@__PURE__*/ b('StretchDIBits',
-    '<HDC>ptr! i32 i32 i32 i32 i32 i32 i32 i32 <BYTE>ptr <BYTE>ptr u32 u32@RasterOp -> i32')
+    '<HDC>ptr! i32 i32 i32 i32 i32 i32 i32 i32 <BYTE>ptr <BYTE>ptr u32@ColorUse u32@RasterOp -> i32')
 
 // ============ 画图原语（笔 / 线 / 形状 / 文字） ============
 

package/lib/windows/kernel32.js

@@ -266,6 +266,15 @@ export const GetComputerName = /*@__PURE__*/ b('GetComputerNameW', '<BYTE>ptr <B
  *  @param args_1 lpFilename 接收缓冲，传 WCHAR.alloc(n)
  *  @param args_2 nSize 缓冲容量（WCHAR 个数） */
 export const GetModuleFileName = /*@__PURE__*/ b('GetModuleFileNameW', '<HMODULE>ptr <BYTE>ptr u32 -> u32');
+/** 取**已加载**模块的句柄（不加载、不加引用计数；LoadLibrary 的反向查询）
+ *  @returns 模块句柄（HMODULE/HINSTANCE，与 win 模块同型）；失败 → NULL
+ *  @param args_0 lpModuleName 模块名（大小写不敏感，`.dll` 可省；只认模块名不认路径），
+ *    传 NULL = 当前进程主 exe —— `<WCHAR>ptr` 位收 string 或 NULL（JS null/undefined 会 fail-loud） */
+export const GetModuleHandle = /*@__PURE__*/ b('GetModuleHandleW', '<WCHAR>ptr -> <HMODULE>ptr');
+/** 卸载 LoadLibrary 加载的模块（引用计数减 1）；GetModuleHandle 拿到的句柄**不可**传此 API
+ *  @returns 成功 → 非 0
+ *  @param args_0 hModule LoadLibrary 返回的模块句柄 */
+export const FreeLibrary = /*@__PURE__*/ b('FreeLibrary', '<HMODULE>ptr -> i32');
 /** 进程命令行（含程序名；进程启动即有值，永不返回 NULL）
  *  @returns 命令行整串（返回位 `<WCHAR>ptr!`：内建 WCHAR codec 自动解码为 string，
  *    `!` 担保非 NULL 由返回位 0 检查兜底，无需接收缓冲） */

package/lib/windows/kernel32.ts

@@ -297,6 +297,15 @@ export const GetComputerName = /*@__PURE__*/ b('GetComputerNameW', '<BYTE>ptr <B
  *  @param args_1 lpFilename 接收缓冲，传 WCHAR.alloc(n)
  *  @param args_2 nSize 缓冲容量（WCHAR 个数） */
 export const GetModuleFileName = /*@__PURE__*/ b('GetModuleFileNameW', '<HMODULE>ptr <BYTE>ptr u32 -> u32')
+/** 取**已加载**模块的句柄（不加载、不加引用计数；LoadLibrary 的反向查询）
+ *  @returns 模块句柄（HMODULE/HINSTANCE，与 win 模块同型）；失败 → NULL
+ *  @param args_0 lpModuleName 模块名（大小写不敏感，`.dll` 可省；只认模块名不认路径），
+ *    传 NULL = 当前进程主 exe —— `<WCHAR>ptr` 位收 string 或 NULL（JS null/undefined 会 fail-loud） */
+export const GetModuleHandle = /*@__PURE__*/ b('GetModuleHandleW', '<WCHAR>ptr -> <HMODULE>ptr')
+/** 卸载 LoadLibrary 加载的模块（引用计数减 1）；GetModuleHandle 拿到的句柄**不可**传此 API
+ *  @returns 成功 → 非 0
+ *  @param args_0 hModule LoadLibrary 返回的模块句柄 */
+export const FreeLibrary = /*@__PURE__*/ b('FreeLibrary', '<HMODULE>ptr -> i32')
 /** 进程命令行（含程序名；进程启动即有值，永不返回 NULL）
  *  @returns 命令行整串（返回位 `<WCHAR>ptr!`：内建 WCHAR codec 自动解码为 string，
  *    `!` 担保非 NULL 由返回位 0 检查兜底，无需接收缓冲） */

package/lib/windows/shell32.js

@@ -1,6 +1,6 @@
-// shell32 绑定（shell 对话框 / PIDL→路径 / 托盘图标定位）
+// shell32 绑定（shell 对话框 / PIDL→路径 / 托盘图标增删与定位）
 import { bind } from '../ffi/bind.js';
-import { NOTIFYICONIDENTIFIER } from './structs.js';
+import { NOTIFYICONIDENTIFIER, NOTIFYICONDATAW } from './structs.js';
 // dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）；第三参透传
 // encoders（结构入参位注册，方向约定见 lib/windows/user32.ts 头注释）
 const b = (name, sig, encoders) => bind('shell32.dll', name, sig, encoders);
@@ -32,3 +32,12 @@ export const Shell_NotifyIconGetRect = (() => {
         return null; // XP 等老系统无此导出（可选 API）；探测走 examples/execd/tray.ts
     }
 })();
+/** 托盘通知图标增删改（Shell_NotifyIconW；XP 起即有）
+ *  @returns 成功 → 非 0，失败 → 0
+ *  @param args_0 dwMessage NotifyIconCmd（ADD / MODIFY / DELETE / SETVERSION…；DELETE 只需
+ *    hWnd+uID）
+ *  @param args_1 lpData NOTIFYICONDATAW 对象直传（encoder 已注册，缺省字段跳过）；cbSize 填
+ *    NOTIFYICONDATAW.size、uFlags 取 NotifyIconFlag.*（ICON/MESSAGE/TIP…，决定下面哪些字段
+ *    生效）、uCallbackMessage 常填自定义消息号、hIcon 接 LoadImage/LoadAppIcon 的结果、
+ *    szTip 直接给 string（宽字符串糖，最长 127 字符） */
+export const ShellNotifyIcon = /*@__PURE__*/ b('Shell_NotifyIconW', 'u32 <NOTIFYICONDATAW>ptr -> i32', { NOTIFYICONDATAW });

package/lib/windows/shell32.ts

@@ -1,6 +1,6 @@
-// shell32 绑定（shell 对话框 / PIDL→路径 / 托盘图标定位）
+// shell32 绑定（shell 对话框 / PIDL→路径 / 托盘图标增删与定位）
 import { bind, type CodecMap } from '../ffi/bind.js'
-import { NOTIFYICONIDENTIFIER } from './structs.js'
+import { NOTIFYICONIDENTIFIER, NOTIFYICONDATAW } from './structs.js'
 
 // dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）；第三参透传
 // encoders（结构入参位注册，方向约定见 lib/windows/user32.ts 头注释）
@@ -37,3 +37,14 @@ export const Shell_NotifyIconGetRect = (() => {
         return null    // XP 等老系统无此导出（可选 API）；探测走 examples/execd/tray.ts
     }
 })()
+
+/** 托盘通知图标增删改（Shell_NotifyIconW；XP 起即有）
+ *  @returns 成功 → 非 0，失败 → 0
+ *  @param args_0 dwMessage NotifyIconCmd（ADD / MODIFY / DELETE / SETVERSION…；DELETE 只需
+ *    hWnd+uID）
+ *  @param args_1 lpData NOTIFYICONDATAW 对象直传（encoder 已注册，缺省字段跳过）；cbSize 填
+ *    NOTIFYICONDATAW.size、uFlags 取 NotifyIconFlag.*（ICON/MESSAGE/TIP…，决定下面哪些字段
+ *    生效）、uCallbackMessage 常填自定义消息号、hIcon 接 LoadImage/LoadAppIcon 的结果、
+ *    szTip 直接给 string（宽字符串糖，最长 127 字符） */
+export const ShellNotifyIcon = /*@__PURE__*/ b('Shell_NotifyIconW',
+    'u32 <NOTIFYICONDATAW>ptr -> i32', { NOTIFYICONDATAW })

package/lib/windows/structs.js

@@ -78,6 +78,29 @@ export const LOGFONTW_DECL = {
     lfFaceName: 'u16[32]@utf-16le',
 };
 export const LOGFONTW = /* @__PURE__ */ struct('LOGFONTW', LOGFONTW_DECL);
+/** 非客户区度量（504B，x64/ia32 同布局）：内嵌 4 个 LOGFONTW + iPaddedBorderWidth（Vista+）；
+ *  SystemParametersInfo(SPI_GETNONCLIENTMETRICS) 纯出参位（不注册 encoder：
+ *  encode({cbSize}) 建缓冲带初值 → 传 .ptr → decode 读回 lfMessageFont 等） */
+export const NONCLIENTMETRICSW_DECL = {
+    '#': 'struct',
+    cbSize: 'u32',
+    iBorderWidth: 'i32',
+    iScrollWidth: 'i32',
+    iScrollHeight: 'i32',
+    iCaptionWidth: 'i32',
+    iCaptionHeight: 'i32',
+    lfCaptionFont: LOGFONTW_DECL,
+    iSmCaptionWidth: 'i32',
+    iSmCaptionHeight: 'i32',
+    lfSmCaptionFont: LOGFONTW_DECL,
+    iMenuWidth: 'i32',
+    iMenuHeight: 'i32',
+    lfMenuFont: LOGFONTW_DECL,
+    lfStatusFont: LOGFONTW_DECL,
+    lfMessageFont: LOGFONTW_DECL,
+    iPaddedBorderWidth: 'i32',
+};
+export const NONCLIENTMETRICSW = /* @__PURE__ */ struct('NONCLIENTMETRICSW', NONCLIENTMETRICSW_DECL);
 /** TEXTMETRICW（60B = 11 LONG + 4 WCHAR + 5 BYTE 尾部补齐，双架构同布局）：
  *  GetTextMetrics 纯出参位（不注册 encoder：TEXTMETRICW.alloc().ptr 进、decode 读回） */
 export const TEXTMETRICW_DECL = {
@@ -655,3 +678,31 @@ export const NOTIFYICONIDENTIFIER_DECL = {
     guidItem: 'u32[4]',
 };
 export const NOTIFYICONIDENTIFIER = /* @__PURE__ */ struct('NOTIFYICONIDENTIFIER', NOTIFYICONIDENTIFIER_DECL);
+/** NOTIFYICONDATAW（Shell_NotifyIconW；x86 956B / x64 976B——hWnd/hIcon/hBalloonIcon 随
+ *  位宽，GUID 固定 16B；偏移经 mingw 头文件实测对齐）。cbSize 调用前填
+ *  NOTIFYICONDATAW.size（cb 结构惯例，同 NOTIFYICONIDENTIFIER / SCROLLINFO）——
+ *  本声明取 Vista+ 布局（与 mingw sizeof 一致），XP 上同样可注册（实测）。
+ *  szTip/szInfo/szInfoTitle 走宽字符串糖（u16[N]@utf-16le，同 LOGFONTW.lfFaceName）；
+ *  图标句柄用裸 <>ptr：LoadImageW 的返回类型由 uType 决定（HICON/HCURSOR/HBITMAP），
+ *  绑定给不出品牌——裸地址收品牌指针（子型）无障碍；
+ *  uTimeout 与 uVersion 是同址 union，本仓只用前者（恒 0，不走版本协商），
+ *  故按单字段 u32 声明而非 union 布局。 */
+export const NOTIFYICONDATAW_DECL = {
+    '#': 'struct',
+    cbSize: 'u32',
+    hWnd: '<HWND>ptr',
+    uID: 'u32',
+    uFlags: 'u32',
+    uCallbackMessage: 'u32',
+    hIcon: '<>ptr',
+    szTip: 'u16[128]@utf-16le',
+    dwState: 'u32',
+    dwStateMask: 'u32',
+    szInfo: 'u16[256]@utf-16le',
+    uTimeout: 'u32',
+    szInfoTitle: 'u16[64]@utf-16le',
+    dwInfoFlags: 'u32',
+    guidItem: 'u32[4]',
+    hBalloonIcon: '<>ptr',
+};
+export const NOTIFYICONDATAW = /* @__PURE__ */ struct('NOTIFYICONDATAW', NOTIFYICONDATAW_DECL);

package/lib/windows/structs.ts

@@ -93,6 +93,31 @@ export const LOGFONTW_DECL = {
 
 export const LOGFONTW = /* @__PURE__ */ struct('LOGFONTW', LOGFONTW_DECL)
 
+/** 非客户区度量（504B，x64/ia32 同布局）：内嵌 4 个 LOGFONTW + iPaddedBorderWidth（Vista+）；
+ *  SystemParametersInfo(SPI_GETNONCLIENTMETRICS) 纯出参位（不注册 encoder：
+ *  encode({cbSize}) 建缓冲带初值 → 传 .ptr → decode 读回 lfMessageFont 等） */
+export const NONCLIENTMETRICSW_DECL = {
+    '#': 'struct',
+    cbSize: 'u32',
+    iBorderWidth: 'i32',
+    iScrollWidth: 'i32',
+    iScrollHeight: 'i32',
+    iCaptionWidth: 'i32',
+    iCaptionHeight: 'i32',
+    lfCaptionFont: LOGFONTW_DECL,
+    iSmCaptionWidth: 'i32',
+    iSmCaptionHeight: 'i32',
+    lfSmCaptionFont: LOGFONTW_DECL,
+    iMenuWidth: 'i32',
+    iMenuHeight: 'i32',
+    lfMenuFont: LOGFONTW_DECL,
+    lfStatusFont: LOGFONTW_DECL,
+    lfMessageFont: LOGFONTW_DECL,
+    iPaddedBorderWidth: 'i32',
+} satisfies C_Struct
+
+export const NONCLIENTMETRICSW = /* @__PURE__ */ struct('NONCLIENTMETRICSW', NONCLIENTMETRICSW_DECL)
+
 /** TEXTMETRICW（60B = 11 LONG + 4 WCHAR + 5 BYTE 尾部补齐，双架构同布局）：
  *  GetTextMetrics 纯出参位（不注册 encoder：TEXTMETRICW.alloc().ptr 进、decode 读回） */
 export const TEXTMETRICW_DECL = {
@@ -750,3 +775,33 @@ export const NOTIFYICONIDENTIFIER_DECL = {
 } satisfies C_Struct
 
 export const NOTIFYICONIDENTIFIER = /* @__PURE__ */ struct('NOTIFYICONIDENTIFIER', NOTIFYICONIDENTIFIER_DECL)
+
+/** NOTIFYICONDATAW（Shell_NotifyIconW；x86 956B / x64 976B——hWnd/hIcon/hBalloonIcon 随
+ *  位宽，GUID 固定 16B；偏移经 mingw 头文件实测对齐）。cbSize 调用前填
+ *  NOTIFYICONDATAW.size（cb 结构惯例，同 NOTIFYICONIDENTIFIER / SCROLLINFO）——
+ *  本声明取 Vista+ 布局（与 mingw sizeof 一致），XP 上同样可注册（实测）。
+ *  szTip/szInfo/szInfoTitle 走宽字符串糖（u16[N]@utf-16le，同 LOGFONTW.lfFaceName）；
+ *  图标句柄用裸 <>ptr：LoadImageW 的返回类型由 uType 决定（HICON/HCURSOR/HBITMAP），
+ *  绑定给不出品牌——裸地址收品牌指针（子型）无障碍；
+ *  uTimeout 与 uVersion 是同址 union，本仓只用前者（恒 0，不走版本协商），
+ *  故按单字段 u32 声明而非 union 布局。 */
+export const NOTIFYICONDATAW_DECL = {
+    '#': 'struct',
+    cbSize: 'u32',
+    hWnd: '<HWND>ptr',
+    uID: 'u32',
+    uFlags: 'u32',
+    uCallbackMessage: 'u32',
+    hIcon: '<>ptr',
+    szTip: 'u16[128]@utf-16le',
+    dwState: 'u32',
+    dwStateMask: 'u32',
+    szInfo: 'u16[256]@utf-16le',
+    uTimeout: 'u32',
+    szInfoTitle: 'u16[64]@utf-16le',
+    dwInfoFlags: 'u32',
+    guidItem: 'u32[4]',
+    hBalloonIcon: '<>ptr',
+} satisfies C_Struct
+
+export const NOTIFYICONDATAW = /* @__PURE__ */ struct('NOTIFYICONDATAW', NOTIFYICONDATAW_DECL)

package/lib/windows/user32.js

@@ -495,10 +495,10 @@ export const GetSubMenu = /*@__PURE__*/ b('GetSubMenu', '<HMENU>ptr i32 -> <HMEN
  *  @param args_1 uFlags TPM_* 标志
  *  @param args_2 x 屏幕 x
  *  @param args_3 y 屏幕 y
- *  @param args_4 nReserved 保留，传 0
- *  @param args_5 prcRect 点击区矩形（DeepPartial RECT / .ptr / NULL）
- *  @param args_6 hdc 参考 DC，可 NULL */
-export const TrackPopupMenu = /*@__PURE__*/ b('TrackPopupMenu', '<HMENU>ptr u32 i32 i32 i32 <RECT>ptr <HDC>ptr -> i32', { RECT });
+ *  @param args_4 nReserved 保留，传 0（TrackPopupMenuEx 才用）
+ *  @param args_5 hWnd 拥有者窗口（TPM_RETURNCMD 时命令 ID 回到该窗口所属线程队列）
+ *  @param args_6 prcRect 保留位，传 NULL（Win32 文档标注本 API 忽略此参数） */
+export const TrackPopupMenu = /*@__PURE__*/ b('TrackPopupMenu', '<HMENU>ptr u32 i32 i32 i32 <HWND>ptr <RECT>ptr -> i32', { RECT });
 /** 创建弹出菜单；配对 DestroyMenu
  *  @returns 菜单句柄；失败 → NULL */
 export const CreatePopupMenu = /*@__PURE__*/ b('CreatePopupMenu', ' -> <HMENU>ptr');
@@ -534,7 +534,8 @@ export const MessageBox = /*@__PURE__*/ b('MessageBoxW', '<HWND>ptr <WCHAR>ptr <
 // ============ 图像 ============
 /** 按名加载图像（string 自动编码；uType/fuLoad 用 Win32 真值——与 ImageType 枚举当前值
  *  不同）
- *  @returns 图像句柄；失败 → 0
+ *  @returns 图像句柄——类型随 uType（IMAGE_ICON→HICON / CURSOR→HCURSOR / BITMAP→HBITMAP），
+ *    绑定侧给不出品牌故为裸地址档；失败 → 0
  *  @param args_0 hinst 模块句柄，NULL = 系统资源或 .ico 文件
  *  @param args_1 name 图像名 string（资源名或文件路径）
  *  @param args_2 uType IMAGE_* 真值（BITMAP=0/CURSOR=1/ICON=2）

package/lib/windows/user32.ts

@@ -520,10 +520,10 @@ export const GetSubMenu = /*@__PURE__*/ b('GetSubMenu', '<HMENU>ptr i32 -> <HMEN
  *  @param args_1 uFlags TPM_* 标志
  *  @param args_2 x 屏幕 x
  *  @param args_3 y 屏幕 y
- *  @param args_4 nReserved 保留，传 0
- *  @param args_5 prcRect 点击区矩形（DeepPartial RECT / .ptr / NULL）
- *  @param args_6 hdc 参考 DC，可 NULL */
-export const TrackPopupMenu = /*@__PURE__*/ b('TrackPopupMenu', '<HMENU>ptr u32 i32 i32 i32 <RECT>ptr <HDC>ptr -> i32', { RECT })
+ *  @param args_4 nReserved 保留，传 0（TrackPopupMenuEx 才用）
+ *  @param args_5 hWnd 拥有者窗口（TPM_RETURNCMD 时命令 ID 回到该窗口所属线程队列）
+ *  @param args_6 prcRect 保留位，传 NULL（Win32 文档标注本 API 忽略此参数） */
+export const TrackPopupMenu = /*@__PURE__*/ b('TrackPopupMenu', '<HMENU>ptr u32 i32 i32 i32 <HWND>ptr <RECT>ptr -> i32', { RECT })
 /** 创建弹出菜单；配对 DestroyMenu
  *  @returns 菜单句柄；失败 → NULL */
 export const CreatePopupMenu = /*@__PURE__*/ b('CreatePopupMenu', ' -> <HMENU>ptr')
@@ -565,7 +565,8 @@ export const MessageBox = /*@__PURE__*/ b('MessageBoxW', '<HWND>ptr <WCHAR>ptr <
 
 /** 按名加载图像（string 自动编码；uType/fuLoad 用 Win32 真值——与 ImageType 枚举当前值
  *  不同）
- *  @returns 图像句柄；失败 → 0
+ *  @returns 图像句柄——类型随 uType（IMAGE_ICON→HICON / CURSOR→HCURSOR / BITMAP→HBITMAP），
+ *    绑定侧给不出品牌故为裸地址档；失败 → 0
  *  @param args_0 hinst 模块句柄，NULL = 系统资源或 .ico 文件
  *  @param args_1 name 图像名 string（资源名或文件路径）
  *  @param args_2 uType IMAGE_* 真值（BITMAP=0/CURSOR=1/ICON=2）