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

package/src/client/plugin.ts

@@ -0,0 +1,55 @@
+import { siteBase, STATUS } from '@lincyaw/host'
+import { EXECUTOR } from '@lincyaw/kernel'
+import type { PluginDefinition } from '@lincyaw/kernel'
+import { version } from '../../package.json'
+import { createExecutorRouter, EXEC_ID, execConfig, TRACER } from '../domain/index.ts'
+import { messages } from './messages.ts'
+import { withRuntimeFeedback } from './feedback.ts'
+import { createPyodideExecutor } from './pyodide/executor.ts'
+import type { PyodideExecutor } from './pyodide/executor.ts'
+import { declaredEnvironments } from './runs-in.ts'
+import { createScriptExecutor } from './script/executor.ts'
+import type { ScriptExecutor } from './script/executor.ts'
+
+let pyodide: PyodideExecutor | undefined
+let script: ScriptExecutor | undefined
+let stopStatus: (() => void) | undefined
+
+export const execPlugin: PluginDefinition = {
+  manifest: { id: EXEC_ID, name: { 'zh-CN': '代码运行', en: 'Code Runner' }, version, kernel: '^1.0.0', provides: [EXECUTOR, TRACER], requires: [{ token: STATUS, optional: true }], capabilities: ['exec'] },
+  setup(ctx) {
+    const config = execConfig(ctx.config)
+    declaredEnvironments.set(ctx.environments ?? {})
+    pyodide?.dispose()
+    script?.dispose()
+    pyodide = createPyodideExecutor({
+      indexURL: config.pyodideURL ?? `${siteBase()}pyodide/`,
+      timeoutMs: config.timeoutMs,
+      loadTimeoutMs: config.loadTimeoutMs,
+      maxTraceEvents: config.maxTraceEvents,
+    })
+    script = createScriptExecutor({ timeoutMs: config.timeoutMs })
+    const router = createExecutorRouter({
+      noExecutor: lang => messages().noExecutor(lang),
+      executorUnavailable: (id, lang) => messages().executorUnavailable(id, lang),
+      executorCrashed: (id, error) => messages().executorCrashed(id, error),
+    })
+    router.register(pyodide)
+    router.register(script)
+    const feedback = withRuntimeFeedback(router)
+    stopStatus?.()
+    stopStatus = ctx.tryGet(STATUS)?.register({ id: EXEC_ID, read: feedback.read })
+    ctx.provide(EXECUTOR, feedback.executor)
+    ctx.provide(TRACER, pyodide)
+  },
+  dispose() {
+    pyodide?.dispose()
+    pyodide = undefined
+    script?.dispose()
+    script = undefined
+    stopStatus?.()
+    stopStatus = undefined
+  },
+}
+
+export default execPlugin

package/src/client/pyodide/executor.ts

@@ -0,0 +1,94 @@
+import { createResidentWorker } from '@lincyaw/host'
+import { failedRun } from '@lincyaw/kernel'
+import type { Executor, RunRequest, RunResult } from '@lincyaw/kernel'
+import { isPython } from '../../domain/index.ts'
+import type { Trace, Tracer } from '../../domain/index.ts'
+import { messages } from '../messages.ts'
+import type { WorkerReply, WorkerRequest, WorkerRunResult, WorkerTraceResult } from './protocol.ts'
+
+export const PYODIDE_EXECUTOR_ID = 'pyodide'
+
+export interface PyodideExecutorOptions {
+  indexURL: string
+  timeoutMs: number
+  loadTimeoutMs: number
+  maxTraceEvents: number
+}
+
+export type PyodideExecutor = Executor & Tracer & {
+  dispose(): void
+}
+
+type Outcome<T> =
+  | { ok: true; value: T; durationMs: number }
+  | { ok: false; error: string; timedOut: boolean; durationMs: number }
+
+export function createPyodideExecutor(options: PyodideExecutorOptions): PyodideExecutor {
+  const id = PYODIDE_EXECUTOR_ID
+  const traces = new Map<string, Promise<Trace>>()
+  const resident = createResidentWorker<WorkerRequest, WorkerReply>({
+    start: () => new Worker(new URL('./pyodide.worker.ts', import.meta.url), { type: 'module', name: 'presmium-pyodide' }),
+    loadTimeoutMs: options.loadTimeoutMs,
+  })
+
+  async function send<T>(kind: WorkerRequest['kind'], request: RunRequest, signal?: AbortSignal): Promise<Outcome<T>> {
+    const timeoutMs = request.timeoutMs ?? options.timeoutMs
+    const indexURL = new URL(options.indexURL, location.href).href
+    const outcome = await resident.send({ kind, request: plain(request), indexURL, maxEvents: options.maxTraceEvents }, { timeoutMs, signal })
+    if ('reply' in outcome) {
+      const { reply } = outcome
+      return reply.type === 'done'
+        ? { ok: true, value: reply.value as T, durationMs: reply.durationMs }
+        : { ok: false, error: reply.error, timedOut: false, durationMs: outcome.elapsedMs }
+    }
+    const t = messages()
+    const error = {
+      'cancelled': t.cancelled,
+      'load-timeout': t.loadTimeout('Python', options.loadTimeoutMs),
+      'run-timeout': t.runTimeout(timeoutMs),
+      'crashed': t.runtimeCrashed('Python', outcome.error ?? ''),
+    }[outcome.failure]
+    return { ok: false, error, timedOut: outcome.failure === 'load-timeout' || outcome.failure === 'run-timeout', durationMs: outcome.elapsedMs }
+  }
+
+  return {
+    id,
+    runsIn: 'browser',
+    supports: isPython,
+    async run(request, signal): Promise<RunResult> {
+      const outcome = await send<WorkerRunResult>('run', request, signal)
+      if (!outcome.ok) return { ...failedRun(id, outcome.error, outcome.durationMs), timedOut: outcome.timedOut }
+      const { stdout, stderr, exitCode, outputs } = outcome.value
+      const unavailable = outputs?.find(output => output.output_type === 'error' && output.ename === 'GPUUnavailable')
+      if (unavailable?.output_type === 'error') return { ...failedRun(id, messages().gpuUnavailable(unavailable.evalue), outcome.durationMs), stdout }
+      return { ok: exitCode === 0, stdout, stderr, exitCode, durationMs: outcome.durationMs, timedOut: false, source: 'live', executorId: id, ...outputs ? { outputs } : {} }
+    },
+    async endSession(session) {
+      if (resident.hasWorker()) await send<null>('end', { lang: 'python', code: '', session })
+    },
+    dispose() {
+      resident.dispose()
+      traces.clear()
+    },
+    trace(request, signal) {
+      const key = JSON.stringify([request.code, request.args, request.stdin, request.files])
+      let trace = traces.get(key)
+      if (!trace) {
+        trace = send<WorkerTraceResult>('trace', request, signal).then(toTrace, (error: unknown) => ({ events: [], truncated: false, error: String(error) }))
+        traces.set(key, trace)
+        void trace.then(t => t.error !== undefined && traces.delete(key))
+      }
+      return trace
+    },
+  }
+}
+
+function toTrace(outcome: Outcome<WorkerTraceResult>): Trace {
+  if (!outcome.ok) return { events: [], truncated: false, error: outcome.error }
+  const { events, truncated, output } = outcome.value
+  return events.length ? { events, truncated } : { events, truncated, error: output || undefined }
+}
+
+function plain(request: RunRequest): RunRequest {
+  return JSON.parse(JSON.stringify(request)) as RunRequest
+}

package/src/client/pyodide/presmium_gpu.py

@@ -0,0 +1,297 @@
+"""
+WebGPU from Python in the browser. The Pyodide worker of the execution plugin makes this
+module importable: it runs a WGSL compute shader with `navigator.gpu`, through Pyodide's bridge
+to JavaScript, as the WebGPU plugin runs `{run-panel} wgsl`: buffers by the names of the shader's
+variables (a list of numbers, or a dict with `data`, `size`, `fill`, `type`, `read`), `dispatch`,
+`entry`, `repeat` and `features`.
+
+    import presmium_gpu as gpu
+    result = await gpu.run(SHADER, buffers={'a': [1, 2], 'b': [3, 4], 'out': {'size': 2}})
+    result['out']    # [4.0, 6.0], the buffers read back (those the shader may write)
+    print(result)    # each buffer, the median time of a dispatch and the adapter
+
+`await` works at the top of a code block. Where the browser has JavaScript Promise Integration
+(JSPI), `gpu.run_sync(...)` does the same without `await` (`gpu.can_run_sync()` says whether it
+can). A shader that cannot run here (no WebGPU, no adapter, a missing feature or limit, a lost
+device) raises `GPUUnavailable`; one WebGPU rejects, `GPUError`. The run has the scale limits of
+`{run-panel} wgsl` (the WebGPU plugin's `LIMITS`): all buffers together at most 128 MiB, and
+`repeat` at most 1000; buffers, `dispatch` or `repeat` beyond them or of the wrong shape raise
+`ValueError` before the GPU is asked for.
+"""
+import re
+
+import js
+import pyodide.ffi
+from pyodide.ffi import JsException, can_run_sync, create_once_callable, to_js
+from pyodide.ffi import run_sync as _run_sync
+
+__all__ = ['GPUError', 'GPUUnavailable', 'Result', 'can_run_sync', 'run', 'run_sync']
+
+_ARRAYS = {'f32': 'Float32Array', 'i32': 'Int32Array', 'u32': 'Uint32Array'}
+# Values shown at each end of a long buffer.
+_ENDS = 4
+# The scale limits of a run, as the WebGPU plugin's `LIMITS` (src/domain/config.ts there).
+_MAX_BYTES = 128 * 1024 * 1024
+_MAX_REPEAT = 1000
+_DECLARATION = re.compile(r'((?:@\s*\w+\s*(?:\([^)]*\))?\s*)+)var\s*<\s*(storage|uniform)\s*(?:,\s*(read_write|read))?\s*>\s*([A-Za-z_]\w*)\s*:\s*([^;]+);')
+_SHORTHAND = {'f': 'f32', 'i': 'i32', 'u': 'u32', 'h': 'f16'}
+
+
+class GPUUnavailable(RuntimeError):
+    """The shader cannot run in this browser: no WebGPU, no adapter, a missing feature or limit, a lost device."""
+
+
+class GPUError(RuntimeError):
+    """WebGPU rejected the shader or the buffers."""
+
+
+def _js(value):
+    return to_js(value, dict_converter=js.Object.fromEntries)
+
+
+def _absent(value):
+    """JavaScript's `null` or `undefined` (Pyodide gives `null` as `jsnull`)."""
+    return value is None or value is getattr(pyodide.ffi, 'jsnull', None)
+
+
+def _declarations(code):
+    """The buffers the shader declares: name, group, binding, address space, access, scalar type."""
+    source = re.sub(r'//.*$', '', re.sub(r'/\*[\s\S]*?\*/', '', code), flags=re.M)
+    found = []
+    for attributes, space, access, name, kind in _DECLARATION.findall(source):
+        def attribute(key):
+            match = re.search(r'@\s*%s\s*\(\s*(\d+)\s*\)' % key, attributes)
+            return int(match.group(1)) if match else 0
+        scalars = set(re.findall(r'\b(f32|i32|u32|f16)\b', kind)) | {_SHORTHAND[s] for s in re.findall(r'\b(?:vec[234]|mat[234]x[234])([fiuh])\b', kind)}
+        found.append({
+            'name': name,
+            'group': attribute('group'),
+            'binding': attribute('binding'),
+            'usage': space,
+            'access': 'read_write' if space == 'storage' and access == 'read_write' else 'read',
+            'scalar': next(iter(scalars)) if len(scalars) == 1 else None,
+        })
+    return found
+
+
+def _buffers(code, specs):
+    declared = _declarations(code)
+    for name in specs:
+        if not any(d['name'] == name for d in declared):
+            raise ValueError('The shader has no buffer named %s (var<storage> or var<uniform>)' % name)
+    buffers = []
+    for d in declared:
+        if d['name'] not in specs:
+            raise ValueError("The shader's buffer %s is not in buffers" % d['name'])
+        spec = specs[d['name']]
+        if not isinstance(spec, (list, tuple, range, dict)):
+            raise ValueError('The buffer %s is a list of numbers, or {data, size, fill, type, read}' % d['name'])
+        fields = {'data': list(spec)} if isinstance(spec, (list, tuple, range)) else dict(spec)
+        data = fields.get('data')
+        size = fields.get('size')
+        if (data is not None and not (isinstance(data, (list, tuple, range)) and all(_is_number(v) for v in data))) or (size is not None and not _positive(size)):
+            raise ValueError('The buffer %s is a list of numbers, or {data, size, fill, type, read}' % d['name'])
+        kind = fields.get('type') or d['scalar'] or 'f32'
+        if kind not in _ARRAYS:
+            raise ValueError('The type %s of the buffer %s is not supported (f32, i32, u32)' % (kind, d['name']))
+        length = max(size or 0, len(data) if data is not None else 0)
+        if length == 0:
+            raise ValueError('The buffer %s needs data or size (its number of values)' % d['name'])
+        read = fields.get('read')
+        buffers.append(dict(d, type=kind, length=length, data=data, fill=fields.get('fill'), read=d['access'] == 'read_write' if read is None else read))
+    return buffers
+
+
+def _is_number(value):
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and value == value and abs(value) != float('inf')
+
+
+def _positive(value, most=float('inf')):
+    return isinstance(value, int) and not isinstance(value, bool) and 1 <= value <= most
+
+
+def _bytes(buffer):
+    size = max(4, buffer['length'] * 4)
+    return -(-size // 16) * 16 if buffer['usage'] == 'uniform' else size
+
+
+def _number(value):
+    """A value as the summary shows it: integers whole, others to 6 significant digits."""
+    if value == value and abs(value) != float('inf') and value == int(value) and abs(value) < 1e15:
+        return str(int(value))
+    return '%.6g' % value
+
+
+class Result(dict):
+    """The buffers read back, by name (lists of numbers), with `timing` and `adapter`."""
+
+    def __init__(self, values, types, timing, adapter):
+        super().__init__(values)
+        self.types = types
+        self.timing = timing
+        self.adapter = adapter
+
+    def __str__(self):
+        lines = []
+        for name, values in self.items():
+            shown = values if len(values) <= _ENDS * 2 else values[:_ENDS] + ['…'] + values[-_ENDS:]
+            line = '%s: %s[%d] = [%s]' % (name, self.types[name], len(values), ', '.join(v if v == '…' else _number(v) for v in shown))
+            if len(values) > _ENDS * 2:
+                line += '  min %s, max %s, mean %s' % (_number(min(values)), _number(max(values)), _number(sum(values) / len(values)))
+            lines.append(line)
+        timing, adapter = self.timing, self.adapter
+        notes = [n for n in ['median of %d' % timing['samples'] if timing['samples'] > 1 else '', 'GPU timestamps' if timing['source'] == 'gpu' else 'wall clock', 'CPU emulation' if adapter['fallback'] else ''] if n]
+        lines.append('time: %s ms per dispatch (%s)' % (_number(float('%.3g' % timing['ms'])), '; '.join(notes)))
+        name = ' '.join(p for p in [adapter['vendor'], adapter['architecture']] if p) or adapter['description'] or 'unknown'
+        lines.append('adapter: %s%s' % (name, ' (fallback adapter)' if adapter['fallback'] else ''))
+        return '\n'.join(lines)
+
+
+def _adapter(adapter):
+    info = getattr(adapter, 'info', None)
+
+    def field(key, default=''):
+        return default if _absent(info) else getattr(info, key, default)
+
+    fallback = bool(field('isFallbackAdapter', False) or getattr(adapter, 'isFallbackAdapter', False)) or field('architecture') == 'swiftshader'
+    return {'vendor': field('vendor'), 'architecture': field('architecture'), 'description': field('description'), 'fallback': fallback}
+
+
+async def run(shader, buffers, dispatch=1, entry=None, repeat=1, features=()):
+    """Runs the compute shader `repeat` times on the buffers; returns the `Result`."""
+    specs = _buffers(shader, buffers)
+    groups = list(dispatch) if isinstance(dispatch, (list, tuple)) else [dispatch]
+    if not 1 <= len(groups) <= 3 or not all(_positive(n) for n in groups):
+        raise ValueError('dispatch is 1 to 3 positive integers (workgroups in each dimension)')
+    groups += [1] * (3 - len(groups))
+    if not _positive(repeat, _MAX_REPEAT):
+        raise ValueError('repeat is an integer from 1 to %d' % _MAX_REPEAT)
+    total = sum(_bytes(b) for b in specs)
+    if total > _MAX_BYTES:
+        raise ValueError('The buffers take %d bytes, over the scale limit of %d bytes' % (total, _MAX_BYTES))
+    gpu = getattr(js.navigator, 'gpu', None)
+    if _absent(gpu):
+        raise GPUUnavailable('This browser has no WebGPU')
+    adapter = await gpu.requestAdapter()
+    if _absent(adapter):
+        raise GPUUnavailable('No GPU adapter is available')
+    described = _adapter(adapter)
+    missing = [f for f in features if not adapter.features.has(f)]
+    if missing:
+        raise GPUUnavailable('The GPU adapter lacks the feature %s' % ', '.join(missing))
+    storage = [_bytes(b) for b in specs if b['usage'] == 'storage']
+    uniform = [_bytes(b) for b in specs if b['usage'] == 'uniform']
+    needs = {
+        'maxBufferSize': max([4] + [_bytes(b) for b in specs]),
+        'maxStorageBufferBindingSize': max([4] + storage),
+        'maxUniformBufferBindingSize': max([4] + uniform),
+        'maxStorageBuffersPerShaderStage': len(storage),
+        'maxUniformBuffersPerShaderStage': len(uniform),
+    }
+    for limit, needed in needs.items():
+        if needed > getattr(adapter.limits, limit):
+            raise GPUUnavailable("The GPU adapter's limits are too low: %s %d < %d" % (limit, getattr(adapter.limits, limit), needed))
+    timestamps = adapter.features.has('timestamp-query')
+    try:
+        device = await adapter.requestDevice(_js({'requiredFeatures': list(features) + (['timestamp-query'] if timestamps else []), 'requiredLimits': needs}))
+    except JsException as error:
+        raise GPUUnavailable("The GPU adapter's limits are too low: %s" % error) from None
+    lost = []
+    device.lost.then(create_once_callable(lambda info: lost.append(info.message) if info.reason != 'destroyed' else None))
+    try:
+        return await _dispatch(device, shader, specs, groups, entry, repeat, timestamps, described)
+    except JsException as error:
+        if lost:
+            raise GPUUnavailable('The GPU device was lost: %s' % lost[0]) from None
+        raise GPUError(str(error)) from None
+    finally:
+        device.destroy()
+
+
+async def _dispatch(device, shader, specs, groups, entry, repeat, timestamps, adapter):
+    usage = js.GPUBufferUsage
+    device.pushErrorScope('validation')
+    module = device.createShaderModule(_js({'code': shader}))
+    errors = [m for m in (await module.getCompilationInfo()).messages if m.type == 'error']
+    if errors:
+        await device.popErrorScope()
+        raise GPUError('The shader has errors:\n' + '\n'.join('%d:%d %s' % (m.lineNum, m.linePos, m.message) for m in errors))
+    count = max([b['group'] + 1 for b in specs] + [0])
+    layouts = [device.createBindGroupLayout(_js({'entries': [
+        {'binding': b['binding'], 'visibility': js.GPUShaderStage.COMPUTE, 'buffer': {'type': 'uniform' if b['usage'] == 'uniform' else 'read-only-storage' if b['access'] == 'read' else 'storage'}}
+        for b in specs if b['group'] == group
+    ]})) for group in range(count)]
+    stage = {'module': module, 'entryPoint': entry} if entry else {'module': module}
+    pipeline = device.createComputePipeline(_js({'layout': device.createPipelineLayout(_js({'bindGroupLayouts': layouts})), 'compute': stage}))
+    gpu_buffers = []
+    for b in specs:
+        buffer = device.createBuffer(_js({'size': _bytes(b), 'usage': (usage.UNIFORM if b['usage'] == 'uniform' else usage.STORAGE) | usage.COPY_SRC | usage.COPY_DST, 'mappedAtCreation': True}))
+        values = getattr(js, _ARRAYS[b['type']]).new(buffer.getMappedRange())
+        if b['data'] is not None:
+            values.set(_js(list(b['data'])))
+        elif b['fill']:
+            values.fill(b['fill'])
+        buffer.unmap()
+        gpu_buffers.append(buffer)
+    bind_groups = [device.createBindGroup(_js({'layout': layout, 'entries': [
+        {'binding': b['binding'], 'resource': {'buffer': gpu_buffers[i]}} for i, b in enumerate(specs) if b['group'] == group
+    ]})) for group, layout in enumerate(layouts)]
+
+    def encode(encoder, writes=None):
+        compute_pass = encoder.beginComputePass(_js({'timestampWrites': writes} if writes else {}))
+        compute_pass.setPipeline(pipeline)
+        for i, group in enumerate(bind_groups):
+            compute_pass.setBindGroup(i, group)
+        compute_pass.dispatchWorkgroups(*groups)
+        compute_pass.end()
+
+    samples = []
+    times = None
+    if timestamps:
+        queries = repeat * 2
+        query_set = device.createQuerySet(_js({'type': 'timestamp', 'count': queries}))
+        resolved = device.createBuffer(_js({'size': queries * 8, 'usage': usage.QUERY_RESOLVE | usage.COPY_SRC}))
+        times = device.createBuffer(_js({'size': queries * 8, 'usage': usage.MAP_READ | usage.COPY_DST}))
+        encoder = device.createCommandEncoder()
+        for i in range(repeat):
+            encode(encoder, {'querySet': query_set, 'beginningOfPassWriteIndex': i * 2, 'endOfPassWriteIndex': i * 2 + 1})
+        encoder.resolveQuerySet(query_set, 0, queries, resolved, 0)
+        encoder.copyBufferToBuffer(resolved, 0, times, 0, queries * 8)
+        device.queue.submit(_js([encoder.finish()]))
+    else:
+        for _ in range(repeat):
+            encoder = device.createCommandEncoder()
+            encode(encoder)
+            started = js.performance.now()
+            device.queue.submit(_js([encoder.finish()]))
+            await device.queue.onSubmittedWorkDone()
+            samples.append(js.performance.now() - started)
+    shown = [(b, device.createBuffer(_js({'size': _bytes(b), 'usage': usage.MAP_READ | usage.COPY_DST})), gpu_buffers[i]) for i, b in enumerate(specs) if b['read']]
+    encoder = device.createCommandEncoder()
+    for b, copy, buffer in shown:
+        encoder.copyBufferToBuffer(buffer, 0, copy, 0, _bytes(b))
+    device.queue.submit(_js([encoder.finish()]))
+    error = await device.popErrorScope()
+    if not _absent(error):
+        raise GPUError('WebGPU reported an error: %s' % error.message)
+
+    if times is not None:
+        await times.mapAsync(js.GPUMapMode.READ)
+        ns = js.BigUint64Array.new(times.getMappedRange()).to_py().tolist()
+        samples = [(ns[i * 2 + 1] - ns[i * 2]) / 1e6 for i in range(repeat)]
+    values = {}
+    for b, copy, _buffer in shown:
+        await copy.mapAsync(js.GPUMapMode.READ)
+        values[b['name']] = getattr(js, _ARRAYS[b['type']]).new(copy.getMappedRange(), 0, b['length']).to_py().tolist()
+    ordered = sorted(samples)
+    middle = len(ordered) // 2
+    ms = ordered[middle] if len(ordered) % 2 else (ordered[middle - 1] + ordered[middle]) / 2
+    timing = {'ms': ms, 'samples': len(samples), 'source': 'gpu' if timestamps else 'wall'}
+    return Result(values, {b['name']: b['type'] for b, _copy, _buffer in shown}, timing, adapter)
+
+
+def run_sync(shader, buffers, **options):
+    """`run` without `await`, where the browser has JavaScript Promise Integration (JSPI)."""
+    if not can_run_sync():
+        raise RuntimeError('run_sync needs JavaScript Promise Integration (JSPI), which this browser lacks; use `await presmium_gpu.run(...)`')
+    return _run_sync(run(shader, buffers, **options))

package/src/client/pyodide/protocol.ts

@@ -0,0 +1,27 @@
+import type { RunOutput, RunRequest } from '@lincyaw/kernel'
+
+export interface WorkerRequest {
+  id: number
+  kind: 'run' | 'trace' | 'end'
+  request: RunRequest
+  indexURL: string
+  maxEvents: number
+}
+
+export type WorkerReply =
+  | { id: number; type: 'started' }
+  | { id: number; type: 'done'; value: WorkerRunResult | WorkerTraceResult | null; durationMs: number }
+  | { id: number; type: 'failed'; error: string }
+
+export interface WorkerRunResult {
+  stdout: string
+  stderr: string
+  exitCode: number
+  outputs?: RunOutput[]
+}
+
+export interface WorkerTraceResult {
+  events: { line: number; output: string }[]
+  truncated: boolean
+  output: string
+}

package/src/client/pyodide/pyodide.worker.ts

@@ -0,0 +1,68 @@
+/// <reference lib="webworker" />
+import { errorMessage } from '@lincyaw/kernel'
+import type { loadPyodide as LoadPyodide, PyodideInterface } from 'pyodide'
+import runner from '@lincyaw/kernel/runner.py?raw'
+import gpuBridge from './presmium_gpu.py?raw'
+import type { WorkerReply, WorkerRequest } from './protocol.ts'
+import runAwait from './run_await.py?raw'
+
+declare const self: DedicatedWorkerGlobalScope
+
+const MODULES = '/presmium'
+const JSPI = typeof (WebAssembly as { Suspending?: unknown }).Suspending === 'function'
+
+let runtime: Promise<PyodideInterface> | undefined
+
+async function start(indexURL: string): Promise<PyodideInterface> {
+  const { loadPyodide } = (await import(/* @vite-ignore */ `${indexURL}pyodide.mjs`)) as { loadPyodide: typeof LoadPyodide }
+  const pyodide = await loadPyodide({ indexURL })
+  pyodide.runPython(runner)
+  pyodide.runPython(runAwait)
+  pyodide.FS.mkdirTree(MODULES)
+  pyodide.FS.writeFile(`${MODULES}/presmium_gpu.py`, gpuBridge)
+  pyodide.runPython(`import sys\nsys.path.append(${JSON.stringify(MODULES)})`)
+  return pyodide
+}
+
+function load(indexURL: string): Promise<PyodideInterface> {
+  runtime ??= start(indexURL).catch((error: unknown) => {
+    runtime = undefined
+    throw error
+  })
+  return runtime
+}
+
+const reply = (message: WorkerReply) => self.postMessage(message)
+
+function awaiting(pyodide: PyodideInterface, code: string): boolean {
+  const awaits = pyodide.globals.get('_pm_awaits')
+  try {
+    return awaits(code) as boolean
+  } finally {
+    awaits.destroy()
+  }
+}
+
+self.onmessage = async ({ data }: MessageEvent<WorkerRequest>) => {
+  const { id, kind, request, indexURL, maxEvents } = data
+  try {
+    const pyodide = await load(indexURL)
+    reply({ id, type: 'started' })
+    const awaits = kind === 'run' && awaiting(pyodide, request.code)
+    const fn = pyodide.globals.get(kind === 'trace' ? '_pm_trace' : kind === 'end' ? '_pm_end' : awaits ? '_pm_run_await' : '_pm_run')
+    try {
+      const started = performance.now()
+      const args = [request.code, JSON.stringify(request.args ?? {}), request.stdin ?? '', JSON.stringify(request.files ?? {}), maxEvents, request.session ?? null]
+      const json = kind === 'end'
+        ? (fn(request.session ?? ''), 'null')
+        : kind === 'run' && (awaits || JSPI)
+          ? await (awaits ? fn(...args) : fn.callPromising(...args)) as string
+          : fn(...args) as string
+      reply({ id, type: 'done', value: JSON.parse(json), durationMs: Math.round(performance.now() - started) })
+    } finally {
+      fn.destroy()
+    }
+  } catch (error) {
+    reply({ id, type: 'failed', error: errorMessage(error) })
+  }
+}

package/src/client/pyodide/run_await.py

@@ -0,0 +1,57 @@
+# Top-level `await` for Python in the browser: the asynchronous form of the WebGPU bridge
+# (`await presmium_gpu.run(...)`) and other awaitables Pyodide gives (`pyodide.http`).
+# Loaded into the Pyodide worker after the shared runner (@lincyaw/kernel/runner.py), whose
+# helpers it uses: `_pm_run_await` runs code as `_pm_run` does, with the same outputs (the value of a
+# last expression too), session and isolation, but compiled to allow `await` at its top level, and
+# the worker awaits it.
+import ast as _pm_ast
+import inspect as _pm_inspect
+
+_PM_AWAIT = _pm_ast.PyCF_ALLOW_TOP_LEVEL_AWAIT
+
+
+def _pm_awaits(code):
+    """Whether the code awaits at its top level: it compiles only when that is allowed."""
+    try:
+        compile(code, _PM_FILE, 'exec')
+        return False
+    except SyntaxError:
+        pass
+    try:
+        return bool(compile(code, _PM_FILE, 'exec', flags=_PM_AWAIT).co_flags & _pm_inspect.CO_COROUTINE)
+    except SyntaxError:
+        return False
+
+
+async def _pm_evaluate(code, scope):
+    """Runs compiled code; awaits it when it awaits at its top level."""
+    value = eval(code, scope)
+    return await value if code.co_flags & _pm_inspect.CO_COROUTINE else value
+
+
+async def _pm_run_await(code, args_json, stdin, files_json, _max_events, session_name=None):
+    global _PM_CURRENT
+    outputs = _PmOutputs()
+    exit_code = 0
+    session = _pm_session(session_name) if session_name else None
+    scope = session['scope'] if session is not None else {}
+    _PM_CURRENT = outputs
+    try:
+        with _PmIsolation(None, session), contextlib.redirect_stdout(_PmStream(outputs, 'stdout')), contextlib.redirect_stderr(_PmStream(outputs, 'stderr')):
+            try:
+                # The arguments, stdin and files as the runner gives them; then the code, with await.
+                _pm_prepare('', args_json, stdin, files_json, scope)
+                linecache.cache[_PM_FILE] = (len(code), None, code.splitlines(True), _PM_FILE)
+                program, last = _pm_split(code, _PM_AWAIT)
+                await _pm_evaluate(program, scope)
+                if last is not None:
+                    _pm_result(outputs, await _pm_evaluate(last, scope))
+                _pm_figures()
+            except SystemExit as e:
+                exit_code = e.code if isinstance(e.code, int) else (0 if e.code is None else 1)
+            except BaseException:
+                outputs.error(*_pm_user_traceback())
+                exit_code = 1
+    finally:
+        _PM_CURRENT = None
+    return json.dumps({'stdout': ''.join(outputs.text['stdout']), 'stderr': ''.join(outputs.text['stderr']), 'exitCode': exit_code, 'outputs': outputs.items})

package/src/client/runs-in.ts

@@ -0,0 +1,27 @@
+import { environmentExecutor } from '@lincyaw/kernel'
+import type { EnvironmentSpec, Executor } from '@lincyaw/kernel'
+import { createStore } from '@lincyaw/host'
+
+export type RunsIn =
+  | { kind: 'browser' }
+  | { kind: 'machine' }
+  | { kind: 'remote', name: string }
+  | { kind: 'environment', name: string }
+
+/** The environments of the deck's headmatter, which the plugin's setup records. */
+export const declaredEnvironments = createStore<Readonly<Record<string, EnvironmentSpec>>>({})
+
+/** The environment kinds of the other execution plugins, whose named executors do not say where they run. */
+const KINDS: Record<string, RunsIn['kind']> = { wasi: 'browser', webgpu: 'browser', devcontainer: 'machine', jupyter: 'remote' }
+
+/** Where the executor runs code: its own `runsIn`, or for a named environment the kind the headmatter declares. */
+export function runsInOf(executorId: string | undefined, executor?: Executor): RunsIn | undefined {
+  if (!executorId) return undefined
+  const prefix = environmentExecutor('')
+  if (executorId.startsWith(prefix)) {
+    const name = executorId.slice(prefix.length)
+    const kind = executor?.runsIn ?? KINDS[declaredEnvironments.getSnapshot()[name]?.kind ?? ''] ?? 'environment'
+    return kind === 'browser' || kind === 'machine' ? { kind } : { kind, name }
+  }
+  return executor?.runsIn ? { kind: executor.runsIn } : undefined
+}