@linloir/limr 0.0.0-stage → 0.1.0

package/docs/extensions.md

@@ -0,0 +1,309 @@
+# 扩展指南
+
+语法、节点渲染、角注和选区操作遵循同一套公开接口。`standard()` 只是默认模块列表，没有第二套内部专用模块接口。
+
+## 独立语法模块
+
+`defineBlock({name, component, tags?, directives?, selection?})` 同时注册标签和指令适配器：
+
+```tsx
+const warning = defineBlock({
+  name: 'warning',
+  component: ({ children, pending }) => <aside aria-busy={pending}>{children}</aside>,
+});
+```
+
+```markdown
+<warning>
+
+**Markdown** 内容。
+
+</warning>
+
+:::warning
+也可以用指令语法。
+:::
+```
+
+组件接收 `node`（含 attributes/children/原文 position）、`children`、`source`、`pending` 和 `renderChildren(nodes)`。后者直接渲染已解析子树，不需要重新解析字符串。按需渲染答案/提示时可保留对应节点，以原始坐标交还给 `renderChildren`。字面量节点（如 code/inlineCode）使用 `renderValue(tokens?)` 保留源码映射和装饰；token 只需提供正文 `content`、相对 node.value 的 UTF-16 `offset` 和可选 `style`。
+
+属性中的可见文字使用 `renderAttribute('title')`：内置 JSX/指令适配器保留属性值的原文位置（不含引号），因此标题同样支持部分选择、高亮和角注，实体解码后仍能回到原始坐标。直接输出 `node.attributes.title` 则只会得到普通文字。自定义解析器可提供 `node.attributeNodes[name]`（带 `value` / `position` 的文本节点）接入同一链路。
+
+需要行内标签、全新 token 或 AST 改写时用 `defineExtension()`：
+
+```tsx
+const badge = defineExtension({
+  name: 'badge', tags: ['badge'], display: 'inline', scope: 'local',
+  components: { badge: ({ children }) => <span className="badge">{children}</span> },
+});
+```
+
+`micromark` 接收 micromark syntax extensions 数组，`mdast` 接收 mdast from-markdown extensions 数组。`transform(root, {source, streaming, documentId})` 可以把自定义 AST 节点变换为新的节点类型，再通过 `components[nodeType]` 渲染。保留原始 position，不修改原始 source。没有 position 的生成内容无法提供精确选区映射。
+
+`transform` 默认为全文语义。声明 `scope: 'local'` 的承诺是：已有完整顶层区块的输出不依赖其后的区块，不依赖正在变化的全文上下文；输入末尾重新解析就能保持语义正确。编号、跨段关系等插件应保留默认全文模式。内置 Markdown 引用/脚注定义有单独的全文失效机制。未闭合标签会使用原文回退，完成后重试，结束后总会完整解析。
+
+扩展 name、tag、directive 冲突会抛错。用 `replaceExtension(existing, replacement)` 按 name 替换；组件覆盖可直接放 `components`，角注覆盖可直接放 `annotationTypes`。不做隐式的 parser 覆盖。
+
+## 默认模块
+
+| 工厂 / name | 能力和配置 |
+| --- | --- |
+| `gfm()` / `gfm` | 表格、任务列表、删除线、自动链接、标准脚注 |
+| `math({macros?, strict?})` / `math` | `$...$`、`$$...$$`，KaTeX，不信任执行性命令 |
+| `codeHighlight({languages?, lightTheme?, darkTheme?, eager?, maxLength?})` / `code-highlight` | Shiki；默认靠近视口加载，超过 100,000 字符保留纯代码 |
+| `definition({component?})` / `definition` | `<definition>`，title 属性或 `<title>`，可选 `<content>` |
+| `question({component?})` / `question` | 问题正文、提示、答案、选择题 |
+| `extras({component?})` / `extras` | `<extras><extra title="..." url="..." desc="..." /></extras>` |
+| `video({component?, resolveUrl?, loading?})` / `video` | `<video>` / `<md-video>`，自动识别 native / youtube / bilibili |
+| `figures(options?)` / `figures` | `<figures>` 响应式图组、`<figure>` 单图、图注与图片复制 |
+| `citation(annotationTypeOverrides?)` / `citation` | `<ref>` / `<citation>`，citation 角注类型 |
+| `translations({defaultMode?})` / `translations` | `<translations>`、`<origin>`、`<translation>`；原文、译文、对照与段末切换角标 |
+
+问题的子标签为 `question-content`、`question-hint`、`question-answer`、`question-sel-grp` 和 `question-sel`。选择组用 `answer="[0,2]"` 配置从 0 开始的正确选项编号，`multi="true"` 开启多选。它们是内容组件，不包含提问/聊天角注或服务连接。
+
+视频使用 `url` 或 `src`，默认从 URL 识别平台，也可显式指定 `provider="youtube"`、`"bilibili"`、`"native"`。支持 YouTube watch/短链接/embed/shorts/live 地址及起始时间、Bilibili BV/av 地址及分 P。播放器靠近视口 200px 时才挂载真实 iframe/原生 video，不自动播放；可用 `video({ loading: 'click' })` 或单个标签的 `loading="click"` 改成点击后加载，`"eager"` 则立即加载。视频居中、默认最大宽 560px，16:9；右上角复用公式复制按钮，复制原始 Markdown。
+
+YouTube 使用标准 `youtube.com/embed` 地址，iframe 的 `referrerPolicy="strict-origin-when-cross-origin"` 保留来源站点。播放器的来源要求见 [YouTube 官方文档](https://developers.google.com/youtube/iframe_api_reference#Events)（缺少来源身份可能报 153）。远程平台仍决定视频能否嵌入；本地回归使用请求拦截验证 URL、加载时机和 iframe 参数，不代替真实播放验收。未知标签不执行 HTML；自定义组件对自己的远程请求和 URL 处理负责。
+
+## 图片与论文图组
+
+```markdown
+<figures columns="2" rows="2" min-width="220" min-height="120" max-width="560" max-height="480">
+
+<figure src="/paper/a.png" alt="实验 A" caption="(a) 实验 A" />
+
+<figure>
+
+![实验 B](/paper/b.png)
+
+<figcaption>**(b)** 实验 B，支持 Markdown 图注。</figcaption>
+
+</figure>
+
+<figcaption>图 1 · 两个实验的比较。</figcaption>
+
+</figures>
+```
+
+`figure` 可以独立使用，支持 `src` / `url` 属性，或内部的 Markdown 图片、图片引用及 `<img src="..." alt="..." />`。每个 `figure` 放一张图，多图使用 `figures`；图注可用 `caption` 属性、`<figcaption>` 或 `<caption>`。`id` 可以作为普通 Markdown 页内链接的目标。属性文字保留源文坐标；富文本图注仍可选择、高亮和加角注。也支持 `:::figures`、`:::figure`、`:::figcaption` 指令，单图可写作 `::figure{src="/image.png" caption="图注"}`。
+
+图片在各网格行中垂直居中，图注居中对齐。选择按“图片、该图图注、下一张图片、该图图注、总图注”的阅读顺序进行；属性顺序不同也不会把未选中的图注混进选区。图片高亮描绘实际图片的边框（或所选的下划线样式），图注仍按文字高亮。图片角标叠在图片右下角，保留按钮主题底色；图注角标跟随文字。复制按钮位于外框内部。
+
+| 属性 | 默认值 | 行为 |
+| --- | --- | --- |
+| `min-width` / `min-height` | `220` / `120` | 图片可读尺寸下限，用于决定是否增加列；窄于下限时优先适应容器 |
+| `max-width` / `max-height` | `560` / `480` | 图片尺寸上限，保持比例、不裁切；`none` 或 `false` 取消对应上限 |
+| `columns`（或 `cols`） | 自动 | 指定列数，上限 24 |
+| `rows` | 自动 | 单独指定时按图数推导列数；同时指定行列时预留行，超出内容继续排入新行 |
+| `responsive` | `true` | 显式列数无法满足可读尺寸时逐步减列；`false` 保留列数，允许小图 |
+| `gap` | `16` | 图组间距，像素 |
+
+尺寸接受非负数字或 `px`，模块工厂对应驼峰参数，例如 `figures({ maxHeight: 360, maxWidth: false })`。`figures` 的尺寸限制由内部 `figure` 继承，单图属性可覆盖。最小高度也保留媒体区域的留白；长宽比使上下限无法同时满足时，最大尺寸及容器宽度优先，图片不会变形。
+
+自动布局从一列开始，结合图片加载后的真实比例：当前列达到可用最大宽度后，还有空间容纳另一张达到最小宽、高的图，才增加一列。最大高度同样会限制可用宽度。明确关闭全部尺寸上限时，自动布局保持一列；需要多列可设置 `columns` / `rows`。这里的上限约束图片，不裁切较长的图注。
+
+单图按钮复制 **图片 URL**，沿用 infilearn 的行为；相对 URL 保留原来的相对形式。图组按钮复制完整的 **Markdown 源码**。复制不读取图片二进制，也不要求图片服务器允许跨域读取；浏览器拒绝剪贴板写入时会显示失败提示。
+
+## 分段译文与全局参数
+
+```markdown
+<translations default="origin">
+
+<origin>
+
+Original **Markdown**. It can include lists, images and citations.
+
+</origin>
+
+<translation>
+
+翻译后的 **Markdown**，同样可以包含列表、图片和引用。
+
+</translation>
+
+</translations>
+```
+
+`default` 接受 `origin`、`translation`、`both`，默认 `origin`。对照时先显示译文，再显示原文。角标位于最后一段显示内容的末尾，用圆角线条的原文页、译文页、并排页图标表示状态，悬浮提示及无障碍名称说明当前状态和下一步操作，依次切换“原 → 译 → 对照 → 原”。内容高度和透明度共同过渡，支持中途反向切换与减少动态效果偏好；隐藏内容保持挂载并设置 `inert`，其角注不会生成同步侧栏卡片。流式生成期间只有一侧内容时，先显示已到达的内容。
+
+这是 `translations()` 模块通过公共 `InlineMarker` 和 `renderChildren(nodes, { trailing })` 注入的操作，不生成 `Annotation`，不打开浮层或侧栏。`InlineMarker` 也可用于插件自己的纯操作角标；最后一个节点是段落时 `trailing` 放在段内，其余块类型放在块后。
+
+```tsx
+const [mode, setMode] = useState<TranslationMode | undefined>();
+
+<Reader
+  source={source}
+  parameters={{ translationMode: mode, onTranslationModeChange: setMode }}
+/>
+```
+
+`translationMode` 覆盖各块的 `default` 和本地选择；设回 `undefined` 后恢复各块原来的本地选择。传入 `onTranslationModeChange` 时，角标会请求修改全局模式；只有全局值而没有回调时，角标只显示当前模式，不允许局部绕过外部控制。不同阅读器的参数相互隔离。
+
+插件参数是通用能力，不需要修改 LiMR 内核：
+
+```tsx
+import { useRendererParameter, type RendererExtension } from '@linloir/limr';
+
+declare module '@linloir/limr' {
+  interface RendererParameters { glossaryDetail?: 'short' | 'full' }
+}
+
+const glossary: RendererExtension = {
+  name: 'glossary', tags: ['glossary'],
+  parameters: { glossaryDetail: 'short' },
+  components: {
+    glossary: ({ children }) => {
+      const detail = useRendererParameter('glossaryDetail');
+      return <aside data-detail={detail}>{children}</aside>;
+    },
+  },
+};
+
+<Markdown source={source} plugins={[glossary]} parameters={{ glossaryDetail: 'full' }} />
+```
+
+模块在 `RendererExtension.parameters` 注册默认值；宿主通过 `Reader`、`Markdown` 或 `DocumentProvider` 的 `parameters` 覆盖。后注册模块可以覆盖同名默认值。hook 仅订阅所请求的值，参数变化不会重新解析 Markdown，卡片中的 `AnnotationMarkdown` 也继承宿主参数。
+
+## 角注类型
+
+```tsx
+const glossary = defineAnnotation<{ title: string; body: string }>({
+  type: 'glossary', label: '术语', icon: '◎', color: '#548b74',
+  Content: ({ data, presentation }) => <div>
+    <strong>{data?.title}</strong>
+    <AnnotationMarkdown source={data?.body ?? ''} />
+  </div>,
+});
+```
+
+注册类型与放置角注是独立操作。类型定义 icon、可选 Marker 组件、内容组件和可选的数据加载器；数据通过 annotations、文档命令或自定义语法 transform 生成。
+
+`icon` / `Marker` 只负责图形；按钮、点击、悬浮、可访问标签和大小由 LiMR 管理。推荐带方形 `viewBox`、`currentColor` 的 SVG，图形在 viewBox 中居中，不需要写外层按钮、sup 或尺寸。图标槽会限制超大 SVG/图片、嵌套组件的尺寸与溢出，统一普通和插件角标的尺寸，并重置装饰性 HTML 包裹层的字体基线。复杂自定义图形仍应在自己的 viewBox 内留出边界；槽位不能修复 SVG 内部画偏或留白不对称。可通过 `--limr-mark-size` 修改整套角标尺寸。
+
+`Content` 接收 `annotation`、`data`、`presentation`（preview/expanded/sidebar）、`expanded`、`editing`、`loading`、`error`、`retry`。可以按展示模式显示摘要或完整 UI；`editing` 来自 `editAnnotation(id)` 或 `addAnnotation(annotation, { edit: true })`。`load(annotation, {signal})` 只在需要展示内容时调用，必须遵守 signal；同一注释在侧栏和浮层之间共享请求和结果。更换不可变 annotation 对象会换资源标识；显式 `invalidateAnnotation(id)` 或 `retry()` 可重新加载。缓存按阅读器隔离，结果采用有限 LRU；不会把一个应用用户的数据共享给另一阅读器。
+
+`color` 同时作为角标、默认侧栏标题/装饰条/淡色背景及公共浮层标题的主题色，未激活的装饰条也保留主题色。`sidebar.color`、`borderColor`、`titleColor`、`textColor`、`excerptColor`、`previewColor` 可分别覆盖侧栏主题色、未激活装饰条、标题、正文、关联文本和标题下的预览；不指定正文颜色时沿用阅读器正文色，支持 CSS 颜色和变量。`Content` 和 `Preview` 可以给局部元素单独设置颜色，不会被骨架强制覆盖。多条注释共用一张卡片时，首条注释决定卡片主题，各条目的内部富文本仍由模块控制。
+
+默认侧栏卡片顶部始终显示灰色的关联文本区（`.limr-sidebar-reference`），单行省略，完整文本放在 `title` 中。选区角注展示关联范围的可读文本，去掉 Markdown 标记并解码实体；嵌入式 `<ref>` 展示所在段落。它由 LiMR 根据 occurrence 生成，展开后仍保留，模块无需在 Content 内重复渲染。页面级 `renderCard` 接管时可自行选择是否提供关联区域。
+
+收起时，标题下面的摘要由模块的 `sidebar.Preview` 组件渲染。它接收 `AnnotationSidebarPreviewProps<T>`：`annotation`、`data`（本地 `annotation.data`）、`occurrence`、同组的 `annotations` 和上方的 `referenceText`。同组首条注释的模块负责整组预览，可以自行合并摘要或显示数量。默认最多两行，`sidebar.previewLines` 可设置正整数行数；展开后预览收起，改为显示完整 `Content`。设 `Preview: false` 或组件返回 `null` 可关闭预览，不留下空白间距。未配置预览的模块保持只显示标题。
+
+预览不会触发 `load`，也不需要挂载完整内容。远程模块应随本地注释携带摘要字段；摘要更新后预览跟随 `updateAnnotation()` 更新。建议使用简短文字或轻量富文本，不要在 Preview 里启动完整会话或远程加载。返回链接、按钮时，它们保留自身交互，其余预览区域点击展开卡片。
+
+```tsx
+defineAnnotation<{ question: string; answer: string }>({
+  type: 'assistant', label: '询问助手', color: '#8b5cf6',
+  Content: ({ data }) => <AnnotationMarkdown source={data?.answer ?? ''} />,
+  sidebar: {
+    Preview: ({ data }) => data?.question ? <span title={data.question}>{data.question}</span> : null,
+    previewLines: 2,
+    textColor: 'var(--limr-text, #1a1a1a)',
+    previewColor: 'var(--limr-secondary, #7b756e)',
+  },
+});
+```
+
+Citation 的默认预览依次使用 `summary`、`description`、安全 URL、标题；摘要和描述去掉 Markdown 标记并解码实体，同组引用按顺序拼接。`summary` 可通过注释 data 或 `<citation summary="简短摘要" ... />` 提供；有 description 时，展开显示完整 description。`citation({ sidebar: { Preview: MyPreview, previewLines: 3 } })` 可替换展示，`Preview: false` 可关闭。只覆盖颜色或行数会保留默认预览。
+
+**模块内容边距约定：** 默认卡片由灰色关联区和 `.limr-sidebar-card-body` 两块组成，中间保留 `1px` 分隔（`--limr-sidebar-reference-gap`）。两区共享 `--limr-sidebar-padding-inline`，默认 `10px`，关联文本、标题、预览和展开正文的文字起点必须对齐；不要在模块根节点再加水平 padding、margin 或 text-indent。修改横向留白应调整共享变量，不要分别改两区。逻辑方向属性保证 RTL 使用同一约定。
+
+骨架负责标题到预览/正文的间隔；通用内容区底部比顶部多 2px，补足文字基线带来的视觉差异。模块只负责内部段落间距，不要再给 `Content` 或 `Preview` 根节点添加卡片 padding 或用于补偿底部的空段落。骨架清除内容根节点首尾 margin；自定义包裹层中的段落边距由模块处理，Markdown 内容推荐使用 `AnnotationMarkdown`，它会清除末段 margin，包含 source-binding 包裹层和绘制层的情况。不同字体的视觉留白仍需按实际字形检查。
+
+Citation 保留专用间距：多条目的底部补偿及条目间隔不受通用骨架的 2px 调整影响；单条目展开时底部比多条目少 2px。请分别验证带描述/不带描述、单条/多条、普通文本/Markdown、加载中/流式回答和浅色/深色，不要通过统一增减所有卡片的底部 padding 修正某一种内容。
+
+模块通过 `overlay.Card` 接管悬浮和展开卡片的全部内部 UI，包括标题、正文、操作和底栏。`AnnotationOverlayCardProps<T>` 提供 `annotation`、`occurrence`、`presentation`、`expanded`、`pinned`、`canExpand`、`expand()`、`collapse()`、`close()`，以及已经接入各条目 `Content` 和缓存的 `children`。LiMR 只保留浮层定位、挂载、动画和焦点管理。自定义正文可用 `data-limr-card-body` 标记淡入区域。
+
+可以选用公共布局组件，标题仍由模块决定：
+
+```tsx
+import { AnnotationCard, type AnnotationOverlayCardProps } from '@linloir/limr';
+
+function ConversationCard(props: AnnotationOverlayCardProps) {
+  return <AnnotationCard {...props} title="询问助手" />;
+}
+```
+
+不需要默认布局时直接返回自己的 header、正文和操作按钮即可。`Card` 使用同一个组件处理两种 presentation，避免切换时丢失输入状态。兼容旧的仅 `Content` 定义时，默认布局以类型 `label` 作为标题。
+
+浮层是否允许展开、展开的布局由角注模块声明，默认不展开。点击没有展开能力的角标会固定预览，触屏也可滚动阅读、点击关闭；Citation 默认采用此行为。
+
+```tsx
+defineAnnotation({
+  type: 'conversation', label: '对话', Content: Conversation,
+  overlay: { Card: ConversationCard, expand: { placement: 'center', width: 680, height: '80dvh' } },
+  sidebar: { collapseOnContentClick: false },
+});
+
+defineAnnotation({
+  type: 'detail', label: '详细说明', Content: Detail,
+  overlay: { expand: { placement: 'anchor' } },
+  sidebar: { collapseOnContentClick: true },
+});
+```
+
+`overlay.expand` 可以是 `false`、`AnnotationExpansion`，也可以是 `(annotation) => false | AnnotationExpansion`，按数据选择。`placement: 'anchor'` 保持预览靠近角标的一侧边缘，在原地按内容增高；`'center'` 在整个页面的 visual viewport 居中，不受正文列宽或内部滚动容器限制。可设 `width`、`height`、`maxHeight`（数字为 px，字符串为 CSS 长度）；省略 height 时按内容高度，省略 width 时 anchor 保持预览宽度、center 使用 640px。`overlay.previewWidth` 可单独设置预览宽度。尺寸始终受可视区域限制，包括移动键盘。
+
+展开从脚注预览的位置和尺寸放大，关闭缩回该位置和尺寸并淡出；触摸和工具栏直接打开时会先隐式测量实际预览。外壳独立变形，文字和控件保持正常比例。展开、收起复用同一组件与请求，模块可根据 `presentation` 改变内容；关闭动画可被重新打开打断，完成后才卸载。
+
+`sidebar.collapseOnContentClick` 默认 false，Citation 也保持 false。Citation 条目悬浮时显示下划线，有 URL 时点击标题或说明可以跳转；标题栏负责展开/收起。自定义模块启用该选项后，展开卡片的普通文字/空白区域可点击收起，链接、按钮、输入框、选中文本和 `[data-limr-card-interactive]` 区域保留自身交互。模块仍可用 `useLiMR().activateAnnotation(null)` 自行关闭。多个角注共用一个角标时，首个角注决定浮层 Card 和布局，`children` 保留所有条目各自的 Content；侧栏仅在所有角注类型均启用后才允许点击内容收起；页面级 `renderCard` 可完全替换侧栏卡片行为。
+
+自定义语法可以生成 `annotationDefinition` 节点，其 `annotation` 字段为完整数据；生成 `annotationReference` 节点，其 `annotationIds` 为引用的 ID 数组，position 对应角标位置。也可以完全不添加语法，直接给用户选中的范围添加外部 annotation。
+
+## 工具栏插件与展开面板
+
+工具栏默认包含高亮和复制。插件将 `SelectionAction` 放入 `actions` 即可追加入口；`icon` 是必填字段，推荐 `currentColor`、圆润线端和方形 viewBox。LiMR 将 SVG、图片或嵌套图形限制到统一的图标槽中；内部图形的留白和视觉重量仍需由插件作者控制。内置的 `ToolIcon` 提供同一设计语言的常用图形。
+
+```tsx
+import { ToolIcon, defineExtension, type ToolbarActionContext } from '@linloir/limr';
+
+function Settings({ context }: { context: ToolbarActionContext }) {
+  return <button disabled={context.busy} onClick={() => void context.run(current => {
+    current.addAnnotation({
+      id: crypto.randomUUID(), type: 'my-note',
+      range: current.selection.syntax.ranges[0], data: { text: current.selection.text },
+    });
+    current.clearSelection();
+  })}>保存选中文本</button>;
+}
+
+const noteTool = defineExtension({
+  name: 'note-tool',
+  actions: [{
+    id: 'note-tool:add', label: '记一笔', icon: <ToolIcon name="note" />,
+    run: context => context.expand(),
+    renderExpanded: context => <Settings context={context} />,
+  }],
+  // 另行注册 my-note 的 annotationTypes，定义卡片内容。
+});
+```
+
+`renderExpanded` 自动接入悬浮展开、键盘入口、尺寸约束与选区保留；触屏点击动作本身展开。可选 `onHover(context)` 接入自定义悬浮行为。`context.annotations` 是当前片段绑定的所有 annotation，`context.highlight` 是其中的高亮 annotation；`label(context)` / `icon(context)` 可以随状态改变。展开内容的操作使用 `context.run(operation)` 统一处理忙碌与异常。完整自绘 `render` 槽位的控件与可访问性由模块自行管理。
+
+面板的最大可用高度由 LiMR 决定，通过 `--limr-toolbar-panel-height` 暴露；默认上限 260px，样式包可设置 `--limr-toolbar-panel-max-height`。插件使用自然高度和响应式宽度，骨架在实际溢出时提供不占内容宽度的细滚动条，无需插件重复处理滚动。第三方皮肤可覆盖工具栏的颜色、圆角、字体与面板宽高，详见[样式指南](styles.md)。
+
+[notes.tsx](../examples/notes.tsx) 将旁注、笔记、提问和脚注拆成四个直接操作，使用 `addAnnotation(..., { edit: true })` 创建带原文 quote 的锚点、共享高亮并进入编辑。宽屏在侧栏编辑，窄屏直接打开卡片；草稿存入 annotation data，跨布局切换仍然保留。编辑框透明无边框、随内容增高，支持 Markdown 换行及 Ctrl/Cmd+Enter 提交。修改、删除、取消和提交采用右对齐的图标文字按钮，复用 `.limr-underline`。Playground 的模块样式在 `playground/playground.css` 的 `.demo-note-*` 中，移植时可替换为应用自己的样式。插件的卡片内容与业务状态由插件负责，骨架只管理定位、激活、编辑状态和滚动。
+
+## 助手插件的协作方式
+
+[assistant.tsx](../examples/assistant.tsx) 是完整、经过浏览器验证的例子：
+
+1. 插件在 `actions` 注册选区菜单入口。
+2. 动作从选区创建一个具有原始范围和 quote 的自定义 annotation。
+3. 用 `activateAnnotation(id)` 打开卡片，清空菜单选区。
+4. 应用 adapter 产生 `AsyncIterable<string>`；每个片段调用 `updateAnnotation()`。
+5. 自定义 Content 使用 `AnnotationMarkdown streaming` 渲染回答。
+6. Reader 卸载时中止请求，动作不再更新已卸载的文档。
+
+示例支持 `prompt(selection)` 生成首个问题，保存到 `data.question` 并传给 `adapter.answer({ selection, question, signal })`。`sidebar.Preview` 显示这个问题，流式回答只更新答案，不覆盖问题；中文页面可配置 `prompt: selection => \`请解释「${selection.text}」。\``。接入已有对话时，应用也可提供自己的 Preview 展示首条用户消息。
+
+示例只从 `@linloir/limr` 的公共入口导入，可以复制到应用中使用。真实 Codex 集成可以实现同一个 adapter，也可以自行实现更复杂的组件、对话状态、输入框和动作。LiMR 不把助手的传输、认证、问题/答案 schema 写入内核。
+
+插件任务的取消信号来自动作的生命周期上下文。若业务还需要“停止生成”、重试、切换会话等控制，可由插件自己的 AbortController 与 context.signal 联动。角标保留哪个历史回答、是否保存、如何鉴权，也由应用决定。
+
+## 作为独立包分发
+
+插件导出一个返回 `RendererExtension` 的工厂，消费者通过 `plugins={[yourPlugin(options)]}` 添加即可。`plugins` 会追加到 `extensions`（未指定时为 `standard()`），无须消费者重复列出默认模块。以 `@linloir/limr` 和 `react` 为 peerDependencies，导出 ESM 和类型声明；不要把另一份 React 或 LiMR 打包进插件。
+
+[`examples/packages/reading-tools`](../examples/packages/reading-tools) 演示一个同时提供语法、角注内容和选区动作的独立包，[`paper-theme`](../examples/packages/paper-theme) 是独立 CSS 包。`pnpm test:package` 会先打包，再在仓库外安装这些包与 LiMR，验证 React 18/19 的类型、SSR、浏览器交互和 portal 样式。示例包名未发布到 npm；发布自己的包时替换 name、version，并移除 private。
+
+仅样式包无需 React 或解析器依赖。使用 `appearance` 属性选择作用域，使多个阅读器和浮层使用正确主题；详见[样式指南](styles.md)。

package/docs/implementation.md

@@ -0,0 +1,79 @@
+# LiMR implementation and acceptance
+
+The agreed scope is a standalone React Markdown package preserving the original
+renderer's reading style and capabilities while making syntax,
+annotation types, selection actions, layout and resource loading extensible.
+Long-document reading and streaming output are equal first-release requirements.
+All original special syntax modules belong to LiMR's default extensions, with
+individual imports, replacement and opt-out. There is no platform-specific preset.
+Default annotations are reference citations only; highlighting is a core capability.
+Question/note/chat annotations belong to application plugins. Question content
+blocks remain a default syntax extension. Plugins can contribute menu actions,
+annotation types and streaming content updates through document commands.
+
+## Required deliverables
+
+- DOM-free document engine, original UTF-16 offsets, immutable document snapshots,
+  stable blocks, incremental append with reference dependency invalidation.
+- CommonMark/GFM, math, highlighting, images, figures, videos, questions,
+  definitions, extra reading, citations; each special capability is an extension.
+- Public parser and component extension APIs; replace/disable built-ins; no
+  execution of Markdown-supplied JavaScript or unregistered HTML.
+- Markdown, DocumentProvider, Reader, TableOfContents, AnnotationSidebar,
+  AnnotationOverlay, SelectionToolbar; standalone and composed use.
+- Generic annotation types, occurrence anchors, custom icons/content, recursive
+  Markdown with isolated document scopes and shared configuration/resources.
+- Raw, syntax-complete and block selections; extensible atomic selection behavior;
+  versioned selection snapshots and programmable highlights.
+- Scroll-root convention, sidebar collision handling and custom positioning;
+  wrapping/fixed-title/hidden-scrollbar TOC with active-item following.
+- Pointer previews, touch/click expansion, content-column sizing, viewport and
+  keyboard accommodation, focus/keyboard behavior and configurable portals.
+- Bounded caches, deduplicated/cancellable optional data loaders, no implicit CDN
+  font/style requests; local math assets and optional self-hosted font guidance.
+- Classic light/dark theme, SSR/multiple documents, streaming incomplete syntax,
+  final equivalence and opt-in follow-output without fighting user scrolling.
+- Package exports/types/assets; examples and API/extension documentation.
+- Core/SSR tests, real-browser interaction/layout tests, pack/consumer smoke,
+  visual review and reproducible static/streaming performance measurements.
+
+## Decisions
+
+Use mdast/micromark for standards-compatible parsing. Share the parsed document
+across all views. Roll back the final top-level block on append; maintain a
+definition environment for suffix parsing; invalidate previous nodes when
+document-wide definitions change. Unknown whole-document transforms fall back
+to a full parse. Never claim arbitrary plugins are incrementally safe.
+
+The public core has no React or DOM runtime dependency. React renderers own
+their DOM, including marks. Layout reads, selection and document changes use
+separate subscription channels. Source offsets always refer to the original
+input, including legacy tag syntax.
+
+Do not claim performance parity until the measurements cover equivalent
+features. Virtualization is optional future work unless a verified implementation
+preserves selection/search/printing; the default reading mode retains document
+semantics.
+
+## Verification completed
+
+- `pnpm check`: strict TypeScript checking, 32 core/resource/runtime/SSR tests,
+  ESM declaration build and copied local math assets.
+- `pnpm test:browser`: 11 Chromium tests covering desktop rendering, three
+  selection variants, highlights, TOC follow/clamping, shared internal scroll
+  roots, sidebar alignment, pointer and touch cards, reduced visual viewport,
+  plugin streaming/cancellation, multiple documents, SSR hydration, resource
+  handoff/cache invalidation and decoded native-text source mapping.
+- `pnpm test:package`: install the actual tarball in isolated React 18.3 and
+  React 19 consumers; check public TypeScript declarations, SSR, extension
+  imports and every math font URL. Verify the core entry with a loader that
+  rejects React imports. The resulting archive is copied to `artifacts/`.
+- Production Node and isolated-browser benchmarks are reproducible; complete
+  measurements and limitations are in `docs/performance.md`.
+- Desktop, content-block and mobile plugin screenshots are in `docs/screenshots/`.
+  The playground explicitly supplies its own local demo font; package CSS does
+  not fetch a body/code font.
+
+The assistant example uses a local simulated adapter. Real service connections
+and authentication belong to the consuming application. No remote publication,
+real mobile-device acceptance or arbitrary-plugin performance claim is included.

package/docs/performance.md

@@ -0,0 +1,84 @@
+# 性能测量
+
+日期：2026-10-12。环境为 Intel Core i7-13700、WSL2/Linux、Node 20.19.5、Chromium 156.0.8078.4。React 19 production build；对照为 react-markdown 10.1.0 + remark-gfm 4.0.1。
+
+以下是本机固定夹具的实测值。浏览器静态渲染与基线接近；流式追加减少了明显的重复工作。几个百分点的静态差异不应解读为所有设备和内容上的胜负；本轮 Node 长文 SSR 波动较大，也没有显示出性能优势。
+
+## 浏览器
+
+双方都渲染同一份 GFM：标题、强调、链接、行内代码、列表和表格，使用相同排版样式。LiMR 开启正常交互和原文映射能力。这里只比较正文，不把目录、侧栏等基线不具备的 UI 算进去。
+
+每组运行三次、取中位数；每次用独立页面，先预热并等待字体，交替运行两个渲染器，避免上一组 DOM/内存影响下一组。计时范围是同步 React 提交和一次强制布局；不计网络下载、异步重资源加载、帧间空闲时间及后续观察器工作。
+
+| 场景 | LiMR | react-markdown |
+| --- | ---: | ---: |
+| 87,381 字符，200 节，首次挂载 | 126.1 ms | 134.0 ms |
+| 877,782 字符，2,000 节，首次挂载 | 1,345.4 ms | 1,437.6 ms |
+| 34,860 字符，256 字符/次，138 次提交，累计同步时间 | 306.1 ms | 1,864.1 ms |
+| 同一流式场景，单次提交 P95 | 2.9 ms | 23.7 ms |
+
+本次流式累计同步时间约为基线的 **1/6.1**。末次提交执行最终完整解析，也包含在统计内。三轮 LiMR 流式单次最大值为 31.1–31.8 ms，不能将 P95 解读为每一帧都小于 16 ms。
+
+长文夹具最终 DOM 元素数：LiMR 40,002，基线 36,001。差异主要来自表格滚动容器、代码文本映射及一个选区绘制层；普通段落、标题和文本不再依赖额外包裹层。未使用虚拟化，浏览器仍能搜索、选择和打印整个文档。
+
+原始样本：[browser.json](../benchmarks/results/browser.json)。
+
+## 持续拖选
+
+真实鼠标持续按下并移动 90 次，结束前统计更新和绘制，不能用松手后的单次更新通过检查。每组使用三个独立页面，等待字体和代码着色后开始；下表展示按手势总时长排序的中间样本。绘制延迟是 `selectionchange` 到覆盖层 DOM 变更的间隔，帧间隔由 rAF 采样，均不等同于硬件输入到屏幕呈现的延迟。
+
+| 场景 | 原生选区变化 | 拖动中的更新 / 绘制 | 绘制延迟 P95 | 帧间隔 P95 | 长任务 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| LiMR：877,782 字符，8,000 区块 | 91 | 75 / 75 | 25.2 ms | 16.8 ms | 0 |
+| react-markdown：同一篇长文 | 91 | 无自定义覆盖层 | 不适用 | 16.7 ms | 0 |
+| LiMR：1,000 行 Shiki 着色代码 | 51 | 47 / 47 | 19.3 ms | 16.8 ms | 0 |
+
+三轮长文的绘制延迟 P95 为 25.2–28.5 ms，代码为 18.9–19.4 ms。一次绘制只保留视口内片段；这两个手势结束前分别有 11、12 个绘制矩形。浏览器回归还会全选全文并滚动到中间，要求可见绘制跟随滚动且矩形数少于 250。
+
+同一自动化长文手势在 LiMR 中耗时 3.23 秒，基线为 1.52 秒；基线没有原文映射和自定义覆盖层，不能用接近的 rAF 间隔宣称两者输入处理成本相同。保留全部样本以便继续比较，见 [selection.json](../benchmarks/results/selection.json)。
+
+回归预算：更新及绘制次数均超过原生变化的 60%，绘制延迟与帧间隔 P95 小于 40 ms，拖动期间没有超过 100 ms 的任务。测试使用单 worker，避免并发浏览器争抢资源扭曲结果。该预算是当前夹具的回归门槛，不是任意设备的性能保证。
+
+## Node / SSR
+
+core 对照为同版本 mdast-util-from-markdown + GFM。core 除解析外还生成标题、脚注、角注、区块和原文元信息。SSR 对照使用等价 GFM 功能；没有把未加载的代码高亮或公式冷启动算成渲染优势。
+
+| 场景 | LiMR | 对照 |
+| --- | ---: | ---: |
+| 87,381 字符，核心处理 | 109.32 ms | 101.78 ms |
+| 877,782 字符，核心处理 | 2,702.76 ms | 2,864.73 ms |
+| 87,381 字符，SSR | 123.85 ms | 135.80 ms |
+| 877,782 字符，SSR | 5,508.29 ms | 2,720.70 ms |
+| 34,860 字符，137 次核心追加及收尾，累计 | 164.04 ms | 2,673.74 ms |
+
+核心追加对照每次重新解析整个前缀。不同组分别预热，GC 和 JIT 会影响数值，因此不能把“核心处理”和“SSR”两行相减当作精确的 React 渲染成本。本轮长文 SSR 的 LiMR 样本范围为 2.64–9.10 秒，对照为 2.70–5.03 秒；中位数明显较慢，波动原因未归因，不据此承诺长文 SSR 与基线相当。原始区间：[node.json](../benchmarks/results/node.json)。
+
+## 实现要点和边界
+
+- 追加时回退到末尾尚未稳定的顶层区块。先前的 Markdown 定义作为解析环境；新定义影响前文时完整校正；生成结束时完整解析。
+- 源文本从不预处理改写，坐标是原始 UTF-16 偏移。普通文本在真正选择时才建立 DOM 文本节点到源码的映射；装饰和自定义布局按需采用显式绑定。
+- 区块和未变化的目录保持引用稳定；交互、布局与文档分开更新。滚动不会触发重新解析。
+- 选区跟踪按 rAF 合并事件，取消会被持续拖动反复重置的 debounce。语法扩展仅检查边界祖先；绘制按可见区块二分定位、缓存文本映射与字体测量，复用矩形元素。绘制层自身也限制为视口高度，减少超长页面上的布局和命中测试工作。
+- 代码接近视口时加载所需语言/主题；流式代码暂停后高亮。公式和视频分别按需加载或点击加载。
+- 角注的缓存按阅读器隔离。浏览器测试覆盖了预览切换展开时复用同一请求、再次打开命中缓存、数据变更后重新请求；默认渲染没有第三方 CDN 请求。
+
+尾部若是非常长的单个代码块、列表或未闭合标签，重新解析该区块的成本仍会增长。全文 transform、修改中间内容、引用定义变化和收尾都会触发完整解析。这不是任意语法、任意编辑模式下的常数时间增量解析器。
+
+这里的性能数据没有覆盖大型公式集、Shiki 冷启动、密集外部注释、第三方插件、完整 Reader 布局或真实移动设备。相关功能另有交互验证，但不能从这些 GFM 数据推导出它们的性能承诺。
+
+## 复现
+
+在仓库中运行，测量时不要并行运行构建或其他基准：
+
+```sh
+NODE_ENV=production pnpm bench
+pnpm exec vite build
+pnpm exec vite preview --host 127.0.0.1 --port 4174
+# 另一个终端：
+pnpm bench:browser
+pnpm bench:selection
+# 浏览器交互与持续拖选回归：
+pnpm test:browser
+```
+
+脚本及夹具位于 `benchmarks/`、`playground/benchmark.tsx` 和 `playground/selection-benchmark.tsx`；结果写入 `benchmarks/results/`。

package/docs/styles.md

@@ -0,0 +1,103 @@
+# 样式与交互外观
+
+`@linloir/limr/styles.css` 提供默认 classic 样式和代码字体。所有默认规则位于 `@layer limr`；应用或样式包的普通 CSS 可以直接覆盖，无须提高选择器优先级。`appearance="paper"` 会传播到正文、目录、侧栏、选区工具栏和 portal 浮层，适合同页存在多个阅读器的场景。
+
+```tsx
+import '@linloir/limr/styles.css';
+import '@your-scope/limr-theme-paper';
+<Reader source={markdown} appearance="paper" theme="dark" />
+```
+
+主题包可只包含 CSS，并将 `exports["."]` 指向该文件、`sideEffects` 设为 `["**/*.css"]`。用 `[data-limr-appearance='paper']` 包裹 token 和规则，不依赖 `.limr-reader` 作为 portal 的祖先。自定义组件使用稳定的 `.limr-*` 类，状态由 `data-active`、`data-expanded`、`data-open`、`data-status` 等属性表示。
+
+| CSS 变量 | 用途 |
+| --- | --- |
+| `--limr-font-text`, `--limr-font-code` | 正文与代码字体栈 |
+| `--limr-font-size`, `--limr-line-height` | 正文字号和行高 |
+| `--limr-font-features` | 正文 OpenType 特性，默认 `'palt' 1`，使中文字体的弯引号等标点采用比例宽度；`normal` 可恢复字体原有宽度 |
+| `--limr-emphasis-spacing` | 斜体末尾的光学留白，默认 `.08em`；不改变左侧间距 |
+| `--limr-list-item-gap` | 列表项和嵌套层级前后的统一间距，默认 `.375rem` |
+| `--limr-text`, `--limr-heading`, `--limr-secondary`, `--limr-muted` | 文本层次 |
+| `--limr-background`, `--limr-surface`, `--limr-border` | 背景与边框 |
+| `--limr-link`, `--limr-accent`, `--limr-selection` | 链接、激活与选区颜色 |
+| `--limr-code-bg`, `--limr-code-header`, `--limr-inline-code` | 两种主题下的代码颜色 |
+| `--limr-mark-size` | 角标方形边长，默认 `.92em`，统一使用正文基准字号 |
+| `--limr-motion-fast`, `--limr-motion`, `--limr-motion-slow`, `--limr-ease` | 动画时长与曲线 |
+| `--limr-overlay-duration` | 悬浮预览展开/收回共用时长（560ms）；兼容旧变量 `--limr-overlay-enter-duration` |
+| `--limr-overlay-morph-duration`, `--limr-overlay-ease` | 预览与大卡片变换时长（480ms），浮层曲线（`cubic-bezier(.22,1,.36,1)`） |
+| `--limr-video-width`, `--limr-definition-math-bg` | 视频最大宽度与释义块内公式背景 |
+| `--limr-content-width`, `--limr-reader-width`, `--limr-sticky-top` | 布局上限及吸顶位置 |
+| `--limr-toc-width`, `--limr-sidebar-width`, `--limr-column-gap` | 三栏宽度与间隔；默认侧栏随容器增宽 |
+| `--limr-reader-min-height`, `--limr-reader-bottom-space` | 短正文的最小高度与视口底部预留空间；默认自动填充并预留 24px |
+| `--limr-annotation-color`, `--limr-annotation-border`, `--limr-annotation-title`, `--limr-annotation-text`, `--limr-annotation-excerpt` | 模块通过 `color` / `sidebar` 配置提供的卡片局部色值 |
+| `--limr-sidebar-padding-block` | 通用侧栏卡片顶部留白，默认 `.65rem`；底部额外补足 `2px`，Citation 使用独立规则 |
+| `--limr-sidebar-padding-inline` | 关联区与内容区共用的水平留白，默认 `10px`；标题、预览、正文的文字起点一致 |
+| `--limr-sidebar-reference-gap` | 灰色关联区与下方内容区之间的分隔，默认 `1px` |
+| `--limr-toolbar-background`, `--limr-toolbar-border`, `--limr-toolbar-shadow`, `--limr-toolbar-radius` | 工具栏浮层背景、边框、阴影、圆角（默认 `6px`） |
+| `--limr-toolbar-font-size`, `--limr-tool-icon-size`, `--limr-toolbar-accent` | 工具栏文字（默认 `.75rem`）、图标（`18px`）、选择框颜色（沿用 `--limr-accent`） |
+| `--limr-toolbar-panel-width`, `--limr-toolbar-panel-max-height` | 展开内容宽度（默认 `246px`，不含内边距）与高度上限（默认 `260px`） |
+| `--limr-toolbar-panel-height`, `--limr-toolbar-available-height` | 骨架测量得到的面板高度上限与所选方向空间；插件可读取，不应覆盖 |
+
+系统 `prefers-reduced-motion: reduce` 会关闭位移、展开与滚动动画。工具栏文字按钮使用 `.limr-underline` 从左向右展开下划线，不添加悬浮背景；复制成功原位淡出淡入为绿色“已复制”，2.4 秒后恢复。代码块内的图标复制按钮保留独立的背景与图标过渡。默认 `>` 引用块使用“注释 / Note”标题；可用 `components.blockquote` 完全替换其外观。它与插件注册的注记角注类型相互独立。
+
+图片外框使用 `.limr-figure` / `.limr-figures`，继承代码/公式区域的背景和边框色；`.limr-figures-grid` 使用实际测量得出的列数，图片保持长宽比。同一行图片居中对齐、caption 共用行轨道，单图与整组 caption 均居中。图组与单图分别有源码和图片 URL 复制按钮，按钮位于外框内部。`.limr-translations` 内的两个 `.limr-translation-panel` 复用可逆的高度与透明度动画，默认 480ms；隐藏侧设置 `inert`。`.limr-action-mark` 复用普通角标的图标槽与尺寸，原文、译文、对照使用不同的圆润图标，并保留状态提示及无障碍标签。
+
+宽屏参考 infilearn 的正文尺度：阅读器默认最大 `1800px`，正文最大 `900px`，目录和注释栏随容器宽度渐增，列间距默认 `36px`。容器不足 `1120px` 时仍切换为注释浮层，不依赖浏览器窗口宽度。宿主可用上述变量覆盖尺寸。
+
+同步注释侧栏由所在网格行决定高度，并使用 size/layout containment 与 `overflow: clip` 隔离内部位移。短正文自动补足可用阅读高度，注释数量不会撑大页面。悬浮角标驱动侧栏，悬浮卡片则锁定卡片命中区域并平滑移动正文；正文容器裁切位移，不改变页面滚动范围。不要把所有卡片底部的最大值赋给外层 `height` / `min-height`，也不要给这个同步列表添加 `overflow: auto`。卡片正文的长内容滚动与列表定位相互独立。
+
+模块颜色、边距、`sidebar.Preview` 和 Citation 单条/多条补偿的约定见[扩展指南](extensions.md)。可以通过 `.limr-sidebar-card[data-type='assistant']` 定位模块；默认卡片的有色装饰条、背景和 padding 在它的 `.limr-sidebar-card-body` 上，灰色关联区是独立的 `.limr-sidebar-reference`，两者之间留出分隔。`.limr-sidebar-preview` 使用模块配置的预览颜色和行数，展开后隐藏。浮层使用 `.limr-annotation-overlay[data-type='assistant']`，无需依赖阅读器作为 portal 的祖先。
+
+悬浮预览先按最终位置和尺寸排版，再从角标横坐标对应的位置裁切展开，内容不会随动画反复换行。预览在角标上方时从底部展开，在下方时从顶部展开；切换角标会等待新角标的定位结果。视口较矮时，预览高度受对应方向的剩余空间限制。允许展开的模块从预览的位置和尺寸放大至目标布局，关闭时缩回预览位置和尺寸并淡出；触摸、工具栏直接打开也采用同一几何起点。
+
+动画从实时画面重新取样，移开、重入和快速展开/收起均可中途反转。悬浮预览进入和退出共用 560ms，内容和外壳同时结束；鼠标移开后的跨越间隙宽限为 90ms，明确关闭时立即开始动画。组件在退场完成后才卸载，保留请求与组件状态。外壳背景与阴影由 `.limr-overlay-surface` 绘制并独立变形，`.limr-overlay-card` 内的文字、按钮与输入框不缩放。打开时聚焦对话框容器，不自动高亮“收起”按钮，Tab 导航仍保留焦点提示。
+
+窄屏目录使用整行 hover 背景和圆角折线箭头，内容高度、透明度、位移和箭头旋转连续过渡。内容持续挂载、隐藏时 inert，快速点击直接从当前帧反转，没有延迟卸载定时器。
+
+宽屏目录通过不占高度的 sticky 定位容器固定顶部，内部目录按实际可见高度单独限制尺寸，正文末尾不会把目录整体向上推出视口。`--limr-sticky-top` 控制吸顶距离，`--limr-toc-available-height` 由 Reader 测量，不应覆盖。目录标题不参与渐隐；`.limr-toc-scroll` 与正文、注释栏共用 `--limr-overflow-fade-size`（默认 `24px`），仅在对应方向有溢出时淡出，列表自身滚动也会更新渐隐边界。
+
+角标的鼠标命中区域保持固定，hover/按下缩放只作用于内部图形，避免边缘反复触发进入/离开。侧栏展开/收起使用纯文字和下划线渐变，仅悬浮“展开 / 收起”文字或键盘聚焦时触发；切换展开状态时保留卡片 hover。提问选项菱形按第一行文字基线对齐，公布答案时正确选项填充绿色；扩展阅读标题使用正文标题色，副标题字号更小、间距更紧凑。
+
+浮层隐藏原生滚动条，使用不占内容宽度的 3px 覆盖式滚动条（`.limr-overlay-scroll-thumb`）。展开/收起动画期间不显示；实际滚动时淡入，停止 800ms 后淡出，支持拖动滑块。滚轮、触摸和键盘滚动仍由原生滚动容器处理。
+
+## 字体资源和缓存
+
+爱丽丝样例中的撇号是 Unicode 弯引号 `’`（U+2019），不是全角 ASCII 撇号。默认启用字体的比例标点特性以缩小其宽度，不替换源文本，因此复制、选区和 annotation 偏移保持一致。样式包可覆盖 `--limr-font-features`，或通过 `--limr-font-text` 换用自己的字体；特性是否可用取决于字体。代码仍使用独立的等宽字体特性。
+
+两端对齐由渲染器的 `justify` 属性控制，默认关闭。开启时段落和列表使用 `text-align: justify`，末行和显式换行前的行保持起始侧对齐，标题、代码块及表格保持原有排版。选区与高亮使用排版后的实际文字位置测量，包含斜体末尾留白。
+
+默认代码字体来自 [Maple Mono v7.9 的 NF CN 版本](https://github.com/subframe7536/maple-font/releases/tag/v7.9)，保留原版连字、中文、日文、Nerd 图标及原版支持的其他字形。不能把“多语言”理解为所有文字均有字形；缺失字符仍使用系统回退。四个字重/样式文件切分为 unicode-range WOFF2 子集，浏览器只按实际字符请求所需子集，`font-display: swap` 使代码先用系统等宽字体显示。Latin/Greek/Cyrillic 常规子集约 47 KB；完整字体资产约 31 MB，不会在页面初始全部下载。
+
+`src/fonts/manifest.json` 记录来源、原始包摘要、字形覆盖和各文件大小，OFL 许可证随包分发。子集字体使用新名称 `LiMR Maple Mono NF CN`。`scripts/subset-fonts.py` 可从官方 unhinted ZIP 重建资源。WOFF2 文件名包含版本与内容摘要，构建工具可进一步生成哈希资源 URL。
+
+组件无法设置服务器的 HTTP 缓存头。生产部署应对带内容哈希的字体资源返回 `Cache-Control: public, max-age=31536000, immutable`；浏览器是否复用仍取决于 URL、缓存头和用户缓存状态，不应由组件重复 fetch 字体。
+
+本地生产预览的中英混排/希腊/西里尔/Nerd 图标夹具实际请求 4 个 Maple 子集，共 341,440 字节；刷新后没有重新传输字体正文。这是该夹具和预览服务器的观测结果，不能代替宿主应用的缓存配置。
+
+完全使用自己的字体时：
+
+```tsx
+import '@linloir/limr/styles/base.css'; // 默认排版/交互样式，不引入 Maple
+// 可单独 import '@linloir/limr/fonts.css'，或载入应用自己的字体。
+```
+
+## 选区、高亮与移动端
+
+浏览器仍管理原生文本范围、键盘选择、复制与辅助技术；覆盖层统一文本、行内代码、公式及角标的选中高度，不用替换正文或铺设透明文字副本。覆盖层只绘制视口中的片段，并在字体、内容、尺寸和滚动变化后重新计算。全文 DOM 保留，浏览器搜索和打印不受虚拟列表影响。
+
+代码可部分选中；公式按整体选中，块公式继承背景边界与圆角。角标仅在两侧都有文本且范围跨过两侧文本时着色，按钮本身的背景和交互独立。自定义原子组件可给内部实际背景元素添加 `data-limr-selection-surface`，指定覆盖边界和圆角。
+
+图片的选区和背景高亮使用边框，避免遮住图像；下划线样式仍可使用。图片与块公式的角标直接覆盖原有右下角，不增加块高度。图片角标的按钮使用不透明的浅主题底色，不附加白色底板。文字角标与前一个字符共同换行，不单独留在新行；连接字符通过 CSS 生成，不改变源文或复制文本。译文状态图标可用 `--limr-translation-accent` 改色。
+
+侧栏布局优先利用上方留白，把末尾卡片收进可用高度；边界处悬浮不会强行移动正文来追齐角标。正文和侧栏在实际发生上下裁切时使用透明渐隐，跟随窗口、嵌套滚动容器及动画中的真实边界；内容完整时不会淡化边缘，打印时也不保留屏幕蒙版。`--limr-overflow-fade-size` 控制渐隐高度，默认 `24px`，设置为 `0px` 可关闭渐变。
+
+移动视口、触摸点击浮层和 Selection API 的程序化选择有浏览器回归检查。iOS/Android 的系统拖动手柄、放大镜和原生菜单并不能通过网页 CSS 一致接管；保留这些平台控件，不伪装成已在真机上实现了完全自定义触摸选区。实体设备的手指拖动仍需单独验收。
+
+
+工具栏外层 `.limr-selection-toolbar` 只负责定位，`.limr-toolbar-surface` 与各 `.limr-toolbar-item` 分别执行非线性位移和延后淡入。上方工具栏从下向上浮入，下方工具栏从上向下浮入；组件按序延迟 22ms，淡入再稍晚开始。`prefers-reduced-motion` 关闭这些移动和延迟。工具栏优先位于选区下方，为展开内容预留同一份空间预算；展开后按钮行保持靠近选区，面板向外生长。分隔线覆盖整个工具栏宽度，面板内容居左并受宽度约束。
+
+`.limr-tool-icon` 默认 18px，可用 `--limr-tool-icon-size` 覆盖。图标槽约束 SVG、图片及嵌套包装的大小和溢出。文字行高为 1.5，以 1px 底部留白校正视觉中心；内置图标在自身 viewBox 内校正，不对整行施加额外位移。自绘整个 action 的 `render` 槽位需自己复用图标槽或提供等价约束。
+
+面板由骨架的 `OverlayScrollArea` 负责滚动：内容不足预算时自然收缩，溢出时使用 3px 覆盖式滚动条，不挤占内容布局。插件通常不需要设置高度或再提供滚动条；复杂模块可读取上述可用高度变量。外部样式包示例见 [`paper-theme/index.css`](../examples/packages/paper-theme/index.css)。
+
+持久高亮使用 `.limr-highlight-layer`，在各段落、代码或公式背景上方、文字下方绘制；临时选区保留独立的 `.limr-paint-layer`。两个层都只维护视口内的几何，且不拦截指针。高亮悬浮通过正文的坐标命中判断，按叠放顺序选择一个高亮，应用 `data-hovered` / `data-active` 到该高亮的全部可见片段。悬浮侧栏条目、角标或激活 annotation 时，其他片段添加 `data-muted` 暂时隐藏；离开后恢复原本的可见性。打印时隐藏绘制层，恢复语义 mark 的原生装饰。