WAIT — Stale — last commit 1y ago

• 4 active contributors
• MIT licensed
• ⚠ Stale — last commit 1y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 75% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

A WebGL-based 2D fluid dynamics simulator that runs directly in the browser, enabling real-time interactive fluid visualization and manipulation through GPU-accelerated computation. It implements the fast fluid simulation algorithm from GPU Gems, allowing users to interact with virtual fluids via mouse/touch input to create splashes, turbulence, and flow patterns. Monolithic structure: index.html is the entry point, script.js contains the entire simulation engine and UI logic (~51KB), dat.gui.min.js provides GUI controls, and supporting assets (iconfont.ttf, images) are stored in the root directory. No build step, module system, or separation of concerns—pure vanilla WebGL and JavaScript.

Web developers and creative technologists building interactive visualizations, educational demos, or artistic installations that require real-time fluid effects. Users range from casual experimenters testing fluid physics in browsers (including mobile) to developers integrating fluid simulations into WebGL projects.

The project is stable and feature-complete for its scope—it's a single-file implementation (script.js) with no test suite, minimal dependencies, and deployed as a live demo at paveldogreat.github.io. The MIT license and consistent GitHub presence suggest active maintenance, though the lack of CI/CD config and sparse recent commit activity indicate it's in maintenance mode rather than active development.

Risk is minimal: the project has zero external npm dependencies (only dat.gui bundled inline), so supply chain attacks are unlikely. However, it's a single-maintainer repo with no issue tracking visible in the file list, and reliance on WebGL means browser compatibility is critical but unverified by automated tests. The 51KB JavaScript monolith makes debugging or modifying simulation logic directly challenging.

No specific recent changes, PRs, or milestones are visible from the file list provided. The project appears to be in steady-state maintenance: the live demo at paveldogreat.github.io is functional, but active development is not evident.

Clone and open in a browser:

git clone https://github.com/PavelDoGreat/WebGL-Fluid-Simulation.git
cd WebGL-Fluid-Simulation
python3 -m http.server 8000
# Open http://localhost:8000 in your browser

No npm install, build, or dependencies to manage—just serve the files over HTTP.

Daily commands: Serve the directory over HTTP (no dev server needed):

python3 -m http.server 8000
# or
node -e "require('http').createServer((req, res) => require('fs').createReadStream('.' + (req.url === '/' ? '/index.html' : req.url)).pipe(res)).listen(8000)"

Then navigate to http://localhost:8000. Works immediately—no build step.

• script.js — Core simulation engine implementing WebGL-based fluid dynamics; contains all shader programs, simulation loop, and interaction handlers—essential to understand the entire application.
• index.html — Entry point and DOM structure; defines the WebGL canvas and UI elements controlled by dat.gui, required for understanding initialization flow.
• dat.gui.min.js — Third-party UI library providing parameter controls and visualization settings; any UI modifications depend on this dependency.

• WebGL Shader Programs (GLSL ES 2.0, WebGL texture operations) — Implement Navier–Stokes solver steps (advection, diffusion, pressure projection, divergence); compute forces and splat dye.
  • Failure mode: Shader compilation errors crash the simulation; incorrect numerical stencils produce unstable flow or non-divergence-free velocities.
• Texture Management (WebGL framebuffers, texture targets) — Allocate, bind, and swap GPU textures for velocity, pressure, and dye fields across simulation frames.
  • Failure mode: Texture binding errors produce visual artifacts; memory leaks if textures not properly released; format mismatches cause silent failures.
• Interaction Handler (DOM event listeners, canvas coordinate mapping) — Capture mouse/touch input and inject dye and velocity at interaction coordinates.
  • Failure mode: Incorrect coordinate transformation causes splats to appear at wrong canvas location; touch events not registered on mobile.
• dat.gui Parameter Panel (dat.gui library, JavaScript event bindings) — Expose simulation constants (viscosity, time step, splat radius) for real-time user control.
  • Failure mode: Parameter changes not propagated to shaders; UI becomes unresponsive if parameter callbacks block.

• User Input (mouse/touch) → Splat Shader — Coordinates and velocity from interaction event → fragment shader injects dye/velocity into texture.
• Dye/Velocity Texture → Advection Shader — Previous frame texture → shader traces backward along velocity field → new advected texture.
• Velocity Texture → Diffusion Shader — Advected velocity → Jacobi iteration shader applies viscous smoothing.
• Diffused Velocity → Pressure Projection Shader — Velocity field → divergence computed → pressure solved via Jacobi iteration → velocity made divergence-free.
• Final Velocity + Dye → Canvas Rendering — Dye texture rendered to WebGL framebuffer → composited to canvas for display.

Add a new simulation parameter to the UI

1. Open script.js and locate the config object initialization (typically early in the file) (script.js)
2. Add a new property to the configuration object with a default value (script.js)
3. In the dat.gui initialization section, add a new controller using gui.add() to expose the parameter (script.js)
4. Reference the config property in your shader or simulation logic where the parameter should take effect (script.js)

Modify fluid simulation behavior

1. Locate the fragment shader definitions in script.js (typically inline GLSL strings) (script.js)
2. Edit the advection, diffusion, or projection shader to change how velocities and pressures evolve (script.js)
3. Recompile shaders by calling the shader compilation function and test in the simulation loop (script.js)

Change interaction behavior (mouse/touch input)

1. Find mouse event listeners (mousemove, mousedown, touchstart, etc.) in script.js (script.js)
2. Modify the force/velocity injection logic to alter how user input affects the fluid (script.js)
3. Adjust the splat radius or velocity multiplier in the interaction handler to change intensity (script.js)

• WebGL (OpenGL ES 2.0) — Enables GPU-accelerated fluid simulation with parallel texture operations; provides cross-platform graphics access in the browser with strong mobile support.
• GLSL Fragment Shaders — Core computation layer for Navier–Stokes solver; allows per-texel parallel processing of velocity, pressure, and dye fields at GPU speeds.
• dat.gui — Minimalist parameter control panel for real-time tweaking of simulation constants (viscosity, time step, dissipation) without recompiling.
• Canvas 2D + WebGL — Canvas provides display surface; WebGL handles off-screen rendering passes for intermediate simulation steps before final composite.

• Single-file script.js architecture instead of modular build system

  • Why: Reduces deployment complexity and enables zero-dependency deployment; works directly in browser without bundler.
  • Consequence: Large monolithic file makes refactoring difficult; no tree-shaking or code splitting; harder to test individual components.

• Texture-based simulation (values stored in GPU memory) over CPU arrays

  • Why: Avoids expensive GPU↔CPU round-trips; keeps data on GPU for real-time performance.
  • Consequence: Difficult to inspect intermediate values for debugging; requires readPixels() for validation, which stalls the GPU.

• Inline GLSL shaders as JavaScript strings rather than external .glsl files

  • Why: Single HTTP request; no build step; immediate portability.
  • Consequence: No shader syntax highlighting in editor; harder to reuse shaders across projects; shader compilation errors appear at runtime.

• Does not provide 3D volumetric fluid simulation—limited to 2D texture-based incompressible flow.
• Does not support persistent saved simulations or serialization of fluid state.
• Does not implement advanced boundary conditions or obstacle interaction—only domain-wide forces.
• Does not provide performance profiling or GPU timing instrumentation.
• Does not support network multiplayer or real-time synchronization.

• Avg cyclomatic complexity: ~6.5 — Single monolithic file with tightly coupled WebGL state, shader definitions, and interaction logic; high cyclomatic complexity in simulation loop and shader compilation sections; moderate complexity overall for a graphics application.
• Largest file: script.js (1,200 lines)
• Estimated quality issues: ~4 — Lack of modularization, missing error handling in shader compilation, hardcoded magic numbers, and poor separation of concerns between UI and simulation logic reduce maintainability.

• Global shader strings cluttering main function scope (Medium) — script.js: GLSL shader code is defined as inline string literals in the main script, reducing readability and preventing syntax highlighting. Shader changes require string concatenation and are difficult to version control.
• Texture binding state not encapsulated (Medium) — script.js: WebGL texture state and framebuffer targets are managed imperatively without abstraction; easy to accidentally bind wrong texture or render to wrong target.
• Missing error handling in shader compilation (High) — script.js: If shader compilation fails, error messages may not be clearly surfaced to the developer; failures are silent or logged to console.
• Hardcoded magic numbers in simulation parameters (Low) — script.js: Constants like time step, solver iterations, and diffusion coefficients are scattered throughout code rather than centralized in a config object.

• script.js - Pressure projection loop (Jacobi iteration) (GPU bandwidth / round-trip) — Multiple render-to-texture passes (typically 20–40 iterations) to solve the pressure equation; each pass is a full screen quad render with texture lookups.
• script.js - Texture swapping between passes (GPU state management) — Each simulation step (advect, diffuse, project) requires binding different textures as render targets and input samplers; state management overhead.
• Canvas resize handling (Memory allocation) — If canvas is resized, all textures must be reallocated; no incremental resizing strategy.

No hidden gotchas: the project is intentionally simple with no env vars, external services, or build configuration. However: (1) WebGL is required—no fallback for WebGL 1.0-less browsers. (2) The entire state (velocity, pressure, divergence grids) lives in WebGL textures; debugging requires reading framebuffer pixels, which is slow. (3) Shader strings are embedded in JavaScript as plain text—syntax errors produce cryptic WebGL compilation errors.

• Staggered Grid — The fluid solver uses a staggered grid where velocity components (u, v) are stored at cell edges rather than centers—critical for stable pressure projection and mass conservation in incompressible flow
• Incompressible Euler Equations — The mathematical foundation: the simulation solves these equations (with no density variation) to compute velocity fields; understanding the advection-diffusion-projection split is key to modifying the solver
• Pressure Projection / Poisson Solver — The pressure-solve step enforces incompressibility (zero divergence) via iterative Gauss-Seidel on a Poisson equation; this is the most compute-intensive part and directly impacts visual accuracy
• Semi-Lagrangian Advection — Instead of advecting Eulerian grid cells, the solver traces particles backward in time to advect properties; unconditionally stable and used in the advection shader step
• WebGL Framebuffer Objects (FBO) — The grid state (velocity, pressure, color) is stored as textures bound to framebuffers; each simulation step renders to an FBO and swaps the texture ping-pong—core to the GPU compute pattern here
• Texture Ping-Pong — Two alternating textures are used per quantity (e.g., velocity_read, velocity_write) to avoid reading and writing the same texture in a single pass, which GPU hardware cannot do safely
• GLSL Fragment Shaders — All numerical simulation happens in GPU fragment shaders (advection, diffusion, pressure); understanding GLSL syntax and GPU texture sampling is essential to modify or debug the solver

• mharrys/fluids-2d — Referenced in README as a prior implementation; shows an alternative approach to 2D incompressible flow simulation on GPU
• haxiomic/GPU-Fluid-Experiments — Referenced in README as another GPU-accelerated fluid sandbox; demonstrates variations on the same GPU Gems algorithm
• jbouny/ocean — WebGL-based water simulation using FFT; complementary technique for ocean/water surface effects vs. Eulerian grid-based approach here
• dataarts/dat.gui — Official dat.gui repository; this project bundles a minified version for parameter controls

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Extract shader code from script.js into separate .glsl files with a build process

The script.js file likely contains inline WebGL shader code (vertex/fragment shaders) mixed with JavaScript logic. This makes shaders hard to debug, syntax-highlight, and maintain. Extracting shaders into separate .glsl files and using a simple build step (or fetch at runtime) would improve code organization, enable shader linting, and make the codebase more professional for contributors.

• [ ] Create a /shaders directory with separate .glsl files for each shader (e.g., advection.glsl, divergence.glsl, pressure.glsl, etc.)
• [ ] Refactor script.js to load shaders via fetch() or a bundler, with fallback for development
• [ ] Add a simple build script (e.g., npm script) to inline shaders for production if needed
• [ ] Document shader structure in README.md with links to reference implementations

Add mobile-specific touch event handling tests and documentation

The README claims the simulation 'works even on mobile', but there's no visible test coverage or documentation of touch event handling in script.js. Many mobile simulators and real devices have different touch behaviors (multi-touch, pressure sensitivity). Adding explicit touch event tests and documenting tested devices would increase confidence and make it easier for contributors to add features like multi-touch support.

• [ ] Create a test file (e.g., tests/touch-events.test.js) with unit tests for touch event handlers in script.js
• [ ] Document in README.md which devices and browsers have been tested (iOS Safari, Android Chrome, etc.)
• [ ] Add a TESTING.md file with steps to test on mobile devices using browser DevTools device emulation
• [ ] Consider adding a CI workflow (GitHub Actions) to run touch event tests on every PR

Add WebGL capability detection and graceful fallback messaging

The repo has no visible WebGL feature detection or error handling for browsers/devices that don't support WebGL 2.0 or required extensions. Users on older devices or browsers get a silent failure. Adding capability detection with a user-friendly error message would reduce support issues and improve UX.

• [ ] Add a utility function in script.js to detect WebGL 2.0 support and required extensions (e.g., EXT_color_buffer_float)
• [ ] Create a simple modal/message in index.html to display if WebGL is unavailable
• [ ] Test graceful fallback on older browsers (Firefox ESR, Safari 12, etc.) and document in TESTING.md
• [ ] Update README.md with a 'Browser Support' section listing minimum requirements

• Add unit tests for shader correctness: create a test suite (e.g. using Jasmine) that verifies the advection and pressure projection steps produce expected numerical results by reading WebGL framebuffer outputs—currently untested.
• Extract shader code to separate .glsl files and document the staggered grid layout: currently shaders are inline strings in script.js; extracting them and adding comments explaining the grid indexing (u/v component staggering, boundary conditions) would improve maintainability.
• Add mobile gesture support (pinch-to-zoom, two-finger drag for color/viscosity): the current touch handler only supports single-touch drag; adding multi-touch would enhance mobile UX without architectural changes.

The WebGL Fluid Simulation project has a relatively good security posture for a client-side web application. It contains no server-side code, databases, or authentication mechanisms, significantly reducing the attack surface. The main concerns are: (1) lack of formal dependency management and supply chain security practices, (2) missing Content Security Policy headers, and (3) absence of a vulnerability disclosure policy. The project would benefit from implementing npm/yarn lock files, adding CSP headers, and documenting security practices. No critical vulnerabilities were identified.

• Medium · Unminified dat.gui Library — dat.gui.min.js. The project includes dat.gui.min.js, which is a third-party GUI library. While minified, there's no evidence of dependency version pinning, SRI (Subresource Integrity) validation, or lock file management. This could expose the project to supply chain attacks if the library is compromised or updated with malicious code. Fix: Implement dependency management with package.json and npm/yarn lock files. Use SRI attributes if loading from CDN. Pin specific versions and regularly audit dependencies with npm audit or similar tools.
• Low · Missing Content Security Policy — index.html. The index.html file likely lacks a Content Security Policy (CSP) header. While this is a WebGL fluid simulation (low risk for XSS), CSP would prevent potential inline script injection attacks and enforce safer script loading practices. Fix: Add Content-Security-Policy header to HTTP responses or include a meta tag in the HTML head. For example: <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline'"> (adjust as needed for your use case).
• Low · Potential Custom Font Security — iconfont.ttf. The project includes iconfont.ttf font file. Custom fonts can potentially be exploited for information disclosure or fingerprinting attacks if not served with proper CORS headers and content-type validation. Fix: Ensure the font is served with appropriate Content-Type header (font/ttf) and CORS headers if cross-origin access is needed. Consider using WOFF2 format for better compression and browser compatibility.
• Low · Missing security.txt and Security Policy — Repository root. There is no .well-known/security.txt file or SECURITY.md file defining a vulnerability disclosure policy. This makes it difficult for security researchers to report issues responsibly. Fix: Create a SECURITY.md file at the repository root documenting how to report security vulnerabilities. Consider adding .well-known/security.txt for standard vulnerability reporting.
• Low · No HTTPS Enforcement Visible — GitHub Pages configuration. While the GitHub Pages deployment URL uses HTTPS, there's no explicit configuration visible to enforce HTTPS-only access or include HSTS headers in the codebase. Fix: Ensure GitHub Pages HTTPS enforcement is enabled in repository settings. Add HSTS header via _headers file (Netlify) or equivalent if using other hosts.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/PavelDoGreat/WebGL-Fluid-Simulation shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live PavelDoGreat/WebGL-Fluid-Simulation repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/PavelDoGreat/WebGL-Fluid-Simulation.

What it runs against: a local clone of PavelDoGreat/WebGL-Fluid-Simulation — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in PavelDoGreat/WebGL-Fluid-Simulation | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 3 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 573 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of PavelDoGreat/WebGL-Fluid-Simulation. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/PavelDoGreat/WebGL-Fluid-Simulation.git
#   cd WebGL-Fluid-Simulation
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of PavelDoGreat/WebGL-Fluid-Simulation and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "PavelDoGreat/WebGL-Fluid-Simulation(\\.git)?\\b" \\
  && ok "origin remote is PavelDoGreat/WebGL-Fluid-Simulation" \\
  || miss "origin remote is not PavelDoGreat/WebGL-Fluid-Simulation (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "script.js" \\
  && ok "script.js" \\
  || miss "missing critical file: script.js"
test -f "index.html" \\
  && ok "index.html" \\
  || miss "missing critical file: index.html"
test -f "dat.gui.min.js" \\
  && ok "dat.gui.min.js" \\
  || miss "missing critical file: dat.gui.min.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 573 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~543d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/PavelDoGreat/WebGL-Fluid-Simulation"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.