wgpu-kit 0.9.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wgpu-kit authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# wgpu-kit
+
+**Browser GPGPU middle layer. 200,000 particles at 142fps — in 5 lines of code.**
+All the WebGPU boilerplate — device, buffers, pipelines, dispatch, readbacks — wrapped into two simple API layers.
+
+[**API Reference**](docs/API.md) · [中文文档](README.zh-CN.md) · **[LIVE DEMO](https://nanfengw0w.github.io/wgpu-kit/)** · Changelog: [releases](https://github.com/nanfengw0w/wgpu-kit/releases)
+
+![wgpu-kit particle life](docs/assets/hero.gif)
+
+## Quick start
+
+```bash
+npm i wgpu-kit
+```
+
+**100,000 particles in 5 lines:**
+
+```ts
+import { particles } from 'wgpu-kit';
+
+const sim = await particles({ count: 100_000, forces: 'cells' });
+await sim.attach(canvas);
+function frame() { sim.tick(); requestAnimationFrame(frame); }
+frame();
+```
+
+**Custom GPU compute** — you only write the per-element function:
+
+```ts
+import { elementKernel, Buffer } from 'wgpu-kit';
+
+const pos = await Buffer.create('vec2f', 100_000);
+const vel = await Buffer.create('vec2f', 100_000);
+
+const integrate = elementKernel({
+  state:   { pos: 'vec2f' },
+  inputs:  { vel: 'vec2f' },
+  uniforms: { dt: 'f32' },
+  code: `
+    fn userFn(idx: u32, dt: f32) {
+      pos[idx] = (pos[idx] + vel[idx] * dt) * 0.99;
+    }
+  `,
+});
+await integrate.run({ pos, vel }, { dt: 0.02 });
+```
+
+Device management, buffer sizing, pipeline creation, double buffering,
+dispatch, readbacks, error line-mapping — all handled by the library.
+
+## Entry points
+
+| import | purpose |
+| --- | --- |
+| `wgpu-kit` | elementKernel core + Buffer / PingPong / rawKernel |
+| `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 |
+| `wgpu-kit/image` | GPU filter pipeline (blur/sharpen/edge/…) |
+| `wgpu-kit/react` | `<ParticleCanvas />` |
+| `wgpu-kit/three` | three.js snapshot interop |
+| `wgpu-kit/media` | canvas recording (webm/mp4) |
+| `wgpu-kit/vite` | WGSL kernel hot reload |
+
+![life quartet](docs/assets/life-quartet.png)
+
+*The life pack: Turing patterns / Physarum / Boids / Tentacles — [open the demo](https://nanfengw0w.github.io/wgpu-kit/life.html).*
+
+## Numbers (reproducible)
+
+| metric | value | environment |
+| --- | --- | --- |
+| particles end-to-end | 200,000 @ 142fps | RTX 4060 Laptop, playground |
+| particle compute (grid) | 131k @ 0.89ms/frame | headless bench |
+| 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 |
+
+## Three design rules
+
+1. **Level-2 works in 5 minutes, level-1 has no ceiling** — `rawKernel` and
+   native `GPUBuffer` escape hatches stay open;
+2. **Errors speak human** — WGSL compile failures map back to your line numbers;
+3. **Benchmarks are documentation** — every published number is reproducible;
+   gzip budgets are enforced by `npm run build`.
+
+## Support matrix
+
+| browser | status |
+| --- | --- |
+| Chrome / Edge 113+ (incl. headless) | ✅ all validation runs here (RTX 4060, D3D backend) |
+| Safari 18+ / Firefox | 🔶 should work with WebGPU enabled; untested — issues welcome |
+| WebGL2 / no WebGPU | ❌ no fallback (by design); `detect.html` can diagnose |
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,99 @@
+# wgpu-kit
+
+> **Browser GPGPU middle layer. 132,000 particles at 142fps — in 5 lines of code.**
+> 浏览器 GPGPU 中间层:WebGPU 计算的全套样板,打包成两层简单 API。
+
+**状态:公测就绪(v0.9.5)· 演示:[playground](playground/index.html) · [生命合集](playground/life.html) · [画廊](playground/gallery.html)**
+ · **[API 参考(学习文档)](docs/API.md)** · **[文件结构](docs/STRUCTURE.md)** · [基准](docs/benchmarks.md) · API 设计 · 验证日志 · 路线图 · [CHANGELOG](CHANGELOG.md)
+
+## Quick start
+
+```bash
+npm i wgpu-kit   # 首次发布前:git clone + npm run build
+```
+
+**5 行,10 万粒子**(领域包,开箱即用):
+
+```ts
+import { particles } from 'wgpu-kit';
+
+const sim = await particles({ count: 100_000, forces: 'cells' });
+await sim.attach(canvas);
+function frame() { sim.tick(); requestAnimationFrame(frame); }
+frame();
+```
+
+**自定义 GPU 计算**(kernel 核心,写"单个元素怎么变"就行):
+
+```ts
+import { elementKernel, Buffer } from 'wgpu-kit';
+
+const pos = await Buffer.create('vec2f', 100_000);
+const vel = await Buffer.create('vec2f', 100_000);
+
+const integrate = elementKernel({
+  state: { pos: 'vec2f' },
+  inputs: { vel: 'vec2f' },
+  uniforms: { dt: 'f32' },
+  code: `
+    fn userFn(idx: u32, dt: f32) {
+      pos[idx] = (pos[idx] + vel[idx] * dt) * 0.99;
+    }
+  `,
+});
+await integrate.run({ pos, vel }, { dt: 0.02 });
+```
+
+设备/缓冲/管线/绑定/dispatch/双缓冲/读回/错误行号映射——全部由库承担。
+
+## 包家族
+
+| 入口 | 一句话 |
+| --- | --- |
+| `wgpu-kit` | elementKernel 核心 + Buffer/PingPong/rawKernel |
+| `wgpu-kit/particles` | 粒子生命:力矩阵预设/随机宇宙、grid 邻域、热更新、快照分享 |
+| `wgpu-kit/life` | 人工生命:图灵斑图 / 粘菌 / Boids / 软体触手 |
+| `wgpu-kit/fields` | 向量场平迹(数据可视化) |
+| `wgpu-kit/image` | GPU 滤镜管线(blur/sharpen/edge/…) |
+| `wgpu-kit/react` | `<ParticleCanvas />` |
+| `wgpu-kit/three` | three.js 快照互通 |
+| `wgpu-kit/media` | 画布录制(一键产视频素材) |
+| `wgpu-kit/vite` | kernel 热重载插件(WGSL 改动毫秒级生效) |
+
+## 数字(可复现,非营销)
+
+| 指标 | 数值 | 环境 |
+| --- | --- | --- |
+| 粒子模拟(端到端) | **131,072 粒子 @ 142fps** | RTX 4060 Laptop,playground 实测 |
+| 粒子计算(纯 GPU) | grid@131k = **0.89 ms/帧** | 同上,headless 基准 |
+| 邻域算法对比 | grid 比 O(N²) tiling 快 **6.7×**@16k,近似 O(N) | 同会话基准 |
+| 库体积 | core gzip **5.34 kB**;+particles **10.27 kB** | gzip -c |
+
+完整数据与复现命令:开发仓库 benchmarks.md。基准方法学(含两次自我纠错)见验证日志 05。
+
+## 为什么
+
+浏览器里用 GPU,今天只有四条路:纯 JS(慢)、裸写 WebGPU(~150 行仪式代码)、three.js TSL(锁引擎)、gpu.js(WebGL 时代,停滞)。"**简单 + 快 + 引擎无关**"的专用 WebGPU 计算库是空位。完整竞品分析:docs/research.md。
+
+## 三条设计铁律
+
+1. **第二层 5 分钟出活,第一层不封顶**——`rawKernel` 与原生 `GPUBuffer` 逃生舱常开;
+2. **错误说人话**——WGSL 编译失败精确映射回你的代码行;
+3. **基准即文档**——所有宣传数字可复现,性能预算进 CI(`npm run build` 自动核对体积)。
+
+## 支持矩阵
+
+| 浏览器 | 状态 |
+| --- | --- |
+| Chrome / Edge 113+(含无头) | ✅ 本项目全部验证在此完成(RTX 4060,D3D 后端) |
+| Safari 18+ | 🔶 WebGPU 可用即应工作;未在本项目环境实测,issue 欢迎 |
+| Firefox | 🔶 同上 |
+| WebGL2 / 无 WebGPU | ❌ 不做降级(ADR-1);打开 [detect 页](playground/detect.html)可诊断 |
+
+## 项目方法论
+
+这不是一个"写完就算"的仓库:**每个阶段完成后,由无头浏览器在真实 GPU 上运行结构化探针验证,验证日志、路径对比、事故复盘全部入档**。从裸 WebGPU spike 到 13 万粒子,共 6 个阶段、7 个版本标签、38 项自动化探针。
+
+## 许可
+
+[MIT](LICENSE)

package/dist/core/buffer.d.ts

@@ -0,0 +1,21 @@
+import { type ScalarKind } from './layout.ts';
+/** TS 5.7+ 的 TypedArray 泛型:显式钉在 ArrayBuffer 上,兼容 WebGPU 的 GPUAllowSharedBufferSource */
+export type NumArray = Float32Array<ArrayBuffer> | Int32Array<ArrayBuffer> | Uint32Array<ArrayBuffer>;
+/**
+ * 显存数组的类型化封装。替用户做三件事:
+ * ① 算字节数与 usage;② write() 校验长度;③ read() 内置 staging buffer(mapAsync 陷阱全包掉)。
+ * `gpuBuffer` 原生句柄永远可取(章程原则 1:逃生舱常开)。
+ */
+export declare class Buffer<K extends ScalarKind = ScalarKind> {
+    #private;
+    readonly kind: K;
+    readonly length: number;
+    readonly gpuBuffer: GPUBuffer;
+    private constructor();
+    static create<K extends ScalarKind>(kind: K, length: number): Promise<Buffer<K>>;
+    /** 校验并写入(CPU → GPU) */
+    write(data: NumArray): void;
+    /** GPU → CPU:内部 staging buffer + mapAsync,mapAsync 的异步陷阱由库承担 */
+    read(): Promise<NumArray>;
+    destroy(): void;
+}

package/dist/core/context.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 设备上下文:全库单例,惰性申请 adapter/device。
+ * 峰值性能偏好;失败给人话报错;device lost 以 promise 形式暴露。
+ */
+export declare class GpuContext {
+    #private;
+    readonly device: GPUDevice;
+    readonly adapterInfo: string;
+    private constructor();
+    static get(): Promise<GpuContext>;
+    /** device lost 时 reject;调用方可 await 做清理/提示 */
+    get lost(): Promise<GPUDeviceLostInfo>;
+    /** 等待队列中已提交的全部 GPU 工作完成(测试/读回前同步用) */
+    sync(): Promise<void>;
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,20 @@
+/** 错误体系:所有错误说人话,给出定位与修复建议(章程原则 3)。 */
+export declare class WgpuKitError extends Error {
+    constructor(message: string);
+}
+/** 环境无 WebGPU / 拿不到 adapter。 */
+export declare class WebGPUUnavailableError extends WgpuKitError {
+    constructor(reason: string);
+}
+/** WGSL 编译错误,行号已映射回用户代码。 */
+export declare class CompileError extends WgpuKitError {
+    constructor(kernelName: string, messages: readonly {
+        line: number;
+        msg: string;
+    }[], userCodeOffset: number);
+}
+/** 调用方使用不当(缺资源/类型不匹配/长度不一致等)。 */
+export declare class UsageError extends WgpuKitError {
+}
+/** 创建 compute 管线并用 pushErrorScope 捕获异步校验错误(超限等),把"黑屏刷屏"变成显式报错 */
+export declare function createComputePipelineChecked(device: GPUDevice, module: GPUShaderModule, label: string, entryPoint?: string): Promise<GPUComputePipeline>;

package/dist/core/kernel.d.ts

@@ -0,0 +1,52 @@
+import { type ScalarKind, type UniformLayout } from './layout.ts';
+import { Buffer } from './buffer.ts';
+/**
+ * elementKernel —— wgpu-kit 的心脏。
+ *
+ * 用户只写"单个元素怎么变"的 WGSL 函数(第一个参数固定为 idx: u32,
+ * 之后按 uniforms 声明顺序接收 uniform 标量),库生成全部仪式:
+ * uniform struct + 对齐打包、storage 绑定、count 越界保护、
+ * workgroup/dispatch、bind group 缓存、编译错误行号映射回用户代码。
+ */
+export interface ElementKernelSpec {
+    /** 调试名,错误信息里出现 */
+    name?: string;
+    /** 读写字段(就地修改),如 { pos: 'vec2f' } */
+    state?: Record<string, ScalarKind>;
+    /** 只读字段,如 { vel: 'vec2f' } */
+    inputs?: Record<string, ScalarKind>;
+    /** uniform 标量(不允许叫 count,count 由库自动注入) */
+    uniforms?: Record<string, ScalarKind>;
+    /** workgroup 大小,默认 64 */
+    workgroupSize?: number;
+    /** 用户函数,如 `fn step(idx: u32, dt: f32) { ... }`(引用字段名直接访问数组) */
+    code: string;
+}
+export interface ElementKernel {
+    readonly name: string;
+    /** 生成的完整 WGSL(调试/单测用) */
+    readonly source: string;
+    readonly uniformLayout: UniformLayout;
+    readonly workgroupSize: number;
+    run(resources: Record<string, Buffer>, uniforms?: Record<string, number>): Promise<void>;
+    /** 热重载:替换用户函数并重建管线;编译失败时抛错且内核保持旧版 */
+    replace(code: string): Promise<void>;
+    destroy(): void;
+}
+interface NormalizedSpec {
+    name: string;
+    workgroupSize: number;
+    state: Array<readonly [string, ScalarKind]>;
+    inputs: Array<readonly [string, ScalarKind]>;
+    uniforms: Array<readonly [string, ScalarKind]>;
+    code: string;
+}
+/** 纯函数:规范校验 + WGSL 代码生成。单测直接覆盖,不碰 GPU。 */
+export declare function generateElementKernel(spec: ElementKernelSpec): {
+    normalized: NormalizedSpec;
+    source: string;
+    uniformLayout: UniformLayout;
+    userCodeLineOffset: number;
+};
+export declare function elementKernel(spec: ElementKernelSpec): ElementKernel;
+export {};

package/dist/core/layout.d.ts

@@ -0,0 +1,32 @@
+/** WGSL 类型布局表:尺寸、对齐、组件数、对应的 TypedArray。库替用户算字节数的根据。 */
+export type ScalarKind = 'f32' | 'i32' | 'u32' | 'vec2f' | 'vec2i' | 'vec2u' | 'vec3f' | 'vec4f';
+export interface TypeDef {
+    /** 字节数 */
+    readonly size: number;
+    /** 字节对齐(WGSL 规则:vec3 对齐到 16) */
+    readonly align: number;
+    /** 分量数 */
+    readonly comps: number;
+    readonly typed: 'Float32Array' | 'Int32Array' | 'Uint32Array';
+    readonly wgsl: string;
+}
+export declare const TYPES: Record<ScalarKind, TypeDef>;
+export declare function alignTo(offset: number, align: number): number;
+export interface UniformField {
+    readonly name: string;
+    readonly kind: ScalarKind;
+    /** 在 uniform struct 中的字节偏移(与 WGSL 自然对齐规则一致) */
+    readonly offset: number;
+}
+export interface UniformLayout {
+    readonly fields: readonly UniformField[];
+    /** 总字节数,向上取整到 16 的倍数(uniform 绑定安全尺寸) */
+    readonly size: number;
+}
+/**
+ * 按声明顺序规划 uniform 布局。声明顺序 = WGSL struct 成员顺序 = 用户函数参数顺序,
+ * 三者由库保证一致,不给用户对齐自由(对齐是库的事)。
+ */
+export declare function planUniform(entries: ReadonlyArray<readonly [string, ScalarKind]>): UniformLayout;
+/** 把标量值按布局写进 ArrayBuffer;缺失字段报错,多余字段忽略前给出字段清单便于排错 */
+export declare function packUniform(layout: UniformLayout, values: Readonly<Record<string, number>>): ArrayBuffer;

package/dist/core/pingpong.d.ts

@@ -0,0 +1,24 @@
+import { Buffer } from './buffer.ts';
+import { type ScalarKind } from './layout.ts';
+/**
+ * 双缓冲:模拟类 kernel 的绝对刚需(spike 中是 45 行仪式)。
+ * A/B 两组同构缓冲,读"当前侧"、写"另一侧",swap 一次完成帧间翻转。
+ * 泛型 K 保留字段名的字面量类型,Record 访问不会被 noUncheckedIndexedAccess 弄成 undefined。
+ */
+export declare class PingPong<K extends string> {
+    #private;
+    private constructor();
+    static create<K extends string>(kinds: Record<K, ScalarKind>, length: number): Promise<PingPong<K>>;
+    /** 当前帧的数据侧(渲染/读回用) */
+    get current(): Record<K, Buffer>;
+    /** 另一侧(kernel 写入目标) */
+    get other(): Record<K, Buffer>;
+    /** 帧末翻转 */
+    swap(): void;
+    /** 以 (写侧, 读侧) 调用 fn 后自动 swap 的语法糖 */
+    runWith(fn: (write: Record<K, Buffer>, read: Record<K, Buffer>) => Promise<void>): Promise<void>;
+    destroy(): void;
+    /** 克隆一份同构 PingPong(同字段同长度) */
+    clone(): Promise<PingPong<K>>;
+    get names(): readonly K[];
+}

package/dist/core/raw.d.ts

@@ -0,0 +1,9 @@
+/**
+ * rawKernel —— 逃生舱(章程原则 1)。
+ * 用户给完整 WGSL(自己写 binding 声明),库只负责管线与提交,不做任何加工。
+ */
+export interface RawKernel {
+    run(entries: GPUBindGroupEntry[], workgroups: number): Promise<void>;
+    destroy(): void;
+}
+export declare function rawKernel(code: string, entryPoint?: string, label?: string): RawKernel;