bloub-to-vue-and-react 0.1.2 → 0.2.0

package/README.md

@@ -1,111 +1,249 @@
-# bloub
-
-An SVG recreation of the x.ai bot avatar: **one filled black shape** that morphs
-between 14 states, **two white shapes** for the eyes that morph independently, on
-a plain background. No animation library.
-
-![The avatar going through idle, wink, orbit and burst](docs/demo.gif)
-
-## Running it
-
-```bash
-pnpm install
-pnpm dev
-```
-
-Then open http://localhost:5190.
-
-```bash
-pnpm test     # vitest
-pnpm build    # vue-tsc --noEmit && vite build
-```
-
-Vue 3, Vite, TypeScript, Tailwind 4. No ESLint and no Prettier: `vue-tsc` is the
-only gate, so run `pnpm build` before you call something done.
-
-## What's in it
-
-The rail on the left switches between three views. **Customise** offers 8 body
-shapes, 12 colours and 16 rest expressions, kept between visits. **Animations** is
-a small editor: arrange states into a timeline, set how long each is held, save the
-result. **Settings** holds the language (French, English or Chinese) and the
-credits.
-
-Anything on screen can be exported: the avatar as SVG, PNG or an animated GIF, and
-a whole timeline as GIF or MP4. The still formats need no library at all, and the
-video encoder is only fetched the first time you ask for one.
-
-Two URLs are worth knowing:
-
-- `#planche`: the 14 states side by side, frozen. Quick visual check.
-- `#etat=orbit&stop`: opens one state directly, playback paused.
-
-![The 14 states, frozen side by side](docs/states.png)
-
-## Why the numbers look arbitrary
-
-They're measured, not chosen. The reference video was cut at 10 fps and each
-state measured off the frames: silhouettes by sub-pixel ray casting, eyes by
-capsule fitting, colours and stroke widths by direct sampling.
-
-So the constants in the code are **measurements**, and rounding them to friendlier
-values breaks the resemblance, which is the only thing this project is trying to
-get right. A few are counter-intuitive enough to be worth knowing before you
-correct anything:
-
-| What you'd assume | What the video shows |
-|---|---|
-| The eyes lean `//` | They lean `\\`, around 26° off vertical |
-| The body is a squircle | It's a perfect circle, radial deviation under 0.7% |
-| Transitions are springs | Exponential ease-outs; the body never overshoots |
-| The comet crosses the screen | The dot stays put, the trail orbits it |
-| The avatar floats at rest | It doesn't. The life is gaze drift and blinking |
-
-[docs/measurements.md](docs/measurements.md) has the rest, including how to
-regenerate the extracted profiles.
-
-## How it's put together
-
-`src/bot/` is framework-free and clock-free: `engine.sample(t)` is a pure
-function of time. Pausing, resuming, jumping to an arbitrary date and running
-tests all produce the same image, which is what makes the frozen state board and
-the DOM-less test suite possible.
-
-| | |
-|---|---|
-| [docs/architecture.md](docs/architecture.md) | The engine, radial-profile morphing, eyes as mask holes |
-| [docs/measurements.md](docs/measurements.md) | What was measured, and regenerating `profiles.ts` |
-| [docs/intro.md](docs/intro.md) | The arrival sequence, and why it only plays one state |
-| [docs/interface.md](docs/interface.md) | Layout, the three-column scene, CSS traps |
-| [docs/export.md](docs/export.md) | Exporting to SVG, PNG, GIF and MP4 |
-| [docs/i18n.md](docs/i18n.md) | The hand-rolled translation layer |
-
-## Using the component
-
-```vue
-<BloubBot v-model:block="block" v-model:state="state" v-model:playing="playing" />
-<BloubBot state="orbit" :size="120" :frozen-at="1.2" />
-```
-
-`block` is the playback cursor: a montage can play the same state twice, so the
-index is what identifies where you are; `state` follows it as an output. Pass
-`frozenAt` and the component renders one exact frame with no animation loop, which
-is how the thumbnails and the state board are drawn.
-
-Props: `size`, `shape`, `color`, `expression`, `paper`, `frozenAt`, `cycle`,
-`follow`, `gaze`. Models: `block`, `state`, `playing`, `elapsed`. See
-[BloubBot.vue](src/components/BloubBot.vue) for the details.
-
-## Changes
-
-[CHANGELOG.md](CHANGELOG.md), one entry per release — which is how you tell whether the
-copy you have carries a given fix.
-
-## License
-
-MIT. See [LICENSE](LICENSE).
-
-Not affiliated with, endorsed by or connected to x.ai. It recreates the visual
-behaviour of their bot avatar as an exercise; "Grok" and "x.ai" belong to their
-owners. The MIT licence covers the code in this repository, not the design it
-imitates.
+# bloub
+
+一个用 SVG 还原 x.ai 机器人头像的项目：**一个实心黑色形状**在 14 个状态之间形变，**两个白色形状**作为眼睛、各自独立形变，背景为纯色。不依赖任何动画库。
+
+![头像经历 idle、wink、orbit 和 burst](docs/demo.gif)
+
+## 介绍
+
+bloub 是一个框架无关的头像引擎，为 **Vue 3** 和 **React 18+** 提供了一等公民的适配器。整套东西由一个共享内核（`src/bot/` + `src/core/`）驱动，因此两个框架渲染出的画面像素级一致，也永远不会互相漂移。
+
+| | Vue 3 | React 18+ |
+|---|---|---|
+| 入口 | `bloub-to-vue-and-react` | `bloub-to-vue-and-react/react` |
+| 组件 | `BloubBot` | `BloubBot` |
+| Props | `size shape color expression paper frozenAt cycle follow gaze ariaLabel` | 相同 |
+| Models | `block state playing elapsed`（通过 `v-model`） | `block state playing`（受控）+ `elapsed`（输出） |
+| 命令式 | `seek` `rendAt` | `seek` `rendAt`（通过 `ref`） |
+
+## 安装
+
+```bash
+pnpm add bloub-to-vue-and-react
+```
+
+`vue` 是 peer 依赖。`react` 和 `react-dom` 是**可选** peer 依赖：只有使用 React 适配器时才需要安装。纯 Vue 项目永远不会把 React 拉进来，反之亦然。
+
+```bash
+# React 用户
+pnpm add bloub-to-vue-and-react react react-dom
+```
+
+## 使用
+
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { BloubBot } from 'bloub-to-vue-and-react'
+
+const block = ref(0)
+const state = ref('idle')
+const playing = ref(false)
+</script>
+
+<template>
+  <BloubBot v-model:block="block" v-model:state="state" v-model:playing="playing" />
+</template>
+```
+
+`block` 是播放游标——一段蒙太奇可能两次播放同一个状态，所以用索引来标识你所在的位置；`state` 作为输出跟随它。`playing` 用于开始和停止循环播放。
+
+要渲染一帧精确画面而不启动动画循环（缩略图、状态看板），传入 `frozenAt`：
+
+```vue
+<BloubBot state="orbit" :size="120" :frozen-at="1.2" />
+```
+
+通过模板 ref 进行命令式播放：
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { BloubBot } from 'bloub-to-vue-and-react'
+
+const bot = ref<InstanceType<typeof BloubBot> | null>(null)
+bot.value?.seek(2, 0.5)   // 跳到第 2 块、0.5 秒处
+bot.value?.rendAt(3.1)    // 在绝对时间 3.1 秒处渲染蒙太奇
+</script>
+```
+
+### React 18+
+
+```tsx
+import { useRef, useState } from 'react'
+import { BloubBot, type BloubModel, type BloubBotHandle } from 'bloub-to-vue-and-react/react'
+
+function Demo() {
+  const bot = useRef<BloubBotHandle>(null)
+  const [model, setModel] = useState<BloubModel>({ block: 0, state: 'idle', playing: false, elapsed: 0 })
+
+  return (
+    <BloubBot
+      ref={bot}
+      block={model.block}
+      state={model.state}
+      playing={model.playing}
+      onModelChange={setModel}
+    />
+  )
+}
+```
+
+`block` / `state` / `playing` 是受控的；`onModelChange` 会把内核的状态回报回来，让父组件在蒙太奇推进时保持同步。`elapsed` 是只读输出。
+
+冻结单帧渲染：
+
+```tsx
+<BloubBot state="orbit" size={120} frozenAt={1.2} />
+```
+
+命令式播放：
+
+```tsx
+bot.current?.seek(2, 0.5)
+bot.current?.rendAt(3.1)
+```
+
+## 包含内容
+
+### 形状（8 种）
+
+`cercle`、`galet`、`squircle`、`capsule`、`triangle`、`hexagone`、`nuage`、`goutte`。
+
+### 颜色（12 种）
+
+`encre`、`creme`、`brun`、`rouge`、`orange`、`ambre`、`vert`、`turquoise`、`bleu`、`violet`、`rose`、`gris`。
+
+### 表情（31 个）
+
+引擎内置 19 个面部表情和 12 个视线方向。其中带嘴巴的两个（`stupefait`、`sourire`）也会绘制出嘴巴。
+
+| id | 含义 |
+|---|---|
+| `neutre` | 中性（默认） |
+| `attentif` | 专注 |
+| `surpris` | 惊讶 |
+| `excite` | 兴奋 |
+| `heureux` | 开心 |
+| `hilare` | 大笑 |
+| `colere` | 愤怒 |
+| `triste` | 悲伤 |
+| `effraye` | 害怕 |
+| `mefiant` | 狐疑 |
+| `confus` | 困惑 |
+| `curieux` | 好奇 |
+| `fier` | 得意 |
+| `timide` | 害羞 |
+| `blase` | 冷漠 |
+| `somnolent` | 困倦 |
+| `admiratif` | 钦佩 |
+| `stupefait` | 目瞪口呆（带嘴巴） |
+| `sourire` | 微笑（带嘴巴） |
+| `regardHaut` / `regardBas` | 向上看 / 向下看 |
+| `regardGauche` / `regardDroite` | 向左看 / 向右看 |
+| `regardHautGauche` / `regardHautDroite` | 左上 / 右上 |
+| `regardBasGauche` / `regardBasDroite` | 左下 / 右下 |
+| `regardArriereHaut` / `regardArriereBas` | 向后上 / 向后下 |
+| `regardArriereGauche` / `regardArriereDroite` | 向后左 / 向后右 |
+
+### 状态（14 个）
+
+`idle`、`thinking`、`wink`、`wide`、`alert`、`notify`、`exclaim`、`sleep`、`egg`、`hexagon`、`play`、`orbit`、`burst`、`comet`——另加 `swirl`，保留用于界面过渡。
+
+## 使用场景
+
+- **聊天 / 助手头像**——空闲时目光游移、眨眼，模型流式输出时进入 `thinking`，来新消息时 `notify`。
+- **响应式存在感**——用 `follow` 跟随指针，用 `gaze` 脚本编排入场序列，事件触发时 `alert` / `exclaim`。
+- **动画导出**——冻结渲染器（`frozenAt`、`rendAt`）支撑逐帧精确导出为 SVG、PNG、GIF 和 MP4。
+- **产品自定义器**——8 种形状 × 12 种颜色 × 31 个表情，持久化并作为 `cycle` 蒙太奇回放。
+
+## 体积与兼容负担
+
+内核与框架无关，因此消费方为框架特定代码付出的成本只有一层薄薄的适配器。生产构建体积：
+
+| 分块 | 原始 | gzip | 谁加载 |
+|---|---|---|---|
+| 共享内核（`src/bot/` + `src/core/`） | 46.96 kB | 14.60 kB | 所有人 |
+| Vue 适配器 | 2.80 kB | 1.21 kB | 仅 Vue |
+| React 适配器 | 2.39 kB | 1.14 kB | 仅 React |
+
+两个适配器是**相互独立的入口**，共享同一份内核分块：
+
+- 一个 Vue 应用引入 `bloub-to-vue-and-react`，加载内核 + Vue 适配器，携带 **0 字节 React 代码**——产物中不含任何 `react`、`react/jsx-runtime` 或 `react-dom` 的引入。
+- 一个 React 应用引入 `bloub-to-vue-and-react/react`，加载内核 + React 适配器，携带 **0 字节 Vue 代码**。
+- `react` / `react-dom` 是可选 peer 依赖，因此纯 Vue 项目永远不会安装 React。
+
+简而言之：约 47 kB 的内核才是真正的产品本体（形变、表情、动画）；框架税是每个适配器约 1–1.2 kB（gzip），且没有任何跨框架冗余。
+
+## 运行
+
+```bash
+pnpm install
+pnpm dev
+```
+
+然后打开 http://localhost:5190。
+
+```bash
+pnpm test      # vitest
+pnpm build     # vue-tsc --noEmit && vite build
+pnpm build:lib # 为两个入口打包并生成类型声明
+```
+
+Vue 3、Vite、TypeScript、Tailwind 4。没有 ESLint 和 Prettier：`vue-tsc` 是唯一的关卡，所以完工前请先运行 `pnpm build`。
+
+## 里面有什么
+
+左侧的导航栏在三个视图之间切换。**Customise** 提供 8 种身体形状、12 种颜色和 31 个表情，跨访问保留。**Animations** 是一个小编辑器：把状态编排进时间轴、设置每个状态停留的时长、保存结果。**Settings** 存放语言（法语、英语或中文）和致谢。
+
+屏幕上的任何东西都可以导出：头像可导出为 SVG、PNG 或动画 GIF，整条时间轴可导出为 GIF 或 MP4。静态格式完全不依赖任何库，视频编码器只在首次请求时才会按需加载。
+
+有两个值得了解的 URL：
+
+- `#planche`：14 个状态并排冻结展示，用于快速目视检查。
+- `#etat=orbit&stop`：直接打开某个状态，播放暂停。
+
+![14 个状态并排冻结展示](docs/states.png)
+
+## 为什么这些数字看起来很随意
+
+它们是测量出来的，而不是拍脑袋定的。参考视频按 10 fps 切帧，每个状态都从帧上测量出来：轮廓用亚像素射线投射，眼睛用胶囊拟合，颜色和描边宽度用直接采样。
+
+所以代码里的常量都是**测量值**，把它们四舍五入成更"顺眼"的数值会破坏相似度——而这正是本项目唯一追求的东西。有几个反直觉的点值得在改动之前了解：
+
+| 你以为的样子 | 视频里实际的样子 |
+|---|---|
+| 眼睛是 `//` 方向倾斜 | 它们是 `\\` 方向，相对竖直约倾斜 26° |
+| 身体是方圆形 | 它是完美的圆形，径向偏差低于 0.7% |
+| 过渡是弹簧动效 | 指数缓出；身体从不回弹过冲 |
+| 彗星划过屏幕 | 圆点停在原地，是拖尾绕着它转 |
+| 头像在静止时漂浮 | 并非如此，生命力来自目光游移和眨眼 |
+
+[docs/measurements.md](docs/measurements.md) 里有其余内容，包括如何重新生成提取出的轮廓。
+
+## 架构说明
+
+`src/bot/` 和 `src/core/` 与框架无关、与时钟无关：`engine.sample(t)` 是时间的纯函数。暂停、恢复、跳转到任意时间点、运行测试，都会产出同一帧画面——这正是冻结状态看板和无需 DOM 的测试套件能够实现的原因。Vue 和 React 适配器（[BloubBot.vue](src/components/Core/BloubBot.vue) 和 [BloubBot.tsx](src/components/Core/react/BloubBot.tsx)）只是包住这个内核，做的唯一事情就是转发 props 并把帧推送到 DOM。
+
+| | |
+|---|---|
+| [docs/architecture.md](docs/architecture.md) | 引擎、径向轮廓形变、作为遮罩孔洞的眼睛 |
+| [docs/measurements.md](docs/measurements.md) | 测量了什么，以及如何重新生成 `profiles.ts` |
+| [docs/intro.md](docs/intro.md) | 入场序列，以及为什么它只播放一个状态 |
+| [docs/interface.md](docs/interface.md) | 布局、三栏场景、CSS 的坑 |
+| [docs/export.md](docs/export.md) | 导出为 SVG、PNG、GIF 和 MP4 |
+| [docs/i18n.md](docs/i18n.md) | 手写的翻译层 |
+
+## 变更记录
+
+[CHANGELOG.md](CHANGELOG.md)，每个版本一条记录——这也是判断你手上的副本是否包含某个修复的方法。
+
+## 致谢
+
+bloub — 动画引擎与素材（[jeremy-prt/bloub](https://github.com/jeremy-prt/bloub)，MIT）。
+
+## 许可证
+
+MIT。见 [LICENSE](LICENSE)。

package/dist/bloub-react.js

@@ -0,0 +1,80 @@
+import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c } from "./dom-DPqMRRT2.js";
+import { forwardRef as l, useCallback as u, useEffect as d, useImperativeHandle as f, useRef as p, useSyncExternalStore as m } from "react";
+import { jsx as h } from "react/jsx-runtime";
+//#region src/components/Core/react/BloubBot.tsx
+var g = "#f9f9f9", _ = "Animated bloub avatar", v = e().blocks;
+function y(e) {
+	return a.get(e)?.hex ?? "#0a0a0c";
+}
+var b = l(function(e, a) {
+	let { size: l = 320, shape: b = t, color: x = s, expression: S = r, paper: C = g, frozenAt: w, cycle: T = v, follow: E = !1, gaze: D = null, ariaLabel: O = _, block: k, state: A, playing: j, onModelChange: M } = e, N = p(null);
+	N.current === null && (N.current = new n({
+		shape: b,
+		expression: S,
+		cycle: T,
+		follow: E,
+		gaze: D,
+		frozenAt: w,
+		block: k ?? 0,
+		state: A ?? "idle",
+		playing: j ?? !1,
+		elapsed: 0
+	}));
+	let P = N.current, F = p(C), I = p(y(x)), L = p(null), R = p(M), z = u(() => {
+		let e = L.current;
+		e && c(e, o(P.frame, {
+			paper: F.current,
+			ink: I.current,
+			uid: P.uid
+		}));
+	}, [P]), B = u((e) => P.subscribe(e), [P]), V = m(B, () => P.modelSnapshot);
+	d(() => {
+		let e = P.subscribeFrame(z);
+		return z(), e;
+	}, [P, z]), d(() => (P.setRectProvider(() => L.current?.getBoundingClientRect() ?? null), P.start(), () => P.stop()), [P]), d(() => {
+		F.current = C, z();
+	}, [C, z]), d(() => {
+		I.current = y(x), z();
+	}, [x, z]), d(() => {
+		k !== void 0 && k !== P.block && P.setBlock(k);
+	}, [k, P]), d(() => {
+		A !== void 0 && A !== P.state && P.setState(A);
+	}, [A, P]), d(() => {
+		j !== void 0 && j !== P.playing && P.setPlaying(j);
+	}, [j, P]), d(() => {
+		P.setShape(b);
+	}, [b, P]), d(() => {
+		P.setExpression(S);
+	}, [S, P]), d(() => {
+		P.setCycle(T);
+	}, [T, P]), d(() => {
+		P.setFrozenAt(w);
+	}, [w, P]), d(() => {
+		P.setFollow(E);
+	}, [E, P]), d(() => {
+		P.setGaze(D);
+	}, [D, P]), d(() => {
+		R.current = M;
+	}, [M]);
+	let H = p(0);
+	return d(() => {
+		H.current !== V && (H.current = V, R.current?.({
+			block: P.block,
+			state: P.state,
+			playing: P.playing,
+			elapsed: P.elapsed
+		}));
+	}, [V, P]), f(a, () => ({
+		seek: (e, t = 0) => P.seek(e, t),
+		rendAt: (e) => P.rendAt(e)
+	}), [P]), /* @__PURE__ */ h("svg", {
+		ref: L,
+		width: l,
+		height: l,
+		viewBox: i,
+		role: "img",
+		"aria-label": O
+	});
+});
+//#endregion
+export { b as BloubBot };

package/dist/bloub-vue.js

@@ -0,0 +1,96 @@
+import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c } from "./dom-DPqMRRT2.js";
+import { computed as l, createElementBlock as u, defineComponent as d, mergeModels as f, onBeforeUnmount as p, onMounted as m, openBlock as h, ref as g, unref as _, useModel as v, watch as y } from "vue";
+//#region src/components/Core/BloubBot.vue?vue&type=script&setup=true&lang.ts
+var b = [
+	"width",
+	"height",
+	"viewBox",
+	"aria-label"
+], x = /* @__PURE__ */ d({
+	__name: "BloubBot",
+	props: /*@__PURE__*/ f({
+		size: { default: 320 },
+		shape: { default: t },
+		color: { default: s },
+		expression: { default: r },
+		paper: { default: "#f9f9f9" },
+		frozenAt: { default: void 0 },
+		cycle: { default: () => e().blocks },
+		follow: {
+			type: Boolean,
+			default: !1
+		},
+		gaze: {
+			type: [Function, null],
+			default: null
+		},
+		ariaLabel: { default: "Animated bloub avatar" }
+	}, {
+		block: { default: 0 },
+		blockModifiers: {},
+		state: { default: "idle" },
+		stateModifiers: {},
+		playing: {
+			type: Boolean,
+			default: !1
+		},
+		playingModifiers: {},
+		elapsed: { default: 0 },
+		elapsedModifiers: {}
+	}),
+	emits: [
+		"update:block",
+		"update:state",
+		"update:playing",
+		"update:elapsed"
+	],
+	setup(e, { expose: t }) {
+		let r = e, s = v(e, "block"), d = v(e, "state"), f = v(e, "playing"), x = v(e, "elapsed"), S = l(() => a.get(r.color)?.hex ?? "#0a0a0c"), C = new n({
+			shape: r.shape,
+			expression: r.expression,
+			cycle: r.cycle,
+			follow: r.follow,
+			gaze: r.gaze,
+			frozenAt: r.frozenAt,
+			block: s.value,
+			state: d.value,
+			playing: f.value,
+			elapsed: x.value
+		}), w = g(null);
+		function T() {
+			let e = w.value;
+			e && c(e, o(C.frame, {
+				paper: r.paper,
+				ink: S.value,
+				uid: C.uid
+			}));
+		}
+		let E = !1;
+		return C.subscribe(() => {
+			E = !0, s.value = C.block, d.value = C.state, f.value = C.playing, x.value = C.elapsed, E = !1, T();
+		}), y(s, (e) => {
+			E || C.setBlock(e);
+		}, { flush: "sync" }), y(d, (e) => {
+			E || C.setState(e);
+		}, { flush: "sync" }), y(f, (e) => {
+			E || C.setPlaying(e);
+		}, { flush: "sync" }), y(() => r.shape, (e) => C.setShape(e)), y(() => r.expression, (e) => C.setExpression(e)), y(() => r.cycle, (e) => C.setCycle(e)), y(() => r.frozenAt, (e) => C.setFrozenAt(e)), y(() => r.follow, (e) => C.setFollow(e)), y(() => r.gaze, (e) => C.setGaze(e)), y([() => r.paper, S], () => T()), t({
+			seek: (e, t = 0) => C.seek(e, t),
+			rendAt: (e) => C.rendAt(e)
+		}), m(() => {
+			C.setRectProvider(() => w.value?.getBoundingClientRect() ?? null), T(), C.start();
+		}), p(() => {
+			C.stop();
+		}), (e, t) => (h(), u("svg", {
+			ref_key: "svg",
+			ref: w,
+			width: r.size,
+			height: r.size,
+			viewBox: _(i),
+			role: "img",
+			"aria-label": r.ariaLabel
+		}, null, 8, b));
+	}
+});
+//#endregion
+export { x as BloubBot };