quickwin 1.2.1 → 2.0.0

package/README.en.md

@@ -13,10 +13,11 @@ Install:
 ```bash
 # Option 1: npm local install (recommended)
 npm install quickwin
-npx quickwin script.js
+npx quickwin node_modules/quickwin/main.js   # bundled main.js demo; use npx quickwin script.js for your own scripts
 
 # Option 2: download directly from GitHub Release
 iwr https://github.com/xna00/quickwin/releases/latest/download/qwin.exe -OutFile qwin.exe
+iwr https://github.com/xna00/quickwin/releases/latest/download/main.js -OutFile main.js
 .\qwin.exe main.js
 ```
 
@@ -29,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
 
@@ -104,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

package/README.md

@@ -13,10 +13,11 @@ Windows 平台上的 QuickJS 运行时，支持原生 GUI、网络、WASM、FFI
 ```bash
 # 方式一：npm 本地安装（推荐）
 npm install quickwin
-npx quickwin script.js
+npx quickwin node_modules/quickwin/main.js   # 包自带 main.js 示例；用 npx quickwin script.js 运行你自己的脚本
 
 # 方式二：直接从 GitHub Release 下载
 iwr https://github.com/xna00/quickwin/releases/latest/download/qwin.exe -OutFile qwin.exe
+iwr https://github.com/xna00/quickwin/releases/latest/download/main.js -OutFile main.js
 .\qwin.exe main.js
 ```
 
@@ -29,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/...')`，无需安装任何依赖
 
@@ -103,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
@@ -167,48 +167,45 @@ parent.onmessage = (e) => {
 
 ### 前置依赖
 
-- MSYS2 UCRT64 或 MINGW64
-- Node.js（用于通过 tsc 编译 TypeScript）
+- **podman**（开发容器；构建/测试/QEMU 验证都在容器内完成，与 CI 一致）
 - Git（用于子模块）
 
+> 也支持 MSYS2 原生直接 `make`，详见 `.agents/DEVELOPMENT_WORKFLOW.md`。
+
 ### 构建
 
 ```bash
 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` / `make wat` | 编译 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_UINT64], [hwnd], ffi.FFI_TYPE_UINT64);
+                const hdc = GetDC(hwnd);
                 if (hdc) {
                     const bmi = makeBitmapInfo(pm.w, pm.h);
-                    ffi.ffiCall(SetDIBitsToDevice_, [
-                        ffi.FFI_TYPE_UINT64, 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_UINT64, ffi.FFI_TYPE_UINT64], [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_UINT64], [hwnd], ffi.FFI_TYPE_UINT64)
+            const hdc = GetDC(hwnd)
             if (hdc) {
               const bmi = makeBitmapInfo(pm.w, pm.h)
-              ffi.ffiCall(SetDIBitsToDevice_, [
-                ffi.FFI_TYPE_UINT64, 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_UINT64, ffi.FFI_TYPE_UINT64], [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
           }