DESIGN.mdA
DESIGN.md from onemoh/html-explainer is a DESIGN.md file: the design rules coding agents follow in that repo.
mdr add onemoh/html-explainer/DESIGN.md@git:20261105.6b4576cPins git:20261105.6b4576c in mdr.lock. Pin the fingerprint instead.
- Audit grade
- A, 14 of 14 checks passed
- Kind
- DESIGN.md file
- Repository
- onemoh/html-explainer
- Path
DESIGN.md- Versions recorded
- 1
- Latest version
- git:20261105.6b4576c, committed Nov 5, 2026
- Size
- 16,047 bytes
- Repository stars
- 274
- License
- MIT
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# 设计与实现
> `README.md` 的深水区：这里解释**为什么这样做**，以及那些不写下来就会被反复踩的约束。
>
> - 想知道怎么用 → [README.md](README.md)
> - 想看命令与确认点 → [SKILL.md](SKILL.md)
> - 想看踩过的坑（133 条） → [references/lessons.md](references/lessons.md)
**目录**
1. [渲染原理：为什么不用录屏](#渲染原理为什么不用录屏)
2. [`B()` 节拍系统](#b-节拍系统)
3. [画面风格库](#画面风格库)
4. [动效库](#动效库)
5. [模板编排](#模板编排)
6. [封面多画幅](#封面多画幅)
7. [渲染性能实测](#渲染性能实测)
8. [配音细节](#配音细节)
9. [思想来源](#思想来源)
---
## 渲染原理：为什么不用录屏
多数「HTML 转视频」工具是启动浏览器、播放动画、录屏。这条路会生出一整类**间歇性** bug ——
动画在录制开始前就播了、网络字体加载晚了导致半段视频用了错误字体、前几帧拍到的是动画前的状态。
`html-explainer` 不录制，它 **seek**：把 GSAP 时间轴定位到那一瞬间
（`tl.pause(t, false)`），同步所有 CSS 动画（`document.getAnimations().currentTime`），
等两个动画帧后截图。于是第 1204 帧与下一次渲染的第 1204 帧逐像素一致 —— QC 可以定点抽查、
单个场景可以独立重渲，一整类时序 bug 从根本上无法发生。
代价是**每个动画都必须可 seek**：墙钟动画（`setInterval`、`requestAnimationFrame` 计数、
CSS `transition` 入场）不可能工作，会被 `lint_frames.py` 直接拒绝。这也正是动效库被设计成
「`t` → 一组数字」的纯函数的原因：它天生可 seek。
---
## `B()` 节拍系统
`subs.py` 为每个场景生成一份 `beats.js`，把每块字幕按**原文**暴露出来，于是画面动画可以直接
锚在吐字时刻上：
```js
tl.fromTo('.card', { y: 60, autoAlpha: 0 }, { y: 0, autoAlpha: 1, duration: 0.7 }, B('右边卡片'));
tl.fromTo('.verdict', { scale: 0.8 }, { scale: 1, duration: 0.6 }, B('结论句') + 0.2);
```
…Read the whole file at its exact version.
How to install
mdr add onemoh/html-explainer/DESIGN.md@sha256:b89eb9235130d42eThe line at the top of this page pins the label git:20261105.6b4576c, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
[](https://markdownregistry.com/a/art_vhiiswjx6vr72uy2)
1 badge image fetches in 30 days. What the badge shows.
Versions
The registry has recorded 1 version of this file, committed on Nov 5, 2026.
Audit of the latest version
- pass: Size between 200 bytes and 200 KB (16047 bytes)
- pass: No zero-width or bidi control characters
- pass: No instruction hidden inside an HTML comment
- pass: No link to an exfiltration or paste host
- pass: No credential-shaped string
- pass: No instruction to send local credentials anywhere
- pass: No text hidden with inline styles
- pass: No prompt-injection phrasing
- pass: No curl or wget piped into a shell
- pass: No recursive delete of root, home or parent
- pass: No instruction to read or print local credentials
- pass: No base64 blob over 200 characters
- pass: No link to a raw IP address
- pass: No script tag
Source
onemoh/html-explainer · 274 stars · license MIT · pushed 2026-11-05 · branch main
API
GET https://markdownregistry.com/api/v1/artifacts/art_vhiiswjx6vr72uy2 GET https://markdownregistry.com/api/v1/resolve?ref=onemoh/html-explainer/DESIGN.md GET https://markdownregistry.com/api/v1/blob/b89eb9235130d42e1a26a041e34839ec7aa4b4d3acbc8a872ea65501dee62d5e
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
Guides: what DESIGN.md is and how agents use it · which agent file does what.
More from onemoh/html-explainer
Every file in onemoh/html-explainer