wgpu-kit 1.1.0 → 1.1.2

package/dist/core/kernel.js

@@ -1,7 +1,8 @@
 import { planUniform, packUniformInto, TYPES } from "./layout.js";
 import { GpuContext } from "./context.js";
 import { Buffer } from "./buffer.js";
-import { CompileError, UsageError } from "./errors.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;
@@ -19,27 +20,46 @@ export function generateElementKernel(spec) {
     const name = spec.name ?? 'kernel';
     const workgroupSize = spec.workgroupSize ?? 64;
     if (!Number.isInteger(workgroupSize) || workgroupSize < 1 || workgroupSize > 512) {
-        throw new UsageError(`workgroupSize 必须在 1..512,收到: ${String(workgroupSize)}`);
+        throw new UsageError(ERR.WORKGROUP_SIZE, `workgroupSize must be in 1..512, got: ${String(workgroupSize)}`);
     }
     const state = Object.entries(spec.state ?? {});
     const inputs = Object.entries(spec.inputs ?? {});
     const uniforms = Object.entries(spec.uniforms ?? {});
     if (state.length + inputs.length === 0) {
-        throw new UsageError(`elementKernel "${name}" 至少需要一个 state 或 inputs 字段`);
+        throw new UsageError(ERR.RESOURCE_MISSING, `elementKernel "${name}" requires at least one state or inputs field`);
     }
     for (const [uName] of uniforms) {
         if (RESERVED.has(uName))
-            throw new UsageError(`uniform 名 "${uName}" 是保留名(count 由库自动注入)`);
+            throw new UsageError(ERR.USAGE, `uniform name "${uName}" is reserved (count is auto-injected by the library)`);
     }
     const seen = new Set([...state, ...inputs, ...uniforms].map(([n]) => n));
     if (seen.size !== state.length + inputs.length + uniforms.length) {
-        throw new UsageError(`elementKernel "${name}" 的 state/inputs/uniforms 存在重名字段`);
+        throw new UsageError(ERR.USAGE, `elementKernel "${name}" has duplicate field names across state/inputs/uniforms`);
     }
     if (typeof spec.code !== 'string' || spec.code.trim().length === 0) {
-        throw new UsageError(`elementKernel "${name}" 缺少 code(用户 WGSL 函数)`);
+        throw new UsageError(ERR.USAGE, `elementKernel "${name}" is missing code (user WGSL function)`);
     }
     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;
             }
         },
@@ -143,17 +165,17 @@ export function elementKernel(spec) {
                 const f = orderedFields[i];
                 const buf = resources[f.key];
                 if (!buf)
-                    throw new UsageError(`kernel "${normalized.name}".run 缺少资源 "${f.key}"`);
+                    throw new UsageError(ERR.RESOURCE_MISSING, `kernel "${normalized.name}".run is missing resource "${f.key}"`);
                 const want = expectedKinds.get(f.key);
                 if (buf.kind !== want) {
-                    throw new UsageError(`资源 "${f.key}" 类型不匹配: 需要 ${want},收到 ${buf.kind}`);
+                    throw new UsageError(ERR.RESOURCE_TYPE, `Resource "${f.key}" type mismatch: expected ${want}, got ${buf.kind}`);
                 }
                 if (count === -1) {
                     count = buf.length;
                     firstKey = f.key;
                 }
                 else if (buf.length !== count) {
-                    throw new UsageError(`资源 "${f.key}" 长度 ${buf.length} 与 "${firstKey}" 的 ${count} 不一致`);
+                    throw new UsageError(ERR.RESOURCE_LENGTH, `Resource "${f.key}" length ${buf.length} does not match "${firstKey}" length ${count}`);
                 }
                 ordered.push(buf);
             }
@@ -171,12 +193,21 @@ export function elementKernel(spec) {
             let cacheKey = 0;
             for (let i = 0; i < ordered.length; i++)
                 cacheKey = (cacheKey * 31 + bufId(ordered[i].gpuBuffer)) | 0;
-            let bg = bindGroupCache.get(cacheKey);
+            const ids = ordered.map((b) => bufId(b.gpuBuffer));
+            const cached = bindGroupCache.get(cacheKey);
+            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);
+                bindGroupCache.set(cacheKey, { bg, ids });
             }
             // —— 编码提交 ——
             const enc = device.createCommandEncoder();

package/dist/core/layout.js

@@ -1,3 +1,4 @@
+import { ERR, UsageError } from "./errors.js";
 export const TYPES = {
     f32: { size: 4, stride: 4, align: 4, comps: 1, typed: 'Float32Array', wgsl: 'f32' },
     i32: { size: 4, stride: 4, align: 4, comps: 1, typed: 'Int32Array', wgsl: 'i32' },
@@ -38,13 +39,13 @@ export function packUniform(layout, values) {
     for (const f of layout.fields) {
         const pack = PACKERS[f.kind];
         if (!pack) {
-            throw new Error(`uniform 字段 ${f.name} 的类型 ${f.kind} 暂不支持(当前仅支持标量)`);
+            throw new UsageError(ERR.UNIFORM_UNSUPPORTED, `Uniform field "${f.name}" has unsupported type "${f.kind}". Only scalars are currently supported.`);
         }
         const v = values[f.name];
         if (v === undefined)
-            throw new Error(`缺少 uniform 值: ${f.name}`);
+            throw new UsageError(ERR.UNIFORM_FIELD, `Missing uniform value for "${f.name}"`);
         if (typeof v !== 'number' || !Number.isFinite(v)) {
-            throw new Error(`uniform 值 ${f.name} 必须是有限数字,收到: ${String(v)}`);
+            throw new UsageError(ERR.UNIFORM_FIELD, `Uniform value for "${f.name}" must be a finite number, got: ${String(v)}`);
         }
         pack(view, f.offset, v);
     }
@@ -56,13 +57,13 @@ export function packUniformInto(target, layout, values) {
     for (const f of layout.fields) {
         const pack = PACKERS[f.kind];
         if (!pack) {
-            throw new Error(`uniform 字段 ${f.name} 的类型 ${f.kind} 暂不支持(当前仅支持标量)`);
+            throw new UsageError(ERR.UNIFORM_UNSUPPORTED, `Uniform field "${f.name}" has unsupported type "${f.kind}". Only scalars are currently supported.`);
         }
         const v = values[f.name];
         if (v === undefined)
-            throw new Error(`缺少 uniform 值: ${f.name}`);
+            throw new UsageError(ERR.UNIFORM_FIELD, `Missing uniform value for "${f.name}"`);
         if (typeof v !== 'number' || !Number.isFinite(v)) {
-            throw new Error(`uniform 值 ${f.name} 必须是有限数字,收到: ${String(v)}`);
+            throw new UsageError(ERR.UNIFORM_FIELD, `Uniform value for "${f.name}" must be a finite number, got: ${String(v)}`);
         }
         pack(view, f.offset, v);
     }

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/pingpong.js

@@ -20,7 +20,7 @@ export class PingPong {
     static async create(kinds, length) {
         const names = Object.keys(kinds);
         if (names.length === 0)
-            throw new Error('PingPong 至少需要一个字段');
+            throw new Error('PingPong requires at least one field');
         const make = async () => {
             const side = {};
             for (const name of names)

package/dist/core/raw.js

@@ -1,20 +1,20 @@
 import { GpuContext } from "./context.js";
-import { CompileError, UsageError } from "./errors.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('rawKernel 需要 WGSL 代码');
+        throw new UsageError(ERR.USAGE, 'rawKernel requires WGSL code');
     let pipelinePromise = null;
     return {
         async run(entries, workgroups) {
             if (!Number.isInteger(workgroups) || workgroups < 1) {
-                throw new UsageError(`rawKernel.run 的 workgroups 必须是正整数,收到 ${String(workgroups)}`);
+                throw new UsageError(ERR.USAGE, `rawKernel.run workgroups must be a positive integer, got ${String(workgroups)}`);
             }
             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/media.js

@@ -24,14 +24,14 @@ export class CanvasRecorder {
     constructor() {
         const mime = pickMime();
         if (!mime)
-            throw new Error('当前环境不支持 MediaRecorder 录制(无可用编码)');
+            throw new Error('MediaRecorder is not supported in this environment');
         this.#mime = mime;
     }
     get mimeType() { return this.#mime; }
     get recording() { return this.#recorder?.state === 'recording'; }
     start(canvas, videoBitsPerSecond = 12_000_000) {
         if (this.#recorder)
-            throw new Error('已在录制中');
+            throw new Error('Recording already in progress');
         const stream = canvas.captureStream(60);
         this.#chunks = [];
         this.#recorder = new MediaRecorder(stream, { mimeType: this.#mime, videoBitsPerSecond });
@@ -51,7 +51,7 @@ export class CanvasRecorder {
                 const blob = new Blob(this.#chunks, { type: this.#mime });
                 this.#recorder = null;
                 if (blob.size === 0) {
-                    err(new Error(`录制产物为空(${this.#mime});编码器可能不可用,换浏览器或网络前重试`));
+                    err(new Error(`Recording produced 0 bytes (${this.#mime}); encoder may be unavailable`));
                     return;
                 }
                 ok({ blob, mimeType: this.#mime, seconds: (performance.now() - this.#startedAt) / 1000, bytes: blob.size });

package/dist/observe.js

@@ -3,7 +3,7 @@
  * —— 评审指出的"最大产品级缺口":GPGPU 库却看不到"这帧 GPU 花了多少"。
  */
 import { GpuContext } from "./core/context.js";
-import { UsageError } from "./core/errors.js";
+import { ERR, UsageError } from "./core/errors.js";
 /** 时间戳查询封装:测量一段 GPU 工作的真实耗时(毫秒)。
  *  Chrome/Edge 支持 timestamp-query;不支持的浏览器 reject。 */
 export async function timeGpu(fn) {
@@ -11,7 +11,7 @@ export async function timeGpu(fn) {
     const device = ctx.device;
     const featureOk = device.features.has('timestamp-query');
     if (!featureOk)
-        throw new UsageError('timestamp-query 在当前设备不可用(需 Chrome/Edge + 支持时间戳的 GPU)');
+        throw new UsageError(ERR.TIMESTAMP_UNSUPPORTED, 'timestamp-query is not supported on this device (requires Chrome/Edge + a GPU with timestamp support)');
     const QUERY_POOL = 2;
     const querySet = device.createQuerySet({ type: 'timestamp', count: QUERY_POOL });
     const resolveBuf = device.createBuffer({

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>;