wgpu-kit 0.9.10

package/dist/media.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CanvasRecorder:零依赖的画布录制(MediaRecorder 封装)。
+ * 容器协商:mp4(h264)→ webm(vp9)→ webm,按浏览器能力自动选择。
+ * "用户替你生产传播素材"的飞轮从这里开始。
+ */
+export interface RecordingResult {
+    blob: Blob;
+    mimeType: string;
+    seconds: number;
+    bytes: number;
+}
+export declare function pickMime(): string | null;
+export declare class CanvasRecorder {
+    #private;
+    constructor();
+    get mimeType(): string;
+    get recording(): boolean;
+    start(canvas: HTMLCanvasElement, videoBitsPerSecond?: number): void;
+    stop(): Promise<RecordingResult>;
+}
+/** 触发浏览器下载(录完即得的最后一公里) */
+export declare function downloadBlob(blob: Blob, filename: string): void;

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

@@ -0,0 +1,27 @@
+import { type Colormap } from '../life/map.ts';
+/**
+ * fields 包:向量场平迹(flow)。粒子被解析向量场平流,沉积到带衰减的信息素图上,
+ * 流线自会浮现——数据可视化里"风场/流场"的标准画法。
+ * 复用 life/physarum 的沉积-扩散-上屏管线,把"三触须感知"换成"场采样"。
+ */
+export type FieldKind = 'vortex' | 'curl' | 'twin';
+export interface FlowConfig {
+    count?: number;
+    mapSize?: number;
+    field?: FieldKind;
+    speed?: number;
+    decay?: number;
+    deposit?: number;
+    seed?: string | number;
+    colormap?: Colormap;
+}
+export interface FlowSim {
+    attach(canvas: HTMLCanvasElement): Promise<void>;
+    tick(): void;
+    stats(): {
+        fps: number;
+    };
+    sampleTrail(): Promise<Float32Array>;
+    destroy(): void;
+}
+export declare function flow(config?: FlowConfig): Promise<FlowSim>;

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

@@ -0,0 +1,32 @@
+/**
+ * image 包:GPU 图像滤镜管线。source(WebGPU 纹理)→ 逐算子 ping-pong → 目标 canvas。
+ * 当初 Phase 0 推迟的卷积 spike 在这里正式落地。
+ */
+export type ImageOp = {
+    op: 'grayscale';
+} | {
+    op: 'invert';
+} | {
+    op: 'edge';
+    amount?: number;
+} | {
+    op: 'blur';
+    radius?: number;
+} | {
+    op: 'sharpen';
+    amount?: number;
+} | {
+    op: 'brightness';
+    value: number;
+} | {
+    op: 'contrast';
+    value: number;
+};
+export interface ApplyImageResult {
+    width: number;
+    height: number;
+    passes: number;
+    /** GPU 直读结果像素(RGBA,每行按 256B 对齐;headless 里 drawImage 会拿到空帧,断言必须走这里) */
+    readback(): Promise<Uint8Array>;
+}
+export declare function applyImage(source: HTMLImageElement | HTMLCanvasElement | ImageBitmap, target: HTMLCanvasElement, ops: ImageOp[]): Promise<ApplyImageResult>;

package/dist/packs/life/boids.d.ts

@@ -0,0 +1,28 @@
+import { Buffer } from '../../core/buffer.ts';
+/**
+ * Boids 鸟群:分离/对齐/聚集三条规则(Reynolds 1986),十万级个体靠 grid 邻域加速。
+ * 渲染为按速度方向旋转的三角,速度映射颜色。
+ */
+export interface BoidsConfig {
+    count?: number;
+    perception?: number;
+    maxSpeed?: number;
+    wSep?: number;
+    wAli?: number;
+    wCoh?: number;
+    size?: number;
+    seed?: string | number;
+}
+export interface BoidsSim {
+    attach(canvas: HTMLCanvasElement): Promise<void>;
+    tick(): void;
+    stats(): {
+        fps: number;
+    };
+    buffers(): {
+        pos: Buffer;
+        vel: Buffer;
+    };
+    destroy(): void;
+}
+export declare function boids(config?: BoidsConfig): Promise<BoidsSim>;

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

@@ -0,0 +1,9 @@
+/**
+ * life 包 —— 人工生命合集。每个模拟都是"简单规则 → 涌现复杂",
+ * 引擎与渲染管线与 particles 包同源,每个模拟都是一条可发布的视频素材。
+ */
+export { turing, type TuringSim, type TuringConfig, type TuringPreset } from './turing.ts';
+export { physarum, type PhysarumSim, type PhysarumConfig } from './physarum.ts';
+export { boids, type BoidsSim, type BoidsConfig } from './boids.ts';
+export { tentacles, type TentaclesSim, type TentaclesConfig } from './tentacles.ts';
+export type { Colormap } from './map.ts';

package/dist/packs/life/map.d.ts

@@ -0,0 +1,20 @@
+import { Buffer } from '../../core/buffer.ts';
+/**
+ * MapRenderer:把一张 f32 浓度图(storage buffer,W×H)画到全屏。
+ * life 包三个模拟(图灵/粘菌/流场)共用的"浓度图上屏"组件。
+ * colormap 在 wgsl 里按名字生成;maxV 做线性归一,gamma 提对比。
+ */
+export type Colormap = 'amber' | 'ice' | 'duotone' | 'mono';
+export declare function mapFragment(colormap: Colormap): string;
+export declare class MapRenderer {
+    #private;
+    private constructor();
+    static create(canvas: HTMLCanvasElement, opts: {
+        width: number;
+        height: number;
+        maxV: number;
+        gamma?: number;
+        colormap: Colormap;
+    }): Promise<MapRenderer>;
+    render(map: Buffer): void;
+}

package/dist/packs/life/physarum.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 粘菌(Physarum):每个智能体三触须感知信息素、转向、前进、沉积;
+ * 信息素每帧扩散+衰减。没有任何"网络"的设定,河流/菌丝网络自会长出来。
+ */
+export interface PhysarumConfig {
+    /** 智能体数,默认 100,000 */
+    agents?: number;
+    /** 信息素图边长(正方形),默认 1024 */
+    mapSize?: number;
+    sensorAngle?: number;
+    sensorDist?: number;
+    turnAngle?: number;
+    step?: number;
+    decay?: number;
+    seed?: string | number;
+    colormap?: 'amber' | 'ice' | 'duotone' | 'mono';
+}
+export interface PhysarumSim {
+    attach(canvas: HTMLCanvasElement): Promise<void>;
+    tick(): void;
+    stats(): {
+        fps: number;
+    };
+    /** 读回信息素图(验证用;1M 纹素,别每帧调) */
+    sampleTrail(): Promise<Float32Array>;
+    destroy(): void;
+}
+export declare function physarum(config?: PhysarumConfig): Promise<PhysarumSim>;

package/dist/packs/life/tentacles.d.ts

@@ -0,0 +1,29 @@
+import { Buffer } from '../../core/buffer.ts';
+/**
+ * 软体触手:Verlet 链。锚点沿利萨茹轨迹游动,链身靠"跟随约束"松弛,
+ * 重力 + 阻尼让触手甩出水母般的漂移感。
+ * 约束求解必须 ping-pong(读一侧写另一侧):原地读写会让相邻节点的
+ * 数据竞争沿链传播,实测残差放大 10 倍以上——这是本模拟的核心教训。
+ */
+export interface TentaclesConfig {
+    chains?: number;
+    segments?: number;
+    segLen?: number;
+    gravity?: number;
+    damping?: number;
+    iterations?: number;
+    thickness?: number;
+    colorCycle?: number;
+}
+export interface TentaclesSim {
+    attach(canvas: HTMLCanvasElement): Promise<void>;
+    tick(): void;
+    stats(): {
+        fps: number;
+    };
+    buffers(): {
+        pos: Buffer;
+    };
+    destroy(): void;
+}
+export declare function tentacles(config?: TentaclesConfig): Promise<TentaclesSim>;

package/dist/packs/life/turing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 图灵斑图(Gray-Scott 反应扩散):两种化学物质的反应 + 扩散,
+ * 自发长出珊瑚/细胞/斑纹——"复杂来自简单规则"的教科书案例。
+ * state 每纹素 vec2f(A, B);每帧多个迭代步让花纹快速演化。
+ */
+export interface TuringConfig {
+    /** 网格宽高(正方形),默认 512 */
+    size?: number;
+    /** 预设参数:coral 珊瑚 / mitosis 分裂 / spots 斑点 / waves 波纹 / custom */
+    preset?: TuringPreset;
+    /** 自定义 feed(0.01..0.08),preset 为 custom 时生效 */
+    feed?: number;
+    /** 自定义 kill(0.03..0.07) */
+    kill?: number;
+    /** 每帧迭代步数,默认 12 */
+    steps?: number;
+    seed?: string | number;
+    colormap?: 'duotone' | 'amber' | 'ice' | 'mono';
+}
+export type TuringPreset = 'coral' | 'mitosis' | 'spots' | 'waves' | 'custom';
+export interface TuringSim {
+    readonly config: {
+        size: number;
+        preset: TuringPreset;
+        feed: number;
+        kill: number;
+        steps: number;
+    };
+    attach(canvas: HTMLCanvasElement): Promise<void>;
+    tick(): void;
+    /** 喂入扰动:在随机位置撒一把 B(交互/救场用) */
+    sprinkle(count?: number): void;
+    stats(): {
+        fps: number;
+    };
+    /** 读回 B 通道缩略采样(验证/分析用) */
+    sampleB(): Promise<Float32Array>;
+    destroy(): void;
+}
+export declare function turing(config?: TuringConfig): Promise<TuringSim>;

package/dist/packs/particles/config.d.ts

@@ -0,0 +1,47 @@
+import { type ForceMatrix, type ForcePresetName } from './presets.ts';
+/** 粒子模拟的邻域算法路径(基准对比见 validation/05) */
+export type SimMode = 'n2' | 'tiled' | 'grid';
+export interface ParticlesConfig {
+    /** 粒子数(默认 8192;n2 模式建议 ≤ 20000) */
+    count?: number;
+    /** 力矩阵:预设名('cells'|'snakes'|'orbitals'|'viruses'|'random')或自定义 16 元数组 */
+    forces?: ForcePresetName | 'random' | ForceMatrix;
+    /** 邻域算法:'n2' | 'tiled'(默认)| 'grid' */
+    mode?: SimMode;
+    /** 着色:'species'(默认)| 'velocity' */
+    color?: 'species' | 'velocity';
+    /** 边界:'wrap'(默认)| 'clamp' */
+    bounds?: 'wrap' | 'clamp';
+    /** 种子(字符串或数字),决定初始分布与 random 矩阵 */
+    seed?: string | number;
+    /** 物理参数(全部可选,有默认值) */
+    rMax?: number;
+    beta?: number;
+    forceFactor?: number;
+    frictionHalfLife?: number;
+    dt?: number;
+    /** 点大小(canvas 像素单位的比例,默认 0.004;大规模下自动缩小) */
+    pointSize?: number;
+    /** 每粒子邻域候选上限(grid 模式;仅作极端抱团的保险丝,默认 32768 在支持密度内不触发——按格子顺序截断会引入方向偏差伪影) */
+    maxNeighbors?: number;
+}
+export interface ResolvedConfig {
+    count: number;
+    forces: ForceMatrix;
+    forcesName: string;
+    mode: SimMode;
+    color: 'species' | 'velocity';
+    bounds: 'wrap' | 'clamp';
+    seed: string;
+    seedHash: number;
+    rMax: number;
+    beta: number;
+    forceFactor: number;
+    friction: number;
+    dt: number;
+    pointSize: number;
+    maxNeighbors: number;
+}
+export declare function resolveConfig(config?: ParticlesConfig): ResolvedConfig;
+export type { ForceMatrix, ForcePresetName };
+export { FORCE_PRESETS, mulberry32, hashSeed, randomMatrix, resolveMatrix } from './presets.ts';

package/dist/packs/particles/grid.d.ts

@@ -0,0 +1,25 @@
+/**
+ * grid 模式(spatial hash / counting sort)的四个 kernel。
+ * 每帧在同一个 command encoder 里跑四遍:
+ *   ① counts  原子计数每格粒子数
+ *   ② scan    单 workgroup 分块前缀和(cellStart/cellFill),顺带把 cellCount 归零给下一帧
+ *   ③ scatter 按格散射出有序索引表 order
+ *   ④ force   与 tiled 相同的力计算,但邻域遍历改为 3×3 个 cell 的有序区间
+ * 相比 O(N²),复杂度 ≈ O(N · 邻域密度)——10 万粒子的大门。
+ */
+export declare const GRID_WORKGROUP = 64;
+export declare const SCAN_WORKGROUP = 256;
+/** cellOf:世界坐标 → 格子索引(世界固定 [-worldHalf, worldHalf],格宽 = 2*worldHalf/gridSize) */
+export declare const CELL_OF = "\nfn cellOf(p: vec2f) -> u32 {\n  let g = i32(params.gridSize);\n  let span = params.worldHalf * 2.0;\n  let cx = clamp(i32(floor((p.x + params.worldHalf) / span * f32(g))), 0, g - 1);\n  let cy = clamp(i32(floor((p.y + params.worldHalf) / span * f32(g))), 0, g - 1);\n  return u32(cy) * params.gridSize + u32(cx);\n}\n";
+export declare function gridCountsWgsl(): string;
+export declare function gridScanWgsl(): string;
+export declare function gridScatterWgsl(): string;
+/**
+ * grid 力核:拆成两趟以消除负载不均(v0.9.7 黑屏级卡顿的根治)。
+ * 抱团时单格可能挤几千粒子,"一个线程扫 9 格"会让重格子线程拖死整批;
+ * 拆成 (粒子 × 格子) 一线程后工作量均分,物理结果与单趟完全一致(仅求和顺序不同)。
+ *   ① main_force_cell:线程 = (粒子 i × 邻域格 c),把该格贡献写入 partial[i*9+c]
+ *   ② main_force_integrate:线程 = 粒子,汇总 9 份贡献并积分
+ * 同格候选数上限 maxCand(由 JS 侧传 maxNeighbors/9)仍是极端抱团的保险丝。
+ */
+export declare function gridForceWgsl(speciesCount: number): string;

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

@@ -0,0 +1,51 @@
+import { Buffer } from '../../core/buffer.ts';
+import { type ParticlesConfig, type ResolvedConfig } from './config.ts';
+import { type ForceMatrix, type ForcePresetName } from './presets.ts';
+/**
+ * particles(config) —— 粒子领域包(5 分钟出活的 Layer 2)。
+ *
+ * const sim = await particles({ count: 100_000, forces: 'cells' });
+ * await sim.attach(canvas);
+ * function frame() { sim.tick(); requestAnimationFrame(frame); }
+ */
+export interface ParticlesSim {
+    readonly config: ResolvedConfig;
+    /** 配置渲染目标;只调一次(tick 之前或之后均可) */
+    attach(canvas: HTMLCanvasElement): Promise<void>;
+    /** 推进一帧;dtMultiplier 便于暂停(0)/慢放(<1)/快放(>1) */
+    tick(dtMultiplier?: number): void;
+    /** 热更新力矩阵(预设名或自定义) */
+    setForces(forces: ForcePresetName | 'random' | ForceMatrix): void;
+    /** 热更新物理参数(rMax 变化会触发 grid 重建) */
+    setParams(params: {
+        rMax?: number;
+        beta?: number;
+        forceFactor?: number;
+        frictionHalfLife?: number;
+        dt?: number;
+    }): void;
+    /** 可序列化的当前配置(URL 分享用) */
+    snapshot(): string;
+    /** 运行统计(500ms 窗口的 fps;playground/harness 直接读) */
+    stats(): {
+        fps: number;
+        gpuErrors: number;
+    };
+    /** 调试:grid 模式内部缓冲(仅诊断用) */
+    debugGrid?(): {
+        partial: Buffer;
+        start: Buffer;
+        fill: Buffer;
+        sortedPos: Buffer;
+        sortedSp: Buffer;
+        order: Buffer;
+    };
+    /** 当前帧数据(interop/three 用) */
+    buffers(): {
+        pos: Buffer;
+        vel: Buffer;
+        species: Buffer;
+    };
+    destroy(): void;
+}
+export declare function particles(config?: ParticlesConfig): Promise<ParticlesSim>;

package/dist/packs/particles/presets.d.ts

@@ -0,0 +1,25 @@
+/** 粒子包的字段布局(species 独立成 u32 缓冲,方便按需着色) */
+export declare const PARTICLE_FIELDS: {
+    readonly pos: "vec2f";
+    readonly vel: "vec2f";
+    readonly species: "u32";
+};
+export type ForceMatrix = readonly [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number];
+/** 精选力矩阵(4×4,行=施加者,列=承受者;正值吸引)。调参原则:对角 0,正负平衡。 */
+export declare const FORCE_PRESETS: {
+    /** 经典细胞:小团簇 + 缓慢迁移(spike 验证过的矩阵) */
+    readonly cells: ForceMatrix;
+    /** 蛇形:链状结构与游动 */
+    readonly snakes: ForceMatrix;
+    /** 轨道:环带与漩涡感 */
+    readonly orbitals: ForceMatrix;
+    /** 病毒:捕食结构,红吃绿 */
+    readonly viruses: ForceMatrix;
+};
+export type ForcePresetName = keyof typeof FORCE_PRESETS;
+/** mulberry32:种子可复现(seed 支持字符串散列,URL 分享友好) */
+export declare function mulberry32(seed: number): () => number;
+export declare function hashSeed(seed: string): number;
+/** 随机力矩阵(从种子生成,保证可复现) */
+export declare function randomMatrix(seed: number): ForceMatrix;
+export declare function resolveMatrix(forces: ForcePresetName | 'random' | ForceMatrix, seed: number): ForceMatrix;

package/dist/packs/particles/render.d.ts

@@ -0,0 +1,20 @@
+import { Buffer } from '../../core/buffer.ts';
+/**
+ * 粒子渲染器:instanced quad + storage 只读直通(compute 产物零拷贝进 vertex 阶段)。
+ * 属于粒子包内部实现(不进 core);等第二、第三个包出现同类需求再考虑上提。
+ */
+export declare class ParticlesRenderer {
+    #private;
+    private constructor();
+    static create(canvas: HTMLCanvasElement, opts: {
+        count: number;
+        species: Buffer;
+        vel?: Buffer;
+        color: 'species' | 'velocity';
+        pointSize: number;
+        worldHalf: number;
+    }): Promise<ParticlesRenderer>;
+    /** 渲染一帧(pos 来自 PingPong 当前侧;可传入覆盖数量) */
+    render(pos: Buffer, vel?: Buffer | null, count?: number): void;
+    destroy(): void;
+}

package/dist/packs/particles/wgsl.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 粒子模拟 WGSL 生成器。
+ * mode 是"路径对比驱动设计"的落点:
+ *  - n2    每线程全量扫一遍:最简单,≤2 万粒子
+ *  - tiled workgroup 共享内存分块加载:全局读取减少 64×,数万粒子(S3 基准)
+ *  - grid  spatial hash 两遍:10 万+(S4)
+ */
+export declare const WORKGROUP = 64;
+export declare function simWgsl(mode: 'n2' | 'tiled', speciesCount: number): string;
+/** tiled 模式的 workgroup 共享内存声明 */
+export declare const TILE_DECLS = "\nvar<workgroup> tilePos: array<vec2f, 64>;\nvar<workgroup> tileSp: array<u32, 64>;\n";
+/** 渲染着色器:instanced quad + storage 只读直通(spike 验证的形态) */
+export declare function renderWgsl(speciesCount: number, colorMode: 'species' | 'velocity', pointSize: number): string;