@lincyaw/addon-exec-webgpu 0.0.0-stage → 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @lincyaw/addon-exec-webgpu
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser's GPU: WGSL compute shaders, a Python bridge and jax-js, recorded in Chromium at build time.
+
+Part of [Presmium](https://github.com/Lincyaw/presmium), which compiles canonical lecture.json teaching documents into web pages, slides, Jupyter notebooks and narrated playback.
+
+## Install
+
+```sh
+pnpm add -D @lincyaw/addon-exec-webgpu
+```
+
+Add this package to `metadata.plugins` in the document's `lecture.json`.
+
+It is a Presmium plugin: its components work on the web page and in the slides. It needs `@lincyaw/cli` and the renderers in the same project, and declares the Presmium packages it shares with them as peer dependencies (Presmium 1.x).
+
+## What it provides
+
+- An executor for WGSL code in a run-panel component: WebGPU compute shaders run in the browser and can be recorded in Playwright's Chromium at build time; list it together with `@lincyaw/addon-exec`.
+- jax-js for JavaScript and TypeScript code, and the Python bridge `presmium_gpu`.
+- Named environments of `kind: webgpu`.
+
+## Documentation
+
+- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/locales/en/lecture.json) (Chinese: `site/guide/lecture.json`)
+- [Document contract](https://github.com/Lincyaw/presmium/blob/main/.agents/skills/presmium-author/references/document.md): normalized entities, parameters, states and shared validation
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@lincyaw/addon-exec-webgpu",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.1",
+  "description": "Presmium plugin: WGSL compute shaders and jax-js on the browser's GPU, recorded in Chromium at build time",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/addon-exec-webgpu"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/addon-exec-webgpu#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./domain": "./src/domain/index.ts",
+    "./client": "./src/client/index.ts",
+    "./presmium": "./src/node/presmium.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@jax-js/jax": "0.1.25",
+    "playwright-chromium": "1.64.1",
+    "yaml": "^2.9.1"
+  },
+  "peerDependencies": {
+    "@lincyaw/host": "^1.0.0-rc.1",
+    "@lincyaw/kernel": "^1.0.0-rc.1"
+  },
+  "devDependencies": {
+    "@lincyaw/cli": "1.0.0-rc.1",
+    "@lincyaw/host": "1.0.0-rc.1",
+    "@lincyaw/kernel": "1.0.0-rc.1"
+  }
 }

package/src/client/executor.ts

@@ -0,0 +1,81 @@
+import { currentLocale } from '@lincyaw/host'
+import { failedRun } from '@lincyaw/kernel'
+import type { Executor, RunResult } from '@lincyaw/kernel'
+import { computeRequest, isWgsl, MESSAGES, paramsSummary, programError, runResultOf } from '../domain/index.ts'
+import type { WorkerReply, WorkerRequest } from './protocol.ts'
+
+const STOP_GRACE_MS = 200
+
+export type WebgpuExecutor = Executor & {
+  dispose(): void
+}
+
+export function createWebgpuExecutor(options: { id: string, timeoutMs: number }): WebgpuExecutor {
+  const { id } = options
+  const running = new Map<Worker, () => void>()
+  let disposed = false
+  return {
+    id,
+    runsIn: 'browser',
+    supports: isWgsl,
+    params(lang) {
+      if (!isWgsl(lang)) return undefined
+      const text = MESSAGES[currentLocale()]
+      return { labels: text.labels, fields: ['buffers'], summary: args => paramsSummary(args, text) }
+    },
+    run(request, signal) {
+      const text = MESSAGES[currentLocale()]
+      if (disposed || signal?.aborted) return Promise.resolve(failedRun(id, text.cancelled))
+      const made = computeRequest(request.code, request.args, text)
+      if ('error' in made) return Promise.resolve(programError(id, made.error, 0))
+      return new Promise<RunResult>((resolve) => {
+        if (signal?.aborted) return resolve(failedRun(id, text.cancelled))
+        const worker = new Worker(new URL('./webgpu.worker.ts', import.meta.url), { type: 'module', name: 'presmium-webgpu' })
+        const started = performance.now()
+        const elapsed = () => Math.round(performance.now() - started)
+        const timeoutMs = request.timeoutMs ?? options.timeoutMs
+        let settled = false
+        let stopping: ReturnType<typeof setTimeout> | undefined
+        const end = () => {
+          clearTimeout(stopping)
+          running.delete(worker)
+          worker.terminate()
+        }
+        const finish = (result: RunResult) => {
+          if (settled) return
+          settled = true
+          clearTimeout(timer)
+          signal?.removeEventListener('abort', onAbort)
+          resolve(result)
+        }
+        const stop = (result: RunResult) => {
+          if (settled) return
+          finish(result)
+          worker.postMessage({ type: 'stop' } satisfies WorkerRequest)
+          stopping = setTimeout(end, STOP_GRACE_MS)
+        }
+        const timer = setTimeout(() => stop({ ...failedRun(id, text.timedOut(timeoutMs), elapsed()), timedOut: true }), timeoutMs)
+        const onAbort = () => stop(failedRun(id, text.cancelled, elapsed()))
+        signal?.addEventListener('abort', onAbort)
+        running.set(worker, () => {
+          finish(failedRun(id, text.cancelled, elapsed()))
+          end()
+        })
+        worker.onmessage = ({ data }: MessageEvent<WorkerReply>) => {
+          end()
+          if (data.type === 'done') finish(runResultOf(id, data.outcome, elapsed(), text))
+        }
+        worker.onerror = (event) => {
+          end()
+          finish(failedRun(id, text.crashed(event.message), elapsed()))
+        }
+        worker.postMessage({ type: 'run', request: made.request } satisfies WorkerRequest)
+      })
+    },
+    dispose() {
+      disposed = true
+      running.forEach(cancel => cancel())
+      running.clear()
+    },
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,3 @@
+export { createWebgpuExecutor } from './executor.ts'
+export type { WebgpuExecutor } from './executor.ts'
+export { execWebgpuPlugin } from './plugin.ts'

package/src/client/plugin.ts

@@ -0,0 +1,33 @@
+import { environmentExecutor, EXECUTOR } from '@lincyaw/kernel'
+import type { PluginDefinition, Unsubscribe } from '@lincyaw/kernel'
+import { version } from '../../package.json'
+import { DEFAULT_TIMEOUT_MS, EXEC_WEBGPU_ID, WEBGPU_EXECUTOR_ID, WEBGPU_KIND } from '../domain/index.ts'
+import { createWebgpuExecutor } from './executor.ts'
+import type { WebgpuExecutor } from './executor.ts'
+
+let executors: WebgpuExecutor[] = []
+let registrations: Unsubscribe[] = []
+
+function release(): void {
+  registrations.forEach(unregister => unregister())
+  executors.forEach(executor => executor.dispose())
+  registrations = []
+  executors = []
+}
+
+export const execWebgpuPlugin: PluginDefinition = {
+  manifest: { id: EXEC_WEBGPU_ID, name: { 'zh-CN': 'WebGPU 运行', en: 'WebGPU Runner' }, version, kernel: '^1.0.0', requires: [{ token: EXECUTOR }], capabilities: ['exec'] },
+  setup(ctx) {
+    release()
+    const router = ctx.get(EXECUTOR)
+    const named = Object.entries(ctx.environments ?? {}).filter(([, spec]) => spec.kind === WEBGPU_KIND).map(([name]) => environmentExecutor(name))
+    for (const id of [WEBGPU_EXECUTOR_ID, ...named]) {
+      const executor = createWebgpuExecutor({ id, timeoutMs: DEFAULT_TIMEOUT_MS })
+      executors.push(executor)
+      registrations.push(router.register(executor))
+    }
+  },
+  dispose: release,
+}
+
+export default execWebgpuPlugin

package/src/client/protocol.ts

@@ -0,0 +1,9 @@
+import type { ComputeOutcome, ComputeRequest } from '../domain/index.ts'
+
+export type WorkerRequest =
+  | { type: 'run', request: ComputeRequest }
+  | { type: 'stop' }
+
+export type WorkerReply =
+  | { type: 'done', outcome: ComputeOutcome }
+  | { type: 'stopped' }

package/src/client/webgpu.worker.ts

@@ -0,0 +1,17 @@
+/// <reference lib="webworker" />
+import { compute } from '../shared/gpu-compute.mjs'
+import type { WorkerReply, WorkerRequest } from './protocol.ts'
+
+declare const self: DedicatedWorkerGlobalScope
+
+let device: { destroy(): void } | undefined
+const reply = (message: WorkerReply) => self.postMessage(message)
+
+self.onmessage = async ({ data }: MessageEvent<WorkerRequest>) => {
+  if (data.type === 'stop') {
+    device?.destroy()
+    return reply({ type: 'stopped' })
+  }
+  const gpu = (self.navigator as WorkerNavigator & { gpu?: unknown }).gpu
+  reply({ type: 'done', outcome: await compute(gpu, data.request, { device: (d) => { device = d } }) })
+}

package/src/domain/compute.ts

@@ -0,0 +1,57 @@
+export type ScalarType = 'f32' | 'i32' | 'u32'
+
+export interface ComputeBuffer {
+  name: string
+  group: number
+  binding: number
+  usage: 'storage' | 'uniform'
+  access: 'read' | 'read_write'
+  type: ScalarType
+  length: number
+  data?: number[]
+  fill?: number
+  read: boolean
+}
+
+export interface ComputeRequest {
+  code: string
+  entry?: string
+  buffers: ComputeBuffer[]
+  dispatch: [number, number, number]
+  repeat: number
+  features: string[]
+}
+
+export interface AdapterDescription {
+  vendor: string
+  architecture: string
+  description: string
+  fallback: boolean
+}
+
+export interface BufferSummary {
+  name: string
+  type: ScalarType
+  length: number
+  head: number[]
+  tail: number[]
+  min: number
+  max: number
+  mean: number
+}
+
+export interface Timing {
+  ms: number
+  samples: number
+  source: 'gpu' | 'wall'
+}
+
+export type Unavailable = 'no-webgpu' | 'no-adapter' | 'feature' | 'limit' | 'device-lost'
+
+export type ComputeOutcome =
+  | { ok: true, buffers: BufferSummary[], timing: Timing, adapter: AdapterDescription }
+  | { ok: false, reason: Unavailable | 'shader' | 'validation', detail: string, adapter?: AdapterDescription }
+
+export function isUnavailable(reason: string): reason is Unavailable {
+  return ['no-webgpu', 'no-adapter', 'feature', 'limit', 'device-lost'].includes(reason)
+}

package/src/domain/config.ts

@@ -0,0 +1,23 @@
+import { languageId } from '@lincyaw/kernel'
+import type { EnvironmentSpec } from '@lincyaw/kernel'
+
+export const EXEC_WEBGPU_ID = 'presmium.execWebgpu'
+
+export const WEBGPU_EXECUTOR_ID = 'presmium.webgpu'
+
+export const WEBGPU_KIND = 'webgpu'
+
+export const DEFAULT_TIMEOUT_MS = 10_000
+
+export const LIMITS = { maxBytes: 128 * 1024 * 1024, maxRepeat: 1000 }
+
+export function isWgsl(lang: string): boolean {
+  return languageId(lang) === 'wgsl'
+}
+
+export type AdapterChoice = 'auto' | 'gpu' | 'swiftshader'
+
+export function adapterChoice(spec: EnvironmentSpec | undefined): AdapterChoice {
+  const value = spec?.adapter
+  return value === 'gpu' || value === 'swiftshader' ? value : 'auto'
+}

package/src/domain/index.ts

@@ -0,0 +1,9 @@
+export { isUnavailable } from './compute.ts'
+export type { AdapterDescription, BufferSummary, ComputeBuffer, ComputeOutcome, ComputeRequest, ScalarType, Timing, Unavailable } from './compute.ts'
+export { adapterChoice, DEFAULT_TIMEOUT_MS, EXEC_WEBGPU_ID, isWgsl, LIMITS, WEBGPU_EXECUTOR_ID, WEBGPU_KIND } from './config.ts'
+export type { AdapterChoice } from './config.ts'
+export { MESSAGES } from './messages.ts'
+export type { WebgpuMessages } from './messages.ts'
+export { computeRequest, paramsSummary, shaderBuffers } from './params.ts'
+export { programError, runResultOf } from './result.ts'
+export { adapterFingerprint, adapterName, bufferLine, failureText, formatNumber, summaryText } from './summary.ts'

package/src/domain/messages.ts

@@ -0,0 +1,69 @@
+import type { Locale } from '@lincyaw/kernel'
+
+const zhCN = {
+  noWebgpu: '浏览器没有 WebGPU',
+  noAdapter: '没有可用的 GPU 适配器',
+  missingFeature: (features: string) => `GPU 适配器缺少特性 ${features}`,
+  missingLimit: (detail: string) => `GPU 适配器的限制不够：${detail}`,
+  deviceLost: (detail: string) => `GPU 设备丢失${detail ? `：${detail}` : ''}`,
+  timedOut: (ms: number) => `GPU 运行超过 ${ms} ms，已销毁设备并停止`,
+  crashed: (error: string) => `GPU 运行出错：${error}`,
+  cancelled: '已取消',
+  shader: (detail: string) => `着色器有错误：\n${detail}`,
+  validation: (detail: string) => `WebGPU 报告错误：${detail}`,
+  notYaml: (name: string, error: string) => `:params: 中的 ${name} 不是合法的 YAML：${error}`,
+  unknownParam: (name: string) => `:params: 中的 ${name} 不是 buffers、dispatch、entry、repeat、features 之一`,
+  noBuffers: ':params: 要写 buffers：着色器中每个缓冲区的数据或大小，例如 {a: [1, 2], out: {size: 2}}',
+  bufferShape: (name: string) => `缓冲区 ${name} 要写成数字列表，或 {data, size, fill, type, read}`,
+  bufferSize: (name: string) => `缓冲区 ${name} 要有 data 或 size（值的个数）`,
+  noDeclaration: (name: string) => `着色器中没有名为 ${name} 的缓冲区（var<storage> 或 var<uniform>）`,
+  noBuffer: (name: string) => `着色器的缓冲区 ${name} 没有写在 :params: 的 buffers 中`,
+  unsupportedType: (name: string, type: string) => `缓冲区 ${name} 的类型 ${type} 不受支持（f32、i32、u32）`,
+  badDispatch: 'dispatch 要写成 1 到 3 个正整数（每个维度的工作组数）',
+  badRepeat: (max: number) => `repeat 要是 1 到 ${max} 的整数`,
+  badEntry: 'entry 要写成入口函数的名字',
+  badFeatures: 'features 要写成特性名的列表，例如 [shader-f16]',
+  tooLarge: (bytes: number, max: number) => `缓冲区共 ${bytes} 字节，超过规模限制 ${max} 字节`,
+  stats: (min: string, max: string, mean: string) => `最小 ${min}，最大 ${max}，平均 ${mean}`,
+  time: (ms: string, samples: number, gpu: boolean, emulated: boolean) =>
+    `计时：每次派发 ${ms} ms（${[samples > 1 ? `${samples} 次的中位数` : '', gpu ? 'GPU 时间戳' : '挂钟时间', emulated ? 'CPU 模拟' : ''].filter(Boolean).join('；')}）`,
+  adapter: (name: string, fallback: boolean) => `适配器：${name}${fallback ? '（回退适配器）' : ''}`,
+  labels: { buffers: '缓冲区', dispatch: '工作组数', entry: '入口函数', repeat: '重复次数', features: '所需特性' } as Record<string, string>,
+  values: (count: number) => `${count} 个值`,
+}
+
+export type WebgpuMessages = typeof zhCN
+
+const en: WebgpuMessages = {
+  noWebgpu: 'This browser has no WebGPU',
+  noAdapter: 'No GPU adapter is available',
+  missingFeature: features => `The GPU adapter lacks the feature ${features}`,
+  missingLimit: detail => `The GPU adapter’s limits are too low: ${detail}`,
+  deviceLost: detail => `The GPU device was lost${detail ? `: ${detail}` : ''}`,
+  timedOut: ms => `The GPU ran over ${ms} ms; the device was destroyed and the run stopped`,
+  crashed: error => `The GPU run failed: ${error}`,
+  cancelled: 'Canceled',
+  shader: detail => `The shader has errors:\n${detail}`,
+  validation: detail => `WebGPU reported an error: ${detail}`,
+  notYaml: (name, error) => `${name} in :params: is not valid YAML: ${error}`,
+  unknownParam: name => `${name} in :params: is not one of buffers, dispatch, entry, repeat, features`,
+  noBuffers: ':params: needs buffers: the data or size of each buffer of the shader, e.g. {a: [1, 2], out: {size: 2}}',
+  bufferShape: name => `The buffer ${name} is a list of numbers, or {data, size, fill, type, read}`,
+  bufferSize: name => `The buffer ${name} needs data or size (its number of values)`,
+  noDeclaration: name => `The shader has no buffer named ${name} (var<storage> or var<uniform>)`,
+  noBuffer: name => `The shader’s buffer ${name} is not in the buffers of :params:`,
+  unsupportedType: (name, type) => `The type ${type} of the buffer ${name} is not supported (f32, i32, u32)`,
+  badDispatch: 'dispatch is 1 to 3 positive integers (workgroups in each dimension)',
+  badRepeat: max => `repeat is an integer from 1 to ${max}`,
+  badEntry: 'entry is the name of the entry point',
+  badFeatures: 'features is a list of feature names, e.g. [shader-f16]',
+  tooLarge: (bytes, max) => `The buffers take ${bytes} bytes, over the scale limit of ${max} bytes`,
+  stats: (min, max, mean) => `min ${min}, max ${max}, mean ${mean}`,
+  time: (ms, samples, gpu, emulated) =>
+    `time: ${ms} ms per dispatch (${[samples > 1 ? `median of ${samples}` : '', gpu ? 'GPU timestamps' : 'wall clock', emulated ? 'CPU emulation' : ''].filter(Boolean).join('; ')})`,
+  adapter: (name, fallback) => `adapter: ${name}${fallback ? ' (fallback adapter)' : ''}`,
+  labels: { buffers: 'Buffer', dispatch: 'Workgroups', entry: 'Entry point', repeat: 'Repeat', features: 'Features' },
+  values: count => `${count} value${count === 1 ? '' : 's'}`,
+}
+
+export const MESSAGES: Record<Locale, WebgpuMessages> = { 'zh-CN': zhCN, en }

package/src/domain/params.ts

@@ -0,0 +1,151 @@
+import { isRecord } from '@lincyaw/kernel'
+import { parse } from 'yaml'
+import type { ComputeBuffer, ComputeRequest, ScalarType } from './compute.ts'
+import { LIMITS } from './config.ts'
+import type { WebgpuMessages } from './messages.ts'
+
+const KEYS = ['buffers', 'dispatch', 'entry', 'repeat', 'features']
+const TYPES = ['f32', 'i32', 'u32']
+const DECLARATION = /((?:@\s*\w+\s*(?:\([^)]*\))?\s*)+)var\s*<\s*(storage|uniform)\s*(?:,\s*(read_write|read))?\s*>\s*([A-Za-z_]\w*)\s*:\s*([^;]+);/g
+const SHORTHAND: Record<string, string> = { f: 'f32', i: 'i32', u: 'u32', h: 'f16' }
+
+interface Declaration {
+  name: string
+  group: number
+  binding: number
+  usage: 'storage' | 'uniform'
+  access: 'read' | 'read_write'
+  scalar?: string
+}
+
+/** The buffers the shader declares (`var<storage>`, `var<uniform>`), with their group, binding, access and scalar type. */
+export function shaderBuffers(code: string): Declaration[] {
+  const source = code.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '')
+  return [...source.matchAll(DECLARATION)].map(([, attributes, space, access, name, type]) => {
+    const attribute = (key: string) => Number(new RegExp(`@\\s*${key}\\s*\\(\\s*(\\d+)\\s*\\)`).exec(attributes!)?.[1] ?? 0)
+    const scalars = new Set([
+      ...[...type!.matchAll(/\b(f32|i32|u32|f16)\b/g)].map(m => m[1]!),
+      ...[...type!.matchAll(/\b(?:vec[234]|mat[234]x[234])([fiuh])\b/g)].map(m => SHORTHAND[m[1]!]!),
+    ])
+    return {
+      name: name!,
+      group: attribute('group'),
+      binding: attribute('binding'),
+      usage: space as 'storage' | 'uniform',
+      access: space === 'storage' && access === 'read_write' ? 'read_write' : 'read',
+      scalar: scalars.size === 1 ? [...scalars][0] : undefined,
+    }
+  })
+}
+
+const isNumber = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
+const positive = (value: unknown, max = Infinity): value is number => Number.isInteger(value) && (value as number) >= 1 && (value as number) <= max
+
+// The shared gpu-compute.mjs computes the same sizes; it runs alone in the recording's page and cannot import this.
+function bytes(buffer: Pick<ComputeBuffer, 'length' | 'usage'>): number {
+  const size = Math.max(4, buffer.length * 4)
+  return buffer.usage === 'uniform' ? Math.ceil(size / 16) * 16 : size
+}
+
+function buffer(declaration: Declaration, spec: unknown, text: WebgpuMessages): ComputeBuffer | string {
+  const { name } = declaration
+  const fields = Array.isArray(spec) ? { data: spec } : spec
+  if (!isRecord(fields)) return text.bufferShape(name)
+  const { data, size, fill, type, read } = fields
+  if (data !== undefined && !(Array.isArray(data) && data.every(isNumber))) return text.bufferShape(name)
+  if (size !== undefined && !positive(size)) return text.bufferShape(name)
+  if ((fill !== undefined && !isNumber(fill)) || (read !== undefined && typeof read !== 'boolean')) return text.bufferShape(name)
+  const scalar = typeof type === 'string' ? type : declaration.scalar ?? 'f32'
+  if (!TYPES.includes(scalar)) return text.unsupportedType(name, scalar)
+  const values = data as number[] | undefined
+  const length = Math.max(size as number | undefined ?? 0, values?.length ?? 0)
+  if (length === 0) return text.bufferSize(name)
+  return {
+    name,
+    group: declaration.group,
+    binding: declaration.binding,
+    usage: declaration.usage,
+    access: declaration.access,
+    type: scalar as ScalarType,
+    length,
+    ...values ? { data: values } : {},
+    ...fill !== undefined ? { fill: fill as number } : {},
+    read: read ?? declaration.access === 'read_write',
+  }
+}
+
+function valueCount(spec: unknown): number | undefined {
+  const fields = Array.isArray(spec) ? { data: spec } : spec
+  if (!isRecord(fields)) return undefined
+  const counted = [Array.isArray(fields.data) ? fields.data.length : 0, positive(fields.size) ? fields.size : 0]
+  return Math.max(...counted) || undefined
+}
+
+export function paramsSummary(args: Record<string, string>, text: WebgpuMessages): string {
+  const read = (raw: string): unknown => {
+    try {
+      return parse(raw)
+    } catch {
+      return raw
+    }
+  }
+  return Object.entries(args).map(([name, raw]) => {
+    const label = text.labels[name] ?? name
+    const value = read(raw)
+    if (name === 'buffers' && isRecord(value)) {
+      return `${label} ${Object.entries(value).map(([buffer, spec]) => {
+        const count = valueCount(spec)
+        return count === undefined ? buffer : `${buffer}: ${text.values(count)}`
+      }).join(', ')}`
+    }
+    return `${label} ${typeof value === 'string' ? value : JSON.stringify(value)}`
+  }).join(' · ')
+}
+
+export function computeRequest(code: string, args: Record<string, string> | undefined, text: WebgpuMessages): { request: ComputeRequest } | { error: string } {
+  const params: Record<string, unknown> = {}
+  for (const [name, raw] of Object.entries(args ?? {})) {
+    if (!KEYS.includes(name)) return { error: text.unknownParam(name) }
+    try {
+      params[name] = parse(raw)
+    } catch (error) {
+      return { error: text.notYaml(name, error instanceof Error ? error.message.split('\n')[0]! : String(error)) }
+    }
+  }
+
+  const specs = params.buffers
+  if (!isRecord(specs)) return { error: text.noBuffers }
+  const declared = shaderBuffers(code)
+  for (const name of Object.keys(specs)) {
+    if (!declared.some(d => d.name === name)) return { error: text.noDeclaration(name) }
+  }
+  const buffers: ComputeBuffer[] = []
+  for (const declaration of declared) {
+    if (!(declaration.name in specs)) return { error: text.noBuffer(declaration.name) }
+    const made = buffer(declaration, specs[declaration.name], text)
+    if (typeof made === 'string') return { error: made }
+    buffers.push(made)
+  }
+
+  const dispatch = params.dispatch === undefined ? [1] : Array.isArray(params.dispatch) ? params.dispatch : [params.dispatch]
+  if (dispatch.length < 1 || dispatch.length > 3 || !dispatch.every(n => positive(n))) return { error: text.badDispatch }
+  const repeat = params.repeat ?? 1
+  if (!positive(repeat, LIMITS.maxRepeat)) return { error: text.badRepeat(LIMITS.maxRepeat) }
+  const features = params.features ?? []
+  if (!Array.isArray(features) || !features.every(f => typeof f === 'string')) return { error: text.badFeatures }
+  if (params.entry !== undefined && typeof params.entry !== 'string') return { error: text.badEntry }
+  const total = buffers.reduce((sum, b) => sum + bytes(b), 0)
+  if (total > LIMITS.maxBytes) return { error: text.tooLarge(total, LIMITS.maxBytes) }
+
+  const [x, y = 1, z = 1] = dispatch as number[]
+  return {
+    request: {
+      code,
+      ...params.entry ? { entry: params.entry as string } : {},
+      buffers,
+      dispatch: [x!, y, z],
+      repeat,
+      features: features as string[],
+    },
+  }
+}

package/src/domain/result.ts

@@ -0,0 +1,20 @@
+import { failedRun } from '@lincyaw/kernel'
+import type { RunResult } from '@lincyaw/kernel'
+import type { ComputeOutcome } from './compute.ts'
+import { isUnavailable } from './compute.ts'
+import type { WebgpuMessages } from './messages.ts'
+import { failureText, summaryText } from './summary.ts'
+
+export function programError(id: string, message: string, durationMs: number): RunResult {
+  const stderr = `${message}\n`
+  return { ok: false, stdout: '', stderr, exitCode: 1, durationMs, timedOut: false, source: 'live', executorId: id, outputs: [{ output_type: 'stream', name: 'stderr', text: stderr }] }
+}
+
+/** The run's result: a summary of the buffers, or why the GPU could not run the shader (a failed run) or the shader failed (a program error). */
+export function runResultOf(id: string, outcome: ComputeOutcome, durationMs: number, text: WebgpuMessages): RunResult {
+  if (outcome.ok) {
+    const stdout = summaryText(outcome, text)
+    return { ok: true, stdout, stderr: '', exitCode: 0, durationMs, timedOut: false, source: 'live', executorId: id, outputs: [{ output_type: 'stream', name: 'stdout', text: stdout }] }
+  }
+  return isUnavailable(outcome.reason) ? failedRun(id, failureText(outcome, text), durationMs) : programError(id, failureText(outcome, text), durationMs)
+}

package/src/domain/summary.ts

@@ -0,0 +1,46 @@
+import type { AdapterDescription, BufferSummary, ComputeOutcome } from './compute.ts'
+import type { WebgpuMessages } from './messages.ts'
+
+export function formatNumber(value: number): string {
+  if (Number.isInteger(value) && Math.abs(value) < 1e15) return String(value)
+  return Number.isFinite(value) ? String(Number(value.toPrecision(6))) : String(value)
+}
+
+export function bufferLine(buffer: BufferSummary, text: WebgpuMessages): string {
+  const values = buffer.tail.length
+    ? [...buffer.head.map(formatNumber), '…', ...buffer.tail.map(formatNumber)]
+    : buffer.head.map(formatNumber)
+  const line = `${buffer.name}: ${buffer.type}[${buffer.length}] = [${values.join(', ')}]`
+  return buffer.tail.length ? `${line}  ${text.stats(formatNumber(buffer.min), formatNumber(buffer.max), formatNumber(buffer.mean))}` : line
+}
+
+export function adapterName(adapter: AdapterDescription): string {
+  return [adapter.vendor, adapter.architecture].filter(Boolean).join(' ') || adapter.description || 'unknown'
+}
+
+export function summaryText(outcome: Extract<ComputeOutcome, { ok: true }>, text: WebgpuMessages): string {
+  const { timing, adapter } = outcome
+  const ms = formatNumber(Number(timing.ms.toPrecision(3)))
+  return [
+    ...outcome.buffers.map(b => bufferLine(b, text)),
+    text.time(ms, timing.samples, timing.source === 'gpu', adapter.fallback),
+    text.adapter(adapterName(adapter), adapter.fallback),
+  ].join('\n') + '\n'
+}
+
+export function failureText(outcome: Extract<ComputeOutcome, { ok: false }>, text: WebgpuMessages): string {
+  switch (outcome.reason) {
+    case 'no-webgpu': return text.noWebgpu
+    case 'no-adapter': return text.noAdapter
+    case 'feature': return text.missingFeature(outcome.detail)
+    case 'limit': return text.missingLimit(outcome.detail)
+    case 'device-lost': return text.deviceLost(outcome.detail)
+    case 'shader': return text.shader(outcome.detail)
+    case 'validation': return text.validation(outcome.detail)
+  }
+}
+
+/** The environment's fingerprint: the browser and the adapter, marked when it is a fallback adapter. */
+export function adapterFingerprint(browser: string, adapter: AdapterDescription): string {
+  return `${browser}; ${adapterName(adapter)}${adapter.fallback ? ' (fallback)' : ''}`
+}

package/src/node/presmium.ts

@@ -0,0 +1,32 @@
+import { createRequire } from 'node:module'
+import { environmentExecutor, errorMessage } from '@lincyaw/kernel'
+import type { EnvironmentProvider, PresmiumNodePlugin } from '@lincyaw/kernel'
+import { minimalRunEnv } from '@lincyaw/kernel/node'
+import { adapterChoice, EXEC_WEBGPU_ID, WEBGPU_EXECUTOR_ID, WEBGPU_KIND } from '../domain/index.ts'
+import { createChromiumExecutor, findChromiumAdapter } from './recorder.ts'
+import { jaxAssets } from './vite.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+const webgpu: EnvironmentProvider = {
+  create: (name, spec) => createChromiumExecutor({ id: environmentExecutor(name), adapter: adapterChoice(spec) }),
+  async probe(_name, spec) {
+    try {
+      await findChromiumAdapter(adapterChoice(spec), minimalRunEnv())
+      return undefined
+    } catch (error) {
+      return errorMessage(error)
+    }
+  },
+}
+
+const plugin: PresmiumNodePlugin = {
+  id: EXEC_WEBGPU_ID,
+  version,
+  kernel: '^1.0.0',
+  executors: [createChromiumExecutor({ id: WEBGPU_EXECUTOR_ID, adapter: 'auto' })],
+  environments: { [WEBGPU_KIND]: webgpu },
+  assets: () => [jaxAssets()],
+}
+
+export default plugin

package/src/node/recorder.ts

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { deckLocale, failedRun } from '@lincyaw/kernel'
+import type { Executor, RunContext, RunResult } from '@lincyaw/kernel'
+import { minimalRunEnv } from '@lincyaw/kernel/node'
+import type { Browser, BrowserType, Page } from 'playwright-chromium'
+import { adapterFingerprint, adapterName, computeRequest, DEFAULT_TIMEOUT_MS, failureText, isUnavailable, isWgsl, MESSAGES, programError, runResultOf } from '../domain/index.ts'
+import type { AdapterChoice, AdapterDescription, ComputeOutcome, ComputeRequest } from '../domain/index.ts'
+
+const CHROMIUM_ARGS: Record<Exclude<AdapterChoice, 'auto'>, string[]> = {
+  gpu: ['--enable-unsafe-webgpu', '--enable-features=Vulkan', '--use-angle=vulkan'],
+  swiftshader: ['--enable-unsafe-webgpu', '--use-webgpu-adapter=swiftshader', '--enable-unsafe-swiftshader'],
+}
+
+const ORIGIN = 'https://webgpu.presmium.invalid'
+const PAGE = `<!doctype html><meta charset="utf-8"><title>presmium webgpu</title>
+<script type="module">import * as gpu from '/gpu-compute.mjs'; window.presmiumGpu = gpu</script>`
+
+const require = createRequire(import.meta.url)
+let chromium: BrowserType | undefined
+let core: string | undefined
+
+function browserType(): BrowserType {
+  chromium ??= (require('playwright-chromium') as { chromium: BrowserType }).chromium
+  return chromium
+}
+
+function installed(): boolean {
+  try {
+    return existsSync(browserType().executablePath())
+  } catch {
+    return false
+  }
+}
+
+type GpuWindow = { presmiumGpu: { probeAdapter(gpu: unknown): Promise<AdapterDescription | undefined>, compute(gpu: unknown, request: ComputeRequest): Promise<ComputeOutcome> } }
+
+async function withPage<T>(args: string[], env: Readonly<Record<string, string>>, use: (page: Page, browser: Browser) => Promise<T>): Promise<T> {
+  const browser = await browserType().launch({ args, env: { ...env } })
+  try {
+    const page = await browser.newPage()
+    core ??= readFileSync(new URL('../shared/gpu-compute.mjs', import.meta.url), 'utf8')
+    await page.route(`${ORIGIN}/**`, route => route.fulfill(new URL(route.request().url()).pathname === '/gpu-compute.mjs'
+      ? { contentType: 'text/javascript', body: core }
+      : { contentType: 'text/html', body: PAGE }))
+    await page.goto(`${ORIGIN}/`)
+    await page.waitForFunction(() => 'presmiumGpu' in window)
+    return await use(page, browser)
+  } finally {
+    await browser.close()
+  }
+}
+
+/** Chromium's arguments that give it a WebGPU adapter, its version and the adapter. */
+export interface ChromiumAdapter {
+  args: string[]
+  version: string
+  adapter: AdapterDescription
+}
+
+/** Launches Chromium to find its WebGPU adapter: the GPU, SwiftShader, or with `auto` the GPU and else SwiftShader. */
+export async function findChromiumAdapter(choice: AdapterChoice, env: Readonly<Record<string, string>>): Promise<ChromiumAdapter> {
+  const tries = choice === 'auto' ? [CHROMIUM_ARGS.gpu, CHROMIUM_ARGS.swiftshader] : [CHROMIUM_ARGS[choice]]
+  for (const args of tries) {
+    const found = await withPage(args, env, async (page, browser) => ({
+      version: `chromium ${browser.version()}`,
+      adapter: await page.evaluate(() => (window as unknown as GpuWindow).presmiumGpu.probeAdapter((navigator as Navigator & { gpu?: unknown }).gpu)),
+    }))
+    if (found.adapter) return { args, version: found.version, adapter: found.adapter }
+  }
+  throw new Error(`Chromium has no WebGPU adapter (${choice === 'auto' ? 'neither the GPU nor SwiftShader' : choice})`)
+}
+
+/** Records WGSL runs at compile time: each run in a new Chromium page, with the adapter found once. */
+export function createChromiumExecutor(options: { id: string, adapter: AdapterChoice }): Executor {
+  const { id } = options
+  let found: Promise<ChromiumAdapter> | undefined
+  const find = (env: Readonly<Record<string, string>>) => {
+    found ??= findChromiumAdapter(options.adapter, env).catch((error: unknown) => {
+      found = undefined
+      throw error
+    })
+    return found
+  }
+  return {
+    id,
+    supports: lang => isWgsl(lang) && installed(),
+    async fingerprint() {
+      const { version, adapter } = await find(minimalRunEnv())
+      return adapterFingerprint(version, adapter)
+    },
+    async run(request, signal, ctx?: RunContext): Promise<RunResult> {
+      const text = MESSAGES[ctx?.lang ? deckLocale(ctx.lang) : 'en']
+      const made = computeRequest(request.code, request.args, text)
+      if ('error' in made) return programError(id, made.error, 0)
+      const env = ctx?.env ?? minimalRunEnv()
+      const { args } = await find(env)
+      const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS
+      const started = Date.now()
+      const outcome = await withPage(args, env, page => new Promise<ComputeOutcome | 'timeout' | 'cancelled'>((resolve, reject) => {
+        const timer = setTimeout(() => resolve('timeout'), timeoutMs)
+        const cancel = () => resolve('cancelled')
+        if (signal?.aborted) cancel()
+        signal?.addEventListener('abort', cancel, { once: true })
+        page.evaluate(req => (window as unknown as GpuWindow).presmiumGpu.compute((navigator as Navigator & { gpu?: unknown }).gpu, req), made.request)
+          .then(resolve, reject)
+          .finally(() => {
+            clearTimeout(timer)
+            signal?.removeEventListener('abort', cancel)
+          })
+      }))
+      const durationMs = Date.now() - started
+      if (outcome === 'timeout') return { ...failedRun(id, text.timedOut(timeoutMs), durationMs), timedOut: true }
+      if (outcome === 'cancelled') return failedRun(id, text.cancelled, durationMs)
+      if (!outcome.ok && isUnavailable(outcome.reason)) throw new Error(`${failureText(outcome, text)} (${outcome.adapter ? adapterName(outcome.adapter) : 'Chromium'})`)
+      return runResultOf(id, outcome, durationMs, text)
+    },
+  }
+}

package/src/node/vite.ts

@@ -0,0 +1,24 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { findPackageJSON } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import type { RuntimeAssets } from '@lincyaw/kernel'
+
+const JAX_DIR = 'presmium/jax-js/'
+const LICENSE = 'LICENSE'
+
+function jaxFiles(): { dist: string, license: string } {
+  const manifest = findPackageJSON('@jax-js/jax', import.meta.url)
+  if (!manifest) throw new Error('@jax-js/jax is not installed')
+  const { exports } = JSON.parse(readFileSync(manifest, 'utf8')) as { exports: { '.': { import: string } } }
+  return { dist: dirname(resolve(dirname(manifest), exports['.'].import)), license: join(dirname(manifest), LICENSE) }
+}
+
+/** The ES module build of jax-js, at `<base>presmium/jax-js/`. */
+export function jaxAssets(): RuntimeAssets {
+  const { dist, license } = jaxFiles()
+  const types = Object.fromEntries([
+    ...readdirSync(dist).filter(file => file.endsWith('.js')).map(file => [file, 'text/javascript']),
+    [LICENSE, 'text/plain; charset=utf-8'],
+  ])
+  return { name: 'presmium:jax-js', prefix: JAX_DIR, types, source: file => (file === LICENSE ? license : join(dist, file)) }
+}

package/src/shared/gpu-compute.d.mts

@@ -0,0 +1,4 @@
+import type { AdapterDescription, ComputeOutcome, ComputeRequest } from '../domain/compute.ts'
+
+export function probeAdapter(gpu: unknown): Promise<AdapterDescription | undefined>
+export function compute(gpu: unknown, request: ComputeRequest, hooks?: { device?(device: { destroy(): void }): void }): Promise<ComputeOutcome>

package/src/shared/gpu-compute.mjs

@@ -0,0 +1,172 @@
+const ARRAYS = { f32: Float32Array, i32: Int32Array, u32: Uint32Array }
+const ENDS = 4
+
+function describeAdapter(adapter) {
+  const info = adapter.info ?? {}
+  const fallback = Boolean(info.isFallbackAdapter ?? adapter.isFallbackAdapter) || info.architecture === 'swiftshader'
+  return { vendor: info.vendor ?? '', architecture: info.architecture ?? '', description: info.description ?? '', fallback }
+}
+
+export async function probeAdapter(gpu) {
+  const adapter = gpu ? await gpu.requestAdapter().catch(() => null) : null
+  return adapter ? describeAdapter(adapter) : undefined
+}
+
+// The same sizes as the domain's params.ts: this file runs alone in the recording's page, so it imports nothing.
+function bufferBytes(buffer) {
+  const bytes = Math.max(4, buffer.length * 4)
+  return buffer.usage === 'uniform' ? Math.ceil(bytes / 16) * 16 : bytes
+}
+
+function initial(buffer) {
+  const values = new ARRAYS[buffer.type](buffer.length)
+  if (buffer.data) values.set(buffer.data)
+  else if (buffer.fill) values.fill(buffer.fill)
+  return values
+}
+
+function summarize(name, type, values) {
+  let min = Infinity
+  let max = -Infinity
+  let sum = 0
+  for (const value of values) {
+    if (value < min) min = value
+    if (value > max) max = value
+    sum += value
+  }
+  const all = values.length <= ENDS * 2
+  return {
+    name,
+    type,
+    length: values.length,
+    head: Array.from(all ? values : values.subarray(0, ENDS)),
+    tail: all ? [] : Array.from(values.subarray(values.length - ENDS)),
+    min: values.length ? min : 0,
+    max: values.length ? max : 0,
+    mean: values.length ? sum / values.length : 0,
+  }
+}
+
+function median(samples) {
+  const sorted = [...samples].sort((a, b) => a - b)
+  const middle = sorted.length >> 1
+  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2
+}
+
+export async function compute(gpu, request, hooks = {}) {
+  if (!gpu) return { ok: false, reason: 'no-webgpu', detail: '' }
+  const adapter = await gpu.requestAdapter().catch(() => null)
+  if (!adapter) return { ok: false, reason: 'no-adapter', detail: '' }
+  const described = describeAdapter(adapter)
+  const missing = request.features.filter(feature => !adapter.features.has(feature))
+  if (missing.length) return { ok: false, reason: 'feature', detail: missing.join(', '), adapter: described }
+
+  const sizes = usage => request.buffers.filter(b => b.usage === usage).map(bufferBytes)
+  const needs = {
+    maxBufferSize: Math.max(4, ...request.buffers.map(bufferBytes)),
+    maxStorageBufferBindingSize: Math.max(4, ...sizes('storage')),
+    maxUniformBufferBindingSize: Math.max(4, ...sizes('uniform')),
+    maxStorageBuffersPerShaderStage: sizes('storage').length,
+    maxUniformBuffersPerShaderStage: sizes('uniform').length,
+  }
+  for (const [limit, needed] of Object.entries(needs)) {
+    if (needed > adapter.limits[limit]) return { ok: false, reason: 'limit', detail: `${limit} ${adapter.limits[limit]} < ${needed}`, adapter: described }
+  }
+  const timestamps = adapter.features.has('timestamp-query')
+  let device
+  try {
+    device = await adapter.requestDevice({ requiredFeatures: [...request.features, ...timestamps ? ['timestamp-query'] : []], requiredLimits: needs })
+  } catch (error) {
+    return { ok: false, reason: 'limit', detail: String(error?.message ?? error), adapter: described }
+  }
+  hooks.device?.(device)
+  const lost = device.lost.then(info => info.reason === 'destroyed' ? new Promise(() => {}) : { ok: false, reason: 'device-lost', detail: info.message ?? '', adapter: described })
+  try {
+    return await Promise.race([lost, dispatch(device, request, described, timestamps)])
+  } catch (error) {
+    return { ok: false, reason: 'validation', detail: String(error?.message ?? error), adapter: described }
+  } finally {
+    device.destroy()
+  }
+}
+
+async function dispatch(device, request, adapter, timestamps) {
+  const usage = GPUBufferUsage
+  device.pushErrorScope('validation')
+  const module = device.createShaderModule({ code: request.code })
+  const errors = (await module.getCompilationInfo()).messages.filter(message => message.type === 'error')
+  if (errors.length) {
+    await device.popErrorScope()
+    return { ok: false, reason: 'shader', detail: errors.map(m => `${m.lineNum}:${m.linePos} ${m.message}`).join('\n'), adapter }
+  }
+  const groups = Math.max(0, ...request.buffers.map(b => b.group + 1))
+  const layouts = Array.from({ length: groups }, (_, group) => device.createBindGroupLayout({
+    entries: request.buffers.filter(b => b.group === group).map(b => ({
+      binding: b.binding,
+      visibility: GPUShaderStage.COMPUTE,
+      buffer: { type: b.usage === 'uniform' ? 'uniform' : b.access === 'read' ? 'read-only-storage' : 'storage' },
+    })),
+  }))
+  const pipeline = device.createComputePipeline({
+    layout: device.createPipelineLayout({ bindGroupLayouts: layouts }),
+    compute: request.entry ? { module, entryPoint: request.entry } : { module },
+  })
+  const buffers = request.buffers.map((b) => {
+    const buffer = device.createBuffer({ size: bufferBytes(b), usage: (b.usage === 'uniform' ? usage.UNIFORM : usage.STORAGE) | usage.COPY_SRC | usage.COPY_DST, mappedAtCreation: true })
+    new ARRAYS[b.type](buffer.getMappedRange()).set(initial(b))
+    buffer.unmap()
+    return buffer
+  })
+  const bindGroups = layouts.map((layout, group) => device.createBindGroup({
+    layout,
+    entries: request.buffers.flatMap((b, i) => b.group === group ? [{ binding: b.binding, resource: { buffer: buffers[i] } }] : []),
+  }))
+  const encode = (encoder, timestampWrites) => {
+    const pass = encoder.beginComputePass(timestampWrites ? { timestampWrites } : {})
+    pass.setPipeline(pipeline)
+    bindGroups.forEach((group, i) => pass.setBindGroup(i, group))
+    pass.dispatchWorkgroups(...request.dispatch)
+    pass.end()
+  }
+
+  const samples = []
+  let times
+  if (timestamps) {
+    const count = request.repeat * 2
+    const querySet = device.createQuerySet({ type: 'timestamp', count })
+    const resolved = device.createBuffer({ size: count * 8, usage: usage.QUERY_RESOLVE | usage.COPY_SRC })
+    times = device.createBuffer({ size: count * 8, usage: usage.MAP_READ | usage.COPY_DST })
+    const encoder = device.createCommandEncoder()
+    for (let i = 0; i < request.repeat; i++) encode(encoder, { querySet, beginningOfPassWriteIndex: i * 2, endOfPassWriteIndex: i * 2 + 1 })
+    encoder.resolveQuerySet(querySet, 0, count, resolved, 0)
+    encoder.copyBufferToBuffer(resolved, 0, times, 0, count * 8)
+    device.queue.submit([encoder.finish()])
+  } else {
+    for (let i = 0; i < request.repeat; i++) {
+      const encoder = device.createCommandEncoder()
+      encode(encoder)
+      const started = performance.now()
+      device.queue.submit([encoder.finish()])
+      await device.queue.onSubmittedWorkDone()
+      samples.push(performance.now() - started)
+    }
+  }
+  const shown = request.buffers.flatMap((b, i) => b.read ? [{ b, copy: device.createBuffer({ size: bufferBytes(b), usage: usage.MAP_READ | usage.COPY_DST }), buffer: buffers[i] }] : [])
+  const encoder = device.createCommandEncoder()
+  for (const { b, copy, buffer } of shown) encoder.copyBufferToBuffer(buffer, 0, copy, 0, bufferBytes(b))
+  device.queue.submit([encoder.finish()])
+  const error = await device.popErrorScope()
+  if (error) return { ok: false, reason: 'validation', detail: error.message, adapter }
+
+  if (times) {
+    await times.mapAsync(GPUMapMode.READ)
+    const ns = new BigUint64Array(times.getMappedRange())
+    for (let i = 0; i < request.repeat; i++) samples.push(Number(ns[i * 2 + 1] - ns[i * 2]) / 1e6)
+  }
+  const summaries = []
+  for (const { b, copy } of shown) {
+    await copy.mapAsync(GPUMapMode.READ)
+    summaries.push(summarize(b.name, b.type, new ARRAYS[b.type](copy.getMappedRange(), 0, b.length)))
+  }
+  return { ok: true, buffers: summaries, timing: { ms: median(samples), samples: samples.length, source: timestamps ? 'gpu' : 'wall' }, adapter }
+}