@linloir/limr 0.0.0-stage → 1.0.0

package/docs/en/styles.md

@@ -0,0 +1,80 @@
+# Styles and fonts
+
+> Reading note: this page uses LiMR syntax and interactive examples. Some content cannot be fully displayed by ordinary Markdown viewers such as GitHub; visit the [GitHub Pages documentation](https://linloir.github.io/LiMR/#/docs/en/styles) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/styles.md)
+
+## Base styles and themes
+
+Default rules live in @layer limr, so ordinary host CSS can override them. Choose styles.css (with Maple) or styles/base.css (without loading Maple), and add math.css for formulas.
+
+```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" />;
+}
+```
+
+Example 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 propagates to portalled controls. Do not rely only on .limr-reader ancestry. theme: auto selects built-in colors with the system preference; custom dark overrides for auto also need a prefers-color-scheme media rule. See the standalone [paper-theme](../../examples/packages/paper-theme/index.css) example.
+
+## Common variables
+
+| Variable | Purpose |
+| --- | --- |
+| --limr-font-text / --limr-font-code | Body / code fonts |
+| --limr-font-size / --limr-line-height | Base typography |
+| --limr-font-features | Defaults to 'palt' 1 for proportional punctuation where supported |
+| --limr-emphasis-spacing / --limr-list-item-gap | Trailing emphasis / list spacing |
+| --limr-text / --limr-heading / --limr-secondary / --limr-muted | Text hierarchy |
+| --limr-background / --limr-surface / --limr-border | Backgrounds and borders |
+| --limr-link / --limr-accent / --limr-selection | Links, active state, selection |
+| --limr-content-width / --limr-reader-width | Body / overall width; default 900px / 1800px |
+| --limr-toc-width / --limr-sidebar-width / --limr-column-gap | Side column widths and gaps |
+| --limr-sticky-top | Sticky offset |
+| --limr-reader-bottom-space / --limr-reader-min-height | Short-document height and bottom space |
+| --limr-sidebar-padding-inline / --limr-sidebar-reference-gap | Shared padding (10px) and reference separation (1px) |
+| --limr-overlay-duration / --limr-overlay-morph-duration | Enter/exit (560ms), preview/expanded morph (480ms) |
+| --limr-overlay-z / --limr-toolbar-z | Floating control stacking |
+| --limr-overflow-fade-size | Overflow fade, default 24px; 0px disables |
+| --limr-toolbar-panel-max-height | Maximum toolbar panel height |
+| --limr-tool-icon-size / --limr-mark-size | Toolbar icons / inline markers |
+
+--limr-toolbar-available-height, --limr-toolbar-panel-height, and --limr-toc-available-height are runtime measurements, not theme inputs. AnnotationType.sidebar usually supplies local card colors; see [extensions](extensions.md).
+
+## Fonts and package size
+
+Local WOFF2 subsets of Maple Mono NF CN v7.9 ship in the package under the derivative name LiMR Maple Mono NF CN, with the OFL license. unicode-range and font-display: swap limit runtime requests, but the complete font assets still occupy about 31MB. base.css avoids browser loading, not npm installation size.
+
+Body text does not automatically load Chinese fonts. Use system fallbacks, self-hosted fonts, or a host-chosen service. The Playground's Noto Serif SC belongs to the demo. No font should be assumed to cover every script.
+
+Default font/math styles do not require a third-party CDN. Hosts can apply long-lived immutable caching to hashed font URLs; the library cannot set server HTTP headers. Remote image/video/plugin requests depend on content and host configuration.
+
+## Layout and interaction conventions
+
+The reading region determines synchronized sidebar height; do not size the page to all cards combined. Modules own content while the shared layout owns references, summaries, and card shells. Avoid duplicate padding or empty-paragraph compensation. Expanded cards animate from preview geometry; reduced-motion preferences disable motion.
+
+Dense footer references borrow spare space above them at rest. Hovered or active items take alignment priority, allowing neighboring items to clip at the edges. Marker hover can compress the optional summary to leave room for the reference and heading. Expanded content is bounded by the visible reading region and scrolls within its card. Packed sidebar items still align the prose on hover. Deactivation smoothly restores the resting layout using current card heights, `--limr-motion-slow`, and `--limr-ease`, preserving gaps and page height.
+
+Selection retains native browser ranges and keyboard behavior. Paint layers calculate visible fragments only. Code allows partial highlights, math is atomic, and image highlights use borders. Printing hides paint layers while keeping document content. Mobile automation does not certify native iOS/Android handles or physical-device behavior.
+
+## CSS-only themes
+
+Export CSS, include it in files, and mark sideEffects as ["**/*.css"]. A theme does not need React or parser runtime dependencies. Scope rules to an appearance name and check light, dark, auto, portals, and two differently themed readers on the same page.
+
+Expanded toolbar panels use the full available toolbar width. The action row and available viewport determine its width; expanded content does not contribute intrinsic width or enlarge the toolbar. Highlight options use intrinsic text widths and wrap as whole items, aligned to the start. Multiline underlines need an inner inline span rather than a direct flex child.

package/docs/en/syntax.md

@@ -0,0 +1,352 @@
+# Default syntax
+
+> Reading note: this page uses LiMR syntax and interactive examples. Some content cannot be fully displayed by ordinary Markdown viewers such as GitHub; visit the [GitHub Pages documentation](https://linloir.github.io/LiMR/#/docs/en/syntax) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/syntax.md)
+
+**Modules** are configuration objects that add capabilities such as formulas, videos, or citations. A factory is called in application code to return an object; the module name is its `name` property, used for replacement and removal; tags and directives are the syntax written in Markdown. See [built-in modules](modules.md) for concepts and configuration.
+
+The ten modules below ship with `@linloir/limr`. `Reader`, standalone `Markdown`, and `DocumentProvider` enable all of them through `standard()` by default; core-only `createDocument()` starts with CommonMark. The following sections include source and rendered examples, using LiMR itself.
+
+## Module catalog
+
+| Factory (application code) | Module name (name) | Capability | Registered tags / directives |
+| --- | --- | --- | --- |
+| `gfm()` | `gfm` | Tables, strikethrough, tasks, autolinks, standard footnotes | None |
+| `math()` | `math` | Inline and display math | `$…$`, `$$…$$` |
+| `codeHighlight()` | `code-highlight` | Shiki fenced-code highlighting | Standard code fences |
+| `definition()` | `definition` | Definitions | Tags: definition, title, content; directive: definition |
+| `question()` | `question` | Exercises and answers | question and child tags below; directive: question |
+| `extras()` | `extras` | Further reading | Tags: extras, extra; directive: extras |
+| `video()` | `video` | Native video, YouTube, Bilibili | Tags: video, md-video; directive: video |
+| `figures()` | `figures` | Figure groups and captions | Tags: figures, figure, figcaption, caption, img; directives: figures, figure, figcaption |
+| `citation()` | `citation` | Reference definitions and markers | Tags: citation, ref; no directives |
+| `translations()` | `translations` | Original, translated, and parallel text | Tags and directives: translations, origin, translation |
+
+These are registered static tags in Markdown, not an arbitrary MDX/HTML execution environment. Use string attributes such as `multi="true"` and `answer="[0,2]"`. Do not use `answer={[0,2]}`, event functions, or spread attributes. Unregistered HTML is displayed as text; expressions are not executed and may produce diagnostics. Keep blank lines between block tags and their Markdown content.
+
+## CommonMark and GFM
+
+````markdown
+# Heading
+
+**Bold**, *italic*, ~~deleted~~, [link](https://example.com), `inline code`.
+
+> A blockquote, labelled Note by the default renderer.
+
+- A list item
+- [x] Complete
+- [ ] Pending
+
+| Name | Description |
+| --- | --- |
+| LiMR | Markdown renderer |
+
+```typescript
+const value = 42;
+```
+
+A standard footnote[^note].
+
+[^note]: Content at the end of the document.
+````
+
+Rendered result (interactive where applicable):
+
+#### Example heading
+
+**Bold**, *italic*, ~~deleted~~, [link](https://example.com), `inline code`.
+
+> A blockquote, labelled Note by the default renderer.
+
+- A list item
+- [x] Complete
+- [ ] Pending
+
+| Name | Description |
+| --- | --- |
+| LiMR | Markdown renderer |
+
+```typescript
+const value = 42;
+```
+
+A standard footnote[^syntax-note].
+
+[^syntax-note]: Content at the end of the document.
+
+Standard `[^note]` footnotes appear at the end; `<ref>` opens an annotation card. Ordinary Markdown supports `![Description](/image.png)`. Raw HTML is not passed through to the DOM. Register an extension or override `components` to customize rendering.
+
+## Math and code
+
+```markdown
+Inline: $E = mc^2$.
+
+$$
+\int_0^1 x^2\,dx = \frac{1}{3}
+$$
+```
+
+Rendered result (interactive where applicable):
+
+Inline: $E = mc^2$.
+
+$$
+\int_0^1 x^2\,dx = \frac{1}{3}
+$$
+
+Import `@linloir/limr/math.css`. Configure formulas with `math({ macros, strict })`. Fenced language names select Shiki highlighting. Highlighting loads near the viewport; streaming code waits for a 180ms pause. Code over the default 100,000-character limit, unsupported languages, and languages outside the configured list retain readable source. Configure `codeHighlight({ languages, lightTheme, darkTheme, eager, maxLength })`.
+
+## Definitions
+
+```markdown
+<definition title="Entropy">
+
+A measure of uncertainty: $H(X)$.
+
+</definition>
+```
+
+Rendered result (interactive where applicable):
+
+<definition title="Entropy">
+
+A measure of uncertainty: $H(X)$.
+
+</definition>
+
+Use child tags for rich titles and an explicit body:
+
+```markdown
+<definition>
+
+<title>**Entropy** / 熵</title>
+
+<content>
+
+The body supports Markdown.
+
+</content>
+
+</definition>
+```
+
+The `title` attribute is text. Child tags support rich content. The directive form is `:::definition{title="Entropy"}`, closed by `:::`.
+
+## Exercises
+
+```markdown
+<question title="Which numbers are even?">
+
+<question-content>Select all correct options.</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>Consider divisibility by 2.</question-hint>
+
+<question-answer>2 and 4 are even.</question-answer>
+
+</question>
+```
+
+Rendered result (interactive where applicable):
+
+<question title="Which numbers are even?">
+
+<question-content>Select all correct options.</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>Consider divisibility by 2.</question-hint>
+
+<question-answer>2 and 4 are even.</question-answer>
+
+</question>
+
+Answer indices are **zero-based**. `multi` is off by default. `answer` is a string containing a JSON array or a single index. Attributes on the selection group take precedence over question attributes. Hints and answers expand independently; configured answers enable submission, scoring, and retry. This module neither connects to AI nor creates question annotations.
+
+## Further reading
+
+```markdown
+<extras>
+
+<extra title="Read more" url="https://example.com/article" desc="Background material." />
+
+</extras>
+```
+
+Rendered result (interactive where applicable):
+
+<extras>
+
+<extra title="Built-in modules" url="https://linloir.github.io/LiMR/#/docs/en/modules" desc="Background material." />
+
+</extras>
+
+`extra` uses `title`, `url`, and `desc`. Links pass through the built-in URL filter.
+
+## Citation cards
+
+```markdown
+One source<ref id="a" />, or several<ref ids='["a","b"]' />.
+
+<ref id="a">Referenced **text**</ref>
+
+<citation id="a" title="Source A" url="https://example.com/a" description="Full **Markdown** description." summary="Short collapsed summary." />
+
+<citation cite-id="b" title="Source B" url="https://example.com/b" desc="Legacy attribute name." />
+```
+
+Rendered result (interactive where applicable):
+
+One source<ref id="a" />, or several<ref ids='["a","b"]' />.
+
+<ref id="a">Referenced **text**</ref>
+
+<citation id="a" title="Source A" url="https://example.com/a" description="Full **Markdown** description." summary="Short collapsed summary." />
+
+<citation cite-id="b" title="Source B" url="https://example.com/b" desc="Legacy attribute name." />
+
+Citation IDs use `cite-id`, then `id`. Descriptions use `desc`, then `description`. References use `cite-from-ids`, `ids`, then `id`, accepting JSON arrays or comma-separated strings. Definitions do not occupy body space, and multiple markers can reference one definition.
+
+Citations do not expand into large cards by default; clicking pins the preview. Collapsed summaries fall back through `summary → description → safe URL → title`, with Markdown stripped. Card content uses description, then summary. Hovering or activating a reference temporarily highlights its nearest text block (paragraph, heading, list item, or table cell), without saving a highlight. External range annotations use their bound range. See [annotations and selection](annotations.md).
+
+## Images, figures, and captions
+
+```markdown
+<figures columns="2" min-width="220" max-width="560" max-height="480">
+
+<figure src="/figures/a.png" alt="Experiment A" caption="(a) Experiment A" />
+
+<figure id="experiment-b">
+
+![Experiment B](/figures/b.png)
+
+<figcaption>**(b)** A Markdown caption.</figcaption>
+
+</figure>
+
+<figcaption>Figure 1 · Two experiments.</figcaption>
+
+</figures>
+```
+
+Rendered result (interactive where applicable):
+
+<figures columns="2" min-width="220" max-width="560" max-height="480">
+
+<figure src="../assets/source.svg" alt="Experiment A" caption="(a) Experiment A" />
+
+<figure id="experiment-b">
+
+![Experiment B](../assets/rendered.svg)
+
+<figcaption>**(b)** A Markdown caption.</figcaption>
+
+</figure>
+
+<figcaption>Figure 1 · Two experiments.</figcaption>
+
+</figures>
+
+A figure can stand alone. Supply an image through `src` / `url`, nested Markdown, or `<img src="…" alt="…" />`. Use one image per figure and figures for groups. Captions can use an attribute or figcaption / caption child tags; use children for rich text. `id` provides an in-page link target.
+
+| Attribute | Default | Meaning |
+| --- | --- | --- |
+| `min-width` / `min-height` | 220 / 120 | Determines when another column fits; narrow containers take priority |
+| `max-width` / `max-height` | 560 / 480 | Image bounds preserving aspect ratio; none / false removes a bound |
+| `columns` / `cols` | Automatic | Requested columns, capped at 24 |
+| `rows` | Automatic | Derives columns from image count when columns are omitted |
+| `responsive` | true | Reduces explicit columns when space is insufficient; false keeps them |
+| `gap` | 16 | Group gap in pixels |
+
+Dimensions accept nonnegative numbers or px. Figures inherit group limits and can override them. Factory options use camelCase, such as `figures({ maxHeight: 360, maxWidth: false })`. Images retain their aspect ratio, and captions are not cropped. A single figure copies the image URL; a group copies Markdown source. Neither copies image bytes.
+
+Directive example:
+
+```markdown
+:::figures{columns="2"}
+::figure{src="/a.png" caption="A"}
+::figure{src="/b.png" caption="B"}
+:::
+```
+
+## Video
+
+```markdown
+<video src="/demo.mp4" provider="native" title="Demo" />
+
+<md-video url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" loading="click" />
+
+<video url="https://www.bilibili.com/video/BV1xx411c7mD/?p=2" />
+```
+
+`url` takes precedence over `src`. `provider` defaults to auto and also accepts native, youtube, and bilibili. YouTube supports watch, short, embed, shorts, and live URLs with start times. Bilibili supports BV/av IDs and parts. Other attributes are title and loading.
+
+**The default is `loading="visible"`**: the player mounts within 200px of the viewport without autoplay. click waits for a click; eager mounts immediately. Set a module default with `video({ loading: 'click' })`. Actual playback depends on the platform, network, and embedding permissions; local iframe tests do not guarantee remote playback. Use `video({ resolveUrl })` for a custom provider.
+
+Click-to-load example (no player is created before clicking):
+
+<video url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" loading="click" title="Video example" />
+
+## Translations
+
+```markdown
+<translations default="both">
+
+<origin>
+
+Original **Markdown**.
+
+</origin>
+
+<translation>
+
+翻译后的 **Markdown**。
+
+</translation>
+
+</translations>
+```
+
+Rendered result (interactive where applicable):
+
+<translations default="both">
+
+<origin>
+
+Original **Markdown**.
+
+</origin>
+
+<translation>
+
+翻译后的 **Markdown**。
+
+</translation>
+
+</translations>
+
+`default` accepts origin, translation, or both, defaulting to origin unless overridden by the factory's defaultMode. The marker cycles through these modes. Parallel mode shows the translation first. During streaming, an available side is shown while the other is missing. This module does not translate content automatically.
+
+Global `parameters.translationMode` overrides individual blocks. Pass onTranslationModeChange to accept marker requests; without a callback, a global mode is locked. Setting it to undefined restores local choices. See [application integration](integration.md).
+
+## Selection and replacement
+
+Persistent highlights are annotations; there is no built-in `==highlight==` syntax. Register plugins for custom tags. Not every child tag has a corresponding directive. See [extension development](extensions.md) to select or replace default modules.

package/docs/extensions.md

@@ -0,0 +1,8 @@
+# 扩展开发 / Extension development
+
+文档已整理到语言目录。This guide now lives in the language directories.
+
+- [简体中文](zh-CN/extensions.md)
+- [English](en/extensions.md)
+
+[文档目录 / Documentation](README.md)

package/docs/implementation.md

@@ -0,0 +1,8 @@
+# 架构与行为 / Architecture and behavior
+
+文档已整理到语言目录。This guide now lives in the language directories.
+
+- [简体中文](zh-CN/architecture.md)
+- [English](en/architecture.md)
+
+[文档目录 / Documentation](README.md)

package/docs/performance.md

@@ -0,0 +1,8 @@
+# 性能与限制 / Performance and limits
+
+文档已整理到语言目录。This guide now lives in the language directories.
+
+- [简体中文](zh-CN/performance.md)
+- [English](en/performance.md)
+
+[文档目录 / Documentation](README.md)

package/docs/styles.md

@@ -0,0 +1,8 @@
+# 样式与字体 / Styles and fonts
+
+文档已整理到语言目录。This guide now lives in the language directories.
+
+- [简体中文](zh-CN/styles.md)
+- [English](en/styles.md)
+
+[文档目录 / Documentation](README.md)

package/docs/visual-upgrade.md

@@ -0,0 +1,8 @@
+# 样式与交互 / Styles and interaction
+
+文档已整理到语言目录。This guide now lives in the language directories.
+
+- [简体中文](zh-CN/styles.md)
+- [English](en/styles.md)
+
+[文档目录 / Documentation](README.md)

package/docs/zh-CN/README.md

@@ -0,0 +1,26 @@
+# 中文文档
+
+> 阅读提示：本文包含 LiMR 扩展语法和交互示例。部分内容在 GitHub 等普通 Markdown 阅读器中无法完整展示；前往 [GitHub Pages 文档](https://linloir.github.io/LiMR/#/docs/zh-CN/README) 可获得最佳阅读体验。
+
+[文档目录](README.md) · [English](../en/README.md)
+
+这套文档对应当前 LiMR 1.0.0 的公开实现。默认入口为中文，英文页面与本目录一一对应。
+
+| 你要做什么 | 阅读文档 |
+| --- | --- |
+| 安装并显示第一篇文档 | [快速开始](getting-started.md) |
+| 了解模块、默认包含的能力与配置方式 | [内置模块](modules.md) |
+| 编写 Markdown、练习题、引用、图组与译文 | [默认语法](syntax.md) |
+| 集成到 React、接收流式输出、自定义布局或 SSR | [项目集成](integration.md) |
+| 保存选区、高亮、引用和自定义标注 | [标注与选区](annotations.md) |
+| 新增语法、卡片、选区动作和模块参数 | [扩展开发](extensions.md) |
+| 开发独立 npm 插件并在应用中引入 | [插件模块包](plugin-packages.md) |
+| 调整主题、字体、布局与 portal 样式 | [样式与字体](styles.md) |
+| 查询组件 props、hooks 和核心 API | [API 参考](api.md) |
+| 理解解析、状态和资源边界 | [架构与行为](architecture.md) |
+| 了解性能数据和验证范围 | [性能与限制](performance.md) |
+| 让 AI 使用 LiMR 或开发插件 | [AI Skills](ai-skills.md) |
+
+先接入 `Reader`，需要定制布局时再拆分组件；需要应用功能时优先添加插件。Playground 中的本地保存、导入导出和模拟问答是演示应用功能，不是 Reader 自带的服务。
+
+[返回 README](../../README.md) · [在线 Playground](https://linloir.github.io/LiMR/)

package/docs/zh-CN/ai-skills.md

@@ -0,0 +1,57 @@
+# AI Skills：下载、导入与使用
+
+> 阅读提示：本文包含 LiMR 扩展语法和交互示例。部分内容在 GitHub 等普通 Markdown 阅读器中无法完整展示；前往 [GitHub Pages 文档](https://linloir.github.io/LiMR/#/docs/zh-CN/ai-skills) 可获得最佳阅读体验。
+
+[文档目录](README.md) · [English](../en/ai-skills.md)
+
+Skills 是指导 AI 工作的文件包，不是运行在 Reader 中的 RendererExtension，也不是模型服务。安装 Skill 不会自动修改项目、安装插件或连接 AI API。
+
+| Skill | 适用任务 |
+| --- | --- |
+| [limr-use](../../skills/limr-use/SKILL.md) | 接入 LiMR、选择组件、编写语法、配置标注/流式/主题、引入已有插件 |
+| [limr-plugin-development](../../skills/limr-plugin-development/SKILL.md) | 开发新插件模块包，扩展卡片/语法/动作/参数，构建并验证消费者 |
+
+两份 Skill 的指令使用英文以便复用，支持中文任务输入；给使用者的说明同时提供中英文。插件 Skill 包含独立模板，两个 Skill 都包含本地 references，无需把整个 LiMR 仓库放进 AI 上下文。
+
+## 从 npm 包导入
+
+先安装包含 Skills 的 LiMR 版本，在**你的应用项目**中运行：
+
+```sh
+npm install @linloir/limr
+mkdir -p .agents/skills
+cp -R node_modules/@linloir/limr/skills/limr-use .agents/skills/
+cp -R node_modules/@linloir/limr/skills/limr-plugin-development .agents/skills/
+```
+
+以上为新安装示例；已有同名目录时先检查本地定制，再更新整个目录，避免旧模板残留。导入是快照，npm 升级不会自动同步副本。升级 LiMR 后应同时检查 Skill 版本适配。
+
+## 从仓库或 ZIP 导入
+
+可以从仓库的 skills 目录复制，也可以在本地生成 ZIP（需要 Python 3）：
+
+```sh
+pnpm pack:skills
+```
+
+输出在 artifacts/skills，并同步到 Playground 的 public/downloads 供 Docs 页面下载。每个 ZIP 的根目录是完整 skill 文件夹，不只包含 SKILL.md；另有包含两份 Skill 的版本化总包。构建 Docs 站点时自动生成下载文件。
+
+对应版本网站部署后可直接下载：[limr-use.zip](https://linloir.github.io/LiMR/downloads/limr-use.zip)、[limr-plugin-development.zip](https://linloir.github.io/LiMR/downloads/limr-plugin-development.zip)。本地 Docs 的 AI Skills 页面也有下载按钮。ZIP 是便于下载的归档，不代表所有 AI 客户端都支持一键 ZIP 导入；不支持时解压并复制完整目录。
+
+## Codex 的位置与调用
+
+Codex 的项目级目录是 `.agents/skills/`，用户级目录是 `~/.agents/skills/`。选择一个作用域，避免重复安装同名 Skill。客户端仍使用旧目录时，按该版本支持的路径导入。Codex 通常自动发现变化，未显示时重启；可通过 `/skills` 或 `$skill-name` 调用。依据：[OpenAI 官方 Skills 文档](https://developers.openai.com/codex/skills/)。
+
+```text
+$limr-use 在这个 React 项目中接入 LiMR，使用中文界面、流式回答和受控标注。
+```
+
+```text
+$limr-plugin-development 创建术语解释插件包，包含术语块、选区动作、可展开卡片和侧栏摘要，再引入当前应用。
+```
+
+其他支持 SKILL.md 的 AI 工具，使用其实际支持的项目/用户目录；没有 Skill 自动发现能力时，可以要求 AI 阅读 SKILL.md，并按其中链接加载 references 和 assets。无需假定某个客户端专属命令可在所有工具上工作。
+
+## 期望产物
+
+使用 Skill 应交付可运行的集成、稳定配置和验证结果；开发 Skill 应交付模块源码、包导出/类型/CSS、宿主引入示例及真实包消费验证。它们都要求以当前安装版本为准，不虚构解析能力，不删除未知标注的持久化数据，也不在未获指示时发布 npm 或修改外部服务。

package/docs/zh-CN/annotations.md

@@ -0,0 +1,84 @@
+# 标注与选区
+
+> 阅读提示：本文包含 LiMR 扩展语法和交互示例。部分内容在 GitHub 等普通 Markdown 阅读器中无法完整展示；前往 [GitHub Pages 文档](https://linloir.github.io/LiMR/#/docs/zh-CN/annotations) 可获得最佳阅读体验。
+
+[文档目录](README.md) · [English](../en/annotations.md)
+
+## 数据模型
+
+`Annotation` 是数据，`AnnotationType` 是插件注册的呈现和加载逻辑，`AnnotationOccurrence` 是一次出现位置。一个标注可以通过 anchors 出现在多处；一个引用角标可以关联多条标注。
+
+```ts
+import type { Annotation } from '@linloir/limr';
+
+export const annotations: readonly Annotation[] = [{
+  id: 'paper-reference',
+  type: 'citation',
+  data: { title: 'Paper', url: 'https://example.com/paper' },
+  anchors: [{
+    range: { start: 0, end: 4 },
+    documentId: 'article',
+    quote: 'LiMR',
+  }],
+}, {
+  id: 'highlight-1',
+  type: 'highlight',
+  range: { start: 0, end: 4 },
+  data: { color: '#F2C744', style: 'background' },
+}];
+```
+
+这个示例要求 source 的前四个 UTF-16 单元为 `LiMR`，documentId 为 article。range 是单次锚点的简写；传 anchors 后以 anchors 为准。范围均指向**未经改写的输入**，采用 UTF-16、右端不包含，不是 UTF-8 字节或 Unicode 码点。
+
+持久化时保存原始 source、稳定 documentId、annotation.id、type、data、anchors，并在有需要时记录应用文档版本。anchor.revision 对应当前引擎修订号，不是跨会话持久 ID。quote 与原范围不符时，只在全文有唯一匹配时迁移；无匹配、多个匹配或 documentId 不一致会跳过该锚点。没有 quote 且 revision 不匹配的锚点也会跳过。这不是协同编辑的自动位置转换系统。
+
+## 三种选区
+
+| 字段 | 含义 |
+| --- | --- |
+| `text` | 可读的选中文本 |
+| `raw` | 映射得到的原始范围和源码 |
+| `syntax` | 仅吸收两端紧邻的标准 Markdown 标记，不扩选未选文字或特殊块外层标签 |
+| `blocks` | 选区触及的块范围与源码 |
+| `quality` | exact、atomic 或 unmapped |
+| `settled` | 指针仍在拖选时为 false |
+| `documentId` / `revision` | 选区所属文档快照 |
+
+每种结果包含 ranges 和 sourceText。一般笔记使用 syntax.ranges，并为**每个范围**保存 `document.source.slice(start, end)` 作为 quote。代码支持部分选择；公式和图片作为原子内容。不要用 DOM textContent 长度倒推原文范围，实体、转义和 emoji 会让两者不同。
+
+## 高亮和命令
+
+`highlight` 不需要安装额外的 AnnotationType，data 支持 color、style（background / underline / dotted / wavy）、hidden。删除内容标注与隐藏高亮是不同操作。
+
+| 命令 | 行为 |
+| --- | --- |
+| `addAnnotation(annotation, options?)` | 添加/替换同 ID 数据；普通内容标注默认同时补充共享高亮 |
+| `updateAnnotation(id, partial)` | 浅合并标注字段；data 是整体替换，更新时保留需要的字段 |
+| `removeAnnotation(id)` | 移除这一条标注，其他标注和共享高亮保留 |
+| `removeAnnotationsAt(ranges)` | 移除精确匹配片段上的标注及高亮；保留它们其他位置的锚点 |
+| `editAnnotation(id / null)` | 切换共享编辑状态；设置 ID 时也激活卡片 |
+| `activateAnnotation(id / null)` | 激活标注的首个 occurrence，也接受 occurrence ID |
+
+`addAnnotation` 的 `{ highlight: false }` 关闭自动持久高亮，显式 HighlightData 指定样式；`{ edit: true }` 进入编辑。类型配置 `highlight: 'hover'` 时默认不创建持久高亮，但显式传入高亮样式仍可创建。默认选区工具栏为调色板、添加/隐藏高亮、复制、删除；actions 覆盖内置列表，插件动作仍会合并进去。
+
+## Citation 的临时高亮
+
+Citation 默认 `highlight: 'hover'`。角标或侧栏条目悬浮、或引用处于 activate 状态时，用类型 color 的 18% 底色高亮关联文本。底色绘制在文字下方；点击激活后，移开鼠标仍保留，取消激活且不再悬浮后才隐藏。同一段落的激活与悬浮引用不会叠加加深颜色。该效果不更新 annotations，也不改变已保存高亮的 hidden 设置。嵌入 ref 使用最近的段落、标题、列表项或表格单元格；外部范围引用使用自身范围，并以该范围首行对齐侧栏。
+
+侧栏联动使用正文位移动画，不改变页面滚动范围。绘制层在动画过程中及结束、取消时更新可见片段，因此从视口外移入的文本也会同步获得当前悬浮或激活高亮。
+
+使用 `replaceExtension(standard(), citation({ highlight: false }))` 关闭该效果。其他类型也可显式启用 highlight: 'hover'。
+
+## 缺少插件时
+
+当前实现**不会静默忽略未知 annotation 类型**。数据和范围仍保留，可能显示通用圆点角标；没有 Content 时卡片显示本地化的“不可用”及类型名称。缺失 citation 定义也可能显示不可用提示。要保证呈现，应安装对应插件，或由应用决定暂时隐藏哪些标注。
+
+若应用过滤不支持的类型，保留完整的持久化原始数组，并在写回时合并仍隐藏的数据，避免卸载插件导致数据丢失。Playground 的插件勾选目前只启用/关闭动作入口，仍保留卡片渲染器，因此不会模拟完整卸载插件。
+
+## 卡片与异步资源
+
+卡片 UI 由模块注册：Content 渲染内容，overlay.Card 负责完整浮层内部，sidebar.Preview 负责收起时的本地摘要。`AnnotationMarkdown` 在隔离选区作用域内复用 Markdown 配置。
+
+`load(annotation, { signal })` 在内容显示时才调用，同一阅读器内复用请求和有限缓存，不在不同 Reader 间共享。Preview 不调用 load。Content 接收 data、loading、error、retry、editing、presentation、expanded；处理加载和错误 UI 是模块的职责。可通过 useLiMR().invalidateAnnotation(id) 刷新。
+
+动作的 signal 在阅读器销毁时取消，关闭菜单不会取消动作。调用 updateAnnotation 更新流式答案时同时保留问题字段；“停止生成”、重试、认证、会话和保存由应用 adapter 管理。参考[助手示例](../../examples/assistant.tsx)和[扩展开发](extensions.md)。