@vgpu/wgsl-std 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vercel, Inc.
+
+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,106 @@
+# @vgpu/wgsl-std
+
+Pure WGSL utility snippets for use with `@vgpu/wgsl` import resolution.
+
+This package intentionally ships raw `.wgsl` modules instead of JavaScript wrappers or a macro/include system. Import the explicit utility area you need:
+
+```wgsl
+import { saturate, remap, safeNormalize3, rotate2d } from "@vgpu/wgsl-std/math";
+import { srgbToLinear3, linearToSrgb3, luminance, applyExposure } from "@vgpu/wgsl-std/color";
+import { vogelDisk, hammersley2d } from "@vgpu/wgsl-std/sampling";
+import { pi, tau, goldenAngle } from "@vgpu/wgsl-std/constants";
+```
+
+There is no root WGSL export. Subpath exports resolve to physical WGSL files:
+
+- `@vgpu/wgsl-std/math` -> `src/math/index.wgsl`
+- `@vgpu/wgsl-std/color` -> `src/color/index.wgsl`
+- `@vgpu/wgsl-std/sampling` -> `src/sampling/index.wgsl`
+- `@vgpu/wgsl-std/constants` -> `src/constants/index.wgsl`
+
+WGSL snippets in this package must stay pure declaration modules: functions, constants, structs, and aliases only. They must not introduce hidden bindings, resource variables, overrides, or entry points.
+
+## Constants
+
+`@vgpu/wgsl-std/constants` includes common math constants as plain WGSL `const` declarations:
+
+- `pi: f32`: π.
+- `tau: f32`: 2π.
+- `halfPi: f32`: π / 2.
+- `quarterPi: f32`: π / 4.
+- `invPi: f32`: 1 / π.
+- `invTau: f32`: 1 / 2π.
+- `goldenRatio: f32`: φ.
+- `goldenAngle: f32`: golden angle in radians.
+
+The constants module is intentionally small so importing it does not add much WGSL text. `resolveShader()` also performs conservative declaration-level dead-code elimination, so unused declarations from larger WGSL utility modules are pruned from shaders with entry points before minification. `goldenAngle` remains available from `@vgpu/wgsl-std/sampling` for sampling-only shaders.
+
+See `src/constants/index.docs.md` for examples and precision notes.
+
+## Math utilities
+
+`@vgpu/wgsl-std/math` includes scalar range helpers and vector safety helpers:
+
+- `saturate(value: f32) -> f32`: clamp to `[0.0, 1.0]`.
+- `clamp01(value: f32) -> f32`: alias for `saturate`.
+- `inverseLerp(rangeStart: f32, rangeEnd: f32, value: f32) -> f32`: unclamped inverse lerp; returns `0.0` when `rangeStart == rangeEnd`.
+- `remap(inMin: f32, inMax: f32, outMin: f32, outMax: f32, value: f32) -> f32`: unclamped range remap; returns `outMin` when the input range is zero-length.
+- `safeNormalize2/3/4(value, fallback)`: normalize non-zero vectors and return `fallback` for zero-length vectors. WGSL has no user-defined generic overloads, so dimensions are explicit in v1.
+- `rotate2d(value: vec2f, radians: f32) -> vec2f`: counter-clockwise 2D rotation by radians.
+
+See `src/math/index.docs.md` for examples and edge-case notes.
+
+## Color utilities
+
+`@vgpu/wgsl-std/color` includes non-PBR color helpers:
+
+- `srgbToLinear(value: f32) -> f32`: standard IEC/sRGB decode transfer for one channel.
+- `srgbToLinear3(color: vec3f) -> vec3f`: decode RGB channels from sRGB to linear light.
+- `srgbToLinear4(color: vec4f) -> vec4f`: decode RGB channels and preserve alpha.
+- `linearToSrgb(value: f32) -> f32`: standard IEC/sRGB encode transfer for one channel.
+- `linearToSrgb3(color: vec3f) -> vec3f`: encode RGB channels from linear light to sRGB.
+- `linearToSrgb4(color: vec4f) -> vec4f`: encode RGB channels and preserve alpha.
+- `luminance(color: vec3f) -> f32`: relative luminance using Rec.709/sRGB coefficients `(0.2126, 0.7152, 0.0722)`. Pass linear-light color.
+- `applyExposure(color: vec3f, exposure: f32) -> vec3f`: multiply by `exp2(exposure)`, where exposure is measured in stops/EV.
+
+WGSL has no user-defined generics, so vector transfer helpers use `3`/`4` suffixes while scalar transfer helpers keep the base names. Color transfer helpers expect normal `[0.0, 1.0]` color-channel inputs but do not clamp; clamp explicitly with `@vgpu/wgsl-std/math` when desired. The transfer and luminance formulas are mathematically standard and useful for physically meaningful conversions, but they may not match artistic/tuned approximations in an existing shader without deliberate visual review. The color module intentionally defers PBR helpers and tonemappers (ACES/Hable/Filament/Reinhard) so applications choose their own display transform.
+
+See `src/color/index.docs.md` for formulas, examples, and performance notes.
+
+## Sampling utilities
+
+`@vgpu/wgsl-std/sampling` includes deterministic sampling helpers for unit-disk kernels and low-discrepancy 2D point sets:
+
+- `goldenAngle: f32`: golden angle in radians, rounded to WGSL `f32` precision (`2.3999631`).
+- `vogelDisk(index: u32, count: u32, phi: f32) -> vec2f`: Vogel spiral sample in the unit disk for `index < count`; `phi` rotates the pattern in radians. Returns `vec2f(0.0)` when `count == 0u` to avoid division by zero.
+- `radicalInverseVdc(bits: u32) -> f32`: standard base-2 Van der Corput radical inverse via deterministic bit reversal, clamped to the largest `f32` below `1.0` for high reversed-bit values whose WGSL `f32` product would otherwise round to `1.0`.
+- `hammersley2d(index: u32, count: u32) -> vec2f`: Hammersley point `(index / count, radicalInverseVdc(index))`; returns `vec2f(0.0)` when `count == 0u`.
+
+Before, shader code often repeats the sampling math manually:
+
+```wgsl
+fn localVogelDisk(index: u32, count: u32, phi: f32) -> vec2f {
+  if (count == 0u) {
+    return vec2f(0.0);
+  }
+  let angle = f32(index) * 2.3999631 + phi;
+  let radius = sqrt((f32(index) + 0.5) / f32(count));
+  return vec2f(cos(angle), sin(angle)) * radius;
+}
+```
+
+With the utility module, import the helper explicitly:
+
+```wgsl
+import { vogelDisk } from "@vgpu/wgsl-std/sampling";
+
+fn localVogelDisk(index: u32, count: u32, phi: f32) -> vec2f {
+  return vogelDisk(index, count, phi);
+}
+```
+
+Performance note: `vogelDisk` uses `sqrt`, `cos`, and `sin`; precompute fixed kernels if they are reused heavily. `hammersley2d`/`radicalInverseVdc` are stateless integer/float math and are not random-number generators.
+
+Provenance: Vogel disk sampling is an original WGSL transcription of Vogel's 1979 published golden-angle phyllotaxis model. Van der Corput and Hammersley samples are standard low-discrepancy sequence formulas implemented here with original WGSL bit operations; they are deliberate reviewed additions beyond the original minimal `vogelDisk` requirement to satisfy the updated user preference for fewer deferrals while staying provenance-clean. `concentricDisk` is deferred for separate API review of disk-mapping conventions and edge behavior, and Perlin/simplex/fBM/value noise plus shader-magic hash/random snippets are deferred for separate API and provenance review.
+
+See `src/sampling/index.docs.md` for examples, input ranges, and edge-case notes.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@vgpu/wgsl-std",
+  "version": "0.0.5",
+  "description": "Pure WGSL utility snippets for vgpu shaders.",
+  "keywords": [
+    "webgpu",
+    "graphics",
+    "rendering",
+    "wgsl",
+    "shader",
+    "utilities"
+  ],
+  "homepage": "https://github.com/vercel-labs/vgpu#readme",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/vgpu/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/vgpu.git",
+    "directory": "packages/wgsl-std"
+  },
+  "license": "MIT",
+  "author": "Matias Gonzalez <matiasngf@hotmail.com>",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    "./math": "./src/math/index.wgsl",
+    "./color": "./src/color/index.wgsl",
+    "./sampling": "./src/sampling/index.wgsl",
+    "./constants": "./src/constants/index.wgsl"
+  },
+  "files": [
+    "src/**/*.wgsl",
+    "src/**/*.docs.md",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/color/index.docs.md

@@ -0,0 +1,72 @@
+# @vgpu/wgsl-std/color
+
+Raw WGSL color utility module for `@vgpu/wgsl` imports. The module contains pure declarations only: no bindings, overrides, hidden state, or entry points.
+
+```wgsl
+import { srgbToLinear3, linearToSrgb3, luminance, applyExposure } from "@vgpu/wgsl-std/color";
+
+fn shade(baseColorSrgb: vec3f, exposureStops: f32) -> vec3f {
+  let linear = srgbToLinear3(baseColorSrgb);
+  let exposed = applyExposure(linear, exposureStops);
+  return linearToSrgb3(exposed);
+}
+```
+
+## API
+
+WGSL has no user-defined generics, so v1 uses an explicit dimensional suffix for vector transfer helpers and unsuffixed scalar helpers:
+
+- `srgbToLinear(value: f32) -> f32`
+- `srgbToLinear3(color: vec3f) -> vec3f`
+- `srgbToLinear4(color: vec4f) -> vec4f`
+- `linearToSrgb(value: f32) -> f32`
+- `linearToSrgb3(color: vec3f) -> vec3f`
+- `linearToSrgb4(color: vec4f) -> vec4f`
+- `luminance(color: vec3f) -> f32`
+- `applyExposure(color: vec3f, exposure: f32) -> vec3f`
+
+The `vec4f` transfer helpers convert RGB channels and preserve alpha unchanged.
+
+## sRGB transfer functions
+
+`srgbToLinear*` and `linearToSrgb*` implement the standard IEC/sRGB piecewise transfer formulas:
+
+```text
+srgbToLinear(c) = c / 12.92                         when c <= 0.04045
+                = ((c + 0.055) / 1.055) ^ 2.4       otherwise
+
+linearToSrgb(c) = 12.92 * c                         when c <= 0.0031308
+                = 1.055 * c ^ (1 / 2.4) - 0.055     otherwise
+```
+
+The expected input and output range is `[0.0, 1.0]` for color channels. These helpers do **not** clamp inputs or outputs; callers that need display-range saturation should import `saturate` or `clamp01` from `@vgpu/wgsl-std/math` explicitly. The formulas are mathematically standard; replacing an artistic or tuned approximation with these helpers can still change the look of a shader and should be reviewed visually.
+
+## Luminance
+
+`luminance(color)` returns relative luminance for a linear RGB color using Rec.709/sRGB coefficients:
+
+```text
+dot(color, vec3f(0.2126, 0.7152, 0.0722))
+```
+
+Pass linear-light color values. If your source is sRGB encoded, decode with `srgbToLinear3` before computing luminance.
+
+## Exposure
+
+`applyExposure(color, exposure)` treats `exposure` as photographic stops/EV and returns:
+
+```text
+color * exp2(exposure)
+```
+
+Examples: `0.0` leaves the color unchanged, `1.0` doubles it, and `-2.0` multiplies it by `0.25`. The function is intentionally unclamped so HDR pipelines can keep values above `1.0` until an explicit later display transform.
+
+## Performance notes
+
+- Scalar transfer helpers branch once and use `pow` only above the sRGB breakpoint.
+- Vector transfer helpers call the scalar helper per RGB channel. This keeps behavior identical for scalar and vector paths and avoids hidden approximation tables.
+- `luminance` is a single dot product; `applyExposure` is a scalar `exp2` and vector multiply.
+
+## Deferred helpers
+
+This v1 color module intentionally does not include PBR helpers, BRDF/Fresnel/IBL routines, ACES/Hable/Filament tonemappers, or a default tonemap. Tonemapping and PBR-specific utilities are deferred so applications choose their own display transform and resource model explicitly.

package/src/color/index.wgsl

@@ -0,0 +1,37 @@
+export fn luminance(value: vec3f) -> f32 {
+  return dot(value, vec3f(0.2126, 0.7152, 0.0722));
+}
+
+export fn applyExposure(value: vec3f, exposure: f32) -> vec3f {
+  return value * exp2(exposure);
+}
+
+export fn srgbToLinear(value: f32) -> f32 {
+  if (value <= 0.04045) {
+    return value / 12.92;
+  }
+  return pow((value + 0.055) / 1.055, 2.4);
+}
+
+export fn srgbToLinear3(value: vec3f) -> vec3f {
+  return vec3f(srgbToLinear(value.r), srgbToLinear(value.g), srgbToLinear(value.b));
+}
+
+export fn srgbToLinear4(value: vec4f) -> vec4f {
+  return vec4f(srgbToLinear3(value.rgb), value.a);
+}
+
+export fn linearToSrgb(value: f32) -> f32 {
+  if (value <= 0.0031308) {
+    return value * 12.92;
+  }
+  return 1.055 * pow(value, 1.0 / 2.4) - 0.055;
+}
+
+export fn linearToSrgb3(value: vec3f) -> vec3f {
+  return vec3f(linearToSrgb(value.r), linearToSrgb(value.g), linearToSrgb(value.b));
+}
+
+export fn linearToSrgb4(value: vec4f) -> vec4f {
+  return vec4f(linearToSrgb3(value.rgb), value.a);
+}

package/src/constants/index.docs.md

@@ -0,0 +1,53 @@
+# @vgpu/wgsl-std/constants
+
+Raw WGSL math constants for `@vgpu/wgsl` imports. The module contains pure `const` declarations only: no functions, bindings, overrides, hidden state, resources, or entry points.
+
+```wgsl
+import { pi, tau, goldenAngle } from "@vgpu/wgsl-std/constants";
+
+fn angleForIndex(index: u32) -> f32 {
+  return f32(index) * goldenAngle + tau * 0.25;
+}
+```
+
+## API
+
+- `pi: f32`: π, rounded to WGSL `f32` precision (`3.1415927`).
+- `tau: f32`: 2π, rounded to WGSL `f32` precision (`6.2831855`).
+- `halfPi: f32`: π / 2, rounded to WGSL `f32` precision (`1.5707964`).
+- `quarterPi: f32`: π / 4, rounded to WGSL `f32` precision (`0.7853982`).
+- `invPi: f32`: 1 / π, rounded to WGSL `f32` precision (`0.3183099`).
+- `invTau: f32`: 1 / 2π, rounded to WGSL `f32` precision (`0.15915494`).
+- `goldenRatio: f32`: φ, rounded to WGSL `f32` precision (`1.618034`).
+- `goldenAngle: f32`: golden angle in radians, rounded to WGSL `f32` precision (`2.3999631`).
+
+## Native WGSL before
+
+```wgsl
+const PI: f32 = 3.1415927;
+const TAU: f32 = 6.2831855;
+
+fn radiansFromTurns(turns: f32) -> f32 {
+  return turns * TAU;
+}
+```
+
+## Utility import after
+
+```wgsl
+import { tau } from "@vgpu/wgsl-std/constants";
+
+fn radiansFromTurns(turns: f32) -> f32 {
+  return turns * tau;
+}
+```
+
+## Notes
+
+These constants are plain WGSL `const` declarations. The module is intentionally small so importing it does not add much WGSL text. Declaration-level dead-code elimination for larger WGSL utility modules is tracked in https://github.com/vercel-labs/vgpu/issues/98.
+
+`goldenAngle` is also exported by `@vgpu/wgsl-std/sampling` for sampling-only imports. Prefer this constants module when sharing the value across non-sampling shader code.
+
+## Provenance
+
+These are standard mathematical constants transcribed directly into WGSL `f32` literals and rounded to the same precision style as the rest of `@vgpu/wgsl-std`.

package/src/constants/index.wgsl

@@ -0,0 +1,8 @@
+export const pi: f32 = 3.1415927;
+export const tau: f32 = 6.2831855;
+export const halfPi: f32 = 1.5707964;
+export const quarterPi: f32 = 0.7853982;
+export const invPi: f32 = 0.3183099;
+export const invTau: f32 = 0.15915494;
+export const goldenRatio: f32 = 1.618034;
+export const goldenAngle: f32 = 2.3999631;

package/src/math/index.docs.md

@@ -0,0 +1,54 @@
+# @vgpu/wgsl-std/math
+
+Raw WGSL math utility module for `@vgpu/wgsl` imports.
+
+All exports are pure WGSL declarations. Import only the helpers you use:
+
+```wgsl
+import { saturate, remap, safeNormalize3, rotate2d } from "@vgpu/wgsl-std/math";
+
+fn shade(normal: vec3f, uv: vec2f) -> vec3f {
+  let n = safeNormalize3(normal, vec3f(0.0, 0.0, 1.0));
+  let rotatedUv = rotate2d(uv, 0.78539816339);
+  let weight = saturate(remap(-1.0, 1.0, 0.0, 1.0, n.z));
+  return vec3f(rotatedUv, weight);
+}
+```
+
+## Catalog
+
+### `saturate(value: f32) -> f32`
+
+Clamps a scalar `f32` to `[0.0, 1.0]` using WGSL `clamp`.
+
+### `clamp01(value: f32) -> f32`
+
+Alias for `saturate`. Use whichever name is clearer at the call site.
+
+### `inverseLerp(rangeStart: f32, rangeEnd: f32, value: f32) -> f32`
+
+Returns `(value - rangeStart) / (rangeEnd - rangeStart)` without clamping the result. Values outside the input range produce values outside `[0.0, 1.0]`.
+
+If `rangeStart == rangeEnd`, the input range has no length and the helper returns `0.0` deterministically instead of dividing by zero.
+
+### `remap(inMin: f32, inMax: f32, outMin: f32, outMax: f32, value: f32) -> f32`
+
+Maps `value` from input range `[inMin, inMax]` into output range `[outMin, outMax]` using `inverseLerp`, without clamping.
+
+If `inMin == inMax`, `inverseLerp` returns `0.0`, so `remap` returns `outMin`.
+
+### `safeNormalize2(value: vec2f, fallback: vec2f) -> vec2f`
+### `safeNormalize3(value: vec3f, fallback: vec3f) -> vec3f`
+### `safeNormalize4(value: vec4f, fallback: vec4f) -> vec4f`
+
+Normalizes non-zero vectors and returns `fallback` for zero-length vectors. The fallback is returned exactly as supplied; normalize it first if the fallback must be unit length.
+
+WGSL does not provide user-defined generic functions for multiple vector dimensions, so v1 exports explicit `2`, `3`, and `4` dimensional names instead of a single overloaded `safeNormalize`.
+
+### `rotate2d(value: vec2f, radians: f32) -> vec2f`
+
+Rotates a `vec2f` by `radians` counter-clockwise around the origin:
+
+```wgsl
+let up = rotate2d(vec2f(1.0, 0.0), 1.57079632679);
+```

package/src/math/index.wgsl

@@ -0,0 +1,50 @@
+export fn saturate(value: f32) -> f32 {
+  return clamp(value, 0.0, 1.0);
+}
+
+export fn clamp01(value: f32) -> f32 {
+  return saturate(value);
+}
+
+export fn inverseLerp(rangeStart: f32, rangeEnd: f32, value: f32) -> f32 {
+  let denominator = rangeEnd - rangeStart;
+  if (denominator == 0.0) {
+    return 0.0;
+  }
+  return (value - rangeStart) / denominator;
+}
+
+export fn remap(inMin: f32, inMax: f32, outMin: f32, outMax: f32, value: f32) -> f32 {
+  let t = inverseLerp(inMin, inMax, value);
+  return outMin + t * (outMax - outMin);
+}
+
+export fn safeNormalize2(value: vec2f, fallback: vec2f) -> vec2f {
+  let lengthSquared = dot(value, value);
+  if (lengthSquared <= 0.0) {
+    return fallback;
+  }
+  return value * inverseSqrt(lengthSquared);
+}
+
+export fn safeNormalize3(value: vec3f, fallback: vec3f) -> vec3f {
+  let lengthSquared = dot(value, value);
+  if (lengthSquared <= 0.0) {
+    return fallback;
+  }
+  return value * inverseSqrt(lengthSquared);
+}
+
+export fn safeNormalize4(value: vec4f, fallback: vec4f) -> vec4f {
+  let lengthSquared = dot(value, value);
+  if (lengthSquared <= 0.0) {
+    return fallback;
+  }
+  return value * inverseSqrt(lengthSquared);
+}
+
+export fn rotate2d(value: vec2f, radians: f32) -> vec2f {
+  let c = cos(radians);
+  let s = sin(radians);
+  return mat2x2f(c, s, -s, c) * value;
+}

package/src/sampling/index.docs.md

@@ -0,0 +1,86 @@
+# @vgpu/wgsl-std/sampling
+
+Raw WGSL sampling utility module for `@vgpu/wgsl` imports. The module contains pure declarations only: no bindings, overrides, hidden state, resources, or entry points.
+
+```wgsl
+import { goldenAngle, vogelDisk, hammersley2d } from "@vgpu/wgsl-std/sampling";
+
+fn sampleKernel(index: u32, count: u32, rotation: f32) -> vec3f {
+  let disk = vogelDisk(index, count, rotation);
+  let sequence = hammersley2d(index, count);
+  return vec3f(disk, sequence.y);
+}
+```
+
+## API
+
+- `goldenAngle: f32`: golden angle in radians, rounded to WGSL `f32` precision (`2.3999631`).
+- `vogelDisk(index: u32, count: u32, phi: f32) -> vec2f`: deterministic Vogel spiral point in the unit disk.
+- `radicalInverseVdc(bits: u32) -> f32`: base-2 Van der Corput radical inverse using bit reversal, clamped to the largest `f32` below `1.0` for high reversed-bit values whose WGSL `f32` product would otherwise round to `1.0`.
+- `hammersley2d(index: u32, count: u32) -> vec2f`: 2D Hammersley point `(index / count, radicalInverseVdc(index))`.
+
+## Native WGSL before
+
+```wgsl
+fn localVogelDisk(index: u32, count: u32, phi: f32) -> vec2f {
+  if (count == 0u) {
+    return vec2f(0.0);
+  }
+  let goldenAngle = 2.3999631;
+  let angle = f32(index) * goldenAngle + phi;
+  let radius = sqrt((f32(index) + 0.5) / f32(count));
+  return vec2f(cos(angle), sin(angle)) * radius;
+}
+```
+
+## Utility import after
+
+```wgsl
+import { vogelDisk } from "@vgpu/wgsl-std/sampling";
+
+fn localVogelDisk(index: u32, count: u32, phi: f32) -> vec2f {
+  return vogelDisk(index, count, phi);
+}
+```
+
+## Vogel disk samples
+
+`vogelDisk(index, count, phi)` computes:
+
+```text
+angle = f32(index) * goldenAngle + phi
+radius = sqrt((f32(index) + 0.5) / f32(count))
+point = vec2f(cos(angle), sin(angle)) * radius
+```
+
+Use `index < count` for samples bounded by the unit disk. `phi` is an angular offset in radians; pass a per-frame or per-pixel rotation when you want to rotate the entire pattern without changing radial placement.
+
+If `count == 0u`, the function returns `vec2f(0.0)` defensively instead of dividing by zero.
+
+## Low-discrepancy sequence samples
+
+`radicalInverseVdc(bits)` implements the standard base-2 Van der Corput radical inverse by reversing the 32 bits of `bits` and scaling by `1 / 2^32`. Because WGSL returns `f32`, the final value is clamped to `0.99999994` (the largest `f32` below `1.0`) for the highest reversed-bit values whose scaled product would otherwise round up to `1.0`. This preserves the `[0.0, 1.0)` sequence contract even when the reversed `u32` value is near the top of its representable range.
+
+`hammersley2d(index, count)` returns:
+
+```text
+vec2f(f32(index) / f32(count), radicalInverseVdc(index))
+```
+
+Use `index < count` for the conventional Hammersley point set over `[0.0, 1.0) x [0.0, 1.0)`. If `count == 0u`, the function returns `vec2f(0.0)` defensively instead of dividing by zero.
+
+## Performance notes
+
+- `vogelDisk` uses one `sqrt`, one `cos`, and one `sin` per sample. Precompute or reuse points when a fixed kernel is sampled many times.
+- `radicalInverseVdc` uses integer shifts, masks, and one float conversion; it does not use trigonometry or hidden state.
+- `hammersley2d` is deterministic and stateless. It is not a random number generator and does not decorrelate samples across pixels by itself.
+
+## Provenance
+
+Vogel disk sampling comes from Vogel's 1979 published mathematical model for phyllotaxis using the golden-angle spiral. The implementation here is an original transcription of the formula into WGSL.
+
+The Van der Corput radical inverse and Hammersley point set are standard low-discrepancy sequence definitions. The bit-reversal implementation is an original WGSL implementation of those mathematical definitions and uses only ordinary integer mask/shift operations. These helpers are deliberate reviewed additions beyond the original minimal `vogelDisk` requirement, included to satisfy the updated user preference for fewer deferrals while staying provenance-clean.
+
+## Deferred helpers
+
+This module intentionally does not include `concentricDisk`; that helper needs separate API review for disk-mapping conventions and edge behavior. It also does not include Perlin noise, simplex noise, fBM, value noise, or shader-magic hash/random snippets. Those helpers need separate API, quality, and provenance review so v1 avoids copying unattributed shader snippets or baking in a hidden random/resource model.

package/src/sampling/index.wgsl

@@ -0,0 +1,31 @@
+export const goldenAngle: f32 = 2.3999631;
+
+const inverseU32Range: f32 = 2.3283064e-10;
+
+export fn vogelDisk(index: u32, count: u32, phi: f32) -> vec2f {
+  if (count == 0u) {
+    return vec2f(0.0);
+  }
+
+  let angle = f32(index) * goldenAngle + phi;
+  let radius = sqrt((f32(index) + 0.5) / f32(count));
+  return vec2f(cos(angle), sin(angle)) * radius;
+}
+
+export fn radicalInverseVdc(bits: u32) -> f32 {
+  var value = bits;
+  value = (value << 16u) | (value >> 16u);
+  value = ((value & 0x55555555u) << 1u) | ((value & 0xaaaaaaaau) >> 1u);
+  value = ((value & 0x33333333u) << 2u) | ((value & 0xccccccccu) >> 2u);
+  value = ((value & 0x0f0f0f0fu) << 4u) | ((value & 0xf0f0f0f0u) >> 4u);
+  value = ((value & 0x00ff00ffu) << 8u) | ((value & 0xff00ff00u) >> 8u);
+  return min(f32(value) * inverseU32Range, 0.99999994);
+}
+
+export fn hammersley2d(index: u32, count: u32) -> vec2f {
+  if (count == 0u) {
+    return vec2f(0.0);
+  }
+
+  return vec2f(f32(index) / f32(count), radicalInverseVdc(index));
+}