Clearwater — Interactive Water Hero

Purpose

Integrate Clearwater as a responsive, interactive hero background while keeping headings, navigation, and calls to action accessible and usable. This is an integration skill derived from the repository, not an upstream SKILL.md.

Source

• Repository: https://github.com/Aureliengmz/clearwater
• Live demo: https://aureliengmz.github.io/clearwater/
• Reference revision: 4bc826134321043a25df3c2b6fed16fb7b9241e8
• Author: Aurélien / Lumaris
• License: MIT; preserve the copyright and license notice when redistributing the source.

When to use

Use when a user requests a realistic water background, an interactive ripple hero, or this specific Clearwater effect. Do not replace unrelated page content or interactions.

Implementation workflow

1. Inspect the existing hero, navigation height, responsive breakpoints, and page scrolling before making changes.
2. Read the upstream README and use the pinned index.html from the reference revision. Clearwater is a standalone WebGL2 document with no libraries, build step, or external rendering assets required. Do not add Three.js or another rendering library just to embed it.
3. Place the effect inside a dedicated background component, positioned absolutely within a relative, overflow-hidden hero. Prefer a locally hosted, pinned copy of the standalone HTML or an isolated iframe. Keep hero text and controls in the parent document.
4. Check WebGL2 and EXT_color_buffer_float support before starting the effect. Show a static landscape fallback when unsupported or when loading fails; keep the hero content usable throughout loading. The upstream preview is https://raw.githubusercontent.com/Aureliengmz/clearwater/4bc826134321043a25df3c2b6fed16fb7b9241e8/media/landscape.png.
5. Set an initial pitch around -0.15 radians when land should be visible above the water. The upstream page supports ?yaw=0.5&pitch=-0.4 as camera options; adapt pitch to the desired composition. When using iframe srcDoc, configure the document's camera parameters inside the embedded HTML before camera initialization, because the parent page query does not configure srcDoc automatically.
6. Preserve dragging to look around and tapping to create ripples. Decorative parent overlays should use pointer-events:none; real links and buttons must remain pointer-events:auto. Ensure mobile users retain an obvious way to scroll past an interactive iframe.
7. Fit the mobile hero to the available viewport below the header, using dynamic viewport units and balanced padding. Keep the title, description, and primary action centered without covering the interaction hint or scroll control.
8. Preserve upstream adaptive quality and resolution behavior. Respect reduced-motion preferences with a static presentation when appropriate. Remove the embedded document on unmount and prevent late asynchronous updates after unmount.
9. Keep loading indicators understandable and avoid implying that iframe load alone proves successful WebGL rendering. Maintain readable text contrast over both the effect and fallback.

Upstream customization map

• Ocean spectrum (FFT): L, DEPTH, TARGET_SLOPE.
• Interactive ripples: RN and RSIZE.
• Caustics: G, C, and IORS.
• Main water shader: Fresnel, absorption, and seabed shading.
• Camera and input: SUN_EL, SUN_AZ, and VFOV.
• Loop: frame scheduling and adaptive quality.

Debug options

Use ?debug for frame rate, resolution, and quality; ?noglare to disable lens-diffraction glare; ?t=5 to freeze time for a reference image; and ?view=caus to inspect caustics. Apply these to the actual embedded document rather than assuming parent-page parameters are inherited.

Acceptance criteria

The water responds to input, the default composition includes distant land when requested, mobile and desktop text stay readable, all hero actions work, page scrolling remains possible, unsupported devices see a useful static background, and unrelated page functionality is unchanged.

• Requires WebGL2 with EXT_color_buffer_float for the interactive renderer.
• Pin the upstream source revision rather than relying on a changing branch.
• Preserve the upstream MIT copyright and license notice in redistributed source.
• Keep simulation internals isolated from the host application's UI.
• Do not add rendering dependencies that Clearwater does not require.
• Avoid storing the HTML document or its embedded base64 texture in a database field; host it as a file.
• Keep mobile scrolling, keyboard navigation, and primary hero actions usable.

• Covering the effect with a pointer-intercepting decorative overlay.
• Letting the interactive background block the call-to-action or all mobile page scrolling.
• Initializing unsupported WebGL repeatedly or retrying forever.
• Assuming iframe onLoad means the renderer started successfully.
• Passing camera parameters only to the parent URL when the effect uses srcDoc.
• Rebuilding the FFT, caustics, or shader implementation when embedding the existing effect is sufficient.
• Removing license notices from redistributed source.

1. Open the hero on desktop and mobile: confirm land is visible in the default composition and the main content is centered.
2. Drag the water to change the view and tap it to create ripples.
3. Use every hero link and scroll beyond the hero with touch, mouse, and keyboard.
4. Disable WebGL2 or float render target support: confirm the static fallback and readable content remain visible.
5. Simulate a failed source load: confirm loading does not remain indefinitely.
6. Navigate away and back: confirm there are no duplicate embedded renderers or stale updates.
7. Enable reduced motion and confirm the chosen static presentation.
8. Inspect ?debug on a lower-powered device and confirm adaptive quality remains enabled.

Copy the Spec into your coding assistant and ask it to apply the Clearwater hero effect to the desired section. Provide your hero component and whether the default view should include the distant land. For a standalone preview, open the repository's index.html directly in a browser or serve it from a static host; nothing needs to be installed. Use the repository README for supported camera and debug options.