Skip to content
Back to search

fluid

Dependency-free WebGL studio for generative backgrounds and live embeds.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/enonforetsam--fluid/badge.svg)](/listings/enonforetsam--fluid)

HTML

<a href="/listings/enonforetsam--fluid"><img src="/api/listings/enonforetsam--fluid/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/enonforetsam/fluid
cd fluid
open index.html

For the Worker routes, security headers, JSON API, and MCP endpoint:

npm run dev            # http://localhost:8787

Use the script rather than a bare `npx wrangler dev`. The assets directory is the repo root, so wrangler's own `.wrangler/state` writes land inside the tree it is watching — it sees them, reloads, writes again, and reloads about once every four seconds forever, which makes requests hang mid-reload. The script keeps that state outside the repo with `--persist-to`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 219 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="assets/og.png" alt="Fluid generative art preview" width="600">
  3. # Fluid
  4. Dependency-free WebGL studio for generating backgrounds, wallpapers, Open Graph
  5. images, and live embeddable canvases.
  6. One HTML file. No build step. No backend state. No runtime dependencies.
  7. [![License: MIT](https://img.shields.io/badge/license-MIT-3a1f7a.svg)](LICENSE)
  8. &nbsp;[![Live demo](https://img.shields.io/badge/demo-fluid.krackeddevs.com-c84fe0.svg)](https://fluid.krackeddevs.com)
  9. &nbsp;[![No build step](https://img.shields.io/badge/build-none-2aa37a.svg)](#quick-start)
  10. &nbsp;[![npm: fluid-bg](https://img.shields.io/npm/v/fluid-bg?label=fluid-bg)](https://www.npmjs.com/package/fluid-bg)
  11. &nbsp;[![npm: fluid-core](https://img.shields.io/npm/v/fluid-core?label=fluid-core)](https://www.npmjs.com/package/fluid-core)
  12. [Studio](https://fluid.krackeddevs.com) ·
  13. [Gallery](https://fluid.krackeddevs.com/gallery) ·
  14. [Manual](https://fluid.krackeddevs.com/manual) ·
  15. [Dev/API](https://fluid.krackeddevs.com/dev)
  16. </div>
  17. ## Features
  18. - WebGL1 fragment-shader renderer with 24 field engines, including a quasicrystal, paper marbling, string-art caustics, whirling pursuit polygons, Chladni plate figures, Cassini ovals, topographic contours, and a von Karman vortex street.
  19. - Kaleidoscope symmetry modifier: fold any field into an N-fold radial mandala.
  20. - Layers: stack up to three engines, each blending onto everything under it with multiply / screen / add / difference / overlay.
  21. - Math lenses: bend the plane through 12 conformal maps — z², 1/z, Möbius, Droste, hyperbolic, Julia, z³, e^z, sin z, Joukowski, Newton basins, and the SL(2,ℤ) modular fold — plus Ground, which is a camera rather than a map: it tips the plane away so any engine recedes to a horizon.
  22. - Material finishes: glass, metal, sand, liquid, and molten relighting, plus paint — impasto oil, dabs laid along the field's contours with bristle ridges, lit as thick paint on a toned canvas.
  23. - Square, hex, ASCII, halftone, ordered-dither, and glitch surface modes.
  24. - Preset palettes plus shareable custom four-stop gradients, with a draggable colour editor: saturation/brightness pad, hue strip, HSB and RGB sliders, hex, and harmony schemes that rebuild the whole ramp from one hue.
  25. - Optional image melt: uploaded image luminance drives the field.
  26. - Text in living colour: fill a word or brand name with the field, with a 9-font picker and a background-colour choice; persists locally and travels in share links.
  27. - Exact-size export as PNG, JPG, or WebP.
  28. - Self-contained HTML export: copy the piece as a complete, dependency-free file with the shaders inlined — no iframe, no server.
  29. - Clip recording through `MediaRecorder`.
  30. - Undo across the session, with a Recent shelf of every state you passed through as thumbnails.
  31. - Explore: a fresh shelf of generated pieces on every open, rendered on the spot — plus a seed of the day, one piece per UTC day, the same for everyone.
  32. - URL hash format that round-trips every piece without server storage.
  33. - Cloudflare Worker API and Streamable HTTP MCP endpoint.
  34. ## Examples
  35. <p align="center">
  36. <a href="https://fluid.krackeddevs.com/#p=0.5,1.5,5.5,0.03,1,10,0,0,18,0,0,1.7778,0,0,1" title="Aurora Flow"><img src="assets/gallery/x-aurora-flow.jpg" width="140" alt="Aurora Flow"></a>
  37. <a href="https://fluid.krackeddevs.com/#p=0.5,1.4,6,0.03,1,10,0,6,52,0,0,1.7778,0,0,5" title="Pulse"><img src="assets/gallery/x-pulse.jpg" width="140" alt="Pulse"></a>
  38. <a href="https://fluid.krackeddevs.com/#p=0.4,1.5,5,0.03,1,10,0,1,33,0,0,1.7778,0,0,6" title="Bloom"><img src="assets/gallery/x-bloom.jpg" width="140" alt="Bloom"></a>
  39. <a href="https://fluid.krackeddevs.com/#p=0.4,1.9,8,0.03,1,10,0,4,60,0,0,1.7778,0,0,2" title="Magma Cells"><img src="assets/gallery/x-magma-cells.jpg" width="140" alt="Magma Cells"></a>
  40. <a href="https://fluid.krackeddevs.com/#p=0.4,1.6,4.5,0.03,1,10,0,0,28,0,0,1.7778,0,0,3" title="Ribbon"><img src="assets/gallery/x-ribbon.jpg" width="140" alt="Ribbon"></a>
  41. <a href="https://fluid.krackeddevs.com/#p=0.4,1.8,3.5,0.03,1,10,0,4,44,0,0,1.7778,0,0,4" title="Wiring"><img src="assets/gallery/x-wiring.jpg" width="140" alt="Wiring"></a>
  42. </p>
  43. Each thumbnail opens the live piece in the studio.
  44. ## Quick Start
  45. ```sh
  46. git clone https://github.com/enonforetsam/fluid
  47. cd fluid
  48. open index.html
  49. ```
  50. For the Worker routes, security headers, JSON API, and MCP endpoint:
  51. ```sh
  52. npm run dev # http://localhost:8787
  53. ```
  54. Use the script rather than a bare `npx wrangler dev`. The assets directory is the repo root,
  55. so wrangler's own `.wrangler/state` writes land inside the tree it is watching — it sees them,
  56. reloads, writes again, and reloads about once every four seconds forever, which makes requests
  57. hang mid-reload. The script keeps that state outside the repo with `--persist-to`.
  58. ## Embed
  59. Two npm packages ship from this repo. [`fluid-bg`](https://www.npmjs.com/package/fluid-bg)
  60. is the drop-in background — it renders natively on a canvas in your page (~15 KB gz, no iframe):
  61. ```html
  62. <script src="https://cdn.jsdelivr.net/npm/fluid-bg@0.3"></script>
  63. <fluid-bg fixed hash="#p=0.5,1.5,5.5,0.03,1,10,0,0,18,0,0,1.7778"></fluid-bg>
  64. ```
  65. React: `npm i fluid-bg`, then `import FluidBg from 'fluid-bg/react'`. Keep the page
  66. background transparent when using `fixed` — see `fluid-bg/README.md`.
  67. [`fluid-core`](https://www.npmjs.com/package/fluid-core) is the raw engine library
  68. underneath (`createFluid(el, {…})`, zero dependencies, TypeScript types) — see
  69. `fluid-core/README.md`.
  70. No npm at all? A plain iframe still works:
  71. ```html
  72. <iframe
  73. src="https://fluid.krackeddevs.com/#p=0.5,1.5,5.5,0.03,1,10,0,0,18,0,0,1.7778,0,1,1"
  74. title="Fluid background"
  75. loading="lazy"
  76. style="border:0;width:100%;height:100%">
  77. </iframe>
  78. ```
  79. The embed flag makes the canvas fill the iframe without the studio UI.
  80. ## What is open, what is hosted
  81. Everything in this repo is MIT. What is not in the repo is befluid.xyz's data: the
  82. published pieces, their authors, the media and the admin secrets. Clone it and you have
  83. the whole studio; run the Worker with your own bindings and you have your own instance.
  84. The share-hash contract (the `#p=` fields, append-only) is the project's real API and is
  85. specified in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#share-hash-contract).
  86. ## API
  87. ```sh
  88. curl "https://fluid.krackeddevs.com/api/piece?look=borealis"
  89. curl "https://fluid.krackeddevs.com/api/piece?field=flow&palette=sunset&warp=4"
  90. curl "https://fluid.krackeddevs.com/api/piece?field=cellular&colors=0a0a1a,3a1f7a,c84fe0,ffe1f5"
  91. curl "https://fluid.krackeddevs.com/api/looks"
  92. curl "https://fluid.krackeddevs.com/api/today" # the day's piece
  93. curl "https://fluid.krackeddevs.com/api/today?date=2026-01-01" # replay any day
  94. ```
  95. `/today` is a permalink that opens the day's piece in the studio.
  96. MCP clients that support Streamable HTTP can connect to:
  97. ```sh
  98. https://fluid.krackeddevs.com/mcp
  99. ```
  100. Claude Code:
  101. ```sh
  102. claude mcp add --transport http fluid https://fluid.krackeddevs.com/mcp
  103. ```
  104. On claude.ai (web, desktop, or mobile): Settings → Connectors → Add custom
  105. connector → paste the `/mcp` URL. No auth. Tools: `create_piece`,
  106. `get_embed_code`, `list_looks`, `get_seed_of_the_day`, `decode_link`.
  107. AI agents without MCP can read the whole integration surface from
  108. [`/llms.txt`](https://fluid.krackeddevs.com/llms.txt).
  109. ## Architecture
  110. | File | Purpose |
  111. |---|---|
  112. | `index.html` | Complete studio app: UI, WebGL shader, state, export, recording, sharing |
  113. | `worker.js` | Cloudflare Worker: static assets, security headers, API, MCP, OG image rotation |
  114. | `gallery.html` | Curated examples and downloadable preview images |
  115. | `manual.html` | User reference |
  116. | `dev.html` | Embed, API, and MCP reference |
  117. | `fluid-core/` | Zero-dependency native canvas library on npm — shader + engine/palette/look tables generated from `index.html` by `fluid-core/build.mjs`, plus a small mount runtime; see `fluid-core/README.md` |
  118. | `fluid-bg/` | npm package: `<fluid-bg>` web component + React wrapper built on `fluid-core`; see `fluid-bg/README.md` |
  119. | `fluid-vibe/` | Prototype: client-side semantic "describe a vibe" matcher (transformers.js); not yet wired into the studio |
  120. | `assets/` | Favicon, gallery previews, Open Graph images, and README media |
  121. Important invariants:
  122. - Keep the original WebGL Studio dependency-free. The separate React component gallery uses the pinned development toolchain below.
  123. - Keep the shader source as joined string arrays.
  124. - Preserve the append-only `#p=` share-hash field order.
  125. - Keep mirrored constants in `index.html` and `worker.js` in sync.
  126. - After changing engines, palettes, or looks, run `node fluid-core/build.mjs` — the test suite fails on drift.
  127. - Scale screen-space shader sizes by the render scale `k` used for export.
  128. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the share-hash contract and Worker mirror notes.
  129. ## Deploy
  130. The hosted instance auto-deploys from `master` via GitHub Actions. To deploy
  131. your own:
  132. ```sh
  133. npx wrangler deploy
  134. ```
  135. Staging:
  136. ```sh
  137. npx wrangler deploy --env staging
  138. ```
  139. Deployment requires Cloudflare credentials with Worker deploy access.
  140. ## Contributing
  141. See [CONTRIBUTING.md](CONTRIBUTING.md). The most useful contributions are field
  142. engines, palette presets, gallery pieces, manual fixes, and bug reports with a
  143. share link.
  144. ## License
  145. MIT. See [LICENSE](LICENSE).
  146. ## Published app
  147. The public collection explorer, integrated 3.3 Studio, Photo → Fire, background builder and image dither generator live in `site/`. Run `npm ci` on a fresh checkout, then `npm run build:site` to prepare the explicit `.public/` asset package, then `npm run dev` for the complete Worker locally. The build keeps QA, internal project notes, scripts and repository metadata out of public assets, while retaining `/manual`, `/gallery`, `/dev`, social images and native package URLs. Root artwork share/embed hashes continue into `/studio` with their settings preserved.
  148. Publishing follows the existing master-branch GitHub Action, which builds assets and runs engine, dither and packaging tests before deployment. The original root studio remains the source for the existing 42-look API and offline engine tests; the bundled 58-look browser studio is served at `/studio`. This website release does not expand the API/MCP registry or deploy the separate hosted/community experiment.
  149. ## Fluid Components
  150. The library at `/components` contains 39 creative pieces: 22 React components, eight browser-local tools, four complete page sections and five experiments. It offers live previews, controls, source/usage tabs, complete source ZIPs and supported image, vector, HTML, CSS, JSON or JSX exports. Phone browsing is compact and touch-friendly; editing state survives Code, Replay and palette changes. The previews import the exact JSX files and relative helpers visitors receive.
  151. Run `npm ci` on a fresh checkout, `npm run build:components` after editing source or portable CSS, then `npm run build:site` and `npm test`. Both GitHub Actions install locked dependencies and rebuild the gallery before packaging. The explicit public allowlist includes reusable sources, helpers, CSS and full MIT notices, and excludes authoring gallery/registry/manifests, tests, QA and project notes.
  152. Current browser harnesses are `scripts/qa-creative-suite.mjs`, `scripts/qa-creative-worker.mjs` and `scripts/qa-fluid-mobile.mjs`; `FLUID_QA_BASE`, `FLUID_QA_PLAYWRIGHT` and `FLUID_QA_CHROME` can target an existing test installation. The new Canvas2D/CSS materials are independent of the 58-look native engine. Local media stays in the browser; preset links omit images/audio. The suite does not add video recording or change the existing 42-look/five-tool API/MCP boundary. Physical devices and Safari remain untested. The earlier six-component verification is retained historically in `docs/verification/components-library.md`.
  153. ## Pixel homepage study — 30 October 2026
  154. The homepage opens with the native Fluid wordmark rendered as 3,936 small squares. Four explicit controls morph those same squares into Fluid, Wave, Orbit or Bloom. The pixels ripple gently between shape changes, with a Pause/Play control and a target of 30 paints per second. Transitions can be retargeted; pause and hidden/offscreen states freeze both clocks. Reduced motion selects a complete still endpoint, and manual pause is preserved when the preference changes. A matching SVG appears without Canvas or JavaScript, while collection browsing remains independent of the optional artwork module. Featured WebGL studies are below the collections and mount only when visible.
  155. Source: site/pixel-hero.js and site/pixel-hero-points.js. Reproduce all geometry and the fallback without dependencies: node scripts/generate-pixel-hero.mjs. Run npm run build:site and npm test after changes. No new runtime package, remote asset or service is required. The pixel homepage integrates with the existing creative-library release and uses the standard master-branch deployment workflow.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.