quickwin 1.0.0

package/README.en.md

@@ -0,0 +1,197 @@
+> [中文文档](README.md) · **English**
+
+# QuickWin
+
+QuickJS Win32 runtime — run JavaScript with native Windows GUI, networking, WASM, FFI, and more.
+
+```bash
+npm i -g quickwin
+quickwin script.js
+```
+
+## Features
+
+- **Win32 GUI** — native windows, buttons, edit boxes, list boxes, tray icons, popup menus
+- **React renderer** — declarative GUI in JSX with `useState`/`useEffect`, diff updates ([react-qw](lib/react-qw/))
+- **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
+- **mupdf** — embedded PDF rendering
+- **Polyfills** — `TextEncoder`, `URL`, `URLSearchParams`, `btoa`/`atob`, `crypto.subtle`, `setTimeout`
+- **Dynamic import** — `import('https://esm.sh/...')`, no npm install needed
+
+## CLI
+
+```bash
+quickwin script.js                  # run a script
+quickwin -o CON script.js           # run with console (AllocConsole)
+quickwin -o LOG script.js           # run with auto-generated log file
+quickwin -e "console.log('hi')"     # execute expression
+quickwin -- script.js --flag        # -- stops option parsing
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-e <expr>` | Execute expression instead of a file |
+| `-o CON` | Allocate console (`AllocConsole`); only needed for GUI-subsystem builds |
+| `-o LOG` | Redirect stdout+stderr to `log_YYYY_MM_DD_HH_MM_SS.txt` (exe directory) |
+| `-o <file>` | Redirect stdout+stderr to specified file |
+| `-d` | Enable HTTP debug logging |
+| `--` | Stop option parsing, remaining args passed to script |
+
+All unknown flags are transparently forwarded to `scriptArgs` — no error,
+no consumption. Script file is the first non-flag argument after option parsing.
+
+## Embedded Script
+
+You can embed a JS script directly into the `qwin.exe` binary — no recompilation needed.
+
+### Format (appended to exe)
+
+```
+[JS bytes (N)] [N: uint32 LE] [magic "QWJS"]
+```
+
+### Usage
+
+```bash
+# Embed a script
+powershell -ExecutionPolicy Bypass -File scripts/embed-js.ps1 -ExePath _build/qwin.exe -JsFile script.js
+
+# Or via make
+make embed-js JS_EMBED=script.js
+
+# Embed a script brotli-compressed (smaller exe, decompressed at runtime)
+make embed-js-br JS_EMBED=script.js
+
+# Run it (no file argument needed)
+qwin.exe
+```
+
+When run without a script file argument, `qwin.exe` checks for embedded JS at the end of itself. If found, it executes the embedded code. If not, it falls back to `main.js`. Both raw (`QWJS`) and brotli-compressed (`QWBR`) embedded payloads are supported; the compressed form is decompressed at startup.
+
+## Modules
+
+| Module | Import | Description |
+|--------|--------|-------------|
+| `std` | built-in | file I/O, environment, URL download |
+| `os` | built-in | filesystem, process, Worker, timer |
+| `gui` | built-in | Win32 window/control/message/tray API |
+| `sock` | built-in | socket networking (`AddrFamily`, `FdEvent` etc.) |
+| `wolfssl` | built-in | TLS/SSL (`VerifyMode`, `ReturnCode` etc.) |
+| `ffi` | built-in | foreign function interface |
+| `win` | built-in | DLL loading (`LoadLibrary`, `GetProcAddress`) |
+| `brotli` | built-in | Brotli decompression |
+| `wamr` | built-in | low-level WAMR API |
+| `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
+
+Spawn background threads for CPU-bound or I/O-bound work. Workers run in separate QuickJS runtimes with their own event loops.
+
+### Main Thread
+
+```js
+import * as os from 'os'
+
+const worker = new os.Worker('./worker.js')
+
+worker.onmessage = (e) => {
+    console.log('received:', e.data)
+    worker.onmessage = null  // clean up when done
+}
+
+worker.postMessage({ type: 'start', value: 42 })
+```
+
+### Worker Thread
+
+```js
+// worker.js
+import * as os from 'os'
+
+const parent = os.Worker.parent
+
+parent.onmessage = (e) => {
+    if (e.data.type === 'start') {
+        parent.postMessage({ type: 'result', value: e.data.value * 2 })
+    } else if (e.data.type === 'done') {
+        parent.onmessage = null  // clean up to allow event loop exit
+    }
+}
+```
+
+### API
+
+| API | Description |
+|-----|-------------|
+| `new os.Worker(specifier)` | Create worker. `specifier` is a file path or URL (supports `https://` for ESM imports) |
+| `worker.postMessage(data)` | Send message (JSON-serializable) to worker |
+| `worker.onmessage = fn` | Set callback for messages from worker. Set to `null` when done to release the message port |
+| `os.Worker.parent` | (Worker side) reference to the parent thread |
+
+### Cleanup
+
+Both sides must set `onmessage = null` when communication is complete. This releases the message port so the event loop can exit cleanly. Forgetting to do so will cause the process to hang.
+
+## Examples
+
+```bash
+npx quickwin examples/preact_demo.js   # counter GUI with JSX + hooks
+npx quickwin examples/tray_demo.js     # system tray app
+npx quickwin examples/pdf_preview.js   # PDF reader with mupdf
+```
+
+## Build from Source
+
+### Prerequisites
+
+- MSYS2 UCRT64 or MINGW64
+- Node.js (for TypeScript compilation via tsc)
+- Git (for submodules)
+
+### Build
+
+```bash
+git clone --recursive https://github.com/anomalyco/quickwin.git
+cd quickwin
+
+.\run.ps1 "make wamr"       # build WAMR library (first time only)
+.\run.ps1 "make minimal"    # build qwin.exe (-Os + LTO + UPX)
+.\run.ps1 "make js"         # compile TypeScript
+.\run.ps1 "make test"       # run all tests
+```
+
+`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.
+
+### Build Targets
+
+| Target | Description |
+|--------|-------------|
+| `make` / `make nodebug` | fast build |
+| `make minimal` | `-Os` + LTO + `-mwindows` + UPX, no console, add `-o CON` for console |
+| `make nowasm` | no WASM/WAMR build → `_build/qwin-nowasm.exe` (~1.2MB, no `WebAssembly` global) |
+| `make release` | `-O2` + LTO + strip, ~2.5MB |
+| `make debug` | debug build with bridge logs |
+| `make js` | compile TypeScript via tsc |
+| `make wasm` | compile 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 npm-pkg` | package into `dist/quickwin/` |
+| `make clean` | clean build artifacts |
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,196 @@
+> [English](README.en.md) · **中文**
+
+# QuickWin
+
+QuickJS Win32 运行时 —— 用原生 Windows GUI、网络、WASM、FFI 等运行 JavaScript。
+
+```bash
+npm i -g quickwin
+quickwin script.js
+```
+
+## 特性
+
+- **Win32 原生 GUI** —— 原生窗口、按钮、编辑框、列表框、托盘图标、弹出菜单
+- **React 渲染器** —— 用 JSX 声明式 GUI，支持 `useState`/`useEffect`，diff 增量更新（[react-qw](lib/react-qw/)）
+- **HTTP/HTTPS** —— `fetch()` API、Brotli 解压、chunked 传输、条件缓存
+- **WebSocket** —— 完整的 RFC 6455 实现，支持 ws:// 与 wss://
+- **WebAssembly** —— 基于 WAMR，支持标准 `WebAssembly.*` API
+- **FFI** —— 通过 libffi 调用任意 DLL 函数
+- **mupdf** —— 内嵌 PDF 渲染
+- **Polyfills** —— `TextEncoder`、`URL`、`URLSearchParams`、`btoa`/`atob`、`crypto.subtle`、`setTimeout`
+- **动态导入** —— `import('https://esm.sh/...')`，无需 npm install
+
+## CLI
+
+```bash
+quickwin script.js                  # 运行脚本
+quickwin -o CON script.js           # 带控制台运行（AllocConsole）
+quickwin -o LOG script.js           # 自动生成日志文件运行
+quickwin -e "console.log('hi')"     # 执行表达式
+quickwin -- script.js --flag        # -- 停止选项解析
+```
+
+### 选项
+
+| Flag | Description |
+|------|-------------|
+| `-e <expr>` | 执行表达式而不是文件 |
+| `-o CON` | 分配控制台（`AllocConsole`）；仅 GUI 子系统构建所需 |
+| `-o LOG` | 将 stdout+stderr 重定向到 `log_YYYY_MM_DD_HH_MM_SS.txt`（exe 所在目录） |
+| `-o <file>` | 将 stdout+stderr 重定向到指定文件 |
+| `-d` | 开启 HTTP 调试日志 |
+| `--` | 停止选项解析，其余参数传给脚本 |
+
+所有未知参数都会透明转发给 `scriptArgs` —— 不报错、不消费。选项解析后的第一个非参数即脚本文件。
+
+## 内嵌脚本
+
+可以把一个 JS 脚本直接内嵌进 `qwin.exe` 二进制 —— 无需重新编译。
+
+### 格式（追加到 exe 末尾）
+
+```
+[JS bytes (N)] [N: uint32 LE] [magic "QWJS"]
+```
+
+### 用法
+
+```bash
+# 内嵌一个脚本
+powershell -ExecutionPolicy Bypass -File scripts/embed-js.ps1 -ExePath _build/qwin.exe -JsFile script.js
+
+# 或通过 make
+make embed-js JS_EMBED=script.js
+
+# 内嵌 Brotli 压缩的脚本（exe 更小，运行时解压）
+make embed-js-br JS_EMBED=script.js
+
+# 运行它（不需要文件参数）
+qwin.exe
+```
+
+不带脚本文件参数运行时，`qwin.exe` 会检查自身末尾是否有内嵌 JS：找到则执行内嵌代码，否则回退到 `main.js`。同时支持原始（`QWJS`）与 Brotli 压缩（`QWBR`）两种内嵌格式；压缩格式在启动时解压。
+
+## 模块
+
+| Module | Import | Description |
+|--------|--------|-------------|
+| `std` | built-in | 文件 I/O、环境变量、URL 下载 |
+| `os` | built-in | 文件系统、进程、Worker、定时器 |
+| `gui` | built-in | Win32 窗口/控件/消息/托盘 API |
+| `sock` | built-in | Socket 网络（`AddrFamily`、`FdEvent` 等） |
+| `wolfssl` | built-in | TLS/SSL（`VerifyMode`、`ReturnCode` 等） |
+| `ffi` | built-in | 外部函数接口 |
+| `win` | built-in | DLL 加载（`LoadLibrary`、`GetProcAddress`） |
+| `brotli` | built-in | Brotli 解压 |
+| `wamr` | built-in | 底层 WAMR API |
+| `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
+
+面向 CPU 密集或 I/O 密集工作创建后台线程。Worker 运行在独立的 QuickJS runtime 中，各自拥有自己的事件循环。
+
+### 主线程
+
+```js
+import * as os from 'os'
+
+const worker = new os.Worker('./worker.js')
+
+worker.onmessage = (e) => {
+    console.log('received:', e.data)
+    worker.onmessage = null  // 完成后清理
+}
+
+worker.postMessage({ type: 'start', value: 42 })
+```
+
+### Worker 线程
+
+```js
+// worker.js
+import * as os from 'os'
+
+const parent = os.Worker.parent
+
+parent.onmessage = (e) => {
+    if (e.data.type === 'start') {
+        parent.postMessage({ type: 'result', value: e.data.value * 2 })
+    } else if (e.data.type === 'done') {
+        parent.onmessage = null  // 清理以允许事件循环退出
+    }
+}
+```
+
+### API
+
+| API | Description |
+|-----|-------------|
+| `new os.Worker(specifier)` | 创建 worker。`specifier` 是文件路径或 URL（支持 `https://` ESM 导入） |
+| `worker.postMessage(data)` | 向 worker 发送消息（JSON 可序列化） |
+| `worker.onmessage = fn` | 设置来自 worker 的消息回调。完成后设为 `null` 以释放消息端口 |
+| `os.Worker.parent` | （Worker 侧）父线程的引用 |
+
+### 清理
+
+通信完成后，双方都必须把 `onmessage` 设为 `null`。这会释放消息端口，使事件循环能够干净退出。忘记设置会导致进程挂起。
+
+## 示例
+
+```bash
+npx quickwin examples/preact_demo.js   # JSX + hooks 的计数器 GUI
+npx quickwin examples/tray_demo.js     # 系统托盘应用
+npx quickwin examples/pdf_preview.js   # 基于 mupdf 的 PDF 阅读器
+```
+
+## 从源码构建
+
+### 前置依赖
+
+- MSYS2 UCRT64 或 MINGW64
+- Node.js（用于通过 tsc 编译 TypeScript）
+- Git（用于子模块）
+
+### 构建
+
+```bash
+git clone --recursive https://github.com/anomalyco/quickwin.git
+cd quickwin
+
+.\run.ps1 "make wamr"       # 构建 WAMR 库（仅首次）
+.\run.ps1 "make minimal"    # 构建 qwin.exe（-Os + LTO + UPX）
+.\run.ps1 "make js"         # 编译 TypeScript
+.\run.ps1 "make test"       # 运行全部测试
+```
+
+`make nowasm` 会产出更小的 `_build/qwin-nowasm.exe`，不含 WASM/WAMR
+（没有 `WebAssembly` 全局对象）；对这种版本运行 `make test TEST=-wasm` 跳过 WASM 测试。
+
+### 构建目标
+
+| Target | Description |
+|--------|-------------|
+| `make` / `make nodebug` | 快速构建 |
+| `make minimal` | `-Os` + LTO + `-mwindows` + UPX，无控制台，需要控制台时加 `-o CON` |
+| `make nowasm` | 无 WASM/WAMR 构建 → `_build/qwin-nowasm.exe`（约 1.2MB，无 `WebAssembly` 全局） |
+| `make release` | `-O2` + LTO + strip，约 2.5MB |
+| `make debug` | 带 bridge 日志的调试构建 |
+| `make js` | 通过 tsc 编译 TypeScript |
+| `make wasm` | 编译 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 npm-pkg` | 打包到 `dist/quickwin/` |
+| `make clean` | 清理构建产物 |
+
+## 许可证
+
+MIT

package/examples/PdfCanvas.js

@@ -0,0 +1,67 @@
+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;
+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;
+}
+export const PdfCanvas = forwardRef(({ pixmap, style }, ref) => {
+    const canvasRef = useRef(null);
+    const pixmapRef = useRef(pixmap);
+    pixmapRef.current = pixmap;
+    return (_jsx("w", { type: "STATIC", ws: 268435456 /* gui.WindowStyle.VISIBLE */ | 33554432 /* gui.WindowStyle.CLIPCHILDREN */, style: style, ref: (h) => {
+            canvasRef.current = h;
+            if (typeof ref === 'function')
+                ref(h);
+            else if (ref)
+                ref.current = h;
+        }, onEvent: (e) => {
+            const hwnd = e.hwnd;
+            if (e.msg === 0x14)
+                return 1;
+            if (e.msg === 15 /* 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);
+                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);
+                }
+                return 0;
+            }
+            return;
+        } }));
+});

package/examples/PdfCanvas.tsx

@@ -0,0 +1,83 @@
+import { forwardRef, useRef } from 'react'
+import * as gui from 'gui'
+import * as win from 'win'
+import * as ffi from 'ffi'
+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
+}
+
+export interface PdfCanvasProps {
+  pixmap?: { data: ArrayBuffer; w: number; h: number }
+  style?: WStyle
+}
+
+export const PdfCanvas = forwardRef<gui.HWND, PdfCanvasProps>(
+  ({ pixmap, style }, ref) => {
+    const canvasRef = useRef<gui.HWND>(null)
+    const pixmapRef = useRef(pixmap)
+    pixmapRef.current = pixmap
+
+    return (
+      <w type="STATIC"
+        ws={gui.WindowStyle.VISIBLE | gui.WindowStyle.CLIPCHILDREN}
+        style={style}
+        ref={(h: gui.HWND) => {
+          canvasRef.current = h
+          if (typeof ref === 'function') ref(h)
+          else if (ref) (ref as React.RefObject<gui.HWND | null>).current = h
+        }}
+        onEvent={(e) => {
+          const hwnd = e.hwnd
+          if (e.msg === 0x14) return 1
+          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)
+            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)
+            }
+            return 0
+          }
+          return
+        }}
+      />
+    )
+  }
+)