@linloir/limr 0.1.0 → 1.0.0

package/docs/en/extensions.md

@@ -0,0 +1,159 @@
+# Extension development
+
+> 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/extensions) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/extensions.md)
+
+Start with [built-in modules](modules.md) for module objects, factories, names, Markdown tags, and the difference between `extensions` and `plugins`.
+
+## Choose an interface
+
+| Need | Interface |
+| --- | --- |
+| A new block with Markdown content | defineBlock |
+| A standalone annotation type | defineAnnotation |
+| Combined syntax, annotations, actions, and parameters | defineExtension / RendererExtension |
+| A different view for an existing node | components |
+| New parsing rules | micromark + mdast, with transform when needed |
+| Visual changes only | CSS theme package + appearance |
+
+These APIs are publicly exported from @linloir/limr. Third-party packages must not import src/dist internals or non-public helpers such as useRuntime. See [plugin packages](plugin-packages.md) for a complete standalone starter.
+
+## Append, remove, and replace defaults
+
+```tsx
+import { Reader, standard, replaceExtension, video, defineBlock } from '@linloir/limr';
+
+const extensions = replaceExtension(standard(), video({ loading: 'click' }));
+const plugins = [defineBlock({
+  name: 'reading-tip',
+  component: ({ children }) => <aside className="reading-tip">{children}</aside>,
+})];
+
+export function Article({ source }: { source: string }) {
+  return <Reader source={source} extensions={extensions} plugins={plugins} />;
+}
+```
+
+Filter by name to remove a module. Extension names, tag names, and directive names must each be unique; duplicates throw. Do not append a second citation or video through plugins. replaceExtension replaces a matching name or appends if absent. Keep configurations stable to avoid rebuilding the parser during streaming.
+
+## Custom content blocks
+
+```tsx
+import { defineBlock } from '@linloir/limr';
+
+export const notice = defineBlock({
+  name: 'notice',
+  component: ({ children, renderAttribute }) => <aside className="notice">
+    <header>{renderAttribute('title')}</header>
+    {children}
+  </aside>,
+});
+```
+
+This supports `<notice title="Tip">…</notice>` and `:::notice{title="Tip"}`. name becomes the tag and directive name unless tags/directives overrides them. defineBlock defaults to display: block, selection: content, and scope: local.
+
+| NodeRendererProps | Use |
+| --- | --- |
+| node | AST node and static attributes |
+| children | Already-rendered subtree; reuse it where possible |
+| source | Source for **this node**, not the entire document |
+| pending | Whether its tail block is still streaming |
+| renderChildren(nodes, { trailing? }) | Rearrange an existing subtree or append an action-only marker |
+| renderValue(tokens?) | Render literals/tokens while preserving selection and annotation insertion |
+| renderAttribute(name) | Render attribute text with original source coordinates |
+
+Do not stringify/reparse children or render only node.value when source mapping is required. Use selection: atomic for charts/media without character correspondence, and data-limr-selection-surface for a visual boundary. Public InlineMarker supports action-only markers without creating annotations.
+
+## Plugins own card presentation
+
+```tsx
+import { AnnotationCard, AnnotationMarkdown, defineAnnotation, ToolIcon } from '@linloir/limr';
+
+export const note = defineAnnotation<{ text: string }>({
+  type: 'example:note',
+  label: 'Note',
+  icon: <ToolIcon name="note" />,
+  color: '#6B9BD2',
+  Content: ({ data, loading, error, retry }) => loading ? <p>Loading…</p>
+    : error ? <button onClick={retry}>Retry</button>
+    : <AnnotationMarkdown source={data?.text ?? ''} />,
+  sidebar: {
+    Preview: ({ data }) => data?.text ? <span>{data.text}</span> : null,
+    previewLines: 2,
+  },
+  overlay: {
+    Card: props => <AnnotationCard {...props} title="Note" />,
+    previewWidth: 320,
+    expand: { placement: 'center', width: 640, maxHeight: '80dvh' },
+  },
+});
+```
+
+Content handles presentation (preview / expanded / sidebar), editing, data, and resource state. overlay.Card owns title, body, and controls; use AnnotationCard or render everything yourself. children contains the shared loaded content. LiMR owns positioning, portals, focus, animation, and exit lifecycle. Keep the plugin's semantic title.
+
+Expansion is opt-in. placement accepts anchor / center, sizes accept pixels or CSS lengths, and a resolver can vary the policy by annotation. sidebar.Preview reads local data only; do not fetch for a summary. Preview: false or returning null hides it. The first type in an occurrence owns grouped appearance and summary; annotations provides the group.
+
+sidebar also accepts previewLines, previewColor, color, borderColor, titleColor, textColor, excerptColor, and collapseOnContentClick. Do not repeat card padding at the content root. Use --limr-sidebar-padding-inline and manage internal paragraph spacing.
+
+## Selection actions
+
+```tsx
+import { defineExtension, ToolIcon } from '@linloir/limr';
+
+export const savePassage = defineExtension({
+  name: 'example:save-passage',
+  actions: [{
+    id: 'example:save-passage', label: 'Save passage', icon: <ToolIcon name="note" />,
+    visible: ({ selection }) => selection.settled && selection.quality !== 'unmapped',
+    run(context) {
+      const id = `example-note-${crypto.randomUUID()}`;
+      context.addAnnotation({
+        id, type: 'example:note', data: { text: context.selection.text },
+        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();
+    },
+  }],
+});
+```
+
+Install this alongside the note extension above. SelectionAction requires id, label, and icon, and can define visible, disabled, run, onHover, renderExpanded, or render. Use context.run for panel operations to share toolbar busy/error handling. Context contains the selection, full snapshot, annotations/highlight for the fragment, locale, cancellation signal, and commands. Later actions override matching IDs; explicit host actions take final precedence.
+
+## Parameters
+
+```tsx
+import { defineExtension, useRendererParameter } from '@linloir/limr';
+
+declare module '@linloir/limr' {
+  interface RendererParameters { exampleDetail?: 'short' | 'full' }
+}
+
+export const glossary = defineExtension({
+  name: 'example:glossary', tags: ['glossary'], scope: 'local',
+  parameters: { exampleDetail: 'short' },
+  components: {
+    glossary: ({ children }) => <aside data-detail={useRendererParameter('exampleDetail')}>
+      {children}
+    </aside>,
+  },
+});
+```
+
+The host overrides defaults with parameters={{ exampleDetail: 'full' }}. Parameter updates affect views without reparsing; later defaults win. A standalone package must include declaration merging in its exported .d.ts.
+
+## Parsing and streaming constraints
+
+SyntaxExtension supports micromark, mdast, tags, directives, display, selection, transform, and scope. Transforms default to document scope. Declare scope: local only if the transform depends on the current subtree and never revises earlier content or needs document-wide semantics. context.source is the original whole document; positions remain original UTF-16 offsets. Do not regex-rewrite source before parsing.
+
+Unknown custom tags display their complete original text, including Markdown inside. Unknown directives in the default configuration render their inner Markdown without outer directive markers; with no directive extension installed, basic Markdown parsing applies. Incomplete tags fall back with diagnostics and retry on append. Finish with finish() or streaming=false. Transform exceptions become diagnostics. Client renderer boundaries can fall back to source, but React error boundaries do not catch server-rendering exceptions.
+
+Validate tags/directives, Chinese/emoji, offsets, equivalence between finalized streams and one-shot parsing, SSR, and browser behavior for new interactions. For distribution, test actual packed consumption as described in [plugin packages](plugin-packages.md).
+
+## Plugin localization
+
+From 1.0.0, components can read the merged locale through useLocale() and select their own dictionary by locale.language. AnnotationType.label accepts a string or `(locale) => string`; actions use context.locale. Citation titles switch between Citation and 引用. A stable plugin instance can update labels without rewriting source. Saved user notes are never translated.

package/docs/en/getting-started.md

@@ -0,0 +1,67 @@
+# Getting started
+
+> 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/getting-started) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/getting-started.md)
+
+## Install
+
+```sh
+npm install @linloir/limr
+```
+
+The host needs React and React DOM 18.3 or 19. LiMR is ESM and requires Node.js 20+. Use an ESM-capable build tool such as Vite. The application must import CSS explicitly.
+
+## Complete reader
+
+```tsx
+import { Reader } from '@linloir/limr';
+import '@linloir/limr/styles.css';
+import '@linloir/limr/math.css';
+
+const source = `# LiMR
+
+Supports **emphasis**, tables, code, and $x^2$.
+
+## References
+
+Read this passage<ref id="guide" />.
+
+<citation id="guide" title="Guide" url="https://example.com/guide" />`;
+
+export function Article() {
+  return <Reader source={source} theme="auto" />;
+}
+```
+
+Wide containers show contents, body, and annotations. Below `sidebarBreakpoint` (1120px by default), annotations use an overlay. Contents become a collapsible list on narrow screens.
+
+## Body only
+
+```tsx
+import { Markdown } from '@linloir/limr';
+import '@linloir/limr/styles/base.css';
+
+export function Excerpt() {
+  return <Markdown source="Some **Markdown**." />;
+}
+```
+
+Standalone `Markdown` retains parsing and selection support but does not mount a toolbar. Set `interactive={false}` to disable selection tracking for static content. Inside a `DocumentProvider`, use `<Markdown />` without `source` to share its document.
+
+## Choose styles
+
+| Import | Includes |
+| --- | --- |
+| `@linloir/limr/styles.css` | Default theme, layout, interaction, and Maple code fonts |
+| `@linloir/limr/styles/base.css` | The same styling without importing Maple font CSS |
+| `@linloir/limr/fonts.css` | Maple fonts only, for separate use with base.css |
+| `@linloir/limr/math.css` | KaTeX styles and local math fonts |
+
+Choose either styles.css or styles/base.css. Selecting base does not remove font files from the npm download. Body fonts come from the host or system; the Playground's Noto Serif SC is not automatically loaded by the library.
+
+## Next steps
+
+- Read [default syntax](syntax.md) to distinguish built-in content modules from application annotation plugins.
+- Read [application integration](integration.md) for streaming, scroll containers, and SSR.
+- Install the [limr-use Skill](ai-skills.md) for AI-assisted integration.

package/docs/en/integration.md

@@ -0,0 +1,130 @@
+# Application integration
+
+> 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/integration) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/integration.md)
+
+## Choose a component
+
+Use `Reader` for the complete experience and `Markdown` for standalone content. For a custom layout, one DocumentProvider manages one primary Markdown plus its navigation, cards, and toolbar. Passing source to Markdown inside a provider creates an independent document instead of sharing the parent state.
+
+## Streaming content
+
+```tsx
+import { Markdown } from '@linloir/limr';
+
+export function StreamingAnswer({ answer, generating }: {
+  answer: string;
+  generating: boolean;
+}) {
+  return <Markdown source={answer} streaming={generating} followOutput />;
+}
+```
+
+The application owns transport and appends each chunk to the complete answer. Do not pass only the newest chunk as source. The final update must set streaming to false to complete semantic correction. followOutput follows only while the reader remains near the bottom. The core engine supports append(chunk) / finish(); React props take the accumulated string.
+
+## Nested scroll containers
+
+```tsx
+import { useState } from 'react';
+import { Reader } from '@linloir/limr';
+
+export function ScrollPanel({ source }: { source: string }) {
+  const [scrollRoot, setScrollRoot] = useState<HTMLDivElement | null>(null);
+  return <div ref={setScrollRoot} style={{ height: '80vh', overflowY: 'auto' }}>
+    <Reader source={source} scrollRoot={scrollRoot} scrollOffset={32} />
+  </div>;
+}
+```
+
+Window scrolling needs no scrollRoot. Set scrollOffset for a fixed header and --limr-sticky-top for sticky navigation. Give Reader a new React key when switching to an independent document, plus a stable documentId unique on the page, to recreate task and interaction state.
+
+## Custom composition
+
+This is a fixed desktop layout. Prefer Reader for responsive sidebar switching, collapsible contents, and automatic height. With your own breakpoints, decide when to mount the sidebar or overlay.
+
+```tsx
+import { DocumentProvider, Markdown, TableOfContents, AnnotationSidebar,
+  SelectionToolbar } from '@linloir/limr';
+
+export function DesktopReader({ source }: { source: string }) {
+  return <DocumentProvider source={source}>
+    <div style={{ display: 'grid', gridTemplateColumns: '180px minmax(0, 1fr) 280px', gap: 24 }}>
+      <TableOfContents style={{ position: 'sticky', top: 24, alignSelf: 'start', maxHeight: '80vh' }} />
+      <main className="limr-reader-content" style={{ minHeight: '70vh', overflow: 'clip' }}>
+        <Markdown />
+      </main>
+      <AnnotationSidebar />
+    </div>
+    <SelectionToolbar />
+  </DocumentProvider>;
+}
+```
+
+Keep body and synchronized sidebar in the same scroll container and unscaled coordinate system. A grid row or the host supplies sidebar height. Do not grow the page to the total card height or add a separate scroll container to the synchronized list. Long card bodies can scroll independently. For a drawer or ordinary list, use AnnotationSidebar with sync="none" and let the host constrain height and overflow.
+
+For an overlay layout, mount Markdown, AnnotationOverlay, and SelectionToolbar under the same provider. The two floating components accept portalRoot; Reader does not expose that prop directly, so compose components when it is needed.
+
+## Controlled data and document switching
+
+```tsx
+import { useState } from 'react';
+import { Reader, type Annotation } from '@linloir/limr';
+
+export function SavedArticle({ id, source }: { id: string; source: string }) {
+  const [annotations, setAnnotations] = useState<readonly Annotation[]>([]);
+  return <Reader key={id} documentId={id} source={source}
+    annotations={annotations} onAnnotationsChange={setAnnotations} />;
+}
+```
+
+This illustrates state for one article. In an application, load/store annotations by article ID and replace the array on navigation; a React key does not clear host state. Omit annotations for internal state. When supplied, accept edits through onAnnotationsChange and pass the new array back, or editing throws. Do not mutate arrays or data in place. See [annotations and selection](annotations.md) for persistence and relocation rules.
+
+## Global translation mode
+
+```tsx
+import { useState } from 'react';
+import { Reader, type TranslationMode } from '@linloir/limr';
+
+export function BilingualArticle({ source }: { source: string }) {
+  const [mode, setMode] = useState<TranslationMode | undefined>();
+  return <Reader source={source}
+    parameters={{ translationMode: mode, onTranslationModeChange: setMode }} />;
+}
+```
+
+Parameters update views without reparsing. Other plugins can register parameters as described in [extension development](extensions.md).
+
+## SSR and client boundaries
+
+Place interactive components inside your framework's client component boundary (for example, 'use client' where required) and let the framework arrange SSR/hydration. Avoid window/document at module initialization. Keep initial source, documentId, and configuration consistent between server and client.
+
+Synchronous SSR falls back to formula source until math is loaded. To include complete KaTeX output in the first HTML, preload it on the server:
+
+```tsx
+import { renderToString } from 'react-dom/server';
+import { Markdown, preloadMath } from '@linloir/limr';
+
+export async function renderArticle(source: string) {
+  await preloadMath();
+  return renderToString(<Markdown source={source} documentId="server-article" />);
+}
+```
+
+React streaming SSR can also handle Suspense. Shiki adds highlighting on the client; SSR already includes code text. Annotation load requests start when a card is shown on the client. Put preloaded data in annotation.data if needed. The host must still serve CSS and fonts.
+
+## Existing plugins and themes
+
+Import a factory from a real plugin package and create a stable plugins array outside rendering or with useMemo. Import plugin CSS explicitly as documented by its author. Themes are selected with appearance, not passed through plugins. See [plugin packages](plugin-packages.md) for installation and local tgz consumption.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Missing layout or malformed formulas | Import styles or base, plus math.css |
+| Default modules disappear after adding a plugin | Use plugins to append, rather than replacing extensions |
+| Annotation edits do not persist | Return a new array from the controlled callback |
+| Body and navigation disagree | A Markdown source prop may have created a second provider |
+| Nested scrolling targets the wrong place | Pass the actual scrolling DOM element as scrollRoot |
+| Portal colors differ from the reader | Scope CSS by data-limr-appearance |
+| Streaming repeatedly reparses everything | Keep extensions/plugins stable and check document-scoped transforms |

package/docs/en/modules.md

@@ -0,0 +1,80 @@
+# Built-in modules
+
+> 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/modules) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/modules.md)
+
+## What is a module?
+
+LiMR's base parser understands CommonMark: headings, paragraphs, lists, links, images, and code fences. A **module** is a configuration object that adds capabilities, such as formulas, video rendering, or citation cards. Its public TypeScript type is `RendererExtension`, so the API also calls it an extension.
+
+A module can combine parsing rules, React components, annotation types, toolbar actions, and default parameters. It need not include all of them. For example, `math` adds formula syntax and rendering, `code-highlight` colors existing code fences, and `citation` provides both reference syntax and annotation cards.
+
+A **plugin** usually means a module added by your application or supplied by a third-party package. It uses the same interface as built-in modules. An npm package distributes code and can export several modules. Passing a module to `plugins` appends it to the existing configuration.
+
+## Functions, module names, and tag names
+
+Consider video:
+
+```tsx
+import { Reader, standard, replaceExtension, video } from '@linloir/limr';
+
+const videoModule = video({ loading: 'click' });
+// videoModule.name === 'video'
+const extensions = replaceExtension(standard(), videoModule);
+
+export function Article() {
+  return <Reader extensions={extensions} source={'<video src="/lesson.mp4" />'} />;
+}
+```
+
+| Form | Where it belongs | Meaning |
+| --- | --- | --- |
+| `video` / `video(...)` | Application JavaScript / TypeScript | The imported function / a call that creates a module configuration object |
+| `videoModule` | Application code | Your variable name for that object; you can rename it |
+| `'video'` | The module object's `name` property | A stable identifier used to distinguish, replace, and remove modules |
+| `<video … />` / `<md-video … />` | Markdown content | Two tags registered by the module, using the same video renderer |
+| `::video{…}` | Markdown content | A registered directive; a `:::video` container also works |
+
+The names need not match. The code-highlighting factory is `codeHighlight()`, its module name is `'code-highlight'`, and its content uses ordinary code fences without a `<code-highlight>` tag. Writing `video()` or the string `'video'` inside Markdown does not enable a module. Pass the returned object to `plugins`, not a string.
+
+`video({ loading: 'click' })` sets module defaults for that Reader. A `<video loading="eager" … />` tag overrides the setting for one video. Available options vary by module; see [default syntax](syntax.md).
+
+## Ten default modules included with LiMR
+
+These modules ship in `@linloir/limr`; they do not require ten separate npm installations. `standard()` returns an array containing the following ten module objects, each with its default settings.
+
+| Factory function | Object's `name` | Capability and content syntax |
+| --- | --- | --- |
+| `gfm()` | `gfm` | Tables, `~~strikethrough~~`, tasks, autolinks, `[^id]` endnotes |
+| `math()` | `math` | `$…$` inline and `$$…$$` display math; also import math.css |
+| `codeHighlight()` | `code-highlight` | Shiki colors for code fences with a language identifier |
+| `definition()` | `definition` | `<definition>` cards with a title and Markdown body |
+| `question()` | `question` | `<question>` exercises with choices, hints, answers, and local scoring |
+| `extras()` | `extras` | `<extras>` / `<extra>` further-reading links |
+| `video()` | `video` | `<video>` / `<md-video>` native video, YouTube, and Bilibili embeds |
+| `figures()` | `figures` | `<figures>` / `<figure>` responsive groups, single figures, and captions |
+| `citation()` | `citation` | `<citation>` source definitions and `<ref>` markers with cards |
+| `translations()` | `translations` | `<translations>` original, translated, and parallel views |
+
+Import these functions from `@linloir/limr` or `@linloir/limr/extensions`. `standard()` is a convenience function returning an array, not an eleventh module.
+
+`Reader`, standalone `Markdown`, and `DocumentProvider` automatically use `standard()` when `extensions` is omitted. Your first `<Reader source={source} />` therefore supports these capabilities. Components inside a shared Provider inherit its configuration. Core-only `createDocument()` starts with CommonMark; extensions must be explicit, and it does not display React UI.
+
+Highlight, copy, and annotation deletion are built-in toolbar actions. Highlights are saved as annotation data, not a separate Markdown tag. The Playground's margin notes, reading notes, questions, footnote annotations, and simulated assistant come from example plugins and **are not automatically installed in every Reader**. The `question()` exercise module is also separate from question annotations.
+
+## Choosing a configuration
+
+You do not need to call `standard()` when the defaults suffice. For customization, distinguish three operations:
+
+| Goal | Configuration | Result |
+| --- | --- | --- |
+| Add your own capability | `plugins={[myPlugin]}` | Keep default modules and append your plugin object |
+| Keep only selected capabilities | `extensions={[gfm(), math()]}` | Replace the complete default module list; CommonMark remains available |
+| Configure a built-in module | `extensions={replaceExtension(standard(), video({ loading: 'click' }))}` | Replace video by module `name`, preserving the other modules |
+
+To remove one module, filter the array: `standard().filter(module => module.name !== 'video')`. Use `extensions={[]}` when extension syntax is unnecessary.
+
+Do not append `plugins={[video()]}` while the default video module is present: duplicate module names, tags, or directives throw. Without the corresponding module, unknown tags render as text, unknown directives may retain only their inner Markdown, and unknown annotation data remains with generic fallback UI. See [architecture and behavior](architecture.md) for the precise boundaries.
+
+Next, try the [syntax examples](syntax.md), create modules with [extension development](extensions.md), or distribute them using [plugin packages](plugin-packages.md).

package/docs/en/performance.md

@@ -0,0 +1,53 @@
+# Performance and limits
+
+> 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/performance) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/performance.md)
+
+These are the repository's **2026-10-12 historical measurements**, retained for comparison. They were not rerun for this documentation/Playground update and are not guarantees.
+
+Environment: Intel Core i7-13700, WSL2/Linux, Node 20.19.5, Chromium 156.0.8078.4, React 19 production. Baseline: react-markdown 10.1.0 + remark-gfm 4.0.1.
+
+## Browser
+
+Both render equivalent GFM with the same typography, body only, excluding Reader navigation/sidebar. Values are medians of three isolated pages after warmup and font readiness, alternating renderer order. Timing includes synchronous React commits and forced layout, excluding network, asynchronous heavy resources, and idle frame time.
+
+| Scenario | LiMR | react-markdown |
+| --- | ---: | ---: |
+| 87,381 characters, 200 sections, initial mount | 126.1 ms | 134.0 ms |
+| 877,782 characters, 2,000 sections, initial mount | 1,345.4 ms | 1,437.6 ms |
+| 34,860 characters, 138 streaming commits, total synchronous time | 306.1 ms | 1,864.1 ms |
+| Same stream, per-commit P95 | 2.9 ms | 23.7 ms |
+
+The final full parse is included. P95 does not mean every frame stays below 16ms. Raw data: [browser.json](../../benchmarks/results/browser.json).
+
+## Selection and SSR
+
+Historical long-document selection paint latency P95 was 25.2–28.5ms; code was 18.9–19.4ms. This measures selectionchange to paint-layer updates, not hardware input-to-display latency. The same automated drag took 3.23s in LiMR and 1.52s in the baseline; similar rAF intervals do not imply identical processing cost. Data: [selection.json](../../benchmarks/results/selection.json).
+
+| Node scenario | LiMR | Baseline |
+| --- | ---: | ---: |
+| 87,381 characters, SSR | 123.85 ms | 135.80 ms |
+| 877,782 characters, SSR | 5,508.29 ms | 2,720.70 ms |
+| 34,860 characters, 137 core appends/finalization | 164.04 ms | 2,673.74 ms |
+
+Large-document SSR varied substantially: LiMR samples were 2.64–9.10s and baseline 2.70–5.03s. These results show no SSR advantage. The append baseline reparses the entire prefix each time. Data: [node.json](../../benchmarks/results/node.json).
+
+## Practical limits
+
+Keeping the full DOM supports search, selection, and printing, but initial long-document rendering still costs time. Incremental parsing reuses stable prefixes; long tail blocks, document-scoped transforms, definition changes, middle edits, and finalization can remain expensive. Keep extensions/plugins stable and limit highlighting languages/length when appropriate.
+
+The measurements do not cover large formula collections, Shiki cold starts, dense annotations, third-party plugins, full Reader layouts, or physical mobile devices. Installed font size also differs from browser transfers; see [styles and fonts](styles.md).
+
+## Reproduce in the repository
+
+```sh
+NODE_ENV=production pnpm bench
+pnpm exec vite build
+pnpm exec vite preview --host 127.0.0.1 --port 4174
+# In another terminal:
+pnpm bench:browser
+pnpm bench:selection
+```
+
+Avoid concurrent builds/benchmarks. Scripts write benchmarks/results. Reevaluate using your hardware, content, and built version rather than treating historical numbers as current-package acceptance.

package/docs/en/plugin-packages.md

@@ -0,0 +1,68 @@
+# Plugin packages
+
+> 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/plugin-packages) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/plugin-packages.md)
+
+A plugin exports a factory returning RendererExtension. Consumers append it through plugins. One package can provide syntax, annotations, actions, and parameters, with a separate CSS export, without editing LiMR itself.
+
+## Copyable starter
+
+The complete [plugin-template](../../skills/limr-plugin-development/assets/plugin-template/README.md) includes TypeScript, declaration output, CSS, package.json, and tsup configuration. It demonstrates a reading-tip block, an example:note card, and a save-selection action.
+
+After installing LiMR, run from your application:
+
+```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
+```
+
+In a source checkout, use skills/limr-plugin-development/assets/plugin-template. Replace the @example name, extension/type/action IDs, and implement your data/UI. The starter's private: true prevents accidental publication under an example name and still permits local packing.
+
+## Package contract
+
+| Field | Requirement |
+| --- | --- |
+| type | module |
+| exports["."] | import points to ESM; types points to .d.ts |
+| exports["./styles.css"] | Explicit export when the plugin needs CSS |
+| files | Built output and usage instructions |
+| sideEffects | ["**/*.css"] to retain imported styles |
+| peerDependencies | @linloir/limr and react; add react-dom when directly using it |
+| Build external | LiMR, React, react/jsx-runtime, and any React DOM entry used |
+
+Bundling another copy of LiMR or React breaks shared contexts/hooks. Externalize host dependencies and avoid internal deep imports. Ship parameter declaration merging with exported types.
+
+## Import into an application
+
+The @example package below is the starter, not a published npm package. Install the generated local archive; use the actual filename printed by 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: 'Reading note' })];
+
+export function Article({ source }: { source: string }) {
+  return <Reader source={source} plugins={plugins} />;
+}
+```
+
+Use the real name and peer version requirements for a third-party package. Replace default modules through extensions + replaceExtension; do not register the same tag twice. Hosts still configure fonts, math CSS, persistence, and application services.
+
+## Validate distribution
+
+After type checking, install the actual tgz into an independent consumer. Check public imports, SSR, CSS resources, preserved defaults, and new interactions. Packages supporting React 18/19 should verify both. Syntax plugins should compare finalized streams with one-shot parsing. Interactive plugins should cover desktop sidebars, narrow overlays, keyboard behavior, cancellation, and both themes.
+
+The repository also includes packable [reading-tools](../../examples/packages/reading-tools/index.js) and [paper-theme](../../examples/packages/paper-theme/index.css) examples. The [plugin development Skill](ai-skills.md) includes a portable template and references that do not require this repository.

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.