@aethervtt/shard-gpu 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-gpu
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/buffer.d.ts

@@ -0,0 +1,32 @@
+import type { GpuContext } from './context.js';
+export interface GpuBufferOptions {
+    label: string;
+    usage: GPUBufferUsageFlags;
+    /** Initial size in bytes. Default 256. */
+    size?: number;
+}
+/**
+ * A GPU buffer that grows. `ensureCapacity` doubles the size when needed; `version` increments
+ * every time the underlying `GPUBuffer` is replaced, so bind groups built on it know to rebuild.
+ * Contents are not preserved across growth or device loss: rewrite them each frame.
+ */
+export declare class GpuBuffer {
+    readonly label: string;
+    readonly usage: GPUBufferUsageFlags;
+    version: number;
+    private current;
+    private size;
+    private generation;
+    private readonly gpu;
+    constructor(gpu: GpuContext, options: GpuBufferOptions);
+    get buffer(): GPUBuffer;
+    get byteLength(): number;
+    /** Grows to at least `bytes`. Returns true if the buffer was replaced. */
+    ensureCapacity(bytes: number): boolean;
+    /** Writes a TypedArray (or a slice of it, in elements) at a byte offset, growing if needed. */
+    write(data: ArrayBufferView & ArrayLike<number>, byteOffset?: number, start?: number, count?: number): void;
+    destroy(): void;
+    private create;
+    /** After device loss the old buffer is gone; make a new one on the new device. */
+    private checkGeneration;
+}

package/dist/buffer.js

@@ -0,0 +1,64 @@
+class GpuBuffer {
+  label;
+  usage;
+  version = 0;
+  current;
+  size;
+  generation;
+  gpu;
+  constructor(gpu, options) {
+    this.gpu = gpu;
+    this.label = options.label;
+    this.usage = options.usage | GPUBufferUsage.COPY_DST;
+    this.size = align4(Math.max(16, options.size ?? 256));
+    this.generation = gpu.generation;
+    this.current = this.create(this.size);
+  }
+  get buffer() {
+    this.checkGeneration();
+    return this.current;
+  }
+  get byteLength() {
+    return this.size;
+  }
+  /** Grows to at least `bytes`. Returns true if the buffer was replaced. */
+  ensureCapacity(bytes) {
+    this.checkGeneration();
+    if (bytes <= this.size) return false;
+    let size = this.size;
+    while (size < bytes) size *= 2;
+    this.current.destroy();
+    this.size = size;
+    this.current = this.create(size);
+    this.version++;
+    return true;
+  }
+  /** Writes a TypedArray (or a slice of it, in elements) at a byte offset, growing if needed. */
+  write(data, byteOffset = 0, start = 0, count) {
+    const elements = count ?? data.length - start;
+    const bytesPerElement = data.BYTES_PER_ELEMENT;
+    const bytes = align4(elements * bytesPerElement);
+    this.ensureCapacity(byteOffset + bytes);
+    if (elements > 0)
+      this.gpu.device.queue.writeBuffer(this.current, byteOffset, data, start, elements);
+  }
+  destroy() {
+    this.current.destroy();
+  }
+  create(size) {
+    return this.gpu.device.createBuffer({ label: this.label, size, usage: this.usage });
+  }
+  /** After device loss the old buffer is gone; make a new one on the new device. */
+  checkGeneration() {
+    if (this.generation === this.gpu.generation) return;
+    this.generation = this.gpu.generation;
+    this.current = this.create(this.size);
+    this.version++;
+  }
+}
+function align4(n) {
+  return n + 3 & ~3;
+}
+export {
+  GpuBuffer
+};

package/dist/caches.d.ts

@@ -0,0 +1,36 @@
+import type { ShardError } from '@aethervtt/shard-core';
+import type { GpuContext } from './context.js';
+/**
+ * Render and compute pipelines, created asynchronously and cached by descriptor. `render()` returns
+ * undefined until the pipeline is ready; callers skip that draw for the frame instead of stalling.
+ */
+export declare class PipelineCache {
+    /** Draws skipped because their pipeline was still compiling. Reset by the renderer each frame. */
+    skipped: number;
+    private readonly render_;
+    private readonly compute_;
+    private readonly gpu;
+    constructor(gpu: GpuContext);
+    render(descriptor: GPURenderPipelineDescriptor): GPURenderPipeline | undefined;
+    compute(descriptor: GPUComputePipelineDescriptor): GPUComputePipeline | undefined;
+    /** Pipelines still compiling. */
+    get pending(): number;
+    /** Resolves when every pipeline requested so far has finished compiling (or failed). */
+    whenIdle(): Promise<void>;
+    /** Errors from pipelines that failed to compile, by label. */
+    failures(): ShardError[];
+    clear(): void;
+    private get;
+}
+/** Bind group layouts, pipeline layouts, and samplers: equal descriptors give the same object. */
+export declare class LayoutCache {
+    private readonly bindGroupLayouts;
+    private readonly pipelineLayouts;
+    private readonly samplers;
+    private readonly gpu;
+    constructor(gpu: GpuContext);
+    bindGroupLayout(descriptor: GPUBindGroupLayoutDescriptor): GPUBindGroupLayout;
+    pipelineLayout(descriptor: GPUPipelineLayoutDescriptor): GPUPipelineLayout;
+    sampler(descriptor?: GPUSamplerDescriptor): GPUSampler;
+    clear(): void;
+}

package/dist/caches.js

@@ -0,0 +1,111 @@
+import { toShardError } from "./errors.js";
+import { descriptorKey } from "./key.js";
+class PipelineCache {
+  /** Draws skipped because their pipeline was still compiling. Reset by the renderer each frame. */
+  skipped = 0;
+  render_ = /* @__PURE__ */ new Map();
+  compute_ = /* @__PURE__ */ new Map();
+  gpu;
+  constructor(gpu) {
+    this.gpu = gpu;
+  }
+  render(descriptor) {
+    return this.get(this.render_, descriptor, (d) => this.gpu.device.createRenderPipelineAsync(d));
+  }
+  compute(descriptor) {
+    return this.get(this.compute_, descriptor, (d) => this.gpu.device.createComputePipelineAsync(d));
+  }
+  /** Pipelines still compiling. */
+  get pending() {
+    let n = 0;
+    for (const s of this.render_.values()) if (s.status === "pending") n++;
+    for (const s of this.compute_.values()) if (s.status === "pending") n++;
+    return n;
+  }
+  /** Resolves when every pipeline requested so far has finished compiling (or failed). */
+  async whenIdle() {
+    const pending = [];
+    for (const s of [...this.render_.values(), ...this.compute_.values()]) {
+      if (s.status === "pending") pending.push(s.promise);
+    }
+    await Promise.all(pending);
+  }
+  /** Errors from pipelines that failed to compile, by label. */
+  failures() {
+    const out = [];
+    for (const s of [...this.render_.values(), ...this.compute_.values()]) {
+      if (s.status === "failed") out.push(s.error);
+    }
+    return out;
+  }
+  clear() {
+    this.render_.clear();
+    this.compute_.clear();
+  }
+  get(map, descriptor, create) {
+    const key = descriptorKey(descriptor);
+    const state = map.get(key);
+    if (state?.status === "ready") return state.pipeline;
+    if (state) {
+      this.skipped++;
+      return void 0;
+    }
+    const promise = create(descriptor).then(
+      (pipeline) => {
+        map.set(key, { status: "ready", pipeline });
+      },
+      (err) => {
+        const error = toShardError(err, descriptor.label);
+        map.set(key, { status: "failed", error });
+        this.gpu.reportError(error);
+      }
+    );
+    map.set(key, { status: "pending", promise });
+    this.skipped++;
+    return void 0;
+  }
+}
+class LayoutCache {
+  bindGroupLayouts = /* @__PURE__ */ new Map();
+  pipelineLayouts = /* @__PURE__ */ new Map();
+  samplers = /* @__PURE__ */ new Map();
+  gpu;
+  constructor(gpu) {
+    this.gpu = gpu;
+  }
+  bindGroupLayout(descriptor) {
+    return cached(
+      this.bindGroupLayouts,
+      descriptor,
+      () => this.gpu.device.createBindGroupLayout(descriptor)
+    );
+  }
+  pipelineLayout(descriptor) {
+    return cached(
+      this.pipelineLayouts,
+      descriptor,
+      () => this.gpu.device.createPipelineLayout(descriptor)
+    );
+  }
+  sampler(descriptor = {}) {
+    return cached(this.samplers, descriptor, () => this.gpu.device.createSampler(descriptor));
+  }
+  clear() {
+    this.bindGroupLayouts.clear();
+    this.pipelineLayouts.clear();
+    this.samplers.clear();
+  }
+}
+function cached(map, descriptor, create) {
+  const key = descriptorKey(descriptor);
+  let value = map.get(key);
+  if (!value) {
+    value = create();
+    map.set(key, value);
+  }
+  return value;
+}
+export {
+  LayoutCache,
+  PipelineCache
+};

package/dist/context.d.ts

@@ -0,0 +1,66 @@
+import { ShardError } from '@aethervtt/shard-core';
+import { LayoutCache, PipelineCache } from './caches.js';
+import { type GpuErrorListener } from './errors.js';
+export interface CreateGpuContextOptions {
+    /** Omit for offscreen/headless rendering. */
+    canvas?: HTMLCanvasElement | OffscreenCanvas;
+    /** The WebGPU entry point. Defaults to `navigator.gpu`; in Node pass the `webgpu` package's. */
+    gpu?: GPU;
+    /** Requested if the adapter supports them. */
+    features?: GPUFeatureName[];
+    /** Fails with `gpu/missing-feature` if the adapter lacks any. */
+    requiredFeatures?: GPUFeatureName[];
+    powerPreference?: GPUPowerPreference;
+    /**
+     * Request block-compressed texture formats (BC, ASTC, ETC2) when the adapter has them. Default
+     * true; Basis textures transcode to whichever the device ends up with.
+     */
+    compressedTextures?: boolean;
+}
+export interface DeviceLostInfo {
+    reason: string;
+    message: string;
+}
+/**
+ * The adapter, device, and optional canvas, plus the caches every renderer needs. After a device
+ * loss, `recreate()` gets a new device and bumps `generation`; `GpuBuffer`s and caches rebuild
+ * against it.
+ */
+export declare class GpuContext {
+    adapter: GPUAdapter;
+    device: GPUDevice;
+    readonly format: GPUTextureFormat;
+    readonly canvas: HTMLCanvasElement | OffscreenCanvas | undefined;
+    readonly context: GPUCanvasContext | undefined;
+    readonly features: ReadonlySet<string>;
+    readonly pipelines: PipelineCache;
+    readonly layouts: LayoutCache;
+    /** Increments when the device is replaced. */
+    generation: number;
+    /** Canvas pixels per CSS pixel (devicePixelRatio) at the last resize; 1 without a canvas. */
+    pixelRatio: number;
+    /** Most recent GPU errors, newest last. */
+    readonly errors: ShardError[];
+    private readonly options;
+    private readonly errorListeners;
+    private readonly lostListeners;
+    constructor(options: CreateGpuContextOptions, adapter: GPUAdapter, device: GPUDevice, format: GPUTextureFormat, context: GPUCanvasContext | undefined);
+    /** Match the canvas backing size to its CSS size. Returns true if it changed. */
+    resize(): boolean;
+    onError(listener: GpuErrorListener): () => void;
+    onDeviceLost(listener: (info: DeviceLostInfo) => void): () => void;
+    reportError(error: ShardError): void;
+    /**
+     * Runs `fn` inside a validation error scope. Errors are reported asynchronously (WebGPU
+     * resolves error scopes later) with `label` naming the object.
+     */
+    validate<T>(label: string, fn: () => T): T;
+    /** Gets a fresh adapter and device after a loss, and reconfigures the canvas. */
+    recreate(): Promise<void>;
+    /** For tests and debugging: destroys the device and reports it as an unexpected loss. */
+    simulateDeviceLoss(): void;
+    destroy(): void;
+    private attach;
+    private handleLoss;
+}
+export declare function createGpuContext(options?: CreateGpuContextOptions): Promise<GpuContext>;

package/dist/context.js

@@ -0,0 +1,173 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { LayoutCache, PipelineCache } from "./caches.js";
+import { toShardError } from "./errors.js";
+const COMPRESSED_TEXTURE_FEATURES = [
+  "texture-compression-bc",
+  "texture-compression-astc",
+  "texture-compression-etc2"
+];
+const RENDERER_FEATURES = [
+  "rg11b10ufloat-renderable",
+  "indirect-first-instance",
+  "float32-filterable"
+];
+const MAX_ERRORS = 50;
+class GpuContext {
+  adapter;
+  device;
+  format;
+  canvas;
+  context;
+  features;
+  pipelines;
+  layouts;
+  /** Increments when the device is replaced. */
+  generation = 0;
+  /** Canvas pixels per CSS pixel (devicePixelRatio) at the last resize; 1 without a canvas. */
+  pixelRatio = 1;
+  /** Most recent GPU errors, newest last. */
+  errors = [];
+  options;
+  errorListeners = /* @__PURE__ */ new Set();
+  lostListeners = /* @__PURE__ */ new Set();
+  constructor(options, adapter, device, format, context) {
+    this.options = options;
+    this.adapter = adapter;
+    this.device = device;
+    this.format = format;
+    this.canvas = options.canvas;
+    this.context = context;
+    this.features = new Set(device.features);
+    this.pipelines = new PipelineCache(this);
+    this.layouts = new LayoutCache(this);
+    this.attach(device);
+  }
+  /** Match the canvas backing size to its CSS size. Returns true if it changed. */
+  resize() {
+    const canvas = this.canvas;
+    if (!canvas || !("clientWidth" in canvas)) return false;
+    const dpr = globalThis.devicePixelRatio ?? 1;
+    this.pixelRatio = dpr;
+    const width = Math.max(1, Math.floor(canvas.clientWidth * dpr));
+    const height = Math.max(1, Math.floor(canvas.clientHeight * dpr));
+    if (canvas.width === width && canvas.height === height) return false;
+    canvas.width = width;
+    canvas.height = height;
+    return true;
+  }
+  onError(listener) {
+    this.errorListeners.add(listener);
+    return () => this.errorListeners.delete(listener);
+  }
+  onDeviceLost(listener) {
+    this.lostListeners.add(listener);
+    return () => this.lostListeners.delete(listener);
+  }
+  reportError(error) {
+    this.errors.push(error);
+    if (this.errors.length > MAX_ERRORS) this.errors.shift();
+    for (const listener of this.errorListeners) listener(error);
+  }
+  /**
+   * Runs `fn` inside a validation error scope. Errors are reported asynchronously (WebGPU
+   * resolves error scopes later) with `label` naming the object.
+   */
+  validate(label, fn) {
+    this.device.pushErrorScope("validation");
+    const result = fn();
+    void this.device.popErrorScope().then((error) => {
+      if (error) this.reportError(toShardError(error, label));
+    });
+    return result;
+  }
+  /** Gets a fresh adapter and device after a loss, and reconfigures the canvas. */
+  async recreate() {
+    const { adapter, device } = await requestDevice(this.options);
+    this.adapter = adapter;
+    this.device = device;
+    this.context?.configure(canvasConfig(device, this.format));
+    this.pipelines.clear();
+    this.layouts.clear();
+    this.generation++;
+    this.attach(device);
+  }
+  /** For tests and debugging: destroys the device and reports it as an unexpected loss. */
+  simulateDeviceLoss() {
+    this.handleLoss({ reason: "unknown", message: "Simulated device loss" });
+    this.device.destroy();
+  }
+  destroy() {
+    this.lostListeners.clear();
+    this.device.destroy();
+  }
+  attach(device) {
+    device.addEventListener("uncapturederror", (event) => {
+      this.reportError(toShardError(event.error, void 0));
+    });
+    void device.lost.then((info) => {
+      if (info.reason !== "destroyed" && device === this.device) {
+        this.handleLoss({ reason: info.reason, message: info.message });
+      }
+    });
+  }
+  handleLoss(info) {
+    for (const listener of this.lostListeners) listener(info);
+  }
+}
+function canvasConfig(device, format) {
+  return {
+    device,
+    format,
+    alphaMode: "opaque",
+    // COPY_SRC lets the renderer capture screenshots straight from the swapchain.
+    usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC
+  };
+}
+async function requestDevice(options) {
+  const gpu = options.gpu ?? globalThis.navigator?.gpu;
+  if (!gpu) {
+    throw new ShardError("gpu/unsupported", "WebGPU is not available in this environment", {
+      hint: "Use a browser or webview with WebGPU, or pass `gpu` (e.g. from the `webgpu` package in Node)."
+    });
+  }
+  const adapter = await gpu.requestAdapter({
+    powerPreference: options.powerPreference ?? "high-performance"
+  });
+  if (!adapter) throw new ShardError("gpu/no-adapter", "No WebGPU adapter was found");
+  const missing = (options.requiredFeatures ?? []).filter((f) => !adapter.features.has(f));
+  if (missing.length > 0) {
+    throw new ShardError(
+      "gpu/missing-feature",
+      `The GPU lacks required features: ${missing.join(", ")}`
+    );
+  }
+  const requiredFeatures = [
+    ...options.requiredFeatures ?? [],
+    ...[
+      ...options.features ?? [],
+      ...RENDERER_FEATURES,
+      ...options.compressedTextures === false ? [] : COMPRESSED_TEXTURE_FEATURES
+    ].filter((f, i, all) => all.indexOf(f) === i && adapter.features.has(f))
+  ];
+  const device = await adapter.requestDevice({ label: "shard", requiredFeatures });
+  return { adapter, device };
+}
+async function createGpuContext(options = {}) {
+  const { adapter, device } = await requestDevice(options);
+  const gpu = options.gpu ?? globalThis.navigator.gpu;
+  const format = gpu.getPreferredCanvasFormat();
+  let context;
+  if (options.canvas) {
+    const ctx = options.canvas.getContext("webgpu");
+    if (!ctx) throw new ShardError("gpu/no-context", "Could not get a WebGPU canvas context");
+    ctx.configure(canvasConfig(device, format));
+    context = ctx;
+  }
+  const result = new GpuContext(options, adapter, device, format, context);
+  result.resize();
+  return result;
+}
+export {
+  GpuContext,
+  createGpuContext
+};

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+import { ShardError } from '@aethervtt/shard-core';
+export type GpuErrorListener = (error: ShardError) => void;
+/** Turns a WebGPU error into a ShardError that names the object involved. */
+export declare function toShardError(error: GPUError | Error, label: string | undefined): ShardError;

package/dist/errors.js

@@ -0,0 +1,16 @@
+import { ShardError } from "@aethervtt/shard-core";
+function toShardError(error, label) {
+  const what = label ? `"${label}"` : "an unlabeled GPU object";
+  const isOom = typeof GPUOutOfMemoryError !== "undefined" && error instanceof GPUOutOfMemoryError;
+  return new ShardError(
+    isOom ? "gpu/out-of-memory" : "gpu/validation",
+    `WebGPU error in ${what}: ${error.message}`,
+    {
+      path: label,
+      hint: label ? void 0 : "Give every GPU object a label so errors can name it."
+    }
+  );
+}
+export {
+  toShardError
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { GpuBuffer, type GpuBufferOptions } from './buffer.js';
+export { LayoutCache, PipelineCache } from './caches.js';
+export { type CreateGpuContextOptions, createGpuContext, type DeviceLostInfo, GpuContext, } from './context.js';
+export { type GpuErrorListener, toShardError } from './errors.js';
+export { descriptorKey } from './key.js';
+export { type ProbeWebGpuOptions, probeWebGpu, type WebGpuSupport, type WebGpuUnsupportedReason, } from './probe.js';

package/dist/index.js

@@ -0,0 +1,21 @@
+import { GpuBuffer } from "./buffer.js";
+import { LayoutCache, PipelineCache } from "./caches.js";
+import {
+  createGpuContext,
+  GpuContext
+} from "./context.js";
+import { toShardError } from "./errors.js";
+import { descriptorKey } from "./key.js";
+import {
+  probeWebGpu
+} from "./probe.js";
+export {
+  GpuBuffer,
+  GpuContext,
+  LayoutCache,
+  PipelineCache,
+  createGpuContext,
+  descriptorKey,
+  probeWebGpu,
+  toShardError
+};

package/dist/key.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A stable string key for a WebGPU descriptor. Plain data is serialized; GPU objects inside it
+ * (shader modules, layouts, bind group layouts) are keyed by identity.
+ */
+export declare function descriptorKey(descriptor: unknown): string;

package/dist/key.js

@@ -0,0 +1,27 @@
+const ids = /* @__PURE__ */ new WeakMap();
+let nextId = 1;
+function idOf(obj) {
+  let id = ids.get(obj);
+  if (id === void 0) {
+    id = nextId++;
+    ids.set(obj, id);
+  }
+  return id;
+}
+function isPlain(value) {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null || Array.isArray(value);
+}
+function descriptorKey(descriptor) {
+  return JSON.stringify(descriptor, (key, value) => {
+    if (key === "label") return void 0;
+    if (value !== null && typeof value === "object" && !isPlain(value)) {
+      if (ArrayBuffer.isView(value)) return Array.from(value);
+      return `#${idOf(value)}`;
+    }
+    return value;
+  });
+}
+export {
+  descriptorKey
+};

package/dist/node.d.ts

@@ -0,0 +1,5 @@
+import { type CreateGpuContextOptions, type GpuContext } from './context.js';
+/** Defines `GPUBufferUsage`, `GPUTextureUsage`, etc. on globalThis, as browsers do. */
+export declare function installWebGpuGlobals(): void;
+export declare function nodeGpu(): GPU;
+export declare function createNodeGpuContext(options?: Omit<CreateGpuContextOptions, 'gpu'>): Promise<GpuContext>;

package/dist/node.js

@@ -0,0 +1,20 @@
+import { create, globals } from "webgpu";
+import { createGpuContext } from "./context.js";
+let installed = false;
+function installWebGpuGlobals() {
+  if (installed) return;
+  Object.assign(globalThis, globals);
+  installed = true;
+}
+function nodeGpu() {
+  installWebGpuGlobals();
+  return create([]);
+}
+function createNodeGpuContext(options = {}) {
+  return createGpuContext({ ...options, gpu: nodeGpu() });
+}
+export {
+  createNodeGpuContext,
+  installWebGpuGlobals,
+  nodeGpu
+};

package/dist/probe.d.ts

@@ -0,0 +1,38 @@
+import { ShardError } from '@aethervtt/shard-core';
+export interface ProbeWebGpuOptions {
+    /** The WebGPU entry point. Defaults to `navigator.gpu`; in Node pass the `webgpu` package's. */
+    gpu?: GPU;
+    /** Features the app can't run without. Missing any makes the result unsupported. */
+    requiredFeatures?: GPUFeatureName[];
+    powerPreference?: GPUPowerPreference;
+    /** Gives up after this long: some drivers never answer `requestAdapter`. Default 5000 ms. */
+    timeoutMs?: number;
+}
+export type WebGpuUnsupportedReason = 'no-webgpu' | 'no-adapter' | 'missing-feature' | 'device-failed' | 'timeout';
+export interface WebGpuSupport {
+    supported: boolean;
+    /** Why not, when unsupported. */
+    reason?: WebGpuUnsupportedReason;
+    /** The same failure as a ShardError, with a hint a host can show. */
+    error?: ShardError;
+    adapter?: {
+        vendor: string;
+        architecture: string;
+        description: string;
+    };
+    /** Every feature the adapter offers. */
+    features: string[];
+    /** Required features the adapter lacks. */
+    missing: string[];
+    limits?: {
+        maxTextureDimension2D: number;
+        maxBufferSize: number;
+        maxStorageBufferBindingSize: number;
+    };
+}
+/**
+ * Checks, before mounting anything, whether this client can run Shard: WebGPU present, an
+ * adapter, the required features, and a device that really opens (it's destroyed again). Never
+ * throws, so a host can show an honest message instead of a blank canvas.
+ */
+export declare function probeWebGpu(options?: ProbeWebGpuOptions): Promise<WebGpuSupport>;

package/dist/probe.js

@@ -0,0 +1,80 @@
+import { ShardError } from "@aethervtt/shard-core";
+const HINTS = {
+  "no-webgpu": "This browser has no WebGPU. Use a current Chrome, Edge, or Safari, or enable WebGPU in its settings.",
+  "no-adapter": "WebGPU is present but found no usable GPU. It may be blocklisted or disabled.",
+  "missing-feature": "The GPU lacks a feature this app requires.",
+  "device-failed": "The GPU was found but refused to create a device.",
+  timeout: "The GPU did not answer in time. Try reloading, or updating the graphics driver."
+};
+const MESSAGES = {
+  "no-webgpu": "WebGPU is not available in this environment",
+  "no-adapter": "No WebGPU adapter was found",
+  "missing-feature": "The GPU lacks required features",
+  "device-failed": "Could not create a WebGPU device",
+  timeout: "WebGPU did not respond in time"
+};
+async function probeWebGpu(options = {}) {
+  const gpu = options.gpu ?? globalThis.navigator?.gpu;
+  const required = options.requiredFeatures ?? [];
+  if (!gpu) return unsupported("no-webgpu", [], []);
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  try {
+    const adapter = await Promise.race([
+      gpu.requestAdapter({ powerPreference: options.powerPreference ?? "high-performance" }),
+      timeout
+    ]).catch(() => null);
+    if (adapter === "timeout") return unsupported("timeout", [], []);
+    if (!adapter) return unsupported("no-adapter", [], []);
+    const features = [...adapter.features].map(String).sort();
+    const missing = required.filter((f) => !adapter.features.has(f));
+    const info = adapter.info;
+    const base = {
+      features,
+      missing,
+      adapter: {
+        vendor: info?.vendor ?? "",
+        architecture: info?.architecture ?? "",
+        description: info?.description ?? ""
+      },
+      limits: {
+        maxTextureDimension2D: adapter.limits.maxTextureDimension2D,
+        maxBufferSize: adapter.limits.maxBufferSize,
+        maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize
+      }
+    };
+    if (missing.length > 0) {
+      return {
+        ...unsupported("missing-feature", features, missing, missing.join(", ")),
+        adapter: base.adapter,
+        limits: base.limits
+      };
+    }
+    const device = await Promise.race([
+      adapter.requestDevice({ label: "shard-probe", requiredFeatures: required }),
+      timeout
+    ]).catch(() => null);
+    if (device === "timeout") return { ...unsupported("timeout", features, []), ...base };
+    if (!device) return { ...unsupported("device-failed", features, []), ...base };
+    device.destroy();
+    return { supported: true, ...base };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function unsupported(reason, features, missing, detail) {
+  const message = detail ? `${MESSAGES[reason]}: ${detail}` : MESSAGES[reason];
+  return {
+    supported: false,
+    reason,
+    error: new ShardError(`gpu/${reason}`, message, { hint: HINTS[reason] }),
+    features,
+    missing
+  };
+}
+export {
+  probeWebGpu
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@aethervtt/shard-gpu",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-core": "0.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/gpu"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  },
+  "peerDependencies": {
+    "webgpu": "0.6.1"
+  },
+  "peerDependenciesMeta": {
+    "webgpu": {
+      "optional": true
+    }
+  }
+}