quickwin 2.1.1 → 2.3.0

package/examples/tray_demo.tsx

@@ -1,5 +1,6 @@
 import * as gui from 'gui'
 import * as std from 'std'
+import { IDI, ImageType, LoadImageFlag, NotifyIconCmd, NotifyIconFlag, WindowStyle, WmMsg } from '../constants'
 
 const WM_TRAY = 0x8001
 
@@ -24,14 +25,14 @@ gui.RegisterClass('TrayApp', (hwnd, msg, wParam, lParam) => {
                 if (cmd === 1) {
                     gui.ShowWindow(hwnd, 5) // SW_SHOW
                 } else if (cmd === 2) {
-                    gui.ShellNotifyIcon(gui.NotifyIconCmd.DELETE, { hwnd, uID: 1 })
+                    gui.ShellNotifyIcon(NotifyIconCmd.DELETE, { hwnd, uID: 1 })
                     gui.PostQuitMessage(0)
                 }
             }
         }
         return 0
     }
-    if (msg === gui.WmMsg.CLOSE) {
+    if (msg === WmMsg.CLOSE) {
         gui.ShowWindow(hwnd, 0) // SW_HIDE
         return 0
     }
@@ -43,14 +44,14 @@ const W = 500, H = 400
 const scr = gui.GetScreenSize()
 const x = (scr[0] - W) >> 1
 const y = (scr[1] - H) >> 1
-const hwnd = gui.CreateWindow('TrayApp', '系统托盘示例', gui.WindowStyle.OVERLAPPEDWINDOW, x, y, W, H, null, null)
+const hwnd = gui.CreateWindow('TrayApp', '系统托盘示例', WindowStyle.OVERLAPPEDWINDOW, x, y, W, H, null, null)
 if (!hwnd) std.exit(0)
 gui.ShowWindow(hwnd)
 
 // 添加说明文字
 const ES_MULTILINE = 0x0004
 const ES_READONLY = 0x0800
-const style = gui.WindowStyle.CHILD | gui.WindowStyle.VISIBLE | ES_MULTILINE | ES_READONLY
+const style = WindowStyle.CHILD | WindowStyle.VISIBLE | ES_MULTILINE | ES_READONLY
 const text = gui.CreateWindow('EDIT',
     'QuickWin 系统托盘示例\r\n'
     + '\r\n'
@@ -61,15 +62,15 @@ const text = gui.CreateWindow('EDIT',
 if (text) {
     const font = gui.CreateSystemDpiFont()
     if (font)
-        gui.SendMessage(text, gui.WmMsg.SETFONT, font, 1)
+        gui.SendMessage(text, WmMsg.SETFONT, font, 1)
 }
 
 let hIcon = gui.LoadAppIcon()
-if (!hIcon) hIcon = gui.LoadImage(null, gui.IDI.APPLICATION, gui.ImageType.ICON, 0, 0, gui.LoadImageFlag.SHARED)
+if (!hIcon) hIcon = gui.LoadImage(null, IDI.APPLICATION, ImageType.ICON, 0, 0, LoadImageFlag.SHARED)
 if (hIcon) {
-    const ok = gui.ShellNotifyIcon(gui.NotifyIconCmd.ADD, {
+    const ok = gui.ShellNotifyIcon(NotifyIconCmd.ADD, {
         hwnd: hwnd, uID: 1,
-        flags: gui.NotifyIconFlag.MESSAGE | gui.NotifyIconFlag.ICON,
+        flags: NotifyIconFlag.MESSAGE | NotifyIconFlag.ICON,
         callbackMessage: WM_TRAY,
         hIcon,
     })

package/lib/dumpRects.js

@@ -2,7 +2,7 @@ import * as os from 'os';
 import * as gui from 'gui';
 export function startDumpRects(rootHwnd, intervalMs = 3000) {
     function dumpChild(parent, indent) {
-        var ch = gui.GetWindow(parent, 5 /* gui.GetWindowCmd.CHILD */);
+        var ch = gui.GetWindow(parent, 5 /* GetWindowCmd.CHILD */);
         var n = 0;
         while (ch) {
             n++;
@@ -11,7 +11,7 @@ export function startDumpRects(rootHwnd, intervalMs = 3000) {
             var txt = String(gui.GetWindowText(ch) || '').slice(0, 16);
             console.log(indent + '[' + n + '] hwnd=' + String(ch) + ' txt="' + txt + '" wr=' + JSON.stringify(wr) + ' cr=' + JSON.stringify(cr));
             dumpChild(ch, indent + '  ');
-            ch = gui.GetWindow(ch, 2 /* gui.GetWindowCmd.NEXT */);
+            ch = gui.GetWindow(ch, 2 /* GetWindowCmd.NEXT */);
         }
         if (n === 0)
             console.log(indent + '(no children)');

package/lib/dumpRects.ts

@@ -1,9 +1,10 @@
 import * as os from 'os'
 import * as gui from 'gui'
+import { GetWindowCmd } from '../constants'
 
 export function startDumpRects(rootHwnd: gui.HWND, intervalMs: number = 3000): void {
   function dumpChild(parent: gui.HWND, indent: string): void {
-    var ch = gui.GetWindow(parent, gui.GetWindowCmd.CHILD)
+    var ch = gui.GetWindow(parent, GetWindowCmd.CHILD)
     var n = 0
     while (ch) {
       n++
@@ -12,7 +13,7 @@ export function startDumpRects(rootHwnd: gui.HWND, intervalMs: number = 3000): v
       var txt = String(gui.GetWindowText(ch) || '').slice(0, 16)
       console.log(indent + '[' + n + '] hwnd=' + String(ch) + ' txt="' + txt + '" wr=' + JSON.stringify(wr) + ' cr=' + JSON.stringify(cr))
       dumpChild(ch, indent + '  ')
-      ch = gui.GetWindow(ch, gui.GetWindowCmd.NEXT)
+      ch = gui.GetWindow(ch, GetWindowCmd.NEXT)
     }
     if (n === 0) console.log(indent + '(no children)')
   }

package/lib/fetch.js

@@ -180,7 +180,7 @@ async function fetchRequest(req) {
         sock.set_on_event(fd, (event) => {
             if (state === ST_DONE)
                 return;
-            if (event.lNetworkEvents & 16 /* sock.FdEvent.FD_CONNECT */) {
+            if (event.lNetworkEvents & 16 /* FdEvent.FD_CONNECT */) {
                 const err = event.iErrorCode[0];
                 if (err !== 0) {
                     doReject(new Error('Connection failed: ' + err));
@@ -194,10 +194,10 @@ async function fetchRequest(req) {
                         return;
                     }
                     if (req.rejectUnauthorized === false) {
-                        wolfssl.wolfSSL_CTX_set_verify(ctx, 0 /* wolfssl.VerifyMode.SSL_VERIFY_NONE */);
+                        wolfssl.wolfSSL_CTX_set_verify(ctx, 0 /* VerifyMode.SSL_VERIFY_NONE */);
                     }
                     else {
-                        wolfssl.wolfSSL_CTX_set_verify(ctx, 1 /* wolfssl.VerifyMode.SSL_VERIFY_PEER */);
+                        wolfssl.wolfSSL_CTX_set_verify(ctx, 1 /* VerifyMode.SSL_VERIFY_PEER */);
                         wolfssl.loadTrustedCerts(ctx);
                     }
                     ssl = wolfssl.wolfSSL_new(ctx);
@@ -207,7 +207,7 @@ async function fetchRequest(req) {
                     }
                     wolfssl.wolfSSL_set_fd(ssl, sock.get_fd(fd));
                     if (parsedUrl.hostname) {
-                        wolfssl.wolfSSL_UseSNI(ssl, 0 /* wolfssl.SniType.WOLFSSL_SNI_HOST_NAME */, parsedUrl.hostname);
+                        wolfssl.wolfSSL_UseSNI(ssl, 0 /* SniType.WOLFSSL_SNI_HOST_NAME */, parsedUrl.hostname);
                         if (req.rejectUnauthorized !== false) {
                             wolfssl.wolfSSL_check_domain_name(ssl, parsedUrl.hostname);
                         }
@@ -219,21 +219,21 @@ async function fetchRequest(req) {
                     state = ST_RECV_HEADERS;
                 }
             }
-            if ((event.lNetworkEvents & 1 /* sock.FdEvent.FD_READ */) || (event.lNetworkEvents & 2 /* sock.FdEvent.FD_WRITE */)) {
+            if ((event.lNetworkEvents & 1 /* FdEvent.FD_READ */) || (event.lNetworkEvents & 2 /* FdEvent.FD_WRITE */)) {
                 if (state === ST_HANDSHAKE) {
                     if (!ssl) {
                         doReject(new Error('TLS not initialized'));
                         return;
                     }
                     const ret = wolfssl.wolfSSL_connect(ssl);
-                    if (ret === 1 /* wolfssl.ReturnCode.SSL_SUCCESS */) {
+                    if (ret === 1 /* ReturnCode.SSL_SUCCESS */) {
                         wolfssl.wolfSSL_write(ssl, httpRequest);
                         state = ST_RECV_HEADERS;
                     }
                     else {
                         const err = wolfssl.wolfSSL_get_error(ssl, ret);
-                        if (err !== 2 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ */ &&
-                            err !== 3 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE */) {
+                        if (err !== 2 /* WolfsslErrorCode.WOLFSSL_ERROR_WANT_READ */ &&
+                            err !== 3 /* WolfsslErrorCode.WOLFSSL_ERROR_WANT_WRITE */) {
                             doReject(new Error('TLS handshake failed: ' + err));
                         }
                     }
@@ -251,10 +251,10 @@ async function fetchRequest(req) {
                             }
                             else {
                                 const err = wolfssl.wolfSSL_get_error(ssl, n);
-                                if (err === 2 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ */ ||
-                                    err === 3 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE */)
+                                if (err === 2 /* WolfsslErrorCode.WOLFSSL_ERROR_WANT_READ */ ||
+                                    err === 3 /* WolfsslErrorCode.WOLFSSL_ERROR_WANT_WRITE */)
                                     break;
-                                if (n === 0 || err === 6 /* wolfssl.ErrorCode.WOLFSSL_ERROR_ZERO_RETURN */)
+                                if (n === 0 || err === 6 /* WolfsslErrorCode.WOLFSSL_ERROR_ZERO_RETURN */)
                                     break;
                                 doReject(new Error('TLS read failed: ' + err));
                                 return;
@@ -338,10 +338,10 @@ async function fetchRequest(req) {
                             }
                             else {
                                 const err = wolfssl.wolfSSL_get_error(ssl, n);
-                                if (err === 2 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ */ ||
-                                    err === 3 /* wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE */)
+                                if (err === 2 /* WolfsslErrorCode.WOLFSSL_ERROR_WANT_READ */ ||
+                                    err === 3 /* WolfsslErrorCode.WOLFSSL_ERROR_WANT_WRITE */)
                                     break;
-                                if (n === 0 || err === 6 /* wolfssl.ErrorCode.WOLFSSL_ERROR_ZERO_RETURN */)
+                                if (n === 0 || err === 6 /* WolfsslErrorCode.WOLFSSL_ERROR_ZERO_RETURN */)
                                     break;
                                 // Fatal TLS error mid-body: the response already
                                 // resolved, so fail the body stream instead of
@@ -390,7 +390,7 @@ async function fetchRequest(req) {
                     }
                 }
             }
-            if (event.lNetworkEvents & 32 /* sock.FdEvent.FD_CLOSE */) {
+            if (event.lNetworkEvents & 32 /* FdEvent.FD_CLOSE */) {
                 if (state === ST_DONE)
                     return;
                 if (state === ST_RECV_HEADERS) {

package/lib/fetch.ts

@@ -12,6 +12,7 @@ import {
     RequestImpl,
     ResponseImpl,
 } from './http-common.js'
+import { FdEvent, ReturnCode, SniType, VerifyMode, WolfsslErrorCode } from '../constants'
 
 // ── HTTP Response Parser ──
 
@@ -178,7 +179,7 @@ async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
         sock.set_on_event(fd, (event: { lNetworkEvents: number; iErrorCode: number[] }) => {
             if (state === ST_DONE) return
 
-            if (event.lNetworkEvents & sock.FdEvent.FD_CONNECT) {
+            if (event.lNetworkEvents & FdEvent.FD_CONNECT) {
                 const err = event.iErrorCode[0]
                 if (err !== 0) { doReject(new Error('Connection failed: ' + err)); return }
 
@@ -187,16 +188,16 @@ async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
                     ctx = wolfssl.wolfSSL_CTX_new(tlsMethod)
                     if (!ctx) { doReject(new Error('SSL_CTX_new failed')); return }
                     if (req.rejectUnauthorized === false) {
-                        wolfssl.wolfSSL_CTX_set_verify(ctx, wolfssl.VerifyMode.SSL_VERIFY_NONE)
+                        wolfssl.wolfSSL_CTX_set_verify(ctx, VerifyMode.SSL_VERIFY_NONE)
                     } else {
-                        wolfssl.wolfSSL_CTX_set_verify(ctx, wolfssl.VerifyMode.SSL_VERIFY_PEER)
+                        wolfssl.wolfSSL_CTX_set_verify(ctx, VerifyMode.SSL_VERIFY_PEER)
                         wolfssl.loadTrustedCerts(ctx)
                     }
                     ssl = wolfssl.wolfSSL_new(ctx)
                     if (!ssl) { doReject(new Error('SSL_new failed')); return }
                     wolfssl.wolfSSL_set_fd(ssl, sock.get_fd(fd))
                     if (parsedUrl.hostname) {
-                        wolfssl.wolfSSL_UseSNI(ssl, wolfssl.SniType.WOLFSSL_SNI_HOST_NAME, parsedUrl.hostname)
+                        wolfssl.wolfSSL_UseSNI(ssl, SniType.WOLFSSL_SNI_HOST_NAME, parsedUrl.hostname)
                         if (req.rejectUnauthorized !== false) {
                             wolfssl.wolfSSL_check_domain_name(ssl, parsedUrl.hostname)
                         }
@@ -208,17 +209,17 @@ async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
                 }
             }
 
-            if ((event.lNetworkEvents & sock.FdEvent.FD_READ) || (event.lNetworkEvents & sock.FdEvent.FD_WRITE)) {
+            if ((event.lNetworkEvents & FdEvent.FD_READ) || (event.lNetworkEvents & FdEvent.FD_WRITE)) {
                 if (state === ST_HANDSHAKE) {
                     if (!ssl) { doReject(new Error('TLS not initialized')); return }
                     const ret = wolfssl.wolfSSL_connect(ssl)
-                    if (ret === wolfssl.ReturnCode.SSL_SUCCESS) {
+                    if (ret === ReturnCode.SSL_SUCCESS) {
                         wolfssl.wolfSSL_write(ssl, httpRequest)
                         state = ST_RECV_HEADERS
                     } else {
                         const err = wolfssl.wolfSSL_get_error(ssl, ret)
-                        if (err !== wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ &&
-                            err !== wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE) {
+                        if (err !== WolfsslErrorCode.WOLFSSL_ERROR_WANT_READ &&
+                            err !== WolfsslErrorCode.WOLFSSL_ERROR_WANT_WRITE) {
                             doReject(new Error('TLS handshake failed: ' + err))
                         }
                     }
@@ -234,9 +235,9 @@ async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
                                 data = buf.slice(0, n)
                             } else {
                                 const err = wolfssl.wolfSSL_get_error(ssl, n)
-                                if (err === wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ ||
-                                    err === wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE) break
-                                if (n === 0 || err === wolfssl.ErrorCode.WOLFSSL_ERROR_ZERO_RETURN) break
+                                if (err === WolfsslErrorCode.WOLFSSL_ERROR_WANT_READ ||
+                                    err === WolfsslErrorCode.WOLFSSL_ERROR_WANT_WRITE) break
+                                if (n === 0 || err === WolfsslErrorCode.WOLFSSL_ERROR_ZERO_RETURN) break
                                 doReject(new Error('TLS read failed: ' + err))
                                 return
                             }
@@ -315,9 +316,9 @@ async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
                                 data = buf.slice(0, n)
                             } else {
                                 const err = wolfssl.wolfSSL_get_error(ssl, n)
-                                if (err === wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_READ ||
-                                    err === wolfssl.ErrorCode.WOLFSSL_ERROR_WANT_WRITE) break
-                                if (n === 0 || err === wolfssl.ErrorCode.WOLFSSL_ERROR_ZERO_RETURN) break
+                                if (err === WolfsslErrorCode.WOLFSSL_ERROR_WANT_READ ||
+                                    err === WolfsslErrorCode.WOLFSSL_ERROR_WANT_WRITE) break
+                                if (n === 0 || err === WolfsslErrorCode.WOLFSSL_ERROR_ZERO_RETURN) break
                                 // Fatal TLS error mid-body: the response already
                                 // resolved, so fail the body stream instead of
                                 // silently waiting for an FD event that never comes.
@@ -355,7 +356,7 @@ async function fetchRequest(req: RequestImpl): Promise<ResponseImpl> {
                 }
             }
 
-            if (event.lNetworkEvents & sock.FdEvent.FD_CLOSE) {
+            if (event.lNetworkEvents & FdEvent.FD_CLOSE) {
                 if (state === ST_DONE) return
                 if (state === ST_RECV_HEADERS) {
                     doReject(new Error('Connection closed before response'))

package/lib/ffi/bind.js

@@ -73,7 +73,7 @@ function makeFn(proc, sig, encoders, decoders) {
     }
     return (...a) => callPacked(proc, ps, a, encoders, decoders);
 }
-// 每个参数在 argFrame 里占的字节数。与 quickjs-ffi-type.h 的 qwin_ffi_arg_size[]
+// 每个参数在 argFrame 里占的字节数。与 src/quickjs-ffi-type.h 的 qwin_ffi_arg_size[]
 // 保持一致（ia32：≤4B 类型进 4 字节、更大的进 8 字节；x64：恒 8 字节槽）。
 // 注意这是「槽宽」，不是类型的 sizeof——同一定义也用于返回槽。指针布局恒指针宽。
 const IA32_ARG_SIZE = {
@@ -334,7 +334,7 @@ const leakRegistry = new FinalizationRegistry((held) => {
 // args/ret 为「底档 + '!' 绑定」的记录（与 ParsedSig 同形态——修饰随 token 走，
 // 消费者要么整体拿到、要么整体拿不到）。'!' 违约（C 传入 0 / fn 返回 0）打印诊断并
 // 中止本次分发（fn 不被调用 / 结果槽保持 0），与 fn-throw 同风格：此处不 throw，
-// 异常通道只留给用户回调（C 桩捕获 wrapper 异常并清零，quickjs-ffi-closure.c）。
+// 异常通道只留给用户回调（C 桩捕获 wrapper 异常并清零，src/quickjs-ffi-closure.c）。
 function dispatchClosure(args, ret, fn, frameBuf, retBuf, sig) {
     const dv = new DataView(retBuf);
     const is64 = os.arch === 'x64';
@@ -409,7 +409,7 @@ export function closure(sig, fn, opts) {
     const retSpec = { tok: cTokenToType(retToken), nonnull: retToken.endsWith('!') };
     const is64 = os.arch === 'x64';
     const stackCapture = argSpecs.reduce((s, x) => s + IA32_ARG_SIZE[x.tok], 0);
-    // C 桩捕获窗定长（quickjs-ffi-closure.c：x64 栈区 96B=12 槽，第 5 参起在栈上，
+    // C 桩捕获窗定长（src/quickjs-ffi-closure.c：x64 栈区 96B=12 槽，第 5 参起在栈上，
     // 即至多 16 参；ia32 16×4B）——超限 dispatch 会读到捕获缓冲之外的垃圾，或
     // RangeError 被吞成返回 0，故创建期 fail-fast。扩容改 C 侧 buf 尺寸并同步放宽。
     if (is64 ? argSpecs.length > 16 : stackCapture > 64) {

package/lib/ffi/bind.ts

@@ -123,7 +123,7 @@ function makeFn(proc: number, sig: string, encoders: CodecMap, decoders: CodecMa
     return (...a: unknown[]) => callPacked(proc, ps, a, encoders, decoders)
 }
 
-// 每个参数在 argFrame 里占的字节数。与 quickjs-ffi-type.h 的 qwin_ffi_arg_size[]
+// 每个参数在 argFrame 里占的字节数。与 src/quickjs-ffi-type.h 的 qwin_ffi_arg_size[]
 // 保持一致（ia32：≤4B 类型进 4 字节、更大的进 8 字节；x64：恒 8 字节槽）。
 // 注意这是「槽宽」，不是类型的 sizeof——同一定义也用于返回槽。指针布局恒指针宽。
 const IA32_ARG_SIZE: Record<C_BasicType_No_Void, number> = {
@@ -429,7 +429,7 @@ const leakRegistry: FinalizationRegistry<{ sig: string, ptr: number }> =
 // args/ret 为「底档 + '!' 绑定」的记录（与 ParsedSig 同形态——修饰随 token 走，
 // 消费者要么整体拿到、要么整体拿不到）。'!' 违约（C 传入 0 / fn 返回 0）打印诊断并
 // 中止本次分发（fn 不被调用 / 结果槽保持 0），与 fn-throw 同风格：此处不 throw，
-// 异常通道只留给用户回调（C 桩捕获 wrapper 异常并清零，quickjs-ffi-closure.c）。
+// 异常通道只留给用户回调（C 桩捕获 wrapper 异常并清零，src/quickjs-ffi-closure.c）。
 function dispatchClosure(
     args: { tok: C_BasicType_No_Void, nonnull: boolean }[],
     ret: { tok: C_BasicType, nonnull: boolean },
@@ -508,7 +508,7 @@ export function closure<S extends string>(sig: S, fn: BindFn<S, {}, {}>,
     const retSpec = { tok: cTokenToType(retToken), nonnull: retToken.endsWith('!') }
     const is64 = os.arch === 'x64'
     const stackCapture = argSpecs.reduce((s, x) => s + IA32_ARG_SIZE[x.tok], 0)
-    // C 桩捕获窗定长（quickjs-ffi-closure.c：x64 栈区 96B=12 槽，第 5 参起在栈上，
+    // C 桩捕获窗定长（src/quickjs-ffi-closure.c：x64 栈区 96B=12 槽，第 5 参起在栈上，
     // 即至多 16 参；ia32 16×4B）——超限 dispatch 会读到捕获缓冲之外的垃圾，或
     // RangeError 被吞成返回 0，故创建期 fail-fast。扩容改 C 侧 buf 尺寸并同步放宽。
     if (is64 ? argSpecs.length > 16 : stackCapture > 64) {

package/lib/ffi/ctype.ts

@@ -106,7 +106,9 @@ type First =
 //                对象值的唯一判别键是 '#'（多字段/聚合元素无法用糖表达，故保留）
 // '#' 必填（无「裸嵌套 map 默认 struct」）：漏写 '#' 时 union 不会静默翻转成 struct，
 // 类型层直接报错、运行时 throw。顶层 struct()/union() 例外 —— kind 由函数名表明，
-// 参数是平铺字段表（不含 '#'），'#'/`#pack` 由构造器写入 __struct。
+// 参数是平铺字段表（本身不含 '#'；DECL 常量直传时 '#' 须与函数名 kind 一致 —— 参数
+// 类型交叉 `{ '#'?: 'struct' }` / `{ '#'?: 'union' }` 编译期锁），'#'/`#pack` 由构造器
+// 写入声明（buildDecl）。
 // ============================================================
 
 // token 值面：规范 token（C_Number 档）∪ 指针形（含 '!' 非空尾缀）∪ '@枚举标注形'

package/lib/ffi/struct.js

@@ -350,7 +350,7 @@ function doEncode(dv, base, fields, v) {
 function createStruct(t) {
     const { fields, size, maxEffectiveAlign } = computeStructLayout(t);
     return {
-        __struct: t,
+        fields,
         size,
         structAlign: maxEffectiveAlign,
         decode: (p) => {
@@ -389,10 +389,26 @@ function createStruct(t) {
         },
     };
 }
-/** 平铺字段表 → '#' 声明：'#'/`#pack` 由构造器写入（顶层 kind 由函数名表明，字段表本身
- *  不收指令键）。member 里混进的 '#' 前缀键在此剔除 —— 类型层已禁（fresh literal excess
- *  check），这里运行时兜底，避免用户键覆盖构造器写入的 '#'/`#pack`。 */
+/** 平铺字段表 → '#' 声明：'#'/`#pack` 由构造器写入（顶层 kind 由函数名表明）。
+ *  member 里混进的其他 '#' 前缀键在此剔除 —— fresh literal 由 excess check 拒，这里
+ *  运行时兜底，避免用户键覆盖构造器写入的 '#'/`#pack`。
+ *  两处守卫（DECL 常量直传形态，`struct('X', X_DECL)`）：
+ *  - member 自带 '#' 时须与函数名 kind 一致，否则 throw。TS 侧 overload 参数收
+ *    `M & { '#'?: 'struct' }`（union 镜像），'#' 与函数名 kind 不符在编译期就交叉成
+ *    never 报错；此 throw 是 JS / `as any` / 动态构造 DECL 调用方的运行时兜底 ——
+ *    union DECL 误传 struct() 会静默翻转成 struct 布局，是最难查的一类错；
+ *  - '#pack' 透传（剥键即丢，pack 布局静默变自然对齐）：opts.pack 未给时取 member 的，
+ *    两者都给且不等则 throw —— 跨参数的相等约束类型层表达不了，只能运行时校。 */
 function buildDecl(kind, member, pack) {
+    const declKind = member['#'];
+    if (declKind !== undefined && declKind !== kind)
+        throw new Error(`ffi-struct: ${kind}() received a '${String(declKind)}' declaration ` +
+            `(kind mismatch — use ${declKind}() for it)`);
+    const declPack = member['#pack'];
+    if (pack === undefined && declPack !== undefined)
+        pack = declPack;
+    else if (pack !== undefined && declPack !== undefined && pack !== declPack)
+        throw new Error(`ffi-struct: #pack conflict: opts.pack=${pack} vs declaration ${String(declPack)}`);
     const decl = { '#': kind };
     if (pack !== undefined)
         decl['#pack'] = pack;
@@ -418,10 +434,10 @@ function buildDecl(kind, member, pack) {
  *  - 裸地址形：count 必填（地址无长度信息），逐字节拷读（def.decode 的 number 形
  *    同机制）；长度不可校 → 信任 C 的 count。
  *  - count = 0 → []（读 0 个真空安全，与 encode 禁空的 PAB(0) 理由刻意不对称）。
- *  实现：encode 走纯公开 API（alloc + encode offset 循环）；decode 在本文件内复用
- *  computeStructLayout/doDecode。 */
+ *  实现：encode 走纯公开 API（alloc + encode offset 循环）；decode 直接读 def.fields
+ *  （createStruct 暴露的布局 IR，与 def.decode 同一份，无需重算）。 */
 export function structArray(def) {
-    const { fields, size } = computeStructLayout(def.__struct);
+    const { fields, size } = def;
     const readN = (dv, n) => {
         const out = [];
         for (let i = 0; i < n; i++)

package/lib/ffi/struct.ts

@@ -204,7 +204,10 @@ export type Fields = Field[]
 // N = 布局品牌（struct(name, …) 传入）：decode 入参与 alloc().ptr 同品牌。默认 '' ——
 // `Ptr<''>` 归一裸 number（与旧 never 守卫结果相同），品牌化 def 未来收窄时签名不用再动。
 export type StructDef<T extends { '#': 'struct' | 'union' }, N extends string = ''> = {
-    readonly __struct: T
+    // 布局 IR 直接暴露（原 __struct 成员读已删：成员读是可观察副作用，esbuild 无法把
+    // 「PURE 调用 + X.__struct 实参」与 X 的定义一起摇掉 —— DECL 常量（对象字面量）走
+    // 标识符引用则整链可摇。T 只活在 decode/encode 的类型签名里，运行时不挂成员）。
+    readonly fields: Fields
     readonly size: number
     readonly structAlign: number
     decode(buf: ArrayBuffer | Ptr<N>): ShapeOfC<T>
@@ -593,7 +596,7 @@ function doEncode(dv: DataView, base: number, fields: Fields, v: Record<string,
 function createStruct(t: C_Struct | C_Union): any {
     const { fields, size, maxEffectiveAlign } = computeStructLayout(t)
     return {
-        __struct: t,
+        fields,
         size,
         structAlign: maxEffectiveAlign,
         decode: (p: ArrayBuffer | number) => {
@@ -638,10 +641,25 @@ function createStruct(t: C_Struct | C_Union): any {
 /** 聚合对齐上限（pack 压 maxAlign，语义同 MSVC #pragma pack）。 */
 export type AggOpts = { pack?: number }
 
-/** 平铺字段表 → '#' 声明：'#'/`#pack` 由构造器写入（顶层 kind 由函数名表明，字段表本身
- *  不收指令键）。member 里混进的 '#' 前缀键在此剔除 —— 类型层已禁（fresh literal excess
- *  check），这里运行时兜底，避免用户键覆盖构造器写入的 '#'/`#pack`。 */
+/** 平铺字段表 → '#' 声明：'#'/`#pack` 由构造器写入（顶层 kind 由函数名表明）。
+ *  member 里混进的其他 '#' 前缀键在此剔除 —— fresh literal 由 excess check 拒，这里
+ *  运行时兜底，避免用户键覆盖构造器写入的 '#'/`#pack`。
+ *  两处守卫（DECL 常量直传形态，`struct('X', X_DECL)`）：
+ *  - member 自带 '#' 时须与函数名 kind 一致，否则 throw。TS 侧 overload 参数收
+ *    `M & { '#'?: 'struct' }`（union 镜像），'#' 与函数名 kind 不符在编译期就交叉成
+ *    never 报错；此 throw 是 JS / `as any` / 动态构造 DECL 调用方的运行时兜底 ——
+ *    union DECL 误传 struct() 会静默翻转成 struct 布局，是最难查的一类错；
+ *  - '#pack' 透传（剥键即丢，pack 布局静默变自然对齐）：opts.pack 未给时取 member 的，
+ *    两者都给且不等则 throw —— 跨参数的相等约束类型层表达不了，只能运行时校。 */
 function buildDecl(kind: 'struct' | 'union', member: Record<string, unknown>, pack?: number): C_Struct | C_Union {
+    const declKind = member['#']
+    if (declKind !== undefined && declKind !== kind)
+        throw new Error(`ffi-struct: ${kind}() received a '${String(declKind)}' declaration ` +
+            `(kind mismatch — use ${declKind}() for it)`)
+    const declPack = member['#pack']
+    if (pack === undefined && declPack !== undefined) pack = declPack as number
+    else if (pack !== undefined && declPack !== undefined && pack !== declPack)
+        throw new Error(`ffi-struct: #pack conflict: opts.pack=${pack} vs declaration ${String(declPack)}`)
     const decl: Record<string, unknown> = { '#': kind }
     if (pack !== undefined) decl['#pack'] = pack
     for (const [k, v] of Object.entries(member))
@@ -649,11 +667,19 @@ function buildDecl(kind: 'struct' | 'union', member: Record<string, unknown>, pa
     return decl as unknown as C_Struct | C_Union
 }
 
+/** def 的类型经方法签名索引提取（StructDef 不再挂 __struct 成员 —— T 只活在签名里）：
+ *  encode 重载末条首参 = EncodeIn<T>、decode 返回 = ShapeOfC<T>、alloc 返回 = PAB<N>、
+ *  decode 首参剥 ArrayBuffer = Ptr<N>（裸地址形）。 */
+type EncInOf<D extends StructDef<any, any>> = Parameters<D['encode']>[0]
+type DecOf<D extends StructDef<any, any>> = ReturnType<D['decode']>
+type PABOf<D extends StructDef<any, any>> = ReturnType<D['alloc']>
+type AddrOf<D extends StructDef<any, any>> = Exclude<Parameters<D['decode']>[0], ArrayBuffer>
+
 /** decode 双态重载：有 byteLength 的 buffer 形 count 可缺省（自算）；裸地址无长度
  *  信息，count 必填（类型层拦，缺省调用编译红）。 */
-type StructArrayDecode<T extends { '#': 'struct' | 'union' }, N extends string> = {
-    (p: ArrayBuffer, count?: number): ShapeOfC<T>[]
-    (p: Ptr<N>, count: number): ShapeOfC<T>[]
+type StructArrayDecode<D extends StructDef<any, any>> = {
+    (p: ArrayBuffer, count?: number): DecOf<D>[]
+    (p: AddrOf<D>, count: number): DecOf<D>[]
 }
 
 /** 结构/联合体的数组编解码对工厂：返回 `{ encode, decode }`。
@@ -673,25 +699,23 @@ type StructArrayDecode<T extends { '#': 'struct' | 'union' }, N extends string>
  *  - 裸地址形：count 必填（地址无长度信息），逐字节拷读（def.decode 的 number 形
  *    同机制）；长度不可校 → 信任 C 的 count。
  *  - count = 0 → []（读 0 个真空安全，与 encode 禁空的 PAB(0) 理由刻意不对称）。
- *  实现：encode 走纯公开 API（alloc + encode offset 循环）；decode 在本文件内复用
- *  computeStructLayout/doDecode。 */
-export function structArray<T extends { '#': 'struct' | 'union' }, N extends string = ''>(
-    def: StructDef<T, N>,
-) {
-    const { fields, size } = computeStructLayout(def.__struct)
+ *  实现：encode 走纯公开 API（alloc + encode offset 循环）；decode 直接读 def.fields
+ *  （createStruct 暴露的布局 IR，与 def.decode 同一份，无需重算）。 */
+export function structArray<D extends StructDef<any, any>>(def: D) {
+    const { fields, size } = def
     const readN = (dv: DataView, n: number): unknown[] => {
         const out: unknown[] = []
         for (let i = 0; i < n; i++) out.push(doDecode(dv, i * size, fields))
         return out
     }
     return {
-        encode: (els: readonly EncodeIn<T>[]): PtrArrayBuffer<N> => {
+        encode: (els: readonly EncInOf<D>[]): PABOf<D> => {
             if (!Array.isArray(els) || els.length === 0)
                 throw new Error(`ffi-struct: structArray(def).encode(els) requires a ` +
                     `non-empty element array (pass NULL for an empty pointer position)`)
             const out = def.alloc(els.length)
             for (let i = 0; i < els.length; i++) def.encode(els[i], out, i * def.size)
-            return out
+            return out as PABOf<D>
         },
         decode: ((p: ArrayBuffer | number, count?: number): unknown[] => {
             // fail-loud 校验矩阵（见 JSDoc）：显式 count 信调用方但拦越界；缺省只对
@@ -725,16 +749,18 @@ export function structArray<T extends { '#': 'struct' | 'union' }, N extends str
             }
             if (n === 0) return []
             return readN(new DataView(p), n)
-        }) as StructArrayDecode<T, N>,
+        }) as StructArrayDecode<D>,
     }
 }
 
 /** 平铺字段表定义结构体（token/`X[n]`/`unit:width`/`'#'` 声明均可，见 ctype.ts §4）。
- *  给 name 则 alloc().ptr 与 decode 入参带 Ptr<name> 品牌。 */
+ *  给 name 则 alloc().ptr 与 decode 入参带 Ptr<name> 品牌。DECL 常量可直传（
+ *  `struct('X', X_DECL)`）—— 参数交叉 `{ '#'?: 'struct' }` 锁 kind：传 union/array
+ *  DECL 时 '#' 字面类型交叉成 never，编译期即报错。 */
 type StructOf<M, N extends string = ''> = StructDef<{ '#': 'struct', '#pack'?: number } & M, N>
 type UnionOf<M, N extends string = ''> = StructDef<{ '#': 'union', '#pack'?: number } & M, N>
-export function struct<const M extends SimpleMember>(member: M, opts?: AggOpts): StructOf<M>
-export function struct<const N extends string, const M extends SimpleMember>(name: N, member: M, opts?: AggOpts): StructOf<M, N>
+export function struct<const M extends SimpleMember>(member: M & { '#'?: 'struct' }, opts?: AggOpts): StructOf<M>
+export function struct<const N extends string, const M extends SimpleMember>(name: N, member: M & { '#'?: 'struct' }, opts?: AggOpts): StructOf<M, N>
 export function struct(a: string | SimpleMember, b?: SimpleMember | AggOpts, c?: AggOpts): any {
     const isNamed = typeof a === 'string'
     const raw = (isNamed ? b : a) as Record<string, unknown>
@@ -742,9 +768,10 @@ export function struct(a: string | SimpleMember, b?: SimpleMember | AggOpts, c?:
     return createStruct(buildDecl('struct', raw, opts?.pack))
 }
 
-/** 平铺字段表定义联合体；布局/读写与 struct 相同，仅成员偏移重叠。 */
-export function union<const M extends SimpleMember>(member: M, opts?: AggOpts): UnionOf<M>
-export function union<const N extends string, const M extends SimpleMember>(name: N, member: M, opts?: AggOpts): UnionOf<M, N>
+/** 平铺字段表定义联合体；布局/读写与 struct 相同，仅成员偏移重叠。DECL 常量可直传，
+ *  参数交叉 `{ '#'?: 'union' }` 锁 kind（struct 侧镜像，理由见上）。 */
+export function union<const M extends SimpleMember>(member: M & { '#'?: 'union' }, opts?: AggOpts): UnionOf<M>
+export function union<const N extends string, const M extends SimpleMember>(name: N, member: M & { '#'?: 'union' }, opts?: AggOpts): UnionOf<M, N>
 export function union(a: string | SimpleMember, b?: SimpleMember | AggOpts, c?: AggOpts): any {
     const isNamed = typeof a === 'string'
     const raw = (isNamed ? b : a) as Record<string, unknown>

package/lib/http-server.js

@@ -163,7 +163,7 @@ export class HttpServer {
         }
         this.serverSock = s;
         sock.set_on_event(s, (event) => {
-            if (event.lNetworkEvents & 8 /* sock.FdEvent.FD_ACCEPT */)
+            if (event.lNetworkEvents & 8 /* FdEvent.FD_ACCEPT */)
                 this.acceptLoop();
         });
         return 0;
@@ -207,11 +207,11 @@ export class HttpServer {
     onConnEvent(c, event) {
         if (c.closed)
             return;
-        if (event.lNetworkEvents & 1 /* sock.FdEvent.FD_READ */)
+        if (event.lNetworkEvents & 1 /* FdEvent.FD_READ */)
             onRead(c);
-        if (event.lNetworkEvents & 2 /* sock.FdEvent.FD_WRITE */)
+        if (event.lNetworkEvents & 2 /* FdEvent.FD_WRITE */)
             flushQueue(c);
-        if (event.lNetworkEvents & 32 /* sock.FdEvent.FD_CLOSE */) {
+        if (event.lNetworkEvents & 32 /* FdEvent.FD_CLOSE */) {
             onRead(c);
             abortConn(c);
             closeConn(c);
@@ -342,7 +342,7 @@ async function writeStreamingBody(c, body, chunked, trailer) {
         }
         if (c.closed) {
             // 客户端断开（FD_CLOSE / send 失败）：取消响应体，让 producer 感知
-            //（exec_server 借此 kill 子进程），而不是干等它自然结束。
+            //（execd 借此 kill 子进程），而不是干等它自然结束。
             try {
                 await reader.cancel();
             }

package/lib/http-server.ts

@@ -2,6 +2,7 @@ import './polyfill.js'
 import * as sock from 'sock'
 import { HeadersImpl, RequestImpl, ResponseImpl, _readStream } from './http-common.js'
 import { AbortController } from './abort.js'
+import { FdEvent } from '../constants'
 
 type SockHandle = import('sock').SockHandle
 
@@ -191,7 +192,7 @@ export class HttpServer {
         if (sock.listen(s, backlog ?? 64) !== 0) { sock.closesocket(s); return -1 }
         this.serverSock = s
         sock.set_on_event(s, (event: NetEvent) => {
-            if (event.lNetworkEvents & sock.FdEvent.FD_ACCEPT) this.acceptLoop()
+            if (event.lNetworkEvents & FdEvent.FD_ACCEPT) this.acceptLoop()
         })
         return 0
     }
@@ -229,9 +230,9 @@ export class HttpServer {
 
     private onConnEvent(c: Conn, event: NetEvent): void {
         if (c.closed) return
-        if (event.lNetworkEvents & sock.FdEvent.FD_READ) onRead(c)
-        if (event.lNetworkEvents & sock.FdEvent.FD_WRITE) flushQueue(c)
-        if (event.lNetworkEvents & sock.FdEvent.FD_CLOSE) {
+        if (event.lNetworkEvents & FdEvent.FD_READ) onRead(c)
+        if (event.lNetworkEvents & FdEvent.FD_WRITE) flushQueue(c)
+        if (event.lNetworkEvents & FdEvent.FD_CLOSE) {
             onRead(c)
             abortConn(c)
             closeConn(c)
@@ -357,7 +358,7 @@ async function writeStreamingBody(c: Conn, body: ReadableStream<Uint8Array> | nu
         }
         if (c.closed) {
             // 客户端断开（FD_CLOSE / send 失败）：取消响应体，让 producer 感知
-            //（exec_server 借此 kill 子进程），而不是干等它自然结束。
+            //（execd 借此 kill 子进程），而不是干等它自然结束。
             try { await reader.cancel() } catch (e) {
                 console.error('[http-server] body cancel error:', e)
             }