# Fluid

> Fluid is a free, zero-backend generative-art studio at https://fluid.krackeddevs.com. It designs animated
> WebGL backgrounds, wallpapers and OG images that render on the viewer's GPU. Every design
> is a share URL carrying an append-only numeric `#p=` hash — no server rendering, no account,
> no quota. Embeds are free for any site, personal or commercial.

Key facts:

- Design in the studio at https://fluid.krackeddevs.com/, or programmatically via MCP or REST — both return share and embed URLs.
- Embed on any site with the `fluid-bg` npm package (native canvas in the page, ~15 KB gz) or a plain iframe.
- Static images (PNG/JPG/WebP at any size) are exported client-side from the studio's Export panel. There is NO image-render API — never promise a server-rendered file.

## Connect (AI agents)

- MCP server (streamable HTTP, stateless, no auth): https://fluid.krackeddevs.com/mcp
  - Claude Code: `claude mcp add --transport http fluid https://fluid.krackeddevs.com/mcp`
  - claude.ai (web / desktop / mobile): Settings -> Connectors -> Add custom connector -> paste https://fluid.krackeddevs.com/mcp
  - Tools: `create_piece` (design from params, a look, or 2-4 brand hex colours -> share_url + embed code),
    `get_embed_code` (share_url -> copy-paste native <fluid-bg> / React / iframe snippets),
    `list_looks` (curated starting points), `decode_link` (share URL -> named params, for remixing).
- REST, same generator as plain JSON: GET https://fluid.krackeddevs.com/api/piece?look=…&field=…&colors=… and GET https://fluid.krackeddevs.com/api/looks
- Human docs: https://fluid.krackeddevs.com/dev (integration) and https://fluid.krackeddevs.com/manual (studio manual); gallery: https://fluid.krackeddevs.com/gallery

## Embed on a site (fluid-bg)

```html
<script src="https://cdn.jsdelivr.net/npm/fluid-bg@0.2"></script>
<fluid-bg fixed hash="#p=0.5,1.5,5.5,0.03,1,10,0,0,18,0,0,1.7778"></fluid-bg>
```

- React: `npm i fluid-bg`, then `import FluidBg from 'fluid-bg/react'` and `<FluidBg fixed hash="#p=…" />`.
- Raw engine library: `npm i fluid-core` — `createFluid(el, {field, palette|colors, look, …})` + `parseShareHash()`; zero deps, ~21 KB, TypeScript types included. fluid-bg is built on it.
- Native by default (canvas in the page, engines bundled); falls back to a hosted iframe automatically when WebGL is unavailable. `mode="iframe"` forces the old behaviour.
- FOOTGUN: `fixed` sits at z-index -1 — keep the html/body background TRANSPARENT or the page paints over the art.
- A non-fixed `<fluid-bg>` fills its parent: give the parent a size.

## Recipes

- Live background for a site: `create_piece` (match the brand with `colors`) -> `get_embed_code` -> paste the html snippet; keep the body background transparent.
- OG image / wallpaper: `create_piece` with `aspect: "16:9"` (OG) or `"9:16"` (phone) -> open share_url in a browser -> Export panel renders the file locally.
- Match brand colours: pass `colors`: 2-4 hex stops dark -> light, e.g. ["#0a0a1a", "#ffe1f5"].
- Remix an existing piece: `decode_link` on any share URL -> tweak the named params -> `create_piece`.

## Share-hash contract (`#p=`)

Comma-separated numbers, append-only, trailing zeros trimmed (old links round-trip forever):
[0] speed [1] zoom [2] warp [3] grain [4] pixel [5] dot [6] halftone [7] palette (8 = custom)
[8] seed [9] liquify [10] blend [11] aspect [12] preset [13] embed flag (1 = chrome-less canvas)
[14] field [15] screen [16-17] pan [18] symmetry [20-23] packed custom RGB stops
[24] dither-threshold offset [25-27] layer [28] material finish.
Values are numeric only; parsers must clamp and reject NaN.