wgpu-kit 1.1.1 → 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/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)使用:重置单例 */
@@ -28,7 +36,11 @@ export class GpuContext {
         if (typeof navigator === 'undefined' || !('gpu' in navigator) || !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/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): {

package/dist/core/kernel.js

@@ -2,6 +2,7 @@ import { planUniform, packUniformInto, TYPES } from "./layout.js";
 import { GpuContext } from "./context.js";
 import { Buffer } from "./buffer.js";
 import { CompileError, ERR, UsageError } from "./errors.js";
+import { createShaderModuleChecked } from "./shader.js";
 const RESERVED = new Set(['count']);
 /** GPUBuffer 的稳定数字身份(WeakMap 分配,用于 bind group 缓存键) */
 let nextBufferId = 0;
@@ -40,6 +41,25 @@ export function generateElementKernel(spec) {
     }
     const uniformEntries = [...uniforms, ['count', 'u32']];
     const uniformLayout = planUniform(uniformEntries);
+    // —— 静态使用分析:layout:'auto' 的绑定组布局只含入口点**实际引用**的绑定。
+    // 声明了但 userFn 没用到的字段若塞进 bind group → 校验错误且被异步吞掉
+    // (表现为核不生效)。头文件由我们生成,字段是否使用等价于其名字是否作为
+    // 词法 token 出现在用户代码里。params(binding 0)因 params.count 恒被使用。
+    const wordInCode = (n) => new RegExp(`\\b${n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(spec.code);
+    const usedBindings = new Set([0]);
+    {
+        let b = 1;
+        for (const [n] of state) {
+            if (wordInCode(n))
+                usedBindings.add(b);
+            b++;
+        }
+        for (const [n] of inputs) {
+            if (wordInCode(n))
+                usedBindings.add(b);
+            b++;
+        }
+    }
     // —— 生成 WGSL:头部(声明) + main + 用户代码 ——
     const header = [];
     header.push('// 由 wgpu-kit elementKernel 生成');
@@ -65,7 +85,7 @@ export function generateElementKernel(spec) {
     const userCodeLineOffset = header.length; // 1-based 行号:用户代码从 offset+1 行开始
     const source = [...header, spec.code].join('\n');
     return {
-        normalized: { name, workgroupSize, state, inputs, uniforms, code: spec.code },
+        normalized: { name, workgroupSize, state, inputs, uniforms, code: spec.code, usedBindings },
         source,
         uniformLayout,
         userCodeLineOffset,
@@ -92,10 +112,9 @@ export function elementKernel(spec) {
     const compilePipeline = async () => {
         const ctx = await GpuContext.get();
         const device = ctx.device;
-        const module = device.createShaderModule({ code: source, label: normalized.name });
+        const { module, messages } = await createShaderModuleChecked(device, source, normalized.name);
         // 捕获编译错误并映射行号
-        const info = await module.getCompilationInfo();
-        const errors = info.messages.filter((m) => m.type === 'error');
+        const errors = messages.filter((m) => m.type === 'error');
         if (errors.length > 0) {
             throw new CompileError(normalized.name, errors.map((m) => ({ line: m.lineNum, msg: m.message })), userCodeLineOffset);
         }
@@ -117,8 +136,10 @@ export function elementKernel(spec) {
             // 先编译后切换:新代码编译失败则保持旧版不动
             const savedSource = source;
             const savedOffset = userCodeLineOffset;
+            const savedNormalized = normalized;
             source = regen.source;
             userCodeLineOffset = regen.userCodeLineOffset;
+            normalized = regen.normalized; // usedBindings 随新代码重算
             try {
                 const p = await compilePipeline();
                 pipelinePromise = Promise.resolve(p);
@@ -127,6 +148,7 @@ export function elementKernel(spec) {
             catch (e) {
                 source = savedSource;
                 userCodeLineOffset = savedOffset;
+                normalized = savedNormalized;
                 throw e;
             }
         },
@@ -176,8 +198,14 @@ export function elementKernel(spec) {
             const identityMatch = cached && cached.ids.length === ids.length && cached.ids.every((id, idx) => id === ids[idx]);
             let bg = identityMatch ? cached.bg : undefined;
             if (!bg) {
-                const entries = [{ binding: 0, resource: { buffer: uniformBuffer } }];
-                ordered.forEach((buffer, i) => entries.push({ binding: i + 1, resource: { buffer: buffer.gpuBuffer } }));
+                // 只绑定入口点静态使用的绑定(layout:'auto' 语义,见生成处的注释)
+                const entries = [];
+                if (normalized.usedBindings.has(0))
+                    entries.push({ binding: 0, resource: { buffer: uniformBuffer } });
+                ordered.forEach((buffer, i) => {
+                    if (normalized.usedBindings.has(i + 1))
+                        entries.push({ binding: i + 1, resource: { buffer: buffer.gpuBuffer } });
+                });
                 bg = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries });
                 bindGroupCache.set(cacheKey, { bg, ids });
             }

package/dist/core/pack.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pack 平台契约:第三方在 core 之上写自己的模拟包,与内置包(particles/life/
+ * fields)平级注册、平级验证。这是"功能集 → 平台"的那一步。
+ *
+ * 契约只有三条(章程原则 2:错误说人话;原则 3:可验证):
+ *   ① create(config) → PackSim:统一的生命周期(attach/tick/stats/destroy);
+ *   ② 可选 probe():自报物理不变量 —— verify harness 会收集并展示,
+ *      第三方包从第一天就拥有与内置包相同的验证故事;
+ *   ③ registerPack():进入运行时注册表,工具链(playground/gallery)可枚举启动。
+ */
+/** 所有 pack 模拟实例的统一生命周期。tick/destroy 必须;其余可选。 */
+export interface PackSim {
+    /** 需要 canvas 的包在此建渲染器(可选) */
+    attach?(canvas: HTMLCanvasElement): Promise<void>;
+    /** 推进一帧(计算 + 可选渲染) */
+    tick(): void;
+    /** 轻量运行统计(fps 等),工具链直接读 */
+    stats?(): Record<string, number | string>;
+    /** 自检:返回物理不变量(如 totalMass / meanSpeed / gpuErrors),verify 页收集展示 */
+    probe?(): Promise<Record<string, number | string | boolean>>;
+    destroy(): void;
+}
+export interface WgpuKitPack<TConfig, TSim extends PackSim = PackSim> {
+    /** 注册表命名空间名(如 'fields');重复注册同名包报 UsageError */
+    readonly name: string;
+    readonly description?: string;
+    create(config?: TConfig): Promise<TSim>;
+}
+/** 声明一个 pack。运行时只做契约校验;泛型把 TConfig 的类型检查交给编辑器。 */
+export declare function definePack<TConfig, TSim extends PackSim>(pack: WgpuKitPack<TConfig, TSim>): WgpuKitPack<TConfig, TSim>;
+/** 注册进全局注册表(同名重复注册报错,防止第三方覆盖内置包) */
+export declare function registerPack<TConfig, TSim extends PackSim>(pack: WgpuKitPack<TConfig, TSim>): void;
+export declare function getPack(name: string): WgpuKitPack<unknown, PackSim> | undefined;
+export declare function listPacks(): Array<{
+    name: string;
+    description: string;
+}>;

package/dist/core/pack.js

@@ -0,0 +1,35 @@
+/**
+ * Pack 平台契约:第三方在 core 之上写自己的模拟包,与内置包(particles/life/
+ * fields)平级注册、平级验证。这是"功能集 → 平台"的那一步。
+ *
+ * 契约只有三条(章程原则 2:错误说人话;原则 3:可验证):
+ *   ① create(config) → PackSim:统一的生命周期(attach/tick/stats/destroy);
+ *   ② 可选 probe():自报物理不变量 —— verify harness 会收集并展示,
+ *      第三方包从第一天就拥有与内置包相同的验证故事;
+ *   ③ registerPack():进入运行时注册表,工具链(playground/gallery)可枚举启动。
+ */
+import { UsageError, ERR } from "./errors.js";
+/** 声明一个 pack。运行时只做契约校验;泛型把 TConfig 的类型检查交给编辑器。 */
+export function definePack(pack) {
+    if (!pack || typeof pack.name !== 'string' || !/^[a-z][a-z0-9-]*$/.test(pack.name)) {
+        throw new UsageError(ERR.USAGE, `definePack: name must be a lowercase identifier, got: ${String(pack?.name)}`);
+    }
+    if (typeof pack.create !== 'function') {
+        throw new UsageError(ERR.USAGE, `definePack("${pack.name}"): create(config) is required`);
+    }
+    return pack;
+}
+const REGISTRY = new Map();
+/** 注册进全局注册表(同名重复注册报错,防止第三方覆盖内置包) */
+export function registerPack(pack) {
+    if (REGISTRY.has(pack.name)) {
+        throw new UsageError(ERR.USAGE, `registerPack("${pack.name}"): already registered`);
+    }
+    REGISTRY.set(pack.name, pack);
+}
+export function getPack(name) {
+    return REGISTRY.get(name);
+}
+export function listPacks() {
+    return [...REGISTRY.values()].map((p) => ({ name: p.name, description: p.description ?? '' }));
+}

package/dist/core/raw.js

@@ -1,5 +1,6 @@
 import { GpuContext } from "./context.js";
 import { CompileError, ERR, UsageError } from "./errors.js";
+import { createShaderModuleChecked } from "./shader.js";
 export function rawKernel(code, entryPoint = 'main', label = 'rawKernel') {
     if (typeof code !== 'string' || code.trim().length === 0)
         throw new UsageError(ERR.USAGE, 'rawKernel requires WGSL code');
@@ -12,9 +13,8 @@ export function rawKernel(code, entryPoint = 'main', label = 'rawKernel') {
             const ctx = await GpuContext.get();
             if (!pipelinePromise) {
                 pipelinePromise = (async () => {
-                    const module = ctx.device.createShaderModule({ code, label });
-                    const info = await module.getCompilationInfo();
-                    const errors = info.messages.filter((m) => m.type === 'error');
+                    const { module, messages } = await createShaderModuleChecked(ctx.device, code, label);
+                    const errors = messages.filter((m) => m.type === 'error');
                     if (errors.length > 0) {
                         pipelinePromise = null;
                         // 实测(Dawn/Edge 151):lineNum 已是 1-based

package/dist/core/schema.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 类型化 schema 层:字段名与类型用 const 对象声明一次,三处受益——
+ *   ① TS 类型:SchemaInfer 给出精确的行类型,字段拼错/类型不匹配在编辑器就报红;
+ *   ② WGSL:wgslStruct() 由同一份声明生成 struct 代码,消灭"TS 字段表和
+ *      WGSL struct 各写一份"的漂移(名称/顺序由库保证一致);
+ *   ③ 缓冲:buffers() 生成与 elementKernel 绑定模型一致的逐字段 TypedBuffer。
+ * 诚实边界:用户 WGSL 函数体内部的拼写错误仍由 WGSL 编译期报错(带用户行号
+ * 映射)——完整 WGSL 类型检查是一个编译器工程,不在本层承诺范围内。
+ */
+import type { ScalarKind } from './layout.ts';
+import { Buffer } from './buffer.ts';
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface Vec4 {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+/** ScalarKind → TS 行类型(编译期映射,本层类型安全的根基) */
+export type KindOf<S extends ScalarKind> = S extends 'f32' | 'i32' | 'u32' ? number : S extends 'vec2f' | 'vec2i' | 'vec2u' ? Vec2 : S extends 'vec3f' ? Vec3 : S extends 'vec4f' ? Vec4 : never;
+/** schema 声明 → TS 行类型。字段名逐字保留,拼错即编译错误。 */
+export type SchemaInfer<F extends Record<string, ScalarKind>> = {
+    readonly [K in keyof F]: KindOf<F[K]>;
+};
+/**
+ * 单字段类型化缓冲:write/read 收发**行对象**(如 {x, y});原始 flat TypedArray
+ * 走 raw.write/raw.read(章程原则 1:逃生舱常开)。
+ */
+export declare class TypedBuffer<K extends ScalarKind> {
+    readonly raw: Buffer<K>;
+    readonly kind: K;
+    readonly length: number;
+    private constructor();
+    static create<K extends ScalarKind>(kind: K, length: number): Promise<TypedBuffer<K>>;
+    /** 行对象数组 → GPU */
+    write(rows: ReadonlyArray<KindOf<K>>): void;
+    /** GPU → 行对象数组 */
+    read(): Promise<Array<KindOf<K>>>;
+    destroy(): void;
+}
+/** 逐字段缓冲集合:key 逐字保留 schema 字段名;raws() 直接喂 elementKernel.run() */
+export type SchemaBuffers<F extends Record<string, ScalarKind>> = {
+    readonly [K in keyof F]: TypedBuffer<F[K]>;
+} & {
+    /** 传给 elementKernel 的 run()/初始绑定:字段名 → 底层缓冲 */
+    raws(): {
+        readonly [K in keyof F]: Buffer<F[K]>;
+    };
+    destroy(): void;
+};
+/** defineSchema 的返回值:同一份声明,喂类型、喂 WGSL、喂缓冲 */
+export interface Schema<F extends Record<string, ScalarKind>> {
+    /** 声明顺序即 WGSL struct 成员顺序;直接作 elementKernel 的 state */
+    readonly fields: F;
+    /**
+     * 生成 `struct <name> { ... }`。storage 语义下 vec3f 成员补 @size(16)
+     * (WGSL array 元素步长规则),与 CPU 侧 TYPES 步长一一对应,永不漂移。
+     */
+    wgslStruct(name: string, addressSpace?: 'storage' | 'uniform'): string;
+    /** 逐字段缓冲(与 elementKernel 的绑定模型一致) */
+    buffers(count: number): Promise<SchemaBuffers<F>>;
+}
+export declare function defineSchema<const F extends Record<string, ScalarKind>>(fields: F): Schema<F>;

package/dist/core/schema.js

@@ -0,0 +1,118 @@
+import { TYPES } from "./layout.js";
+import { Buffer } from "./buffer.js";
+import { ERR, UsageError } from "./errors.js";
+const COMPS = {
+    f32: 1, i32: 1, u32: 1, vec2f: 2, vec2i: 2, vec2u: 2, vec3f: 3, vec4f: 4,
+};
+const COMP_NAMES = ['x', 'y', 'z', 'w'];
+function rowToFlat(kind, row, index, out, base) {
+    const comps = COMPS[kind];
+    if (comps === 1) {
+        if (typeof row !== 'number' || !Number.isFinite(row)) {
+            throw new UsageError(ERR.BUFFER_WRITE, `schema row ${index} expects a finite number, got: ${typeof row}`);
+        }
+        out[base] = row;
+        return;
+    }
+    if (typeof row !== 'object' || row === null) {
+        throw new UsageError(ERR.BUFFER_WRITE, `schema row ${index} expects an object with ${comps} components, got: ${typeof row}`);
+    }
+    const rec = row;
+    for (let c = 0; c < comps; c++) {
+        const v = rec[COMP_NAMES[c]];
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            throw new UsageError(ERR.BUFFER_WRITE, `schema row ${index} component "${COMP_NAMES[c]}" must be a finite number, got: ${String(v)}`);
+        }
+        out[base + c] = v;
+    }
+}
+function flatToRow(kind, flat, i) {
+    const comps = COMPS[kind];
+    const base = i * comps;
+    if (comps === 1)
+        return flat[base];
+    if (comps === 2)
+        return { x: flat[base], y: flat[base + 1] };
+    if (comps === 3)
+        return { x: flat[base], y: flat[base + 1], z: flat[base + 2] };
+    return { x: flat[base], y: flat[base + 1], z: flat[base + 2], w: flat[base + 3] };
+}
+/**
+ * 单字段类型化缓冲:write/read 收发**行对象**(如 {x, y});原始 flat TypedArray
+ * 走 raw.write/raw.read(章程原则 1:逃生舱常开)。
+ */
+export class TypedBuffer {
+    raw;
+    kind;
+    length;
+    constructor(raw, kind) {
+        this.raw = raw;
+        this.kind = kind;
+        this.length = raw.length;
+    }
+    static async create(kind, length) {
+        return new TypedBuffer(await Buffer.create(kind, length), kind);
+    }
+    /** 行对象数组 → GPU */
+    write(rows) {
+        const comps = COMPS[this.kind];
+        const def = TYPES[this.kind];
+        const flat = (def.typed === 'Float32Array' ? new Float32Array(rows.length * comps)
+            : def.typed === 'Int32Array' ? new Int32Array(rows.length * comps)
+                : new Uint32Array(rows.length * comps));
+        for (let i = 0; i < rows.length; i++)
+            rowToFlat(this.kind, rows[i], i, flat, i * comps);
+        this.raw.write(flat);
+    }
+    /** GPU → 行对象数组 */
+    async read() {
+        const flat = await this.raw.read();
+        const rows = new Array(this.length);
+        for (let i = 0; i < this.length; i++)
+            rows[i] = flatToRow(this.kind, flat, i);
+        return rows;
+    }
+    destroy() {
+        this.raw.destroy();
+    }
+}
+export function defineSchema(fields) {
+    const keys = Object.keys(fields);
+    if (keys.length === 0) {
+        throw new UsageError(ERR.USAGE, 'defineSchema requires at least one field');
+    }
+    return {
+        fields,
+        wgslStruct(name, addressSpace = 'storage') {
+            if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(name)) {
+                throw new UsageError(ERR.USAGE, `wgslStruct name must be a valid WGSL identifier, got: "${name}"`);
+            }
+            const lines = keys.map((k) => {
+                const def = TYPES[fields[k]];
+                // vec3f 在数组元素语义下步长 16 —— 显式 @size 让 GPU/CPU 永不漂移
+                const pad = addressSpace === 'storage' && def.stride !== def.size ? ` @size(${def.stride})` : '';
+                return `  ${k}:${pad} ${def.wgsl},`;
+            });
+            return `struct ${name} {\n${lines.join('\n')}\n}`;
+        },
+        async buffers(count) {
+            const store = {};
+            for (const k of keys) {
+                store[k] = await TypedBuffer.create(fields[k], count);
+            }
+            const raws = () => {
+                const r = {};
+                for (const k of keys)
+                    r[k] = store[k].raw;
+                return r;
+            };
+            return Object.assign(store, {
+                raws,
+                destroy() {
+                    for (const k of keys)
+                        store[k].destroy();
+                },
+            });
+        },
+    };
+}

package/dist/core/shader.d.ts

@@ -0,0 +1,4 @@
+export declare function createShaderModuleChecked(device: GPUDevice, code: string, label: string): Promise<{
+    module: GPUShaderModule;
+    messages: readonly GPUCompilationMessage[];
+}>;

package/dist/core/shader.js

@@ -0,0 +1,38 @@
+/**
+ * 带去重与降级的 shader 编译检查。
+ *
+ * ① 去重:同一 device 上相同 code 的模块直接复用(GPUShaderModule 创建后
+ *    不可变,跨管线共享安全)。
+ *
+ * ② 降级:CI 的 SwiftShader 在页面 GPU 负载累积后,getCompilationInfo 会
+ *    对一切新模块抛 "Instance dropped"(OperationError,连唯一代码的首查
+ *    都失败)。此时返回 messages: [] 继续编译 —— 编译错误并不会被掩盖:
+ *    管线创建/首.dispatch 会触发 uncapturederror,各验证页都有监听。
+ *    健康环境(真 GPU / smoke 页)下查询照常工作,CompileError 行号映射
+ *    不受影响。
+ */
+const MODULE_CACHE = new WeakMap();
+export async function createShaderModuleChecked(device, code, label) {
+    let cache = MODULE_CACHE.get(device);
+    if (!cache) {
+        cache = new Map();
+        MODULE_CACHE.set(device, cache);
+    }
+    const hit = cache.get(code);
+    if (hit)
+        return hit;
+    const module = device.createShaderModule({ code, label });
+    let messages;
+    try {
+        messages = (await module.getCompilationInfo()).messages;
+    }
+    catch (e) {
+        console.warn(`[wgpu-kit] getCompilationInfo unavailable (${String(e?.message ?? e).slice(0, 60)}); skipping compile-info check for "${label}"`);
+        const result = { module, messages: [] };
+        cache.set(code, result);
+        return result;
+    }
+    const result = { module, messages };
+    cache.set(code, result);
+    return result;
+}

package/dist/index.d.ts

@@ -4,7 +4,10 @@ import { elementKernel, type ElementKernel, type ElementKernelSpec } from './cor
 import { PingPong } from './core/pingpong.ts';
 import { rawKernel } from './core/raw.ts';
 export { GpuContext, Buffer, elementKernel, PingPong, rawKernel };
+export { defineSchema, TypedBuffer, type Schema, type SchemaBuffers, type SchemaInfer, type KindOf, type Vec2, type Vec3, type Vec4 } from './core/schema.ts';
+export { definePack, registerPack, getPack, listPacks, type PackSim, type WgpuKitPack } from './core/pack.ts';
 export { particles, type ParticlesSim } from './packs/particles/index.ts';
+export { fieldsPack, type FlowSim, type FlowConfig } from './packs/fields/index.ts';
 export type { ElementKernel, ElementKernelSpec };
 export { TYPES, planUniform, packUniform, packUniformInto, type ScalarKind } from './core/layout.ts';
 export { WgpuKitError, WebGPUUnavailableError, CompileError, UsageError } from './core/errors.ts';

package/dist/index.js

@@ -5,7 +5,20 @@ import { PingPong } from "./core/pingpong.js";
 import { rawKernel } from "./core/raw.js";
 import { UsageError } from "./core/errors.js";
 export { GpuContext, Buffer, elementKernel, PingPong, rawKernel };
+export { defineSchema, TypedBuffer } from "./core/schema.js";
+export { definePack, registerPack, getPack, listPacks } from "./core/pack.js";
 // 主入口直达旗舰包:import { particles } from 'wgpu-kit' 开箱即用
 export { particles } from "./packs/particles/index.js";
+export { fieldsPack } from "./packs/fields/index.js";
 export { TYPES, planUniform, packUniform, packUniformInto } from "./core/layout.js";
 export { WgpuKitError, WebGPUUnavailableError, CompileError, UsageError } from "./core/errors.js";
+// 内置包进入注册表(第三方包用 registerPack 注册后同样可被 listPacks 枚举)
+import { registerPack } from "./core/pack.js";
+import { particles as _particles } from "./packs/particles/index.js";
+import { fieldsPack as _fieldsPack } from "./packs/fields/index.js";
+registerPack({
+    name: 'particles',
+    description: 'Particle-life physics (n2 / tiled / grid up to 200k+)',
+    create: (config) => _particles(config ?? {}),
+});
+registerPack(_fieldsPack);

package/dist/packs/fields/index.d.ts

@@ -1,3 +1,4 @@
+import { type PackSim } from '../../core/pack.ts';
 import { type Colormap } from '../life/map.ts';
 /**
  * fields 包:向量场平迹(flow)。粒子被解析向量场平流,沉积到带衰减的信息素图上,
@@ -15,13 +16,22 @@ export interface FlowConfig {
     seed?: string | number;
     colormap?: Colormap;
 }
-export interface FlowSim {
+export interface FlowSim extends PackSim {
     attach(canvas: HTMLCanvasElement): Promise<void>;
     tick(): void;
     stats(): {
         fps: number;
     };
+    /** 自检:信息素图应有结构(有限值、非零峰值)——verify harness 直接收集 */
+    probe(): Promise<{
+        finite: boolean;
+        trailMax: number;
+        trailMean: number;
+        frames: number;
+    }>;
     sampleTrail(): Promise<Float32Array>;
     destroy(): void;
 }
 export declare function flow(config?: FlowConfig): Promise<FlowSim>;
+/** fields 包的平台注册形态:第三方包与它长得一模一样(见 docs "Writing a pack") */
+export declare const fieldsPack: import("../../index.ts").WgpuKitPack<FlowConfig, FlowSim>;

package/dist/packs/fields/index.js

@@ -2,6 +2,8 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
+import { definePack } from "../../core/pack.js";
 import { MapRenderer } from "../life/map.js";
 import { mulberry32 } from "../particles/presets.js";
 const FIELD_FNS = {
@@ -79,9 +81,8 @@ export async function flow(config = {}) {
     device.queue.writeBuffer(diffuseUniform, 0, new Uint32Array([mapSize, mapSize]));
     device.queue.writeBuffer(diffuseUniform, 8, new Float32Array([1 - decay, 0]));
     const compile = async (code, label) => {
-        const m = device.createShaderModule({ code, label });
-        const info = await m.getCompilationInfo();
-        const errors = info.messages.filter((x) => x.type === 'error');
+        const { module: m, messages } = await createShaderModuleChecked(device, code, label);
+        const errors = messages.filter((x) => x.type === 'error');
         if (errors.length > 0)
             throw new CompileError(label, errors.map((x) => ({ line: x.lineNum, msg: x.message })), 0);
         return m;
@@ -151,6 +152,23 @@ export async function flow(config = {}) {
         },
         stats() { return { fps: lastFps }; },
         async sampleTrail() { return (await trail.current.t.read()); },
+        async probe() {
+            const t = (await trail.current.t.read());
+            let finite = true;
+            let maxv = 0;
+            let sum = 0;
+            for (let i = 0; i < t.length; i++) {
+                const v = t[i];
+                if (!Number.isFinite(v)) {
+                    finite = false;
+                    break;
+                }
+                if (v > maxv)
+                    maxv = v;
+                sum += v;
+            }
+            return { finite, trailMax: maxv, trailMean: sum / Math.max(t.length, 1), frames: frame };
+        },
         destroy() {
             posBuf.destroy();
             trail.destroy();
@@ -159,6 +177,12 @@ export async function flow(config = {}) {
         },
     };
 }
+/** fields 包的平台注册形态:第三方包与它长得一模一样(见 docs "Writing a pack") */
+export const fieldsPack = definePack({
+    name: 'fields',
+    description: 'Vector-field advection trails (vortex / curl / twin)',
+    create: (config) => flow(config ?? {}),
+});
 function advectWgsl(fieldFn, mapSize) {
     return /* wgsl */ `
 struct Params {

package/dist/packs/grid/index.js

@@ -1,6 +1,7 @@
 import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 const WG = 64;
 const SCAN = 256;
 const USIZE = 32;
@@ -34,9 +35,8 @@ export async function createNeighborGrid(config) {
     const cellFill = await Buffer.create('u32', cells);
     const order = await Buffer.create('u32', count);
     cellCount.write(new Uint32Array(cells));
-    const module = device.createShaderModule({ code: gridWgsl(), label: 'ngrid' });
-    const info = await module.getCompilationInfo();
-    const errors = info.messages.filter((m) => m.type === 'error');
+    const { module, messages } = await createShaderModuleChecked(device, gridWgsl(), 'ngrid');
+    const errors = messages.filter((m) => m.type === 'error');
     if (errors.length > 0)
         throw new CompileError('ngrid', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
     const pCounts = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_counts' } });

package/dist/packs/image/index.js

@@ -1,5 +1,6 @@
 import { GpuContext } from "../../core/context.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 const OPS = ['grayscale', 'invert', 'edge', 'blur', 'sharpen', 'brightness', 'contrast'];
 const OP_IDS = { grayscale: 0, invert: 1, edge: 2, blur: 3, sharpen: 4, brightness: 5, contrast: 6 };
 export async function applyImage(source, target, ops) {
@@ -34,9 +35,8 @@ export async function applyImage(source, target, ops) {
         });
         return t;
     };
-    const module = device.createShaderModule({ code: shader(), label: 'image-filters' });
-    const info = await module.getCompilationInfo();
-    const errors = info.messages.filter((m) => m.type === 'error');
+    const { module, messages } = await createShaderModuleChecked(device, shader(), 'image-filters');
+    const errors = messages.filter((m) => m.type === 'error');
     if (errors.length > 0)
         throw new CompileError('image-filters', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
     const pipeline = device.createRenderPipeline({

package/dist/packs/life/boids.js

@@ -2,6 +2,7 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 import { createNeighborGrid } from "../grid/index.js";
 import { mulberry32 } from "../particles/presets.js";
 const WG = 64;
@@ -47,9 +48,8 @@ export async function boids(config = {}) {
         device.queue.writeBuffer(uniform, 0, b);
     };
     writeUniform();
-    const module = device.createShaderModule({ code: boidsWgsl(size), label: 'boids' });
-    const info = await module.getCompilationInfo();
-    const errors = info.messages.filter((m) => m.type === 'error');
+    const { module, messages } = await createShaderModuleChecked(device, boidsWgsl(size), 'boids');
+    const errors = messages.filter((m) => m.type === 'error');
     if (errors.length > 0)
         throw new CompileError('boids', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
     const neighborGrid = await createNeighborGrid({ count: N, worldHalf: 1.0, cellSize: perception });

package/dist/packs/life/physarum.js

@@ -2,6 +2,7 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 import { MapRenderer } from "./map.js";
 import { mulberry32 } from "../particles/presets.js";
 const AWG = 32; // count(u32) pad(u32) + sensorAngle, sensorDist, turnAngle, step, deposit, worldHalf (f32×6) = 32
@@ -51,9 +52,8 @@ export async function physarum(config = {}) {
     // decay 写进 diffuse kernel 的第二个 uniform?并成 16B:w,h,decayFrac,pad
     device.queue.writeBuffer(diffuseUniform, 8, new Float32Array([1 - decay, 0]));
     const compile = async (code, label) => {
-        const m = device.createShaderModule({ code, label });
-        const info = await m.getCompilationInfo();
-        const errors = info.messages.filter((x) => x.type === 'error');
+        const { module: m, messages } = await createShaderModuleChecked(device, code, label);
+        const errors = messages.filter((x) => x.type === 'error');
         if (errors.length > 0)
             throw new CompileError(label, errors.map((x) => ({ line: x.lineNum, msg: x.message })), 0);
         return m;

package/dist/packs/life/turing.js

@@ -2,6 +2,7 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 import { MapRenderer } from "./map.js";
 import { mulberry32 } from "../particles/presets.js";
 const PRESETS = {
@@ -58,9 +59,8 @@ export async function turing(config = {}) {
         device.queue.writeBuffer(uniform, 0, buf);
     };
     writeUniform();
-    const module = device.createShaderModule({ code: updateWgsl(), label: 'turing-update' });
-    const info = await module.getCompilationInfo();
-    const errors = info.messages.filter((m) => m.type === 'error');
+    const { module, messages } = await createShaderModuleChecked(device, updateWgsl(), 'turing-update');
+    const errors = messages.filter((m) => m.type === 'error');
     if (errors.length > 0)
         throw new CompileError('turing-update', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
     const pipeline = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main' } });

package/dist/packs/particles/index.js

@@ -2,6 +2,7 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError, createComputePipelineChecked } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 import { resolveConfig } from "./config.js";
 import { mulberry32, resolveMatrix, hashSeed } from "./presets.js";
 import { simWgsl, WORKGROUP } from "./wgsl.js";
@@ -61,9 +62,8 @@ export async function particles(config = {}) {
     writeUniform(cfg.dt);
     // —— 着色器模块(编译错误 → 行号映射) ——
     const compile = async (code, label) => {
-        const module = device.createShaderModule({ code, label });
-        const info = await module.getCompilationInfo();
-        const errors = info.messages.filter((m) => m.type === 'error');
+        const { module, messages } = await createShaderModuleChecked(device, code, label);
+        const errors = messages.filter((m) => m.type === 'error');
         if (errors.length > 0)
             throw new CompileError(label, errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
         return module;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wgpu-kit",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Creative-coding GPU toolkit for the browser. 200k-particle physics at 120fps in 5 lines of code. WebGPU compute without the boilerplate.",
   "type": "module",
   "license": "MIT",