quickwin 3.0.0 → 3.0.2

package/README.en.md

@@ -157,6 +157,9 @@ Both sides must set `onmessage = null` when communication is complete. This rele
 
 ## Examples
 
+The example scripts live in the repository (**not shipped in the npm package**,
+which only carries the exes, main.js, lib and the type declarations):
+
 ```bash
 .\qwin.exe examples/tray_demo.js     # system tray app
 .\qwin.exe examples/pdf_preview2.js  # PDF reader with mupdf

package/README.md

@@ -155,6 +155,8 @@ parent.onmessage = (e) => {
 
 ## 示例
 
+示例脚本在仓库里（**不随 npm 包发布**，包内只有 exe、main.js、lib 与类型声明）：
+
 ```bash
 .\qwin.exe examples/tray_demo.js     # 系统托盘应用
 .\qwin.exe examples/pdf_preview2.js  # 基于 mupdf 的 PDF 阅读器

package/lib/abort.d.ts

@@ -0,0 +1,21 @@
+export interface AbortEvent {
+    readonly type: 'abort';
+    readonly target: unknown;
+}
+export declare class AbortSignal {
+    private _aborted;
+    private _reason;
+    private _listeners;
+    onabort: ((e: AbortEvent) => void) | null;
+    get aborted(): boolean;
+    get reason(): unknown;
+    addEventListener(type: string, listener: (e: AbortEvent) => void): void;
+    removeEventListener(type: string, listener: (e: AbortEvent) => void): void;
+    /** @internal fired by AbortController.abort() */
+    _fire(reason: unknown): void;
+    throwIfAborted(): void;
+}
+export declare class AbortController {
+    readonly signal: AbortSignal;
+    abort(reason?: unknown): void;
+}

package/lib/assert.d.ts

@@ -0,0 +1,2 @@
+export declare function assertNonNullable<T>(v: T, msg?: string): asserts v is NonNullable<T>;
+export declare function assertArrayBuffer(v: ArrayBufferLike): asserts v is ArrayBuffer;

package/lib/bitmap.d.ts

@@ -0,0 +1,7 @@
+import { type MaybePtr } from './ffi/ctype.js';
+/** 建 32bpp 自顶向下 DIB 段位图（像素为 BGRA，[B,G,R,A] 字节序，alpha 保留 —— 可喂
+ *  ImageListAdd(ILC_COLOR32) 等）。width/height ≤ 0 或像素缓冲不足 width*height*4 →
+ *  NULL（同旧 gui.CreateBitmapFromPixels 语义：非法入参静默返空，由调用方按「无图」处理）；
+ *  GDI 失败同样返 NULL（已建的位图当场回收）。
+ *  位图归调用方所有：用完 DeleteObject。 */
+export declare function createBitmapFromPixels(width: number, height: number, pixels: ArrayBuffer): MaybePtr<'HGDIOBJ'>;

package/lib/cache-utils.d.ts

@@ -0,0 +1,6 @@
+export interface IniCache {
+    headers: Record<string, string>;
+    meta: Record<string, string>;
+}
+export declare function parseIni(text: string): IniCache;
+export declare function toIni(headers: Record<string, string>, meta: Record<string, string>): string;

package/lib/certs.d.ts

@@ -0,0 +1 @@
+export declare const TRUSTED_CA_COUNT = 8;

package/lib/dpi.d.ts

@@ -0,0 +1,9 @@
+import { NULL, type Ptr } from './ffi/ctype.js';
+/** 屏幕缩放系数（96 DPI = 1）：GetDC(NULL) → GetDeviceCaps(LOGPIXELSX) → ReleaseDC 成对释放 */
+export declare function getScaleFactor(): number;
+/** 系统消息字体（CreateFontIndirectW(NONCLIENTMETRICS.lfMessageFont)）——界面控件的默认字体；
+ *  出参位不注册 encoder：encode({cbSize}) 建缓冲带初值 → 传 .ptr → decode 读回。
+ *  cbSize/uiParam 必须与系统认知的结构尺寸一致：Vista+ 为 504（含尾部 iPaddedBorderWidth）、
+ *  XP/2003 为 500 —— 先按 504 试，失败退回 500（lfMessageFont 落在前 500 字节内，尾部留 0）；
+ *  两次都失败 → NULL，调用方按「无字体」处理（控件回落系统默认字体）。 */
+export declare function createSystemDpiFont(): Ptr<'HGDIOBJ'> | NULL;

package/lib/dumpRects.d.ts

@@ -0,0 +1,2 @@
+import * as gui from 'gui';
+export declare function startDumpRects(rootHwnd: gui.HWND, intervalMs?: number): void;

package/lib/exec-log.d.ts

@@ -0,0 +1,23 @@
+export interface LogEntry {
+    /** epoch 秒 */
+    ts: number;
+    /** 展示用命令/请求描述 */
+    cmd: string;
+    /** HTTP 状态码（401/404/500/504 等）；异常终止用 -1 */
+    status: number;
+    /** X-Exit-Code（子进程退出码）；无则 null */
+    exit: number | null;
+    /** 耗时 ms */
+    durMs: number;
+    /** 附加说明（如超时/拒绝原因） */
+    note?: string;
+}
+/** 请求日志：固定容量环形缓冲，GUI ListBox 每行一条。 */
+export declare class RequestLog {
+    private readonly cap;
+    private buf;
+    constructor(cap?: number);
+    get size(): number;
+    push(e: LogEntry): void;
+    list(): LogEntry[];
+}

package/lib/fetch.d.ts

@@ -0,0 +1,4 @@
+declare global {
+    var fetch: (url: string | Request, init?: RequestInit) => Promise<Response>;
+}
+export {};

package/lib/ffi/bind.d.ts

@@ -0,0 +1,70 @@
+import '../text-codec.js';
+import { ArgJsTypeOfToken, RetJsTypeOfToken, type Ptr, PtrArrayBuffer } from './ctype.js';
+type Codec<N extends string = string, V = unknown, T = unknown> = {
+    encode?(v: V, buf?: PtrArrayBuffer<any>): PtrArrayBuffer<any>;
+    decode?(p: Ptr<N> | ArrayBuffer): V;
+    alloc?(a: T): PtrArrayBuffer<N>;
+};
+export type CodecMap = Record<string, {
+    encode?(v: any, buf?: PtrArrayBuffer<any>): PtrArrayBuffer<any>;
+    decode?(p: any): any;
+    alloc?(a: any): PtrArrayBuffer<any>;
+}>;
+type ParseArgStr<S extends string, L, Acc extends unknown[] = []> = S extends `${infer F} ${infer R}` ? ParseArgStr<R, L, [...Acc, ArgJsTypeOfToken<F, L>]> : S extends '' ? Acc : [...Acc, ArgJsTypeOfToken<S, L>];
+type EncodeValue<T> = 'encode' extends keyof T ? (T extends {
+    encode?: (v: infer V, ...r: any[]) => ArrayBuffer;
+} ? V : never) : never;
+type DecodeValue<T> = 'decode' extends keyof T ? (T extends {
+    decode?: (p: any, ...r: any[]) => infer V;
+} ? V : never) : never;
+type BindEncoders<M> = {
+    [K in keyof M]: EncodeValue<M[K]>;
+} & {
+    WCHAR: string;
+    BYTE: PtrArrayBuffer<any>;
+};
+type BindDecoders<M> = {
+    [K in keyof M]: DecodeValue<M[K]>;
+} & {
+    WCHAR: string;
+};
+type BindFn<S extends string, E, D> = S extends `${infer ArgStr} -> ${infer RetStr}` ? ((...args: ParseArgStr<ArgStr, E>) => RetJsTypeOfToken<RetStr, D>) : never;
+/** 内建 UTF-16 编解码：encode 入参序列化（UTF-16LE + NUL）；decode 双态单参——
+ *  品牌指针逐字节读到 NUL（野指针无终止 4MiB 上限 fail-fast）、ArrayBuffer 直读到
+ *  NUL 或末尾（out 参数未写 NUL 时按读满处理）；alloc 预分配返回带 .ptr 的
+ *  PtrArrayBuffer（a = 字符数，缺省 256）。类型取必需形态——
+ *  内建三件齐备，调用无需空断言。刻意 Pick 而非 Required<Codec>：只声明消费的
+ *  三件（encode/decode/alloc），新增可选能力位不被拉成必填。 */
+export declare const WCHAR: Required<Pick<Codec<'WCHAR', string, number>, 'encode' | 'decode' | 'alloc'>>;
+/** 内建字节缓冲：encode identity 直通（收 PtrArrayBuffer、原地存活，native 写回同一
+ *  buffer）；alloc 预分配返回带 .ptr 的 PtrArrayBuffer（a = 字节数）。无 decode——
+ *  地址不携带长度（无终止符），读回直接在 buffer 上 DataView / TypedArray 取。 */
+export declare const BYTE: Required<Pick<Codec<'BYTE', PtrArrayBuffer<any>, number>, 'encode' | 'alloc'>>;
+/** 绑定单个函数。encoders/decoders 是两张可选布局表（结构上是 Codec）：
+ *  encoders 喂入参位（encode 值域 → 形参类型），decoders 喂返回位（decode 值域
+ *  → 返回 V | null，替代 Ptr | null）。decoders 缺省时回退到 encoders——双向 codec
+ *  只需传一次（与运行时 `decoders ?? encoders` 同构：都只在实参缺省时生效，
+ *  显式传空对象不 fallback）。内建 WCHAR/BYTE 无条件参与两张表。 */
+export declare function bind<const S extends string, const LE extends CodecMap = {}, const LD extends CodecMap = LE>(dll: string, name: string, sig: S, encoders?: LE, decoders?: LD): BindFn<S, BindEncoders<LE>, BindDecoders<LD>>;
+/** 批量绑定（map = 函数名 → 签名串）。encoders/decoders 语义同 bind()。 */
+export declare function bindLib<const M extends Record<string, string>, const LE extends CodecMap = {}, const LD extends CodecMap = LE>(dll: string, map: M, encoders?: LE, decoders?: LD): { [K in keyof M]: BindFn<M[K], BindEncoders<LE>, BindDecoders<LD>>; };
+/** 把 JS 函数变成可传给 Win32 API 的函数指针（同步同线程回调）。
+ *  sig 为回调签名：实参只许 BasicKind（ptr 槽 0 保真读回 NULL | Ptr），
+ *  返回只许 void|u8..u64|i8..i64|f32|f64|ptr（u64/i64 走 EDX:EAX，x64 走 RAX）。
+ *  '!' 标记位运行时校验（与 bind 调用位同语义，见 dispatchClosure）：参数位 C 传入 0
+ *  → 打印诊断并跳过回调；返回位 fn 返回 0 → 保持结果槽 0。
+ *  opts.stdcall 仅 ia32 有效（默认 true，Win32 回调标准 CALLBACK）；msvcrt 等
+ *  cdecl 库回调传 { stdcall: false }。x64 恒由调用方清栈，无需指定。
+ *  参数上限：x64 至多 16 个、ia32 栈区至多 64 字节（C 桩定长捕获窗），超限抛错。
+ *  返回 { ptr, dispose }：ptr 即函数指针（传给 API 的 ptr 参数）；dispose 注销
+ *  并释放回调函数，幂等；闭包期间回调被强引用，不会被 GC 回收。
+ *  注意：dispose 后 ptr 不得再被任何 native 方引用。
+ *  从未 dispose 就丢弃通道（整个返回对象或解构出来的 dispose 均算）
+ *  → 打印泄漏警告（只警告、不自动释放，见 leakRegistry）。 */
+export declare function closure<S extends string>(sig: S, fn: BindFn<S, {}, {}>, opts?: {
+    stdcall?: boolean;
+}): {
+    ptr: number;
+    dispose(): void;
+};
+export {};

package/lib/ffi/ctype.d.ts

@@ -0,0 +1,117 @@
+declare const C_BASIC_TYPE: readonly ['void', 'u8', 'i8', 'u16', 'i16', 'u32', 'i32', 'u64', 'i64', 'f32', 'f64', 'ptr'];
+export type C_BasicType = (typeof C_BASIC_TYPE)[number];
+export type C_BasicType_No_Void = Exclude<C_BasicType, 'void'>;
+export type C_BasicType_Token = Exclude<C_BasicType, 'ptr'> | `<${string}>ptr` | `<${string}>ptr!` | `<${string}>`;
+export type C_BasicType_Token_No_Void = Exclude<C_BasicType_Token, 'void'>;
+export declare function isCPtrToken(t: string): t is `<${string}>ptr` | `${string}ptr!` | `${string}ptr@${string}`;
+export declare function isCValToken(t: string): t is `<${string}>`;
+export declare function valName<const N extends string>(t: `<${N}>`): N;
+export declare function ptrName<const N extends string>(t: `<${N}>ptr` | `<${N}>ptr!`): N;
+/**
+ * @description `<${string}>ptr` / `<${string}>ptr!` -> 'ptr'。按值形 `<${string}>` 无
+ * 标量槽等价物 —— 运行时 throw（返回位由 parseSig 拒、closure 入参位由 closure() 拒，
+ * 正常路径不可达），返回类型同时 Exclude 掉按值形：消费方（readRet / dispatchClosure
+ * 的 IA32_ARG_SIZE 索引）拿不到会误导编译期的标量误判。
+ */
+export declare const cTokenToType: <const T extends string>(t: T) => Exclude<T, `<${string}>ptr` | `<${string}>ptr!` | `<${string}>`> | 'ptr';
+export type C_Number = Exclude<C_BasicType, 'void' | 'ptr'>;
+export type C_Integer = Exclude<C_Number, 'f32' | 'f64'>;
+export type Encoding = 'utf-8' | 'utf-16le';
+type First = '_' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+export type SimpleToken = C_Number | `${C_Number}@${keyof EnumMap}` | `<${string}>ptr` | `${string}ptr!` | `<${string}>ptr@${keyof EnumMap}`;
+export type SimpleMember = {
+    [K: `${First}${string}`]: SimpleValue;
+    [K: `$${string}`]: C_Struct | C_Union;
+};
+export interface C_Struct {
+    '#': 'struct';
+    '#pack'?: number;
+    [K: `${First}${string}`]: SimpleValue;
+    [K: `$${string}`]: C_Struct | C_Union;
+}
+export interface C_Union {
+    '#': 'union';
+    '#pack'?: number;
+    [K: `${First}${string}`]: SimpleValue;
+    [K: `$${string}`]: C_Struct | C_Union;
+}
+export type C_Array = {
+    '#': 'array';
+    element: SimpleValue;
+    length: number;
+};
+export type SimpleValue = SimpleToken | `${SimpleToken}[${number}]` | `${C_Number}:${number}` | `${'u8' | 'u16'}[${number}]@${Encoding}` | C_Struct | C_Union | C_Array;
+export declare const PTR_SIZE: number;
+export declare const SizeAlign: Record<C_Number, number>;
+export type Ptr<T extends string> = '' extends T ? number : number & {
+    readonly ptrBrand: T;
+};
+/** NULL 品牌零：0 的品牌形态 —— 全 FFI 层唯一的空指针字面量（对应 C 的 NULL 宏，
+ *  运行时就是 0）。JS 的 null 不在指针值域：类型层禁收，运行时不做 null→0 转换
+ *  （动态 null 在参数槽 / 写槽处 fail-loud 报错）。 */
+export type NULL = 0 & {
+    readonly ptrBrand: 'NULL';
+};
+export declare const NULL: NULL;
+/** 唯一指针类型：参数位 / 返回位 / struct 字段 / closure 双侧通用。
+ *  C→JS 0 保真（readScalar 不做 0→null）；JS→C 空位写 NULL（写槽即 0）。
+ *  传参前由 tsc 收窄掉空位（truthy / === NULL / === 0）。 */
+export type MaybePtr<T extends string> = NULL | Ptr<T>;
+export type C_TypeJsTypeMap = {
+    u8: number;
+    i8: number;
+    u16: number;
+    i16: number;
+    u32: number;
+    i32: number;
+    i64: bigint;
+    u64: bigint;
+    f32: number;
+    f64: number;
+};
+export type TokenArgJsTypeMap = C_TypeJsTypeMap;
+export type TokenReturnJsTypeMap = C_TypeJsTypeMap & {
+    void: void;
+};
+/** token 枚举标注（'u32@Name' / '<>ptr@Name'）的值域表 —— 全局 interface 声明合并：
+ *  预填由 tools/gen_enum_map.sh 从 quickwin_const.d.ts 提取（quickwin_enum_map.d.ts），
+ *  用户在自己的 .d.ts 里直接扩展（interface EnumMap { MyEnum: import('...').MyEnum }）——
+ *  勿用 declare module：用户 import specifier 形态五花八门，模块匹配不上；全局合并对
+ *  「按枚举名索引」的 token 语义才成立。消费点（bind Arg/Ret、struct 字段）统一以
+ *  `infer E extends keyof EnumMap` 收紧后直接索引本表 —— 值域类型不分参数/返回语境
+ *  （拦异种枚举、域外字面量靠枚举类型自身的 nominal）；未知枚举名由词汇/分支约束
+ *  挡在外面：struct 定义点 ∉ SimpleValue，bind 签名落链末 map[never] 塌 never
+ *  （参数位）/ unknown（返回位——never 是 bottom 会被任意使用放行，反而危险）。 */
+declare global {
+    interface EnumMap {
+    }
+}
+export type ArgJsTypeOfToken<K extends string, L> = K extends `<${infer N}>ptr!` ? Ptr<N> | L[N & keyof L] : K extends `<${string}>ptr@${infer E extends keyof EnumMap}` ? EnumMap[E] : K extends `<${infer N}>ptr` ? MaybePtr<N> | L[N & keyof L] : K extends `<${infer N}>` ? L[N & keyof L] : K extends `${C_Number}@${infer E extends keyof EnumMap}` ? EnumMap[E] : TokenArgJsTypeMap[K & keyof TokenArgJsTypeMap] extends never ? never : TokenArgJsTypeMap[K & keyof TokenArgJsTypeMap];
+export type RetJsTypeOfToken<K extends string, D> = K extends `<${infer N}>ptr!` ? (D[N & keyof D] extends never ? Ptr<N> : D[N & keyof D]) : K extends `<${string}>ptr@${infer E extends keyof EnumMap}` ? EnumMap[E] : K extends `<${infer N}>ptr` ? (D[N & keyof D] extends never ? MaybePtr<N> : D[N & keyof D] | NULL) : K extends `${C_Number}@${infer E extends keyof EnumMap}` ? EnumMap[E] : TokenReturnJsTypeMap[K & keyof TokenReturnJsTypeMap] extends never ? unknown : TokenReturnJsTypeMap[K & keyof TokenReturnJsTypeMap];
+export declare function normToken(t: string): C_BasicType_Token;
+export declare function readScalar(dv: DataView, off: number, k: C_BasicType_No_Void): number | bigint | null;
+type Entry = {
+    [K in C_BasicType_No_Void]: {
+        k: K;
+        v: (C_TypeJsTypeMap & {
+            ptr: number;
+        })[K];
+    };
+}[C_BasicType_No_Void];
+/** 内存写：按 sizeof 精确写，供 struct 字段编码用。小整数只占自己的字节，
+ *  否则 `{a:u8,b:u8}` 这类紧凑布局会被 setUint32 越界覆盖相邻字段。 */
+export declare function writeScalar(dv: DataView, off: number, { k, v }: Entry): void;
+/** 槽写：供 bind 的参数槽/返回槽用。小整数扩展到 4 字节 —— 可变参数按 int 提升读，
+ *  `i8 = -1` 必须给 `0xFFFFFFFF` 而非 `0x000000FF`。u32/i32/u64/i64/f32/f64/ptr
+ *  槽宽 == sizeof，直接委托 writeScalar。 */
+export declare function writeSlot(dv: DataView, off: number, e: Entry): void;
+/** buffer + 品牌指针合一：一个引用既是 ArrayBuffer（喂 decode / encode(v, buf) 复用）
+ *  又带 `.ptr` 直接喂 <N>ptr 形参 —— 替代旧 { buf, ptr } 结构包装。
+ *  `ptr` 是构造时快照（与旧 StructAlloc 同性质：底层数据不可 detach/transfer）。
+ *  品牌 N 由创建方声明：struct def 的 alloc()/encode() 返回值在类型层带 def 的 N（不可伪造）；
+ *  直接 new 属自报品牌，仅限内部/原型场景 —— 生产路径一律走 def.alloc()。 */
+export declare class PtrArrayBuffer<N extends string> extends ArrayBuffer {
+    readonly ptr: Ptr<N>;
+    constructor(byteLength: number);
+}
+export {};

package/lib/ffi/index.d.ts

@@ -0,0 +1,2 @@
+export * from './bind.js';
+export * from './struct.js';

package/lib/ffi/struct.d.ts

@@ -0,0 +1,174 @@
+import '../text-codec.js';
+import { C_BasicType_No_Void, C_TypeJsTypeMap, MaybePtr, PtrArrayBuffer, type C_Array, type C_Integer, type C_Number, type C_Struct, type C_Union, type Encoding, type Ptr, type SimpleMember, type SimpleToken } from './ctype.js';
+type N = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53;
+type ValOf<T> = T extends `<${infer B}>ptr!` ? Ptr<B> : T extends `<${string}>ptr@${infer E extends keyof EnumMap}` ? EnumMap[E] : T extends `<${infer B}>ptr` ? MaybePtr<B> : T extends `${infer U}@${infer E extends keyof EnumMap}` ? (U extends C_Number ? EnumMap[E] : never) : T extends C_Number ? C_TypeJsTypeMap[T] : never;
+type BitShape<T extends string, W extends number> = T extends C_Integer ? (W extends N ? number : bigint) : never;
+type ShapeOfValue<V> = V extends infer T extends SimpleToken ? ValOf<T> : V extends `${infer U}[${infer L}]@${infer E}` ? (U extends 'u8' | 'u16' ? (L extends `${number}` ? (E extends Encoding ? string : never) : never) : never) : V extends `${infer T extends SimpleToken}[${infer L extends number}]` ? Tuple<ShapeOfValue<T>, L> : V extends `${infer T extends SimpleToken}:${infer W extends number}` ? BitShape<T, W> : V extends {
+    '#': 'array';
+    element: infer E;
+    length: infer L extends number;
+} ? Tuple<ShapeOfValue<E>, L> : V extends {
+    '#': 'struct' | 'union';
+} ? ShapeOfC<V> : never;
+type Tuple<T, N extends number, R extends T[] = []> = number extends N ? T[] : R['length'] extends N ? R : R['length'] extends 64 ? T[] : Tuple<T, N, [...R, T]>;
+type DollarKeys<T> = {
+    [K in keyof T]: K extends `$${string}` ? K : never;
+}[keyof T];
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+type Lift<T> = {
+    [K in keyof T as K extends `$${string}` ? never : K]: T[K] extends readonly unknown[] ? T[K] : T[K] extends number ? T[K] : T[K] extends object ? Lift<T[K]> : T[K];
+} & UnionToIntersection<{
+    [K in DollarKeys<T>]: Lift<T[K]>;
+}[DollarKeys<T>]>;
+type FieldKey<K> = K extends `#${string}` ? never : K extends `${infer B}@${string}` ? B : K;
+type _ShapeOfC<M> = {
+    [K in keyof M as FieldKey<K>]: ShapeOfValue<M[K]>;
+};
+type ShapeOfC<M> = Lift<_ShapeOfC<M>>;
+export type DeepPartial<T> = T extends readonly unknown[] ? T : T extends number | string | boolean | bigint | symbol ? T : {
+    [K in keyof T]?: DeepPartial<T[K]>;
+};
+type IsSubtreeMandatory<D> = D extends {
+    '#': 'array';
+    element: infer E;
+} ? IsSubtreeMandatory<E> : D extends {
+    '#': 'struct' | 'union';
+} ? (true extends {
+    [K in keyof D]-?: IsSubtreeMandatory<D[K]> extends true ? true : false;
+}[keyof D] ? true : false) : D extends `${string}[${number}]@${string}` ? false : D extends `${infer TK extends SimpleToken}[${string}]` ? IsSubtreeMandatory<TK> : D extends `${string}:${number}` ? false : D extends `<${string}>ptr!` ? true : D extends `<${string}>ptr@${infer E extends keyof EnumMap}` ? (0 extends EnumMap[E] ? false : true) : D extends `${infer U}@${infer E extends keyof EnumMap}` ? (U extends C_Number ? (0 extends EnumMap[E] ? false : true) : false) : false;
+type MandatoryDeclKeys<T> = {
+    [K in keyof T]-?: IsSubtreeMandatory<T[K]> extends true ? FieldKey<K> : never;
+}[keyof T];
+type EncodeValOfT<D> = D extends {
+    '#': 'struct' | 'union';
+} ? EncodeShapeOfC<D> : ShapeOfValue<D>;
+type EncodeShapeOfC<T> = DeepPartial<ShapeOfC<T>> & {
+    [K in keyof T as IsSubtreeMandatory<T[K]> extends true ? FieldKey<K> : never]-?: EncodeValOfT<T[K]>;
+};
+type EncodeIn<T extends {
+    '#': 'struct' | 'union';
+}> = [
+    MandatoryDeclKeys<T>
+] extends [never] ? DeepPartial<ShapeOfC<T>> : EncodeShapeOfC<T>;
+type FieldType = {
+    tag: 'basic';
+    kind: C_BasicType_No_Void;
+} | {
+    tag: 'bitfield';
+    unit: C_Integer;
+    bit: number;
+    width: number;
+} | {
+    tag: 'string';
+    encoding: Encoding;
+} | {
+    tag: 'struct' | 'union';
+    fields: Field[];
+} | {
+    tag: 'array';
+    elementType: FieldType;
+    elementSize: number;
+};
+export type Field = {
+    name: string;
+    offset: number;
+    size: number;
+    type: FieldType;
+    /** '!' 标注字段（原文 token `<X>ptr!`）：decode 读出 0 当场 throw（后置兜底 ——
+     *  C 没填 / 拿未填充槽 decode 都在这里拦，见 doDecode）。 */
+    nonnull?: true;
+};
+export type Fields = Field[];
+export type StructDef<T extends {
+    '#': 'struct' | 'union';
+}, N extends string = ''> = {
+    readonly fields: Fields;
+    readonly size: number;
+    readonly structAlign: number;
+    decode(buf: ArrayBuffer | Ptr<N>): ShapeOfC<T>;
+    /** n（默认 1）= 按本布局 size 步长连续分配 n 个元素的零填充缓冲（出参数组场景，
+     *  品牌 .ptr 直接喂 <N>ptr 位）。n < 1 / 非整数运行时 throw ——
+     *  任何路径都不产出 PAB(0)（其 .ptr 是"非 0 的 1 字节堆指针"，会骗过 C 的 NULL
+     *  防御；空位语义由调用方显式传 NULL）。 */
+    alloc(n?: number): PtrArrayBuffer<N>;
+    encode(v: EncodeIn<T>): PtrArrayBuffer<N>;
+    encode(v: EncodeIn<T>, buf: PtrArrayBuffer<any>, offset?: number): PtrArrayBuffer<any>;
+    offsetOf(name: string): number;
+};
+type Layout = {
+    size: number;
+    maxEffectiveAlign: number;
+    fields: Fields;
+};
+export declare function computeArray(t: C_Array): {
+    align: number;
+    size: number;
+};
+export declare function computeStructLayout(t: C_Struct | C_Union): Layout;
+/** 聚合对齐上限（pack 压 maxAlign，语义同 MSVC #pragma pack）。 */
+export type AggOpts = {
+    pack?: number;
+};
+/** 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<D extends StructDef<any, any>> = {
+    (p: ArrayBuffer, count?: number): DecOf<D>[];
+    (p: AddrOf<D>, count: number): DecOf<D>[];
+};
+/** 结构/联合体的数组编解码对工厂：返回 `{ encode, decode }`。
+ *  encode —— 单值 encoder 的数组版：收元素数组 → 按本布局 size 步长紧密排列
+ *  （stride = size，已含尾部对齐 padding），返回带品牌 .ptr 的 PAB —— 与 C 的
+ *  `const T apt[]` 同构。值域刻意收普通数组（调用方持有的 `const pts = [...]` 变量
+ *  直传，非空元组会拒之）；[] / 非数组 / 单对象运行时 throw —— 任何路径都不产出
+ *  PAB(0)（其 .ptr 是"非 0 的 1 字节堆指针"，会骗过 C 的 NULL 防御；空位语义由
+ *  调用方显式传 NULL）。注册进 bind 的 encoders 表（`{ POINT: structArray(POINT) }`）
+ *  后，普通 `<POINT>ptr` 位的值域即元素数组（值域由 encoder 推导，token/引擎/类型层
+ *  零数组概念）；直接调用 `.encode(els).ptr` 亦可。
+ *  decode —— 出参数组读回（与 def.decode 的 ArrayBuffer/地址双态对称）：
+ *  - buffer 形（含 PAB）：count? 缺省自算 byteLength/size —— 要求整数倍，% ≠ 0
+ *    throw（混合缓冲如 EnumPrinters 的"结构 + 尾部字符串"必须显式 count）；显式
+ *    count 校验 count*size ≤ byteLength（写错 count → 越界读的防线，buf 形可校才
+ *    校；不验品牌，与 def.decode 的 buffer 形同款）。
+ *  - 裸地址形：count 必填（地址无长度信息），逐字节拷读（def.decode 的 number 形
+ *    同机制）；长度不可校 → 信任 C 的 count。
+ *  - count = 0 → []（读 0 个真空安全，与 encode 禁空的 PAB(0) 理由刻意不对称）。
+ *  实现：encode 走纯公开 API（alloc + encode offset 循环）；decode 直接读 def.fields
+ *  （createStruct 暴露的布局 IR，与 def.decode 同一份，无需重算）。 */
+export declare function structArray<D extends StructDef<any, any>>(def: D): {
+    encode: (els: readonly EncInOf<D>[]) => PABOf<D>;
+    decode: StructArrayDecode<D>;
+};
+/** 平铺字段表定义结构体（token/`X[n]`/`unit:width`/`'#'` 声明均可，见 ctype.ts §4）。
+ *  给 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 declare function struct<const M extends SimpleMember>(member: M & {
+    '#'?: 'struct';
+}, opts?: AggOpts): StructOf<M>;
+export declare function struct<const N extends string, const M extends SimpleMember>(name: N, member: M & {
+    '#'?: 'struct';
+}, opts?: AggOpts): StructOf<M, N>;
+/** 平铺字段表定义联合体；布局/读写与 struct 相同，仅成员偏移重叠。DECL 常量可直传，
+ *  参数交叉 `{ '#'?: 'union' }` 锁 kind（struct 侧镜像，理由见上）。 */
+export declare function union<const M extends SimpleMember>(member: M & {
+    '#'?: 'union';
+}, opts?: AggOpts): UnionOf<M>;
+export declare function union<const N extends string, const M extends SimpleMember>(name: N, member: M & {
+    '#'?: 'union';
+}, opts?: AggOpts): UnionOf<M, N>;
+export {};

package/lib/http-common.d.ts

@@ -0,0 +1,143 @@
+import './polyfill.js';
+import './stream.js';
+export declare function _concat(parts: Uint8Array[]): Uint8Array<ArrayBuffer>;
+export declare function _toReadableStream(body: BodyInit): ReadableStream<Uint8Array>;
+export declare function _readStream(stream: ReadableStream<Uint8Array>): Promise<Uint8Array<ArrayBuffer>>;
+export declare function _hasChunkedEnd(data: Uint8Array): boolean;
+export declare function decodeChunked(data: Uint8Array): Uint8Array;
+export declare class HeadersImpl {
+    private _headers;
+    constructor(init?: HeadersInit);
+    append(name: string, value: string): void;
+    delete(name: string): void;
+    get(name: string): string | null;
+    has(name: string): boolean;
+    set(name: string, value: string): void;
+    forEach(callback: (value: string, name: string, headers: HeadersImpl) => void): void;
+    entries(): IterableIterator<[string, string]>;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<string>;
+    [Symbol.iterator](): IterableIterator<[string, string]>;
+}
+export declare class RequestImpl {
+    readonly url: string;
+    readonly method: string;
+    readonly headers: HeadersImpl;
+    private _body;
+    readonly redirect: RequestRedirect;
+    readonly timeout: number;
+    readonly maxRedirects: number;
+    private _bodyConsumed;
+    readonly integrity: string;
+    readonly keepalive: boolean;
+    readonly mode: string;
+    readonly cache: string;
+    readonly credentials: string;
+    readonly referrer: string;
+    readonly referrerPolicy: string;
+    readonly signal: AbortSignal | null;
+    readonly rejectUnauthorized: boolean;
+    readonly destination: string;
+    get body(): ReadableStream<Uint8Array> | null;
+    get bodyUsed(): boolean;
+    constructor(input: string | RequestImpl, init?: RequestInit);
+    arrayBuffer(): Promise<ArrayBuffer>;
+    json<T = unknown>(): Promise<T>;
+    text(): Promise<string>;
+    clone(): RequestImpl;
+}
+export declare class ResponseImpl {
+    readonly status: number;
+    readonly statusText: string;
+    readonly ok: boolean;
+    private _headers;
+    _redirected: boolean;
+    private _type;
+    _url: string;
+    private _body;
+    private _bodyConsumed;
+    private _trailers;
+    get body(): ReadableStream<Uint8Array>;
+    get bodyUsed(): boolean;
+    /** Trailing headers to emit after a chunked body (Promise resolves to
+     *  a HeadersInit), when a `Trailer` declaration header is present. */
+    get trailers(): Promise<HeadersInit> | undefined;
+    get headers(): HeadersImpl;
+    get redirected(): boolean;
+    get type(): ResponseType;
+    get url(): string;
+    constructor(body?: BodyInit | null, init?: ResponseInit);
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    clone(): Response;
+    _applyDecompressedBody(stream: ReadableStream<Uint8Array>, _body: ArrayBuffer, newHeaders: HeadersImpl): void;
+}
+declare global {
+    type HeadersInit = [string, string][] | Record<string, string> | Headers;
+    type BodyInit = ReadableStream<Uint8Array> | string | ArrayBuffer | ArrayBufferView;
+    type RequestRedirect = 'error' | 'follow' | 'manual';
+    type RequestCache = 'default' | 'force-cache' | 'no-cache' | 'no-store' | 'only-if-cached' | 'reload';
+    type RequestCredentials = 'include' | 'omit' | 'same-origin';
+    type RequestMode = 'cors' | 'navigate' | 'no-cors' | 'same-origin';
+    type ResponseType = 'basic' | 'cors' | 'default' | 'error' | 'opaque' | 'opaqueredirect';
+    interface AbortSignal {
+        readonly aborted: boolean;
+        readonly reason: unknown;
+        onabort: ((event: {
+            type: 'abort';
+            target: unknown;
+        }) => void) | null;
+        addEventListener(type: 'abort', listener: (e: {
+            type: 'abort';
+            target: unknown;
+        }) => void): void;
+        removeEventListener(type: 'abort', listener: (e: {
+            type: 'abort';
+            target: unknown;
+        }) => void): void;
+        throwIfAborted(): void;
+    }
+    interface RequestInit {
+        body?: BodyInit | null;
+        cache?: RequestCache;
+        credentials?: RequestCredentials;
+        headers?: HeadersInit;
+        integrity?: string;
+        keepalive?: boolean;
+        method?: string;
+        mode?: RequestMode;
+        redirect?: RequestRedirect;
+        referrer?: string;
+        referrerPolicy?: string;
+        signal?: AbortSignal | null;
+        window?: null;
+        timeout?: number;
+        maxRedirects?: number;
+        /** Non-standard: when false, TLS certificate verification is skipped
+         *  (mirrors Node's https.request rejectUnauthorized option). */
+        rejectUnauthorized?: boolean;
+    }
+    interface ResponseInit {
+        status?: number;
+        statusText?: string;
+        headers?: HeadersInit;
+        /** Non-standard: trailing headers, resolved after the body streams.
+         *  http-server emits them (Node addTrailers semantics) when a `Trailer`
+         *  declaration header is present and the body is chunk-framed. */
+        trailers?: Promise<HeadersInit>;
+    }
+    interface Headers extends HeadersImpl {
+    }
+    var Headers: typeof HeadersImpl;
+    interface Response extends Omit<ResponseImpl, '_url' | '_redirected' | '_applyDecompressedBody'> {
+    }
+    interface ResponseConstructor {
+        new (body?: BodyInit | null, init?: ResponseInit): Response;
+    }
+    var Response: ResponseConstructor;
+    interface Request extends RequestImpl {
+    }
+    var Request: typeof RequestImpl;
+}