# 墨池 Inkpond

> Inkpond is an ink-wash background library for web developers: animated Chinese glyphs behind your page that answer the pointer, give an empty landing, sign-in or AI chat screen some atmosphere, and stay out of the content's way. Canvas 2D, zero runtime dependencies, MIT licensed, with an optional React component.

墨池（Inkpond）是给网页开发者用的背景库：在页面背后铺一层会回应鼠标的水墨汉字动画，让空白的首页、登录页或 AI 对话页有东方意境，又不遮挡内容、不拖慢页面。

Key facts:

- Six scenes: `shanshui` (hills in mist, default), `lotus` (lotus pond whose koi avoid the pointer and swim to dropped ink), `qingming` (a handscroll of Along the River During the Qingming Festival that keeps unrolling), `jieqi` (the 24 solar terms, a picture each, chosen by today's date and switching live when the next term begins; `term: "qingming"` pins one, `date` picks a day; `jieqiAt(date)` returns a moment's term), `beiming` (the deep sea from above, a whale's shadow rising and sinking beneath the swell; it dives from the pointer and comes toward dropped ink), `dafeijing` (a comic big fat whale and a bowl of white rice drawn as bare paper; it eats until it swells, burps and spouts rice, chases rice scattered where ink drops, and laughs when the pointer pokes it).
- Interaction: the pointer stirs ripples, a click or tap drops ink; elements marked `data-inkpond-avoid` keep a clear zone that koi, boats and walkers steer around.
- Install: `npm i inkpond` (or the latest commit: `npm i github:shin4/inkpond`). Then `import "inkpond/inkpond.css"` and either `<InkPond scene="lotus" />` from `inkpond/react` (React 18+, marked "use client" so it renders from Next.js Server Components) or `createInkPond(canvas, { scene })` from `inkpond` in any framework (Vue, Svelte, Angular, plain JS).
- Programmatic input: `pond.ripple(clientX, clientY, strength)` and `pond.drop(clientX, clientY)`.
- Performance: glyphs are rasterised once into an atlas; under 1 ms of script per calm frame, about 2 ms p95 when fully stirred (1920×1080, DPR 1.5). Frame rate drops when calm, stops after 30 s idle, pauses in hidden tabs, and steps down on weak devices or software rendering.
- Accessibility: the canvas is `aria-hidden`; reduced motion draws a still picture; forced-colours mode hides it.
- Glyph size: `cellSize` (CSS px, 12–48, default 16); a device that steps down keeps its tier's larger cell.
- Colours: ink and four pale pigments (vermilion, rouge, ochre, indigo) are CSS variables with dark-mode values; `tint: false` for ink only.
- Licence: code MIT; the bundled glyph subsets of Source Han Serif SC are SIL OFL 1.1, renamed Inkpond Glyphs.
- Inspired by stackedlol/ascii-sharks; written from scratch.

## Docs

- [README (中文)](https://github.com/shin4/inkpond/blob/main/README.md): scenes, install, usage, options, performance, fonts
- [README (English)](https://github.com/shin4/inkpond/blob/main/README.en.md): the same in English
- [Full docs in one file](https://shin4.github.io/inkpond/llms-full.txt): the English README plus both FAQs, with Next.js, Vue and Svelte examples
- [FAQ (English)](https://shin4.github.io/inkpond/en/faq/): what it is, who it is for, frameworks, Next.js, Vue, Svelte, Vanta.js and tsParticles, performance, mobile, accessibility, licence
- [常见问题（中文）](https://shin4.github.io/inkpond/faq/): the same in Chinese

## Demos

- [Project page (English)](https://shin4.github.io/inkpond/en/) and [项目主页（中文）](https://shin4.github.io/inkpond/): all six scenes live, with tint and ink-depth controls
- [Session demo](https://shin4.github.io/inkpond/session/): the background behind an AI chat start screen

## Optional

- [Source code](https://github.com/shin4/inkpond): TypeScript, MIT
- [npm package](https://www.npmjs.com/package/inkpond)
- [ascii-sharks](https://github.com/stackedlol/ascii-sharks): the project that inspired Inkpond