wgpu-kit 1.1.0 → 1.1.2

package/README.cn.md

@@ -51,7 +51,7 @@ await integrate.run({ pos, vel }, { dt: 0.02 });
 
 | 导入 | 用途 |
 | --- | --- |
-| `wgpu-kit` | elementKernel 核心 + Buffer / PingPong / rawKernel |
+| `wgpu-kit` | elementKernel 核心 + Buffer / PingPong / rawKernel + **类型化 schema** + **pack 平台** |
 | `wgpu-kit/particles` | 粒子生命:力矩阵预设、自适应世界、热更新 |
 | `wgpu-kit/life` | 图灵斑图 / 粘菌 / Boids / 软体触手 |
 | `wgpu-kit/fields` | 向量场平迹 |
@@ -66,14 +66,75 @@ await integrate.run({ pos, vel }, { dt: 0.02 });
 
 *life 包:图灵斑图 / 粘菌 / Boids / 软体触手 — [打开演示](https://nanfengw0w.github.io/wgpu-kit/life.html)。*
 
+## 类型化 schema
+
+WGSL 仍是 WGSL,但**字段表不再是会写错的字符串**。声明一次,TS 行类型、
+WGSL struct 代码和 GPU 缓冲全部同源;拼错字段是编辑器里的红线,不是运行时错误:
+
+```ts
+import { defineSchema, elementKernel } from 'wgpu-kit';
+
+const Boid = defineSchema({ pos: 'vec2f', vel: 'vec2f', species: 'u32' });
+type Boid = SchemaInfer<typeof Boid.fields>;   // { pos: {x,y}, vel: {x,y}, species: number }
+
+const bufs = await Boid.buffers(count);
+bufs.pos.write([{ x: 1, y: 2 }, /* … */]);      // ❌ 写成 `{ z: 0 }` 编译期就报
+const k = elementKernel({ state: Boid.fields, code: 'fn userFn(idx: u32) { … }' });
+await k.run(bufs.raws());
+const rows = await bufs.pos.read();             // 返回带类型的行对象
+```
+
+诚实边界:WGSL 函数体**内部**的拼写错误仍由 WGSL 编译器报错(带你的行号映射)。
+完整的 WGSL 类型检查是编译器工程;本层消灭的是 JS/WGSL **schema 漂移**和
+无类型的 buffer 读写。
+
+## 平台,不是功能列表
+
+内置包没有任何特权。`definePack` 就是内置包自己用的契约——统一生命周期、
+统计、自验证 `probe()` 和注册表:
+
+```ts
+import { definePack, registerPack, listPacks } from 'wgpu-kit';
+
+const orbit = definePack({
+  name: 'orbit',
+  description: 'my N-body toy',
+  create: async (config) => {
+    // … 用 elementKernel / rawKernel 搭你的模拟 …
+    return {
+      tick() { /* … */ },
+      async probe() { return { energyDrift: 0.003 }; },  // verify harness 会收集
+      destroy() { /* … */ },
+    };
+  },
+});
+registerPack(orbit);
+listPacks(); // [{ name: 'particles', … }, { name: 'fields', … }, { name: 'orbit', … }]
+```
+
+`probe()` 是平台的关键约定:第三方包在验证 harness 里享受与内置包完全相同
+的待遇——正确性是契约的一部分,不是恩赐。
+
 ## 数字(全部可复现)
 
-| 指标 | 数值 | 环境 |
-| --- | --- | --- |
-| 粒子端到端 | 200,000 @ 122fps · 66,000 @ 144fps(**可见帧**)| RTX 4060 Laptop,playground 实测 |
-| 粒子计算(grid) | 16k→262k 平坦,3.0→4.4ms/帧 | headless 基准,GPU 42°C |
-| 邻域算法 | grid 近似 O(N),66k 时比暴力快 8.5× | 同会话 A/B |
-| 库体积 | core gzip ~10kB(共享上下文构建) | gzip |
+三种都是真实数字,量的是不同的东西,**别混着读**(双口径全表见
+[docs/BENCHMARK.md](docs/BENCHMARK.md),由 `npm run bench` 生成):
+
+- **显示帧率**:playground 里实际看到的 fps,由浏览器节流(探针:URL 加
+  `?verify=10` 自报);
+- **管线饱和吞吐**:3 帧在途泵送——每帧提交不等完成、在途满 3 帧排空一次,
+  这是 GPU 的持续吞吐上限(`npm run bench` 的"管线 fps"列);
+- **同步延迟**:每帧 `tick()` 后等 GPU 完成——单帧往返上界,用于算法 A/B。
+
+| 指标 | 数值 | 口径 | 环境 |
+| --- | --- | --- | --- |
+| 粒子端到端 | 200,000 @ ~120fps · 66,000 @ ~144fps | 显示 | RTX 4060 Laptop,playground 探针 |
+| 粒子计算(grid)同步 | 16k → 200k:3.6 → 36ms/帧 | 同步 | `npm run bench` → docs/BENCHMARK.md |
+| 邻域算法 | grid 近似 O(N),66k 时比暴力快 8.5× | 同步 A/B | 同会话 |
+| 库体积 | core gzip ~15kB,含类型化 schema 与 pack 平台(共享上下文构建) | — | gzip 预算由 build 强制 |
+
+所以:如果你用每帧 `device.queue.onSubmittedWorkDone()` 去测 grid@200k,
+看到的会是 ~30ms——那是同步延迟列,和 120fps 不矛盾。
 
 ## 三条设计铁律
 
@@ -81,6 +142,17 @@ await integrate.run({ pos, vel }, { dt: 0.02 });
 2. **错误说人话**——WGSL 编译失败映射回你的代码行号;
 3. **基准即文档**——所有数字可复现;gzip 体积预算由 `npm run build` 强制核对。
 
+## 验证
+
+41+ 自动化探针在真实 GPU 上经 headless Chromium harness 运行(随库附带:
+`tests/` + `scripts/verify.mjs`)——包括**物理等价性回归**(n2 / tiled / grid
+三种邻域算法结构发散即构建失败),以及扫描不变量与冻结带检测(确定性拦截
+半格失效类 bug)。
+
+**CI 中**:正确性子集(smoke / packages / grid 不变量)在每次 push 时于
+Chrome 的 SwiftShader WebGPU 上运行——无需 GPU——物理正确性不会在机器之间
+悄悄回退。fps 类探针在 CPU 适配器上没有意义,按设计只在真机上跑。
+
 ## 支持矩阵
 
 | 浏览器 | 状态 |

package/README.md

@@ -91,7 +91,7 @@ to compile, the error points at **your line**.
 
 | import | purpose |
 | --- | --- |
-| `wgpu-kit` | elementKernel core + Buffer / PingPong / rawKernel |
+| `wgpu-kit` | elementKernel core + Buffer / PingPong / rawKernel + **typed schemas** + **pack platform** |
 | `wgpu-kit/particles` | particle life: presets, adaptive world, live updates |
 | `wgpu-kit/life` | Turing patterns / Physarum / Boids / Tentacles |
 | `wgpu-kit/fields` | vector-field advection trails |
@@ -106,16 +106,81 @@ to compile, the error points at **your line**.
 
 *The life pack: Turing patterns / Physarum / Boids / Tentacles — [open the demo](https://nanfengw0w.github.io/wgpu-kit/life.html).*
 
+## Type-safe schemas
+
+WGSL stays WGSL, but the *field table* stops being a string you can get wrong.
+Declare once — TypeScript row types, WGSL struct code and GPU buffers all come
+from the same declaration; a typo'd field is a red squiggle, not a runtime error:
+
+```ts
+import { defineSchema, elementKernel } from 'wgpu-kit';
+
+const Boid = defineSchema({ pos: 'vec2f', vel: 'vec2f', species: 'u32' });
+type Boid = SchemaInfer<typeof Boid.fields>;   // { pos: {x,y}, vel: {x,y}, species: number }
+
+const bufs = await Boid.buffers(count);
+bufs.pos.write([{ x: 1, y: 2 }, /* … */]);      // ❌ `{ z: 0 }` fails at compile time
+const k = elementKernel({ state: Boid.fields, code: 'fn userFn(idx: u32) { … }' });
+await k.run(bufs.raws());
+const rows = await bufs.pos.read();             // typed rows back
+```
+
+Honest boundary: errors inside your WGSL function body are still caught by the
+WGSL compiler (with your-line mapping). Full WGSL type-checking is a compiler
+project; what this layer eliminates is JS/WGSL **schema drift** and untyped
+buffer I/O.
+
+## A platform, not a feature list
+
+The built-in packs are not privileged. `definePack` is the same contract they
+use — lifecycle, stats, a self-verification `probe()` and a registry:
+
+```ts
+import { definePack, registerPack, listPacks } from 'wgpu-kit';
+
+const orbit = definePack({
+  name: 'orbit',
+  description: 'my N-body toy',
+  create: async (config) => {
+    // … build your sim from elementKernel / rawKernel …
+    return {
+      tick() { /* … */ },
+      async probe() { return { energyDrift: 0.003 }; },  // verify harness collects this
+      destroy() { /* … */ },
+    };
+  },
+});
+registerPack(orbit);
+listPacks(); // [{ name: 'particles', … }, { name: 'fields', … }, { name: 'orbit', … }]
+```
+
+`probe()` is the platform deal: a third-party pack gets the same treatment in
+the verification harness as the built-ins — correctness is part of the
+contract, not a courtesy.
+
 ## Numbers (reproducible)
 
-All fps numbers are **visible frames** — every `tick()` renders fresh state.
+Two honest measurement conventions — both real, measuring different things. **Don't
+mix them up** (see [docs/BENCHMARK.md](docs/BENCHMARK.md) for both, generated by
+`npm run bench`):
+
+- **Display fps** — what you actually see in the playground, paced by the
+  browser (probe: append `?verify=10` to any playground URL — it self-reports
+  fps and GPU errors).
+- **Pipeline saturation** — bounded 3-frame-in-flight pump: `tick()` without
+  waiting, drain every 3 frames. The GPU's sustained throughput ceiling.
+- **Sync latency** — `tick()` then wait for GPU completion every frame. Upper
+  bound on per-frame round-trip; used for same-session algorithm A/B.
 
-| metric | value | environment |
-| --- | --- | --- |
-| particles end-to-end | 200,000 @ 122fps · 66,000 @ 144fps | RTX 4060 Laptop, playground |
-| particle compute (grid) | 16k→262k flat, 3.0→4.4ms/frame | reproducible via `npm run bench` → docs/BENCHMARK.md |
-| neighborhood algorithms | grid ~O(N), 8.5× faster than brute force at 66k | same-session A/B |
-| bundle size | core gzip ~10kB (all entries share one context) | measured by `npm run build` |
+| metric | value | convention | environment |
+| --- | --- | --- | --- |
+| particles end-to-end | 200,000 @ ~120fps · 66,000 @ ~144fps | display | RTX 4060 Laptop, playground probe |
+| particle compute (grid), sync | 16k → 200k: 3.6 → 36 ms/frame | sync | `npm run bench` → docs/BENCHMARK.md |
+| neighborhood algorithms | grid ~O(N), 8.5× faster than brute force at 66k | sync A/B | same-session |
+| bundle size | core gzip ~15kB incl. typed schemas + pack platform (all entries share one context) | — | enforced by `npm run build` |
+
+So yes: if you benchmark grid @200k with a per-frame `device.queue.onSubmittedWorkDone()`
+you will see ~30ms — that is the sync-latency column, not a contradiction.
 
 ## Three design rules
 
@@ -130,7 +195,13 @@ All fps numbers are **visible frames** — every `tick()` renders fresh state.
 41+ automated probes run on a real GPU via a headless Chromium harness
 (included: `tests/` + `scripts/verify.mjs`) — including a **physics
 equivalence regression** that fails the build if the neighborhood algorithms
-(n2 / tiled / grid) ever produce divergent structures.
+(n2 / tiled / grid) ever produce divergent structures, plus scan-invariant and
+frozen-band checks that catch partial-grid failures deterministically.
+
+**In CI:** the correctness subset (smoke / packages / grid invariants) runs on
+every push against Chrome's SwiftShader WebGPU — no GPU required — so the
+physics cannot silently regress between machines. fps-class probes are
+meaningless on a CPU adapter and stay on real hardware by design.
 
 ## Support matrix
 

package/dist/core/buffer.js

@@ -1,6 +1,6 @@
 import { TYPES } from "./layout.js";
 import { GpuContext } from "./context.js";
-import { UsageError } from "./errors.js";
+import { ERR, UsageError } from "./errors.js";
 const TYPED_CTORS = {
     Float32Array, Int32Array, Uint32Array,
 };
@@ -16,6 +16,7 @@ export class Buffer {
     #ctx;
     #byteLength;
     #stride;
+    #reading = null;
     #staging = null;
     constructor(ctx, kind, length, gpuBuffer) {
         this.#ctx = ctx;
@@ -27,11 +28,11 @@ export class Buffer {
     }
     static async create(kind, length) {
         if (!Number.isInteger(length) || length <= 0) {
-            throw new UsageError(`Buffer 长度必须是正整数,收到: ${String(length)}`);
+            throw new UsageError(ERR.BUFFER_CREATE, `Buffer length must be a positive integer, got: ${String(length)}`);
         }
         const def = TYPES[kind];
         if (!def)
-            throw new UsageError(`未知类型 "${String(kind)}",可用: ${Object.keys(TYPES).join(', ')}`);
+            throw new UsageError(ERR.BUFFER_CREATE, `Unknown Buffer kind "${String(kind)}". Available: ${Object.keys(TYPES).join(", ")}`);
         const ctx = await GpuContext.get();
         const gpuBuffer = ctx.device.createBuffer({
             size: length * def.stride,
@@ -45,11 +46,11 @@ export class Buffer {
         const def = TYPES[this.kind];
         const ctor = TYPED_CTORS[def.typed];
         if (!(data instanceof ctor)) {
-            throw new UsageError(`Buffer<${this.kind}>.write 需要 ${def.typed},收到 ${data.constructor?.name ?? typeof data}`);
+            throw new UsageError(ERR.BUFFER_WRITE, `Buffer<${this.kind}>.write expects ${def.typed}, got ${data.constructor?.name ?? typeof data}`);
         }
         const expected = this.length * def.comps;
         if (data.length !== expected) {
-            throw new UsageError(`Buffer<${this.kind}>[${this.length}].write 需要 ${expected} 个分量,收到 ${data.length}`);
+            throw new UsageError(ERR.BUFFER_WRITE, `Buffer<${this.kind}>[${this.length}].write expects ${expected} components, got ${data.length}`);
         }
         if (def.stride === def.size || def.comps === 1) {
             this.#ctx.device.queue.writeBuffer(this.gpuBuffer, 0, data);
@@ -67,6 +68,17 @@ export class Buffer {
     }
     /** GPU → CPU:内部 staging buffer + mapAsync,mapAsync 的异步陷阱由库承担 */
     async read() {
+        if (this.#reading)
+            return this.#reading;
+        this.#reading = this.#doRead();
+        try {
+            return await this.#reading;
+        }
+        finally {
+            this.#reading = null;
+        }
+    }
+    async #doRead() {
         const def = TYPES[this.kind];
         if (!this.#staging) {
             this.#staging = this.#ctx.device.createBuffer({

package/dist/core/codes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Error codes for programmatic identification of wgpu-kit errors.
+ * These are stable string constants — safe to switch on in user code.
+ */
+export declare const ERR: {
+    /** WebGPU is unavailable or the adapter could not be acquired */
+    readonly WGPU_UNAVAILABLE: "ERR_WGPU_UNAVAILABLE";
+    /** WGSL compilation failed */
+    readonly COMPILE: "ERR_COMPILE";
+    /** Invalid argument passed by the caller */
+    readonly USAGE: "ERR_USAGE";
+    /** A required uniform field is missing or has an invalid value */
+    readonly UNIFORM_FIELD: "ERR_UNIFORM_FIELD";
+    /** Uniform scalar types are not yet supported */
+    readonly UNIFORM_UNSUPPORTED: "ERR_UNIFORM_UNSUPPORTED";
+    /** workgroupSize is outside the valid range */
+    readonly WORKGROUP_SIZE: "ERR_WORKGROUP_SIZE";
+    /** A resource (Buffer) is missing from the resources map */
+    readonly RESOURCE_MISSING: "ERR_RESOURCE_MISSING";
+    /** A resource type does not match the kernel declaration */
+    readonly RESOURCE_TYPE: "ERR_RESOURCE_TYPE";
+    /** Resource lengths are inconsistent across state/inputs */
+    readonly RESOURCE_LENGTH: "ERR_RESOURCE_LENGTH";
+    /** Buffer.create received an invalid kind or length */
+    readonly BUFFER_CREATE: "ERR_BUFFER_CREATE";
+    /** Buffer.write type or component count mismatch */
+    readonly BUFFER_WRITE: "ERR_BUFFER_WRITE";
+    /** MediaRecorder is unavailable or the recording failed */
+    readonly MEDIA: "ERR_MEDIA";
+    /** timestamp-query is not supported on this device */
+    readonly TIMESTAMP_UNSUPPORTED: "ERR_TIMESTAMP_UNSUPPORTED";
+    /** A generic library error that doesn't fit any specific code */
+    readonly GENERIC: "ERR_GENERIC";
+};
+export type ErrorCode = (typeof ERR)[keyof typeof ERR];

package/dist/core/codes.js

@@ -0,0 +1,34 @@
+/**
+ * Error codes for programmatic identification of wgpu-kit errors.
+ * These are stable string constants — safe to switch on in user code.
+ */
+export const ERR = {
+    /** WebGPU is unavailable or the adapter could not be acquired */
+    WGPU_UNAVAILABLE: 'ERR_WGPU_UNAVAILABLE',
+    /** WGSL compilation failed */
+    COMPILE: 'ERR_COMPILE',
+    /** Invalid argument passed by the caller */
+    USAGE: 'ERR_USAGE',
+    /** A required uniform field is missing or has an invalid value */
+    UNIFORM_FIELD: 'ERR_UNIFORM_FIELD',
+    /** Uniform scalar types are not yet supported */
+    UNIFORM_UNSUPPORTED: 'ERR_UNIFORM_UNSUPPORTED',
+    /** workgroupSize is outside the valid range */
+    WORKGROUP_SIZE: 'ERR_WORKGROUP_SIZE',
+    /** A resource (Buffer) is missing from the resources map */
+    RESOURCE_MISSING: 'ERR_RESOURCE_MISSING',
+    /** A resource type does not match the kernel declaration */
+    RESOURCE_TYPE: 'ERR_RESOURCE_TYPE',
+    /** Resource lengths are inconsistent across state/inputs */
+    RESOURCE_LENGTH: 'ERR_RESOURCE_LENGTH',
+    /** Buffer.create received an invalid kind or length */
+    BUFFER_CREATE: 'ERR_BUFFER_CREATE',
+    /** Buffer.write type or component count mismatch */
+    BUFFER_WRITE: 'ERR_BUFFER_WRITE',
+    /** MediaRecorder is unavailable or the recording failed */
+    MEDIA: 'ERR_MEDIA',
+    /** timestamp-query is not supported on this device */
+    TIMESTAMP_UNSUPPORTED: 'ERR_TIMESTAMP_UNSUPPORTED',
+    /** A generic library error that doesn't fit any specific code */
+    GENERIC: 'ERR_GENERIC',
+};

package/dist/core/context.js

@@ -6,9 +6,17 @@ import { WebGPUUnavailableError } from "./errors.js";
 export class GpuContext {
     device;
     adapterInfo;
-    constructor(device, adapterInfo) {
+    /**
+     * 必须持有 adapter 强引用:adapter 是 JS 侧到 Dawn Instance 的锚。若被 GC
+     * 回收,设备的异步操作(mapAsync / getCompilationInfo)会随机 abort
+     * "A valid external Instance reference no longer exists" —— 无头 SwiftShader
+     * 上必现的重负载页面死亡根因(CI gpu-probes 第 2~7 跑的事故链)。
+     */
+    #adapter;
+    constructor(device, adapterInfo, adapter) {
         this.device = device;
         this.adapterInfo = adapterInfo;
+        this.#adapter = adapter;
     }
     static #singleton = null;
     /** 仅供设备丢失自动重建(observe.watchDevice)使用:重置单例 */
@@ -26,9 +34,13 @@ export class GpuContext {
     }
     static async #create() {
         if (typeof navigator === 'undefined' || !('gpu' in navigator) || !navigator.gpu) {
-            throw new WebGPUUnavailableError('navigator.gpu 不存在');
+            throw new WebGPUUnavailableError('navigator.gpu is not available');
         }
-        const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
+        // 机器有真 GPU 时 high-performance 命中独显;无 GPU 的 CI/虚拟机/远程桌面
+        // 场景再退到 forceFallbackAdapter(SwiftShader 软件适配器)——正确性一致,
+        // 只是慢,让探针能在任何机器上跑起来而不是直接报"无 WebGPU"。
+        const adapter = (await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' })) ??
+            (await navigator.gpu.requestAdapter({ forceFallbackAdapter: true }));
         if (!adapter)
             throw new WebGPUUnavailableError('requestAdapter() 返回 null');
         const info = adapter.info;
@@ -49,7 +61,7 @@ export class GpuContext {
                 requiredLimits[key] = supported;
         }
         const device = await adapter.requestDevice({ label: 'wgpu-kit', requiredLimits });
-        return new GpuContext(device, label);
+        return new GpuContext(device, label, adapter);
     }
     /** device lost 时 reject;调用方可 await 做清理/提示 */
     get lost() {

package/dist/core/errors.d.ts

@@ -1,20 +1,32 @@
-/** 错误体系:所有错误说人话,给出定位与修复建议(章程原则 3)。 */
+import { type ErrorCode } from './codes.ts';
+/**
+ * Error hierarchy for wgpu-kit. All errors extend WgpuKitError and carry a
+ * stable machine-readable `code` for programmatic handling.
+ */
 export declare class WgpuKitError extends Error {
-    constructor(message: string);
+    /** Stable error code, e.g. 'ERR_WGPU_UNAVAILABLE' — safe to switch on. */
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
 }
-/** 环境无 WebGPU / 拿不到 adapter。 */
+/** WebGPU is unavailable or the adapter could not be acquired. */
 export declare class WebGPUUnavailableError extends WgpuKitError {
     constructor(reason: string);
 }
-/** WGSL 编译错误,行号已映射回用户代码。 */
+/** WGSL compilation failed. Line numbers are mapped back to user code. */
 export declare class CompileError extends WgpuKitError {
     constructor(kernelName: string, messages: readonly {
         line: number;
         msg: string;
     }[], userCodeOffset: number);
 }
-/** 调用方使用不当(缺资源/类型不匹配/长度不一致等)。 */
+/** Caller passed an invalid argument (missing resource, type mismatch, bad length, etc.). */
 export declare class UsageError extends WgpuKitError {
+    constructor(code: ErrorCode, message: string);
 }
-/** 创建 compute 管线并用 pushErrorScope 捕获异步校验错误(超限等),把"黑屏刷屏"变成显式报错 */
+/** Compute pipeline creation failed validation (e.g. too many storage buffers). */
+export declare class PipelineError extends WgpuKitError {
+    constructor(label: string, detail: string);
+}
+export { ERR, type ErrorCode } from './codes.ts';
+/** Create a compute pipeline with pushErrorScope to surface async validation errors. */
 export declare function createComputePipelineChecked(device: GPUDevice, module: GPUShaderModule, label: string, entryPoint?: string): Promise<GPUComputePipeline>;

package/dist/core/errors.js

@@ -1,42 +1,57 @@
-/** 错误体系:所有错误说人话,给出定位与修复建议(章程原则 3)。 */
+import { ERR } from "./codes.js";
+/**
+ * Error hierarchy for wgpu-kit. All errors extend WgpuKitError and carry a
+ * stable machine-readable `code` for programmatic handling.
+ */
 export class WgpuKitError extends Error {
-    constructor(message) {
+    /** Stable error code, e.g. 'ERR_WGPU_UNAVAILABLE' — safe to switch on. */
+    code;
+    constructor(code, message) {
         super(message);
         this.name = new.target.name;
+        this.code = code;
     }
 }
-/** 环境无 WebGPU / 拿不到 adapter。 */
+/** WebGPU is unavailable or the adapter could not be acquired. */
 export class WebGPUUnavailableError extends WgpuKitError {
     constructor(reason) {
-        super(`当前环境不可用 WebGPU: ${reason}\n` +
-            '  排查:① 浏览器需 Chrome/Edge 113+ 或 Safari 18+;② 无头环境需开启 WebGPU;③ 检查 GPU 驱动与硬件加速设置。\n' +
-            '  可用 navigator.gpu 是否存在快速判断。');
+        super(ERR.WGPU_UNAVAILABLE, `WebGPU is unavailable: ${reason}\n` +
+            '  Check: 1) Use Chrome/Edge 113+ or Safari 18+. 2) Enable WebGPU in headless mode. 3) Verify GPU drivers and hardware acceleration.');
     }
 }
-/** WGSL 编译错误,行号已映射回用户代码。 */
+/** WGSL compilation failed. Line numbers are mapped back to user code. */
 export class CompileError extends WgpuKitError {
     constructor(kernelName, messages, userCodeOffset) {
         const mapped = messages
             .map((m) => {
             const userLine = m.line - userCodeOffset;
-            const where = userLine > 0 ? `用户代码第 ${userLine} 行` : `生成代码第 ${m.line} 行(库的问题,欢迎报 issue)`;
+            const where = userLine > 0 ? `your code, line ${userLine}` : `generated code, line ${m.line} (library issue — please file an issue)`;
             return `  ${where}: ${m.msg}`;
         })
             .join('\n');
-        super(`kernel "${kernelName}" WGSL 编译失败:\n${mapped}`);
+        super(ERR.COMPILE, `kernel "${kernelName}" WGSL compilation failed:\n${mapped}`);
     }
 }
-/** 调用方使用不当(缺资源/类型不匹配/长度不一致等)。 */
+/** Caller passed an invalid argument (missing resource, type mismatch, bad length, etc.). */
 export class UsageError extends WgpuKitError {
+    constructor(code, message) {
+        super(code, message);
+    }
+}
+/** Compute pipeline creation failed validation (e.g. too many storage buffers). */
+export class PipelineError extends WgpuKitError {
+    constructor(label, detail) {
+        super(ERR.GENERIC, `compute pipeline "${label}" creation failed: ${detail}`);
+    }
 }
-/** 创建 compute 管线并用 pushErrorScope 捕获异步校验错误(超限等),把"黑屏刷屏"变成显式报错 */
+export { ERR } from "./codes.js";
+/** Create a compute pipeline with pushErrorScope to surface async validation errors. */
 export async function createComputePipelineChecked(device, module, label, entryPoint = 'main') {
     device.pushErrorScope('validation');
     const pipeline = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint } });
     const err = await device.popErrorScope();
     if (err) {
-        throw new WgpuKitError(`compute 管线 "${label}" 创建失败: ${err.message}
-  常见原因:storage buffer 数超过每阶段上限(可向本库提 issue 申请 limits 支持)`);
+        throw new PipelineError(label, err.message);
     }
     return pipeline;
 }

package/dist/core/kernel.d.ts

@@ -40,6 +40,8 @@ interface NormalizedSpec {
     inputs: Array<readonly [string, ScalarKind]>;
     uniforms: Array<readonly [string, ScalarKind]>;
     code: string;
+    /** 入口点静态使用的 binding 号('auto' 布局语义,见生成处的注释) */
+    usedBindings: Set<number>;
 }
 /** 纯函数:规范校验 + WGSL 代码生成。单测直接覆盖,不碰 GPU。 */
 export declare function generateElementKernel(spec: ElementKernelSpec): {