quickwin 1.3.0 → 2.1.0

package/README.en.md

@@ -30,7 +30,7 @@ The npm package ships 4 executables: `qwin.exe` (64-bit) / `qwin-x86.exe` (32-bi
 - **HTTP/HTTPS** — `fetch()` API, Brotli decompression, chunked transfer, conditional caching
 - **WebSocket** — full RFC 6455 implementation, ws:// + wss://
 - **WebAssembly** — WAMR-based, supports `WebAssembly.*` standard API
-- **FFI** — call any DLL function via libffi
+- **FFI** — call any DLL function via a built-in asm stub and declarative `bind()` signatures (no third-party dependency)
 - **Polyfills** — `TextEncoder`, `URL`, `URLSearchParams`, `btoa`/`atob`, `crypto.subtle`, `setTimeout`
 - **Dynamic import** — `import('https://esm.sh/...')`, no dependency installation needed
 
@@ -105,7 +105,6 @@ When run without a script file argument, `qwin.exe` checks for embedded JS at th
 | `fetch` | `import './lib/fetch.js'` | adds `fetch()`, `Response`, `Headers` to globalThis |
 | `websocket` | `import './lib/websocket.js'` | adds `WebSocket` to globalThis |
 | `polyfill` | `import './lib/polyfill.js'` | adds `TextEncoder`, `URL`, `btoa`/`atob`, `setTimeout` to globalThis |
-| `preact` | `lib/preact/...` | JSX → Win32 renderer (`render`, `useState`, `useEffect`) |
 | `react-qw` | `lib/react-qw/` | React Custom Renderer for Win32 GUI ([docs](lib/react-qw/)) |
 
 ## Worker
@@ -169,8 +168,7 @@ Both sides must set `onmessage = null` when communication is complete. This rele
 
 ### Prerequisites
 
-- MSYS2 UCRT64 or MINGW64
-- Node.js (for TypeScript compilation via tsc)
+- **podman** (dev container; build/test/QEMU verification all run inside the container, consistent with CI)
 - Git (for submodules)
 
 ### Build
@@ -179,38 +177,34 @@ Both sides must set `onmessage = null` when communication is complete. This rele
 git clone --recursive https://github.com/xna00/quickwin.git
 cd quickwin
 
-.\run.ps1 "make wamr"       # build WAMR library (first time only)
-.\run.ps1 "make small"      # build qwin.exe (-Os + LTO, ~1.5MB)
-.\run.ps1 "make js"         # compile TypeScript
-.\run.ps1 "make test"       # run all tests
+./docker/dev-podman.sh up      # start dev container (reuses ghcr.io/xna00/quickwin-dev)
+podman exec quickwin-dev bash -lc 'cd /workspace && make js && make cc64 && make test TEST=-net'
 ```
 
-`make nowasm` produces a smaller `_build/qwin-nowasm.exe` without WASM/WAMR
-(no `WebAssembly` global); run `make test TEST=-wasm` to skip WASM tests on it.
+`make cc64` produces `_build/qwin.exe`. `cc64-nowasm` produces a smaller
+`_build/qwin-nowasm.exe` without WASM/WAMR (no `WebAssembly` global); for
+that build run `make test TEST=-wasm` to skip WASM tests.
 
 ### Build Targets
 
 | Target | Description |
 |--------|-------------|
-| `make` / `make nodebug` | fast build |
-| `make small` | `-Os` + LTO + strip, ~1.5MB (recommended) |
-| `make minimal` | `small` + UPX compression |
-| `make release` | `-O2` + LTO + strip (not `-Os` optimized) |
-| `make debug` | debug build with bridge logs |
-| `make nowasm` | no WASM/WAMR build → `_build/qwin-nowasm.exe` (~1.2MB, no `WebAssembly` global) |
-| `make cc64-small` | cross-compile x86_64 `_build/qwin.exe` (`-Os`, used by CI) |
-| `make cc32-small` | cross-compile i686 `_build/qwin-x86.exe` (`-Os`, XP-compatible, used by CI) |
+| `make cc64` | cross-compile x86_64 → `_build/qwin.exe` (default target, `BUILD=fast`) |
+| `make cc32` | cross-compile i686/XP → `_build/qwin-x86.exe` |
+| `make cc64-nowasm` / `cc32-nowasm` | no WASM/WAMR builds |
+| `BUILD=fast\|small\|debug` | build flavor: `make cc64 BUILD=small` = `-Os`+LTO (~1.5MB, used by CI) |
 | `make js` | compile TypeScript via tsc |
-| `make wasm` | compile WAT → WASM fixtures |
+| `make wasm` | compile `test/*.wat` → WASM fixtures |
 | `make test` | run all tests |
 | `make test TEST=-net` | skip network tests (fast) |
 | `make test TEST=wasm` | run WASM tests only |
-| `make wamr` | rebuild WAMR library |
-| `make embed-js` | embed `embed.js` into exe (use `JS_EMBED=file.js`) |
-| `make embed-js-br` | embed brotli-compressed JS into exe |
-| `make exec_server` | Bundle `examples/exec_server.ts` and brotli-embed into `_build/exec_server.exe` |
+| `make exec_server` | bundle `examples/exec_server.ts` and brotli-embed into `_build/exec_server.exe` |
+| `make embed-js` / `embed-js-br` | embed JS (brotli-compressed) into exe |
 | `make npm-pkg` | package into `dist/quickwin/` |
-| `make clean` | clean build artifacts |
+| `make gen-const` | regenerate `quickwin_const.d.ts` |
+| `make clean` / `distclean` | clean (wipes all of `_build/`; afterwards run `make js wasm`) |
+
+Build and troubleshooting details: `.agents/DEVELOPMENT_WORKFLOW.md`.
 
 ## License
 

package/README.md

@@ -30,7 +30,7 @@ npm 包自带 4 个可执行文件：`qwin.exe`（64 位）/ `qwin-x86.exe`（32
 - **HTTP/HTTPS** —— `fetch()` API、Brotli 解压、chunked 传输、条件缓存
 - **WebSocket** —— 完整的 RFC 6455 实现，支持 ws:// 与 wss://
 - **WebAssembly** —— 基于 WAMR，支持标准 `WebAssembly.*` API
-- **FFI** —— 通过 libffi 调用任意 DLL 函数
+- **FFI** —— 内置汇编调用桩，用 `bind()` 声明式签名调用任意 DLL 函数（无第三方依赖）
 - **Polyfills** —— `TextEncoder`、`URL`、`URLSearchParams`、`btoa`/`atob`、`crypto.subtle`、`setTimeout`
 - **动态导入** —— `import('https://esm.sh/...')`，无需安装任何依赖
 
@@ -104,7 +104,6 @@ _build/exec_server.exe
 | `fetch` | `import './lib/fetch.js'` | 向 globalThis 添加 `fetch()`、`Response`、`Headers` |
 | `websocket` | `import './lib/websocket.js'` | 向 globalThis 添加 `WebSocket` |
 | `polyfill` | `import './lib/polyfill.js'` | 向 globalThis 添加 `TextEncoder`、`URL`、`btoa`/`atob`、`setTimeout` |
-| `preact` | `lib/preact/...` | JSX → Win32 渲染器（`render`、`useState`、`useEffect`） |
 | `react-qw` | `lib/react-qw/` | 面向 Win32 GUI 的 React 自定义渲染器（[文档](lib/react-qw/)） |
 
 ## Worker
@@ -168,8 +167,7 @@ parent.onmessage = (e) => {
 
 ### 前置依赖
 
-- MSYS2 UCRT64 或 MINGW64
-- Node.js（用于通过 tsc 编译 TypeScript）
+- **podman**（开发容器；构建/测试/QEMU 验证都在容器内完成，与 CI 一致）
 - Git（用于子模块）
 
 ### 构建
@@ -178,38 +176,34 @@ parent.onmessage = (e) => {
 git clone --recursive https://github.com/xna00/quickwin.git
 cd quickwin
 
-.\run.ps1 "make wamr"       # 构建 WAMR 库（仅首次）
-.\run.ps1 "make small"      # 构建 qwin.exe（-Os + LTO，约 1.5MB）
-.\run.ps1 "make js"         # 编译 TypeScript
-.\run.ps1 "make test"       # 运行全部测试
+./docker/dev-podman.sh up      # 启动开发容器（复用 ghcr.io/xna00/quickwin-dev）
+podman exec quickwin-dev bash -lc 'cd /workspace && make js && make cc64 && make test TEST=-net'
 ```
 
-`make nowasm` 会产出更小的 `_build/qwin-nowasm.exe`，不含 WASM/WAMR
-（没有 `WebAssembly` 全局对象）；对这种版本运行 `make test TEST=-wasm` 跳过 WASM 测试。
+`make cc64` 产出 `_build/qwin.exe`。`cc64-nowasm` 会产出更小的
+`_build/qwin-nowasm.exe`，不含 WASM/WAMR（没有 `WebAssembly` 全局对象）；
+对这种版本运行 `make test TEST=-wasm` 跳过 WASM 测试。
 
 ### 构建目标
 
 | Target | Description |
 |--------|-------------|
-| `make` / `make nodebug` | 快速构建 |
-| `make small` | `-Os` + LTO + strip，约 1.5MB（推荐） |
-| `make minimal` | `small` + UPX 压缩 |
-| `make release` | `-O2` + LTO + strip（未做 `-Os` 优化） |
-| `make debug` | 带 bridge 日志的调试构建 |
-| `make nowasm` | 无 WASM/WAMR 构建 → `_build/qwin-nowasm.exe`（约 1.2MB，无 `WebAssembly` 全局） |
-| `make cc64-small` | 交叉编译 x86_64 `_build/qwin.exe`（`-Os`，CI 用） |
-| `make cc32-small` | 交叉编译 i686 `_build/qwin-x86.exe`（`-Os`，兼容 XP，CI 用） |
+| `make cc64` | 交叉编译 x86_64 → `_build/qwin.exe`（默认目标，`BUILD=fast`） |
+| `make cc32` | 交叉编译 i686/XP → `_build/qwin-x86.exe` |
+| `make cc64-nowasm` / `cc32-nowasm` | 无 WASM/WAMR 版 |
+| `BUILD=fast\|small\|debug` | 构建 flavor：`make cc64 BUILD=small` = `-Os`+LTO（约 1.5MB，CI 用） |
 | `make js` | 通过 tsc 编译 TypeScript |
-| `make wasm` | 编译 WAT → WASM fixtures |
+| `make wasm` | 编译 `test/*.wat` → WASM fixtures |
 | `make test` | 运行全部测试 |
 | `make test TEST=-net` | 跳过网络测试（快速） |
 | `make test TEST=wasm` | 仅运行 WASM 测试 |
-| `make wamr` | 重建 WAMR 库 |
-| `make embed-js` | 把 `embed.js` 内嵌进 exe（用 `JS_EMBED=file.js`） |
-| `make embed-js-br` | 把 Brotli 压缩的 JS 内嵌进 exe |
 | `make exec_server` | 打包 `examples/exec_server.ts` 并 Brotli 内嵌进 `_build/exec_server.exe` |
+| `make embed-js` / `embed-js-br` | 把 JS（Brotli 压缩）内嵌进 exe |
 | `make npm-pkg` | 打包到 `dist/quickwin/` |
-| `make clean` | 清理构建产物 |
+| `make gen-const` | 重新生成 `quickwin_const.d.ts` |
+| `make clean` / `distclean` | 清理（会清掉整个 `_build/`，之后需 `make js wasm`） |
+
+构建与排错细节见 `.agents/DEVELOPMENT_WORKFLOW.md`。
 
 ## 许可证
 

package/examples/PdfCanvas.js

@@ -1,32 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef, useRef } from 'react';
-import * as win from 'win';
-import * as ffi from 'ffi';
-const _user32 = win.LoadLibrary('user32.dll');
-const _gdi32 = win.LoadLibrary('gdi32.dll');
-if (!_user32 || !_gdi32)
-    throw new Error('Failed to load user32/gdi32');
-function loadProc(lib, name) {
-    const ptr = win.GetProcAddress(lib, name);
-    if (!ptr)
-        throw new Error('Failed to load ' + name);
-    return ptr;
-}
-const GetDC_ = loadProc(_user32, 'GetDC');
-const ReleaseDC_ = loadProc(_user32, 'ReleaseDC');
-const SetDIBitsToDevice_ = loadProc(_gdi32, 'SetDIBitsToDevice');
-const FFI_PTR = ffi.FFI_TYPE_POINTER;
-const FFI_U32 = ffi.FFI_TYPE_UINT32;
-const FFI_S32 = ffi.FFI_TYPE_SINT32;
+import { GetDC, ReleaseDC } from '../lib/windows/user32.js';
+import { SetDIBitsToDevice } from '../lib/windows/gdi32.js';
+import { BITMAPINFOHEADER } from '../lib/windows/structs.js';
 function makeBitmapInfo(w, h) {
-    const bmi = new ArrayBuffer(40);
-    const bv = new DataView(bmi);
-    bv.setUint32(0, 40, true);
-    bv.setInt32(4, w, true);
-    bv.setInt32(8, -h, true);
-    bv.setUint16(12, 1, true);
-    bv.setUint16(14, 24, true);
-    return bmi;
+    // biHeight 负 = 自顶向下（DIB 原点左上）；biCompression 缺省 0 = BI_RGB 无压缩
+    return BITMAPINFOHEADER.encode({ biSize: BITMAPINFOHEADER.size, biWidth: w, biHeight: -h, biPlanes: 1, biBitCount: 24 });
 }
 export const PdfCanvas = forwardRef(({ pixmap, style }, ref) => {
     const canvasRef = useRef(null);
@@ -46,19 +25,11 @@ export const PdfCanvas = forwardRef(({ pixmap, style }, ref) => {
                 const pm = pixmapRef.current;
                 if (!pm)
                     return 0;
-                const hdc = ffi.ffiCall(GetDC_, [ffi.FFI_TYPE_POINTER], [hwnd], ffi.FFI_TYPE_POINTER);
+                const hdc = GetDC(hwnd);
                 if (hdc) {
                     const bmi = makeBitmapInfo(pm.w, pm.h);
-                    ffi.ffiCall(SetDIBitsToDevice_, [
-                        ffi.FFI_TYPE_POINTER, FFI_S32, FFI_S32, FFI_U32, FFI_U32,
-                        FFI_S32, FFI_S32, FFI_U32, FFI_U32,
-                        FFI_PTR, FFI_PTR, FFI_U32
-                    ], [
-                        hdc, 0, 0, pm.w, pm.h,
-                        0, 0, 0, pm.h,
-                        pm.data, bmi, 0
-                    ], FFI_S32);
-                    ffi.ffiCall(ReleaseDC_, [ffi.FFI_TYPE_POINTER, ffi.FFI_TYPE_POINTER], [hwnd, hdc], FFI_S32);
+                    SetDIBitsToDevice(hdc, 0, 0, pm.w, pm.h, 0, 0, 0, pm.h, pm.data, bmi, 0);
+                    ReleaseDC(hwnd, hdc);
                 }
                 return 0;
             }

package/examples/PdfCanvas.tsx

@@ -1,40 +1,18 @@
+import { PtrArrayBuffer } from '../lib/ffi/ctype.js'
 import { forwardRef, useRef } from 'react'
 import * as gui from 'gui'
-import * as win from 'win'
-import * as ffi from 'ffi'
+import { GetDC, ReleaseDC } from '../lib/windows/user32.js'
+import { SetDIBitsToDevice } from '../lib/windows/gdi32.js'
+import { BITMAPINFOHEADER } from '../lib/windows/structs.js'
 import type { WStyle } from '../lib/react-qw/jsx.d.ts'
 
-const _user32 = win.LoadLibrary('user32.dll')
-const _gdi32 = win.LoadLibrary('gdi32.dll')
-if (!_user32 || !_gdi32) throw new Error('Failed to load user32/gdi32')
-
-function loadProc(lib: win.HMODULE, name: string): number {
-  const ptr = win.GetProcAddress(lib, name)
-  if (!ptr) throw new Error('Failed to load ' + name)
-  return ptr
-}
-
-const GetDC_ = loadProc(_user32, 'GetDC')
-const ReleaseDC_ = loadProc(_user32, 'ReleaseDC')
-const SetDIBitsToDevice_ = loadProc(_gdi32, 'SetDIBitsToDevice')
-
-const FFI_PTR = ffi.FFI_TYPE_POINTER
-const FFI_U32 = ffi.FFI_TYPE_UINT32
-const FFI_S32 = ffi.FFI_TYPE_SINT32
-
-function makeBitmapInfo(w: number, h: number): ArrayBuffer {
-  const bmi = new ArrayBuffer(40)
-  const bv = new DataView(bmi)
-  bv.setUint32(0, 40, true)
-  bv.setInt32(4, w, true)
-  bv.setInt32(8, -h, true)
-  bv.setUint16(12, 1, true)
-  bv.setUint16(14, 24, true)
-  return bmi
+function makeBitmapInfo(w: number, h: number) {
+  // biHeight 负 = 自顶向下（DIB 原点左上）；biCompression 缺省 0 = BI_RGB 无压缩
+  return BITMAPINFOHEADER.encode({ biSize: BITMAPINFOHEADER.size, biWidth: w, biHeight: -h, biPlanes: 1, biBitCount: 24 })
 }
 
 export interface PdfCanvasProps {
-  pixmap?: { data: ArrayBuffer; w: number; h: number }
+  pixmap?: { data: PtrArrayBuffer<string>; w: number; h: number }
   style?: WStyle
 }
 
@@ -59,19 +37,11 @@ export const PdfCanvas = forwardRef<gui.HWND, PdfCanvasProps>(
           if (e.msg === gui.WmMsg.PAINT) {
             const pm = pixmapRef.current
             if (!pm) return 0
-            const hdc = ffi.ffiCall(GetDC_, [ffi.FFI_TYPE_POINTER], [hwnd], ffi.FFI_TYPE_POINTER)
+            const hdc = GetDC(hwnd)
             if (hdc) {
               const bmi = makeBitmapInfo(pm.w, pm.h)
-              ffi.ffiCall(SetDIBitsToDevice_, [
-                ffi.FFI_TYPE_POINTER, FFI_S32, FFI_S32, FFI_U32, FFI_U32,
-                FFI_S32, FFI_S32, FFI_U32, FFI_U32,
-                FFI_PTR, FFI_PTR, FFI_U32
-              ], [
-                hdc, 0, 0, pm.w, pm.h,
-                0, 0, 0, pm.h,
-                pm.data, bmi, 0
-              ], FFI_S32)
-              ffi.ffiCall(ReleaseDC_, [ffi.FFI_TYPE_POINTER, ffi.FFI_TYPE_POINTER], [hwnd, hdc], FFI_S32)
+              SetDIBitsToDevice(hdc, 0, 0, pm.w, pm.h, 0, 0, 0, pm.h, pm.data, bmi, 0)
+              ReleaseDC(hwnd, hdc)
             }
             return 0
           }