wgpu-kit 0.9.10 → 1.0.0

package/README.md

@@ -16,7 +16,7 @@ npm i wgpu-kit
 **100,000 particles in 5 lines:**
 
 ```ts
-import { particles } from 'wgpu-kit';
+import { particles } from 'wgpu-kit';  // 或 'wgpu-kit/particles'
 
 const sim = await particles({ count: 100_000, forces: 'cells' });
 await sim.attach(canvas);
@@ -75,6 +75,13 @@ dispatch, readbacks, error line-mapping — all handled by the library.
 | neighborhood algorithms | grid ~O(N); 8.5× faster than brute force at 66k | same-session A/B |
 | bundle size | core gzip 5.5kB; +particles 10.3kB | gzip |
 
+## Verification
+
+41+ automated probes run on a real GPU via a headless Chromium harness
+(included under `tests/` + `scripts/verify.mjs`) — including a physics
+equivalence regression that fails if the neighborhood algorithms ever
+produce divergent structures.
+
 ## Three design rules
 
 1. **Level-2 works in 5 minutes, level-1 has no ceiling** — `rawKernel` and

package/dist/core/buffer.d.ts

@@ -13,7 +13,7 @@ export declare class Buffer<K extends ScalarKind = ScalarKind> {
     readonly gpuBuffer: GPUBuffer;
     private constructor();
     static create<K extends ScalarKind>(kind: K, length: number): Promise<Buffer<K>>;
-    /** 校验并写入(CPU → GPU) */
+    /** 校验并写入(CPU → GPU);vec3f 等 stride≠size 的类型自动补 padding */
     write(data: NumArray): void;
     /** GPU → CPU:内部 staging buffer + mapAsync,mapAsync 的异步陷阱由库承担 */
     read(): Promise<NumArray>;

package/dist/core/buffer.js

@@ -0,0 +1,109 @@
+import { TYPES } from "./layout.js";
+import { GpuContext } from "./context.js";
+import { UsageError } from "./errors.js";
+const TYPED_CTORS = {
+    Float32Array, Int32Array, Uint32Array,
+};
+/**
+ * 显存数组的类型化封装。替用户做三件事:
+ * ① 算字节数与 usage;② write() 校验长度;③ read() 内置 staging buffer(mapAsync 陷阱全包掉)。
+ * `gpuBuffer` 原生句柄永远可取(章程原则 1:逃生舱常开)。
+ */
+export class Buffer {
+    kind;
+    length;
+    gpuBuffer;
+    #ctx;
+    #byteLength;
+    #stride;
+    #staging = null;
+    constructor(ctx, kind, length, gpuBuffer) {
+        this.#ctx = ctx;
+        this.kind = kind;
+        this.length = length;
+        this.gpuBuffer = gpuBuffer;
+        this.#byteLength = length * TYPES[kind].stride;
+        this.#stride = TYPES[kind].stride;
+    }
+    static async create(kind, length) {
+        if (!Number.isInteger(length) || length <= 0) {
+            throw new UsageError(`Buffer 长度必须是正整数,收到: ${String(length)}`);
+        }
+        const def = TYPES[kind];
+        if (!def)
+            throw new UsageError(`未知类型 "${String(kind)}",可用: ${Object.keys(TYPES).join(', ')}`);
+        const ctx = await GpuContext.get();
+        const gpuBuffer = ctx.device.createBuffer({
+            size: length * def.stride,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+            label: `wgpu-kit Buffer<${kind}>[${length}]`,
+        });
+        return new Buffer(ctx, kind, length, gpuBuffer);
+    }
+    /** 校验并写入(CPU → GPU);vec3f 等 stride≠size 的类型自动补 padding */
+    write(data) {
+        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}`);
+        }
+        const expected = this.length * def.comps;
+        if (data.length !== expected) {
+            throw new UsageError(`Buffer<${this.kind}>[${this.length}].write 需要 ${expected} 个分量,收到 ${data.length}`);
+        }
+        if (def.stride === def.size || def.comps === 1) {
+            this.#ctx.device.queue.writeBuffer(this.gpuBuffer, 0, data);
+            return;
+        }
+        // stride ≠ size(vec3f):逐元素补 padding 到 GPU 布局
+        const comps = def.comps;
+        const per = def.stride / 4;
+        const gpu = new Float32Array(this.length * per);
+        for (let i = 0; i < this.length; i++) {
+            for (let c = 0; c < comps; c++)
+                gpu[i * per + c] = data[i * comps + c];
+        }
+        this.#ctx.device.queue.writeBuffer(this.gpuBuffer, 0, gpu);
+    }
+    /** GPU → CPU:内部 staging buffer + mapAsync,mapAsync 的异步陷阱由库承担 */
+    async read() {
+        const def = TYPES[this.kind];
+        if (!this.#staging) {
+            this.#staging = this.#ctx.device.createBuffer({
+                size: this.#byteLength,
+                usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+                label: `wgpu-kit staging[${this.length}]`,
+            });
+        }
+        const enc = this.#ctx.device.createCommandEncoder();
+        enc.copyBufferToBuffer(this.gpuBuffer, 0, this.#staging, 0, this.#byteLength);
+        this.#ctx.device.queue.submit([enc.finish()]);
+        await this.#staging.mapAsync(GPUMapMode.READ);
+        const ab = this.#staging.getMappedRange().slice(0);
+        this.#staging.unmap();
+        if (def.stride === def.size || def.comps === 1) {
+            if (def.typed === 'Float32Array')
+                return new Float32Array(ab);
+            if (def.typed === 'Int32Array')
+                return new Int32Array(ab);
+            return new Uint32Array(ab);
+        }
+        // stride ≠ size(vec3f):剥掉 GPU 布局的 padding
+        const comps = def.comps;
+        const per = def.stride / 4;
+        const src = new Float32Array(ab);
+        const out = new Float32Array(this.length * comps);
+        for (let i = 0; i < this.length; i++) {
+            for (let c = 0; c < comps; c++)
+                out[i * comps + c] = src[i * per + c];
+        }
+        return out;
+    }
+    destroy() {
+        if (this.#staging) {
+            this.#staging.destroy();
+            this.#staging = null;
+        }
+        this.gpuBuffer.destroy();
+    }
+}

package/dist/core/context.d.ts

@@ -7,6 +7,8 @@ export declare class GpuContext {
     readonly device: GPUDevice;
     readonly adapterInfo: string;
     private constructor();
+    /** 仅供设备丢失自动重建(observe.watchDevice)使用:重置单例 */
+    static resetForTests(): void;
     static get(): Promise<GpuContext>;
     /** device lost 时 reject;调用方可 await 做清理/提示 */
     get lost(): Promise<GPUDeviceLostInfo>;

package/dist/core/context.js

@@ -0,0 +1,62 @@
+import { WebGPUUnavailableError } from "./errors.js";
+/**
+ * 设备上下文:全库单例,惰性申请 adapter/device。
+ * 峰值性能偏好;失败给人话报错;device lost 以 promise 形式暴露。
+ */
+export class GpuContext {
+    device;
+    adapterInfo;
+    constructor(device, adapterInfo) {
+        this.device = device;
+        this.adapterInfo = adapterInfo;
+    }
+    static #singleton = null;
+    /** 仅供设备丢失自动重建(observe.watchDevice)使用:重置单例 */
+    static resetForTests() {
+        GpuContext.#singleton = null;
+    }
+    static get() {
+        if (!GpuContext.#singleton) {
+            GpuContext.#singleton = GpuContext.#create().catch((e) => {
+                GpuContext.#singleton = null; // 允许环境修复后重试
+                throw e;
+            });
+        }
+        return GpuContext.#singleton;
+    }
+    static async #create() {
+        if (typeof navigator === 'undefined' || !('gpu' in navigator) || !navigator.gpu) {
+            throw new WebGPUUnavailableError('navigator.gpu 不存在');
+        }
+        const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
+        if (!adapter)
+            throw new WebGPUUnavailableError('requestAdapter() 返回 null');
+        const info = adapter.info;
+        const label = info
+            ? [info.vendor, info.architecture, info.description].filter(Boolean).join(' / ') || 'unknown'
+            : 'unknown';
+        // 按适配器能力申请存储缓冲上限:grid 力核等大 binding 数内核需要 >8,
+        // 而默认上限是 8(有头真机会直接判管线无效——v0.9.5 黑屏事故的根因)
+        const requiredLimits = {};
+        const want = [
+            'maxStorageBuffersPerShaderStage',
+            'maxStorageBuffersInVertexStage',
+            'maxStorageBufferBindingSize',
+        ];
+        for (const key of want) {
+            const supported = adapter.limits[key];
+            if (typeof supported === 'number')
+                requiredLimits[key] = supported;
+        }
+        const device = await adapter.requestDevice({ label: 'wgpu-kit', requiredLimits });
+        return new GpuContext(device, label);
+    }
+    /** device lost 时 reject;调用方可 await 做清理/提示 */
+    get lost() {
+        return this.device.lost;
+    }
+    /** 等待队列中已提交的全部 GPU 工作完成(测试/读回前同步用) */
+    async sync() {
+        await this.device.queue.onSubmittedWorkDone();
+    }
+}

package/dist/core/errors.js

@@ -0,0 +1,42 @@
+/** 错误体系:所有错误说人话,给出定位与修复建议(章程原则 3)。 */
+export class WgpuKitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** 环境无 WebGPU / 拿不到 adapter。 */
+export class WebGPUUnavailableError extends WgpuKitError {
+    constructor(reason) {
+        super(`当前环境不可用 WebGPU: ${reason}\n` +
+            '  排查:① 浏览器需 Chrome/Edge 113+ 或 Safari 18+;② 无头环境需开启 WebGPU;③ 检查 GPU 驱动与硬件加速设置。\n' +
+            '  可用 navigator.gpu 是否存在快速判断。');
+    }
+}
+/** WGSL 编译错误,行号已映射回用户代码。 */
+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)`;
+            return `  ${where}: ${m.msg}`;
+        })
+            .join('\n');
+        super(`kernel "${kernelName}" WGSL 编译失败:\n${mapped}`);
+    }
+}
+/** 调用方使用不当(缺资源/类型不匹配/长度不一致等)。 */
+export class UsageError extends WgpuKitError {
+}
+/** 创建 compute 管线并用 pushErrorScope 捕获异步校验错误(超限等),把"黑屏刷屏"变成显式报错 */
+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 支持)`);
+    }
+    return pipeline;
+}

package/dist/core/kernel.js

@@ -0,0 +1,197 @@
+import { planUniform, packUniformInto, TYPES } from "./layout.js";
+import { GpuContext } from "./context.js";
+import { Buffer } from "./buffer.js";
+import { CompileError, UsageError } from "./errors.js";
+const RESERVED = new Set(['count']);
+/** GPUBuffer 的稳定数字身份(WeakMap 分配,用于 bind group 缓存键) */
+let nextBufferId = 0;
+const bufferIds = new WeakMap();
+function bufId(b) {
+    let id = bufferIds.get(b);
+    if (id === undefined) {
+        id = ++nextBufferId;
+        bufferIds.set(b, id);
+    }
+    return id;
+}
+/** 纯函数:规范校验 + WGSL 代码生成。单测直接覆盖,不碰 GPU。 */
+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)}`);
+    }
+    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 字段`);
+    }
+    for (const [uName] of uniforms) {
+        if (RESERVED.has(uName))
+            throw new UsageError(`uniform 名 "${uName}" 是保留名(count 由库自动注入)`);
+    }
+    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 存在重名字段`);
+    }
+    if (typeof spec.code !== 'string' || spec.code.trim().length === 0) {
+        throw new UsageError(`elementKernel "${name}" 缺少 code(用户 WGSL 函数)`);
+    }
+    const uniformEntries = [...uniforms, ['count', 'u32']];
+    const uniformLayout = planUniform(uniformEntries);
+    // —— 生成 WGSL:头部(声明) + main + 用户代码 ——
+    const header = [];
+    header.push('// 由 wgpu-kit elementKernel 生成');
+    header.push('struct Params {');
+    for (const [n, k] of uniformEntries)
+        header.push(`  ${n}: ${TYPES[k].wgsl},`);
+    header.push('};');
+    header.push('@group(0) @binding(0) var<uniform> params: Params;');
+    let binding = 1;
+    for (const [n, k] of state)
+        header.push(`@group(0) @binding(${binding++}) var<storage, read_write> ${n}: array<${TYPES[k].wgsl}>;`);
+    for (const [n, k] of inputs)
+        header.push(`@group(0) @binding(${binding++}) var<storage, read> ${n}: array<${TYPES[k].wgsl}>;`);
+    header.push('');
+    header.push(`@compute @workgroup_size(${workgroupSize})`);
+    header.push('fn main(@builtin(global_invocation_id) gid: vec3u) {');
+    header.push('  let idx = gid.x;');
+    header.push('  if (idx >= params.count) { return; }');
+    const uniformArgs = uniforms.map(([n]) => `params.${n}`).join(', ');
+    // 用户函数固定命名 userFn —— 唯一约定,杜绝调用名对不上的脆弱性
+    header.push(`  userFn(idx${uniformArgs ? ', ' + uniformArgs : ''});`);
+    header.push('}');
+    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 },
+        source,
+        uniformLayout,
+        userCodeLineOffset,
+    };
+}
+export function elementKernel(spec) {
+    const first = generateElementKernel(spec);
+    const uniformLayout = first.uniformLayout;
+    let normalized = first.normalized;
+    let source = first.source;
+    let userCodeLineOffset = first.userCodeLineOffset;
+    const uniformBufferName = `${normalized.name}:uniform`;
+    // 构造期预展开:稳态 run() 每帧零分配(评审:两次展开 + O(字段²) find + 字符串 key)
+    const orderedFields = [
+        ...normalized.state.map(([k, t]) => ({ key: k, kind: t })),
+        ...normalized.inputs.map(([k, t]) => ({ key: k, kind: t })),
+    ];
+    const expectedKinds = new Map(orderedFields.map((f) => [f.key, f.kind]));
+    const sharedPack = new ArrayBuffer(uniformLayout.size); // 复用打包缓冲(writeBuffer 会拷贝)
+    let pipelinePromise = null;
+    let cachedCtx = null; // 首帧后缓存为普通引用
+    const bindGroupCache = new Map();
+    let uniformBuffer = null;
+    const compilePipeline = async () => {
+        const ctx = await GpuContext.get();
+        const device = ctx.device;
+        const module = device.createShaderModule({ code: source, label: normalized.name });
+        // 捕获编译错误并映射行号
+        const info = await module.getCompilationInfo();
+        const errors = info.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);
+        }
+        return device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main' } });
+    };
+    async function getPipeline() {
+        if (!pipelinePromise) {
+            pipelinePromise = compilePipeline().catch((e) => { pipelinePromise = null; throw e; });
+        }
+        return pipelinePromise;
+    }
+    return {
+        get name() { return normalized.name; },
+        get source() { return source; },
+        get uniformLayout() { return first.uniformLayout; },
+        get workgroupSize() { return normalized.workgroupSize; },
+        async replace(code) {
+            const regen = generateElementKernel({ ...spec, code });
+            // 先编译后切换:新代码编译失败则保持旧版不动
+            const savedSource = source;
+            const savedOffset = userCodeLineOffset;
+            source = regen.source;
+            userCodeLineOffset = regen.userCodeLineOffset;
+            try {
+                const p = await compilePipeline();
+                pipelinePromise = Promise.resolve(p);
+                bindGroupCache.clear();
+            }
+            catch (e) {
+                source = savedSource;
+                userCodeLineOffset = savedOffset;
+                throw e;
+            }
+        },
+        async run(resources, uniforms = {}) {
+            if (!cachedCtx)
+                cachedCtx = await GpuContext.get();
+            const device = cachedCtx.device;
+            const pipeline = await getPipeline();
+            // —— 资源校验 + 有序收集(预展开清单,稳态零分配) ——
+            const ordered = [];
+            let count = -1;
+            let firstKey = '';
+            for (let i = 0; i < orderedFields.length; i++) {
+                const f = orderedFields[i];
+                const buf = resources[f.key];
+                if (!buf)
+                    throw new UsageError(`kernel "${normalized.name}".run 缺少资源 "${f.key}"`);
+                const want = expectedKinds.get(f.key);
+                if (buf.kind !== want) {
+                    throw new UsageError(`资源 "${f.key}" 类型不匹配: 需要 ${want},收到 ${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} 不一致`);
+                }
+                ordered.push(buf);
+            }
+            // —— uniform 打包上传 ——
+            packUniformInto(sharedPack, uniformLayout, { ...uniforms, count });
+            if (!uniformBuffer) {
+                uniformBuffer = device.createBuffer({
+                    size: uniformLayout.size,
+                    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                    label: uniformBufferName,
+                });
+            }
+            device.queue.writeBuffer(uniformBuffer, 0, sharedPack);
+            // —— bind group(按 buffer 身份缓存) ——
+            let cacheKey = 0;
+            for (let i = 0; i < ordered.length; i++)
+                cacheKey = (cacheKey * 31 + bufId(ordered[i].gpuBuffer)) | 0;
+            let bg = bindGroupCache.get(cacheKey);
+            if (!bg) {
+                const entries = [{ binding: 0, resource: { buffer: uniformBuffer } }];
+                ordered.forEach((buffer, i) => entries.push({ binding: i + 1, resource: { buffer: buffer.gpuBuffer } }));
+                bg = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries });
+                bindGroupCache.set(cacheKey, bg);
+            }
+            // —— 编码提交 ——
+            const enc = device.createCommandEncoder();
+            const pass = enc.beginComputePass();
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, bg);
+            pass.dispatchWorkgroups(Math.ceil(count / normalized.workgroupSize));
+            pass.end();
+            device.queue.submit([enc.finish()]);
+        },
+        destroy() {
+            pipelinePromise = null;
+            bindGroupCache.clear();
+            uniformBuffer?.destroy();
+            uniformBuffer = null;
+        },
+    };
+}

package/dist/core/layout.d.ts

@@ -1,8 +1,10 @@
 /** WGSL 类型布局表:尺寸、对齐、组件数、对应的 TypedArray。库替用户算字节数的根据。 */
 export type ScalarKind = 'f32' | 'i32' | 'u32' | 'vec2f' | 'vec2i' | 'vec2u' | 'vec3f' | 'vec4f';
 export interface TypeDef {
-    /** 字节数 */
+    /** 字节数(uniform/标量语义) */
     readonly size: number;
+    /** **storage 数组元素步长**(WGSL 规则:array<vec3f> 步长 16,与 size 12 不同) */
+    readonly stride: number;
     /** 字节对齐(WGSL 规则:vec3 对齐到 16) */
     readonly align: number;
     /** 分量数 */
@@ -30,3 +32,5 @@ export interface UniformLayout {
 export declare function planUniform(entries: ReadonlyArray<readonly [string, ScalarKind]>): UniformLayout;
 /** 把标量值按布局写进 ArrayBuffer;缺失字段报错,多余字段忽略前给出字段清单便于排错 */
 export declare function packUniform(layout: UniformLayout, values: Readonly<Record<string, number>>): ArrayBuffer;
+/** packUniform 的零分配变体:写入调用方提供的缓冲(每帧路径用,避免 new ArrayBuffer) */
+export declare function packUniformInto(target: ArrayBuffer, layout: UniformLayout, values: Readonly<Record<string, number>>): void;

package/dist/core/layout.js

@@ -0,0 +1,69 @@
+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' },
+    u32: { size: 4, stride: 4, align: 4, comps: 1, typed: 'Uint32Array', wgsl: 'u32' },
+    vec2f: { size: 8, stride: 8, align: 8, comps: 2, typed: 'Float32Array', wgsl: 'vec2f' },
+    vec2i: { size: 8, stride: 8, align: 8, comps: 2, typed: 'Int32Array', wgsl: 'vec2i' },
+    vec2u: { size: 8, stride: 8, align: 8, comps: 2, typed: 'Uint32Array', wgsl: 'vec2u' },
+    vec3f: { size: 12, stride: 16, align: 16, comps: 3, typed: 'Float32Array', wgsl: 'vec3f' },
+    vec4f: { size: 16, stride: 16, align: 16, comps: 4, typed: 'Float32Array', wgsl: 'vec4f' },
+};
+export function alignTo(offset, align) {
+    return Math.ceil(offset / align) * align;
+}
+/**
+ * 按声明顺序规划 uniform 布局。声明顺序 = WGSL struct 成员顺序 = 用户函数参数顺序,
+ * 三者由库保证一致,不给用户对齐自由(对齐是库的事)。
+ */
+export function planUniform(entries) {
+    const fields = [];
+    let cursor = 0;
+    for (const [name, kind] of entries) {
+        const def = TYPES[kind];
+        cursor = alignTo(cursor, def.align);
+        fields.push({ name, kind, offset: cursor });
+        cursor += def.size;
+    }
+    return { fields, size: alignTo(Math.max(cursor, 1), 16) };
+}
+const PACKERS = {
+    f32: (v, o, x) => v.setFloat32(o, x, true),
+    i32: (v, o, x) => v.setInt32(o, x, true),
+    u32: (v, o, x) => v.setUint32(o, x, true),
+};
+/** 把标量值按布局写进 ArrayBuffer;缺失字段报错,多余字段忽略前给出字段清单便于排错 */
+export function packUniform(layout, values) {
+    const buf = new ArrayBuffer(layout.size);
+    const view = new DataView(buf);
+    for (const f of layout.fields) {
+        const pack = PACKERS[f.kind];
+        if (!pack) {
+            throw new Error(`uniform 字段 ${f.name} 的类型 ${f.kind} 暂不支持(当前仅支持标量)`);
+        }
+        const v = values[f.name];
+        if (v === undefined)
+            throw new Error(`缺少 uniform 值: ${f.name}`);
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            throw new Error(`uniform 值 ${f.name} 必须是有限数字,收到: ${String(v)}`);
+        }
+        pack(view, f.offset, v);
+    }
+    return buf;
+}
+/** packUniform 的零分配变体:写入调用方提供的缓冲(每帧路径用,避免 new ArrayBuffer) */
+export function packUniformInto(target, layout, values) {
+    const view = new DataView(target);
+    for (const f of layout.fields) {
+        const pack = PACKERS[f.kind];
+        if (!pack) {
+            throw new Error(`uniform 字段 ${f.name} 的类型 ${f.kind} 暂不支持(当前仅支持标量)`);
+        }
+        const v = values[f.name];
+        if (v === undefined)
+            throw new Error(`缺少 uniform 值: ${f.name}`);
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            throw new Error(`uniform 值 ${f.name} 必须是有限数字,收到: ${String(v)}`);
+        }
+        pack(view, f.offset, v);
+    }
+}

package/dist/core/pingpong.js

@@ -0,0 +1,61 @@
+import { Buffer } from "./buffer.js";
+import {} from "./layout.js";
+/**
+ * 双缓冲:模拟类 kernel 的绝对刚需(spike 中是 45 行仪式)。
+ * A/B 两组同构缓冲,读"当前侧"、写"另一侧",swap 一次完成帧间翻转。
+ * 泛型 K 保留字段名的字面量类型,Record 访问不会被 noUncheckedIndexedAccess 弄成 undefined。
+ */
+export class PingPong {
+    #sides;
+    #names;
+    #length;
+    #kinds;
+    #index = 0;
+    constructor(names, kinds, length, a, b) {
+        this.#names = names;
+        this.#kinds = kinds;
+        this.#length = length;
+        this.#sides = [a, b];
+    }
+    static async create(kinds, length) {
+        const names = Object.keys(kinds);
+        if (names.length === 0)
+            throw new Error('PingPong 至少需要一个字段');
+        const make = async () => {
+            const side = {};
+            for (const name of names)
+                side[name] = await Buffer.create(kinds[name], length);
+            return side;
+        };
+        return new PingPong(names, kinds, length, await make(), await make());
+    }
+    /** 当前帧的数据侧(渲染/读回用) */
+    get current() {
+        return this.#sides[this.#index];
+    }
+    /** 另一侧(kernel 写入目标) */
+    get other() {
+        return this.#sides[1 - this.#index];
+    }
+    /** 帧末翻转 */
+    swap() {
+        this.#index = 1 - this.#index;
+    }
+    /** 以 (写侧, 读侧) 调用 fn 后自动 swap 的语法糖 */
+    async runWith(fn) {
+        await fn(this.other, this.current);
+        this.swap();
+    }
+    destroy() {
+        for (const side of this.#sides)
+            for (const b of Object.values(side))
+                b.destroy();
+    }
+    /** 克隆一份同构 PingPong(同字段同长度) */
+    async clone() {
+        return PingPong.create(this.#kinds, this.#length);
+    }
+    get names() {
+        return this.#names;
+    }
+}

package/dist/core/raw.js

@@ -0,0 +1,38 @@
+import { GpuContext } from "./context.js";
+import { CompileError, UsageError } from "./errors.js";
+export function rawKernel(code, entryPoint = 'main', label = 'rawKernel') {
+    if (typeof code !== 'string' || code.trim().length === 0)
+        throw new UsageError('rawKernel 需要 WGSL 代码');
+    let pipelinePromise = null;
+    return {
+        async run(entries, workgroups) {
+            if (!Number.isInteger(workgroups) || workgroups < 1) {
+                throw new UsageError(`rawKernel.run 的 workgroups 必须是正整数,收到 ${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');
+                    if (errors.length > 0) {
+                        pipelinePromise = null;
+                        // 实测(Dawn/Edge 151):lineNum 已是 1-based
+                        throw new CompileError(label, errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
+                    }
+                    return ctx.device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint } });
+                })();
+            }
+            const pipeline = await pipelinePromise;
+            const bg = ctx.device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries });
+            const enc = ctx.device.createCommandEncoder();
+            const pass = enc.beginComputePass();
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, bg);
+            pass.dispatchWorkgroups(workgroups);
+            pass.end();
+            ctx.device.queue.submit([enc.finish()]);
+        },
+        destroy() { pipelinePromise = null; },
+    };
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ 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 { particles, type ParticlesSim } from './packs/particles/index.ts';
 export type { ElementKernel, ElementKernelSpec };
-export { TYPES, planUniform, packUniform, type ScalarKind } from './core/layout.ts';
+export { TYPES, planUniform, packUniform, packUniformInto, type ScalarKind } from './core/layout.ts';
 export { WgpuKitError, WebGPUUnavailableError, CompileError, UsageError } from './core/errors.ts';