@dooph-software/fluid-gradients 1.0.0

package/dist/palettes.d.ts

@@ -0,0 +1,261 @@
+/**
+ * The complement of a `#rrggbb` color, built to stand out: the opposite OKLCH
+ * hue at its most saturated readable lightness. Grays get the opposite-lightness gray.
+ */
+declare function complementColor(hex: string): string;
+
+declare const MIN_PALETTE_COLORS = 3;
+declare const MAX_PALETTE_COLORS = 5;
+/** `#rrggbb`. The type only checks the `#`; the 6 hex digits are checked at runtime. */
+type HexColor = `#${string}`;
+/** A color ramp of 3–5 stops, light → dark. */
+type PaletteColors = readonly [HexColor, HexColor, HexColor] | readonly [HexColor, HexColor, HexColor, HexColor] | readonly [HexColor, HexColor, HexColor, HexColor, HexColor];
+type Palette = {
+    /** Unique within a palette set. Seed-based picks are keyed on it, so renaming reshuffles. */
+    name: string;
+    colors: PaletteColors;
+};
+declare const colorPalettes: readonly [{
+    readonly name: "amber-latte";
+    readonly colors: readonly ["#faf4ea", "#f2d29b", "#e0a45c", "#b9722f"];
+}, {
+    readonly name: "terracotta-sand";
+    readonly colors: readonly ["#f6ede1", "#e8c9a0", "#cf8f63", "#9c4e33"];
+}, {
+    readonly name: "peach-blush";
+    readonly colors: readonly ["#fdf1ec", "#f8cbb6", "#ef9a8a", "#d76e73"];
+}, {
+    readonly name: "coral-cream";
+    readonly colors: readonly ["#fbe9df", "#f5b79a", "#e8735a", "#c33f36"];
+}, {
+    readonly name: "honey-espresso";
+    readonly colors: readonly ["#f7ecd9", "#e5b877", "#b9793f", "#5f3418"];
+}, {
+    readonly name: "apricot-plum";
+    readonly colors: readonly ["#fdf0e6", "#f6c79a", "#e58b6f", "#7d4a6b"];
+}, {
+    readonly name: "golden-hour";
+    readonly colors: readonly ["#fdf3e1", "#f7cf8a", "#e89a5a", "#9a4a3a"];
+}, {
+    readonly name: "vermilion-blush";
+    readonly colors: readonly ["#fbe8e2", "#f7c6a8", "#e4562f", "#a82a1c"];
+}, {
+    readonly name: "ivory-gilt";
+    readonly colors: readonly ["#fffdf7", "#f7ecd0", "#e0c47e", "#b08c3a"];
+}, {
+    readonly name: "rose-gold";
+    readonly colors: readonly ["#fceee8", "#f2cdbd", "#dba18c", "#b3705c"];
+}, {
+    readonly name: "peony-glow";
+    readonly colors: readonly ["#fdeef3", "#f9b3c8", "#f78a5c", "#f2a93f"];
+}, {
+    readonly name: "lavender-rose";
+    readonly colors: readonly ["#f4eefb", "#d9c2ef", "#c98fb8", "#8a5fd0"];
+}, {
+    readonly name: "violet-mist";
+    readonly colors: readonly ["#f1eefb", "#c9b8ef", "#8f7fe0", "#4a3d9c"];
+}, {
+    readonly name: "mauve-plum";
+    readonly colors: readonly ["#f6f0f2", "#d8b8c6", "#a5738c", "#5f3a55"];
+}, {
+    readonly name: "periwinkle-blush";
+    readonly colors: readonly ["#f0f0fb", "#c3c6f0", "#cf9fc6", "#6a5fd0"];
+}, {
+    readonly name: "orchid-frost";
+    readonly colors: readonly ["#f6eff6", "#e0c2e0", "#b98fc4", "#7a5aa6", "#3f2f5c"];
+}, {
+    readonly name: "quartz-rose";
+    readonly colors: readonly ["#faf1f1", "#ecc9cc", "#c99aa3", "#8a5f6a"];
+}, {
+    readonly name: "wisteria-sky";
+    readonly colors: readonly ["#f2f0fb", "#cfc6ef", "#9fb2e6", "#4f6aa6"];
+}, {
+    readonly name: "zephyr-dawn";
+    readonly colors: readonly ["#fdf3f5", "#f2d6e2", "#c6d6f2", "#7f9fd8"];
+}, {
+    readonly name: "candy-sky";
+    readonly colors: readonly ["#f6e8ff", "#f7a3e8", "#9aa8f5", "#3fa0f5"];
+}, {
+    readonly name: "sky-slate";
+    readonly colors: readonly ["#eef4fb", "#bcd2ef", "#6f8fc4", "#2f3f66"];
+}, {
+    readonly name: "teal-fog";
+    readonly colors: readonly ["#eef7f6", "#b6dcd8", "#5fa39c", "#234a49"];
+}, {
+    readonly name: "arctic-ink";
+    readonly colors: readonly ["#f2f6f8", "#cddbe2", "#7f96a3", "#1c2630"];
+}, {
+    readonly name: "cloud-navy";
+    readonly colors: readonly ["#f0f3f7", "#c6d1de", "#7488a3", "#1f2c44"];
+}, {
+    readonly name: "denim-clay";
+    readonly colors: readonly ["#eef2f6", "#aebfd0", "#5f7794", "#b06a4e"];
+}, {
+    readonly name: "cobalt-ice";
+    readonly colors: readonly ["#e8eeff", "#b9cdfb", "#2f4fd8", "#1836b8"];
+}, {
+    readonly name: "sage-mist";
+    readonly colors: readonly ["#f2f5ee", "#cdd8bd", "#8fa579", "#4a5c3a"];
+}, {
+    readonly name: "mint-sea";
+    readonly colors: readonly ["#eef8f4", "#b6e2d2", "#5fb39c", "#1f5c4d"];
+}, {
+    readonly name: "olive-cream";
+    readonly colors: readonly ["#f6f3e6", "#dbd09b", "#a39a5c", "#5f5a2f"];
+}, {
+    readonly name: "eucalyptus-fog";
+    readonly colors: readonly ["#eff4f1", "#cbdcd2", "#94b3a6", "#4f6b60"];
+}, {
+    readonly name: "kelp-forest";
+    readonly colors: readonly ["#eef3ea", "#a9c49a", "#4f7a5a", "#1f3a2f"];
+}, {
+    readonly name: "yuzu-mint";
+    readonly colors: readonly ["#fbfbe6", "#eef29a", "#b3d98a", "#3f8f7a"];
+}, {
+    readonly name: "lime-lagoon";
+    readonly colors: readonly ["#f8ffe8", "#c8f56a", "#6fe3d8", "#2fc6d8"];
+}, {
+    readonly name: "bliss-meadow";
+    readonly colors: readonly ["#f4fbff", "#8ed0f2", "#6cb03a", "#2d6b22"];
+}, {
+    readonly name: "periwinkle-gold";
+    readonly colors: readonly ["#dfe6ff", "#a9b6f0", "#5b6bd6", "#e6c25a"];
+}, {
+    readonly name: "lilac-lemon";
+    readonly colors: readonly ["#f3eefb", "#d3c2ef", "#9f8fd0", "#e6d25a"];
+}, {
+    readonly name: "blush-teal";
+    readonly colors: readonly ["#fbeee9", "#f2c2b0", "#d78a8f", "#3f9c94"];
+}, {
+    readonly name: "sage-coral";
+    readonly colors: readonly ["#f2f5ee", "#cdd8bd", "#8fa579", "#e0755a"];
+}, {
+    readonly name: "slate-amber";
+    readonly colors: readonly ["#eef2f6", "#bcc9d8", "#5f7794", "#e0a24e"];
+}, {
+    readonly name: "ultramarine-sand";
+    readonly colors: readonly ["#dfe8ff", "#e6c27a", "#4757dd", "#232a9c"];
+}, {
+    readonly name: "amber-tide";
+    readonly colors: readonly ["#eef4f8", "#a9c8ef", "#f2b96b", "#df8a33"];
+}, {
+    readonly name: "sunset-rose";
+    readonly colors: readonly ["#fce9d6", "#f6a95c", "#e8617a", "#8a3d7a"];
+}, {
+    readonly name: "berry-bloom";
+    readonly colors: readonly ["#fbe9f2", "#e88fb8", "#c94f8f", "#7a2f6a"];
+}, {
+    readonly name: "jewel-peacock";
+    readonly colors: readonly ["#e6f5f0", "#4fb3a6", "#1f7a99", "#243f8a"];
+}, {
+    readonly name: "iris-meadow";
+    readonly colors: readonly ["#eaf5ec", "#7cc48f", "#3f8fb3", "#5f4fb0"];
+}, {
+    readonly name: "autumn-spice";
+    readonly colors: readonly ["#f7ecd6", "#dba24f", "#b5522f", "#6e2f4a"];
+}, {
+    readonly name: "ultraviolet-sea";
+    readonly colors: readonly ["#e9f0fb", "#6f9fe0", "#4a5fc4", "#6a3da6"];
+}, {
+    readonly name: "purple-rain";
+    readonly colors: readonly ["#f1ebf7", "#b69ad6", "#6f3fa8", "#2a1740"];
+}, {
+    readonly name: "nectarine-fizz";
+    readonly colors: readonly ["#fff1e6", "#ffc59a", "#ff8a5c", "#d9485f"];
+}, {
+    readonly name: "raspberry-cream";
+    readonly colors: readonly ["#fdeef1", "#f4a9bd", "#d9537a", "#8a1f45"];
+}, {
+    readonly name: "pastel-confetti";
+    readonly colors: readonly ["#ffffff", "#f9f3cf", "#cbbcf2", "#e8798f"];
+}, {
+    readonly name: "burgundy-velvet";
+    readonly colors: readonly ["#f2dfe0", "#c98a91", "#8a2740", "#4a0f22"];
+}, {
+    readonly name: "indigo-beam";
+    readonly colors: readonly ["#ffffff", "#a9b6f7", "#4a3fe0", "#2a1fb0"];
+}, {
+    readonly name: "crimson-ice";
+    readonly colors: readonly ["#f2f7fc", "#f8d7e0", "#e0517f", "#a81050"];
+}, {
+    readonly name: "fog-plum";
+    readonly colors: readonly ["#f2f0f3", "#cfc6d2", "#9a8a9c", "#5f4a5c"];
+}, {
+    readonly name: "sand-sky";
+    readonly colors: readonly ["#f4efe4", "#e0d3b8", "#a9bcc4", "#5f7f8c"];
+}, {
+    readonly name: "xanadu-sage";
+    readonly colors: readonly ["#f1f4f1", "#c8d3c8", "#738678", "#36443a"];
+}, {
+    readonly name: "walnut-grain";
+    readonly colors: readonly ["#e8d5b7", "#c49a6c", "#8a5a34", "#4a2c17"];
+}, {
+    readonly name: "onyx-gold";
+    readonly colors: readonly ["#e8c877", "#b8862f", "#3a2f14", "#0b0b0d"];
+}, {
+    readonly name: "onyx-silver";
+    readonly colors: readonly ["#d7dade", "#8b9199", "#3a3f45", "#0c0d0f"];
+}, {
+    readonly name: "graphite-royal";
+    readonly colors: readonly ["#9fb0e8", "#3f56c4", "#2a2e38", "#101218"];
+}, {
+    readonly name: "onyx-ultraviolet";
+    readonly colors: readonly ["#c9a6ff", "#7b3ff2", "#2a1450", "#08070d"];
+}, {
+    readonly name: "onyx-snow";
+    readonly colors: readonly ["#ffffff", "#b0b0b0", "#4a4a4a", "#000000"];
+}, {
+    readonly name: "midnight-ember";
+    readonly colors: readonly ["#f0a468", "#c23f1f", "#2a1410", "#0a0a0c"];
+}, {
+    readonly name: "slate-harbor";
+    readonly colors: readonly ["#aeb7bd", "#6f7b84", "#3c454c", "#1a1f24"];
+}, {
+    readonly name: "ivory-ink";
+    readonly colors: readonly ["#f7f4ef", "#d8d2c8", "#8a8378", "#20201d"];
+}, {
+    readonly name: "paper-graphite";
+    readonly colors: readonly ["#f4f4f5", "#cfcfd4", "#83838f", "#1c1c22"];
+}, {
+    readonly name: "bone-coffee";
+    readonly colors: readonly ["#f5efe6", "#d9c9b3", "#9c8468", "#3a2c1e"];
+}, {
+    readonly name: "porcelain-greige";
+    readonly colors: readonly ["#f6f3ef", "#ddd4c9", "#b0a596", "#6a5f52"];
+}, {
+    readonly name: "battleship-steel";
+    readonly colors: readonly ["#e6e9e8", "#b9c0be", "#7d8683", "#3f4745"];
+}, {
+    readonly name: "gunmetal-fog";
+    readonly colors: readonly ["#eceef1", "#c2c7cd", "#7b838d", "#343a42"];
+}];
+/** Union of every built-in palette name, e.g. `"mint-sea"`. */
+type PaletteName = (typeof colorPalettes)[number]['name'];
+/** Primary accent for UI chips: the palette ramp's mid-tone. */
+declare function paletteAccent(palette: Palette): string;
+/**
+ * A color built to stand out on the palette's images: the hue opposite the
+ * accent (or the whole ramp, when the accent is near-gray) at its most saturated
+ * readable lightness. For chips, geometry and highlights.
+ */
+declare function paletteComplement(palette: Palette): string;
+/**
+ * Runtime check for palettes that didn't come through the type system
+ * (JSON, CLI input, `as` casts). Throws with the offending palette's name.
+ */
+declare function validatePalette(palette: Palette): void;
+/** Validates every palette and that names are unique. */
+declare function validatePalettes(palettes: readonly Palette[]): void;
+/** Look up a palette by name. Throws if not found. */
+declare function findPalette(name: PaletteName | (string & {}), palettes?: readonly Palette[]): Palette;
+/**
+ * Deterministically pick a palette from a seed.
+ *
+ * Uses rendezvous (highest-random-weight) hashing: every palette gets a
+ * pseudo-random score from `seed + name`, and the highest score wins. The list's
+ * order doesn't matter, adding a palette only moves the seeds the new palette
+ * wins (~1 in N), and removing one only moves the seeds that had picked it.
+ */
+declare function pickPalette(seed: string, palettes?: readonly Palette[]): Palette;
+
+export { type HexColor, MAX_PALETTE_COLORS, MIN_PALETTE_COLORS, type Palette, type PaletteColors, type PaletteName, colorPalettes, complementColor, findPalette, paletteAccent, paletteComplement, pickPalette, validatePalette, validatePalettes };

package/dist/palettes.js

@@ -0,0 +1,25 @@
+import {
+  MAX_PALETTE_COLORS,
+  MIN_PALETTE_COLORS,
+  colorPalettes,
+  complementColor,
+  findPalette,
+  paletteAccent,
+  paletteComplement,
+  pickPalette,
+  validatePalette,
+  validatePalettes
+} from "./chunk-KYCZHKFE.js";
+export {
+  MAX_PALETTE_COLORS,
+  MIN_PALETTE_COLORS,
+  colorPalettes,
+  complementColor,
+  findPalette,
+  paletteAccent,
+  paletteComplement,
+  pickPalette,
+  validatePalette,
+  validatePalettes
+};
+//# sourceMappingURL=palettes.js.map

package/dist/palettes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@dooph-software/fluid-gradients",
+  "version": "1.0.0",
+  "description": "Deterministic, seeded fluid-gradient images with a curated set of color palettes.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dooph-software/fluid-gradients.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "bin": {
+    "fluid-gradient": "./dist/cli.js",
+    "fluid-gradients-init-skills": "./bin/init-skills.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./palettes": {
+      "types": "./dist/palettes.d.ts",
+      "import": "./dist/palettes.js",
+      "require": "./dist/palettes.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "skills",
+    "bin"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "gradient": "npm run build && node dist/cli.js",
+    "lint": "tsc --noEmit",
+    "test": "npm run build && node scripts/sync-docs.mjs --check && node scripts/check-readme-types.mjs && node --test test/*.test.mjs",
+    "examples": "npm run build && node scripts/generate-examples.mjs",
+    "docs": "npm run build && node scripts/sync-docs.mjs",
+    "docs:check": "npm run build && node scripts/sync-docs.mjs --check && node scripts/check-readme-types.mjs",
+    "version": "npm run build && node scripts/sync-docs.mjs && node scripts/check-readme-types.mjs && git add README.md package.json",
+    "prep-release:patch": "npm version patch && npm run build && git push --follow-tags",
+    "prep-release:minor": "npm version minor && npm run build && git push --follow-tags",
+    "prep-release:major": "npm version major && npm run build && git push --follow-tags",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^1.0.5",
+    "sharp": "^0.35.3",
+    "simplex-noise": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.0",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3"
+  }
+}

package/skills/using-fluid-gradients/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: using-fluid-gradients
+description: Use when generating, storing, serving, or displaying gradient images or palette colors in a project that depends on @dooph-software/fluid-gradients — cover art, hero backgrounds, avatars, placeholders, OG images, or accent chips that should match a gradient.
+---
+
+# Using @dooph-software/fluid-gradients
+
+An image is a pure function of **seed + palette + aspect ratio + look**. Store those, not just the seed, and the image is reproducible forever.
+
+## What to persist per image
+
+| Store | Why |
+| --- | --- |
+| `seed` | Drives the composition. |
+| `palette.name` (from the result) | Omitting `palette` picks one from the seed, but that pick shifts for ~1/N seeds whenever a package upgrade adds palettes. Store the resolved name and pass it back. |
+| `width` × `height` | The field is scaled to the image's height and anchored at its left edge. Same aspect ratio → same composition at any resolution. Wider or narrower → the right side extends or trims, so a square render is exactly the left square of a wide one (only the grain differs — it's seeded but drawn per pixel, so it depends on size). Taller or shorter relative to width → rescaled, a different-looking image. |
+| `accent`, `complement` (optional) | Mid-tone hex, and a vivid opposite-hue color built to stand out on the image, for chips and geometry. Both are derivable later from the palette name. |
+
+If "must never change" is a hard requirement, also store the rendered bytes. The renderer is frozen by design, but an encoder (sharp/libwebp) upgrade can still shift WebP bytes; stored bytes can't drift at all.
+
+## Core usage
+
+```ts
+// server-only module — rendering needs Node (native canvas + sharp)
+import { generateMeshGradient } from '@dooph-software/fluid-gradients';
+
+const { buffer, palette, accent } = await generateMeshGradient({ seed: post.slug, width: 1200, height: 630 });
+// persist: seed, palette.name, 1200×630, accent — and buffer, if immutability is required
+```
+
+```ts
+// client / edge-safe — zero dependencies, no rendering
+import { findPalette, paletteAccent, paletteComplement } from '@dooph-software/fluid-gradients/palettes';
+const palette = findPalette(post.gradientPalette);
+const chip = paletteAccent(palette);
+const contrastChip = paletteComplement(palette); // opposite hue, vivid — stands out on the image
+```
+
+## Quick reference
+
+- **Custom palettes or a project-wide default size:** `createMeshGradients({ palettes, width, height })` in one module, exported and reused.
+- **Browse palettes:** `npx fluid-gradient --list-palettes`; one-off images: `npx fluid-gradient --seed x --palette y`.
+- **Draw on top before encoding:** `renderMeshGradient` returns the canvas.
+
+## Common mistakes
+
+- **Importing the main entry in client or edge code.** It pulls in native binaries; use `/palettes` for colors.
+- **Re-deriving the palette from the seed on every read.** Works until an upgrade adds palettes; then some existing images change color.
+- **Assuming a new crop needs new art.** For a narrower variant (e.g. a square from a 1200×630 cover), render the same seed + palette at the new size: it matches the cover's left edge. Only a relatively taller variant changes the composition.
+- **Assuming text is readable on the image.** Ramps run light to dark, so no single text color is safe everywhere — put text on a scrim or a solid surface.