@simulatte/webgpu 0.3.0 → 0.3.2

package/src/bun.js

@@ -1,6 +1,6 @@
 import * as ffi from "./bun-ffi.js";
 import * as full from "./full.js";
-import { createDoeNamespace } from "./doe.js";
+import { createDoeNamespace } from "@simulatte/webgpu-doe";
 
 const runtime = process.platform === "linux" ? ffi : full;
 
@@ -14,10 +14,14 @@ export const setupGlobals = runtime.setupGlobals;
 export const requestAdapter = runtime.requestAdapter;
 export const requestDevice = runtime.requestDevice;
 export const providerInfo = runtime.providerInfo;
+export const preflightShaderSource = runtime.preflightShaderSource ?? full.preflightShaderSource;
+export const setNativeTimeoutMs = runtime.setNativeTimeoutMs ?? full.setNativeTimeoutMs;
 export const createDoeRuntime = runtime.createDoeRuntime;
 export const runDawnVsDoeCompare = runtime.runDawnVsDoeCompare;
 
 export default {
   ...runtime,
+  preflightShaderSource,
+  setNativeTimeoutMs,
   doe,
 };

package/src/compute.d.ts

@@ -1,9 +1,9 @@
 import type {
   BoundDoeNamespace,
   DoeKernelDispatchOptions,
+  DoeKernelCreateOptions,
   DoeNamespace,
-  DoeRunComputeOptions,
-} from "./doe.js";
+} from "@simulatte/webgpu-doe";
 import type {
   DoeRuntime,
   DoeRuntimeRunResult,
@@ -107,7 +107,7 @@ export interface RequestDeviceOptions {
   createArgs?: string[] | null;
 }
 
-export interface ComputeDoeRunComputeOptions extends DoeRunComputeOptions<ComputeGPUBuffer> {}
+export interface ComputeDoeKernelCreateOptions extends DoeKernelCreateOptions<ComputeGPUBuffer> {}
 
 export interface ComputeDoeKernelDispatchOptions extends DoeKernelDispatchOptions<ComputeGPUBuffer> {}
 
@@ -118,15 +118,12 @@ export interface ComputeDoeKernel {
 }
 
 export interface ComputeBoundDoeNamespace
-  extends BoundDoeNamespace<ComputeGPUDevice, ComputeGPUBuffer, ComputeDoeKernel, ComputeDoeRunComputeOptions> {}
+  extends BoundDoeNamespace<ComputeGPUDevice, ComputeGPUBuffer, ComputeDoeKernel, ComputeDoeKernelCreateOptions> {}
 
 export interface ComputeDoeNamespace
   extends DoeNamespace<
     ComputeGPUDevice,
-    ComputeGPUBuffer,
-    ComputeDoeKernel,
     ComputeBoundDoeNamespace,
-    ComputeDoeRunComputeOptions,
     RequestDeviceOptions
   > {}
 
@@ -144,6 +141,16 @@ export function createDoeRuntime(options?: {
   libPath?: string;
 }): DoeRuntime;
 export function runDawnVsDoeCompare(options: Record<string, unknown>): DoeRuntimeRunResult;
+export function preflightShaderSource(code: string): {
+  ok: boolean;
+  stage: string;
+  kind: string;
+  message: string;
+  reasons: string[];
+  line?: number;
+  column?: number;
+};
+export function setNativeTimeoutMs(ms: number): void;
 
 export const doe: ComputeDoeNamespace;
 
@@ -156,6 +163,8 @@ declare const _default: {
   providerInfo: typeof providerInfo;
   createDoeRuntime: typeof createDoeRuntime;
   runDawnVsDoeCompare: typeof runDawnVsDoeCompare;
+  preflightShaderSource: typeof preflightShaderSource;
+  setNativeTimeoutMs: typeof setNativeTimeoutMs;
   doe: ComputeDoeNamespace;
 };
 

package/src/compute.js

@@ -1,11 +1,11 @@
 import * as full from './index.js';
-import { createDoeNamespace } from './doe.js';
+import { createDoeNamespace } from '@simulatte/webgpu-doe';
 
 function unwrap(value) {
   return value && typeof value === 'object' && '_raw' in value ? value._raw : value;
 }
 
-function wrap_buffer(raw) {
+function wrapBuffer(raw) {
   return {
     _raw: raw,
     size: raw.size,
@@ -100,19 +100,19 @@ function wrap_buffer(raw) {
   };
 }
 
-function wrap_bind_group_layout(raw) {
+function wrapBindGroupLayout(raw) {
   return { _raw: raw };
 }
 
-function wrap_bind_group(raw) {
+function wrapBindGroup(raw) {
   return { _raw: raw };
 }
 
-function wrap_pipeline_layout(raw) {
+function wrapPipelineLayout(raw) {
   return { _raw: raw };
 }
 
-function wrap_compute_pipeline(raw) {
+function wrapComputePipeline(raw) {
   return {
     _raw: raw,
     /**
@@ -131,12 +131,12 @@ function wrap_compute_pipeline(raw) {
      * - The returned layout is wrapped back into the compute facade.
      */
     getBindGroupLayout(index) {
-      return wrap_bind_group_layout(raw.getBindGroupLayout(index));
+      return wrapBindGroupLayout(raw.getBindGroupLayout(index));
     },
   };
 }
 
-function wrap_compute_pass(raw) {
+function wrapComputePass(raw) {
   return {
     _raw: raw,
     /**
@@ -246,7 +246,7 @@ function wrap_compute_pass(raw) {
   };
 }
 
-function wrap_command_encoder(raw) {
+function wrapCommandEncoder(raw) {
   return {
     _raw: raw,
     /**
@@ -264,7 +264,7 @@ function wrap_command_encoder(raw) {
      * - The returned pass is wrapped back into the compute facade.
      */
     beginComputePass(descriptor) {
-      return wrap_compute_pass(raw.beginComputePass(descriptor));
+      return wrapComputePass(raw.beginComputePass(descriptor));
     },
     /**
      * Record a buffer-to-buffer copy.
@@ -336,7 +336,7 @@ function wrap_command_encoder(raw) {
   };
 }
 
-function wrap_queue(raw) {
+function wrapQueue(raw) {
   return {
     _raw: raw,
     /**
@@ -394,7 +394,7 @@ function wrap_queue(raw) {
   };
 }
 
-function wrap_query_set(raw) {
+function wrapQuerySet(raw) {
   return {
     _raw: raw,
     /**
@@ -417,10 +417,10 @@ function wrap_query_set(raw) {
   };
 }
 
-function wrap_device(raw) {
+function wrapDevice(raw) {
   return {
     _raw: raw,
-    queue: wrap_queue(raw.queue),
+    queue: wrapQueue(raw.queue),
     limits: raw.limits,
     features: raw.features,
     /**
@@ -441,7 +441,7 @@ function wrap_device(raw) {
      * - The returned buffer is wrapped back into the compute facade.
      */
     createBuffer(descriptor) {
-      return wrap_buffer(raw.createBuffer(descriptor));
+      return wrapBuffer(raw.createBuffer(descriptor));
     },
     /**
      * Create a shader module from WGSL source.
@@ -479,7 +479,7 @@ function wrap_device(raw) {
      */
     createComputePipeline(descriptor) {
       const compute = descriptor.compute ?? {};
-      return wrap_compute_pipeline(raw.createComputePipeline({
+      return wrapComputePipeline(raw.createComputePipeline({
         ...descriptor,
         layout: descriptor.layout === 'auto' ? 'auto' : unwrap(descriptor.layout),
         compute: {
@@ -503,7 +503,15 @@ function wrap_device(raw) {
      * - The returned pipeline is wrapped back into the compute facade.
      */
     async createComputePipelineAsync(descriptor) {
-      return wrap_compute_pipeline(await raw.createComputePipelineAsync(descriptor));
+      const compute = descriptor.compute ?? {};
+      return wrapComputePipeline(await raw.createComputePipelineAsync({
+        ...descriptor,
+        layout: descriptor.layout === 'auto' ? 'auto' : unwrap(descriptor.layout),
+        compute: {
+          ...compute,
+          module: unwrap(compute.module),
+        },
+      }));
     },
     /**
      * Create a bind-group layout.
@@ -520,7 +528,7 @@ function wrap_device(raw) {
      * - The returned layout is wrapped for compute-surface use.
      */
     createBindGroupLayout(descriptor) {
-      return wrap_bind_group_layout(raw.createBindGroupLayout(descriptor));
+      return wrapBindGroupLayout(raw.createBindGroupLayout(descriptor));
     },
     /**
      * Create a bind group.
@@ -543,7 +551,7 @@ function wrap_device(raw) {
           ? { ...entry.resource, buffer: unwrap(entry.resource.buffer) }
           : entry.resource,
       }));
-      return wrap_bind_group(raw.createBindGroup({
+      return wrapBindGroup(raw.createBindGroup({
         ...descriptor,
         layout: unwrap(descriptor.layout),
         entries,
@@ -564,7 +572,7 @@ function wrap_device(raw) {
      * - Wrapped bind-group layouts are unwrapped before creation.
      */
     createPipelineLayout(descriptor) {
-      return wrap_pipeline_layout(raw.createPipelineLayout({
+      return wrapPipelineLayout(raw.createPipelineLayout({
         ...descriptor,
         bindGroupLayouts: (descriptor.bindGroupLayouts ?? []).map(unwrap),
       }));
@@ -584,7 +592,7 @@ function wrap_device(raw) {
      * - The returned encoder is wrapped back into the compute facade.
      */
     createCommandEncoder(descriptor) {
-      return wrap_command_encoder(raw.createCommandEncoder(descriptor));
+      return wrapCommandEncoder(raw.createCommandEncoder(descriptor));
     },
     /**
      * Create a query set.
@@ -604,7 +612,7 @@ function wrap_device(raw) {
       if (typeof raw.createQuerySet !== 'function') {
         throw new Error('query sets are unsupported on the compute surface');
       }
-      return wrap_query_set(raw.createQuerySet(descriptor));
+      return wrapQuerySet(raw.createQuerySet(descriptor));
     },
     /**
      * Release the wrapped device.
@@ -626,7 +634,7 @@ function wrap_device(raw) {
   };
 }
 
-function wrap_adapter(raw) {
+function wrapAdapter(raw) {
   return {
     _raw: raw,
     features: raw.features,
@@ -646,7 +654,7 @@ function wrap_adapter(raw) {
      * - The wrapped device intentionally omits render and surface APIs.
      */
     async requestDevice(descriptor) {
-      return wrap_device(await raw.requestDevice(descriptor));
+      return wrapDevice(await raw.requestDevice(descriptor));
     },
     /**
      * Release the wrapped adapter.
@@ -667,7 +675,7 @@ function wrap_adapter(raw) {
   };
 }
 
-function wrap_gpu(raw) {
+function wrapGpu(raw) {
   return {
     _raw: raw,
     /**
@@ -685,7 +693,7 @@ function wrap_gpu(raw) {
      * - The wrapped adapter later produces compute-only devices.
      */
     async requestAdapter(options) {
-      return wrap_adapter(await raw.requestAdapter(options));
+      return wrapAdapter(await raw.requestAdapter(options));
     },
   };
 }
@@ -728,7 +736,7 @@ export const globals = full.globals;
  * - The returned device intentionally omits render, sampler, and surface methods.
  */
 export function create(createArgs = null) {
-  return wrap_gpu(full.create(createArgs));
+  return wrapGpu(full.create(createArgs));
 }
 
 /**
@@ -803,8 +811,12 @@ export async function requestAdapter(adapterOptions = undefined, createArgs = nu
 /**
  * Request a compute-only device facade from the Doe runtime.
  *
- * This requests an adapter, then wraps the resulting device so only the
- * compute-side JS surface is exposed.
+ * Surface: Direct WebGPU compute package surface.
+ * Input: Optional adapter, device, and package creation options.
+ * Returns: A promise for a compute-only device facade.
+ *
+ * This requests an adapter and then wraps the resulting raw device so the
+ * package exposes only the compute-side JS surface.
  *
  * This example shows the API in its basic form.
  *
@@ -812,11 +824,12 @@ export async function requestAdapter(adapterOptions = undefined, createArgs = nu
  * import { requestDevice } from "@simulatte/webgpu/compute";
  *
  * const device = await requestDevice();
- * console.log(typeof device.createRenderPipeline); // "undefined"
+ * console.log(typeof device.createRenderPipeline);
  * ```
  *
- * - The facade hides render, sampler, and surface methods even if the underlying runtime has them.
- * - Buffer and queue operations remain available for upload, dispatch, copy, and readback workflows.
+ * - The facade hides render, sampler, and surface methods even if the runtime has them.
+ * - Buffer and queue operations remain available for upload, dispatch, copy, and readback.
+ * - See `doe.requestDevice(...)` for the bound Doe API entrypoint over this same device.
  */
 export async function requestDevice(options = {}) {
   const adapter = await requestAdapter(options?.adapterOptions, options?.createArgs ?? null);
@@ -824,15 +837,15 @@ export async function requestDevice(options = {}) {
 }
 
 /**
- * Shared Doe API / Doe routines namespace for the compute package surface.
+ * Shared Doe API namespace for the compute package surface.
  *
- * This exposes `await doe.requestDevice()` for the one-line Doe API entry,
- * `doe.bind(device)` when you already have a device, `doe.buffers.*` and
- * `doe.compute.run(...)` / `doe.compute.compile(...)` for the `Doe API`
- * surface, and `doe.compute.once(...)` for `Doe routines`.
+ * Surface: Doe API on `@simulatte/webgpu/compute`.
+ * Input: Called through `doe.requestDevice(...)` or `doe.bind(device)`.
+ * Returns: A bound `gpu` helper object over a compute-only device facade.
  *
- * The exported `doe` object here is the JS convenience surface over the Doe
- * runtime, not a separate runtime.
+ * This is the JS convenience surface over the compute package. Both entry
+ * points return the same bound `gpu` object, with `gpu.buffer.*`,
+ * `gpu.kernel.*`, and a single `gpu.compute(...)` helper.
  *
  * This example shows the API in its basic form.
  *
@@ -840,21 +853,27 @@ export async function requestDevice(options = {}) {
  * import { doe } from "@simulatte/webgpu/compute";
  *
  * const gpu = await doe.requestDevice();
- * const src = gpu.buffers.fromData(new Float32Array([1, 2, 3, 4]));
- * const dst = gpu.buffers.like(src, { usage: "storageReadWrite" });
+ * const src = gpu.buffer.create({ data: new Float32Array([1, 2, 3, 4]) });
+ * const dst = gpu.buffer.create({ size: src.size, usage: "storageReadWrite" });
  * ```
  *
- * - This Doe API and Doe routines shape is shared with the full package surface; the difference is the raw device returned underneath.
- * - `gpu.compute.once(...)` is intentionally narrow and rejects raw numeric usage flags; drop to `gpu.buffers.*` if you need explicit raw control.
+ * - This helper shape matches the full package `doe`; only the raw device underneath differs.
+ * - `gpu.compute(...)` is the narrowest helper; drop to `gpu.kernel.*` for explicit control.
+ * - See `requestDevice(...)` when you want the compute-only raw facade without Doe helpers.
  */
 export const doe = createDoeNamespace({
   requestDevice,
 });
 
 /**
- * Report how the compute package surface resolved the Doe runtime.
+ * Report how the compute package resolved the Doe runtime.
  *
- * This re-exports the same provenance report as the full package.
+ * Surface: Package runtime metadata.
+ * Input: None.
+ * Returns: A provenance object describing the loaded Doe provider.
+ *
+ * This re-exports the same runtime provenance report as the full package so
+ * callers can inspect which native library and package path were selected.
  *
  * This example shows the API in its basic form.
  *
@@ -864,14 +883,19 @@ export const doe = createDoeNamespace({
  * console.log(providerInfo().loaded);
  * ```
  *
- * - The report describes the shared package/runtime load path, not the compute facade wrapper itself.
+ * - The report describes runtime loading, not the compute facade wrapper itself.
+ * - The shape is shared with `@simulatte/webgpu`.
  */
 export const providerInfo = full.providerInfo;
 /**
- * Create a Node/Bun runtime wrapper for Doe CLI execution from the compute package.
+ * Create a Doe CLI/runtime wrapper from the compute package.
+ *
+ * Surface: Package tooling and runtime orchestration.
+ * Input: Optional runtime configuration accepted by the shared runtime helper.
+ * Returns: A Doe runtime wrapper for CLI-style execution paths.
  *
- * This re-exports the same runtime CLI helper as the full package for
- * benchmark and command-stream execution workflows.
+ * This re-exports the same runtime wrapper as the full package for benchmark,
+ * trace, and command-stream execution workflows.
  *
  * This example shows the API in its basic form.
  *
@@ -881,13 +905,19 @@ export const providerInfo = full.providerInfo;
  * const runtime = createDoeRuntime();
  * ```
  *
- * - This is package/runtime orchestration, not the in-process compute facade.
+ * - This is package/runtime orchestration, not the in-process `gpu.*` helper surface.
+ * - See `runDawnVsDoeCompare(...)` for the packaged compare entrypoint.
  */
 export const createDoeRuntime = full.createDoeRuntime;
 /**
- * Run the Dawn-vs-Doe compare harness from the compute package surface.
+ * Run the Dawn-vs-Doe compare harness from the compute package.
+ *
+ * Surface: Package benchmarking and artifact tooling.
+ * Input: Compare options or forwarded CLI arguments.
+ * Returns: The compare harness result from the shared tooling layer.
  *
- * This re-exports the compare wrapper used for artifact-backed benchmark runs.
+ * This re-exports the benchmark compare wrapper used for artifact-backed
+ * Dawn-vs-Doe performance runs.
  *
  * This example shows the API in its basic form.
  *
@@ -898,7 +928,8 @@ export const createDoeRuntime = full.createDoeRuntime;
  * ```
  *
  * - Requires an explicit compare config path either in options or forwarded CLI args.
- * - This is a tooling entrypoint, not the in-process `doe.compute.*` helper path.
+ * - This is a tooling entrypoint, not the in-process `gpu.compute(...)` helper path.
+ * - See `createDoeRuntime()` for lower-level runtime orchestration.
  */
 export const runDawnVsDoeCompare = full.runDawnVsDoeCompare;
 

package/src/full.d.ts

@@ -1,9 +1,9 @@
 import type {
   BoundDoeNamespace,
   DoeKernelDispatchOptions,
+  DoeKernelCreateOptions,
   DoeNamespace,
-  DoeRunComputeOptions,
-} from "./doe.js";
+} from "@simulatte/webgpu-doe";
 
 export interface ProviderInfo {
   module: string;
@@ -64,7 +64,7 @@ export interface RequestDeviceOptions {
   createArgs?: string[] | null;
 }
 
-export interface FullDoeRunComputeOptions extends DoeRunComputeOptions<GPUBuffer> {}
+export interface FullDoeKernelCreateOptions extends DoeKernelCreateOptions<GPUBuffer> {}
 
 export interface FullDoeKernelDispatchOptions extends DoeKernelDispatchOptions<GPUBuffer> {}
 
@@ -75,15 +75,12 @@ export interface FullDoeKernel {
 }
 
 export interface FullBoundDoeNamespace
-  extends BoundDoeNamespace<GPUDevice, GPUBuffer, FullDoeKernel, FullDoeRunComputeOptions> {}
+  extends BoundDoeNamespace<GPUDevice, GPUBuffer, FullDoeKernel, FullDoeKernelCreateOptions> {}
 
 export interface FullDoeNamespace
   extends DoeNamespace<
     GPUDevice,
-    GPUBuffer,
-    FullDoeKernel,
     FullBoundDoeNamespace,
-    FullDoeRunComputeOptions,
     RequestDeviceOptions
   > {}
 
@@ -101,6 +98,16 @@ export function createDoeRuntime(options?: {
   libPath?: string;
 }): DoeRuntime;
 export function runDawnVsDoeCompare(options: Record<string, unknown>): DoeRuntimeRunResult;
+export function preflightShaderSource(code: string): {
+  ok: boolean;
+  stage: string;
+  kind: string;
+  message: string;
+  reasons: string[];
+  line?: number;
+  column?: number;
+};
+export function setNativeTimeoutMs(ms: number): void;
 
 export const doe: FullDoeNamespace;
 
@@ -113,6 +120,8 @@ declare const _default: {
   providerInfo: typeof providerInfo;
   createDoeRuntime: typeof createDoeRuntime;
   runDawnVsDoeCompare: typeof runDawnVsDoeCompare;
+  preflightShaderSource: typeof preflightShaderSource;
+  setNativeTimeoutMs: typeof setNativeTimeoutMs;
   doe: FullDoeNamespace;
 };
 

package/src/full.js

@@ -1,16 +1,17 @@
 import * as full from './index.js';
-import { createDoeNamespace } from './doe.js';
+import { createDoeNamespace } from '@simulatte/webgpu-doe';
 
 /**
- * Shared Doe API / Doe routines namespace for the full package surface.
+ * Shared Doe API namespace for the full package surface.
  *
- * This exposes `await doe.requestDevice()` for the one-line Doe API entry,
- * `doe.bind(device)` when you already have a full device, `doe.buffers.*` and
- * `doe.compute.run(...)` / `doe.compute.compile(...)` for the `Doe API`
- * surface, and `doe.compute.once(...)` for `Doe routines`.
+ * Surface: Doe API on `@simulatte/webgpu`.
+ * Input: Called through `doe.requestDevice(...)` or `doe.bind(device)`.
+ * Returns: A bound `gpu` helper object over a full raw device.
  *
- * The exported `doe` object here is the JS convenience surface over the Doe
- * runtime, not a separate runtime.
+ * This is the JS convenience surface over the full package. Both entry points
+ * return the same bound `gpu` object, with `gpu.buffer.*`, `gpu.kernel.*`,
+ * and a single `gpu.compute(...)` helper, while still leaving the underlying
+ * raw device reachable as `gpu.device`.
  *
  * This example shows the API in its basic form.
  *
@@ -20,8 +21,9 @@ import { createDoeNamespace } from './doe.js';
  * const gpu = await doe.requestDevice();
  * ```
  *
- * - The Doe API and Doe routines shape is the same as `@simulatte/webgpu/compute`; the difference is that the underlying device here stays full-surface rather than compute-only.
- * - If you need explicit render, sampler, or surface APIs, keep the raw device from `requestDevice()` or access `gpu.device` after `doe.requestDevice()`.
+ * - The Doe helper shape matches `@simulatte/webgpu/compute`; the difference is the raw device underneath.
+ * - If you need explicit render, sampler, or surface APIs, use `gpu.device`.
+ * - See the package `requestDevice()` export when you want the raw full device without Doe helpers.
  */
 export const doe = createDoeNamespace({
   requestDevice: full.requestDevice,