feat(shaders): add LiquidGradient

.changeset/liquid-gradient.md

@@ -0,0 +1,7 @@
+---
+'@camp-dev/shaders': minor
+---
+
+Add `LiquidGradient`, a Source that streaks bands of color along slow, curling currents, like paint stirred into liquid. Mount it inside a `ShaderScene`. `stops`, `colorSpace`, and `hueInterpolation` pick the colors, as they do on `LinearGradient`. `angle` and `repeat` lay the bands out before the current moves them, and `softness` sets how the colors meet, from hard bands at 0 to full blends at 1. `swirl` sets how far the current carries the colors, `scale` sets roughly how many eddies span the canvas's height, and `speed` sets how fast the current drifts. Each of those six props takes a static value or an animation signal. `seed` picks a different layout with the same look. A literal `speed={0}` holds the current still and lets the scene park. It works in Mode 1 only.
+
+`LiquidGradient` draws the current, a noise field, and its palette into textures before the scene pass, and redraws each texture only when a prop it depends on changes. Where the renderer cannot draw into a half-float target, on WebGL2 without `EXT_color_buffer_float`, every read works its value out from the noise or the palette instead. The result looks the same and costs more GPU time.

GLOSSARY.md

@@ -14,6 +14,10 @@ _Avoid_: Base component, generator, layer
 A component that acts on the image beneath it in a scene rather than drawing its own, such as Grain, Dither, or LedWall. An Effect composes over any Source or Effect mounted before it.
 _Avoid_: Overlay, post-process pass, post-process layer, filter
 
+**UV warp**:
+An Effect's change to where the image beneath it is sampled, such as Dither's pixel snap or CursorRipple's refraction. A UV warp bends only what Sources drew.
+_Avoid_: Warp on its own, base UV transform
+
 **Input**:
 A value that changes over time and is not drawn, such as the cursor, scroll, or canvas size. An Input is fed to a component as an animation signal.
 _Avoid_: Cursor hook, entry point, scene-level field

apps/docs-tests/visual/liquid-gradient.spec.ts

@@ -0,0 +1,8 @@
+import { expect, test } from './fixtures';
+import { waitForShader } from './helpers';
+
+test('LiquidGradient — default story', async ({ page }) => {
+  await page.goto('/components/liquid-gradient?visualTest=1');
+  await waitForShader(page);
+  await expect(page.locator('canvas').first()).toHaveScreenshot('liquid-gradient-default.png');
+});

apps/docs/src/app/components/demo-registry.tsx

@@ -21,6 +21,7 @@ import { GodRaysIsland } from './god-rays/demo';
 import { GrainIsland } from './grain/demo';
 import { LedWallIsland } from './led-wall/demo';
 import { LinearGradientIsland } from './linear-gradient/demo';
+import { LiquidGradientIsland } from './liquid-gradient/demo';
 import { MeshGradientIsland } from './mesh-gradient/demo';
 import { RadialGradientIsland } from './radial-gradient/demo';
 import { RadialWipeIsland } from './radial-wipe/demo';
@@ -248,6 +249,12 @@ export const COMPONENT_PAGES: Record<string, ComponentPageEntry> = {
     Island: LinearGradientIsland,
     usageSnippet: `<ShaderScene>
   <LinearGradient />
+</ShaderScene>`,
+  },
+  'liquid-gradient': {
+    Island: LiquidGradientIsland,
+    usageSnippet: `<ShaderScene>
+  <LiquidGradient />
 </ShaderScene>`,
   },
   'mesh-gradient': {

apps/docs/src/app/components/liquid-gradient/demo.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+/**
+ * LiquidGradient demo island: the interactive slice of the LiquidGradient
+ * page — control store, shader preview, and control panel for the bands,
+ * the current that streaks them, mixing, and the color stops. The shared
+ * components/[slug] template renders this between its static header and
+ * prose sections.
+ */
+import dynamic from 'next/dynamic';
+import { useMemo } from 'react';
+
+import {
+  COLOR_SPACE_OPTIONS,
+  ColorInput,
+  ControlPanel,
+  ControlsProvider,
+  createControlStore,
+  DemoLayout,
+  HUE_ARC_OPTIONS,
+  ListInput,
+  NumberInput,
+  Section,
+  SelectInput,
+  SliderInput,
+  useSnapshot,
+} from '@/components/controls';
+import { DemoPoster } from '@/components/DemoPoster';
+import { createStop, newStopIndex } from '@/lib/stops';
+import { VisualTestPause } from '@/lib/visualTestHooks';
+
+import { INITIAL, MAX_STOPS, MIN_STOPS } from './params';
+import type { Params, Stop } from './params';
+
+const LiquidGradientScene = dynamic(() => import('./scene'), { ssr: false });
+
+function LiquidGradientDemo() {
+  const params = useSnapshot<Params>();
+
+  return (
+    <DemoPoster
+      alt="Liquid gradient shader preview: blue, violet, and purple streaked along curling currents"
+      src="/posters/liquid-gradient.jpg"
+    >
+      <LiquidGradientScene params={params}>
+        <VisualTestPause />
+      </LiquidGradientScene>
+    </DemoPoster>
+  );
+}
+
+function LiquidGradientControls() {
+  return (
+    <ControlPanel>
+      <Section title="Bands">
+        <SliderInput label="Angle" max={360} min={0} path="angle" step={1} />
+        <SliderInput label="Repeat" max={8} min={1} path="repeat" step={0.1} />
+        <SliderInput label="Softness" max={1} min={0} path="softness" step={0.01} />
+      </Section>
+      <Section title="Flow">
+        <SliderInput label="Swirl" max={2} min={0} path="swirl" step={0.01} />
+        <SliderInput label="Scale" max={4} min={0.5} path="scale" step={0.1} />
+        <SliderInput label="Speed" max={2} min={0} path="speed" step={0.01} />
+        <SliderInput label="Seed" max={100} min={0} path="seed" step={1} />
+      </Section>
+      <Section title="Mixing">
+        <SelectInput label="Color space" options={COLOR_SPACE_OPTIONS} path="colorSpace" />
+        <SelectInput label="Hue arc" options={HUE_ARC_OPTIONS} path="hueInterpolation" />
+      </Section>
+      <ListInput<Stop>
+        createItem={createStop}
+        insertIndex={newStopIndex}
+        itemLabel="stop"
+        label="Color stops"
+        max={MAX_STOPS}
+        min={MIN_STOPS}
+        path="stops"
+      >
+        {() => (
+          <>
+            <ColorInput label="Color" path="color" />
+            <NumberInput
+              label="Position"
+              max={1}
+              min={0}
+              path="position"
+              scale={100}
+              step={0.01}
+              unit="%"
+            />
+          </>
+        )}
+      </ListInput>
+    </ControlPanel>
+  );
+}
+
+export function LiquidGradientIsland() {
+  const store = useMemo(() => createControlStore<Params>(INITIAL), []);
+
+  return (
+    <ControlsProvider store={store}>
+      <DemoLayout controls={<LiquidGradientControls />}>
+        <div data-shader-demo>
+          <LiquidGradientDemo />
+        </div>
+      </DemoLayout>
+    </ControlsProvider>
+  );
+}

apps/docs/src/app/components/liquid-gradient/params.ts

@@ -0,0 +1,43 @@
+import type { ColorSpace, HueInterpolation } from '@camp-dev/shaders';
+
+import { paletteOklch } from '../../../lib/palette';
+
+export interface Stop {
+  color: string;
+  position: number;
+}
+
+export interface Params {
+  angle: number;
+  repeat: number;
+  softness: number;
+  swirl: number;
+  scale: number;
+  speed: number;
+  seed: number;
+  colorSpace: ColorSpace;
+  hueInterpolation: HueInterpolation;
+  stops: Stop[];
+}
+
+export const MIN_STOPS = 1;
+export const MAX_STOPS = 6;
+
+// Values mirror the component defaults in liquid-gradient.tsx. Keep the two
+// in sync.
+export const INITIAL: Params = {
+  angle: 0,
+  repeat: 2,
+  softness: 1,
+  swirl: 0.9,
+  scale: 1.5,
+  speed: 0.15,
+  seed: 0,
+  colorSpace: 'oklab',
+  hueInterpolation: 'shorter',
+  stops: [
+    { color: paletteOklch.blue[3], position: 0 },
+    { color: paletteOklch.violet[6], position: 0.5 },
+    { color: paletteOklch.purple[9], position: 1 },
+  ],
+};

apps/docs/src/app/components/liquid-gradient/scene.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { LiquidGradient, ShaderScene } from '@camp-dev/shaders';
+
+import { INITIAL, type Params } from './params';
+
+export default function LiquidGradientScene({
+  params = INITIAL,
+  children,
+}: {
+  params?: Params;
+  children?: ReactNode;
+} = {}) {
+  return (
+    <ShaderScene>
+      <LiquidGradient
+        angle={params.angle}
+        colorSpace={params.colorSpace}
+        hueInterpolation={params.hueInterpolation}
+        repeat={params.repeat}
+        scale={params.scale}
+        seed={params.seed}
+        softness={params.softness}
+        speed={params.speed}
+        stops={params.stops}
+        swirl={params.swirl}
+      />
+      {children}
+    </ShaderScene>
+  );
+}

apps/docs/src/app/dev/liquid-gradient-benchmark/benchmark-scene.tsx

@@ -0,0 +1,83 @@
+'use client';
+
+// Benchmark for LiquidGradient with ShaderMonitor's GPU readout (SHA-223).
+// `?size=card` renders it in the Reactive card's 312 by 309 CSS-pixel
+// window, where it must stay under 0.4 ms at 2x; `?size=full` renders it at
+// 1440 by 900. `?dpr=2` caps the canvas at two pixels per CSS pixel, and
+// anything else at one. `?still` sets speed to 0, the Reactive card's
+// parked case, while the scene keeps drawing. `?baseline` renders a
+// LinearGradient instead: it reads about 0.12 ms in the card window at 2x
+// on the M1 Max, so a higher reading means another tab or app is sharing
+// the GPU and every reading beside it is inflated (the skewed-readout
+// gotcha in docs/agents/tsl.md). The links are full page loads, so each
+// measurement starts from a fresh renderer.
+import { useState } from 'react';
+
+import {
+  LinearGradient,
+  LiquidGradient,
+  ShaderMonitor,
+  ShaderScene,
+  useStaticSceneHint,
+} from '@camp-dev/shaders';
+
+const SIZES = {
+  card: { width: 312, height: 309 },
+  full: { width: 1440, height: 900 },
+} as const;
+
+type SizeName = keyof typeof SIZES;
+
+interface Settings {
+  size: SizeName;
+  pixelRatio: number;
+  still: boolean;
+  baseline: boolean;
+}
+
+const readSettings = (): Settings => {
+  const search = new URLSearchParams(window.location.search);
+
+  return {
+    size: search.get('size') === 'full' ? 'full' : 'card',
+    pixelRatio: search.get('dpr') === '2' ? 2 : 1,
+    still: search.has('still'),
+    baseline: search.has('baseline'),
+  };
+};
+
+/**
+ * Votes the scene animated, so a still gradient keeps drawing frames and the
+ * GPU readout averages many frames instead of settling on one.
+ */
+function KeepDrawing() {
+  useStaticSceneHint(false);
+
+  return null;
+}
+
+export default function BenchmarkScene() {
+  const [{ size, pixelRatio, still, baseline }] = useState(readSettings);
+  const { width, height } = SIZES[size];
+  const query = (overrides: Partial<Record<'size' | 'dpr', string>>) =>
+    `?size=${overrides.size ?? size}&dpr=${overrides.dpr ?? pixelRatio}`;
+
+  return (
+    <main style={{ padding: 24, background: '#000', color: '#fff', minHeight: '100vh' }}>
+      <p style={{ margin: '0 0 16px', font: '13px ui-monospace, monospace' }}>
+        {baseline ? 'LinearGradient baseline' : 'LiquidGradient'}
+        {still ? ' (still)' : ''} at {width} × {height} CSS px, pixel ratio capped at {pixelRatio}x.{' '}
+        <a href={query({ size: 'card' })}>card</a> · <a href={query({ size: 'full' })}>full</a> ·{' '}
+        <a href={query({ dpr: '1' })}>1x</a> · <a href={query({ dpr: '2' })}>2x</a> ·{' '}
+        <a href={`${query({})}&still`}>still</a> · <a href={`${query({})}&baseline`}>baseline</a>
+      </p>
+      <div style={{ position: 'relative', width, height }}>
+        <ShaderScene maxDPR={pixelRatio}>
+          {baseline ? <LinearGradient /> : <LiquidGradient speed={still ? 0 : undefined} />}
+          <KeepDrawing />
+          <ShaderMonitor anchor="top-left" />
+        </ShaderScene>
+      </div>
+    </main>
+  );
+}

apps/docs/src/app/dev/liquid-gradient-benchmark/page.dev.tsx

@@ -0,0 +1,12 @@
+'use client';
+
+import dynamic from 'next/dynamic';
+
+// three/webgpu references `self` at module load and cannot SSR, so the
+// benchmark scene is loaded client-only. Dev route: invisible to production
+// builds.
+const BenchmarkScene = dynamic(() => import('./benchmark-scene'), { ssr: false });
+
+export default function LiquidGradientBenchmarkPage() {
+  return <BenchmarkScene />;
+}

apps/docs/src/content/components.ts

@@ -83,6 +83,11 @@ export const COMPONENTS = {
     description: 'Animated linear gradient. The simplest, foundational Shaders component.',
     category: 'gradients',
   },
+  'liquid-gradient': {
+    description:
+      "Colors streaked along slow, curling currents, like dye in moving water. Takes LinearGradient's stops and angle.",
+    category: 'gradients',
+  },
   'mesh-gradient': {
     description:
       'Warped 4-color fluid gradient with time-cycling palette and film grain. Linear/Stripe marketing-page style.',

packages/shaders/src/components/index.ts

@@ -49,6 +49,9 @@ export type { LedWallProps } from './led-wall/led-wall.js';
 export { LinearGradient } from './linear-gradient/linear-gradient.js';
 export type { LinearGradientProps } from './linear-gradient/linear-gradient.js';
 
+export { LiquidGradient } from './liquid-gradient/liquid-gradient.js';
+export type { LiquidGradientProps } from './liquid-gradient/liquid-gradient.js';
+
 export { MeshGradient } from './mesh-gradient/mesh-gradient.js';
 export type { MeshGradientProps } from './mesh-gradient/mesh-gradient.js';