slide-dsl 是 thu-maic/openmaic 项目中的幻灯片 DSL 完整手册，面向需要直接编辑幻灯片 JSON 文档的使用者。
用途
幻灯片页面是一个 JSON 文档。要正确编辑它，需要写入承载目标改动的确切字段，采用渲染器读取的确切形状，并保持相邻字段逐字节不变。本手册用于说明该 DSL 的结构、字段含义与编辑规则。
写入路径的特点
写入路径存储你发送的内容。没有标记白名单、没有清理器、没有颜色或字体规范化、没有几何裁剪、没有在写入时应用的内置样式。patch_stage 只检查一件事：结果文档是否仍匹配 DSL 结构 schema（字段名、类型、必填字段、封闭对象），然后逐字节持久化你的值。因此结构与含义是分离的：结构合法的页面仍可能不可读，例如渲染器从不设置样式的标记、没有任何绘制读取的颜色、与来源不一致的公式快照。护栏只捕获形状，不捕获含义。
读取深度
read_stage 有三种深度，不可互换：
- inventory（默认）：每个元素一行紧凑信息，包含 id、type、纯文本 text、left、top、width、height、src。用于查找元素，不可作为补丁来源。
- source：返回精确持久化的页面 JSON，是所有补丁路径的根。每次写入后应再次读取。
- text：返回每个含文本元素的 { path, id, type, text } 以及一个页面级 combinedText，用于确认旧文案没有残留。
文档结构
幻灯片场景的 content 为：{ type: 'slide', schemaVersion?: number, canvas: Slide }。type 和 schemaVersion 位于 /content/canvas/ 之外，因此不可通过 slide-canvas 补丁路径访问。所有可写入内容都位于 canvas 下。
画布字段
canvas 包含：id（必填，页面标识，更改会被拒绝）、viewportSize（必填，画布宽度 px，本产品为 1000）、viewportRatio（必填，高度÷宽度，0.5625，即画布 1000 × 562.5 px）、theme（必填）、elements（必填，按绘制顺序排列的元素数组，索引 0 为最底层）、background（可选）、animations（可选）、turningMode（可选）、sectionTag（可选）、type（可选）、script（可选）。
几何
viewportSize 是设计空间宽度，不是屏幕宽度。每个元素的 left/top/width/height 使用相同的设计像素，原点在画布左上角，x 向右，y 向下。渲染时整个画布按一个因子缩放以适应容器，因此设计像素本质上是比例。标准页面的常量：画布 0 ≤ left ≤ 1000，0 ≤ top ≤ 562.5；水平居中 left = (1000 - width) / 2；垂直居中 top = (562.5 - height) / 2。DOM 中画布边缘不裁剪，但快照/导出捕获会裁剪画布外的内容。
背景
background 为 { type, color?, image?, gradient? }，type 为 solid | image | gradient。渲染器按固定顺序解析，缺少对应载荷的 type 会回退到纯白 #fff。solid 读取 color；image 读取 image { src, size }；gradient 读取 gradient { type, colors[], rotate }。gradient.colors 为 [{ pos, color }, …]，pos 为 0–100 的百分比数字，rotate 为度数。当 type 仍为 'gradient' 时设置 background.color 不会产生可见变化。
theme
theme 为 { backgroundColor, themeColors[], fontColor, fontName, outline?, shadow? }，四个标量均必填。渲染器实际只绘制 fontColor 和 fontName，它们设置在包裹每个元素的容器上，作为继承默认值。theme.backgroundColor 不是页面背景（页面背景是 canvas.background）；theme.themeColors、theme.outline 和 theme.shadow 是编辑器创建新元素时使用的创作默认值，渲染器不读取。
animations
animations 为 [{ id, elId, effect, type, duration, trigger }, …]，type 为 in / out / attention，trigger 为 click / meantime / auto。播放时不会播放它们，两个渲染器都不读取 canvas.animations，唯一消费者是 Pro 模式编辑器的动画面板。它们被存储、校验和保留，应视为不可破坏的数据。删除元素会同时删除绑定到其 id 的动画。
elements 与 z 顺序
深度由数组位置决定：索引 0 最先绘制（底层），最后一个元素最后绘制（顶层）。没有 zIndex 字段，渲染器根据数组索引分配 CSS z-index。重排是唯一没有叶子可寻址的改动，需要整体写入 /content/canvas/elements 数组，保持 id 集合和每个 id→type 配对不变。
编辑操作
对于幻灯片画布，patch_stage 提供五种操作：
- set：path, value，写入一个 JSON Pointer 路径。
- remove：path，移除一个可选字段或有界数组项。
- str_replace：path, oldText, newText, 可选 replaceAll，替换一个字符串字段内的精确锚点。
- add_element：element（完整，无 id），afterId 或 index，插入一个新元素，服务器分配 id。
- delete_element：elementId，移除该元素及其绑定的动画。
set 不带 value 会失败；remove 带 value 会失败。add_element 拒绝携带 id 的元素；afterId 和 index 不能同时提供；index 必须是 0 到当前元素数量的整数；两者都省略时元素落在顶层。创建元素是完整元素写入，不是补丁，必须提供该类型所有 DSL 必填字段。
寻址字段
path 是以 read_stage detail:"source" 返回的精确场景为根的 JSON Pointer，幻灯片字段以 /content/canvas/ 开头。应寻址叶子而非分支，给出隔离改动的最小路径。数组索引是规范且有界的，0、1、2 合法，03、-1、+1 和越界索引均被拒绝。最后一个段之前的所有段必须已存在；最后一个段不必存在，set 可添加可选字段，remove 可删除它。路径不能跨越标量。对数组索引 remove 会缩短数组。~1 和 ~0 转义键中的 / 和 ~。值在写入时深拷贝。
结构 schema 拒绝的情况
指针级拒绝：不以 /content/canvas/ 开头的路径、格式错误的 ~ 转义、非规范或越界的数组索引、缺失中间段或跨越非容器的路径、对不存在的键或索引 remove、set 不带 value 或 remove 带 value。
身份拒绝：更改 /content/canvas/id、添加/移除/重命名/复制元素 id、更改现有 id 的 type、add_element 携带 id 或同时提供 afterId 和 index。
Schema 拒绝：任何未知字段（所有对象封闭，additionalProperties: false）、类型错误、超出封闭联合的值、移除必填字段、元数错误的元组、字段用在错误类型上。
服务器唯一重写：当补丁更改元素的 latex 时，服务器从新来源重新渲染该元素的 html 快照（KaTeX，显示模式，错误渲染而非抛出）并存储。如果渲染无返回，则移除 html。文档中其他内容不会被触碰。
两种渲染器
同一 JSON 由两种实现绘制：播放渲染器（应用内元素组件，默认用于课堂页面）和预览渲染器（@openmaic/renderer 的 SlideCanvas，用于页面缩略图，也可在环境变量开启时用于播放）。富文本样式表方面，播放渲染器没有样式表，只有全局 CSS reset、浏览器默认和你的内联样式；预览渲染器随画布提供自己的 .slide-renderer-prose 规则。已知差异包括：列表标记、text 元素的 paragraphSpace、text 元素的 vAlign 和表格单元格的逐边边框、纯文本内容中的换行、audio 元素、超大公式的缩放行为。规则是：为交集编写。
每个元素都携带的字段
id、left、top、width、height、rotate 均必填，另有可选 lock、groupId、link { type, target } 和 name。left/top/width/height 为画布 px，原点左上。rotate 为度数，顺时针，围绕盒子中心。line 元素例外：没有 height 和 rotate，其范围和方向来自端点。lock、groupId 和 name 是编辑器簿记，渲染器不读取。link 也不被渲染器绘制，元素级超链接被存储和导出，但播放中不可点击。旋转应用于定位盒子内部的包裹层，因此 left/top/width/height 始终描述未旋转的盒子。
十种元素类型
text、shape、image、line、chart、table、latex、video、audio、code。手册为每种类型提供单独章节，说明其字段、单位、默认值和合法取值。
适用场景与限制
本手册适用于需要直接编辑或生成 openmaic 幻灯片 JSON 的场景，尤其是通过 patch_stage 进行精确字段修改。限制在于：写入路径不做语义校验，结构合法不等于视觉正确；两种渲染器存在已知差异；动画在播放中不生效；部分字段仅用于编辑器簿记。