@linloir/limr 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linloir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,123 @@
+# LiMR
+
+[![npm version](https://img.shields.io/npm/v/@linloir/limr.svg)](https://www.npmjs.com/package/@linloir/limr)
+
+[简体中文](README.md) · **English**
+
+**Linloir’s limr Is a Markdown Renderer.** A React Markdown renderer for long documents and streaming output. Body text, navigation, reference cards, selections, and highlights share one document state, and can also be composed into your own interface.
+
+[Live Playground](https://linloir.github.io/LiMR/) · [English docs](docs/en/README.md) · [中文文档](docs/zh-CN/README.md) · [AI Skills](docs/en/ai-skills.md)
+
+## Install and use
+
+```sh
+npm install @linloir/limr
+# or pnpm add @linloir/limr
+```
+
+```tsx
+import { Reader } from '@linloir/limr';
+import '@linloir/limr/styles.css';
+import '@linloir/limr/math.css';
+
+const source = '# Start reading\n\nSupports **Markdown** and $E = mc^2$.';
+
+export default function Article() {
+  return <Reader source={source} />;
+}
+```
+
+Requires React / React DOM **18.3 or 19**, Node.js **20+**, and an ESM-capable build tool. Interactive features target modern browsers; Node SSR is supported. UI labels default to English; pass the exported `chinese` locale for Chinese labels. Import `math.css` when using formulas.
+
+Render just the body, or a growing response:
+
+```tsx
+import { Markdown } from '@linloir/limr';
+
+export function Answer({ text, generating }: { text: string; generating: boolean }) {
+  return <Markdown source={text} streaming={generating} followOutput />;
+}
+```
+
+`source` is the complete accumulated string. Set `streaming` to `false` when generation ends. `followOutput` is off by default and pauses when the reader scrolls up. `Markdown` does not include navigation, a sidebar, or a selection toolbar.
+
+## Capabilities
+
+| Scenario | Features |
+| --- | --- |
+| Reading | CommonMark, GFM tables/tasks/footnotes, math, Shiki code highlighting |
+| Rich content | Images, figure groups, captions, video, definitions, exercises, further reading, citations, original/translated/parallel text |
+| Interaction | Responsive contents, desktop annotation sidebar, narrow-screen overlays, copying, four highlight styles |
+| Integration | Controlled annotations, original UTF-16 offsets, isolated readers, nested scroll containers, SSR |
+| Extensions | Custom syntax, React renderers, annotation types, selection actions, parameters, CSS theme packages |
+
+The default content annotation type is `citation`; `highlight` provides persistent highlighting. Notes, questions, and chat annotations belong to application plugins. The default `question()` extension renders exercises in the document. See the [syntax reference](docs/en/syntax.md).
+
+```markdown
+<definition title="Definition">
+
+Use **Markdown** inside custom blocks.
+
+</definition>
+
+This passage has a source<ref id="paper" />.
+
+<citation id="paper" title="Reference" url="https://example.com/paper" summary="Short summary" />
+```
+
+## Composition and extensions
+
+`Reader` provides a complete layout. Use `DocumentProvider` with `Markdown`, `TableOfContents`, `AnnotationSidebar`, `AnnotationOverlay`, and `SelectionToolbar` for your own layout. See [application integration](docs/en/integration.md).
+
+```tsx
+import { Reader, defineBlock } from '@linloir/limr';
+
+const plugins = [defineBlock({
+  name: 'notice',
+  component: ({ children }) => <aside className="notice">{children}</aside>,
+})];
+
+export function Notice() {
+  return <Reader source={'<notice>\n\n**Custom content**\n\n</notice>'} plugins={plugins} />;
+}
+```
+
+`plugins` appends to the defaults. `extensions` replaces the entire list; `extensions={[]}` uses basic CommonMark. Replace a named extension explicitly with `replaceExtension()`. Keep configuration references stable.
+
+Plugins can own the complete card UI (`overlay.Card`), collapsed sidebar summary (`sidebar.Preview`), async loading, and selection actions. Use the [plugin development Skill](skills/limr-plugin-development/SKILL.md) or [package guide](docs/en/plugin-packages.md) to build an installable extension and add it through `plugins`. Examples cover [notes](examples/notes.tsx), a [streaming assistant](examples/assistant.tsx), a [standalone plugin](examples/packages/reading-tools/index.js), and a [CSS theme](examples/packages/paper-theme/index.css). The `@limr-example/*` packages are unpublished local examples.
+
+## AI Skills
+
+| Skill | Purpose |
+| --- | --- |
+| [limr-use](skills/limr-use/SKILL.md) | Integrate LiMR, author content, configure interaction, and install existing plugins |
+| [limr-plugin-development](skills/limr-plugin-development/SKILL.md) | Build standalone module packages with a TypeScript / ESM / CSS starter and validation guidance |
+
+Skills ship in the npm package and can also be downloaded from this repository. Copy the entire skill directory to keep references and templates together. See [download, installation, and invocation](docs/en/ai-skills.md) for Codex project and user scopes.
+
+## Styles and runtime
+
+- `styles.css` includes light/dark styling and local Maple code fonts. `styles/base.css` provides the same styling without loading Maple. Font assets remain in the npm download. Choose one stylesheet.
+- `appearance` scopes CSS themes across the reader and portalled controls. Applications or system fonts supply body typography.
+- Code highlighting and math load on demand. Video loads near the viewport by default, with a click-to-load option. Remote media may contact its source site.
+- The full DOM remains available for browser search, native selection, and printing. Streaming appends reuse stable blocks and finish with a full parse; not every edit is incremental.
+- Unregistered HTML is displayed as text. Markdown-supplied JavaScript expressions are never executed. Custom renderers own their data and remote requests.
+
+See [styles and fonts](docs/en/styles.md), [API](docs/en/api.md), and [performance and limits](docs/en/performance.md).
+
+## Local development
+
+```sh
+pnpm install
+pnpm dev
+pnpm check
+pnpm test:docs
+pnpm exec playwright install chromium
+pnpm test:browser
+```
+
+Local development uses Python 3 to generate downloadable Skill archives. The header switches between Playground and LiMR-rendered, bilingual Docs.
+
+The local Playground runs at `http://127.0.0.1:4173`. Use `@linloir/limr/core` for parsing without React/DOM. Other entry points are `@linloir/limr/react` and `@linloir/limr/extensions`.
+
+[MIT License](LICENSE). Developed with Codex.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# LiMR
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@linloir/limr.svg)](https://www.npmjs.com/package/@linloir/limr)
+
+**简体中文** · [English](README.en.md)
+
+**Linloir’s limr Is a Markdown Renderer.** 面向长文阅读和流式输出的 React Markdown 渲染器。正文、目录、引用卡片、选区和高亮共享文档状态，也可以拆开组合到自己的界面中。
+
+[在线 Playground](https://linloir.github.io/LiMR/) · [中文文档](docs/zh-CN/README.md) · [English docs](docs/en/README.md) · [AI Skills](docs/zh-CN/ai-skills.md)
+
+## 安装与使用
+
+```sh
+npm install @linloir/limr
+# 或 pnpm add @linloir/limr
+```
+
+```tsx
+import { Reader, chinese } from '@linloir/limr';
+import '@linloir/limr/styles.css';
+import '@linloir/limr/math.css';
+
+const source = '# 开始阅读\n\n支持 **Markdown** 与 $E = mc^2$。';
+
+export default function Article() {
+  return <Reader source={source} locale={chinese} />;
+}
+```
+
+需要 React / React DOM **18.3 或 19**、Node.js **20+** 和支持 ESM 的构建工具。交互功能面向现代浏览器；支持 Node SSR。默认界面语言为英文，中文界面传入 `chinese`。`math.css` 在使用公式时引入。
+
+只显示正文，或显示持续生成的回答：
+
+```tsx
+import { Markdown } from '@linloir/limr';
+
+export function Answer({ text, generating }: { text: string; generating: boolean }) {
+  return <Markdown source={text} streaming={generating} followOutput />;
+}
+```
+
+`source` 是累计的完整字符串，生成结束时把 `streaming` 设为 `false`。`followOutput` 默认关闭；开启后在读者向上滚动时暂停跟随。`Markdown` 不自带目录、侧栏或选区工具栏。
+
+## 支持什么
+
+| 场景 | 能力 |
+| --- | --- |
+| 文档阅读 | CommonMark、GFM 表格/任务列表/脚注、数学公式、Shiki 代码高亮 |
+| 富内容 | 图片与图组、图注、视频、释义、练习题、拓展阅读、引用、原文/译文/对照 |
+| 阅读交互 | 响应式目录、桌面标注侧栏、窄屏浮层、复制、四种高亮样式 |
+| 应用集成 | 受控标注、原始 UTF-16 坐标、多个独立阅读器、内部滚动容器、SSR |
+| 扩展 | 自定义语法、React 渲染组件、标注类型、选区动作、参数与 CSS 主题包 |
+
+默认内容标注类型是 `citation`；`highlight` 是内置持久高亮。笔记、提问和聊天标注由应用插件提供，`question()` 则是默认的练习题正文模块。完整写法见[语法手册](docs/zh-CN/syntax.md)。
+
+```markdown
+<definition title="定义">
+
+在特殊区块中继续使用 **Markdown**。
+
+</definition>
+
+这段内容有参考来源<ref id="paper" />。
+
+<citation id="paper" title="参考资料" url="https://example.com/paper" summary="简短摘要" />
+```
+
+## 组合与扩展
+
+`Reader` 提供完整布局；自定义布局可用 `DocumentProvider` 组合 `Markdown`、`TableOfContents`、`AnnotationSidebar`、`AnnotationOverlay` 和 `SelectionToolbar`。详见[项目集成](docs/zh-CN/integration.md)。
+
+```tsx
+import { Reader, defineBlock } from '@linloir/limr';
+
+const plugins = [defineBlock({
+  name: 'notice',
+  component: ({ children }) => <aside className="notice">{children}</aside>,
+})];
+
+export function Notice() {
+  return <Reader source={'<notice>\n\n**自定义内容**\n\n</notice>'} plugins={plugins} />;
+}
+```
+
+`plugins` 追加到默认扩展；`extensions` 替换整个扩展列表，`extensions={[]}` 使用基础 CommonMark。同名扩展使用 `replaceExtension()` 显式替换。配置应保持引用稳定。
+
+插件可以拥有完整卡片 UI（`overlay.Card`）、侧栏摘要（`sidebar.Preview`）、异步加载和选区操作。使用 [AI 插件开发 Skill](skills/limr-plugin-development/SKILL.md) 或[独立插件包指南](docs/zh-CN/plugin-packages.md)创建可安装的包，再通过 `plugins` 引入。仓库提供[笔记](examples/notes.tsx)、[流式助手](examples/assistant.tsx)、[独立插件](examples/packages/reading-tools/index.js)和 [CSS 主题](examples/packages/paper-theme/index.css)示例；`@limr-example/*` 是未发布的本地示例包。
+
+## AI Skills
+
+| Skill | 用途 |
+| --- | --- |
+| [limr-use](skills/limr-use/SKILL.md) | 指导 AI 在项目中接入 LiMR、编写内容、配置交互和引入已有插件 |
+| [limr-plugin-development](skills/limr-plugin-development/SKILL.md) | 指导 AI 开发独立模块包，附带 TypeScript / ESM / CSS 模板及验证步骤 |
+
+Skills 随 npm 包分发，也可以从仓库下载。复制完整目录即可保留引用文件和模板；[下载、安装与调用说明](docs/zh-CN/ai-skills.md)包含 Codex 项目级与用户级配置。
+
+## 样式与运行方式
+
+- `styles.css` 包含默认浅色/深色样式和本地 Maple 代码字体；`styles/base.css` 提供相同样式但不加载 Maple。字体资产仍包含在 npm 包中。两者选一即可。
+- `appearance` 为 CSS 主题提供作用域，也会传播到 portal 中的工具栏和浮层。正文中文字体由应用或系统提供。
+- 代码高亮和公式按需加载。视频默认接近视口时加载，可以配置为点击加载；远程媒体仍可能访问其来源站点。
+- 保留全文 DOM，支持浏览器查找、原生选择与打印。流式追加复用稳定区块，结束时完整解析；并非所有编辑都能局部解析。
+- 未注册的 HTML 显示为原文，Markdown 中的 JavaScript 表达式不执行。自定义组件负责自己的数据和远程请求。
+
+详见[样式与字体](docs/zh-CN/styles.md)、[API](docs/zh-CN/api.md)和[性能与限制](docs/zh-CN/performance.md)。
+
+## 本地开发
+
+```sh
+pnpm install
+pnpm dev
+pnpm check
+pnpm test:docs
+pnpm exec playwright install chromium
+pnpm test:browser
+```
+
+本地开发需要 Python 3 生成 Skill 下载归档。标题栏可切换 Docs / Playground，Docs 由 LiMR 渲染，可切换语言。
+
+本地 Playground 位于 `http://127.0.0.1:4173`。纯解析场景使用 `@linloir/limr/core`，不依赖 React/DOM；其他入口为 `@linloir/limr/react` 和 `@linloir/limr/extensions`。
+
+[MIT License](LICENSE). Developed with Codex.

package/benchmarks/results/browser.json

@@ -0,0 +1,237 @@
+{
+  "date": "2026-10-12T09:32:24.107Z",
+  "browser": "156.0.8078.4",
+  "measurement": "Synchronous React update plus forced layout, production Vite build. Each trial has an isolated page, font-ready warmup and alternating renderer order. Streaming updates spaced by one animation frame; idle frame time excluded.",
+  "results": [
+    {
+      "sections": 200,
+      "renderer": "limr",
+      "median": {
+        "characters": 87381,
+        "updates": 1,
+        "totalMs": 126.10000002384186,
+        "p95Ms": 126.10000002384186,
+        "maxMs": 126.10000002384186,
+        "elements": 4002
+      },
+      "samples": [
+        {
+          "characters": 87381,
+          "updates": 1,
+          "totalMs": 124.69999998807907,
+          "p95Ms": 124.69999998807907,
+          "maxMs": 124.69999998807907,
+          "elements": 4002
+        },
+        {
+          "characters": 87381,
+          "updates": 1,
+          "totalMs": 126.10000002384186,
+          "p95Ms": 126.10000002384186,
+          "maxMs": 126.10000002384186,
+          "elements": 4002
+        },
+        {
+          "characters": 87381,
+          "updates": 1,
+          "totalMs": 147.5,
+          "p95Ms": 147.5,
+          "maxMs": 147.5,
+          "elements": 4002
+        }
+      ]
+    },
+    {
+      "sections": 200,
+      "renderer": "react-markdown",
+      "median": {
+        "characters": 87381,
+        "updates": 1,
+        "totalMs": 134,
+        "p95Ms": 134,
+        "maxMs": 134,
+        "elements": 3601
+      },
+      "samples": [
+        {
+          "characters": 87381,
+          "updates": 1,
+          "totalMs": 122.40000003576279,
+          "p95Ms": 122.40000003576279,
+          "maxMs": 122.40000003576279,
+          "elements": 3601
+        },
+        {
+          "characters": 87381,
+          "updates": 1,
+          "totalMs": 134,
+          "p95Ms": 134,
+          "maxMs": 134,
+          "elements": 3601
+        },
+        {
+          "characters": 87381,
+          "updates": 1,
+          "totalMs": 142.39999997615814,
+          "p95Ms": 142.39999997615814,
+          "maxMs": 142.39999997615814,
+          "elements": 3601
+        }
+      ]
+    },
+    {
+      "sections": 2000,
+      "renderer": "limr",
+      "median": {
+        "characters": 877782,
+        "updates": 1,
+        "totalMs": 1345.4000000357628,
+        "p95Ms": 1345.4000000357628,
+        "maxMs": 1345.4000000357628,
+        "elements": 40002
+      },
+      "samples": [
+        {
+          "characters": 877782,
+          "updates": 1,
+          "totalMs": 1337.699999988079,
+          "p95Ms": 1337.699999988079,
+          "maxMs": 1337.699999988079,
+          "elements": 40002
+        },
+        {
+          "characters": 877782,
+          "updates": 1,
+          "totalMs": 1345.4000000357628,
+          "p95Ms": 1345.4000000357628,
+          "maxMs": 1345.4000000357628,
+          "elements": 40002
+        },
+        {
+          "characters": 877782,
+          "updates": 1,
+          "totalMs": 1394.199999988079,
+          "p95Ms": 1394.199999988079,
+          "maxMs": 1394.199999988079,
+          "elements": 40002
+        }
+      ]
+    },
+    {
+      "sections": 2000,
+      "renderer": "react-markdown",
+      "median": {
+        "characters": 877782,
+        "updates": 1,
+        "totalMs": 1437.5999999642372,
+        "p95Ms": 1437.5999999642372,
+        "maxMs": 1437.5999999642372,
+        "elements": 36001
+      },
+      "samples": [
+        {
+          "characters": 877782,
+          "updates": 1,
+          "totalMs": 1308.1000000238419,
+          "p95Ms": 1308.1000000238419,
+          "maxMs": 1308.1000000238419,
+          "elements": 36001
+        },
+        {
+          "characters": 877782,
+          "updates": 1,
+          "totalMs": 1437.5999999642372,
+          "p95Ms": 1437.5999999642372,
+          "maxMs": 1437.5999999642372,
+          "elements": 36001
+        },
+        {
+          "characters": 877782,
+          "updates": 1,
+          "totalMs": 1481.3999999761581,
+          "p95Ms": 1481.3999999761581,
+          "maxMs": 1481.3999999761581,
+          "elements": 36001
+        }
+      ]
+    },
+    {
+      "sections": 80,
+      "stream": true,
+      "renderer": "limr",
+      "median": {
+        "characters": 34860,
+        "updates": 138,
+        "totalMs": 306.09999972581863,
+        "p95Ms": 2.900000035762787,
+        "maxMs": 31.099999964237213,
+        "elements": 1602
+      },
+      "samples": [
+        {
+          "characters": 34860,
+          "updates": 138,
+          "totalMs": 298.60000014305115,
+          "p95Ms": 2.800000011920929,
+          "maxMs": 31.80000001192093,
+          "elements": 1602
+        },
+        {
+          "characters": 34860,
+          "updates": 138,
+          "totalMs": 306.09999972581863,
+          "p95Ms": 2.900000035762787,
+          "maxMs": 31.099999964237213,
+          "elements": 1602
+        },
+        {
+          "characters": 34860,
+          "updates": 138,
+          "totalMs": 317.099999666214,
+          "p95Ms": 3,
+          "maxMs": 31.600000023841858,
+          "elements": 1602
+        }
+      ]
+    },
+    {
+      "sections": 80,
+      "stream": true,
+      "renderer": "react-markdown",
+      "median": {
+        "characters": 34860,
+        "updates": 138,
+        "totalMs": 1864.100000321865,
+        "p95Ms": 23.69999998807907,
+        "maxMs": 32.80000001192093,
+        "elements": 1441
+      },
+      "samples": [
+        {
+          "characters": 34860,
+          "updates": 138,
+          "totalMs": 1842.2000004649162,
+          "p95Ms": 26,
+          "maxMs": 27.80000001192093,
+          "elements": 1441
+        },
+        {
+          "characters": 34860,
+          "updates": 138,
+          "totalMs": 1864.100000321865,
+          "p95Ms": 23.69999998807907,
+          "maxMs": 32.80000001192093,
+          "elements": 1441
+        },
+        {
+          "characters": 34860,
+          "updates": 138,
+          "totalMs": 1893.8000000715256,
+          "p95Ms": 22.900000035762787,
+          "maxMs": 37.799999952316284,
+          "elements": 1441
+        }
+      ]
+    }
+  ]
+}

package/benchmarks/results/node.json

@@ -0,0 +1,75 @@
+{
+  "date": "2026-10-12T09:34:31.373Z",
+  "node": "v20.19.5",
+  "mode": "production",
+  "platform": "linux 6.18.40.1-microsoft-standard-WSL2",
+  "cpu": "13th Gen Intel(R) Core(TM) i7-13700",
+  "results": [
+    {
+      "scenario": "static-gfm",
+      "characters": 87381,
+      "sections": 200,
+      "core": {
+        "medianMs": 109.32,
+        "minMs": 102.73,
+        "maxMs": 125.04
+      },
+      "mdast": {
+        "medianMs": 101.78,
+        "minMs": 95.3,
+        "maxMs": 114.94
+      },
+      "limrSSR": {
+        "medianMs": 123.85,
+        "minMs": 123.37,
+        "maxMs": 132.6
+      },
+      "reactMarkdownSSR": {
+        "medianMs": 135.8,
+        "minMs": 133.71,
+        "maxMs": 162.13
+      }
+    },
+    {
+      "scenario": "static-gfm",
+      "characters": 877782,
+      "sections": 2000,
+      "core": {
+        "medianMs": 2702.76,
+        "minMs": 2546.75,
+        "maxMs": 6815.28
+      },
+      "mdast": {
+        "medianMs": 2864.73,
+        "minMs": 2501.24,
+        "maxMs": 4779.01
+      },
+      "limrSSR": {
+        "medianMs": 5508.29,
+        "minMs": 2642.18,
+        "maxMs": 9102.85
+      },
+      "reactMarkdownSSR": {
+        "medianMs": 2720.7,
+        "minMs": 2698.5,
+        "maxMs": 5033.33
+      }
+    },
+    {
+      "scenario": "streaming-gfm",
+      "characters": 34860,
+      "chunkSize": 256,
+      "updates": 137,
+      "incremental": {
+        "medianMs": 164.04,
+        "minMs": 152.69,
+        "maxMs": 175.39
+      },
+      "fullParse": {
+        "medianMs": 2673.74,
+        "minMs": 2626.34,
+        "maxMs": 2769.29
+      }
+    }
+  ]
+}