@linloir/limr 0.0.0-stage → 1.0.0

package/docs/zh-CN/plugin-packages.md

@@ -0,0 +1,68 @@
+# 插件模块包
+
+> 阅读提示：本文包含 LiMR 扩展语法和交互示例。部分内容在 GitHub 等普通 Markdown 阅读器中无法完整展示；前往 [GitHub Pages 文档](https://linloir.github.io/LiMR/#/docs/zh-CN/plugin-packages) 可获得最佳阅读体验。
+
+[文档目录](README.md) · [English](../en/plugin-packages.md)
+
+一个插件包导出返回 RendererExtension 的工厂，消费者安装后通过 plugins 追加。插件可同时提供语法、标注、动作和参数，CSS 独立导出。它不需要修改 LiMR 源码。
+
+## 可复制模板
+
+完整模板位于 [plugin-template](../../skills/limr-plugin-development/assets/plugin-template/README.md)，包含 TypeScript 源码、类型构建、CSS、package.json 和 tsup 配置。它演示 reading-tip 区块、example:note 卡片和保存选区动作。
+
+安装 LiMR 后，在应用目录执行：
+
+```sh
+mkdir -p packages/limr-reading-tools
+cp -R node_modules/@linloir/limr/skills/limr-plugin-development/assets/plugin-template/. packages/limr-reading-tools/
+cd packages/limr-reading-tools
+npm install
+npm run typecheck
+npm run build
+npm pack
+```
+
+源码仓库中的对应路径为 skills/limr-plugin-development/assets/plugin-template。替换模板的 @example 包名、扩展名、类型名和动作 ID，再实现业务数据与 UI；模板的 private: true 用于防止示例名被误发布，不影响本地打包。
+
+## 包契约
+
+| 字段 | 要求 |
+| --- | --- |
+| type | module |
+| exports["."] | import 指向 ESM，types 指向 .d.ts |
+| exports["./styles.css"] | 插件需要 CSS 时显式导出 |
+| files | 包含构建输出与使用说明 |
+| sideEffects | CSS 使用 ["**/*.css"]，避免被构建工具移除 |
+| peerDependencies | @linloir/limr、react；直接依赖 react-dom API 时再声明 react-dom |
+| 构建 external | LiMR、React、react/jsx-runtime，以及使用到的 React DOM 入口 |
+
+LiMR 或 React 的第二份内置副本会破坏上下文/Hook 共享。不要打包宿主依赖，不要深度导入 LiMR 内部文件。参数声明合并必须随导出的类型分发。
+
+## 在应用中引入
+
+下方 @example 包来自模板，并未发布到 npm。先安装本地打出的归档；生成文件名以 npm pack 输出为准：
+
+```sh
+npm install ./packages/limr-reading-tools/example-limr-reading-tools-0.1.0.tgz
+```
+
+```tsx
+import { Reader } from '@linloir/limr';
+import { readingTools } from '@example/limr-reading-tools';
+import '@linloir/limr/styles.css';
+import '@example/limr-reading-tools/styles.css';
+
+const plugins = [readingTools({ label: '阅读笔记' })];
+
+export function Article({ source }: { source: string }) {
+  return <Reader source={source} plugins={plugins} />;
+}
+```
+
+真实第三方包使用它的包名和 peer 版本约束。改写已存在的默认模块使用 extensions + replaceExtension，不要重复注册同一标签。字体、公式样式、持久化和应用服务仍由宿主配置。
+
+## 验证可分发性
+
+本地类型检查通过后，还需把真实 tgz 安装到独立消费者中：检查公开导入、SSR、CSS 资源、默认模块仍可用和新增交互。支持 React 18/19 的包应分别验证两种宿主。语法插件检查流式结束与一次性解析等价；交互插件检查桌面侧栏、窄屏浮层、键盘、异步取消和两种主题。
+
+LiMR 仓库的 [reading-tools](../../examples/packages/reading-tools/index.js) 和 [paper-theme](../../examples/packages/paper-theme/index.css) 是另一组可打包示例。AI 可使用[插件开发 Skill](ai-skills.md)，其中的模板可独立复制，引用文件无需依赖本仓库路径。

package/docs/zh-CN/styles.md

@@ -0,0 +1,80 @@
+# 样式与字体
+
+> 阅读提示：本文包含 LiMR 扩展语法和交互示例。部分内容在 GitHub 等普通 Markdown 阅读器中无法完整展示；前往 [GitHub Pages 文档](https://linloir.github.io/LiMR/#/docs/zh-CN/styles) 可获得最佳阅读体验。
+
+[文档目录](README.md) · [English](../en/styles.md)
+
+## 基础样式和主题
+
+默认 CSS 在 `@layer limr` 中，宿主普通 CSS 可覆盖。选择 styles.css（带 Maple）或 styles/base.css（不加载 Maple）；公式另加 math.css。
+
+```tsx
+import { Reader } from '@linloir/limr';
+import '@linloir/limr/styles/base.css';
+import './paper.css';
+
+export function Paper({ source }: { source: string }) {
+  return <Reader source={source} appearance="paper" theme="auto" />;
+}
+```
+
+paper.css 示例：
+
+```css
+[data-limr-appearance='paper'] {
+  --limr-font-text: Georgia, 'Noto Serif SC', serif;
+  --limr-content-width: 820px;
+  --limr-accent: #8b6548;
+}
+[data-limr-appearance='paper'][data-limr-theme='dark'] {
+  --limr-accent: #d1ab84;
+}
+```
+
+appearance 会传给 portal 中的浮层/工具栏；不要只用 `.limr-reader .your-selector` 匹配这些元素。theme: auto 通过系统偏好选择内置主题；自定义 auto 深色覆盖还需对应 prefers-color-scheme 媒体规则。独立 CSS 包示例见 [paper-theme](../../examples/packages/paper-theme/index.css)。
+
+## 常用变量
+
+| 变量 | 用途 |
+| --- | --- |
+| --limr-font-text / --limr-font-code | 正文 / 代码字体 |
+| --limr-font-size / --limr-line-height | 基础排版 |
+| --limr-font-features | 正文默认 'palt' 1，字体支持时采用比例标点 |
+| --limr-emphasis-spacing / --limr-list-item-gap | 斜体末尾 / 列表间距 |
+| --limr-text / --limr-heading / --limr-secondary / --limr-muted | 文字层次 |
+| --limr-background / --limr-surface / --limr-border | 背景和边框 |
+| --limr-link / --limr-accent / --limr-selection | 链接、激活、选区 |
+| --limr-content-width / --limr-reader-width | 正文 / 总宽，默认 900px / 1800px |
+| --limr-toc-width / --limr-sidebar-width / --limr-column-gap | 侧栏宽度与列间隔 |
+| --limr-sticky-top | 吸顶偏移 |
+| --limr-reader-bottom-space / --limr-reader-min-height | 短正文高度与底部预留 |
+| --limr-sidebar-padding-inline / --limr-sidebar-reference-gap | 侧栏内容统一留白（10px）和关联区间隔（1px） |
+| --limr-overlay-duration / --limr-overlay-morph-duration | 浮层进退（560ms）和预览/展开转换（480ms） |
+| --limr-overlay-z / --limr-toolbar-z | 浮层层级 |
+| --limr-overflow-fade-size | 溢出渐隐，默认 24px，0px 关闭 |
+| --limr-toolbar-panel-max-height | 工具栏面板高度上限 |
+| --limr-tool-icon-size / --limr-mark-size | 工具图标 / 正文角标尺寸 |
+
+runtime 测量的 --limr-toolbar-available-height、--limr-toolbar-panel-height、--limr-toc-available-height 是布局输出，不应由主题覆盖。sidebar 的局部颜色通常由 AnnotationType.sidebar 配置提供，见[扩展开发](extensions.md)。
+
+## 字体和资源体积
+
+Maple Mono NF CN v7.9 的本地 WOFF2 子集随包分发，衍生字体名为 LiMR Maple Mono NF CN，OFL 许可证随资源提供。unicode-range 和 font-display: swap 限制运行时按需请求，但完整字体资产仍约 31MB，base.css 只避免浏览器加载，不减少 npm 安装体积。
+
+正文不自动加载中文字体；可使用系统回退、自托管或宿主选定的字体服务。Playground 的 Noto Serif SC 是演示项目依赖。不要假定任何字体覆盖所有文字。
+
+默认字体/公式样式不依赖外部 CDN。带哈希的字体资源可由宿主设置长期 immutable 缓存；库无法替服务器设置 HTTP 缓存头。远程图片、视频和插件请求由内容和宿主决定。
+
+## 布局与交互约定
+
+同步侧栏的高度由阅读区域决定，不能用所有卡片总高撑大页面。模块只控制自己的内容，骨架负责灰色关联区、摘要与卡片外壳；避免重复 padding 或空段落补偿。大卡片从预览位置过渡，减少动态效果设置会关闭动画。
+
+密集的文末引用在静止时向上借用空余空间。悬浮或激活时优先对齐当前条目，允许邻项在边缘裁切；角标悬浮时可压缩可选摘要，为关联区和标题留出空间。展开内容受可见阅读区域高度限制，并可在卡片内滚动。侧栏条目即使被向上收拢，也会反向对齐正文。取消激活后按当前卡片高度平滑回位，使用 `--limr-motion-slow` 和 `--limr-ease`，保持卡片间距与页面高度。
+
+选区保留原生浏览器范围与键盘行为，绘制层只计算可见片段。代码支持局部高亮，公式整体选择，图片高亮使用边框。打印隐藏绘制层并保留正文。移动端自动化检查不等于 iOS/Android 原生拖动手柄和真机验收。
+
+## 仅 CSS 的独立主题
+
+包可导出 CSS，files 包含 CSS，sideEffects 为 `["**/*.css"]`；不需要 React 或解析器运行时依赖。规则用独立 appearance 名隔离，覆盖浅色、深色、auto 和 portal，并在同页两个不同主题 Reader 中检查。
+
+展开工具栏面板使用工具栏的全部可用宽度。宽度由当前操作按钮行与可用视口决定，展开内容不参与工具栏的固有宽度计算，不会反向撑大工具栏。高亮样式按钮按文字自然宽度排列，空间不足时整项换行并左对齐。多行下划线需要保持内部 span 为 inline，不把它直接作为 flex 子项。

package/docs/zh-CN/syntax.md

@@ -0,0 +1,352 @@
+# 默认语法
+
+> 阅读提示：本文包含 LiMR 扩展语法和交互示例。部分内容在 GitHub 等普通 Markdown 阅读器中无法完整展示；前往 [GitHub Pages 文档](https://linloir.github.io/LiMR/#/docs/zh-CN/syntax) 可获得最佳阅读体验。
+
+[文档目录](README.md) · [English](../en/syntax.md)
+
+**模块**是为 LiMR 增加一组能力的配置对象，例如公式、视频或引用。下面的“创建函数”在应用代码中调用，返回模块对象；“模块名”是对象的 `name` 字段，用于替换和移除；“标签 / 指令”才是写在 Markdown 正文中的语法。完整概念和配置方式见[内置模块](modules.md)。
+
+`@linloir/limr` 随包提供以下十个模块。`Reader`、独立 `Markdown` 和 `DocumentProvider` 默认通过 `standard()` 全部启用；纯核心 `createDocument()` 默认只有 CommonMark。下面每节给出源码和实际效果，交互示例由 LiMR 自己渲染。
+
+## 模块清单
+
+| 创建函数（应用代码） | 模块名（name） | 默认能力 | 注册的特殊标签 / 指令 |
+| --- | --- | --- | --- |
+| `gfm()` | `gfm` | 表格、删除线、任务列表、自动链接、标准脚注 | 无 |
+| `math()` | `math` | 行内与块级公式 | `$…$`、`$$…$$` |
+| `codeHighlight()` | `code-highlight` | Shiki 围栏代码高亮 | 标准代码围栏 |
+| `definition()` | `definition` | 释义 | 标签 `definition`、`title`、`content`；指令 `definition` |
+| `question()` | `question` | 练习题与答案 | 标签 `question` 及下文子标签；指令 `question` |
+| `extras()` | `extras` | 拓展阅读 | 标签 `extras`、`extra`；指令 `extras` |
+| `video()` | `video` | 原生视频、YouTube、Bilibili | 标签 `video`、`md-video`；指令 `video` |
+| `figures()` | `figures` | 图组与图注 | 标签 `figures`、`figure`、`figcaption`、`caption`、`img`；指令 `figures`、`figure`、`figcaption` |
+| `citation()` | `citation` | 引用定义与角标 | 标签 `citation`、`ref`；不注册指令 |
+| `translations()` | `translations` | 原文、译文与对照 | 标签及指令 `translations`、`origin`、`translation` |
+
+这些是 Markdown 中允许的静态标签，不是任意 MDX/HTML 执行环境。使用字符串属性，如 `multi="true"`、`answer="[0,2]"`；不要使用 `answer={[0,2]}`、事件函数或展开属性。未注册 HTML 按文本显示；表达式不执行并可能产生诊断。嵌套块的标签和正文之间保留空行。
+
+## CommonMark 与 GFM
+
+````markdown
+# 标题
+
+**粗体**、*斜体*、~~删除线~~、[链接](https://example.com)、`行内代码`。
+
+> 引用块，默认界面标题为 Note / 注释。
+
+- 普通列表
+- [x] 已完成
+- [ ] 未完成
+
+| 名称 | 说明 |
+| --- | --- |
+| LiMR | Markdown renderer |
+
+```typescript
+const value = 42;
+```
+
+标准脚注[^note]。
+
+[^note]: 出现在文末的脚注内容。
+````
+
+实际效果（可交互）：
+
+#### 标题示例
+
+**粗体**、*斜体*、~~删除线~~、[链接](https://example.com)、`行内代码`。
+
+> 引用块，默认界面标题为 Note / 注释。
+
+- 普通列表
+- [x] 已完成
+- [ ] 未完成
+
+| 名称 | 说明 |
+| --- | --- |
+| LiMR | Markdown renderer |
+
+```typescript
+const value = 42;
+```
+
+标准脚注[^syntax-note]。
+
+[^syntax-note]: 出现在文末的脚注内容。
+
+标准 `[^note]` 是文末脚注，`<ref>` 是标注卡片，两者不同。图片 `![说明](/image.png)` 由普通 Markdown 支持。原始 HTML 不透传到 DOM；需要自定义外观时注册扩展或覆盖 `components`。
+
+## 公式与代码
+
+```markdown
+行内公式：$E = mc^2$。
+
+$$
+\int_0^1 x^2\,dx = \frac{1}{3}
+$$
+```
+
+实际效果（可交互）：
+
+行内公式：$E = mc^2$。
+
+$$
+\int_0^1 x^2\,dx = \frac{1}{3}
+$$
+
+公式需要导入 `@linloir/limr/math.css`；支持通过 `math({ macros, strict })` 配置。代码围栏语言用于 Shiki 高亮。默认接近视口才加载高亮，流式代码暂停更新 180ms 后尝试高亮；超过默认 100,000 字符、未支持或未在允许列表中的语言保留可读源码。`codeHighlight({ languages, lightTheme, darkTheme, eager, maxLength })` 可配置。
+
+## 释义
+
+```markdown
+<definition title="熵">
+
+表示不确定性的量：$H(X)$。
+
+</definition>
+```
+
+实际效果（可交互）：
+
+<definition title="熵">
+
+表示不确定性的量：$H(X)$。
+
+</definition>
+
+富文本标题和指定正文可以使用子标签：
+
+```markdown
+<definition>
+
+<title>**Entropy** / 熵</title>
+
+<content>
+
+正文支持 Markdown。
+
+</content>
+
+</definition>
+```
+
+`title` 属性按文字渲染；富文本用子标签。也可以写 `:::definition{title="熵"}`，以 `:::` 结束。
+
+## 练习题
+
+```markdown
+<question title="哪些是偶数？">
+
+<question-content>请选择所有正确选项。</question-content>
+
+<question-sel-grp multi="true" answer="[0,2]">
+
+<question-sel>2</question-sel>
+
+<question-sel>3</question-sel>
+
+<question-sel>4</question-sel>
+
+</question-sel-grp>
+
+<question-hint>考虑能否被 2 整除。</question-hint>
+
+<question-answer>2 和 4 是偶数。</question-answer>
+
+</question>
+```
+
+实际效果（可交互）：
+
+<question title="哪些是偶数？">
+
+<question-content>请选择所有正确选项。</question-content>
+
+<question-sel-grp multi="true" answer="[0,2]">
+
+<question-sel>2</question-sel>
+
+<question-sel>3</question-sel>
+
+<question-sel>4</question-sel>
+
+</question-sel-grp>
+
+<question-hint>考虑能否被 2 整除。</question-hint>
+
+<question-answer>2 和 4 是偶数。</question-answer>
+
+</question>
+
+答案索引从 **0** 开始。`multi` 默认关闭；`answer` 可以是 JSON 数组或单个索引的字符串。属性优先读取选择组，其次读取 `question`。提示和答案可以单独展开，有答案索引时支持提交、判分和重试。它不连接 AI，也不创建问答标注。
+
+## 拓展阅读
+
+```markdown
+<extras>
+
+<extra title="继续阅读" url="https://example.com/article" desc="背景和补充材料。" />
+
+</extras>
+```
+
+实际效果（可交互）：
+
+<extras>
+
+<extra title="内置模块" url="https://linloir.github.io/LiMR/#/docs/zh-CN/modules" desc="背景和补充材料。" />
+
+</extras>
+
+`extra` 使用 `title`、`url`、`desc`。链接经过内置 URL 过滤。
+
+## 引用卡片
+
+```markdown
+一个来源<ref id="a" />，或一组来源<ref ids='["a","b"]' />。
+
+<ref id="a">带引用的 **原文**</ref>
+
+<citation id="a" title="资料 A" url="https://example.com/a" description="完整的 **Markdown** 说明。" summary="收起时的简短摘要。" />
+
+<citation cite-id="b" title="资料 B" url="https://example.com/b" desc="兼容属性名。" />
+```
+
+实际效果（可交互）：
+
+一个来源<ref id="a" />，或一组来源<ref ids='["a","b"]' />。
+
+<ref id="a">带引用的 **原文**</ref>
+
+<citation id="a" title="资料 A" url="https://example.com/a" description="完整的 **Markdown** 说明。" summary="收起时的简短摘要。" />
+
+<citation cite-id="b" title="资料 B" url="https://example.com/b" desc="兼容属性名。" />
+
+`citation` 的 ID 读取 `cite-id`，其次 `id`；说明读取 `desc`，其次 `description`。`ref` 读取 `cite-from-ids`、`ids`、`id`，支持 JSON 数组或逗号分隔字符串。定义本身不占正文位置，同一个定义可以被多个角标引用。
+
+Citation 默认不提供展开大卡片，点击固定预览；摘要按 `summary → description → 安全 URL → title` 回退，去掉 Markdown 标记。正文显示 `description`，没有时显示 `summary`。悬浮或激活时临时高亮引用所在的最近文本块（段落、标题、列表项或表格单元格），不写入已保存高亮；外部范围标注使用绑定范围。配置与存储见[标注与选区](annotations.md)。
+
+## 图片、图组与图注
+
+```markdown
+<figures columns="2" min-width="220" max-width="560" max-height="480">
+
+<figure src="/figures/a.png" alt="实验 A" caption="(a) 实验 A" />
+
+<figure id="experiment-b">
+
+![实验 B](/figures/b.png)
+
+<figcaption>**(b)** 支持 Markdown 的图注。</figcaption>
+
+</figure>
+
+<figcaption>图 1 · 两个实验。</figcaption>
+
+</figures>
+```
+
+实际效果（可交互）：
+
+<figures columns="2" min-width="220" max-width="560" max-height="480">
+
+<figure src="../assets/source.svg" alt="实验 A" caption="(a) 实验 A" />
+
+<figure id="experiment-b">
+
+![实验 B](../assets/rendered.svg)
+
+<figcaption>**(b)** 支持 Markdown 的图注。</figcaption>
+
+</figure>
+
+<figcaption>图 1 · 两个实验。</figcaption>
+
+</figures>
+
+`figure` 可独立使用。图片可以来自 `src` / `url` 属性、内部 Markdown 图片或 `<img src="…" alt="…" />`。每个 figure 放一张图；多张图用 figures。图注可用 `caption` 属性或 `figcaption` / `caption` 子标签，富文本使用子标签。`id` 可作为页内链接目标。
+
+| 属性 | 默认值 | 说明 |
+| --- | --- | --- |
+| `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 })`。图片不变形、不裁切图注。单图复制按钮复制图片 URL；图组复制按钮复制 Markdown 源码，不下载图片二进制。
+
+指令示例：
+
+```markdown
+:::figures{columns="2"}
+::figure{src="/a.png" caption="A"}
+::figure{src="/b.png" caption="B"}
+:::
+```
+
+## 视频
+
+```markdown
+<video src="/demo.mp4" provider="native" title="演示" />
+
+<md-video url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" loading="click" />
+
+<video url="https://www.bilibili.com/video/BV1xx411c7mD/?p=2" />
+```
+
+`url` 优先于 `src`；`provider` 默认 `auto`，还可以是 `native`、`youtube`、`bilibili`。YouTube 支持 watch、短链接、embed、shorts、live 和起始时间；Bilibili 支持 BV/av 与分 P。支持 `title` 和 `loading`。
+
+**默认 `loading="visible"`**：在视口附近 200px 挂载播放器，不自动播放。`click` 等待点击，`eager` 立即挂载。可以用 `video({ loading: 'click' })` 设置模块默认值。平台、网络和嵌入权限仍会影响真实播放；不能把本地 iframe 测试当作远程播放保证。自定义平台通过 `video({ resolveUrl })` 接入。
+
+点击加载的视频示例（点击前不创建播放器）：
+
+<video url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" loading="click" title="视频示例" />
+
+## 分段译文
+
+```markdown
+<translations default="both">
+
+<origin>
+
+Original **Markdown**.
+
+</origin>
+
+<translation>
+
+翻译后的 **Markdown**。
+
+</translation>
+
+</translations>
+```
+
+实际效果（可交互）：
+
+<translations default="both">
+
+<origin>
+
+Original **Markdown**.
+
+</origin>
+
+<translation>
+
+翻译后的 **Markdown**。
+
+</translation>
+
+</translations>
+
+`default` 为 `origin`、`translation` 或 `both`，未指定时默认 `origin`（可用工厂 `defaultMode` 改写）。角标依次切换原文、译文、对照；对照时译文在前。流式输入只有一侧时先显示已有内容。模块不提供自动翻译服务。
+
+全局 `parameters.translationMode` 覆盖各块；传 `onTranslationModeChange` 接受角标发出的更改请求，否则全局模式锁定。设回 `undefined` 恢复各块的本地选择。见[项目集成](integration.md)。
+
+## 选择与替换
+
+默认高亮存为 annotation，没有 `==高亮==` 内置语法。自定义标签需注册插件；不是所有子标签都有同名指令。使用完整清单配置或替换默认模块，见[扩展开发](extensions.md)。

package/examples/assistant.tsx

@@ -0,0 +1,52 @@
+import { AnnotationCard, AnnotationMarkdown, defineExtension, type AnnotationContentProps, type AnnotationOverlayCardProps, type AnnotationSidebarPreviewProps, type RendererExtension, type SelectionSnapshot } from '@linloir/limr';
+import type { ReactNode } from 'react';
+
+/** Your application owns transport, authentication and conversation storage. */
+export interface AssistantAdapter {
+  answer: (request: { selection: SelectionSnapshot; question: string; signal: AbortSignal }) => AsyncIterable<string>;
+}
+interface AnswerData { text: string; question?: string; status: 'streaming' | 'complete' | 'error'; error?: string }
+const assistantIcon = <svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="m8 2 1.8 4.2L14 8l-4.2 1.8L8 14l-1.8-4.2L2 8l4.2-1.8L8 2Z" fill="currentColor" /></svg>;
+
+/** Example application plugin. This is deliberately not a LiMR default module. */
+export function assistant({ adapter, type = 'assistant', label = 'Ask assistant', icon = assistantIcon, color = '#8b5cf6', prompt = selection => `Explain “${selection.text}”` }: {
+  adapter: AssistantAdapter; type?: string; label?: string; icon?: ReactNode; color?: string; prompt?: (selection: SelectionSnapshot) => string;
+}): RendererExtension {
+  function Card(props: AnnotationOverlayCardProps<AnswerData>) {
+    return <AnnotationCard {...props} title={label} />;
+  }
+  function Answer({ data }: AnnotationContentProps<AnswerData>) {
+    return <div aria-busy={data?.status === 'streaming'}>
+      <AnnotationMarkdown source={data?.text || '…'} streaming={data?.status === 'streaming'} />
+      {data?.status === 'error' && <p role="alert">{data.error}</p>}
+    </div>;
+  }
+  function Preview({ data, referenceText }: AnnotationSidebarPreviewProps<AnswerData>) {
+    const question = data?.question || referenceText;
+    return question ? <span title={question}>{question}</span> : null;
+  }
+  return defineExtension({
+    name: type,
+    annotationTypes: [{ type, label, icon, color, Content: Answer, sidebar: { Preview }, overlay: { Card, expand: { placement: 'center', width: 680, height: '80dvh' } } }],
+    actions: [{ id: `${type}:ask`, label, icon: icon ?? assistantIcon, async run(context) {
+      const id = `${type}-${crypto.randomUUID()}`;
+      const question = prompt(context.selection);
+      let text = '';
+      context.addAnnotation({ id, type, data: { text, question, status: 'streaming' } satisfies AnswerData, anchors: context.selection.syntax.ranges.map(range => ({
+        range, documentId: context.document.id, quote: context.document.source.slice(range.start, range.end),
+      })) });
+      context.activateAnnotation(id);
+      context.clearSelection();
+      try {
+        for await (const chunk of adapter.answer({ selection: context.selection, question, signal: context.signal })) {
+          if (context.signal.aborted) return;
+          text += chunk;
+          context.updateAnnotation(id, { data: { text, question, status: 'streaming' } satisfies AnswerData });
+        }
+        if (!context.signal.aborted) context.updateAnnotation(id, { data: { text, question, status: 'complete' } satisfies AnswerData });
+      } catch (error) {
+        if (!context.signal.aborted) context.updateAnnotation(id, { data: { text, question, status: 'error', error: error instanceof Error ? error.message : String(error) } satisfies AnswerData });
+      }
+    } }],
+  });
+}

package/examples/notes.tsx

@@ -0,0 +1,80 @@
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import { AnnotationMarkdown, ToolIcon, defineExtension, useLiMR, useLocale, type AnnotationContentProps, type RendererExtension } from '@linloir/limr';
+
+interface NoteData { text: string; draft?: string }
+const kinds = [
+  { type: 'margin-note', label: '旁注', icon: 'comment', color: '#81B29A', hint: '在段落旁留下一个想法', labelEn: 'Margin note', hintEn: 'Leave a thought beside this passage' },
+  { type: 'reading-note', label: '笔记', icon: 'note', color: '#6B9BD2', hint: '整理这一段的阅读笔记', labelEn: 'Note', hintEn: 'Write a reading note' },
+  { type: 'reader-question', label: '提问', icon: 'question', color: '#E5A06E', hint: '写下还想进一步理解的问题', labelEn: 'Question', hintEn: 'What would you like to understand?' },
+  { type: 'reader-footnote', label: '脚注', icon: 'footnote', color: '#B39DDB', hint: '补充解释或参考来源', labelEn: 'Footnote', hintEn: 'Add an explanation or a source' },
+] as const;
+
+function NoteContent({ annotation, data, editing, presentation }: AnnotationContentProps<NoteData>) {
+  const commands = useLiMR();
+  const locale = useLocale();
+  const zh = locale.language?.startsWith('zh') ?? false;
+  const text = data?.draft ?? data?.text ?? '';
+  const isEditing = editing || data?.draft !== undefined;
+  const input = useRef<HTMLTextAreaElement>(null);
+  const kind = kinds.find(kind => kind.type === annotation.type)!;
+  useEffect(() => {
+    if (!isEditing) return;
+    if (presentation === 'preview') return;
+    const frame = requestAnimationFrame(() => {
+      const field = input.current;
+      if (field) { field.focus({ preventScroll: true }); field.selectionStart = field.selectionEnd = field.value.length; }
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [isEditing, presentation]);
+  useLayoutEffect(() => {
+    const field = input.current;
+    if (!field) return;
+    const resize = () => { field.style.height = 'auto'; field.style.height = `${field.scrollHeight}px`; };
+    resize();
+    // The same draft can move between a narrow card and the wider sidebar.
+    let width = field.clientWidth;
+    const observer = new ResizeObserver(() => { if (field.clientWidth !== width) { width = field.clientWidth; resize(); } });
+    observer.observe(field.parentElement!);
+    return () => observer.disconnect();
+  }, [isEditing, text]);
+  const save = () => {
+    if (!text.trim()) return;
+    commands.updateAnnotation(annotation.id, { data: { text } }); commands.editAnnotation(null);
+  };
+  const cancel = () => {
+    if (!data?.text.trim()) commands.removeAnnotation(annotation.id);
+    else { commands.updateAnnotation(annotation.id, { data: { text: data.text } }); commands.editAnnotation(null); }
+  };
+  return <div className="demo-note-content" data-limr-card-interactive="true">
+    {isEditing ? <form onSubmit={event => { event.preventDefault(); save(); }}>
+      <textarea className="demo-note-editor" ref={input} aria-label={zh ? `${kind.label}内容` : `${kind.labelEn} content`} rows={1} value={text} onChange={event => commands.updateAnnotation(annotation.id, { data: { text: data?.text ?? '', draft: event.target.value } })} placeholder={zh ? kind.hint : kind.hintEn} onKeyDown={event => {
+        if (event.nativeEvent.isComposing) return;
+        if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); cancel(); }
+        else if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) { event.preventDefault(); save(); }
+      }} />
+      <div className="demo-note-actions"><button type="button" onClick={cancel}><ToolIcon name="close" /><span className="limr-underline">{zh ? '取消' : 'Cancel'}</span></button><button type="submit" className="demo-note-submit" disabled={!text.trim()}><ToolIcon name="check" /><span className="limr-underline">{locale.submit}</span></button></div>
+    </form> : <><AnnotationMarkdown source={data?.text || (zh ? '还没有内容。' : 'No content yet.')} /><div className="demo-note-actions"><button type="button" onClick={() => { commands.updateAnnotation(annotation.id, { data: { text: data?.text ?? '', draft: data?.text ?? '' } }); commands.editAnnotation(annotation.id); }}><ToolIcon name="edit" /><span className="limr-underline">{zh ? '修改' : 'Edit'}</span></button><button type="button" className="demo-note-delete" onClick={() => commands.removeAnnotation(annotation.id)}><ToolIcon name="trash" /><span className="limr-underline">{locale.deleteAnnotations}</span></button></div></>}
+  </div>;
+}
+
+function NotePreview({ data }: { data?: NoteData }) {
+  const locale = useLocale();
+  return <span>{data?.text || (locale.language?.startsWith('zh') ? '正在编辑…' : 'Editing…')}</span>;
+}
+
+/** Modules bind every footnote/note/question through the same annotation API. */
+export function readingNotes(): RendererExtension {
+  return defineExtension({
+    name: 'reading-notes',
+    annotationTypes: kinds.map(kind => ({ type: kind.type, label: locale => locale.language?.startsWith('zh') ? kind.label : kind.labelEn, color: kind.color, icon: <ToolIcon name={kind.icon} />, Content: NoteContent,
+      sidebar: { Preview: NotePreview },
+      overlay: { previewWidth: 300, expand: { placement: 'center' as const, width: 400, maxHeight: '75dvh' } },
+    })),
+    actions: kinds.map(kind => ({ id: `reading-notes:${kind.type}`, label: context => context.locale.language?.startsWith('zh') ? kind.label : kind.labelEn, icon: <ToolIcon name={kind.icon} />, run: context => {
+      context.addAnnotation({ id: `note-${crypto.randomUUID()}`, type: kind.type, data: { text: '', draft: '' } satisfies NoteData,
+        anchors: context.selection.syntax.ranges.map(range => ({ range, documentId: context.document.id, quote: context.document.source.slice(range.start, range.end) })),
+      }, { edit: true });
+      context.clearSelection();
+    } })),
+  });
+}

package/examples/packages/paper-theme/index.css

@@ -0,0 +1,25 @@
+/* Unlayered application/theme CSS overrides the built-in @layer limr. */
+[data-limr-appearance='paper'] {
+  --limr-accent: #185145;
+  --limr-link: #185145;
+  --limr-selection: #548b7440;
+  --limr-background: #fcfaf4;
+  --limr-heading: #283b34;
+}
+[data-limr-appearance='paper'][data-limr-theme='dark'] {
+  --limr-background: #1e2421;
+  --limr-heading: #d8e4db;
+  --limr-link: #a8cbb8;
+}
+[data-limr-appearance='paper'] .reading-tip {
+  border-inline-start: 3px solid var(--limr-accent);
+  padding: .8rem 1rem;
+  background: #548b7410;
+}
+
+/* The same appearance selector is applied to portalled toolbars. */
+.limr-selection-toolbar[data-limr-appearance='paper'] {
+  --limr-toolbar-radius: 3px;
+  --limr-toolbar-panel-max-height: 190px;
+  --limr-toolbar-accent: var(--limr-accent);
+}

package/examples/packages/paper-theme/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@limr-example/paper-theme",
+  "version": "0.0.0",
+  "private": true,
+  "exports": { ".": "./index.css" },
+  "sideEffects": ["**/*.css"]
+}