@derschmale/tiny-helix 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Lenaerts
+
+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,95 @@
+# tiny-helix
+
+A lightweight TypeScript library for WebGPU, built as an ES6 module.
+
+## Quickstart
+
+Install:
+
+```bash
+npm install tiny-helix
+```
+
+Or for development from source:
+
+```bash
+git clone https://github.com/DerSchmale/tiny-helix.git
+cd tiny-helix
+npm install
+npm run build:debug   # builds non-minified debug bundles with source maps
+```
+
+## Usage (browser)
+
+Basic example showing initialization and a simple render loop:
+
+```ts
+import TinyHelix from 'tiny-helix';
+
+const app = new TinyHelix();
+await app.initialize({ canvas: document.querySelector('canvas')! });
+
+function frame() {
+  app.startFrame();
+  const encoder = app.createCommandEncoder('frame-encoder');
+
+  // Simple clear pass: create a render pass, set the clear color and end the pass.
+  // This uses the backbuffer as the default target.
+  const clearPass = encoder.createRenderPass()
+    .withLabel('clear-pass')
+    .withClearColor(0.1, 0.12, 0.15, 1.0) // r,g,b,a
+    .build();
+
+  clearPass.end();
+
+  encoder.submit();
+  requestAnimationFrame(frame);
+}
+
+frame();
+```
+
+## Debug build and source maps
+
+A development-friendly debug build is included. It produces readable, non-minified bundles with full source maps. The debug builds output the following files into `dist/`:
+
+- `tiny-helix.debug.js` + `tiny-helix.debug.js.map` (UMD / CommonJS-like build)
+- `tiny-helix.esm.debug.js` + `tiny-helix.esm.debug.js.map` (ESM build)
+
+To create the debug bundles run:
+
+```bash
+npm run build:debug
+```
+
+The webpack configuration is set up so source maps use `file:///...` absolute file URLs instead of the `webpack://` scheme. This prevents browsers from attempting to resolve `webpack://` sources when consuming the package as a module.
+
+## API overview
+
+This project exposes a small set of helpers and wrappers for working with WebGPU in TypeScript. The main entry points are:
+
+- `TinyHelix` (default export): High-level manager for a WebGPU context, backbuffer and helpers for creating render targets, shaders, meshes and render pipelines.
+- `WebGPUContext`: Low-level context manager that handles adapter/device initialization and canvas configuration.
+- `CommandEncoder`: Helper for recording and submitting GPU commands per-frame.
+- `RenderPass`, `RenderPipeline`, `RenderTarget`, `Shader`, `Mesh`, `Texture`, and buffer helpers.
+
+See the inline JSDoc comments in `src/` for detailed method and type information. TypeScript consumers will get typings from the `dist/index.d.ts` entry.
+
+## Development notes
+
+- Use `npm run build` to produce production bundles (minified, optimized).
+- Use `npm run build:debug` to produce debug bundles with full source maps.
+- For TypeScript projects, install `@webgpu/types` for better type completion:
+
+```bash
+npm install --save-dev @webgpu/types
+```
+
+## Requirements
+
+- A browser with WebGPU support
+- For TypeScript projects, you may want to install `@webgpu/types` for full type definitions
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.

package/dist/BindGroup.d.ts

@@ -0,0 +1,121 @@
+/// <reference types="@webgpu/types" />
+import { WebGPUContext } from "./WebGPUContext";
+import { UniformBuffer, UniformBufferLayout } from "./buffers/UniformBuffer";
+import { IBuffer } from "./buffers/IBuffer";
+import { Texture, TextureView } from "./Texture";
+import { Sampler } from "./Sampler";
+import { TextureFormat } from "../dist";
+import { StorageAccess } from "./enums";
+/**
+ * Lightweight wrapper around a GPUBindGroup.
+ * Use {@link TinyHelix.createBindGroup} to create instances.
+ */
+export declare class BindGroup {
+    /** @internal */
+    readonly _inner: GPUBindGroup;
+    /**
+     * Construct a wrapper around an existing GPUBindGroup.
+     * @internal
+     */
+    constructor(inner: GPUBindGroup);
+}
+/**
+ * Builder for creating GPUBindGroup instances. Supports adding uniform buffer
+ * entries and a human-readable label.
+ */
+export declare class BindGroupBuilder {
+    private _entries;
+    private _label?;
+    private _layout;
+    private _ctx;
+    /**
+     * @internal
+     */
+    constructor(ctx: WebGPUContext, layout: BindGroupLayout);
+    /**
+     * Assign a human-readable label for the bind group (useful in GPU debuggers).
+     */
+    withLabel(label: string): this;
+    /**
+     * Attach a buffer to the bind group
+     * @param fieldName
+     * @param buffer
+     */
+    withBuffer(fieldName: string, buffer: IBuffer): this;
+    /** Attach a texture to the bind group. */
+    withTexture(fieldName: string, texture: Texture | TextureView): this;
+    /** Attach a sampler to the bind group at the given binding index. */
+    withSampler(fieldName: string, sampler: Sampler): this;
+    /**
+     * Create the GPUBindGroup and return a wrapped `BindGroup` instance.
+     */
+    build(): BindGroup;
+}
+/**
+ * Wrapper around a GPUBindGroupLayout that also keeps track of any
+ * UniformBufferLayout objects associated with the layout. Useful for
+ * constructing `BindGroupBuilder` instances for specific layouts.
+ */
+export declare class BindGroupLayout {
+    /** @internal */
+    readonly _inner: GPUBindGroupLayout;
+    private _uboLayouts;
+    private _ctx;
+    private _indices;
+    constructor(inner: GPUBindGroupLayout, ctx: WebGPUContext, indices: Map<string, number>, uboLayouts: Map<string, UniformBufferLayout>);
+    /**
+     * Get the UniformBufferLayout associated with a named field (if any).
+     */
+    getUniformBufferLayout(name: string): UniformBufferLayout | undefined;
+    createUniformBuffer(name: string): UniformBuffer | undefined;
+    _getBindingIndex(fieldName: string): number;
+}
+/**
+ * Builder for GPUBindGroupLayout. Currently supports adding uniform buffers
+ * and their associated layout information.
+ */
+declare class BindGroupLayoutBuilder {
+    private _entries;
+    private _indices;
+    private _uboLayouts;
+    private _label?;
+    private _ctx;
+    constructor(ctx: WebGPUContext);
+    /**
+     * Assign a label for the bind group layout.
+     */
+    withLabel(label: string): this;
+    /**
+     * Add a uniform buffer binding at the given index and record its layout.
+     * @param index - binding index
+     * @param field_name - a name used to reference the layout later
+     * @param layout - the UniformBufferLayout describing the UBO
+     * @param visibility - shader stage visibility flags (defaults to VERTEX|FRAGMENT|COMPUTE)
+     */
+    withUniformBuffer(index: number, field_name: string, layout: UniformBufferLayout, visibility?: GPUShaderStageFlags): this;
+    /**
+     * Add a storage buffer binding at the given index and record its layout.
+     * @param index - binding index
+     * @param field_name - a name used to reference the layout later
+     * @param access_mode - Defines whether the storage buffer is read-only or not.
+     * @param visibility - shader stage visibility flags (defaults to FRAGMENT|COMPUTE)
+     */
+    withStorageBuffer(index: number, field_name: string, access_mode: StorageAccess, visibility?: GPUShaderStageFlags): this;
+    /**
+     * Add a storage texture binding at the given index. The texture will be
+     * write-only and use RGBA8Unorm format.
+     * @param index
+     * @param field_name
+     * @param format
+     * @param access_mode
+     * @param visibility
+     */
+    withStorageTexture(index: number, field_name: string, format: TextureFormat, access_mode: StorageAccess, visibility?: GPUShaderStageFlags): this;
+    withTexture(index: number, field_name: string, visibility?: GPUShaderStageFlags): this;
+    withSampler(index: number, field_name: string, visibility?: GPUShaderStageFlags): this;
+    /**
+     * Create the underlying GPUBindGroupLayout and return a wrapped `BindGroupLayout`.
+     */
+    build(): BindGroupLayout;
+}
+export default BindGroupLayoutBuilder;

package/dist/BlendMode.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="@webgpu/types" />
+import { BlendFactor } from "./enums";
+export declare class BlendMode {
+    readonly _inner: GPUBlendState;
+    static ALPHA: BlendMode;
+    static ADDITIVE: BlendMode;
+    static MULTIPLY: BlendMode;
+    static SCREEN: BlendMode;
+    static OVERLAY: BlendMode;
+    static DARKEN: BlendMode;
+    static LIGHTEN: BlendMode;
+    get srcFactor(): BlendFactor;
+    set srcFactor(value: BlendFactor);
+    get dstFactor(): BlendFactor;
+    set dstFactor(value: BlendFactor);
+    get alphaSrcFactor(): BlendFactor;
+    set alphaSrcFactor(value: BlendFactor);
+    get alphaDstFactor(): BlendFactor;
+    set alphaDstFactor(value: BlendFactor);
+    constructor(srcFactor: BlendFactor, dstFactor: BlendFactor, alphaSrcFactor: BlendFactor, alphaDstFactor: BlendFactor);
+}

package/dist/Buffer.d.ts

@@ -0,0 +1,66 @@
+/// <reference types="@webgpu/types" />
+import { WebGPUContext } from "./WebGPUContext";
+/**
+ * Buffer usage flags re-exported from the WebGPU API for convenience.
+ * Use these when constructing buffers with `BufferBuilder.withUsage()`.
+ */
+export declare enum BufferUsage {
+    MapRead,
+    MapWrite,
+    CopySrc,
+    CopyDst,
+    Index,
+    Vertex,
+    Uniform,
+    Storage,
+    Indirect,
+    QueryResolve
+}
+/**
+ * Builder for creating GPU-backed buffers.
+ *
+ * Example:
+ * const buf = new BufferBuilder(ctx)
+ *   .withUsage(BufferUsage.Vertex | BufferUsage.CopyDst)
+ *   .withData(new Float32Array([...]).buffer)
+ *   .build();
+ */
+export declare class BufferBuilder {
+    private _ctx;
+    private _data?;
+    private _size;
+    private _keepData;
+    private _usage;
+    constructor(ctx: WebGPUContext);
+    /**
+     * Add usage flags for the GPU buffer.
+     */
+    withUsage(usage: BufferUsage): this;
+    /**
+     * Provide initial data for the buffer. If `keepOnCPU` is true the original
+     * ArrayBuffer is stored in the resulting `Buffer.data` field for readback or
+     * reuse.
+     */
+    withData(data: ArrayBufferLike, keepOnCPU?: boolean): this;
+    /**
+     * Create the GPU buffer and upload any provided data.
+     */
+    build(): Buffer;
+}
+/**
+ * Lightweight wrapper around a GPUBuffer. Exposes the original CPU-side data
+ * (when kept) and the underlying GPU buffer for low-level interop.
+ */
+export declare class Buffer {
+    readonly _inner: GPUBuffer;
+    readonly data?: ArrayBufferLike;
+    /**
+     * Create a Buffer from an existing GPUBuffer.
+     * @param inner The underlying GPUBuffer.
+     * @param data Optional CPU-side copy of the buffer contents.
+     */
+    constructor(inner: GPUBuffer, data?: ArrayBufferLike);
+    /** Size of the GPU buffer in bytes. */
+    get size(): number;
+    _uploadData(ctx: WebGPUContext): void;
+}

package/dist/BufferDataWriter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Utility for incrementally building binary data into an ArrayBuffer.
+ * Provides typed push helpers for common numeric types used in vertex/index buffers.
+ */
+export declare class BufferDataWriter {
+    private _buffer;
+    private _view;
+    private _offset;
+    /** Create a new writer with the given total byte size. */
+    constructor(byteSize: number);
+    /** Push an unsigned 8-bit integer. */
+    pushUint8(value: number): this;
+    /** Push two unsigned 8-bit integers. */
+    pushUint8x2(x: number, y: number): this;
+    /** Push four unsigned 8-bit integers. */
+    pushUint8x4(x: number, y: number, z: number, w: number): this;
+    /** Push a signed 8-bit integer. */
+    pushSint8(value: number): this;
+    /** Push two signed 8-bit integers. */
+    pushSint8x2(x: number, y: number): this;
+    /** Push four signed 8-bit integers. */
+    pushSint8x4(x: number, y: number, z: number, w: number): this;
+    /** Push an unsigned 16-bit integer (little-endian). */
+    pushUint16(value: number): this;
+    /** Push two unsigned 16-bit integers (little-endian). */
+    pushUint16x2(x: number, y: number): this;
+    /** Push four unsigned 16-bit integers (little-endian). */
+    pushUint16x4(x: number, y: number, z: number, w: number): this;
+    /** Push a signed 16-bit integer (little-endian). */
+    pushSint16(value: number): this;
+    /** Push two signed 16-bit integers (little-endian). */
+    pushSint16x2(x: number, y: number): this;
+    /** Push four signed 16-bit integers (little-endian). */
+    pushSint16x4(x: number, y: number, z: number, w: number): this;
+    /** Push a 16-bit float (little-endian). */
+    pushFloat16(value: number): this;
+    /** Push two 16-bit floats (little-endian). */
+    pushFloat16x2(x: number, y: number): this;
+    /** Push four 16-bit floats (little-endian). */
+    pushFloat16x4(x: number, y: number, z: number, w: number): this;
+    /** Push a 32-bit float (little-endian). */
+    pushFloat32(value: number): this;
+    /** Push two 32-bit floats (little-endian). */
+    pushFloat32x2(x: number, y: number): this;
+    /** Push four 32-bit floats (little-endian). */
+    pushFloat32x3(x: number, y: number, z: number): this;
+    /** Push an 8-bit float (little-endian). */
+    pushFloat32x4(x: number, y: number, z: number, w: number): this;
+    /** Push an unsigned 32-bit integer (little-endian). */
+    pushUint32(value: number): this;
+    /** Push two unsigned 32-bit integers (little-endian). */
+    pushUint32x2(x: number, y: number): this;
+    /** Push three unsigned 32-bit integers (little-endian). */
+    pushUint32x3(x: number, y: number, z: number): this;
+    /** Push four unsigned 32-bit integers (little-endian). */
+    pushUint32x4(x: number, y: number, z: number, w: number): this;
+    /** Push a signed 32-bit integer (little-endian). */
+    pushSint32(value: number): this;
+    /** Push two signed 32-bit integers (little-endian). */
+    pushSint32x2(x: number, y: number): this;
+    /** Push three signed 32-bit integers (little-endian). */
+    pushSint32x3(x: number, y: number, z: number): this;
+    /** Push four signed 32-bit integers (little-endian). */
+    pushSint32x4(x: number, y: number, z: number, w: number): this;
+    /** Returns the underlying ArrayBuffer containing all written data. */
+    get arrayBuffer(): ArrayBuffer;
+}

package/dist/CommandEncoder.d.ts

@@ -0,0 +1,50 @@
+import { WebGPUContext } from "./WebGPUContext";
+import { RenderPassBuilder } from "./RenderPass";
+import { RenderTarget } from "./RenderTarget";
+import { ComputePassBuilder } from "./ComputePass";
+import { BindGroup } from "./BindGroup";
+import { Buffer } from "./buffers/Buffer";
+/**
+ * Encapsulates a GPUCommandEncoder and provides helper methods to build and
+ * submit GPU commands for a single frame. CommandEncoder should only be created
+ * through the TinyHelix instance (See {@link TinyHelix.createCommandEncoder})
+ */
+export declare class CommandEncoder {
+    private _encoder;
+    private _queue;
+    private _backbufferTarget;
+    private _commandBuffer;
+    private _depthStencilTarget;
+    private _globalBindGroups;
+    /**
+     * Create a new CommandEncoder bound to a backbuffer/render target and
+     * the WebGPU context.
+     *
+     * @internal
+     */
+    constructor(backbufferTarget: RenderTarget, globalBindGroups: BindGroup[], ctx: WebGPUContext, depthStencilTarget?: RenderTarget, label?: string);
+    /**
+     * Clears a buffer's contents
+     */
+    clearBuffer(buffer: Buffer, offset?: number, size?: number): this;
+    /**
+     * Begin building a render pass attached to this encoder.
+     * Returns a fluent RenderPassBuilder used to configure attachments and clear ops.
+     */
+    createRenderPass(): RenderPassBuilder;
+    /**
+     * Begin building a compute pass attached to this encoder.
+     * Returns a fluent ComputePassBuilder used to configure bindings and dispatch ops.
+     */
+    createComputePass(): ComputePassBuilder;
+    /**
+     * Mark the encoder as finished and finalize any pending commands.
+     * Calling finish() multiple times is safe but a no-op after the first call.
+     */
+    finish(): void;
+    /**
+     * Submit the recorded commands to the GPU queue. If the encoder has not
+     * been finished yet, finish() will be called automatically.
+     */
+    submit(): void;
+}

package/dist/ComputePass.d.ts

@@ -0,0 +1,37 @@
+/// <reference types="@webgpu/types" />
+import { BindGroup } from "./BindGroup";
+import { ComputePipeline } from "./ComputePipeline";
+import { Buffer } from "./buffers/Buffer";
+export declare class ComputePass {
+    private readonly _inner;
+    constructor(inner: GPUComputePassEncoder);
+    /**
+     * Set the compute pipeline to use for the next dispatch calls.
+     * @param pipeline
+     */
+    setPipeline(pipeline: ComputePipeline): this;
+    dispatch(x: GPUSize32, y?: GPUSize32, z?: GPUSize32): this;
+    dispatchIndirect(buffer: Buffer, offset: number): this;
+    /**
+     * Set a bind group at the given index.
+     * @param index - bind group index in the render pipeline layout
+     * @param bindGroup - a `BindGroup` instance
+     */
+    setBindGroup(index: number, bindGroup: BindGroup): this;
+    /**
+     * End the compute pass. After calling end(), the underlying encoder may
+     * continue recording other passes or be finished/submitted.
+     */
+    end(): void;
+}
+export declare class ComputePassBuilder {
+    private _label?;
+    private _encoder;
+    private _globalBindGroups;
+    constructor(encoder: GPUCommandEncoder, globalBindGroups: BindGroup[]);
+    /**
+     * Assign a human-readable label for the render pass (useful for GPU debuggers).
+     */
+    withLabel(label: string): this;
+    build(): ComputePass;
+}

package/dist/ComputePipeline.d.ts

@@ -0,0 +1,18 @@
+/// <reference types="@webgpu/types" />
+import { WebGPUContext } from "./WebGPUContext";
+import { Shader } from "./Shader";
+export declare class ComputePipeline {
+    readonly _inner: GPUComputePipeline;
+    constructor(inner: GPUComputePipeline);
+}
+export declare class ComputePipelineBuilder {
+    private _ctx;
+    private _label?;
+    private _shader;
+    private _entry;
+    constructor(ctx: WebGPUContext);
+    withLabel(label: string): this;
+    /** Select the shader entry point for the fragment stage. */
+    withShader(shader: Shader, entry: string): this;
+    build(): ComputePipeline;
+}

package/dist/Mesh.d.ts

@@ -0,0 +1,177 @@
+import { Buffer } from "./buffers/Buffer";
+import { WebGPUContext } from "./WebGPUContext";
+/**
+ * Index buffer formats supported by the library.
+ */
+export declare enum IndexFormat {
+    Uint16 = "uint16",
+    Uint32 = "uint32"
+}
+declare class IndexBuffer {
+    buffer: Buffer;
+    format: IndexFormat;
+    count: number;
+    constructor(data: Uint16Array | Uint32Array, ctx: WebGPUContext, keepData?: boolean);
+}
+/**
+ * Mesh topology enum (maps to GPU primitive topologies).
+ */
+export declare enum MeshTopology {
+    TriangleList = "triangle-list",
+    TriangleStrip = "triangle-strip",
+    LineList = "line-list",
+    LineStrip = "line-strip",
+    PointList = "point-list"
+}
+/**
+ * Winding mode for front-facing triangles.
+ */
+export declare enum FrontFace {
+    Clockwise = "cw",
+    CounterClockwise = "ccw"
+}
+/**
+ * Vertex attribute formats supported by the helper. These are translated into
+ * GPU vertex attribute formats when building pipelines.
+ */
+export declare enum VertexFormat {
+    Uint8 = "uint8",
+    Uint8x2 = "uint8x2",
+    Uint8x4 = "uint8x4",
+    Sint8 = "sint8",
+    Sint8x2 = "sint8x2",
+    Sint8x4 = "sint8x4",
+    Unorm8 = "unorm8",
+    Unorm8x2 = "unorm8x2",
+    Unorm8x4 = "unorm8x4",
+    Snorm8 = "snorm8",
+    Snorm8x2 = "snorm8x2",
+    Snorm8x4 = "snorm8x4",
+    Uint16 = "uint16",
+    Uint16x2 = "uint16x2",
+    Uint16x4 = "uint16x4",
+    Sint16 = "sint16",
+    Sint16x2 = "sint16x2",
+    Sint16x4 = "sint16x4",
+    Unorm16 = "unorm16",
+    Unorm16x2 = "unorm16x2",
+    Unorm16x4 = "unorm16x4",
+    Snorm16 = "snorm16",
+    Snorm16x2 = "snorm16x2",
+    Snorm16x4 = "snorm16x4",
+    Float16 = "float16",
+    Float16x2 = "float16x2",
+    Float16x4 = "float16x4",
+    Float32 = "float32",
+    Float32x2 = "float32x2",
+    Float32x3 = "float32x3",
+    Float32x4 = "float32x4",
+    Uint32 = "uint32",
+    Uint32x2 = "uint32x2",
+    Uint32x3 = "uint32x3",
+    Uint32x4 = "uint32x4",
+    Sint32 = "sint32",
+    Sint32x2 = "sint32x2",
+    Sint32x3 = "sint32x3",
+    Sint32x4 = "sint32x4",
+    Unorm10_10_10_2 = "unorm10-10-10-2",
+    Unorm8x4_bgra = "unorm8x4-bgra"
+}
+/**
+ * Lightweight Mesh representation containing vertex streams and an optional index buffer.
+ * Use `MeshBuilder` to construct instances.
+ */
+export declare class Mesh {
+    private _topology;
+    private _frontFace;
+    private _streams;
+    private _indexBuffer?;
+    private _numVertices;
+    /**
+     * @internal
+     */
+    constructor(topology: MeshTopology, frontFace: FrontFace, streams: VertexStream[], indexBuffer?: IndexBuffer);
+    /** The primitive topology for this mesh. */
+    get topology(): MeshTopology;
+    /** The winding used to determine front-facing triangles. */
+    get frontFace(): FrontFace;
+    /** The number of vertex streams in this mesh. */
+    get numStreams(): number;
+    /** Get the number of vertices in the first vertex stream. */
+    get numVertices(): number;
+    /** Get the GPU-backed vertex buffer for a given stream index. */
+    getVertexBuffer(streamIndex: number): Buffer;
+    /** Get the stride (byte size) of a vertex in the requested stream. */
+    getStreamStride(streamIndex: number): number;
+    /** Get the declared attributes for a vertex stream. */
+    getStreamAttributes(streamIndex: number): VertexAttribute[];
+    /** Get the optional index buffer backing this mesh. */
+    get indexBuffer(): Buffer | undefined;
+    /** Get the index format of the index buffer backing this mesh. */
+    get indexFormat(): IndexFormat;
+    /** Get the number of indices in the index buffer backing this mesh. */
+    get numIndices(): number;
+}
+export type VertexAttribute = {
+    name: string;
+    format: VertexFormat;
+    offset: number;
+};
+declare class VertexStream {
+    stride: number;
+    attributes: VertexAttribute[];
+    buffer?: Buffer;
+    pushAttribute(name: string, format: VertexFormat): void;
+    get numVertices(): number;
+}
+/**
+ * Builder helper used when creating a vertex stream for a Mesh.
+ */
+export declare class StreamBuilder {
+    private _stream;
+    private _ctx;
+    /**
+     * @internal
+     */
+    constructor(stream: VertexStream, ctx: WebGPUContext);
+    /**
+     * Add a vertex attribute to the stream.
+     * @param name - attribute name used by the shader bindings
+     * @param format - attribute format (see VertexFormat)
+     */
+    pushAttribute(name: string, format: VertexFormat): this;
+    /**
+     * Upload vertex data for this stream. `keepOnCPU` controls whether the
+     * source ArrayBuffer is retained in memory for readback.
+     */
+    withData(data: ArrayBufferLike, keepOnCPU?: boolean): void;
+}
+/**
+ * Fluent builder for creating a Mesh. Use `pushStream()` to describe vertex
+ * streams and `withIndexData()` to add optional indices.
+ */
+export declare class MeshBuilder {
+    private _topology;
+    private _frontFace;
+    private _streams;
+    private _ctx;
+    private _indexBuffer?;
+    /**
+     * @internal
+     */
+    constructor(ctx: WebGPUContext);
+    /** Add a vertex stream using a builder callback. */
+    pushStream(buildFunc: (builder: StreamBuilder) => void): this;
+    /** Set the winding used to determine front-facing triangles. Defaults to counter-clockwise. */
+    withFrontFace(value: FrontFace): this;
+    /** Set the primitive topology for the mesh. Defaults to triangle list. */
+    withTopology(value: MeshTopology): this;
+    /**
+     * Provide index data (Uint16Array or Uint32Array). If `keepOnCPU` is true the
+     * original array buffer will be preserved on the resulting mesh's index buffer.
+     */
+    withIndexData(data: Uint16Array | Uint32Array, keepOnCPU?: boolean): this;
+    /** Build the mesh. */
+    build(): Mesh;
+}
+export {};