@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/popular-web-designs/templates/zapier.md

@@ -0,0 +1,341 @@
+# Design System: Zapier
+
+
+> **Hermes Agent — 实现说明**
+>
+> 原始站点使用专有字体。对于自包含的 HTML 输出，请使用这些 CDN 替代字体：
+> - **Primary:** `Inter` | **Mono:** `system monospace stack`
+> - **Font stack (CSS):** `font-family: 'Inter', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;`
+> - **Mono stack (CSS):** `font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;`
+> ```html
+> <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+> ```
+> 使用 `write_file` 创建 HTML，通过 `generative-widgets` skill（cloudflared tunnel）提供服务。
+> 生成后使用 `browser_vision` 验证视觉准确性。
+
+## 1. 视觉主题与氛围
+
+Zapier 的网站散发着温暖、平易近人的专业气质。它摒弃了开发者工具那种冰冷的极简主义单色风格，转而采用带有奶油色调的画布（`#fffefb`），给人一种如同未漂白纸张的感觉——就像是数字世界中一本井井有条的笔记本。接近黑色的（`#201515`）文字带有微弱的红棕色暖意，营造出一种比机械感更具有人情味的氛围。这种自动化设计让人感觉毫不费力，而不是充满技术感。
+
+排版系统是两种截然不同的个性之间刻意的交织。**Degular Display** —— 一种几何感强、字间距宽的展示字体 —— 以中等字重（500）和极其紧凑的行高（0.90）处理 56-80px 的大标题，创造出像堆叠方块一样在垂直方向上压缩的标题。**Inter** 作为主力字体承担了其余的所有工作，从章节标题到正文、导航，并以 Helvetica 和 Arial 作为后备字体。**GT Alpina**，一种优雅的细字重衬线字体，具有极强的负字间距（-1.6px 到 -1.92px），偶尔会在展现柔和编辑感的时刻出现。这种三字体系统赋予了 Zapier 转换语域的能力 —— 从粗犷有力的风格到简洁实用的风格，再到精致文艺的风格。
+
+品牌标志性的橙色（`#ff4f00`）是毋庸置疑的 —— 一种鲜艳、高饱和度的红橙色，恰到好处地介于交通锥的紧迫感与日落的温暖感之间。它的使用克制而果断：主要用于主要 CTA 按钮、活跃状态的下划线以及强调边框。在温暖的奶油色背景下，这种橙色营造出一种充满活力而又不具攻击性的色彩关系。
+
+**关键特征：**
+- 温暖的奶油色画布（`#fffefb`）代替纯白色 —— 自然的、纸张般的温暖感
+- 带有红色底色调的近黑色（`#201515`） —— 会呼吸而不是占据主导地位
+- Degular Display 用于行高为 0.90 的 Hero 大标题 —— 紧凑、有冲击力、现代
+- Inter 作为涵盖所有功能排版的通用 UI 字体
+- GT Alpina 用于编辑强调 —— 极细字重衬线体，带有极强的负字间距
+- Zapier 橙色（`#ff4f00`）作为唯一的强调色 —— 鲜艳、温暖、克制应用
+- 温暖的中性调色板：边框（`#c5c0b1`）、柔和的文本（`#939084`）、表面色调（`#eceae3`）
+- 基于 8px 的基础间距系统，CTA 具有宽裕的内边距（20px 24px）
+- 边框导向设计：使用暖灰色的 `1px solid` 边框代替阴影来定义结构
+
+## 2. 色彩调色板与角色
+
+### Primary
+- **Zapier Black** (`#201515`)：主要文本、标题、深色按钮背景。带有红色底色调的暖近黑色 —— 永不显得冰冷。
+- **Cream White** (`#fffefb`)：页面背景、卡片表面、浅色按钮填充。不是纯白色；偏黄的暖色调是刻意为之的。
+- **Off-White** (`#fffdf9`)：次要背景表面，微妙的交替色调。几乎与奶油白难以区分，但能创造深度。
+
+### Brand Accent
+- **Zapier Orange** (`#ff4f00`)：主要 CTA 按钮、活跃下划线指示器、强调边框。标志性颜色 —— 鲜艳且温暖。
+
+### Neutral Scale
+- **Dark Charcoal** (`#36342e`)：次要文本、页脚文本、强分割线的边框颜色。一种温暖的深灰棕色，带有 70% 透明度变体。
+- **Warm Gray** (`#939084`)：三级文本、柔和标签、时间戳样式内容。带有偏绿暖底色的中间色调。
+- **Sand** (`#c5c0b1`)：主要边框颜色、Hover 状态背景、分割线。Zapier 结构元素的骨干。
+- **Light Sand** (`#eceae3`)：次要按钮背景、浅色边框、微妙的卡片表面。
+- **Mid Warm** (`#b5b2aa`)：交替的边框色调，用于特定的 span 元素。
+
+### Interactive
+- **Orange CTA** (`#ff4f00`)：主要操作按钮和活跃标签页下划线。
+- **Dark CTA** (`#201515`)：带有 sand Hover 状态的次要深色按钮。
+- **Light CTA** (`#eceae3`)：带有 sand Hover 的三级/幽灵按钮。
+- **Link 默认** (`#201515`)：标准链接颜色，与正文文本相匹配。
+- **Hover Underline**：链接在 Hover 时移除 `text-decoration: underline`（反向模式）。
+
+### Overlay & Surface
+- **Semi-transparent Dark** (`rgba(45, 45, 46, 0.5)`)：覆盖层按钮变体、类似背景遮罩的元素。
+- **Pill Surface** (`#fffefb`)：带有 sand 边框的白色胶囊按钮。
+
+### Shadows & Depth
+- **Inset Underline** (`rgb(255, 79, 0) 0px -4px 0px 0px inset`)：活跃标签指示器 —— 使用 inset box-shadow 的橙色下划线。
+- **Hover Underline** (`rgb(197, 192, 177) 0px -4px 0px 0px inset`)：非活跃标签 Hover —— sand 色下划线。
+
+## 3. 排版规则
+
+### Font Families
+- **Display**：`Degular Display` —— 用于 Hero 大标题的宽体几何展示字面
+- **Primary**：`Inter`，后备字体：`Helvetica, Arial`
+- **Editorial**：`GT Alpina` —— 用于展现编辑感的细字重衬线字体
+- **System**：`Arial` —— 表单元素和系统 UI 的后备字体
+
+### Hierarchy
+
+| 角色 | Font | Size | Weight | Line Height | Letter Spacing | 备注 |
+|------|------|------|--------|-------------|----------------|-------|
+| Display Hero XL | Degular Display | 80px (5.00rem) | 500 | 0.90 (tight) | normal | 最大视觉冲击，压缩的区块 |
+| Display Hero | Degular Display | 56px (3.50rem) | 500 | 0.90-1.10 (tight) | 0-1.12px | 主要 Hero 大标题 |
+| Display Hero SM | Degular Display | 40px (2.50rem) | 500 | 0.90 (tight) | normal | 较小的 Hero 变体 |
+| Display Button | Degular Display | 24px (1.50rem) | 600 | 1.00 (tight) | 1px | 大型 CTA 按钮文本 |
+| Section Heading | Inter | 48px (3.00rem) | 500 | 1.04 (tight) | normal | 主要章节标题 |
+| Editorial Heading | GT Alpina | 48px (3.00rem) | 250 | normal | -1.92px | 细体编辑大标题 |
+| Editorial Sub | GT Alpina | 40px (2.50rem) | 300 | 1.08 (tight) | -1.6px | 编辑副标题 |
+| Sub-heading LG | Inter | 36px (2.25rem) | 500 | normal | -1px | 大型子章节 |
+| Sub-heading | Inter | 32px (2.00rem) | 400 | 1.25 (tight) | normal | 标准子章节 |
+| Sub-heading MD | Inter | 28px (1.75rem) | 500 | normal | normal | 中等子标题 |
+| Card Title | Inter | 24px (1.50rem) | 600 | normal | -0.48px | 卡片标题 |
+| Body Large | Inter | 20px (1.25rem) | 400-500 | 1.00-1.20 (tight) | -0.2px | 功能描述 |
+| Body Emphasis | Inter | 18px (1.13rem) | 600 | 1.00 (tight) | normal | 强调正文文本 |
+| Body | Inter | 16px (1.00rem) | 400-500 | 1.20-1.25 | -0.16px | 标准阅读文本 |
+| Body Semibold | Inter | 16px (1.00rem) | 600 | 1.16 (tight) | normal | 强标签 |
+| Button | Inter | 16px (1.00rem) | 600 | normal | normal | 标准按钮 |
+| Button SM | Inter | 14px (0.88rem) | 600 | normal | normal | 小型按钮 |
+| Caption | Inter | 14px (0.88rem) | 500 | 1.25-1.43 | normal | 标签、元数据 |
+| Caption Upper | Inter | 14px (0.88rem) | 600 | normal | 0.5px | 大写章节标签 |
+| Micro | Inter | 12px (0.75rem) | 600 | 0.90-1.33 | 0.5px | 微小标签，通常为大写 |
+| Micro SM | Inter | 13px (0.81rem) | 500 | 1.00-1.54 | normal | 小型元数据文本 |
+
+### Principles
+- **三字体系统，角色明确**：Degular Display 仅在 Hero 尺度上吸引注意力。Inter 处理所有功能性内容。GT Alpina 谨慎地增加编辑感的温暖度。
+- **压缩展示**：行高为 0.90 的 Degular 创造了垂直压缩的大标题块，感觉现代且具有建筑感。
+- **字重作为层级信号**：Inter 使用 400（阅读）、500（导航/强调）、600（标题/CTA）。Degular 使用 500（展示）和 600（按钮）。
+- **大写用于标签**：章节标签（如 "01 / Colors"）和细微的分类使用 `text-transform: uppercase` 和 0.5px 的字间距。
+- **负字间距展现优雅**：GT Alpina 在其细字重的编辑大标题中使用了 -1.6px 到 -1.92px 的字间距。
+
+## 4. 组件样式
+
+### Buttons
+
+**Primary Orange**
+- Background: `#ff4f00`
+- Text: `#fffefb`
+- Padding: 8px 16px
+- Radius: 4px
+- Border: `1px solid #ff4f00`
+- Use: 主要 CTA（"Start free with email", "Sign up free"）
+
+**Primary Dark**
+- Background: `#201515`
+- Text: `#fffefb`
+- Padding: 20px 24px
+- Radius: 8px
+- Border: `1px solid #201515`
+- Hover: background 转换为 `#c5c0b1`，text 转换为 `#201515`
+- Use: 大型次要 CTA 按钮
+
+**Light / Ghost**
+- Background: `#eceae3`
+- Text: `#36342e`
+- Padding: 20px 24px
+- Radius: 8px
+- Border: `1px solid #c5c0b1`
+- Hover: background 转换为 `#c5c0b1`，text 转换为 `#201515`
+- Use: 三级操作、过滤按钮
+
+**Pill Button**
+- Background: `#fffefb`
+- Text: `#36342e`
+- Padding: 0px 16px
+- Radius: 20px
+- Border: `1px solid #c5c0b1`
+- Use: 标签式选择项、过滤胶囊按钮
+
+**Overlay Semi-transparent**
+- Background: `rgba(45, 45, 46, 0.5)`
+- Text: `#fffefb`
+- Radius: 20px
+- Hover: background 变为完全不透明的 `#2d2d2e`
+- Use: 视频播放按钮、浮动操作
+
+**Tab / Navigation (Inset Shadow)**
+- Background: transparent
+- Text: `#201515`
+- Padding: 12px 16px
+- Shadow: `rgb(255, 79, 0) 0px -4px 0px 0px inset`（活跃状态的橙色下划线）
+- Hover shadow: `rgb(197, 192, 177) 0px -4px 0px 0px inset`（sand 色下划线）
+- Use: 水平标签页导航
+
+### Cards & Containers
+- Background: `#fffefb`
+- Border: `1px solid #c5c0b1`（暖 sand 色边框）
+- Radius: 5px（标准），8px（特色）
+- 默认无阴影 elevation —— 边框定义了包含关系
+- Hover: 边框颜色微弱加深
+
+### Inputs & Forms
+- Background: `#fffefb`
+- Text: `#201515`
+- Border: `1px solid #c5c0b1`
+- Radius: 5px
+- Focus: border 颜色转换为 `#ff4f00`（橙色）
+- Placeholder: `#939084`
+
+### Navigation
+- 奶油色背景上的干净水平导航
+- Zapier logotype 左对齐，104x28px
+- Links: Inter 16px weight 500，`#201515` 文本
+- CTA: 橙色按钮（"Start free with email"）
+- Tab 导航使用 inset box-shadow 下划线技术
+- Mobile: hamburger 折叠菜单
+
+### Image Treatment
+- 产品截图带有 `1px solid #c5c0b1` 边框
+- 圆角: 5-8px
+- 仪表盘/工作流截图在功能区块中非常突出
+- Hero 内容背后有浅色渐变背景
+
+### Distinctive Components
+
+**Workflow Integration Cards**
+- 成对展示已连接的应用图标
+- 应用之间有箭头或连接指示器
+- Sand 色边框包含
+- Inter weight 500 用于应用名称
+
+**Stat Counter**
+- 使用 Inter 48px weight 500 的大型展示数字
+- 下方是 `#36342e` 颜色的柔和描述
+- 用于社会认同指标
+
+**Social Proof Icons**
+- 圆形图标按钮：14px radius
+- Sand 边框：`1px solid #c5c0b1`
+- 用于页脚中的社交媒体关注链接
+
+## 5. 布局原则
+
+### Spacing System
+- 基础单位：8px
+- 比例尺：1px, 4px, 6px, 8px, 10px, 12px, 16px, 20px, 24px, 32px, 40px, 48px, 56px, 64px, 72px
+- CTA 按钮使用宽大的内边距：大型按钮为 20px 24px，标准按钮为 8px 16px
+- 章节内边距：垂直方向 64px-80px
+
+### Grid & Container
+- 最大内容宽度：大约 1200px
+- Hero: 居中的单列布局，顶部有巨大的内边距
+- 特性区块：用于集成卡片的 2-3 列网格
+- 区块之间的全宽 sand 色边框分隔线
+- 页脚：多列深色背景（`#201515`）
+
+### Whitespace Philosophy
+- **温暖的呼吸空间**：各区块之间有宽裕的垂直间距（64px-80px），但内容区域相对密集 —— Zapier 在其奶油色画布上高效地填充了信息。
+- **建筑感压缩**：行高为 0.90 的 Degular Display 标题在垂直方向上受到压缩，与其周围开放的间距形成对比。
+- **节奏感分区**：全程使用奶油色背景，区块之间通过 sand 色边框而不是背景色的变化来分隔。
+
+### Border Radius Scale
+- Tight (3px)：小型内联 span
+- Standard (4px)：按钮（橙色 CTA）、标签、小型元素
+- Content (5px)：卡片、链接、常规容器
+- Comfortable (8px)：特色卡片、大型按钮、标签页
+- Social (14px)：社交图标按钮、类胶囊元素
+- Pill (20px)：播放按钮、大型胶囊按钮、浮动操作
+
+## 6. Depth & Elevation
+
+| 层级 | 处理方式 | 用途 |
+|-------|-----------|-----|
+| Flat (Level 0) | 无阴影 | 页面背景、文本块 |
+| Bordered (Level 1) | `1px solid #c5c0b1` | 标准卡片、容器、输入框 |
+| Strong Border (Level 1b) | `1px solid #36342e` | 深色分隔线、强调区块 |
+| Active Tab (Level 2) | `rgb(255, 79, 0) 0px -4px 0px 0px inset` | 活跃标签页下划线（橙色） |
+| Hover Tab (Level 2b) | `rgb(197, 192, 177) 0px -4px 0px 0px inset` | Hover 标签页下划线（sand 色） |
+| Focus (Accessibility) | `1px solid #ff4f00` outline | 交互元素上的聚焦环 |
+
+**Shadow Philosophy**：Zapier 刻意避免了传统的基于阴影的 elevation。结构几乎完全通过边框来定义 —— 暖 sand 色（`#c5c0b1`）边框用于标准的包含，深木炭色（`#36342e`）边框用于强调。唯一类似阴影的技术是用于标签页下划线的 inset box-shadow，其中 `0px -4px 0px 0px inset` 阴影创建了一个底部指示条。这种边框优先的方法使设计保持扎实和有形，而不是漂浮的感觉。
+
+### Decorative Depth
+- 活跃标签页上的橙色 inset 下划线在元素底部创造了视觉上的“重量感”
+- Sand 色 Hover 下划线提供了预览状态，而不会导致布局偏移
+- 主内容中没有背景渐变 —— 奶油色画布保持一致
+- 页脚使用全深色背景（`#201515`）以实现对比度反转
+
+## 7. Do's and Don'ts
+
+### Do
+- 专门使用 Degular Display 处理 Hero 尺度的标题（40px+），行高设为 0.90 以获得压缩的冲击力
+- 将 Inter 用于所有功能性 UI —— 导航、正文、按钮、标签
+- 应用暖奶油色（`#fffefb`）作为背景，绝不用纯白色
+- 使用 `#201515` 作为文本色，绝不用纯黑色 —— 红色的暖意很重要
+- 将 Zapier 橙色（`#ff4f00`）保留给主要 CTA 和活跃状态指示器
+- 使用 sand 色（`#c5c0b1`）边框作为主要结构元素，而不是阴影
+- 为大型 CTA 应用宽大的按钮内边距（20px 24px），以匹配 Zapier 宽敞的按钮风格
+- 为标签导航使用 inset box-shadow 下划线，而不是 border-bottom
+- 对章节标签和微观分类应用大写转换并加上 0.5px 的字间距
+
+### Don't
+- 不要将 Degular Display 用于正文或 UI 元素 —— 它仅用于展示
+- 不要使用纯白（`#ffffff`）或纯黑（`#000000`） —— Zapier 的调色板是偏向暖色调的
+- 不要对卡片应用 box-shadow elevation —— 应该使用边框
+- 不要在整个 UI 中散落 Zapier 橙色 —— 它是预留给 CTA 和活跃状态的
+- 不要在大型 CTA 按钮上使用紧凑的内边距 —— Zapier 的按钮刻意设计得很宽敞
+- 不要忽视暖色中性系统 —— 边框应该是 `#c5c0b1`，而不是灰色
+- 不要将 GT Alpina 用于功能性 UI —— 它仅作为编辑强调，只在细字重下使用
+- 不要对 GT Alpina 应用正字间距 —— 它使用的是极强的负字间距（-1.6px 到 -1.92px）
+- 不要为主要按钮使用圆滑的胶囊形状（9999px） —— 胶囊形状是预留给标签和社交图标的
+
+## 8. Responsive Behavior
+
+### Breakpoints
+| 名称 | 宽度 | 关键变化 |
+|------|-------|-------------|
+| Mobile Small | <450px | 紧凑单列，缩小的 Hero 文本 |
+| Mobile | 450-600px | 标准移动端，堆叠布局 |
+| Mobile Large | 600-640px | 轻微的水平呼吸空间 |
+| Tablet Small | 640-680px | 开始出现 2 列网格 |
+| Tablet | 680-768px | 卡片网格扩展 |
+| Tablet Large | 768-991px | 完整的卡片网格，扩展的内边距 |
+| Desktop Small | 991-1024px | 启动桌面布局 |
+| Desktop | 1024-1280px | 完整布局，最大内容宽度 |
+| Large Desktop | >1280px | 居中并带有宽裕的边距 |
+
+### Touch Targets
+- 大型 CTA 按钮：20px 24px 内边距（舒适的 60px+ 高度）
+- 标准按钮：8px 16px 内边距
+- 导航链接：16px weight 500 并带有充足的间距
+- 社交图标：14px radius 的圆形按钮
+- 标签项目：12px 16px 内边距
+
+### Collapsing Strategy
+- Hero: Degular 80px 展示字体在较小屏幕上缩放至 40-56px
+- Navigation: 水平链接 + CTA 折叠为 hamburger 菜单
+- 特性卡片：3 列网格变为 2 列，再到单列堆叠
+- 集成工作流插图：保持长宽比，可能会简化
+- 页脚：多列深色区块折叠为堆叠形式
+- 区块间距：移动端从 64-80px 缩减至 40-48px
+
+### Image Behavior
+- 产品截图在所有尺寸下都保持 sand 色边框处理
+- 集成应用图标在响应式容器内保持固定尺寸
+- Hero 插图按比例缩放
+- 全宽区块保持边缘到边缘的处理方式
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- 主要 CTA：Zapier Orange (`#ff4f00`)
+- 背景：Cream White (`#fffefb`)
+- 标题文本：Zapier Black (`#201515`)
+- 正文文本：Dark Charcoal (`#36342e`)
+- 边框：Sand (`#c5c0b1`)
+- 次要表面：Light Sand (`#eceae3`)
+- 柔和文本：Warm Gray (`#939084`)
+
+### 示例 Component Prompts
+- "Create a hero section on cream background (`#fffefb`). Headline at 56px Degular Display weight 500, line-height 0.90, color `#201515`. Subtitle at 20px Inter weight 400, line-height 1.20, color `#36342e`. Orange CTA button (`#ff4f00`, 4px radius, 8px 16px padding, white text) and dark button (`#201515`, 8px radius, 20px 24px padding, white text)."
+- "Design a card: cream background (`#fffefb`), `1px solid #c5c0b1` border, 5px radius. Title at 24px Inter weight 600, letter-spacing -0.48px, `#201515`. Body at 16px weight 400, `#36342e`. No box-shadow."
+- "Build a tab navigation: transparent background. Inter 16px weight 500, `#201515` text. Active tab: `box-shadow: rgb(255, 79, 0) 0px -4px 0px 0px inset`. Hover: `box-shadow: rgb(197, 192, 177) 0px -4px 0px 0px inset`. Padding 12px 16px."
+- "Create navigation: cream sticky header (`#fffefb`). Inter 16px weight 500 for links, `#201515` text. Orange pill CTA 'Start free with email' right-aligned (`#ff4f00`, 4px radius, 8px 16px padding)."
+- "Design a footer with dark background (`#201515`). Text `#fffefb`. Links in `#c5c0b1` with hover to `#fffefb`. Multi-column layout. Social icons as 14px-radius circles with sand borders."
+
+### Iteration Guide
+1. 始终使用暖奶油色（`#fffefb`）背景，绝不使用纯白色 —— 这种温暖感定义了 Zapier
+2. 边框（`1px solid #c5c0b1`）是结构骨干 —— 避免使用阴影 elevation
+3. Zapier 橙色（`#ff4f00`）是唯一的强调色；其他所有部分都是暖中性色
+4. 三种字体，严格的规则：Degular Display（Hero）、Inter（UI）、GT Alpina（Editorial）
+5. 大型 CTA 按钮需要宽裕的内边距（20px 24px） —— Zapier 的按钮感觉很宽敞
+6. 标签页导航使用 inset box-shadow 下划线，而不是 border-bottom
+7. 文本始终是暖色的：深色用 `#201515`，正文用 `#36342e`，柔和文本用 `#939084`
+8. 12-14px 的大写标签，配合 0.5px 的字间距用于章节分类

package/extensions/skills/builtin/creative/pretext/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: pretext
+description: "用于使用 @chenglou/pretext 构建创意浏览器演示 —— 无 DOM 的文本布局，适用于 ASCII 艺术、围绕障碍物的排版流动、文本即几何游戏、动态排版以及文本驱动的生成艺术。默认生成单文件 HTML 演示。"
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [creative-coding, typography, pretext, ascii-art, canvas, generative, text-layout, kinetic-typography]
+    related_skills: [p5js, claude-design, excalidraw, architecture-diagram]
+---
+
+# Pretext 创意演示
+
+## 概览
+
+[`@chenglou/pretext`](https://github.com/chenglou/pretext) 是由 Cheng Lou（React 核心开发者、ReasonML、Midjourney）开发的一个 15KB 零依赖 TypeScript 库，用于**无 DOM 的多行文本测量与布局**。它只做一件事：给定 `(text, font, width)`，返回换行位置、每行宽度、每个 grapheme 的位置以及总高度——所有这些都通过 canvas 测量完成，无需 reflow。
+
+这听起来像是底层管道工作。其实不然。因为它既快又基于几何运算，它是一个**创意原语 (creative primitive)**：你可以以 60fps 的帧率让段落围绕移动的精灵 (sprite) 重新排版，构建关卡几何由真实单词组成的游戏，让 ASCII 标志穿过正文，利用精确的 grapheme 起始位置将文本炸裂成粒子，或者打包紧贴边界的多行 UI，而无需频繁调用 `getBoundingClientRect`。
+
+这个技能的存在是为了让 Hermes 能够用它制作**酷炫的演示**——那种人们会分享到 X 上的作品。可以在 `pretext.cool` 和 `chenglou.me/pretext` 查看社区演示集。
+
+## 何时使用
+
+当用户要求以下内容时使用：
+- "pretext demo" / "酷炫的 pretext 玩意" / "text-as-X"（以文本作为某物）
+- 文本围绕移动的形状流动（主视觉区块、编辑级排版、动画长页面）
+- 使用**真实的单词或正文**的 ASCII 艺术效果，而不是等宽栅格图
+- 游戏场地 / 障碍物 / 砖块由文本组成的游戏（字母俄罗斯方块、正文打砖块）
+- 带有基于单个字形物理效果的动态排版（炸裂、散射、聚集、流动）
+- 排版生成艺术，特别是包含非拉丁文字或混合文字的情况
+- 多行 "shrink-wrap"（紧缩包裹）UI（依然能容纳文本的最小容器宽度）
+- 任何需要在渲染*之前*知道换行位置的场景
+
+不要用于：
+- CSS 已经解决布局问题的静态 SVG/HTML 页面——直接用 CSS 即可
+- 富文本编辑器、通用的行内格式化引擎（pretext 是刻意保持功能收敛的）
+- 图片转文本（使用 `ascii-art` / `ascii-video` 技能）
+- 没有文本参与的纯 canvas 生成艺术——使用 `p5js`
+
+## 创意标准
+
+这是在浏览器中渲染的视觉艺术。Pretext 负责返回数字；而**你**来负责绘制。
+
+- **不要交付 "hello world" 级别的演示。** `hello-orb-flow.html` 模板只是*起点*。每一个交付的演示都必须加入刻意的色彩、动态、构图，以及一个用户没有要求但会欣赏的视觉细节。
+- **深色背景，暖色核心，精心考量的调色板。** 经典的黑底琥珀字（CRT / 终端机风格）很不错，但炭灰底冷白字（杂志排版风格）和低饱和度柔和色（孔版印刷风格）同样出色。选定一种并贯彻到底。
+- **比例字体才是重点。** Pretext 的整体调性就是 "非等宽"——拥抱这一点。使用 Iowan Old Style、Inter、JetBrains Mono、Helvetica Neue 或可变字体。永远不要用默认的无衬线字体。
+- **真实的源码/文本，不要用 lorem ipsum。** 语料库应该是有意义的。简短的宣言、诗歌、真实的源代码、偶然发现的文本、该库自己的 README——绝不要用 `lorem ipsum`。
+- **第一帧渲染就要足够出彩。** 没有加载状态，没有空白帧。演示在打开的瞬间就必须看起来像是可以发布的成品。
+
+## Stack
+
+每个演示对应一个单独的 HTML 文件。无需构建步骤。
+
+| Layer | 工具 | 用途 |
+| ------- | ------ | --------- |
+| Core | 通过 `esm.sh` CDN 引入 `@chenglou/pretext` | 文本测量 + 行布局 |
+| Render | HTML5 Canvas 2D | 字形渲染，逐帧构图 |
+| Segmentation | `Intl.Segmenter` (内置) | 用于 emoji / CJK / 组合字符的 grapheme 分割 |
+| Interaction | 原生 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) 查看最新版本。
+
+## 两大用例
+
+几乎所有场景都可以归结为这两种模式中的一种。请熟练掌握它们。
+
+### Use-case 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 一致，否则测量结果会产生偏差。
+
+### Use-case 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 或任何坐标系中
+- 替换逐个字形的变换（旋转、抖动、缩放、透明度）
+- 将行元数据（宽度、grapheme 位置）作为几何数据使用
+
+对于**每行可变宽度**的流动效果（文本围绕形状流动、在环形带中排布文本、非矩形列中的文本）：
+
+```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 上疯传的演示。
+
+### 值得了解的辅助 API
+
+- `measureLineStats(prepared, maxWidth)` → `{ lineCount, maxLineWidth }` —— 最宽行的宽度，即多行紧缩包裹宽度。
+- `walkLineRanges(prepared, maxWidth, callback)` —— 遍历行而无需分配字符串。当你不需要具体字符，只需对 grapheme 进行统计或物理计算时使用。
+- `@chenglou/pretext/rich-inline` —— 同样的系统，但适用于混合字体 / 标签 / 提及的段落。从子路径中导入。
+
+## 演示套路模式
+
+社区演示集（参见 `references/patterns.md`）主要集中于几种强有力的模式。选择一种并加以发挥——除非有要求，否则不要发明新类别。
+
+| Pattern | Key API | Example idea |
+| --- | --- | --- |
+| **围绕障碍物重新排版** | `layoutNextLineRange` + 逐行宽度函数 | 围绕拖拽光标精灵分开的杂志排版段落 |
+| **文本即几何游戏** | `layoutWithLines` + 逐行碰撞矩形 | 打砖块游戏，每块砖都是一个测量过的单词 |
+| **炸裂 / 粒子化** | `walkLineRanges` → 逐个 grapheme 的 (x,y) → 物理效果 | 点击后爆炸成字母的句子 |
+| **ASCII 障碍物排版** | `layoutNextLineRange` + 测量出的逐行障碍区段 | 位图 ASCII 标志、形状变形，以及可拖拽的线框物体，让文本根据其真实几何形状避让 |
+| **杂志多列排版** | 每列 `layoutNextLineRange` + 共享游标 | 带有引言的动画杂志跨页排版 |
+| **动态排版** | `layoutWithLines` + 随时间变化的逐行变换 | 星球大战字幕滚动、波浪、弹跳、故障风 |
+| **多行紧缩包裹** | `measureLineStats` | 自动缩放至最紧凑容器的引用卡片 |
+
+可以在 `templates/donut-orbit.html` 和 `templates/hello-orb-flow.html` 中查看可运行的单文件入门示例。
+
+## Workflow
+
+1. 根据用户的简报，从上表中**选择一种模式**。
+2. **从模板开始**：
+   - `templates/hello-orb-flow.html` —— 围绕移动球体重新排版的文本（围绕障碍物重排模式）
+   - `templates/donut-orbit.html` —— 进阶示例：测量出的 ASCII 标志障碍物、可拖拽的线框球体/立方体、变形的形状场、可选中的 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. **向用户展示文件路径**，而不仅仅是代码——他们需要的是直接打开它。
+
+## Performance Notes
+
+- `prepare()` / `prepareWithSegments()` 是开销较大的调用。对每个文本+字体组合只执行**一次**。缓存返回的句柄。
+- 在窗口缩放时，只需重新运行 `layout()` / `layoutWithLines()`——绝不重新执行 prepare。
+- 对于文本不变但几何形状变化的逐帧动画，在紧凑循环中调用 `layoutNextLineRange` 的开销很小，对于正常长度的段落完全可以做到 60fps 每帧运行。
+- 当逐帧渲染 ASCII 遮罩时，请保留一个单元格缓冲区 (`Uint8Array`/类型化数组)，从单元格或投影几何中推导出测量过的逐行障碍区段，合并区段，然后在绘制文本之前将这些区段输入到 `layoutNextLineRange` 中。
+- 保持视觉动画与布局动画联动。如果一个球体变形为立方体，请使用相同的数值同时对渲染的单元格缓冲区和障碍区段进行补间动画；否则，演示看起来会像是贴图上去的，而不是物理上的重新排版。
+- 对于淡入淡出效果，首选改变图层透明度，而不是改变字形强度或障碍物缩放比例。将瞬态 ASCII 精灵放在单独的 canvas 上，并使用 CSS/GSAP 控制其透明度进行淡入淡出，这样几何体看起来就不会像是在缩小。
+- Canvas 的 `ctx.font` 设置出人意料地慢；如果字体没有变化，每帧只设置**一次**，而不是在每次调用 `fillText` 时设置。
+
+## Common Pitfalls
+
+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` 会导致性能骤降。请将准备好的句柄保留在模块作用域中。
+
+3. **分割 grapheme 时忘记使用 `Intl.Segmenter`。** Emoji、组合符号、CJK——`"é".split("")` 会返回两个字符。当提取独立的可见字形时，请使用 `new Intl.Segmenter(undefined, { granularity: "grapheme" })`。
+
+4. **使用 `break: 'never'` 标签却没有提供 `extraWidth`。** 在 `rich-inline` 中，如果你为不可分割的标签/提及使用了 `break: 'never'`，你必须同时提供 `extraWidth` 以容纳标签内边距——否则标签的边界会溢出容器。
+
+5. **从 `unpkg` 引入仅含 TypeScript 入口的 `@chenglou/pretext`。** 请使用 `esm.sh`——它会自动将 TS 导出编译为浏览器就绪的 ESM。`unpkg` 会返回 404 或直接提供原始 TS 代码。
+
+6. **等宽字体回退悄无声息地抹杀了全部意义。** 看到等宽字体输出的用户，通常是因为其 CSS `font-family` 最终回退到了 `monospace`。请通过开发者工具 (DevTools) 验证实际渲染的字体。
+
+7. **在围绕形状流动时跳过行与调整宽度的区别。** 如果某一行的通道太窄，无法容纳文本，请直接*跳过该行*（`y += lineHeight; continue;`），而不是向 `layoutNextLineRange` 传入一个极小的 maxWidth——否则 pretext 会返回单 grapheme 的行，看起来就像坏掉了一样。
+
+8. **交付了一个冷冰冰的演示。** 默认的初始画面看起来像新手教程级别。请添加：晕影 (vignette)、微妙的扫描线、待机自动动画、以及一个精心挑选的交互响应（拖拽、悬停、滚动、点击）。如果没有这些，"酷炫的 pretext 演示" 给人的感觉就会变成 "实习生对 README 的复刻"。
+
+## 验证 检查清单
+
+- [ ] Demo 是一个独立的 `.html` 文件——双击或通过 `python3 -m http.server` 即可打开
+- [ ] 通过 `esm.sh` 引入 `@chenglou/pretext` 并锁定了版本
+- [ ] 语料库是真实的散文，而不是 lorem ipsum，且符合演示的概念
+- [ ] 传给 `prepare` 的字体字符串与 CSS 字体完全一致
+- [ ] `prepare()` / `prepareWithSegments()` 只被调用一次，而不是在每一帧
+- [ ] 深色背景 + 精心考量的调色板——不是默认的白色 canvas
+- [ ] 至少有一种交互响应（拖拽 / 悬停 / 滚动 / 点击）或待机自动动画
+- [ ] 已通过 `python3 -m http.server` 在本地测试，并确认没有控制台报错
+- [ ] 在中端笔记本上达到 60fps（或有文档记录的优雅降级策略）
+- [ ] 包含一个用户没有要求但令人惊喜的 "额外" 细节
+
+## Reference: Community Demos
+
+克隆这些项目以获取灵感 / 模式（均为 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 聊天、富文本笔记。