@linloir/limr 0.1.0 → 1.0.0

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/notes.tsx

@@ -1,16 +1,18 @@
 import { useEffect, useLayoutEffect, useRef } from 'react';
-import { AnnotationMarkdown, ToolIcon, defineExtension, useLiMR, type AnnotationContentProps, type RendererExtension } from '@linloir/limr';
+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: '在段落旁留下一个想法' },
-  { type: 'reading-note', label: '笔记', icon: 'note', color: '#6B9BD2', hint: '整理这一段的阅读笔记' },
-  { type: 'reader-question', label: '提问', icon: 'question', color: '#E5A06E', hint: '写下还想进一步理解的问题' },
-  { type: 'reader-footnote', label: '脚注', icon: 'footnote', color: '#B39DDB', hint: '补充解释或参考来源' },
+  { 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);
@@ -45,25 +47,30 @@ function NoteContent({ annotation, data, editing, presentation }: AnnotationCont
   };
   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={`${kind.label}内容`} rows={1} value={text} onChange={event => commands.updateAnnotation(annotation.id, { data: { text: data?.text ?? '', draft: event.target.value } })} placeholder={kind.hint} onKeyDown={event => {
+      <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">取消</span></button><button type="submit" className="demo-note-submit" disabled={!text.trim()}><ToolIcon name="check" /><span className="limr-underline">提交</span></button></div>
-    </form> : <><AnnotationMarkdown source={data?.text || '还没有内容。'} /><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">修改</span></button><button type="button" className="demo-note-delete" onClick={() => commands.removeAnnotation(annotation.id)}><ToolIcon name="trash" /><span className="limr-underline">删除</span></button></div></>}
+      <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: kind.label, color: kind.color, icon: <ToolIcon name={kind.icon} />, Content: NoteContent,
-      sidebar: { Preview: ({ data }: { data?: NoteData }) => <span>{data?.text || '正在编辑…'}</span> },
+    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: kind.label, icon: <ToolIcon name={kind.icon} />, run: context => {
+    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 });

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"]
+}

package/examples/packages/reading-tools/index.d.ts

@@ -0,0 +1,2 @@
+import type { RendererExtension } from '@linloir/limr';
+export declare function readingTools(): RendererExtension;

package/examples/packages/reading-tools/index.js

@@ -0,0 +1,25 @@
+import { createElement as h } from 'react';
+import { AnnotationCard, AnnotationMarkdown, defineBlock, defineExtension } from '@linloir/limr';
+
+// No renderer internals or application services are needed by an npm plugin.
+export function readingTools() {
+  const tip = defineBlock({ name: 'reading-tip', component: ({ children }) => h('aside', { className: 'reading-tip' }, children) });
+  return defineExtension({
+    ...tip,
+    name: 'reading-tools',
+    annotationTypes: [{
+      type: 'reading-note', label: 'Reading note', icon: '◇', color: '#548b74',
+      overlay: { Card: props => h(AnnotationCard, { ...props, title: 'Reading note' }), expand: { placement: 'anchor' } },
+      Content: ({ data }) => h(AnnotationMarkdown, { source: data?.text ?? '' }),
+    }],
+    actions: [{
+      id: 'reading-note:add', label: 'Save passage', icon: h('svg', { viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.7, strokeLinecap: 'round', strokeLinejoin: 'round' }, h('rect', { x: 5, y: 3, width: 14, height: 18, rx: 3 }), h('path', { d: 'M9 8h6M9 12h6M9 16h4' })),
+      run(context) {
+        const id = `reading-note-${crypto.randomUUID()}`;
+        context.addAnnotation({ id, type: 'reading-note', range: context.selection.syntax.ranges[0], data: { text: `**Saved passage**\n\n${context.selection.text}` } });
+        context.activateAnnotation(id);
+        context.clearSelection();
+      },
+    }],
+  });
+}

package/examples/packages/reading-tools/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@limr-example/reading-tools",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "peerDependencies": {
+    "@linloir/limr": "^1.0.0",
+    "react": "^18.3.0 || ^19.0.0"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linloir/limr",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Linloir's limr Is a Markdown Renderer — extensible reading and streaming components for React",
   "type": "module",
   "license": "MIT",
@@ -23,9 +23,11 @@
   "files": [
     "dist",
     "README.md",
+    "README.en.md",
     "LICENSE",
-    "docs/*.md",
-    "examples/*.tsx",
+    "docs",
+    "skills",
+    "examples",
     "benchmarks/results/*.json"
   ],
   "exports": {
@@ -97,14 +99,16 @@
     "vitest": "^3.2.7"
   },
   "scripts": {
-    "dev": "vite --host 127.0.0.1",
+    "dev": "pnpm pack:skills && vite --host 127.0.0.1",
     "build": "tsup && node scripts/build-assets.mjs",
-    "build:playground": "vite build --base=/LiMR/",
+    "build:playground": "pnpm pack:skills && vite build --base=/LiMR/",
     "preview:playground": "vite preview --host 127.0.0.1 --base=/LiMR/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:browser": "playwright test",
     "test:package": "node scripts/package-smoke.mjs",
+    "test:docs": "node scripts/check-docs.mjs",
+    "pack:skills": "python3 scripts/package-skills.py",
     "bench": "tsx benchmarks/run.ts",
     "bench:browser": "tsx benchmarks/browser.ts",
     "bench:selection": "tsx benchmarks/selection.ts",

package/skills/limr-plugin-development/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: limr-plugin-development
+description: Develop, package, and integrate new @linloir/limr extension modules with custom syntax, annotation cards, selection actions, parameters, or CSS themes. Use for reusable LiMR plugin packages; ordinary application integration belongs to limr-use.
+---
+
+# Develop a LiMR plugin
+
+Deliver the requested extension as a package plus a working host import. Inspect the installed LiMR version and public declarations before choosing APIs. This bundle describes 1.0.0, including its locale APIs.
+
+Read [the contract](references/contract.md) for source mapping, annotation presentation, actions, resources, and localization. Start from [plugin-template](assets/plugin-template/README.md) when a standalone TypeScript/ESM package is useful. Copy the complete template to the requested project destination, rename its example package and IDs, and remove capabilities not needed by the task. Do not edit the installed skill as the project implementation.
+
+Choose the smallest public contract: defineBlock for a block; defineAnnotation for a type; defineExtension to combine capabilities. Keep React/LiMR as peers and build externals, export declarations, and expose CSS separately with sideEffects. Import no renderer internals and bundle no second React or LiMR runtime.
+
+Preserve original source positions. Reuse children/renderChildren, renderValue, and renderAttribute. Store every selected range with documentId and its original quote. A transform defaults to document scope; scope:local is valid only for subtree-local, prefix-independent work.
+
+Let the module own card meaning and controls through Content, overlay.Card, and sidebar.Preview. Reuse AnnotationCard and AnnotationMarkdown where suitable. LiMR owns shared positioning, portals, focus, and motion. Preview must not fetch; long tasks honor context.signal. The application owns services and credentials.
+
+Support host localization when requested: on 1.0.0 use useLocale() in components, locale.language for plugin dictionaries, label(locale) for annotation names, and context.locale in actions. Preserve stored user text across language changes. Older hosts require explicit plugin options instead; reflect the actual minimum in peerDependencies.
+
+Integrate with a stable plugins array and explicit CSS imports. Use extensions + replaceExtension for default replacements; duplicate names/tags/directives are errors. Do not silently discard persisted unknown annotations.
+
+Validate the built package in an independent consumer, not just a source alias. Check TypeScript, SSR, retained built-ins, syntax/source mapping/finalized streaming where relevant, and desktop/mobile card interactions for UI features. Exercise supported React major versions and both languages/themes when claimed. Report the package path and verified limits. Publishing remains a separate user action unless explicitly requested.

package/skills/limr-plugin-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Develop LiMR Plugins"
+  short_description: "Build and integrate LiMR extension packages"
+  default_prompt: "Use $limr-plugin-development to build a LiMR plugin package and import it into this application."

package/skills/limr-plugin-development/assets/plugin-template/README.md

@@ -0,0 +1,30 @@
+# LiMR reading-tools starter / 插件模板
+
+Copy this entire folder into your project, rename the example package/extension/type/action IDs, and adapt the implementation. It requires LiMR 1.0.0 for useLocale and localized annotation labels. The @example package is not on npm. private: true permits local packing while preventing accidental publication under the sample name.
+
+复制完整目录到项目，替换示例包名和各 ID。模板需要 LiMR 1.0.0 的语言接口；未发布版本可先安装维护者提供的本地 LiMR tgz。
+
+```sh
+npm install
+npm run typecheck
+npm run build
+npm pack
+```
+
+Install the generated tgz in a separate host application, then:
+
+```tsx
+import { Reader, chinese } 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()];
+export function Article({ source }: { source: string }) {
+  return <Reader source={source} plugins={plugins} locale={chinese} />;
+}
+```
+
+Supports <reading-tip title="Tip"> with Markdown inside, plus a selection action creating an example:note annotation with original-source anchors. English/Chinese labels follow the reader locale; options.label explicitly overrides both. User note text is never translated. Persist annotations in the host with annotations/onAnnotationsChange. The plugin includes no service connection or storage.
+
+Test the actual archive in each supported React major, SSR, desktop/mobile cards, and both locales before claiming compatibility. Keep React and LiMR external and declare them as peers. The CSS import is explicit.

package/skills/limr-plugin-development/assets/plugin-template/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@example/limr-reading-tools",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@linloir/limr": "^1.0.0",
+    "react": "^18.3.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0"
+  }
+}