# rogue-agency/shaders architecture

> Architecture diagram of the GitHub repository rogue-agency/shaders, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rogue-agency/shaders
- Repository: https://github.com/rogue-agency/shaders

## Overview

Paper Shaders is a browser-side shader library distributed as vanilla JavaScript and React packages. The principal workflow starts when an external website’s developer renders a shader component or constructs a vanilla mount: React props (or direct uniforms) configure a shader, image inputs may be prepared, and the library renders the effect to a WebGL canvas. The packages include many independent visual effects; they are not a hosted rendering service.

#### Components

##### Public interfaces and React adapters
- **Vanilla package exports** — `packages/shaders/src/index.ts`: Exposes the core mount, sizing utilities, shader presets, fragment shader sources, and parameter/uniform types for direct use by browser applications.
- **React package exports** — `packages/shaders-react/src/index.ts`: Exposes React shader components, presets, and prop types; its client entry point re-exports the framework adapters.
- **React shader adapters** — `packages/shaders-react/src/shaders/mesh-gradient.tsx`: The per-effect adapter pattern is represented by this component; adapters provide React props/default presets, convert colors into uniforms, and render through the shared React mount. The tree shows adapters for many effects.
- **React mount and input handling** — `packages/shaders-react/src/shader-mount.tsx`: Provides the shared React wrapper, asynchronously prepares image uniforms, creates and retains the vanilla mount, and updates uniforms, speed, and pixel limits as props change.

##### Rendering and shader implementation
- **WebGL rendering engine** — `packages/shaders/src/shader-mount.ts`: Creates and manages the WebGL2 program and canvas, sets uniforms and textures, and controls animation, sizing, and visibility-aware speed.
- **Shader sizing and shared utilities** — `packages/shaders/src/shader-sizing.ts`: Defines shared sizing parameters and uniforms used to fit shader output to its rendered element.
- **Effect shader library** — `packages/shaders/src/shaders/mesh-gradient.ts`: Represents the effect modules that define fragment-shader programs and their parameter/uniform contracts; the tree contains a broad catalog of distinct effects.
- **Shared shader helpers and types** — `packages/shaders/src/shader-utils.ts`: Provides reusable shader-level helpers imported by effect modules; shared type definitions are in `packages/shaders/src/types.ts`.

##### Image-based effects
- **Gem Smoke image processing and effect** — `packages/shaders/src/shaders/gem-smoke.ts`: In addition to its fragment shader, exports `toProcessedGemSmoke`, which loads an image, derives shape masks and pixel neighborhoods, solves image data, and produces a PNG blob for the effect.
- **Liquid Metal image effect** — `packages/shaders/src/shaders/liquid-metal.ts`: Implements an image-aware fragment shader that samples image textures and applies animated material treatment; the excerpt also contains image-processing routines, but their complete relationship to this effect cannot be determined from the sample.

##### Package build and release
- **Package build** — `build.js`: Builds both package source trees into browser ESM bundles and declaration files.
- **Package publication** — `publish.js`: Publishes the vanilla and React packages sequentially through the npm CLI, substituting workspace dependency versions during publication.

#### Relationships

- **External website developer -> React package exports**: Imports and renders a published React component; README documents npm installation and examples.
- **External website developer -> Vanilla package exports**: Imports the vanilla package for browser use; README documents this package and framework-independent usage.
- **React package exports -> React shader adapters**: Re-exports effect components and presets; evidenced by the entry-point exports.
- **React shader adapters -> React mount and input handling**: Passes fragment shaders, uniforms, speed, and frame into the shared wrapper; evidenced by `packages/shaders-react/src/shaders/gem-smoke.tsx`.
- **React mount and input handling -> WebGL rendering engine**: Constructs the vanilla `ShaderMount` and calls its update methods; evidenced by `packages/shaders-react/src/shader-mount.tsx`.
- **Vanilla package exports -> WebGL rendering engine**: Exports the mount as the direct-use API; evidenced by `packages/shaders/src/index.ts`.
- **WebGL rendering engine -> Effect shader library**: Compiles and renders the fragment shader supplied by the caller; engine compilation is evidenced in `packages/shaders/src/shader-mount.ts`, while effect modules and exports establish the shader sources.
- **Effect shader library -> Shader sizing and shared utilities**: Effect modules use shared sizing or shader helpers; evidenced by imports in `packages/shaders/src/shaders/liquid-metal.ts`.
- **React shader adapters -> Gem Smoke image processing and effect**: Calls `toProcessedGemSmoke` for image inputs and supplies the processed image as a uniform; evidenced by `packages/shaders-react/src/shaders/gem-smoke.tsx`.
- **Gem Smoke image processing and effect -> React mount and input handling**: The adapter passes its processed image and shader uniforms into the shared React mount; evidenced by the same adapter.
- **Build invocation -> Package build**: The root `build` script runs `build.js`; evidenced by `package.json`.
- **Package build -> Vanilla package exports**: Builds the vanilla source tree into distributable output; evidenced by `build.js`.
- **Package build -> React package exports**: Builds the React source tree into distributable output; evidenced by `build.js`.
- **Publication invocation -> Package publication**: Root publication scripts run the publisher after building; evidenced by `package.json`.
- **Package publication -> npm registry**: Runs `npm publish` for each package; the registry is an external system with no repository path.

#### Coverage limits

The sample does not include the documentation application’s source, most shader implementations, package manifests for both libraries, or the full mount and image-processing code. The README documents designer workflows and examples, but does not establish an in-repository connection from the Paper design product to these package APIs.

Main entry points: [`packages/shaders-react/src/shaders/mesh-gradient.tsx`](https://github.com/rogue-agency/shaders/blob/main/packages/shaders-react/src/shaders/mesh-gradient.tsx) (React Shader Adapters), [`packages/shaders-react/src/shader-mount.tsx`](https://github.com/rogue-agency/shaders/blob/main/packages/shaders-react/src/shader-mount.tsx) (React Mount), [`packages/shaders/src/shader-mount.ts`](https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/shader-mount.ts) (WebGL Engine), [`packages/shaders/src/index.ts`](https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/index.ts) (Vanilla Exports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public Interfaces"]
  node_vanilla_exports["Vanilla Exports<br/>Package API"]
  node_react_exports["React Exports<br/>Package API"]
end

subgraph group_react_integration["React Integration"]
  node_react_adapters["React Shader Adapters<br/>React components"]
  node_react_mount["React Mount<br/>React wrapper"]
end

subgraph group_rendering["Rendering"]
  node_webgl_engine["WebGL Engine<br/>Renderer"]
  node_shader_utilities["Shader Utilities<br/>Sizing and helpers"]
end

subgraph group_shader_effects["Shader Effects"]
  node_effect_library["Effect Shader Library<br/>Fragment shaders"]
  node_gem_smoke["Gem Smoke Processing<br/>Image effect"]
end

node_website_developer["Website Developer<br/>External actor"]

node_website_developer -->|"imports and renders"| node_react_exports
node_website_developer -->|"imports"| node_vanilla_exports
node_react_exports -->|"re-exports"| node_react_adapters
node_react_adapters -->|"passes shader props"| node_react_mount
node_react_mount -->|"creates and updates"| node_webgl_engine
node_vanilla_exports -->|"exports mount"| node_webgl_engine
node_webgl_engine -->|"compiles supplied shaders"| node_effect_library
node_effect_library -->|"uses helpers"| node_shader_utilities
node_react_adapters -->|"processes image inputs"| node_gem_smoke
node_gem_smoke -->|"supplies processed image"| node_react_mount

click node_vanilla_exports "https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/index.ts"
click node_react_exports "https://github.com/rogue-agency/shaders/blob/main/packages/shaders-react/src/index.ts"
click node_react_adapters "https://github.com/rogue-agency/shaders/blob/main/packages/shaders-react/src/shaders/mesh-gradient.tsx"
click node_react_mount "https://github.com/rogue-agency/shaders/blob/main/packages/shaders-react/src/shader-mount.tsx"
click node_webgl_engine "https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/shader-mount.ts"
click node_shader_utilities "https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/shader-sizing.ts"
click node_effect_library "https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/shaders/mesh-gradient.ts"
click node_gem_smoke "https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/shaders/gem-smoke.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_vanilla_exports,node_react_exports toneBlue
class node_react_adapters,node_react_mount toneAmber
class node_webgl_engine,node_shader_utilities toneMint
class node_effect_library,node_gem_smoke toneRose
class node_website_developer toneIndigo
```

## Components

### Public Interfaces

- [Vanilla Exports](https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/index.ts): Package API · `packages/shaders/src/index.ts`
- [React Exports](https://github.com/rogue-agency/shaders/blob/main/packages/shaders-react/src/index.ts): Package API · `packages/shaders-react/src/index.ts`

### React Integration

- [React Shader Adapters](https://github.com/rogue-agency/shaders/blob/main/packages/shaders-react/src/shaders/mesh-gradient.tsx): React components · `packages/shaders-react/src/shaders/mesh-gradient.tsx`
- [React Mount](https://github.com/rogue-agency/shaders/blob/main/packages/shaders-react/src/shader-mount.tsx): React wrapper · `packages/shaders-react/src/shader-mount.tsx`

### Rendering

- [WebGL Engine](https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/shader-mount.ts): Renderer · `packages/shaders/src/shader-mount.ts`
- [Shader Utilities](https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/shader-sizing.ts): Sizing and helpers · `packages/shaders/src/shader-sizing.ts`

### Shader Effects

- [Effect Shader Library](https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/shaders/mesh-gradient.ts): Fragment shaders · `packages/shaders/src/shaders/mesh-gradient.ts`
- [Gem Smoke Processing](https://github.com/rogue-agency/shaders/blob/main/packages/shaders/src/shaders/gem-smoke.ts): Image effect · `packages/shaders/src/shaders/gem-smoke.ts`

### Other components

- **Website Developer**: External actor

## Connections

- Website Developer → React Exports: imports and renders
- Website Developer → Vanilla Exports: imports
- React Exports → React Shader Adapters: re-exports
- React Shader Adapters → React Mount: passes shader props
- React Mount → WebGL Engine: creates and updates
- Vanilla Exports → WebGL Engine: exports mount
- WebGL Engine → Effect Shader Library: compiles supplied shaders
- Effect Shader Library → Shader Utilities: uses helpers
- React Shader Adapters → Gem Smoke Processing: processes image inputs
- Gem Smoke Processing → React Mount: supplies processed image