matrix-rain-webgpu 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabrizio Duroni
+
+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,82 @@
+# matrix-rain-webgpu
+
+[![Deploy](https://github.com/chicio/matrix-rain-webgpu/actions/workflows/deploy.yml/badge.svg)](https://github.com/chicio/matrix-rain-webgpu/actions/workflows/deploy.yml)
+
+> A Matrix-style "digital rain" background effect for React, rendered on the GPU with WebGPU via [TypeGPU](https://docs.swmansion.com/TypeGPU/). GPU-driven simulation, signed-distance-field glyphs, depth parallax, bloom, and a CRT post-process.
+
+**▶ Live demo & full documentation: https://chicio.github.io/matrix-rain-webgpu/**
+
+It powers the animated background on [fabrizioduroni.it](https://www.fabrizioduroni.it). Requires a WebGPU-capable browser (recent Chrome / Edge / Safari / Firefox).
+
+## Install
+
+```sh
+npm install matrix-rain-webgpu react react-dom typegpu @typegpu/react @typegpu/noise
+```
+
+`react`/`react-dom` (v19) and `typegpu`/`@typegpu/react`/`@typegpu/noise` (v0.11) are
+peer dependencies — they must resolve to a single instance in your app, so you install
+them yourself. The shaders are pre-compiled at publish time, so you do **not** need any
+TypeGPU build plugin.
+
+> **Module resolution:** the published types target bundler-style resolution
+> (`moduleResolution: "bundler"` / `"node"`), which is what Vite, Next.js, and most React
+> setups use. Strict `"node16"`/`"nodenext"` resolution isn't supported yet.
+
+## Usage
+
+The component renders a `<canvas>` that fills its positioned parent and ignores pointer events:
+
+```tsx
+import { MatrixRainWebGPU } from 'matrix-rain-webgpu';
+
+export function Background() {
+  return (
+    <div style={{ position: 'relative', width: '100%', height: '100dvh' }}>
+      <MatrixRainWebGPU />
+    </div>
+  );
+}
+```
+
+Everything is optional and grouped — omit for defaults, pass an object to tune, or `false` to disable an effect:
+
+```tsx
+<MatrixRainWebGPU rain={{ fontSize: 24 }} bloom={{ intensity: 2 }} crt={false} />
+```
+
+WebGPU isn't available everywhere; gate on `isWebGPUSupported()` and render your own fallback when it's missing:
+
+```tsx
+import { MatrixRainWebGPU, isWebGPUSupported } from 'matrix-rain-webgpu';
+
+return isWebGPUSupported() ? <MatrixRainWebGPU /> : <My2DFallback />;
+```
+
+## Documentation
+
+Full docs live on the site — including the interactive playground:
+
+- **[Getting started](https://chicio.github.io/matrix-rain-webgpu/overview/getting-started/)** & **[Public API](https://chicio.github.io/matrix-rain-webgpu/usage/public-api/)** — install, props, recipes.
+- **[Architecture](https://chicio.github.io/matrix-rain-webgpu/architecture/pipeline-overview/)** — how the pieces connect.
+- **[How it works](https://chicio.github.io/matrix-rain-webgpu/how-it-works/glyph-rendering/)** — per-component deep dives, with the computer-graphics concepts and the math.
+- **[Playground](https://chicio.github.io/matrix-rain-webgpu/playground/)** — the live demo with every knob exposed.
+
+## Local development
+
+This repo is two packages: the publishable library at the root (`src/`) and the docs + demo site (`docs/`, an Astro + Starlight app).
+
+```sh
+# Library — typecheck + lint/format
+npm install
+npm run types
+npm run check
+
+# Docs + demo site (Astro)
+npm --prefix docs install
+npm --prefix docs run dev
+```
+
+## Author
+
+Built by [Fabrizio Duroni](https://www.fabrizioduroni.it). If you enjoy it, a visit to the site is the best way to support the work. Also don't foget to star this repository :star:

package/dist/gpu/atlas/bindings.d.ts

@@ -0,0 +1,9 @@
+import { d } from 'typegpu';
+export declare const atlasBindings: import("typegpu").TgpuBindGroupLayout<{
+    atlas: {
+        texture: d.WgslTexture2dArray<d.F32>;
+    };
+    sampler: {
+        sampler: "filtering";
+    };
+}>;

package/dist/gpu/atlas/build-sdf-atlas.d.ts

@@ -0,0 +1,6 @@
+export type SdfAtlas = {
+    data: Uint8Array;
+    layerCount: number;
+    layerSize: number;
+};
+export declare function buildSdfAtlas(): Promise<SdfAtlas>;

package/dist/gpu/atlas/glyph-set.d.ts

@@ -0,0 +1,3 @@
+export declare const GLYPHS: string[];
+export declare const GLYPH_COUNT: number;
+export declare const ATLAS_LAYER_SIZE = 64;

package/dist/gpu/feature-detect.d.ts

@@ -0,0 +1 @@
+export declare const isWebGPUSupported: () => boolean;

package/dist/gpu/material/hash.d.ts

@@ -0,0 +1,3 @@
+import { d } from 'typegpu';
+export declare const glyphIndex: import("typegpu").TgpuFn<(seed: d.U32, slotY: d.U32) => d.U32>;
+export declare const brightnessJitter: import("typegpu").TgpuFn<(seed: d.U32, slotY: d.U32) => d.F32>;

package/dist/gpu/material/palette.d.ts

@@ -0,0 +1,6 @@
+export declare const PALETTE: {
+    readonly background: readonly [0, number, 0, 1];
+    readonly head: readonly [number, number, number, 1];
+    readonly trail: readonly [0, number, number, 1];
+    readonly fade: readonly [0, number, number, 1];
+};

package/dist/gpu/pipelines/blit.d.ts

@@ -0,0 +1,11 @@
+import { d, type TgpuRoot } from 'typegpu';
+export declare const blitBindings: import("typegpu").TgpuBindGroupLayout<{
+    source: {
+        texture: d.WgslTexture2d<d.F32>;
+    };
+    sampler: {
+        sampler: "filtering";
+    };
+}>;
+export declare function createBlitPipeline(root: TgpuRoot): import("typegpu").TgpuRenderPipeline<d.Vec4f>;
+export type BlitPipeline = ReturnType<typeof createBlitPipeline>;

package/dist/gpu/pipelines/bloom.d.ts

@@ -0,0 +1,19 @@
+import { d, type TgpuRoot, type TgpuUniform } from 'typegpu';
+import { Uniforms } from '../schemas/uniforms';
+export declare function createExtractPipeline(root: TgpuRoot, uniforms: TgpuUniform<typeof Uniforms>, format: GPUTextureFormat): import("typegpu").TgpuRenderPipeline<d.Vec4f>;
+export type ExtractPipeline = ReturnType<typeof createExtractPipeline>;
+export declare function createBlurPipeline(root: TgpuRoot, uniforms: TgpuUniform<typeof Uniforms>, format: GPUTextureFormat, direction: readonly [number, number]): import("typegpu").TgpuRenderPipeline<d.Vec4f>;
+export type BlurPipeline = ReturnType<typeof createBlurPipeline>;
+export declare const combineBindings: import("typegpu").TgpuBindGroupLayout<{
+    scene: {
+        texture: d.WgslTexture2d<d.F32>;
+    };
+    bloom: {
+        texture: d.WgslTexture2d<d.F32>;
+    };
+    sampler: {
+        sampler: "filtering";
+    };
+}>;
+export declare function createCombinePipeline(root: TgpuRoot, uniforms: TgpuUniform<typeof Uniforms>, format: GPUTextureFormat): import("typegpu").TgpuRenderPipeline<d.Vec4f>;
+export type CombinePipeline = ReturnType<typeof createCombinePipeline>;

package/dist/gpu/pipelines/compute-step.d.ts

@@ -0,0 +1,6 @@
+import { d, type TgpuMutable, type TgpuRoot, type TgpuUniform } from 'typegpu';
+import { Column } from '../schemas/column';
+import { Uniforms } from '../schemas/uniforms';
+export declare const COMPUTE_STEP_WORKGROUP_SIZE = 64;
+export declare function createComputeStepPipeline(root: TgpuRoot, columns: TgpuMutable<d.WgslArray<typeof Column>>, uniforms: TgpuUniform<typeof Uniforms>): import("typegpu").TgpuComputePipeline;
+export type ComputeStepPipeline = ReturnType<typeof createComputeStepPipeline>;

package/dist/gpu/pipelines/crt.d.ts

@@ -0,0 +1,4 @@
+import { d, type TgpuRoot, type TgpuUniform } from 'typegpu';
+import { Uniforms } from '../schemas/uniforms';
+export declare function createCrtPipeline(root: TgpuRoot, uniforms: TgpuUniform<typeof Uniforms>): import("typegpu").TgpuRenderPipeline<d.Vec4f>;
+export type CrtPipeline = ReturnType<typeof createCrtPipeline>;

package/dist/gpu/pipelines/render-glyphs.d.ts

@@ -0,0 +1,5 @@
+import { d, type TgpuMutable, type TgpuRoot, type TgpuUniform } from 'typegpu';
+import { Column } from '../schemas/column';
+import { Uniforms } from '../schemas/uniforms';
+export declare function createRenderGlyphsPipeline(root: TgpuRoot, columns: TgpuMutable<d.WgslArray<typeof Column>>, uniforms: TgpuUniform<typeof Uniforms>, format: GPUTextureFormat): import("typegpu").TgpuRenderPipeline<d.Vec4f>;
+export type RenderGlyphsPipeline = ReturnType<typeof createRenderGlyphsPipeline>;

package/dist/gpu/render-graph.d.ts

@@ -0,0 +1,31 @@
+import { type TgpuRoot } from 'typegpu';
+import type { SdfAtlas } from './atlas/build-sdf-atlas';
+import type { BloomConfig, CrtConfig, ParallaxConfig } from '../types';
+export type CreateRenderGraphArgs = {
+    root: TgpuRoot;
+    ctx: GPUCanvasContext;
+    atlas: SdfAtlas;
+    cellSize: number;
+    density: number;
+    stepRate: number;
+    tailRange: [number, number];
+    bloom: BloomConfig;
+    crt: CrtConfig;
+    parallax: ParallaxConfig;
+};
+export type RenderGraph = {
+    resize: (width: number, height: number) => void;
+    step: (deltaSeconds: number, elapsedSeconds: number) => void;
+    settle: () => void;
+    render: () => void;
+    setDensity: (density: number) => void;
+    setStepRate: (stepRate: number) => void;
+    setTailRange: (range: [number, number]) => void;
+    setBloom: (config: BloomConfig) => void;
+    setCrt: (config: CrtConfig) => void;
+    setParallax: (config: ParallaxConfig) => void;
+    regenerate: () => void;
+    getColumnCount: () => number;
+    dispose: () => void;
+};
+export declare function createRenderGraph(args: CreateRenderGraphArgs): RenderGraph;

package/dist/gpu/schemas/column.d.ts

@@ -0,0 +1,8 @@
+import { d } from 'typegpu';
+export declare const Column: d.WgslStruct<{
+    headY: d.F32;
+    speed: d.F32;
+    depth: d.F32;
+    tailLength: d.F32;
+    seed: d.U32;
+}>;

package/dist/gpu/schemas/uniforms.d.ts

@@ -0,0 +1,14 @@
+import { d } from 'typegpu';
+export declare const Uniforms: d.WgslStruct<{
+    time: d.F32;
+    stepProgress: d.F32;
+    resolution: d.Vec2f;
+    cellSize: d.F32;
+    density: d.F32;
+    depthDim: d.F32;
+    bloomThreshold: d.F32;
+    bloomIntensity: d.F32;
+    headEmission: d.F32;
+    scanlineStrength: d.F32;
+    aberration: d.F32;
+}>;

package/dist/hooks/use-matrix-rain-renderer.d.ts

@@ -0,0 +1,21 @@
+import { type RefObject } from 'react';
+import type { BloomConfig, CrtConfig, ParallaxConfig } from '../types';
+type UseMatrixRainRendererArgs = {
+    ctxRef: RefObject<GPUCanvasContext | null>;
+    cellSize: number;
+    density: number;
+    stepRate: number;
+    tailRange: [number, number];
+    bloom: BloomConfig;
+    crt: CrtConfig;
+    parallax: ParallaxConfig;
+    paused: boolean;
+    onError?: ((err: Error) => void) | undefined;
+};
+export type MatrixRainRenderer = {
+    tick: (deltaSeconds: number, elapsedSeconds: number) => void;
+    regenerate: () => void;
+    columnCount: number;
+};
+export declare function useMatrixRainRenderer(args: UseMatrixRainRendererArgs): MatrixRainRenderer;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { MatrixRainWebGPU } from './matrix-rain';
+export { isWebGPUSupported } from './gpu/feature-detect';
+export type { MatrixRainProps, RainOptions, ParallaxOptions, BloomOptions, CrtOptions, } from './types';