ljg-present

ljg-present：演讲铸造器

将 outline 铸造成舞台。内容由作者决定，Skill 只决定它如何呈现。

核心契约

Outline 是真理，Skill 是渲染器。

• 标题、段落、清单项目、引用不改动文字。
• 表格不变更结构，example/程式码区块不改动空格与换行。
• 所有原始元素依原顺序出现；不提炼、不浓缩、不重排。
• 唯一允许改变的是物理分页与视觉构图。
• #+title: 是文件标题，必须先产生独立 cover；第一个 outline 节点仍保持在下一页。若两者文字完全相同，可合并为 cover，不得重复。

Workflow Routing

Workflow	Trigger	File
Generate	讲这个、present、做成简报/演讲、slides、按 outline 美化、产生 HTML 简报	Workflows/Generate.md

产生简报时先读取 RenderingSpec.md，再使用根目录的 SloganTemplate.html。切勿凭记忆重造范本。

Quick Reference

输入与输出

• 输入：Orgmode、Markdown 或纯文字。
• 输出：~/Downloads/{title}.html，单文件、离线、无外链资源。
• 首屏：文件标题 cover。
• 空间节奏：所有文字页共用稳定中轴；cover 与章节页靠深浅色场、字级大小与居中短信号线区分。
• Header：不承载任何资讯。
• Footer：首页显示页码与 subtitle/meta；其他页仅显示页码。

Theme

优先顺序：显式参数 > #+filetags: > 预设 black。

参数	theme	调性
-b / --theme=black	black	沉思、论证
-r / --theme=red	red	宣言、号召
-y / --theme=yellow	yellow	反讽、警觉
--hacker	hacker	逆向工程实验纸
--cyber	hacker	相容别名；不再产生 CRT/HUD
--theme=hacker-dark	hacker-dark	低眩光深色终端；全页暗场、柔和灰绿内文

Hacker 有两个静态阅读变体。两者皆拒绝荧光特效堆叠：

--hacker-void:   #07110D;
--hacker-paper:  #EAF4EC;
--hacker-signal: #00C46A;

--hacker-dark-bg:     #06110D;
--hacker-dark-deep:   #020806;
--hacker-dark-panel:  #0A1A13;
--hacker-dark-fg:     #CFE1D5;
--hacker-dark-signal: #25E981;

hacker 的一般页使用浅色实验纸；hacker-dark 的所有页面使用深色场，cover 与一级章节再加深一档。暗色内文非纯白，而是柔和灰绿；信号绿仅负责居中信号轨、重点与表格标签。请勿使用矩阵雨、发光描边、伪 HUD 或闪烁游标。

Outline 映射

Source	Page
* 一级标题	独占 emphasis 章节页
** 及更深标题	独占 title 页；阶层越深字级越小
段落	theme 文字页；仅在必要时物理切页
列表	同阶层连续 3–4 项优先整组同页；更长列表切分为 3–4 项一页，并避免单项残留末页
表格	table 页；超过 6 行分页并重复表头
引用	quote 页；超过 2 个原始行时续页并记录 sourceParts
#+begin_example / fenced code	pre 页，逐字元保留
*强调* / ~code~ / =verbatim=	hl: true；emphasis 页忽略 inline hl

多行并非统一缩减字级

多行页同时评估「行数」与「文字密度」，但始终使用单列 rows：

• 2、3、4 行全部沿着页面中轴纵向排列，翻页时不切换左右阅读路径。
• 字级由「行数 + light/medium/dense」复合规则决定；先切页、再放大，最后才由 fit guard 微调。
• 单行、非列表、非整行公式且去除空白后 ≤16 个字形的内容，优先判定为「语义原子」：即使 CJK 权重落在 long，仍保持整句单行并套用高桥流。
• 连续同阶层列表优先保持语义区块：3–4 项整组放在同页；超过 4 项时切分为 3–4 项一页，避免将最后一项单独孤立。
• 网格项目必须设定 min-width: 0，使内文自然换行；切勿将 .line 设为 flex/grid，以免拆散高亮与公式。
• 单行 single/short/medium 套用「高桥流」：少字即为主视觉，横萤幕有效字级以 ≥90px 为目标。

阈值与 DOM 栏位依 RenderingSpec.md 规范为准。

公式、ASCII 与尺寸

• 仅将闭合的 $...$ / $$...$$ 视为公式；像 $20/month 这类价格并非公式。
• 离线算图/渲染常用符号与上下标，不依赖 MathJax/CDN。
• ASCII/pre 依据物理行数分阶：≤16 行自 22px 起、17–24 行自 18px 起、25–28 行自 15.5px 起；面板居中，字元内部靠左对齐。
• 一般长文字/引用目标的有效字级需 ≥42px，2–4 行文字 ≥40px，表格 ≥30px；若无法达到则优先切页。
• 每页皆测量真实可用宽高；监听 resize、fullscreen、字型就绪与 ResizeObserver。
• data-fits=true 仅代表未超出边界；一般非 table/pre 文字页若 fitScale < 0.80，必须重新切页。语义原子为了保持完整单行，以最终有效字级 ≥56px 为门槛，不再以原始字级比例造成误判。

通用互动

• → ↓ Space Enter j PageDown：下一页。
• ← ↑ k PageUp：上一页。
• Home / End：第一页 / 最后一页。
• f / F：全萤幕。
• 触控萤幕左右滑动、点击左右半萤幕：翻页。

上下键与 PageUp/PageDown 同时保留，因为不同蓝芽简报笔发送的键值不同。

验收门槛

产生 HTML 后执行：

bun Tools/ValidateDeck.ts ~/Downloads/<deck>.html --theme <theme>

Validator 负责静态契约：范本版本、JS 语法、标题 cover、header/footer、零特效动画、公式保护、多行布局、fit guard、页面类型、翻页键与外链资源。

视觉判断必须使用 Interceptor 在隔离的浏览器中复验典型页与高密度页。若隔离 context 无法使用，应回报「静态验证通过，尚未经过浏览器视觉复验」；不得改用主浏览器或其他截图工具，亦不得宣称视觉已完成验证。

Gotchas

• 视觉居中不等于仅设定 text-align:center。 文字对齐、左右 padding、装饰轨道与 transform origin 必须共同共用同一中轴，否则翻页时仍会产生偏移。
• Cover、emphasis、title 为同轴的三种空间角色。 它们利用字级大小、深浅色场与短信号线建立节奏，不再变更左右锚点。
• 缩放原点也是构图的一部分。 文字页统一采用 center center；否则套用 fit 后会将原本居中的内容拉偏。
• Theme 并非配色别名。 纯黑搭配纯白容易在长简报中造成视觉疲劳；暗色 Hacker 使用深绿黑、柔和灰绿文字与两阶暗场，资讯阶层来自结构线与明度差，而非靠荧光特效堆叠。
• 「放得下」不等于「后排看得清」。 多行页不能仅按最长字元缩减字级；列表优先维持 3–4 项的语义区块，引用最多两行，低于投影字级门槛时才办理续页。
• 语法长度不等于语义长度。 「AI 为火药，人为点火者。」这类短句即使经 CJK 加权后归类为 long，也必须先作为完整的语义原子处理，不可让通用换行规则将结尾文字甩到下一行。
• 分页单位并非固定两项。 同标题、同阶层、连续 3–4 项往往构成一个对比或推论；应先将整组放在同页，再依真实有效字级与溢出状况决定是否需要人工切分。
• 中文句尾需防止孤字。 允许换行的长句应使用不改变 textContent 的尾段 span 留住最后三个汉字及标点符号；切勿插入隐藏字元以免污染复制结果。
• vmin 并非响应式解法。 固定字级只能大致估算；真实边界必须由 scrollWidth/scrollHeight 与可用宽高共同计算。
• fits 不等于可读。 极端缩小仍可能取得 fits=true；一般文字页若 fitScale < 0.80 或低于投影字级门槛，皆应重新切页。语义原子须单独验收最终有效字级，因为其目标是将整句等比例缩放为单行。
• ASCII 的上限取决于行数。 28 行的字元图在 648px 高度的萤幕上不可能同时达到 22px；必须使用依密度分阶的物理下限，必要时应人工拆图。
• 公式辨识必须要求闭合的分隔符。 否则价格、货币或路径中的 $ 会被误判为公式。
• 多行网格必须设定 min-width: 0。 缺少此设定时，长字词或公式会将栏位撑出 viewport。
• .line 应维持为行内容器。 若将其设为 flex/grid，会拆散 chunks、inline math 与高亮；布局应作用于 .lines。
• Header 与 footer 属于不同契约。 Header 不放置任何资讯；meta 仅出现在 cover footer，pager 则是每页都有。
• 禁止所有视觉特效与动画。 不仅需检查 shorthand 简写，还须涵盖 animation-*、transition-*、view-transition-*、smooth scroll、.animate() 与计时器。
• 离线检查不能只扫描 <img> 与 https://。 CSS 中的相对路径 url(...)、@import、image-set(...) 同样会导致单文件在其他机器上遗失资源。
• 真实浏览器的测试证据无法被取代。 静态 validator 能防止结构回归，但无法证明字型、换行与视觉节奏在真实 Chrome 环境中正常成立。
• 占位符注入必须使用函数式 replacer。 String.replace(pattern, replacementString) 会解析 $$、$&、$` 、$' 等替换模式，可能静默破坏 LaTeX 或内文；四个范本占位符皆需使用 () => value 注入。
• 保真审计必须涵盖最终 HTML。 若仅审计序列化前的记忆体 slides，会漏掉注入层的位移；写入档案前，先从完整 HTML 反解析 RAW_SLIDES，再针对 source manifest、可见文字、continuation 与 example 重新执行同一套审计。

Examples

Example 1：常规 outline 简报

User: 用 ljg-present 讲这个 ~/Documents/notes/talk.org
→ 读取 Generate workflow、RenderingSpec 与 SloganTemplate
→ 保留全部 outline，产生标题 cover 与 black/red/yellow 主题页面
→ 执行 ValidateDeck，再输出 ~/Downloads/<title>.html

Example 2：静态 Hacker 简报

User: 把这篇 org 做成 Hacker style，不要动画特效
→ 选择 --hacker，一般页浅底、章节页深底
→ 所有文字页保持中轴；短句套用高桥流，多行统一 rows 并先切页
→ 验证零特效动画、公式、footer、自适应与简报笔

Example 3：静态暗色 Hacker 简报

User: 整体改成暗色 Hacker style，不要任何动画特效
→ 选择 --theme=hacker-dark，全页使用深绿黑场与柔和灰绿内文
→ cover/emphasis 再加深一档，信号绿仅用于结构线、重点与标签
→ 验证内文对比度 ≥9:1、零阴影/动画特效、双尺寸零超出边界

中文预设

预设输出中文；原文为英文且使用者要求保留时，不予翻译。