npm - dotmote - Versions diffs - 0.3.2 → 0.3.3 - Mend

dotmote 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/LICENSE CHANGED Viewed

@@ -1,21 +1,21 @@
-MIT License
-Copyright (c) 2026 Ryan
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+Copyright (c) 2026 Ryan
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,201 +1,205 @@
-# dotmote
-<img src="https://raw.githubusercontent.com/rryanchiu/dotmote/main/docs/example.png" alt="dotmote — LED dot-matrix glow component" width="100%" />
-<p align="center">
-  <a href="https://www.npmjs.com/package/dotmote"><img alt="npm" src="https://img.shields.io/npm/v/dotmote" /></a>
-  <img alt="license" src="https://img.shields.io/npm/l/dotmote" />
-  <img alt="bundle size" src="https://img.shields.io/bundlephobia/minzip/dotmote" />
-  <a href="https://dotmote.imryan.dev"><img alt="Live demo" src="https://img.shields.io/badge/Live%20demo-dotmote.imryan.dev-2ea44f" /></a>
-  <a href="https://stackblitz.com/github/rryanchiu/dotmote"><img alt="Open in StackBlitz" src="https://img.shields.io/badge/Open%20in-StackBlitz-1269D3" /></a>
-</p>
-<p align="center">[English](https://github.com/rryanchiu/dotmote/blob/main/README.md) · [简体中文](https://github.com/rryanchiu/dotmote/blob/main/README.zh-CN.md)</p>
-> **Live demo** — [dotmote.imryan.dev](https://dotmote.imryan.dev) · **Try it live**: [Open in StackBlitz](https://stackblitz.com/github/rryanchiu/dotmote) to run the playground in your browser. You can also import this GitHub repo into CodeSandbox.
-A framework-agnostic dotted-matrix glow background for React and Vue. Scatter a few letters, emoji, or shapes over an endless grid of dots — they drift, bump into each other, and glow through the lattice like a little light show.
-- **React 18+** · TypeScript · Canvas 2D · **SSR-safe**
-- **Zero runtime deps** — just `react` (peer)
-- Pure Canvas 2D — no particle or dot-grid libraries
-## Install
-```bash
-npm install dotmote
-```
-Requires `react >= 18`. Ships ESM + TypeScript types.
-## Quick start
-```tsx
-import { Dotmote } from 'dotmote';
-export function Page() {
-  return (
-    <div style={{ position: 'relative', minHeight: '100vh' }}>
-      <Dotmote theme="gradient" />
-      <main style={{ position: 'relative', zIndex: 1, padding: 24 }}>
-        <h1>My page</h1>
-      </main>
-    </div>
-  );
-}
-```
-The wrapper `<div>` is absolutely positioned behind everything — put your content in a sibling with a higher `z-index`.
-## Vue
-The Canvas core is framework-agnostic — React and Vue are both thin wrappers over
-the same `createDotMatrixCore`. For Vue 3 use the `dotmote/vue` entry:
-```vue
-<script setup>
-import { Dotmote } from 'dotmote/vue';
-</script>
-<template>
-  <div style="position: relative; min-height: 40vh">
-    <Dotmote values="👋dotmote!" theme="auto" motion="ticker-right" />
-  </div>
-</template>
-```
-`class` / `style` fall through to the wrapper `<div>`.
-## Props
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `values` | `string` | — | Content as a string — each character becomes one body (whitespace skipped). Shorthand for `items`. |
-| `items` | `(ContentItem \| string)[]` | `['A','B','C','D','E']` | The bodies to drift. Strings become letters; see [Content](#content). |
-| `theme` | `ThemePreset \| ThemeConfig` | `'auto'` | A preset name or an inline config (`dotColor`, `activeDotColor`, `glow`, `background`). `auto` picks `light`/`dark` from the OS. |
-| `motion` | `MotionMode` | `'drift'` | How the bodies move — see [Motion](#motion). |
-| `speed` | `number` | `1` | Global speed multiplier. |
-| `glowStrength` | `number` | `1` | Glow strength: `<1` fades it, `>1` brightens. (`glowAlpha` is a deprecated alias.) |
-| `dotRadius` | `number` | `spacing <= 9 ? 0.82 : 1` | Dot size in px. Bigger = chunkier dots. |
-| `fontFamily` | `string` | `"Trebuchet MS", ui-rounded, sans-serif` | Font stack (weight/size are prefixed: `900 ${fontSize}px …`). |
-| `fontSize` | `number` | — | Fixed character size in px. Overrides the auto size (and `fontSizeOverride`). |
-| `fontSizeOverride` | `number \| ((w)=>number)` | — | Override the automatic font size. |
-| `fontSizeMin` / `fontSizeMax` | `number` | `207` / `270` | Bounds of the automatic font clamp. |
-| `breakpoints` | `Partial<Breakpoints>` | `{small:372, medium:640, …}` | Responsive geometry. |
-| `spacingScale` | `number` | `1` | Lattice density — `<1` denser, `>1` sparser. |
-| `charGap` | `number` | `auto` | Gap between characters in `ticker` / `static` rows (px). Omit for an auto compact spacing. |
-| `introDurationMs` | `number` | `520` | Hold + fade-in period. |
-| `className` / `class` / `style` | `string` / `string` / `CSSProperties` | — | Passed to the wrapper `<div>`. `class` is an alias for `className`. |
-| `ariaHidden` | `boolean` | `true` | `aria-hidden` on the wrapper. |
-## Themes
-Pick a neutral preset, or bring your own colors:
-```tsx
-<Dotmote theme="mono" />   // default
-<Dotmote theme="dark" />
-<Dotmote theme="gradient" />
-<Dotmote
-  theme={{
-    dotColor: 'rgba(96, 165, 250, 0.6)',
-    glow: ['rgba(56, 189, 248, 0.9)', 'rgba(99, 102, 241, 0.9)', 'rgba(236, 72, 153, 0.9)'],
-    background: '#0b1020',
-  }}
-/>
-```
-Presets: `auto`, `light`, `dark`, `mono`, `gradient`. `auto` (the default) follows
-the OS `prefers-color-scheme` — leave `theme` out to use it. The quick start uses
-`theme="gradient"`; pass `theme="mono"` for no background + neutral gray dots.
-```ts
-interface ThemeConfig {
-  dotColor?: string;       // lattice dot color
-  activeDotColor?: string; // flat glow color (all 3 stops); omit to use `glow`
-  glow: [string, string, string];
-  background?: string;
-}
-```
-Changing the theme hot-updates in place — the bodies keep their positions and motion.
-## Content
-`values` is the fastest way to fill the background — each character becomes a body:
-```tsx
-<Dotmote values="dotmote" />
-<Dotmote values="🌊🔥⭐🌙" />
-```
-For per-body control, use `items`:
-```tsx
-<Dotmote items={['A', 'B', 'C', 'D', 'E']} />
-<Dotmote items={[{ kind: 'shape', value: 'circle', radius: 60 }, { kind: 'emoji', value: '🌊' }]} />
-```
-```ts
-type ContentItem =
-  | { kind: 'text'; value: string }
-  | { kind: 'emoji'; value: string }
-  | { kind: 'shape'; value: 'circle' | 'square' | 'triangle' | 'star' | 'diamond'; radius?: number }
-  | { kind: 'path'; value: string }; // SVG path
-```
-## Motion
-| Mode | Behavior |
-| --- | --- |
-| `drift` | drift + wall bounce + pairs collide |
-| `roam` | drift + bounce, bodies pass through each other |
-| `static` | frozen after the intro fade — laid out horizontally-aligned as a centered row |
-| `ticker-left` / `ticker-right` | marquee: horizontally-aligned row at the center, scrolling and looping with even spacing |
-## Development
-```bash
-npm install
-npm run dev       # playground at http://localhost:5199/
-npm test          # vitest (physics + item normalization)
-npm run lint
-npm run typecheck
-npm run build     # tsc → dist/
-```
-The playground runs on any modern browser — resize across 372 / 640px to see the breakpoints, and open DevTools → Console to confirm the reload is clean.
-## Deploy the demo
-The playground (`examples/`) is a static Vite site; `npm run build:site` emits it to `site/`. The npm **library** is built separately with `npm run build` → `dist/` (that's what gets published to npm, not the site).
-### GitHub Pages
-1. Push the repo, then in Settings → **Pages → Source = "GitHub Actions"**.
-2. The included `.github/workflows/pages.yml` builds the demo on every push and publishes it at `https://<user>.github.io/dotmote/` (base `/dotmote/`).
-### Cloudflare Pages
-1. Dashboard → **Workers & Pages → Create → Pages → Connect to Git** → pick the repo.
-2. Build settings:
-   - Build command: `npm run build:site`
-   - Build output directory: `site`
-3. Leave the base path empty — Cloudflare serves from the domain root, so no `--base` is needed.
-## Architecture
-A thin React wrapper over a framework-agnostic Canvas core. Four canvases: a dot lattice, its white alpha mask, the gradient-illuminated bodies, and the composite. The lattice and mask redraw only on resize; the glow composites every frame.
-## Notes / limitations
-- **ESM only** — no CommonJS build; use a bundler that supports ESM.
-- **Emoji keep their own colors** — they ignore the glow gradient (text and shapes recolor).
-- **`path` is basic** — feed a path already centered near the origin and scaled to ~±100 units.
-- Collision is a simplified momentum swap, not a full physics impulse.
-## License
-MIT
+# dotmote
+<img src="https://raw.githubusercontent.com/rryanchiu/dotmote/main/docs/example.png" alt="dotmote — LED dot-matrix glow component" width="100%" />
+<p align="center">
+  <a href="https://www.npmjs.com/package/dotmote"><img alt="npm" src="https://img.shields.io/npm/v/dotmote" /></a>
+  <img alt="license" src="https://img.shields.io/npm/l/dotmote" />
+  <img alt="bundle size" src="https://img.shields.io/bundlephobia/minzip/dotmote" />
+  <a href="https://dotmote.imryan.dev"><img alt="Live demo" src="https://img.shields.io/badge/Live%20demo-dotmote.imryan.dev-2ea44f" /></a>
+  <a href="https://stackblitz.com/github/rryanchiu/dotmote"><img alt="Open in StackBlitz" src="https://img.shields.io/badge/Open%20in-StackBlitz-1269D3" /></a>
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rryanchiu/dotmote/main/docs/dotmote.gif" alt="dotmote demo" width="200" />
+</p>
+<p align="center"><a href="https://github.com/rryanchiu/dotmote/blob/main/README.md">English</a> · <a href="https://github.com/rryanchiu/dotmote/blob/main/README.zh-CN.md">简体中文</a></p>
+> **Live demo** — [dotmote.imryan.dev](https://dotmote.imryan.dev) · **Try it live**: [Open in StackBlitz](https://stackblitz.com/github/rryanchiu/dotmote) to run the playground in your browser. You can also import this GitHub repo into CodeSandbox.
+A framework-agnostic dotted-matrix glow background for React and Vue. Scatter a few letters, emoji, or shapes over an endless grid of dots — they drift, bump into each other, and glow through the lattice like a little light show.
+- **React 18+** · TypeScript · Canvas 2D · **SSR-safe**
+- **Zero runtime deps** — just `react` (peer)
+- Pure Canvas 2D — no particle or dot-grid libraries
+## Install
+```bash
+npm install dotmote
+```
+Requires `react >= 18`. Ships ESM + TypeScript types.
+## Quick start
+```tsx
+import { Dotmote } from 'dotmote';
+export function Page() {
+  return (
+    <div style={{ position: 'relative', minHeight: '100vh' }}>
+      <Dotmote theme="gradient" />
+      <main style={{ position: 'relative', zIndex: 1, padding: 24 }}>
+        <h1>My page</h1>
+      </main>
+    </div>
+  );
+}
+```
+The wrapper `<div>` is absolutely positioned behind everything — put your content in a sibling with a higher `z-index`.
+## Vue
+The Canvas core is framework-agnostic — React and Vue are both thin wrappers over
+the same `createDotMatrixCore`. For Vue 3 use the `dotmote/vue` entry:
+```vue
+<script setup>
+import { Dotmote } from 'dotmote/vue';
+</script>
+<template>
+  <div style="position: relative; min-height: 40vh">
+    <Dotmote values="👋dotmote!" theme="auto" motion="ticker-right" />
+  </div>
+</template>
+```
+`class` / `style` fall through to the wrapper `<div>`.
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `values` | `string` | — | Content as a string — each character becomes one body (whitespace skipped). Shorthand for `items`. |
+| `items` | `(ContentItem \| string)[]` | `['A','B','C','D','E']` | The bodies to drift. Strings become letters; see [Content](#content). |
+| `theme` | `ThemePreset \| ThemeConfig` | `'auto'` | A preset name or an inline config (`dotColor`, `activeDotColor`, `glow`, `background`). `auto` picks `light`/`dark` from the OS. |
+| `motion` | `MotionMode` | `'drift'` | How the bodies move — see [Motion](#motion). |
+| `speed` | `number` | `1` | Global speed multiplier. |
+| `glowStrength` | `number` | `1` | Glow strength: `<1` fades it, `>1` brightens. (`glowAlpha` is a deprecated alias.) |
+| `dotRadius` | `number` | `spacing <= 9 ? 0.82 : 1` | Dot size in px. Bigger = chunkier dots. |
+| `fontFamily` | `string` | `"Trebuchet MS", ui-rounded, sans-serif` | Font stack (weight/size are prefixed: `900 ${fontSize}px …`). |
+| `fontSize` | `number` | — | Fixed character size in px. Overrides the auto size (and `fontSizeOverride`). |
+| `fontSizeOverride` | `number \| ((w)=>number)` | — | Override the automatic font size. |
+| `fontSizeMin` / `fontSizeMax` | `number` | `207` / `270` | Bounds of the automatic font clamp. |
+| `breakpoints` | `Partial<Breakpoints>` | `{small:372, medium:640, …}` | Responsive geometry. |
+| `spacingScale` | `number` | `1` | Lattice density — `<1` denser, `>1` sparser. |
+| `charGap` | `number` | `auto` | Gap between characters in `ticker` / `static` rows (px). Omit for an auto compact spacing. |
+| `introDurationMs` | `number` | `520` | Hold + fade-in period. |
+| `className` / `class` / `style` | `string` / `string` / `CSSProperties` | — | Passed to the wrapper `<div>`. `class` is an alias for `className`. |
+| `ariaHidden` | `boolean` | `true` | `aria-hidden` on the wrapper. |
+## Themes
+Pick a neutral preset, or bring your own colors:
+```tsx
+<Dotmote theme="mono" />   // default
+<Dotmote theme="dark" />
+<Dotmote theme="gradient" />
+<Dotmote
+  theme={{
+    dotColor: 'rgba(96, 165, 250, 0.6)',
+    glow: ['rgba(56, 189, 248, 0.9)', 'rgba(99, 102, 241, 0.9)', 'rgba(236, 72, 153, 0.9)'],
+    background: '#0b1020',
+  }}
+/>
+```
+Presets: `auto`, `light`, `dark`, `mono`, `gradient`. `auto` (the default) follows
+the OS `prefers-color-scheme` — leave `theme` out to use it. The quick start uses
+`theme="gradient"`; pass `theme="mono"` for no background + neutral gray dots.
+```ts
+interface ThemeConfig {
+  dotColor?: string;       // lattice dot color
+  activeDotColor?: string; // flat glow color (all 3 stops); omit to use `glow`
+  glow: [string, string, string];
+  background?: string;
+}
+```
+Changing the theme hot-updates in place — the bodies keep their positions and motion.
+## Content
+`values` is the fastest way to fill the background — each character becomes a body:
+```tsx
+<Dotmote values="dotmote" />
+<Dotmote values="🌊🔥⭐🌙" />
+```
+For per-body control, use `items`:
+```tsx
+<Dotmote items={['A', 'B', 'C', 'D', 'E']} />
+<Dotmote items={[{ kind: 'shape', value: 'circle', radius: 60 }, { kind: 'emoji', value: '🌊' }]} />
+```
+```ts
+type ContentItem =
+  | { kind: 'text'; value: string }
+  | { kind: 'emoji'; value: string }
+  | { kind: 'shape'; value: 'circle' | 'square' | 'triangle' | 'star' | 'diamond'; radius?: number }
+  | { kind: 'path'; value: string }; // SVG path
+```
+## Motion
+| Mode | Behavior |
+| --- | --- |
+| `drift` | drift + wall bounce + pairs collide |
+| `roam` | drift + bounce, bodies pass through each other |
+| `static` | frozen after the intro fade — laid out horizontally-aligned as a centered row |
+| `ticker-left` / `ticker-right` | marquee: horizontally-aligned row at the center, scrolling and looping with even spacing |
+## Development
+```bash
+npm install
+npm run dev       # playground at http://localhost:5199/
+npm test          # vitest (physics + item normalization)
+npm run lint
+npm run typecheck
+npm run build     # tsc → dist/
+```
+The playground runs on any modern browser — resize across 372 / 640px to see the breakpoints, and open DevTools → Console to confirm the reload is clean.
+## Deploy the demo
+The playground (`examples/`) is a static Vite site; `npm run build:site` emits it to `site/`. The npm **library** is built separately with `npm run build` → `dist/` (that's what gets published to npm, not the site).
+### GitHub Pages
+1. Push the repo, then in Settings → **Pages → Source = "GitHub Actions"**.
+2. The included `.github/workflows/pages.yml` builds the demo on every push and publishes it at `https://<user>.github.io/dotmote/` (base `/dotmote/`).
+### Cloudflare Pages
+1. Dashboard → **Workers & Pages → Create → Pages → Connect to Git** → pick the repo.
+2. Build settings:
+   - Build command: `npm run build:site`
+   - Build output directory: `site`
+3. Leave the base path empty — Cloudflare serves from the domain root, so no `--base` is needed.
+## Architecture
+A thin React wrapper over a framework-agnostic Canvas core. Four canvases: a dot lattice, its white alpha mask, the gradient-illuminated bodies, and the composite. The lattice and mask redraw only on resize; the glow composites every frame.
+## Notes / limitations
+- **ESM only** — no CommonJS build; use a bundler that supports ESM.
+- **Emoji keep their own colors** — they ignore the glow gradient (text and shapes recolor).
+- **`path` is basic** — feed a path already centered near the origin and scaled to ~±100 units.
+- Collision is a simplified momentum swap, not a full physics impulse.
+## License
+MIT

package/README.zh-CN.md CHANGED Viewed

@@ -1,179 +1,183 @@
-# dotmote
-<img src="https://raw.githubusercontent.com/rryanchiu/dotmote/main/docs/example.png" alt="dotmote — LED 点阵流光组件" width="100%" />
-<p align="center">
-  <a href="https://www.npmjs.com/package/dotmote"><img alt="npm" src="https://img.shields.io/npm/v/dotmote" /></a>
-  <img alt="license" src="https://img.shields.io/npm/l/dotmote" />
-  <img alt="bundle size" src="https://img.shields.io/bundlephobia/minzip/dotmote" />
-  <a href="https://dotmote.imryan.dev"><img alt="在线演示" src="https://img.shields.io/badge/Live%20demo-dotmote.imryan.dev-2ea44f" /></a>
-  <a href="https://stackblitz.com/github/rryanchiu/dotmote"><img alt="Open in StackBlitz" src="https://img.shields.io/badge/Open%20in-StackBlitz-1269D3" /></a>
-</p>
-<p align="center">[English](https://github.com/rryanchiu/dotmote/blob/main/README.md) · [简体中文](https://github.com/rryanchiu/dotmote/blob/main/README.zh-CN.md)</p>
-> **在线演示** — [dotmote.imryan.dev](https://dotmote.imryan.dev)。
-框架无关的点阵发光背景，支持 React 与 Vue。把几个字母、emoji 或形状撒在一片无边的点阵上——它们四处漂移、彼此碰撞，然后从网格里透出光来，像一场小小的灯展。
-- **React 18+** · TypeScript · Canvas 2D · **SSR 安全**
-- **零运行时依赖** —— 只需 `react`（peer）
-- 纯 Canvas 2D，不用任何粒子或点阵库
-## 安装
-```bash
-npm install dotmote
-```
-需要 `react >= 18`。提供 ESM + TypeScript 类型声明。
-## 快速开始
-```tsx
-import { Dotmote } from 'dotmote';
-export function Page() {
-  return (
-    <div style={{ position: 'relative', minHeight: '100vh' }}>
-      <Dotmote theme="gradient" />
-      <main style={{ position: 'relative', zIndex: 1, padding: 24 }}>
-        <h1>My page</h1>
-      </main>
-    </div>
-  );
-}
-```
-外层包裹的 `<div>` 是绝对定位、垫在所有内容后面——把你的内容放进一个 `z-index` 更高的兄弟节点即可。
-## Vue
-Canvas 核心与框架无关——React 与 Vue 都只是同一套 `createDotMatrixCore` 的薄封装。Vue 3 用 `dotmote/vue` 入口：
-```vue
-<script setup>
-import { Dotmote } from 'dotmote/vue';
-</script>
-<template>
-  <div style="position: relative; min-height: 40vh">
-    <Dotmote values="👋dotmote!" theme="auto" motion="ticker-right" />
-  </div>
-</template>
-```
-`class` / `style` 会透传到外层 `<div>`。
-## 属性
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `values` | `string` | — | 用一个字符串填充内容——每个字符成为一个主体（空白会被跳过）。`items` 的简写。 |
-| `items` | `(ContentItem \| string)[]` | `['A','B','C','D','E']` | 要漂移的主体。字符串会变成字母；见 [内容](#内容)。 |
-| `theme` | `ThemePreset \| ThemeConfig` | `'mono'` | 预设名，或内联配置（`dotColor`、`activeDotColor`、`glow`、`background`）。 |
-| `motion` | `MotionMode` | `'drift'` | 主体的运动方式——见 [动效](#动效)。 |
-| `speed` | `number` | `1` | 全局速度倍率。 |
-| `glowStrength` | `number` | `1` | 发光强度：`<1` 变淡，`>1` 更亮。（`glowAlpha` 是已废弃的别名。） |
-| `dotRadius` | `number` | `spacing <= 9 ? 0.82 : 1` | 点的大小（px）。越大越"颗粒感"。 |
-| `fontFamily` | `string` | `"Trebuchet MS", ui-rounded, sans-serif` | 字体栈（字重/字号会自动前置：`900 ${fontSize}px …`）。 |
-| `fontSizeOverride` | `number \| ((w)=>number)` | — | 覆盖自动字号。 |
-| `fontSizeMin` / `fontSizeMax` | `number` | `207` / `270` | 自动字号钳制的上下界。 |
-| `breakpoints` | `Partial<Breakpoints>` | `{small:372, medium:640, …}` | 响应式几何。 |
-| `spacingScale` | `number` | `1` | 点阵密度——`<1` 更密，`>1` 更疏。 |
-| `introDurationMs` | `number` | `520` | 停留 + 淡入时长。 |
-| `className` / `style` | `string` / `CSSProperties` | — | 传给包裹 `<div>`。 |
-| `ariaHidden` | `boolean` | `true` | 包裹 `<div>` 的 `aria-hidden`。 |
-## 主题
-选一个中性预设，或换成你自己的配色：
-```tsx
-<Dotmote theme="mono" />   // 默认
-<Dotmote theme="dark" />
-<Dotmote theme="gradient" />
-<Dotmote
-  theme={{
-    dotColor: 'rgba(96, 165, 250, 0.6)',
-    glow: ['rgba(56, 189, 248, 0.9)', 'rgba(99, 102, 241, 0.9)', 'rgba(236, 72, 153, 0.9)'],
-    background: '#0b1020',
-  }}
-/>
-```
-预设：`light`、`dark`、`mono`、`gradient`、`rainbow`。
-```ts
-interface ThemeConfig {
-  dotColor?: string;       // 点阵颜色
-  activeDotColor?: string; // 纯色发光（3 个 stop 同色）；不填则用 `glow`
-  glow: [string, string, string];
-  background?: string;
-}
-```
-切换主题会原地热更新——主体保持当前位置和运动不变。
-## 内容
-`values` 是最快的填充方式——每个字符成为一个主体：
-```tsx
-<Dotmote values="dotmote" />
-<Dotmote values="🌊🔥⭐🌙" />
-```
-想逐个控制，就用 `items`：
-```tsx
-<Dotmote items={['A', 'B', 'C', 'D', 'E']} />
-<Dotmote items={[{ kind: 'shape', value: 'circle', radius: 60 }, { kind: 'emoji', value: '🌊' }]} />
-```
-```ts
-type ContentItem =
-  | { kind: 'text'; value: string }
-  | { kind: 'emoji'; value: string }
-  | { kind: 'shape'; value: 'circle' | 'square' | 'triangle' | 'star' | 'diamond'; radius?: number }
-  | { kind: 'path'; value: string }; // SVG 路径
-```
-## 动效
-| Mode | 行为 |
-| --- | --- |
-| `drift` | 漂移 + 碰壁反弹 + 两两碰撞 |
-| `roam` | 漂移 + 反弹，主体彼此穿过 |
-| `static` | 淡入后静止 |
-| `ticker-left` / `ticker-right` | 跑马灯：主体排成一行循环滚动 |
-## 开发
-```bash
-npm install
-npm run dev       # playground 在 http://localhost:5199/examples/index.html
-npm test          # vitest（物理 + 内容归一化）
-npm run lint
-npm run typecheck
-npm run build     # tsc → dist/
-```
-playground 在任何现代浏览器都能跑——把窗口跨过 372 / 640px 看断点变化，并在 DevTools → Console 里确认刷新无报错。
-## 架构
-薄薄一层 React 包装，下面是框架无关的 Canvas 核心。四个画布：点阵、它的白色 alpha 遮罩、被渐变照亮的主体、以及合成层。点阵和遮罩只在尺寸变化时重绘；发光层每帧合成。
-## 说明 / 限制
-- **仅 ESM** —— 没有 CommonJS 构建；请用支持 ESM 的打包器。
-- **emoji 保持自身颜色** —— 它们不跟随发光渐变（文本和形状会变色）。
-- **`path` 只支持基础用法** —— 传入一条已大致以原点为中心、缩放到约 ±100 单位的路径。
-- 碰撞是简化的动量交换，不是完整的物理冲量。
-## 许可证
-MIT
+# dotmote
+<img src="https://raw.githubusercontent.com/rryanchiu/dotmote/main/docs/example.png" alt="dotmote — LED 点阵流光组件" width="100%" />
+<p align="center">
+  <a href="https://www.npmjs.com/package/dotmote"><img alt="npm" src="https://img.shields.io/npm/v/dotmote" /></a>
+  <img alt="license" src="https://img.shields.io/npm/l/dotmote" />
+  <img alt="bundle size" src="https://img.shields.io/bundlephobia/minzip/dotmote" />
+  <a href="https://dotmote.imryan.dev"><img alt="在线演示" src="https://img.shields.io/badge/Live%20demo-dotmote.imryan.dev-2ea44f" /></a>
+  <a href="https://stackblitz.com/github/rryanchiu/dotmote"><img alt="Open in StackBlitz" src="https://img.shields.io/badge/Open%20in-StackBlitz-1269D3" /></a>
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rryanchiu/dotmote/main/docs/dotmote.gif" alt="dotmote 演示" width="200" />
+</p>
+<p align="center"><a href="https://github.com/rryanchiu/dotmote/blob/main/README.md">English</a> · <a href="https://github.com/rryanchiu/dotmote/blob/main/README.zh-CN.md">简体中文</a></p>
+> **在线演示** — [dotmote.imryan.dev](https://dotmote.imryan.dev)。
+框架无关的点阵发光背景，支持 React 与 Vue。把几个字母、emoji 或形状撒在一片无边的点阵上——它们四处漂移、彼此碰撞，然后从网格里透出光来，像一场小小的灯展。
+- **React 18+** · TypeScript · Canvas 2D · **SSR 安全**
+- **零运行时依赖** —— 只需 `react`（peer）
+- 纯 Canvas 2D，不用任何粒子或点阵库
+## 安装
+```bash
+npm install dotmote
+```
+需要 `react >= 18`。提供 ESM + TypeScript 类型声明。
+## 快速开始
+```tsx
+import { Dotmote } from 'dotmote';
+export function Page() {
+  return (
+    <div style={{ position: 'relative', minHeight: '100vh' }}>
+      <Dotmote theme="gradient" />
+      <main style={{ position: 'relative', zIndex: 1, padding: 24 }}>
+        <h1>My page</h1>
+      </main>
+    </div>
+  );
+}
+```
+外层包裹的 `<div>` 是绝对定位、垫在所有内容后面——把你的内容放进一个 `z-index` 更高的兄弟节点即可。
+## Vue
+Canvas 核心与框架无关——React 与 Vue 都只是同一套 `createDotMatrixCore` 的薄封装。Vue 3 用 `dotmote/vue` 入口：
+```vue
+<script setup>
+import { Dotmote } from 'dotmote/vue';
+</script>
+<template>
+  <div style="position: relative; min-height: 40vh">
+    <Dotmote values="👋dotmote!" theme="auto" motion="ticker-right" />
+  </div>
+</template>
+```
+`class` / `style` 会透传到外层 `<div>`。
+## 属性
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `values` | `string` | — | 用一个字符串填充内容——每个字符成为一个主体（空白会被跳过）。`items` 的简写。 |
+| `items` | `(ContentItem \| string)[]` | `['A','B','C','D','E']` | 要漂移的主体。字符串会变成字母；见 [内容](#内容)。 |
+| `theme` | `ThemePreset \| ThemeConfig` | `'mono'` | 预设名，或内联配置（`dotColor`、`activeDotColor`、`glow`、`background`）。 |
+| `motion` | `MotionMode` | `'drift'` | 主体的运动方式——见 [动效](#动效)。 |
+| `speed` | `number` | `1` | 全局速度倍率。 |
+| `glowStrength` | `number` | `1` | 发光强度：`<1` 变淡，`>1` 更亮。（`glowAlpha` 是已废弃的别名。） |
+| `dotRadius` | `number` | `spacing <= 9 ? 0.82 : 1` | 点的大小（px）。越大越"颗粒感"。 |
+| `fontFamily` | `string` | `"Trebuchet MS", ui-rounded, sans-serif` | 字体栈（字重/字号会自动前置：`900 ${fontSize}px …`）。 |
+| `fontSizeOverride` | `number \| ((w)=>number)` | — | 覆盖自动字号。 |
+| `fontSizeMin` / `fontSizeMax` | `number` | `207` / `270` | 自动字号钳制的上下界。 |
+| `breakpoints` | `Partial<Breakpoints>` | `{small:372, medium:640, …}` | 响应式几何。 |
+| `spacingScale` | `number` | `1` | 点阵密度——`<1` 更密，`>1` 更疏。 |
+| `introDurationMs` | `number` | `520` | 停留 + 淡入时长。 |
+| `className` / `style` | `string` / `CSSProperties` | — | 传给包裹 `<div>`。 |
+| `ariaHidden` | `boolean` | `true` | 包裹 `<div>` 的 `aria-hidden`。 |
+## 主题
+选一个中性预设，或换成你自己的配色：
+```tsx
+<Dotmote theme="mono" />   // 默认
+<Dotmote theme="dark" />
+<Dotmote theme="gradient" />
+<Dotmote
+  theme={{
+    dotColor: 'rgba(96, 165, 250, 0.6)',
+    glow: ['rgba(56, 189, 248, 0.9)', 'rgba(99, 102, 241, 0.9)', 'rgba(236, 72, 153, 0.9)'],
+    background: '#0b1020',
+  }}
+/>
+```
+预设：`light`、`dark`、`mono`、`gradient`、`rainbow`。
+```ts
+interface ThemeConfig {
+  dotColor?: string;       // 点阵颜色
+  activeDotColor?: string; // 纯色发光（3 个 stop 同色）；不填则用 `glow`
+  glow: [string, string, string];
+  background?: string;
+}
+```
+切换主题会原地热更新——主体保持当前位置和运动不变。
+## 内容
+`values` 是最快的填充方式——每个字符成为一个主体：
+```tsx
+<Dotmote values="dotmote" />
+<Dotmote values="🌊🔥⭐🌙" />
+```
+想逐个控制，就用 `items`：
+```tsx
+<Dotmote items={['A', 'B', 'C', 'D', 'E']} />
+<Dotmote items={[{ kind: 'shape', value: 'circle', radius: 60 }, { kind: 'emoji', value: '🌊' }]} />
+```
+```ts
+type ContentItem =
+  | { kind: 'text'; value: string }
+  | { kind: 'emoji'; value: string }
+  | { kind: 'shape'; value: 'circle' | 'square' | 'triangle' | 'star' | 'diamond'; radius?: number }
+  | { kind: 'path'; value: string }; // SVG 路径
+```
+## 动效
+| Mode | 行为 |
+| --- | --- |
+| `drift` | 漂移 + 碰壁反弹 + 两两碰撞 |
+| `roam` | 漂移 + 反弹，主体彼此穿过 |
+| `static` | 淡入后静止 |
+| `ticker-left` / `ticker-right` | 跑马灯：主体排成一行循环滚动 |
+## 开发
+```bash
+npm install
+npm run dev       # playground 在 http://localhost:5199/examples/index.html
+npm test          # vitest（物理 + 内容归一化）
+npm run lint
+npm run typecheck
+npm run build     # tsc → dist/
+```
+playground 在任何现代浏览器都能跑——把窗口跨过 372 / 640px 看断点变化，并在 DevTools → Console 里确认刷新无报错。
+## 架构
+薄薄一层 React 包装，下面是框架无关的 Canvas 核心。四个画布：点阵、它的白色 alpha 遮罩、被渐变照亮的主体、以及合成层。点阵和遮罩只在尺寸变化时重绘；发光层每帧合成。
+## 说明 / 限制
+- **仅 ESM** —— 没有 CommonJS 构建；请用支持 ESM 的打包器。
+- **emoji 保持自身颜色** —— 它们不跟随发光渐变（文本和形状会变色）。
+- **`path` 只支持基础用法** —— 传入一条已大致以原点为中心、缩放到约 ±100 单位的路径。
+- 碰撞是简化的动量交换，不是完整的物理冲量。
+## 许可证
+MIT

package/package.json CHANGED Viewed

@@ -1,77 +1,86 @@
-{
-  "name": "dotmote",
-  "version": "0.3.2",
-  "description": "Brand-agnostic dotted-matrix glow background. Framework-agnostic Canvas core with thin React and Vue wrappers.",
-  "keywords": [
-    "react",
-    "canvas",
-    "background",
-    "dot-matrix",
-    "dotted-grid",
-    "particles",
-    "glow",
-    "typescript"
-  ],
-  "license": "MIT",
-  "type": "module",
-  "sideEffects": false,
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./themes": {
-      "types": "./dist/themes.d.ts",
-      "import": "./dist/themes.js"
-    },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js"
-    },
-    "./vue": {
-      "types": "./dist/vue/index.d.ts",
-      "import": "./dist/vue/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "README.zh-CN.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.build.json",
-    "build:site": "vite build",
-    "prepublishOnly": "npm run build",
-    "lint": "eslint . --ext .ts,.tsx",
-    "test": "vitest run",
-    "dev": "vite",
-    "clean": "rm -rf dist"
-  },
-  "peerDependencies": {
-    "react": ">=18",
-    "vue": "^3.3"
-  },
-  "devDependencies": {
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
-    "@typescript-eslint/eslint-plugin": "^7.16.1",
-    "@typescript-eslint/parser": "^7.16.1",
-    "@vitejs/plugin-react": "^4.3.1",
-    "eslint": "^8.57.0",
-    "eslint-plugin-react-hooks": "^4.6.2",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "typescript": "^5.5.3",
-    "vite": "^5.4.0",
-    "vitest": "^2.0.3",
-    "vue": "^3.4.2"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "dotmote",
+  "version": "0.3.3",
+  "description": "Brand-agnostic dotted-matrix glow background. Framework-agnostic Canvas core with thin React and Vue wrappers.",
+  "keywords": [
+    "react",
+    "canvas",
+    "background",
+    "dot-matrix",
+    "dotted-grid",
+    "particles",
+    "glow",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rryanchiu/dotmote.git"
+  },
+  "homepage": "https://dotmote.imryan.dev",
+  "bugs": {
+    "url": "https://github.com/rryanchiu/dotmote/issues"
+  },
+  "author": "Ryan <xiaolg.qiu@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./themes": {
+      "types": "./dist/themes.d.ts",
+      "import": "./dist/themes.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./vue": {
+      "types": "./dist/vue/index.d.ts",
+      "import": "./dist/vue/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "build:site": "vite build",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint . --ext .ts,.tsx",
+    "test": "vitest run",
+    "dev": "vite",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "vue": "^3.3"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@typescript-eslint/eslint-plugin": "^7.16.1",
+    "@typescript-eslint/parser": "^7.16.1",
+    "@vitejs/plugin-react": "^4.3.1",
+    "eslint": "^8.57.0",
+    "eslint-plugin-react-hooks": "^4.6.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.5.3",
+    "vite": "^5.4.0",
+    "vitest": "^2.0.3",
+    "vue": "^3.4.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}