@dooph-software/fluid-gradients 1.0.0 → 3.1.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { randomBytes } from "crypto";
+import { randomBytes, randomInt } from "crypto";
 import { mkdirSync, realpathSync, writeFileSync } from "fs";
 import { dirname, extname, join } from "path";
 import { fileURLToPath } from "url";
@@ -10,8 +10,257 @@ import { parseArgs } from "util";
 // src/render.ts
 import { createCanvas, ImageData } from "@napi-rs/canvas";
 import sharp from "sharp";
+import { createNoise2D as createNoise2D2 } from "simplex-noise";
+
+// src/sweep.ts
 import { createNoise2D } from "simplex-noise";
 
+// src/random.ts
+function hashStringToInt(seed) {
+  let hash = 2166136261 >>> 0;
+  for (let i = 0; i < seed.length; i++) {
+    hash ^= seed.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function createSeededRandom(seedInt) {
+  let state = seedInt;
+  return function nextRandom() {
+    state |= 0;
+    state = state + 1831565813 | 0;
+    let mixed = Math.imul(state ^ state >>> 15, 1 | state);
+    mixed = mixed + Math.imul(mixed ^ mixed >>> 7, 61 | mixed) ^ mixed;
+    return ((mixed ^ mixed >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+// src/sweep.ts
+var tuning = {
+  workHeight: 400,
+  velocityFrequency: 0.4,
+  /** Velocity grid cells per image height. */
+  velocityResolution: 80,
+  /** Travel at sweep 1, measured at drift speed. */
+  advectDistance: 1.6,
+  advectSteps: 32,
+  /** Drift speed relative to the current's RMS speed. */
+  drift: 1,
+  /** Eddy speed cap, relative to the drift. Two fields mixed at most √2 ×
+   * this, which must stay below 1 or eddies can close. */
+  eddyCap: 0.65,
+  /** Radians the current turns between its two fields over the trace. */
+  timeSpin: 1.2,
+  defocus: 8e-3,
+  smearLength: 0.5,
+  smearSteps: 40,
+  /** Fraction of the exposure at full weight before the window tapers. */
+  smearFlat: 0.6,
+  groundSoftness: 0.35,
+  groundFieldWeight: 1,
+  groundNoiseWeight: 0.6,
+  groundBlur: 0.02,
+  groundMaxCover: 0.9,
+  groundFrequency: 0.9
+};
+var smoothStep = (edge) => edge * edge * (3 - 2 * edge);
+var clamp01 = (value) => Math.max(0, Math.min(1, value));
+var fractal = (noise, x, y) => 0.5 * noise(x, y) + 0.25 * noise(x * 2, y * 2);
+var Grid = class {
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+    this.values = new Float32Array(width * height);
+  }
+  width;
+  height;
+  values;
+  sample(x, y) {
+    const gx = Math.max(0, Math.min(this.width - 1.0001, x));
+    const gy = Math.max(0, Math.min(this.height - 1.0001, y));
+    const x0 = Math.floor(gx);
+    const y0 = Math.floor(gy);
+    const fx = gx - x0;
+    const fy = gy - y0;
+    const v = this.values;
+    const i = y0 * this.width + x0;
+    const top = v[i] + (v[i + 1] - v[i]) * fx;
+    const bottom = v[i + this.width] + (v[i + this.width + 1] - v[i + this.width]) * fx;
+    return top + (bottom - top) * fy;
+  }
+};
+function applySweep(input) {
+  const { seed, width, height, pixels, rampPositionAt, rgbStops, sampleRamp, sweep, ground } = input;
+  const t = tuning;
+  const random = createSeededRandom(hashStringToInt(`${seed}::sweep`));
+  const currentNoiseA = createNoise2D(random);
+  const currentNoiseB = createNoise2D(random);
+  const coverageNoise = createNoise2D(random);
+  const coverageWarpNoise = createNoise2D(random);
+  const driftAngle = random() * Math.PI * 2;
+  const scale = Math.min(1, t.workHeight / height);
+  const workW = Math.max(2, Math.round(width * scale));
+  const workH = Math.max(2, Math.round(height * scale));
+  const aspect = width / height;
+  const driftX = Math.cos(driftAngle) * t.drift;
+  const driftY = Math.sin(driftAngle) * t.drift;
+  const margin = 2 * t.advectDistance * sweep + 0.1;
+  const cell = 1 / t.velocityResolution;
+  const velW = Math.ceil((aspect + 2 * margin) / cell) + 2;
+  const velH = Math.ceil((1 + 2 * margin) / cell) + 2;
+  const currents = [currentNoiseA, currentNoiseB].map((noise) => {
+    const vx = new Grid(velW, velH);
+    const vy = new Grid(velW, velH);
+    const f = t.velocityFrequency;
+    const e = 2e-3;
+    let total = 0;
+    for (let gy = 0; gy < velH; gy++) {
+      for (let gx = 0; gx < velW; gx++) {
+        const u = (gx * cell - margin) * f;
+        const v = (gy * cell - margin) * f;
+        const i = gy * velW + gx;
+        vx.values[i] = (fractal(noise, u, v + e) - fractal(noise, u, v - e)) / (2 * e);
+        vy.values[i] = -(fractal(noise, u + e, v) - fractal(noise, u - e, v)) / (2 * e);
+        total += vx.values[i] ** 2 + vy.values[i] ** 2;
+      }
+    }
+    const rms = Math.sqrt(total / vx.values.length) || 1;
+    const cap = t.eddyCap * t.drift;
+    for (let i = 0; i < vx.values.length; i++) {
+      const speed = Math.hypot(vx.values[i], vy.values[i]) / rms + 1e-9;
+      const limited = cap * Math.tanh(speed / cap) / speed / rms;
+      vx.values[i] *= limited;
+      vy.values[i] *= limited;
+    }
+    return { vx, vy };
+  });
+  const velocity = (u, v, phase, out) => {
+    const gx = (u + margin) / cell;
+    const gy = (v + margin) / cell;
+    const a = Math.cos(phase);
+    const b = Math.sin(phase);
+    out[0] = a * currents[0].vx.sample(gx, gy) + b * currents[1].vx.sample(gx, gy) + driftX;
+    out[1] = a * currents[0].vy.sample(gx, gy) + b * currents[1].vy.sample(gx, gy) + driftY;
+  };
+  const flowX = new Grid(workW, workH);
+  const flowY = new Grid(workW, workH);
+  const fieldSource = new Grid(workW, workH);
+  const sourceU = new Float32Array(workW * workH);
+  const sourceV = new Float32Array(workW * workH);
+  const steps = t.advectSteps;
+  const dt = sweep * t.advectDistance / t.drift / steps;
+  const k1 = [0, 0];
+  const k2 = [0, 0];
+  for (let y = 0; y < workH; y++) {
+    for (let x = 0; x < workW; x++) {
+      let u = x / workH;
+      let v = y / workH;
+      const i = y * workW + x;
+      velocity(u, v, 0, k1);
+      flowX.values[i] = k1[0];
+      flowY.values[i] = k1[1];
+      for (let s = 0; s < steps; s++) {
+        const phase = t.timeSpin * s / steps;
+        velocity(u, v, phase, k1);
+        velocity(u - k1[0] * dt / 2, v - k1[1] * dt / 2, phase, k2);
+        u -= k2[0] * dt;
+        v -= k2[1] * dt;
+      }
+      sourceU[i] = u;
+      sourceV[i] = v;
+      fieldSource.values[i] = rampPositionAt(u, v);
+    }
+  }
+  boxBlur(fieldSource.values, workW, workH, Math.max(1, Math.round(t.defocus * sweep * workH)), 3);
+  const coverageSource = new Grid(workW, workH);
+  if (ground > 0) {
+    for (let y = 0; y < workH; y++) {
+      for (let x = 0; x < workW; x++) {
+        const i = y * workW + x;
+        const su = sourceU[i] * t.groundFrequency;
+        const sv = sourceV[i] * t.groundFrequency;
+        const warpX = fractal(coverageWarpNoise, su, sv);
+        const warpY = fractal(coverageWarpNoise, su + 5.2, sv + 1.3);
+        coverageSource.values[i] = t.groundFieldWeight * fieldSource.values[i] + t.groundNoiseWeight * fractal(coverageNoise, su + warpX, sv + warpY);
+      }
+    }
+    const sorted = Float32Array.from(coverageSource.values).sort();
+    const threshold = sorted[Math.min(sorted.length - 1, Math.floor(ground * t.groundMaxCover * sorted.length))];
+    for (let i = 0; i < coverageSource.values.length; i++) coverageSource.values[i] -= threshold;
+    boxBlur(coverageSource.values, workW, workH, Math.max(1, Math.round(t.groundBlur * workH)), 3);
+  }
+  const smearedField = new Grid(workW, workH);
+  const smearedCoverage = new Grid(workW, workH);
+  const smearSteps = t.smearSteps;
+  const step = sweep * t.smearLength * workH / 2 / Math.hypot(1, t.drift) / smearSteps;
+  const weights = new Float32Array(smearSteps + 1);
+  for (let s = 0; s <= smearSteps; s++) {
+    const along = s / (smearSteps + 1);
+    weights[s] = along <= t.smearFlat ? 1 : 0.5 + 0.5 * Math.cos(Math.PI * (along - t.smearFlat) / (1 - t.smearFlat));
+  }
+  for (let y = 0; y < workH; y++) {
+    for (let x = 0; x < workW; x++) {
+      let fieldTotal = weights[0] * fieldSource.sample(x, y);
+      let coverageTotal = ground > 0 ? weights[0] * coverageSource.sample(x, y) : 0;
+      let weightTotal = weights[0];
+      for (let direction = -1; direction <= 1; direction += 2) {
+        let px = x;
+        let py = y;
+        for (let s = 1; s <= smearSteps; s++) {
+          const mx = px + direction * flowX.sample(px, py) * step / 2;
+          const my = py + direction * flowY.sample(px, py) * step / 2;
+          px += direction * flowX.sample(mx, my) * step;
+          py += direction * flowY.sample(mx, my) * step;
+          if (px < 0 || py < 0 || px > workW - 1 || py > workH - 1) break;
+          const w = weights[s];
+          fieldTotal += w * fieldSource.sample(px, py);
+          if (ground > 0) coverageTotal += w * coverageSource.sample(px, py);
+          weightTotal += w;
+        }
+      }
+      smearedField.values[y * workW + x] = fieldTotal / weightTotal;
+      smearedCoverage.values[y * workW + x] = coverageTotal / weightTotal;
+    }
+  }
+  const groundColor = rgbStops[0];
+  for (let py = 0; py < height; py++) {
+    for (let px = 0; px < width; px++) {
+      const sx = (px + 0.5) * scale - 0.5;
+      const sy = (py + 0.5) * scale - 0.5;
+      let [r, g, b] = sampleRamp(smearedField.sample(sx, sy));
+      if (ground > 0) {
+        const m = smoothStep(clamp01(smearedCoverage.sample(sx, sy) / t.groundSoftness + 0.5));
+        r = groundColor[0] + (r - groundColor[0]) * m;
+        g = groundColor[1] + (g - groundColor[1]) * m;
+        b = groundColor[2] + (b - groundColor[2]) * m;
+      }
+      const o = (py * width + px) * 4;
+      pixels[o] = r;
+      pixels[o + 1] = g;
+      pixels[o + 2] = b;
+    }
+  }
+}
+function boxBlur(values, width, height, radius, passes) {
+  const scratch = new Float32Array(values.length);
+  for (let pass = 0; pass < passes; pass++) {
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        let total = 0;
+        for (let k = -radius; k <= radius; k++) total += values[y * width + Math.max(0, Math.min(width - 1, x + k))];
+        scratch[y * width + x] = total / (2 * radius + 1);
+      }
+    }
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        let total = 0;
+        for (let k = -radius; k <= radius; k++) total += scratch[Math.max(0, Math.min(height - 1, y + k)) * width + x];
+        values[y * width + x] = total / (2 * radius + 1);
+      }
+    }
+  }
+}
+
 // src/color.ts
 var ACHROMATIC_CHROMA = 0.01;
 var HUE_TRUST_CHROMA = 0.03;
@@ -92,26 +341,6 @@ function paletteComplementColor(accent, ramp) {
   return Math.hypot(meanA, meanB) < ACHROMATIC_CHROMA / 2 ? oppositeGray(L) : vividOpposite(meanA, meanB);
 }
 
-// src/random.ts
-function hashStringToInt(seed) {
-  let hash = 2166136261 >>> 0;
-  for (let i = 0; i < seed.length; i++) {
-    hash ^= seed.charCodeAt(i);
-    hash = Math.imul(hash, 16777619);
-  }
-  return hash >>> 0;
-}
-function createSeededRandom(seedInt) {
-  let state = seedInt;
-  return function nextRandom() {
-    state |= 0;
-    state = state + 1831565813 | 0;
-    let mixed = Math.imul(state ^ state >>> 15, 1 | state);
-    mixed = mixed + Math.imul(mixed ^ mixed >>> 7, 61 | mixed) ^ mixed;
-    return ((mixed ^ mixed >>> 14) >>> 0) / 4294967296;
-  };
-}
-
 // src/palettes.ts
 var MIN_PALETTE_COLORS = 3;
 var MAX_PALETTE_COLORS = 5;
@@ -190,13 +419,43 @@ var colorPalettes = [
   { name: "onyx-snow", colors: ["#ffffff", "#b0b0b0", "#4a4a4a", "#000000"] },
   { name: "midnight-ember", colors: ["#f0a468", "#c23f1f", "#2a1410", "#0a0a0c"] },
   { name: "slate-harbor", colors: ["#aeb7bd", "#6f7b84", "#3c454c", "#1a1f24"] },
+  { name: "ember-mono", colors: ["#ff9a6b", "#cf5604", "#632400", "#180501"] },
+  // ── Monochromatic: one hue, lightness stepping down (OKLCH-spaced) ──
+  { name: "tangerine-mono", colors: ["#ffeee4", "#feb079", "#dc7100", "#824103"] },
+  { name: "electric-blue-mono", colors: ["#ebf2fe", "#a4c6fc", "#5d91e7", "#2a5397"] },
+  { name: "magenta-mono", colors: ["#feecf5", "#edaed1", "#cd6ca6", "#823564"] },
+  { name: "emerald-mono", colors: ["#e2f8ea", "#95d5af", "#2cab70", "#03663e"] },
+  { name: "violet-mono", colors: ["#f2f0fe", "#c8b7ff", "#9e71fd", "#5f38a7"] },
+  { name: "crimson-mono", colors: ["#ffedec", "#feaaa9", "#f44f5d", "#9e122b"] },
+  { name: "aqua-mono", colors: ["#dff7f8", "#8dd2d6", "#39a4a9", "#026266"] },
+  { name: "burgundy-mono", colors: ["#fbe0e4", "#dc9ea8", "#a7415a", "#560c24"] },
+  { name: "indigo-mono", colors: ["#eaeefe", "#a7b2f7", "#5a5ce2", "#261b81"] },
+  { name: "lime-mono", colors: ["#edfcd7", "#c2e87d", "#9fc93e", "#638119"] },
+  // ── Monochromatic earth tones: same idea, chroma held up so they stay
+  // clay / ochre / moss rather than collapsing to greige ──
+  { name: "terracotta-mono", colors: ["#fdeae4", "#f6b19b", "#c5694c", "#73311b"] },
+  { name: "ochre-mono", colors: ["#f9edd5", "#dec082", "#a87f09", "#5b4404"] },
+  { name: "olive-mono", colors: ["#edf2d7", "#c2cb91", "#848e38", "#474d04"] },
+  { name: "fern-mono", colors: ["#e3f5df", "#a9d1a0", "#5f9752", "#2a5320"] },
+  { name: "verdigris-mono", colors: ["#d6f7f1", "#96d2c9", "#38988d", "#07534c"] },
+  { name: "umber-mono", colors: ["#feeada", "#e1bc9d", "#ab7a4f", "#623f1e"] },
+  { name: "adobe-mono", colors: ["#fee9e8", "#eeb3b0", "#bb6d6b", "#6c3434"] },
   // ── Neutral / mono ──
   { name: "ivory-ink", colors: ["#f7f4ef", "#d8d2c8", "#8a8378", "#20201d"] },
   { name: "paper-graphite", colors: ["#f4f4f5", "#cfcfd4", "#83838f", "#1c1c22"] },
   { name: "bone-coffee", colors: ["#f5efe6", "#d9c9b3", "#9c8468", "#3a2c1e"] },
   { name: "porcelain-greige", colors: ["#f6f3ef", "#ddd4c9", "#b0a596", "#6a5f52"] },
   { name: "battleship-steel", colors: ["#e6e9e8", "#b9c0be", "#7d8683", "#3f4745"] },
-  { name: "gunmetal-fog", colors: ["#eceef1", "#c2c7cd", "#7b838d", "#343a42"] }
+  { name: "gunmetal-fog", colors: ["#eceef1", "#c2c7cd", "#7b838d", "#343a42"] },
+  { name: "silver-steel", colors: ["#e2e5e8", "#c4c9cf", "#9aa2ac", "#646f7d"] },
+  // ── Airy: a near-white base with soft color splashes, in the style of
+  // blurred editorial gradients (light stops first, then the splash hues) ──
+  { name: "petal-bloom", colors: ["#e4eeff", "#bcd2ff", "#dfa6e9", "#fa787b", "#fba96a"] },
+  { name: "tulip-blur", colors: ["#e6f1f6", "#a8d4e8", "#f1c4d0", "#ee9a6e", "#f4b81c"] },
+  { name: "silk-rose", colors: ["#fcedf4", "#f2cfdd", "#f0c1b8", "#d68ba5", "#b07a9f"] },
+  // ── Flags: sampled from heraldic flag art ──
+  { name: "sultans-eagle", colors: ["#f2da38", "#e3c42a", "#c9a21d", "#a1353a", "#6a1c26"] },
+  { name: "zhuge-nu", colors: ["#f0f3ee", "#dfc652", "#4fa79b", "#1f8283", "#0f5252"] }
 ];
 function paletteAccent(palette) {
   const colors = palette.colors;
@@ -259,14 +518,18 @@ var lookDescriptions = {
   domainWarpStrength: "How much the color field swirls.",
   fractalOctaveCount: "More octaves add finer detail.",
   colorTransitionContrast: "Sharpness of the edges between colors.",
-  grainOpacity: "Strength of the film-grain overlay."
+  grainOpacity: "Strength of the film-grain overlay.",
+  sweep: "Drifts the color into soft, curving wisps, like dye in water or folded silk, 0\u20131. 0 is the plain fluid.",
+  ground: "Roughly the share of the image, 0\u20131, left as a pale ground in the palette's lightest color."
 };
 var defaultLook = {
   baseNoiseFrequency: 0.3,
   domainWarpStrength: 1,
   fractalOctaveCount: 2,
   colorTransitionContrast: 1.75,
-  grainOpacity: 0.09
+  grainOpacity: 0.09,
+  sweep: 0,
+  ground: 0
 };
 var DEFAULT_WIDTH = 1200;
 var DEFAULT_HEIGHT = 1500;
@@ -288,15 +551,20 @@ function sampleColorRamp(rgbStops, position) {
     lowB + (highB - lowB) * blend
   ];
 }
-var smoothStep = (edge) => edge * edge * (3 - 2 * edge);
+var smoothStep2 = (edge) => edge * edge * (3 - 2 * edge);
 async function renderCanvas(options) {
   const { seed, palette, width = DEFAULT_WIDTH, height = DEFAULT_HEIGHT } = options;
   const look = { ...defaultLook, ...options.look };
+  for (const knob of ["sweep", "ground"]) {
+    if (!(look[knob] >= 0 && look[knob] <= 1)) {
+      throw new RangeError(`look.${knob} must be between 0 and 1. Got: ${look[knob]}`);
+    }
+  }
   const random = createSeededRandom(hashStringToInt(seed));
   const rgbStops = palette.colors.map(hexToRgb2);
-  const horizontalWarpNoise = createNoise2D(random);
-  const verticalWarpNoise = createNoise2D(random);
-  const colorFieldNoise = createNoise2D(random);
+  const horizontalWarpNoise = createNoise2D2(random);
+  const verticalWarpNoise = createNoise2D2(random);
+  const colorFieldNoise = createNoise2D2(random);
   const sampleFractalNoise = (noise, sampleX, sampleY) => {
     let total = 0;
     let amplitude = 0.5;
@@ -313,21 +581,24 @@ async function renderCanvas(options) {
   const image = context.createImageData(width, height);
   const pixels = image.data;
   const aspectRatio = width / height;
+  const rampPositionAt = (sampleX, sampleY) => {
+    const horizontalWarpOffset = sampleFractalNoise(horizontalWarpNoise, sampleX, sampleY);
+    const verticalWarpOffset = sampleFractalNoise(verticalWarpNoise, sampleX + 5.2, sampleY + 1.3);
+    const rawFieldValue = sampleFractalNoise(
+      colorFieldNoise,
+      sampleX + look.domainWarpStrength * horizontalWarpOffset,
+      sampleY + look.domainWarpStrength * verticalWarpOffset
+    );
+    const normalizedValue = (rawFieldValue + 1) / 2;
+    return smoothStep2(
+      Math.max(0, Math.min(1, (normalizedValue - 0.5) * look.colorTransitionContrast + 0.5))
+    );
+  };
   for (let pixelY = 0; pixelY < height; pixelY++) {
     for (let pixelX = 0; pixelX < width; pixelX++) {
       const sampleX = pixelX / width * look.baseNoiseFrequency * aspectRatio;
       const sampleY = pixelY / height * look.baseNoiseFrequency;
-      const horizontalWarpOffset = sampleFractalNoise(horizontalWarpNoise, sampleX, sampleY);
-      const verticalWarpOffset = sampleFractalNoise(verticalWarpNoise, sampleX + 5.2, sampleY + 1.3);
-      const rawFieldValue = sampleFractalNoise(
-        colorFieldNoise,
-        sampleX + look.domainWarpStrength * horizontalWarpOffset,
-        sampleY + look.domainWarpStrength * verticalWarpOffset
-      );
-      const normalizedValue = (rawFieldValue + 1) / 2;
-      const contrastedValue = smoothStep(
-        Math.max(0, Math.min(1, (normalizedValue - 0.5) * look.colorTransitionContrast + 0.5))
-      );
+      const contrastedValue = rampPositionAt(sampleX, sampleY);
       const [red, green, blue] = sampleColorRamp(rgbStops, contrastedValue);
       const pixelIndex = (pixelY * width + pixelX) * 4;
       pixels[pixelIndex] = red;
@@ -336,6 +607,20 @@ async function renderCanvas(options) {
       pixels[pixelIndex + 3] = 255;
     }
   }
+  if (look.sweep > 0 || look.ground > 0) {
+    applySweep({
+      seed,
+      width,
+      height,
+      pixels,
+      // Height units: the fluid's x runs 0…aspect, y runs 0…1.
+      rampPositionAt: (u, v) => rampPositionAt(u * look.baseNoiseFrequency, v * look.baseNoiseFrequency),
+      rgbStops,
+      sampleRamp: (position) => sampleColorRamp(rgbStops, position),
+      sweep: look.sweep,
+      ground: look.ground
+    });
+  }
   context.putImageData(image, 0, 0);
   const grainPixels = new Uint8ClampedArray(width * height * 4);
   for (let i = 0; i < width * height; i++) {
@@ -390,6 +675,13 @@ var finiteNumber = (flag) => (raw) => {
   if (!Number.isFinite(value)) throw new Error(`--${flag} must be a number. Got: ${raw}`);
   return value;
 };
+var unitInterval = (flag) => (raw) => {
+  const value = Number(raw);
+  if (raw.trim() === "" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new Error(`--${flag} must be a number from 0 to 1. Got: ${raw}`);
+  }
+  return value;
+};
 var optionFlags = {
   seed: {
     flag: "seed",
@@ -452,6 +744,18 @@ var lookFlags = {
     placeholder: "<0-1>",
     describe: `${lookDescriptions.grainOpacity} Default ${defaultLook.grainOpacity}.`,
     parse: finiteNumber("grain-opacity")
+  },
+  sweep: {
+    flag: "sweep",
+    placeholder: "<0-1>",
+    describe: `${lookDescriptions.sweep} Default ${defaultLook.sweep}.`,
+    parse: unitInterval("sweep")
+  },
+  ground: {
+    flag: "ground",
+    placeholder: "<0-1>",
+    describe: `${lookDescriptions.ground} Default ${defaultLook.ground}.`,
+    parse: unitInterval("ground")
   }
 };
 var cliOnlyFlags = [
@@ -460,6 +764,21 @@ var cliOnlyFlags = [
     placeholder: "<path>",
     describe: "Output file, .webp or .png. Default: output/<palette>-<seed>.webp"
   },
+  {
+    flag: "random-palette",
+    placeholder: "",
+    describe: "Pick the palette at random instead of deriving it from --seed. The name is printed."
+  },
+  {
+    flag: "chaos",
+    placeholder: "",
+    describe: "Ignore the palettes: use 3\u20135 random colors (the same --seed gives the same colors)."
+  },
+  {
+    flag: "colors",
+    placeholder: "<hex,...>",
+    describe: 'Use your own 3\u20135 colors, light \u2192 dark, comma-separated: "#fdf6ee,#f2c4ce,#3f6fd8". The # is optional.'
+  },
   { flag: "json", placeholder: "", describe: "Print result metadata as JSON." },
   { flag: "list-palettes", placeholder: "", describe: "Print built-in palette names and exit." },
   { flag: "help", placeholder: "", describe: "Show this help (-h)." }
@@ -532,11 +851,33 @@ ${cliOnlyFlags.map(line).join("\n")}
 })();
 var parseOptions = {
   ...Object.fromEntries(allFlags.map((f) => [f.flag, { type: "string" }])),
-  out: { type: "string" },
-  json: { type: "boolean" },
-  "list-palettes": { type: "boolean" },
+  // A CLI-only flag with a placeholder takes a value; one without is a switch.
+  ...Object.fromEntries(
+    cliOnlyFlags.map((f) => [f.flag, { type: f.placeholder ? "string" : "boolean" }])
+  ),
   help: { type: "boolean", short: "h" }
 };
+function chaosPalette(seed) {
+  const random = createSeededRandom(hashStringToInt(`${seed}::chaos`));
+  const count = 3 + Math.floor(random() * 3);
+  const colors = Array.from({ length: count }, () => {
+    const channels = [random(), random(), random()].map(
+      (c) => Math.floor(c * 256).toString(16).padStart(2, "0")
+    );
+    return `#${channels.join("")}`;
+  });
+  return { name: "chaos", colors };
+}
+function customPalette(raw) {
+  const colors = raw.split(",").map((c) => c.trim()).filter((c) => c.length > 0).map((c) => (c.startsWith("#") ? c : `#${c}`).toLowerCase());
+  const palette = { name: "custom", colors };
+  try {
+    validatePalette(palette);
+  } catch (err) {
+    throw new Error(err.message.replace('Palette "custom"', "--colors"));
+  }
+  return palette;
+}
 async function runCli(argv) {
   const values = parseArgs({ args: argv, options: parseOptions }).values;
   const raw = (flag) => values[flag];
@@ -562,7 +903,14 @@ async function runCli(argv) {
   }
   const seed = read("seed") ?? randomBytes(4).toString("hex");
   const paletteName = read("palette");
-  const palette = paletteName === void 0 ? pickPalette(seed) : findPalette(paletteName);
+  const customColors = raw("colors");
+  const sources = ["palette", "random-palette", "chaos", "colors"].filter(
+    (flag) => values[flag] !== void 0 && values[flag] !== false
+  );
+  if (sources.length > 1) {
+    throw new Error(`${sources.map((f) => `--${f}`).join(" and ")} cannot be combined.`);
+  }
+  const palette = customColors !== void 0 ? customPalette(customColors) : values.chaos ? chaosPalette(seed) : values["random-palette"] ? colorPalettes[randomInt(colorPalettes.length)] : paletteName === void 0 ? pickPalette(seed) : findPalette(paletteName);
   const out = raw("out") ?? join("output", `${palette.name}-${seed}.webp`);
   const extension = extname(out).toLowerCase();
   if (extension !== ".webp" && extension !== ".png") {
@@ -587,6 +935,9 @@ async function runCli(argv) {
   } else {
     console.log(`\u2713 ${out} (${(result.buffer.length / 1024).toFixed(2)} KB)`);
     console.log(`  seed: ${result.seed}`);
+    if (values.chaos || customColors !== void 0) {
+      console.log(`  colors: ${result.palette.colors.join(" ")}`);
+    }
     console.log(`  palette: ${result.palette.name} (accent: ${result.accent}, complement: ${result.complement})`);
   }
 }