better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/creative/creative-popular-web-designs.md

@@ -0,0 +1,211 @@
+---
+title: "流行网页设计 — 54 个真实设计系统（Stripe、Linear、Vercel）的 HTML/CSS"
+sidebar_label: "流行网页设计"
+description: "54 个真实设计系统（Stripe、Linear、Vercel）的 HTML/CSS"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# 流行网页设计
+
+54 个真实设计系统（Stripe、Linear、Vercel）的 HTML/CSS。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/creative/popular-web-designs` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent + Teknium（设计系统来源：VoltAgent/awesome-design-md） |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# 流行网页设计
+
+54 个可直接用于生成 HTML/CSS 的真实设计系统。每个模板都完整呈现了某个网站的视觉语言：色彩调色板、排版层级、组件样式、间距系统、阴影、响应式行为，以及包含精确 CSS 值的实用 agent prompt（提示词）。
+
+## 相关设计 skill
+
+- **`claude-design`** — 用于设计*流程与品味*（梳理需求、生成变体、验证本地 HTML 产物、避免 AI 设计陷阱）。当用户希望按照某个已知品牌风格设计页面时，可与本 skill 配合使用：`claude-design` 驱动工作流，本 skill 提供视觉词汇。
+- **`design-md`** — 当交付物是正式的 DESIGN.md token（设计令牌）规范文件而非渲染产物时使用。
+
+## 使用方法
+
+1. 从下方目录中选择一个设计
+2. 加载它：`skill_view(name="popular-web-designs", file_path="templates/<site>.md")`
+3. 生成 HTML 时使用设计 token 和组件规范
+4. 配合 `generative-widgets` skill，通过 cloudflared tunnel 提供服务
+
+每个模板顶部都包含一个 **Hermes 实现说明** 块，内容包括：
+- CDN 字体替代方案及 Google Fonts `<link>` 标签（可直接粘贴）
+- 主字体和等宽字体的 CSS font-family 栈
+- 提醒使用 `write_file` 创建 HTML 文件，使用 `browser_vision` 进行验证
+
+## HTML 生成模式
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Page Title</title>
+  <!-- Paste the Google Fonts <link> from the template's Hermes notes -->
+  <link href="https://fonts.googleapis.com/css2?family=..." rel="stylesheet">
+  <style>
+    /* Apply the template's color palette as CSS custom properties */
+    :root {
+      --color-bg: #ffffff;
+      --color-text: #171717;
+      --color-accent: #533afd;
+      /* ... more from template Section 2 */
+    }
+    /* Apply typography from template Section 3 */
+    body {
+      font-family: 'Inter', system-ui, sans-serif;
+      color: var(--color-text);
+      background: var(--color-bg);
+    }
+    /* Apply component styles from template Section 4 */
+    /* Apply layout from template Section 5 */
+    /* Apply shadows from template Section 6 */
+  </style>
+</head>
+<body>
+  <!-- Build using component specs from the template -->
+</body>
+</html>
+```
+
+使用 `write_file` 写入文件，通过 `generative-widgets` 工作流（cloudflared tunnel）提供服务，并使用 `browser_vision` 验证结果以确认视觉准确性。
+
+## 字体替代参考
+
+大多数网站使用无法通过 CDN 获取的专有字体。每个模板都映射到一个 Google Fonts 替代字体，以保留设计的整体风格。常见映射关系：
+
+| 专有字体 | CDN 替代字体 | 风格特征 |
+|---|---|---|
+| Geist / Geist Sans | Geist（Google Fonts 上可用） | 几何感，字距紧凑 |
+| Geist Mono | Geist Mono（Google Fonts 上可用） | 简洁等宽，支持连字 |
+| sohne-var (Stripe) | Source Sans 3 | 轻字重优雅感 |
+| Berkeley Mono | JetBrains Mono | 技术感等宽字体 |
+| Airbnb Cereal VF | DM Sans | 圆润、友好的几何风格 |
+| Circular (Spotify) | DM Sans | 几何感，温暖 |
+| figmaSans | Inter | 简洁人文主义风格 |
+| Pin Sans (Pinterest) | DM Sans | 友好，圆润 |
+| NVIDIA-EMEA | Inter（或 Arial 系统字体） | 工业感，简洁 |
+| CoinbaseDisplay/Sans | DM Sans | 几何感，值得信赖 |
+| UberMove | DM Sans | 粗犷，紧凑 |
+| HashiCorp Sans | Inter | 企业级，中性 |
+| waldenburgNormal (Sanity) | Space Grotesk | 几何感，略微压缩 |
+| IBM Plex Sans/Mono | IBM Plex Sans/Mono | Google Fonts 上可用 |
+| Rubik (Sentry) | Rubik | Google Fonts 上可用 |
+
+当模板的 CDN 字体与原始字体一致时（Inter、IBM Plex、Rubik、Geist），不存在替代损失。当使用替代字体时（如用 DM Sans 替代 Circular，用 Source Sans 3 替代 sohne-var），请严格遵循模板中的字重、字号和字距值——这些参数承载的视觉识别度往往高于字体本身。
+
+## 设计目录
+
+### AI 与机器学习
+
+| 模板 | 网站 | 风格 |
+|---|---|---|
+| `claude.md` | Anthropic Claude | 暖赤陶色强调色，简洁编辑排版 |
+| `cohere.md` | Cohere | 鲜艳渐变，数据丰富的仪表盘美学 |
+| `elevenlabs.md` | ElevenLabs | 暗色电影感 UI，音频波形美学 |
+| `minimax.md` | Minimax | 带霓虹强调色的粗犷暗色界面 |
+| `mistral.ai.md` | Mistral AI | 法式工程极简主义，紫色调 |
+| `ollama.md` | Ollama | 终端优先，单色简约 |
+| `opencode.ai.md` | OpenCode AI | 开发者向暗色主题，全等宽字体 |
+| `replicate.md` | Replicate | 干净白色画布，代码优先 |
+| `runwayml.md` | RunwayML | 电影感暗色 UI，媒体丰富布局 |
+| `together.ai.md` | Together AI | 技术感，蓝图风格设计 |
+| `voltagent.md` | VoltAgent | 纯黑画布，翠绿强调色，终端原生 |
+| `x.ai.md` | xAI | 极简单色，未来主义，全等宽字体 |
+
+### 开发者工具与平台
+
+| 模板 | 网站 | 风格 |
+|---|---|---|
+| `cursor.md` | Cursor | 流畅暗色界面，渐变强调色 |
+| `expo.md` | Expo | 暗色主题，紧凑字距，代码中心 |
+| `linear.app.md` | Linear | 极简暗色模式，精准，紫色强调色 |
+| `lovable.md` | Lovable | 活泼渐变，友好开发者美学 |
+| `mintlify.md` | Mintlify | 简洁，绿色强调，阅读优化 |
+| `posthog.md` | PostHog | 活泼品牌，开发者友好暗色 UI |
+| `raycast.md` | Raycast | 流畅暗色外壳，鲜艳渐变强调色 |
+| `resend.md` | Resend | 极简暗色主题，等宽字体强调 |
+| `sentry.md` | Sentry | 暗色仪表盘，数据密集，粉紫强调色 |
+| `supabase.md` | Supabase | 暗色翠绿主题，代码优先开发工具 |
+| `superhuman.md` | Superhuman | 高端暗色 UI，键盘优先，紫色光晕 |
+| `vercel.md` | Vercel | 黑白精准，Geist 字体系统 |
+| `warp.md` | Warp | 暗色 IDE 风界面，块式命令 UI |
+| `zapier.md` | Zapier | 暖橙色，友好插图驱动 |
+
+### 基础设施与云
+
+| 模板 | 网站 | 风格 |
+|---|---|---|
+| `clickhouse.md` | ClickHouse | 黄色强调，技术文档风格 |
+| `composio.md` | Composio | 现代暗色，彩色集成图标 |
+| `hashicorp.md` | HashiCorp | 企业级简洁，黑白配色 |
+| `mongodb.md` | MongoDB | 绿叶品牌，开发者文档焦点 |
+| `sanity.md` | Sanity | 红色强调，内容优先编辑布局 |
+| `stripe.md` | Stripe | 标志性紫色渐变，300 字重优雅感 |
+
+### 设计与生产力
+
+| 模板 | 网站 | 风格 |
+|---|---|---|
+| `airtable.md` | Airtable | 多彩，友好，结构化数据美学 |
+| `cal.md` | Cal.com | 简洁中性 UI，开发者向简约 |
+| `clay.md` | Clay | 有机形状，柔和渐变，艺术指导布局 |
+| `figma.md` | Figma | 鲜艳多色，活泼而专业 |
+| `framer.md` | Framer | 粗犷黑蓝，动效优先，设计前沿 |
+| `intercom.md` | Intercom | 友好蓝色调，对话式 UI 模式 |
+| `miro.md` | Miro | 亮黄强调色，无限画布美学 |
+| `notion.md` | Notion | 温暖极简，衬线标题，柔和表面 |
+| `pinterest.md` | Pinterest | 红色强调，瀑布流网格，图片优先布局 |
+| `webflow.md` | Webflow | 蓝色强调，精致营销站美学 |
+
+### 金融科技与加密货币
+
+| 模板 | 网站 | 风格 |
+|---|---|---|
+| `coinbase.md` | Coinbase | 简洁蓝色标识，信任导向，机构感 |
+| `kraken.md` | Kraken | 紫色强调暗色 UI，数据密集仪表盘 |
+| `revolut.md` | Revolut | 流畅暗色界面，渐变卡片，金融科技精准感 |
+| `wise.md` | Wise | 亮绿强调色，友好清晰 |
+
+### 企业与消费者
+
+| 模板 | 网站 | 风格 |
+|---|---|---|
+| `airbnb.md` | Airbnb | 暖珊瑚强调色，摄影驱动，圆润 UI |
+| `apple.md` | Apple | 高端留白，SF Pro，电影感图像 |
+| `bmw.md` | BMW | 暗色高端表面，精准工程美学 |
+| `ibm.md` | IBM | Carbon 设计系统，结构化蓝色调色板 |
+| `nvidia.md` | NVIDIA | 绿黑能量感，技术力量美学 |
+| `spacex.md` | SpaceX | 极简黑白，全出血图像，未来主义 |
+| `spotify.md` | Spotify | 暗底鲜绿，粗犷字体，专辑封面驱动 |
+| `uber.md` | Uber | 粗犷黑白，紧凑字体，都市能量 |
+
+## 选择设计
+
+根据内容匹配设计：
+
+- **开发者工具 / 仪表盘：** Linear、Vercel、Supabase、Raycast、Sentry
+- **文档 / 内容站点：** Mintlify、Notion、Sanity、MongoDB
+- **营销 / 落地页：** Stripe、Framer、Apple、SpaceX
+- **暗色模式 UI：** Linear、Cursor、ElevenLabs、Warp、Superhuman
+- **浅色 / 简洁 UI：** Vercel、Stripe、Notion、Cal.com、Replicate
+- **活泼 / 友好：** PostHog、Figma、Lovable、Zapier、Miro
+- **高端 / 奢华：** Apple、BMW、Stripe、Superhuman、Revolut
+- **数据密集 / 仪表盘：** Sentry、Kraken、Cohere、ClickHouse
+- **等宽 / 终端美学：** Ollama、OpenCode、x.ai、VoltAgent

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/creative/creative-pretext.md

@@ -0,0 +1,238 @@
+---
+title: "Pretext"
+sidebar_label: "Pretext"
+description: "适用于使用 @chenglou/pretext 构建创意浏览器演示 —— 无 DOM 文本布局，用于 ASCII 艺术、排版绕障流动、文字即几何游戏、动态排版及文字驱动的生成艺术。"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Pretext
+
+适用于使用 @chenglou/pretext 构建创意浏览器演示 —— 无 DOM 文本布局，用于 ASCII 艺术、排版绕障流动、文字即几何游戏、动态排版及文字驱动的生成艺术。默认生成单文件 HTML 演示。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/creative/pretext` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `creative-coding`, `typography`, `pretext`, `ascii-art`, `canvas`, `generative`, `text-layout`, `kinetic-typography` |
+| 相关 skill | [`p5js`](/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Pretext 创意演示
+
+## 概述
+
+[`@chenglou/pretext`](https://github.com/chenglou/pretext) 是由 Cheng Lou（React 核心团队、ReasonML、Midjourney）开发的 15KB 零依赖 TypeScript 库，用于**无 DOM 多行文本测量与布局**。它只做一件事：给定 `(text, font, width)`，返回换行位置、每行宽度、每个字形（grapheme）的坐标以及总高度 —— 全部通过 canvas 测量完成，无需触发重排（reflow）。
+
+听起来像底层管道，但并非如此。由于它快速且几何化，它是一个**创意原语**：你可以在 60fps 下让段落绕着移动的精灵重排，构建关卡几何体由真实文字组成的游戏，将 ASCII logo 嵌入散文，利用精确的每字形起始坐标将文字炸裂成粒子，或者在不调用任何 `getBoundingClientRect` 的情况下打包紧凑的多行 UI。
+
+此 skill 的存在是为了让 Hermes 能用它制作**酷炫演示** —— 那种人们会发到 X 上的作品。社区演示库请见 `pretext.cool` 和 `chenglou.me/pretext`。
+
+## 使用时机
+
+当用户要求以下内容时使用：
+- "pretext 演示" / "酷炫的 pretext 作品" / "文字即 X"
+- 文字绕移动形状流动（hero 区块、编辑排版、动态长文页面）
+- 使用**真实文字或散文**（而非等宽字符光栅）的 ASCII 艺术效果
+- 游戏场地 / 障碍物 / 砖块由文字构成的游戏（字母版俄罗斯方块、散文版打砖块）
+- 带有每字形物理效果的动态排版（碎裂、散射、群集、流动）
+- 排版生成艺术，尤其是非拉丁文字或混合文字
+- 多行"紧缩包裹"UI（能容纳文字的最小容器宽度）
+- 任何需要在渲染**前**知道换行位置的场景
+
+不适用于：
+- CSS 已能解决布局的静态 SVG/HTML 页面 —— 直接用 CSS
+- 富文本编辑器、通用内联格式化引擎（pretext 有意保持功能单一）
+- 图片转文字（使用 `ascii-art` / `ascii-video` skill）
+- 文字不起核心作用的纯 canvas 生成艺术 —— 使用 `p5js`
+
+## 创意标准
+
+这是在浏览器中渲染的视觉艺术。Pretext 返回数字；**你**来绘制内容。
+
+- **不要交付"hello world"演示。** `hello-orb-flow.html` 模板只是*起点*。每个交付的演示都必须加入有意为之的色彩、动效、构图，以及一个用户没有要求但会欣赏的视觉细节。
+- **深色背景、暖色核心、精心调配的色板。** 经典的琥珀色配黑色（CRT / 终端风）可行，冷白配炭灰（编辑风）和去饱和粉彩（risograph 风）同样可行。选定一种并坚持到底。
+- **比例字体才是重点。** Pretext 的核心魅力在于"非等宽" —— 充分利用这一点。使用 Iowan Old Style、Inter、JetBrains Mono、Helvetica Neue 或可变字体。绝不使用默认无衬线字体。
+- **使用真实语料，而非 lorem ipsum。** 语料库应有意义。短篇宣言、诗歌、真实源代码、发现的文本、库自身的 README —— 绝不用 `lorem ipsum`。
+- **首帧即精品。** 无加载状态，无空白帧。演示打开的瞬间就必须达到可发布水准。
+
+## 技术栈
+
+每个演示为单个自包含 HTML 文件，无需构建步骤。
+
+| 层级 | 工具 | 用途 |
+|-------|------|---------|
+| 核心 | `@chenglou/pretext`（通过 `esm.sh` CDN） | 文本测量 + 行布局 |
+| 渲染 | HTML5 Canvas 2D | 字形渲染、逐帧合成 |
+| 分割 | `Intl.Segmenter`（内置） | emoji / CJK / 组合字符的字形拆分 |
+| 交互 | 原生 DOM 事件 | 鼠标 / 触摸 / 滚轮 —— 无框架 |
+
+```html
+<script type="module">
+import {
+  prepare, layout,                   // use-case 1: simple height
+  prepareWithSegments, layoutWithLines,  // use-case 2a: fixed-width lines
+  layoutNextLineRange, materializeLineRange, // use-case 2b: streaming / variable width
+  measureLineStats, walkLineRanges,  // stats without string allocation
+} from "https://esm.sh/@chenglou/pretext@0.0.6";
+</script>
+```
+
+锁定版本。撰写时为 `@0.0.6` —— 如演示行为异常，请在 [npm](https://www.npmjs.com/package/@chenglou/pretext) 查看最新版本。
+
+## 两种使用场景
+
+几乎所有需求都归结为以下两种形态之一。两种都要掌握。
+
+### 场景 1 —— 测量，然后用 CSS/DOM 渲染
+
+```js
+const prepared = prepare(text, "16px Inter");
+const { height, lineCount } = layout(prepared, 320, 20);
+```
+
+浏览器仍负责绘制文字。Pretext 只告诉你在给定宽度下文本框的高度，**无需**读取 DOM。适用于：
+- 包含换行文字的虚拟列表行高计算
+- 需要精确卡片高度的瀑布流布局
+- "这个标签放得下吗？"的开发时检查
+- 防止远程文字加载时的布局偏移
+
+**保持 `font` 和 `letterSpacing` 与 CSS 完全同步。** canvas 的 `ctx.font` 格式（如 `"16px Inter"`、`"500 17px 'JetBrains Mono'"`）必须与渲染 CSS 一致，否则测量结果会产生偏差。
+
+### 场景 2 —— 自行测量*并*渲染
+
+```js
+const prepared = prepareWithSegments(text, FONT);
+const { lines } = layoutWithLines(prepared, 320, 26);
+for (let i = 0; i < lines.length; i++) {
+  ctx.fillText(lines[i].text, 0, i * 26);
+}
+```
+
+创意工作就在这里。你掌控绘制，因此可以：
+- 渲染到 canvas、SVG、WebGL 或任意坐标系
+- 对每个字形应用变换（旋转、抖动、缩放、透明度）
+- 将行元数据（宽度、字形坐标）用作几何数据
+
+对于**每行宽度可变**的流动排版（文字绕形状流动、文字在环形带内、文字在非矩形列中）：
+
+```js
+let cursor = { segmentIndex: 0, graphemeIndex: 0 };
+let y = 0;
+while (true) {
+  const lineWidth = widthAtY(y);  // your function: how wide is the corridor at this y?
+  const range = layoutNextLineRange(prepared, cursor, lineWidth);
+  if (!range) break;
+  const line = materializeLineRange(prepared, range);
+  ctx.fillText(line.text, leftEdgeAtY(y), y);
+  cursor = range.end;
+  y += lineHeight;
+}
+```
+
+这是整个库中最重要的模式。它解锁了"文字绕拖拽精灵流动"的效果 —— 那个在 X 上病毒式传播的演示。
+
+### 值得了解的辅助函数
+
+- `measureLineStats(prepared, maxWidth)` → `{ lineCount, maxLineWidth }` —— 最宽的行，即多行紧缩包裹宽度。
+- `walkLineRanges(prepared, maxWidth, callback)` —— 无字符串分配地遍历各行。在不需要字符内容时用于统计/物理计算。
+- `@chenglou/pretext/rich-inline` —— 同一系统，但支持混合字体 / 标签 / 提及的段落。从子路径导入。
+
+## 演示配方模式
+
+社区语料库（见 `references/patterns.md`）归纳为几种强力模式。选一种进行变奏 —— 除非被要求，否则不要发明新类别。
+
+| 模式 | 核心 API | 示例创意 |
+|---|---|---|
+| **绕障重排** | `layoutNextLineRange` + 逐行宽度函数 | 编辑排版段落，绕拖拽光标精灵分开 |
+| **文字即几何游戏** | `layoutWithLines` + 逐行碰撞矩形 | 每块砖都是一个测量过的单词的打砖块游戏 |
+| **碎裂 / 粒子** | `walkLineRanges` → 每字形 (x,y) → 物理 | 点击时句子炸裂成字母 |
+| **ASCII 障碍排版** | `layoutNextLineRange` + 逐行障碍区间测量 | 位图 ASCII logo、形态变换，以及可拖拽的线框物体，使文字绕其实际几何形状展开 |
+| **编辑多栏** | 每栏 `layoutNextLineRange` + 共享游标 | 带引用块的动态杂志版面 |
+| **动态排版** | `layoutWithLines` + 逐行随时间变换 | 星球大战字幕滚动、波浪、弹跳、故障效果 |
+| **多行紧缩包裹** | `measureLineStats` | 自动适配最紧凑容器的引用卡片 |
+
+可参考 `templates/donut-orbit.html` 和 `templates/hello-orb-flow.html` 中可运行的单文件起始模板。
+
+## 工作流程
+
+1. **根据用户需求从上表选择一种模式。**
+2. **从模板开始**：
+   - `templates/hello-orb-flow.html` —— 文字绕移动球体重排（绕障重排模式）
+   - `templates/donut-orbit.html` —— 进阶示例：测量 ASCII logo 障碍物、可拖拽线框球体/立方体、变形形状场、可选 DOM 文字及仅开发模式控件
+   - 用 `write_file` 将新 `.html` 写入 `/tmp/` 或用户工作区。
+3. **将语料库替换为**与需求相关的有意义内容。真实散文，10-100 句，不用 lorem。
+4. **调整美学** —— 字体、色板、构图、交互。这才是核心工作，不要跳过。
+5. **本地验证**：
+   ```sh
+   cd <dir-with-html> && python3 -m http.server 8765
+   # then open http://localhost:8765/<file>.html
+   ```
+6. **检查控制台** —— 若 `prepareWithSegments` 传入错误的字体字符串，pretext 会抛出异常；`Intl.Segmenter` 在所有现代浏览器中均可用。
+7. **向用户展示文件路径**，而非仅展示代码 —— 他们想直接打开文件。
+
+## 性能说明
+
+- `prepare()` / `prepareWithSegments()` 是开销较大的调用。每个文字+字体组合只调用**一次**，缓存句柄。
+- 窗口大小改变时，只重新运行 `layout()` / `layoutWithLines()` —— 绝不重新 prepare。
+- 对于文字内容不变但几何形状变化的逐帧动画，在紧密循环中调用 `layoutNextLineRange` 对普通长度的段落来说足够在 60fps 下每帧执行。
+- 逐帧渲染 ASCII 遮罩时，维护一个单元格缓冲区（`Uint8Array` / 类型化数组），从单元格或投影几何体推导每行障碍区间，合并区间，再将这些区间传入 `layoutNextLineRange` 后绘制文字。
+- 保持视觉动画与布局动画同步。若球体变形为立方体，用同一个值对渲染单元格缓冲区和障碍区间同时做补间；否则演示看起来像贴图而非物理重排。
+- 淡入淡出效果优先使用图层透明度，而非改变字形强度或障碍物缩放。将瞬态 ASCII 精灵放在独立 canvas 上，用 CSS/GSAP 的 opacity 淡化该 canvas，避免几何形状看起来在缩小。
+- Canvas 的 `ctx.font` 设置出人意料地慢；若字体在帧内不变，每帧只设置**一次**，而非每次 `fillText` 调用都设置。
+
+## 常见陷阱
+
+1. **CSS 与 canvas 字体字符串不一致。** `ctx.font = "16px Inter"` 用于测量，但 CSS 写的是 `font-family: Inter, sans-serif; font-size: 16px`。如果 Inter 加载成功则没问题。若 Inter 404，CSS 会回退到 sans-serif，测量结果偏差 5-20%。始终 `preload` 字体，或使用 web 安全字体族。
+
+2. **在动画循环内重复 prepare。** 只有 `layout*` 是廉价的。每帧调用 `prepare` 会严重拖慢性能。将 prepared 句柄保存在模块作用域中。
+
+3. **忘记用 `Intl.Segmenter` 拆分字形。** Emoji、组合字符、CJK —— `"é".split("")` 会给出两个字符。在采样单个可见字形时，使用 `new Intl.Segmenter(undefined, { granularity: "grapheme" })`。
+
+4. **`break: 'never'` 标签缺少 `extraWidth`。** 在 `rich-inline` 中，若对原子标签/提及使用 `break: 'never'`，还必须提供 `extraWidth` 用于标签内边距 —— 否则标签外框会溢出容器。
+
+5. **从 `unpkg` 使用 `@chenglou/pretext` 时遇到 TypeScript 专属入口。** 使用 `esm.sh` —— 它会自动将 TS 导出编译为浏览器可用的 ESM。`unpkg` 会 404 或返回原始 TS。
+
+6. **等宽字体回退悄悄抹杀了整个意义。** 用户看到等宽输出，通常是因为 CSS `font-family` 回退到了 `monospace`。通过 DevTools 验证实际渲染字体。
+
+7. **绕形状流动时跳过行而非调整宽度。** 若当前行的通道太窄无法容纳一行，应*跳过该行*（`y += lineHeight; continue;`），而非向 `layoutNextLineRange` 传入极小的 maxWidth —— pretext 会返回单字形行，看起来很破碎。
+
+8. **交付冷启动演示。** 默认首帧看起来像教程级别。请添加：暗角、细微扫描线、空闲自动动效、一个精心选择的交互响应（拖拽、悬停、滚动、点击）。缺少这些，"酷炫 pretext 演示"就会沦为"README 复现"。
+
+## 验证清单
+
+- [ ] 演示是单个自包含 `.html` 文件 —— 双击或 `python3 -m http.server` 即可打开
+- [ ] `@chenglou/pretext` 通过 `esm.sh` 导入并锁定版本
+- [ ] 语料库为真实散文，非 lorem ipsum，且与演示概念匹配
+- [ ] 传入 `prepare` 的字体字符串与 CSS 字体完全一致
+- [ ] `prepare()` / `prepareWithSegments()` 只调用一次，不在每帧调用
+- [ ] 深色背景 + 精心调配的色板 —— 非默认白色 canvas
+- [ ] 至少一种交互响应（拖拽 / 悬停 / 滚动 / 点击）或空闲自动动效
+- [ ] 已用 `python3 -m http.server` 本地测试，确认无控制台报错
+- [ ] 在中端笔记本上达到 60fps（或已记录优雅降级方案）
+- [ ] 一个用户未要求的"超额"细节
+
+## 参考：社区演示
+
+克隆以下项目获取灵感 / 模式（均为 MIT 类许可，链接来自 [pretext.cool](https://www.pretext.cool/)）：
+
+- **Pretext Breaker** —— 单词砖块打砖块 —— `github.com/rinesh/pretext-breaker`
+- **Tetris × Pretext** —— `github.com/shinichimochizuki/tetris-pretext`
+- **Dragon animation** —— `github.com/qtakmalay/PreTextExperiments`
+- **Somnai editorial engine** —— `github.com/somnai-dreams/pretext-demos`
+- **Bad Apple!! ASCII** —— `github.com/frmlinn/bad-apple-pretext`
+- **Drag-sprite reflow** —— `github.com/dokobot/pretext-demo`
+- **Alarmy editorial clock** —— `github.com/SmisLee/alarmy-pretext-demo`
+
+官方演示场：[chenglou.me/pretext](https://chenglou.me/pretext/) —— 手风琴、气泡、动态布局、编辑引擎、对齐比较、瀑布流、Markdown 聊天、富文本笔记。