wgpu-kit 0.9.10 → 1.0.0

package/dist/index.js

@@ -1,484 +1,11 @@
-// src/core/errors.ts
-var WgpuKitError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = new.target.name;
-  }
-};
-var WebGPUUnavailableError = class extends WgpuKitError {
-  constructor(reason) {
-    super(
-      `\u5F53\u524D\u73AF\u5883\u4E0D\u53EF\u7528 WebGPU: ${reason}
-  \u6392\u67E5:\u2460 \u6D4F\u89C8\u5668\u9700 Chrome/Edge 113+ \u6216 Safari 18+;\u2461 \u65E0\u5934\u73AF\u5883\u9700\u5F00\u542F WebGPU;\u2462 \u68C0\u67E5 GPU \u9A71\u52A8\u4E0E\u786C\u4EF6\u52A0\u901F\u8BBE\u7F6E\u3002
-  \u53EF\u7528 navigator.gpu \u662F\u5426\u5B58\u5728\u5FEB\u901F\u5224\u65AD\u3002`
-    );
-  }
-};
-var CompileError = class extends WgpuKitError {
-  constructor(kernelName, messages, userCodeOffset) {
-    const mapped = messages.map((m) => {
-      const userLine = m.line - userCodeOffset;
-      const where = userLine > 0 ? `\u7528\u6237\u4EE3\u7801\u7B2C ${userLine} \u884C` : `\u751F\u6210\u4EE3\u7801\u7B2C ${m.line} \u884C(\u5E93\u7684\u95EE\u9898,\u6B22\u8FCE\u62A5 issue)`;
-      return `  ${where}: ${m.msg}`;
-    }).join("\n");
-    super(`kernel "${kernelName}" WGSL \u7F16\u8BD1\u5931\u8D25:
-${mapped}`);
-  }
-};
-var UsageError = class extends WgpuKitError {
-};
-
-// src/core/context.ts
-var GpuContext = class _GpuContext {
-  device;
-  adapterInfo;
-  constructor(device, adapterInfo) {
-    this.device = device;
-    this.adapterInfo = adapterInfo;
-  }
-  static #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 \u4E0D\u5B58\u5728");
-    }
-    const adapter = await navigator.gpu.requestAdapter({ powerPreference: "high-performance" });
-    if (!adapter) throw new WebGPUUnavailableError("requestAdapter() \u8FD4\u56DE null");
-    const info = adapter.info;
-    const label = info ? [info.vendor, info.architecture, info.description].filter(Boolean).join(" / ") || "unknown" : "unknown";
-    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();
-  }
-};
-
-// src/core/layout.ts
-var TYPES = {
-  f32: { size: 4, align: 4, comps: 1, typed: "Float32Array", wgsl: "f32" },
-  i32: { size: 4, align: 4, comps: 1, typed: "Int32Array", wgsl: "i32" },
-  u32: { size: 4, align: 4, comps: 1, typed: "Uint32Array", wgsl: "u32" },
-  vec2f: { size: 8, align: 8, comps: 2, typed: "Float32Array", wgsl: "vec2f" },
-  vec2i: { size: 8, align: 8, comps: 2, typed: "Int32Array", wgsl: "vec2i" },
-  vec2u: { size: 8, align: 8, comps: 2, typed: "Uint32Array", wgsl: "vec2u" },
-  vec3f: { size: 12, align: 16, comps: 3, typed: "Float32Array", wgsl: "vec3f" },
-  vec4f: { size: 16, align: 16, comps: 4, typed: "Float32Array", wgsl: "vec4f" }
-};
-function alignTo(offset, align) {
-  return Math.ceil(offset / align) * align;
-}
-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) };
-}
-var 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)
-};
-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 \u5B57\u6BB5 ${f.name} \u7684\u7C7B\u578B ${f.kind} \u6682\u4E0D\u652F\u6301(\u5F53\u524D\u4EC5\u652F\u6301\u6807\u91CF)`);
-    }
-    const v = values[f.name];
-    if (v === void 0) throw new Error(`\u7F3A\u5C11 uniform \u503C: ${f.name}`);
-    if (typeof v !== "number" || !Number.isFinite(v)) {
-      throw new Error(`uniform \u503C ${f.name} \u5FC5\u987B\u662F\u6709\u9650\u6570\u5B57,\u6536\u5230: ${String(v)}`);
-    }
-    pack(view, f.offset, v);
-  }
-  return buf;
-}
-
-// src/core/buffer.ts
-var TYPED_CTORS = {
-  Float32Array,
-  Int32Array,
-  Uint32Array
-};
-var Buffer = class _Buffer {
-  kind;
-  length;
-  gpuBuffer;
-  #ctx;
-  #byteLength;
-  #staging = null;
-  constructor(ctx, kind, length, gpuBuffer) {
-    this.#ctx = ctx;
-    this.kind = kind;
-    this.length = length;
-    this.gpuBuffer = gpuBuffer;
-    this.#byteLength = length * TYPES[kind].size;
-  }
-  static async create(kind, length) {
-    if (!Number.isInteger(length) || length <= 0) {
-      throw new UsageError(`Buffer \u957F\u5EA6\u5FC5\u987B\u662F\u6B63\u6574\u6570,\u6536\u5230: ${String(length)}`);
-    }
-    const def = TYPES[kind];
-    if (!def) throw new UsageError(`\u672A\u77E5\u7C7B\u578B "${String(kind)}",\u53EF\u7528: ${Object.keys(TYPES).join(", ")}`);
-    const ctx = await GpuContext.get();
-    const gpuBuffer = ctx.device.createBuffer({
-      size: length * def.size,
-      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
-      label: `wgpu-kit Buffer<${kind}>[${length}]`
-    });
-    return new _Buffer(ctx, kind, length, gpuBuffer);
-  }
-  /** 校验并写入(CPU → GPU) */
-  write(data) {
-    const ctor = TYPED_CTORS[TYPES[this.kind].typed];
-    if (!(data instanceof ctor)) {
-      throw new UsageError(`Buffer<${this.kind}>.write \u9700\u8981 ${TYPES[this.kind].typed},\u6536\u5230 ${data.constructor?.name ?? typeof data}`);
-    }
-    const expected = this.length * TYPES[this.kind].comps;
-    if (data.length !== expected) {
-      throw new UsageError(`Buffer<${this.kind}>[${this.length}].write \u9700\u8981 ${expected} \u4E2A\u5206\u91CF,\u6536\u5230 ${data.length}`);
-    }
-    this.#ctx.device.queue.writeBuffer(this.gpuBuffer, 0, data);
-  }
-  /** 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.typed === "Float32Array") return new Float32Array(ab);
-    if (def.typed === "Int32Array") return new Int32Array(ab);
-    return new Uint32Array(ab);
-  }
-  destroy() {
-    if (this.#staging) {
-      this.#staging.destroy();
-      this.#staging = null;
-    }
-    this.gpuBuffer.destroy();
-  }
-};
-
-// src/core/kernel.ts
-var RESERVED = /* @__PURE__ */ new Set(["count"]);
-var nextBufferId = 0;
-var bufferIds = /* @__PURE__ */ new WeakMap();
-function bufId(b) {
-  let id = bufferIds.get(b);
-  if (id === void 0) {
-    id = ++nextBufferId;
-    bufferIds.set(b, id);
-  }
-  return id;
-}
-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 \u5FC5\u987B\u5728 1..512,\u6536\u5230: ${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}" \u81F3\u5C11\u9700\u8981\u4E00\u4E2A state \u6216 inputs \u5B57\u6BB5`);
-  }
-  for (const [uName] of uniforms) {
-    if (RESERVED.has(uName)) throw new UsageError(`uniform \u540D "${uName}" \u662F\u4FDD\u7559\u540D(count \u7531\u5E93\u81EA\u52A8\u6CE8\u5165)`);
-  }
-  const seen = new Set([...state, ...inputs, ...uniforms].map(([n]) => n));
-  if (seen.size !== state.length + inputs.length + uniforms.length) {
-    throw new UsageError(`elementKernel "${name}" \u7684 state/inputs/uniforms \u5B58\u5728\u91CD\u540D\u5B57\u6BB5`);
-  }
-  if (typeof spec.code !== "string" || spec.code.trim().length === 0) {
-    throw new UsageError(`elementKernel "${name}" \u7F3A\u5C11 code(\u7528\u6237 WGSL \u51FD\u6570)`);
-  }
-  const uniformEntries = [...uniforms, ["count", "u32"]];
-  const uniformLayout = planUniform(uniformEntries);
-  const header = [];
-  header.push("// \u7531 wgpu-kit elementKernel \u751F\u6210");
-  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(", ");
-  header.push(`  userFn(idx${uniformArgs ? ", " + uniformArgs : ""});`);
-  header.push("}");
-  const userCodeLineOffset = header.length;
-  const source = [...header, spec.code].join("\n");
-  return {
-    normalized: { name, workgroupSize, state, inputs, uniforms, code: spec.code },
-    source,
-    uniformLayout,
-    userCodeLineOffset
-  };
-}
-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`;
-  let pipelinePromise = null;
-  const bindGroupCache = /* @__PURE__ */ 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 = {}) {
-      const ctx = await GpuContext.get();
-      const device = ctx.device;
-      const pipeline = await getPipeline();
-      const ordered = [];
-      for (const [key] of [...normalized.state, ...normalized.inputs]) {
-        const buf = resources[key];
-        if (!buf) throw new UsageError(`kernel "${normalized.name}".run \u7F3A\u5C11\u8D44\u6E90 "${key}"`);
-        const want = [...normalized.state, ...normalized.inputs].find(([n]) => n === key)?.[1];
-        if (buf.kind !== want) {
-          throw new UsageError(`\u8D44\u6E90 "${key}" \u7C7B\u578B\u4E0D\u5339\u914D: \u9700\u8981 ${want},\u6536\u5230 ${buf.kind}`);
-        }
-        ordered.push({ key, buffer: buf });
-      }
-      const count = ordered[0]?.buffer.length ?? 0;
-      for (const { key, buffer } of ordered) {
-        if (buffer.length !== count) {
-          throw new UsageError(`\u8D44\u6E90 "${key}" \u957F\u5EA6 ${buffer.length} \u4E0E "${ordered[0].key}" \u7684 ${count} \u4E0D\u4E00\u81F4`);
-        }
-      }
-      const uBytes = packUniform(uniformLayout, { ...uniforms, count });
-      if (!uniformBuffer) {
-        uniformBuffer = device.createBuffer({
-          size: uniformLayout.size,
-          usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-          label: uniformBufferName
-        });
-      }
-      device.queue.writeBuffer(uniformBuffer, 0, uBytes);
-      const cacheKey = ordered.map(({ key, buffer }) => `${key}:${bufId(buffer.gpuBuffer)}`).join("|");
-      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;
-    }
-  };
-}
-
-// src/core/pingpong.ts
-var PingPong = 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 \u81F3\u5C11\u9700\u8981\u4E00\u4E2A\u5B57\u6BB5");
-    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;
-  }
-};
-
-// src/core/raw.ts
-function rawKernel(code, entryPoint = "main", label = "rawKernel") {
-  if (typeof code !== "string" || code.trim().length === 0) throw new UsageError("rawKernel \u9700\u8981 WGSL \u4EE3\u7801");
-  let pipelinePromise = null;
-  return {
-    async run(entries, workgroups) {
-      if (!Number.isInteger(workgroups) || workgroups < 1) {
-        throw new UsageError(`rawKernel.run \u7684 workgroups \u5FC5\u987B\u662F\u6B63\u6574\u6570,\u6536\u5230 ${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;
-            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;
-    }
-  };
-}
-export {
-  Buffer,
-  CompileError,
-  GpuContext,
-  PingPong,
-  TYPES,
-  UsageError,
-  WebGPUUnavailableError,
-  WgpuKitError,
-  elementKernel,
-  packUniform,
-  planUniform,
-  rawKernel
-};
+import { GpuContext } from "./core/context.js";
+import { Buffer } from "./core/buffer.js";
+import { elementKernel } from "./core/kernel.js";
+import { PingPong } from "./core/pingpong.js";
+import { rawKernel } from "./core/raw.js";
+import { UsageError } from "./core/errors.js";
+export { GpuContext, Buffer, elementKernel, PingPong, rawKernel };
+// 主入口直达旗舰包:import { particles } from 'wgpu-kit' 开箱即用
+export { particles } from "./packs/particles/index.js";
+export { TYPES, planUniform, packUniform, packUniformInto } from "./core/layout.js";
+export { WgpuKitError, WebGPUUnavailableError, CompileError, UsageError } from "./core/errors.js";

package/dist/interop/three.js

@@ -0,0 +1,29 @@
+export function threePoints(sim, THREE, opts = {}) {
+    const { pos } = sim.buffers();
+    const count = pos.length;
+    const positions = new Float32Array(count * 3); // three 需要 vec3,z=0
+    const geometry = new THREE.BufferGeometry();
+    const attr = new THREE.BufferAttribute(positions, 3);
+    geometry.setAttribute('position', attr);
+    const material = new THREE.PointsMaterial({
+        size: opts.size ?? 0.015,
+        color: opts.color ?? 0x8fb4ff,
+        sizeAttenuation: true,
+    });
+    const points = new THREE.Points(geometry, material);
+    return {
+        points,
+        async update() {
+            const data = (await pos.read());
+            for (let i = 0; i < count; i++) {
+                positions[i * 3] = data[i * 2] ?? 0;
+                positions[i * 3 + 1] = data[i * 2 + 1] ?? 0;
+                positions[i * 3 + 2] = 0;
+            }
+            attr.needsUpdate = true;
+        },
+        dispose() {
+            sim.destroy();
+        },
+    };
+}

package/dist/media.js

@@ -0,0 +1,70 @@
+const CANDIDATES = [
+    // webm 在无头/软件编码环境下最可靠;mp4 的 isTypeSupported 可能"说行但编不动"
+    // (实测 headless Edge:mp4 协商成功但产物 0 字节),故排后
+    'video/webm;codecs=vp9',
+    'video/webm;codecs=vp8',
+    'video/webm',
+    'video/mp4;codecs=avc1.42E01E',
+    'video/mp4',
+];
+export function pickMime() {
+    if (typeof MediaRecorder === 'undefined')
+        return null;
+    for (const m of CANDIDATES) {
+        if (MediaRecorder.isTypeSupported(m))
+            return m;
+    }
+    return null;
+}
+export class CanvasRecorder {
+    #recorder = null;
+    #chunks = [];
+    #startedAt = 0;
+    #mime;
+    constructor() {
+        const mime = pickMime();
+        if (!mime)
+            throw new Error('当前环境不支持 MediaRecorder 录制(无可用编码)');
+        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('已在录制中');
+        const stream = canvas.captureStream(60);
+        this.#chunks = [];
+        this.#recorder = new MediaRecorder(stream, { mimeType: this.#mime, videoBitsPerSecond });
+        this.#recorder.ondataavailable = (e) => { if (e.data.size > 0)
+            this.#chunks.push(e.data); };
+        this.#startedAt = performance.now();
+        this.#recorder.start(250);
+    }
+    stop() {
+        return new Promise((ok, err) => {
+            const r = this.#recorder;
+            if (!r || r.state !== 'recording') {
+                err(new Error('没有进行中的录制'));
+                return;
+            }
+            r.onstop = () => {
+                const blob = new Blob(this.#chunks, { type: this.#mime });
+                this.#recorder = null;
+                if (blob.size === 0) {
+                    err(new Error(`录制产物为空(${this.#mime});编码器可能不可用,换浏览器或网络前重试`));
+                    return;
+                }
+                ok({ blob, mimeType: this.#mime, seconds: (performance.now() - this.#startedAt) / 1000, bytes: blob.size });
+            };
+            r.stop();
+        });
+    }
+}
+/** 触发浏览器下载(录完即得的最后一公里) */
+export function downloadBlob(blob, filename) {
+    const a = document.createElement('a');
+    a.href = URL.createObjectURL(blob);
+    a.download = filename;
+    a.click();
+    setTimeout(() => URL.revokeObjectURL(a.href), 5000);
+}

package/dist/observe.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 可观测性与健壮性助手(批次 2)。
+ * —— 评审指出的"最大产品级缺口":GPGPU 库却看不到"这帧 GPU 花了多少"。
+ */
+import { GpuContext } from './core/context.ts';
+/** 时间戳查询封装:测量一段 GPU 工作的真实耗时(毫秒)。
+ *  Chrome/Edge 支持 timestamp-query;不支持的浏览器 reject。 */
+export declare function timeGpu(fn: (ctx: GpuContext) => void | Promise<void>): Promise<number>;
+/** 设备诊断:注册错误/丢失回调;设备丢失时自动重建上下文并调用 onRebuild。
+ *  长跑页面(展览/大屏)的必需品。 */
+export declare function watchDevice(opts: {
+    onError?: (message: string, recoverable: boolean) => void;
+    onRebuild?: (ctx: GpuContext) => void;
+}): void;
+/** 推荐的画布 canvas 格式(一行助手的语义化封装)。 */
+export declare function preferredCanvasFormat(): GPUTextureFormat;
+/** 画布 resize(DPR 上限策略):宽高物理像素 = clientSize × min(dpr, cap)。
+ *  返回是否实际改变了尺寸(没变则无需重建)。 */
+export declare function resizeCanvas(canvas: HTMLCanvasElement, dprCap?: number): boolean;

package/dist/observe.js

@@ -0,0 +1,76 @@
+/**
+ * 可观测性与健壮性助手(批次 2)。
+ * —— 评审指出的"最大产品级缺口":GPGPU 库却看不到"这帧 GPU 花了多少"。
+ */
+import { GpuContext } from "./core/context.js";
+import { UsageError } from "./core/errors.js";
+/** 时间戳查询封装:测量一段 GPU 工作的真实耗时(毫秒)。
+ *  Chrome/Edge 支持 timestamp-query;不支持的浏览器 reject。 */
+export async function timeGpu(fn) {
+    const ctx = await GpuContext.get();
+    const device = ctx.device;
+    const featureOk = device.features.has('timestamp-query');
+    if (!featureOk)
+        throw new UsageError('timestamp-query 在当前设备不可用(需 Chrome/Edge + 支持时间戳的 GPU)');
+    const QUERY_POOL = 2;
+    const querySet = device.createQuerySet({ type: 'timestamp', count: QUERY_POOL });
+    const resolveBuf = device.createBuffer({
+        size: QUERY_POOL * 8,
+        usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
+    });
+    const readBuf = device.createBuffer({ size: QUERY_POOL * 8, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
+    // 新版 WebGPU 规范:时间戳通过 pass 的 timestampWrites 写入(无 encoder.writeTimestamp)
+    const enc = device.createCommandEncoder();
+    {
+        const p0 = enc.beginComputePass({ timestampWrites: { querySet, beginningOfPassWriteIndex: 0 } });
+        p0.end();
+    }
+    await fn(ctx);
+    {
+        const p1 = enc.beginComputePass({ timestampWrites: { querySet, beginningOfPassWriteIndex: 1 } });
+        p1.end();
+    }
+    enc.resolveQuerySet(querySet, 0, QUERY_POOL, resolveBuf, 0);
+    enc.copyBufferToBuffer(resolveBuf, 0, readBuf, 0, QUERY_POOL * 8);
+    device.queue.submit([enc.finish()]);
+    await readBuf.mapAsync(GPUMapMode.READ);
+    const times = new BigInt64Array(readBuf.getMappedRange().slice(0));
+    readBuf.unmap();
+    querySet.destroy();
+    resolveBuf.destroy();
+    readBuf.destroy();
+    // period = 1ns(按规范),换算毫秒
+    const deltaNs = Number(times[1] - times[0]);
+    return deltaNs / 1e6;
+}
+/** 设备诊断:注册错误/丢失回调;设备丢失时自动重建上下文并调用 onRebuild。
+ *  长跑页面(展览/大屏)的必需品。 */
+export function watchDevice(opts) {
+    void GpuContext.get().then((ctx) => {
+        ctx.device.addEventListener?.('uncapturederror', (e) => {
+            opts.onError?.(String(e.error?.message ?? e), true);
+        });
+        void ctx.lost.then((info) => {
+            opts.onError?.(`GPU device lost: ${info.reason}`, false);
+            // 丢失后重置单例,下一次 GpuContext.get() 走全新设备
+            GpuContext.resetForTests?.();
+            void GpuContext.get().then((fresh) => opts.onRebuild?.(fresh)).catch(() => undefined);
+        });
+    });
+}
+/** 推荐的画布 canvas 格式(一行助手的语义化封装)。 */
+export function preferredCanvasFormat() {
+    return navigator.gpu.getPreferredCanvasFormat();
+}
+/** 画布 resize(DPR 上限策略):宽高物理像素 = clientSize × min(dpr, cap)。
+ *  返回是否实际改变了尺寸(没变则无需重建)。 */
+export function resizeCanvas(canvas, dprCap = 2) {
+    const dpr = Math.min(window.devicePixelRatio || 1, dprCap);
+    const w = Math.max(1, Math.floor(canvas.clientWidth * dpr));
+    const h = Math.max(1, Math.floor(canvas.clientHeight * dpr));
+    if (canvas.width === w && canvas.height === h)
+        return false;
+    canvas.width = w;
+    canvas.height = h;
+    return true;
+}