@linloir/limr 0.1.0 → 1.0.1

package/docs/en/annotations.md

@@ -0,0 +1,86 @@
+# Annotations and selection
+
+> 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/annotations) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/annotations.md)
+
+## Data model
+
+Annotation stores data, AnnotationType registers presentation/loading, and AnnotationOccurrence describes one location. One annotation can have multiple anchors; one citation marker can refer to several annotations.
+
+```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' },
+}];
+```
+
+The example requires source to begin with LiMR and documentId to be article. range is shorthand for one anchor; anchors takes precedence. All ranges address the **unmodified input**, using UTF-16 offsets with an exclusive end, not UTF-8 bytes or Unicode code points.
+
+Persist source, a stable documentId, annotation ID/type/data/anchors, and your application document version when needed. anchor.revision belongs to the current engine session, not a cross-session identity. If quote no longer matches the range, relocation succeeds only for one unique match in the source. Missing/ambiguous matches or a mismatched documentId skip that anchor. Without quote, a mismatched revision also skips it. This is not automatic position transformation for collaborative editing.
+
+## Three selection forms
+
+| Field | Meaning |
+| --- | --- |
+| text | Readable selected text; settled atomic content uses its complete original source |
+| raw | Mapped original ranges and source |
+| syntax | Absorbs adjacent standard Markdown delimiters at each edge, without selecting extra words or outer custom tags |
+| blocks | Ranges and source for touched blocks |
+| quality | exact, atomic, or unmapped |
+| settled | False while a pointer selection is changing |
+| documentId / revision | Owning document snapshot |
+
+Each result has ranges and sourceText. Notes usually use syntax.ranges. Store document.source.slice(start, end) as quote for **every range**. Code supports partial selection; math and images are atomic. Do not infer offsets from DOM textContent lengths: entities, escapes, and emoji make those coordinates differ.
+
+The default selection toolbar and browser copy serialize atomic content as a whole, retaining its original delimiters (`$…$`, `$$…$$`, image syntax, Mermaid fences/directives, or plugin block tags). Surrounding ordinary text keeps its rendered spelling and explicit line breaks. This also applies when reopening an existing highlight. A plugin's `selection: 'atomic'` covers its mapped attributes, children, and nested atoms; block-local copy buttons may offer their own specialized format.
+
+## Highlights and commands
+
+highlight needs no extra AnnotationType. Its data supports color, style (background / underline / dotted / wavy), and hidden. Deleting content annotations differs from hiding their highlight.
+
+| Command | Behavior |
+| --- | --- |
+| addAnnotation(annotation, options?) | Adds/replaces an ID; ordinary content annotations also get a shared persistent highlight by default |
+| updateAnnotation(id, partial) | Shallowly merges fields; data is replaced as a whole, so retain needed fields |
+| removeAnnotation(id) | Removes that annotation, preserving other annotations and shared highlights |
+| removeAnnotationsAt(ranges) | Removes annotations/highlights at exact matching fragments, retaining other anchors |
+| editAnnotation(id / null) | Changes shared editing state; setting an ID also activates its card |
+| activateAnnotation(id / null) | Opens the annotation's first occurrence, or accepts an explicit occurrence ID |
+
+addAnnotation accepts highlight: false to suppress automatic persistent highlighting, explicit HighlightData to choose its style, and edit: true to enter editing. Types configured with highlight: 'hover' do not add persistent highlights by default, but an explicit appearance still creates one. Default toolbar actions are palette, add/hide highlight, copy, and delete. actions replaces built-in actions; plugin actions are still merged in.
+
+## Citation hover highlights
+
+Citations default to highlight: 'hover'. Hovering a marker or sidebar item, or activating a reference, paints the referenced text with an 18% tint of the type's color behind the text. Clicking pins the highlight after the pointer leaves; it disappears once the reference is neither active nor hovered. Active and hovered references to the same paragraph do not stack their tints. This feedback never updates annotations or saved hidden settings. Embedded refs use their nearest paragraph, heading, list item, or table cell. External references use their own range; the first line anchors sidebar alignment.
+
+Sidebar alignment translates the prose without changing the page's scroll range. Paint updates throughout that animation and on completion or cancellation, so text entering from outside the viewport receives the current hover or active feedback.
+
+Disable it with replaceExtension(standard(), citation({ highlight: false })). Other types can opt into highlight: 'hover'.
+
+## Missing plugins
+
+The current implementation **does not silently ignore unknown annotation types**. It retains data/ranges and may show a generic dot marker. Without Content, the card shows the localized unavailable label and type name. A missing citation definition may also show unavailable content. Install the matching plugin, or let the application decide which annotations to hide temporarily.
+
+If filtering unsupported types, retain the full persisted array and merge hidden data back when accepting edits, so disabling a plugin cannot discard data. Playground plugin checkboxes currently toggle action entries while retaining card renderers; they do not simulate uninstalling a plugin.
+
+## Cards and async resources
+
+Modules register Content for annotation content, overlay.Card for the whole floating card interior, and sidebar.Preview for a local collapsed summary. AnnotationMarkdown reuses Markdown configuration with an isolated selection scope.
+
+load(annotation, { signal }) runs when content is displayed, sharing requests and a bounded cache within one reader. Separate readers are isolated. Preview never invokes load. Content receives data, loading, error, retry, editing, presentation, and expanded; the module renders loading/error UI. Refresh with useLiMR().invalidateAnnotation(id).
+
+Action signals abort when the reader is disposed, not when the menu closes. Preserve question fields when replacing data with streamed answers. Stopping generation, retries, authentication, conversation state, and storage belong to the application adapter. See the [assistant example](../../examples/assistant.tsx) and [extension development](extensions.md).

package/docs/en/api.md

@@ -0,0 +1,115 @@
+# API reference
+
+> 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/api) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/api.md)
+
+## Entry points
+
+| Entry | Contents |
+| --- | --- |
+| @linloir/limr | All public core, React, and extension APIs |
+| @linloir/limr/core | DOM/React-free engine, selection calculations, tree helpers, caches, data types |
+| @linloir/limr/react | Components, hooks, locales, React types |
+| @linloir/limr/extensions | Module factories, definitions, selection actions, AnnotationMarkdown |
+| styles.css / styles/base.css / fonts.css / math.css | Public styles, prefixed by the package name |
+| @linloir/limr/package.json | Package metadata |
+
+This is an API guide. Exact TypeScript declarations ship with the package; plugins should use the installed version's declarations.
+
+## Shared document configuration
+
+Reader, Markdown, and DocumentProvider accept:
+
+| Prop | Default / meaning |
+| --- | --- |
+| source | Empty string; original Markdown |
+| streaming | false |
+| documentId | Generated; explicit values should be stable and unique on the page |
+| extensions | standard(); the complete extension list |
+| plugins | Appended to the default or explicit list |
+| parameters | Document-wide module parameter overrides |
+| components | NodeRenderer overrides by AST type/custom tag |
+| annotationTypes | Add/override presentation by type |
+| annotations | Internal state if omitted; controlled if supplied |
+| onAnnotationsChange | Next external annotation array, including highlights; required to accept controlled edits |
+| theme | light, dark, or auto |
+| appearance | classic; CSS scope propagated to portals |
+| locale | english; accepts chinese or Partial<LiMRLocale> |
+| justify | false; justify prose/list text |
+| typography | standard (default), knuth-plass, or justify; legacy CSS modes pretty / normal remain available |
+| knuthPlass | TeX paragraph parameters; see [styles](styles.md) |
+| rendererOverrides | Ordered, reader-scoped rules with type, component and optional when predicate |
+| streamEffect | Increment animation override; false disables |
+| scrollRoot | null/omitted means window |
+| scrollOffset | 24px |
+| onDocumentChange | DocumentSnapshot after updates |
+| onSelectionChange | SelectionSnapshot or null |
+| onAnnotationClick | Activated AnnotationOccurrence |
+| onAnnotationHover | Occurrence or null |
+| onHighlightClick / onHighlightHover | Highlight Annotation; hover exit is null |
+
+The default locale is english. Missing partial keys fall back to English. locale affects built-in controls that use LiMRLocale, not document text or third-party copy. Some auxiliary labels (for example Copy LaTeX and translation switch hints) are currently fixed by their modules. The Playground reader-language control demonstrates Chinese/English switching and saves that preference separately in browser storage.
+
+## Components
+
+| Component | Extra props and defaults |
+| --- | --- |
+| Reader | toc=true, sidebar=true, fillHeight=true, sidebarBreakpoint=1120, actions, followOutput=false, className/style |
+| Markdown | interactive=true, followOutput=false, className/style |
+| DocumentProvider | children; supplies context to composed views |
+| TableOfContents | title, maxDepth=6, followActive=true, topInset=24, updateHash=false, className/style |
+| AnnotationSidebar | sync='document' / 'none', gap=14, positioner=alignSidebar, renderCard, className/style |
+| AnnotationOverlay | disabled=false, portalRoot, previewWidth=340, maxHeight='80dvh' |
+| SelectionToolbar | actions, portalRoot, maxPanelHeight=260, render, className/style |
+| AnnotationCard | AnnotationOverlayCardProps plus required title and optional bodyLabel |
+| AnnotationContent | annotationId, presentation, expanded=true, enabled=true |
+| AnnotationGroup | occurrence, presentation, expanded=true, enabled=true |
+| AnnotationMarkdown | MarkdownProps with required source; interactive=false by default |
+| InlineMarker | Required label, color, children, button props/ref |
+| ToolIcon | name and SVG props; e.g. note, copy, highlight, comment, zoom-in, zoom-out, source, image |
+
+Shared views/hooks require a provider, except standalone Markdown and Reader. AnnotationCard is an interior template, not its own portal. sidebar.renderCard receives occurrence/active/activate; toolbar.render receives context/actions/run.
+
+`SidebarPositioner` receives `{ id, anchorTop, height }[]` and `{ activeId, gap, height?, prioritizeActive? }`, returning a map of IDs to top positions. anchorTop is the first line of referenced text; prioritizeActive distinguishes hovered or active items from the item selected by reading position. The default alignSidebar packs footer cards at rest and prioritizes the current item during interaction.
+
+## Hooks
+
+| Hook | Result |
+| --- | --- |
+| useDocument() | Complete snapshot |
+| useDocumentSelector(select) | Selected value; unchanged references avoid rerenders |
+| useLocale() | Merged locale; built-in language is en / zh-CN for plugin dictionaries |
+| useSelection() | Selection or null |
+| useAnnotation(id) | Annotation or undefined |
+| useAnnotations() | Annotations Map and occurrences, combining embedded and external data |
+| useAnnotationState() | Active/hovered occurrence IDs plus activate/hover |
+| useAnchor(occurrenceId) | Element, viewport rect, contentRect; null until mounted |
+| useRendererParameter(name) | Host override or last registered default |
+| useLiMR() | Engine, commands, signal, clearSelection, scrollToHeading, scrollToAnnotation, invalidateAnnotation |
+
+useRuntime and useTheme are not public APIs. useLocale, locale.language, and localized annotation labels are available from 1.0.0. See [annotations](annotations.md) for commands and [extensions](extensions.md) for renderer/action contracts.
+
+## Core engine
+
+```ts
+import { createDocument, selectionFromRange } from '@linloir/limr/core';
+
+const engine = createDocument('# Hello\n\nText', { id: 'core-doc', streaming: true });
+engine.append('\n\nMore text.');
+const document = engine.finish();
+const selection = selectionFromRange(document, { start: 9, end: 13 });
+console.log(document.headings, selection.syntax.sourceText);
+```
+
+createDocument(source?, { id?, extensions?, streaming? }) returns DocumentEngine. Read with getSnapshot(); subscribe(listener) returns an unsubscribe function. update(source, { streaming? }) replaces the complete input, append(chunk) appends in streaming mode, finish() finalizes, and setExtensions(list) changes parsing configuration.
+
+Core defaults to extensions=[]. Use SyntaxExtension with micromark/mdast for a strictly React-free parser; importing standard from the React extension entry introduces React dependencies.
+
+DocumentSnapshot contains id, revision, source, streaming, blocks, headings, definitions, footnotes, footnoteOrder, annotations, occurrences, diagnostics, and metrics. Its annotations are **parsed from source**. Use useAnnotations for merged external data.
+
+Other core exports include walk, textContent, rangeOf, intersects, safeUrl, mapText, selectionFromRange, replaceExtension, resolveAnnotationAnchors, annotationReferenceRange, sameRange, defaultHighlight, LruCache, and ResourceCache. ResourceCache.acquire returns promise/release; invalidate clears a key or everything.
+
+`inlineHighlights({ color?, component? })` and `footnotes(annotationTypeOptions?)` are included in `standard()`. `HighlightData.readOnly` limits the default highlight toolbar to copying and a hint; `AnnotationOccurrence.referenceRange` separates a marker's source location from the text it references.
+
+Core also exports `knuthPlass(items, lengths, options?)`, `prepareKnuthPlass(items)`, `texBadness`, and their types. The prepared function reuses prefix sums when solving the same paragraph at multiple widths.

package/docs/en/architecture.md

@@ -0,0 +1,41 @@
+# Architecture and behavior
+
+> 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/architecture) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/architecture.md)
+
+## Three public layers
+
+1. core owns original source, AST, blocks, headings, embedded references, diagnostics, and selection coordinates, without a React/DOM runtime dependency.
+2. React connects document, interaction, layout, external annotations, and resource state to views.
+3. extensions implements defaults through the same public contract available to applications; modules can be appended, replaced, or removed.
+
+Docs navigation and Playground persistence/loading/language menus belong to the demo application, not the LiMR core.
+
+## Append parsing
+
+Streaming reparses from the unstable final top-level block, reusing stable prefixes, line indexes, and node semantic indexes. Growing code fences can use a literal fast path. Finalization can also reparse only the tail rather than always parsing the whole document. Late Markdown reference/footnote definitions, middle edits, document-scoped transforms, or extension changes can still require a full parse. Long paragraphs, lists, and complex unclosed tags retain tail-parsing costs.
+
+`incomplete` identifies an unclosed node; `pending` describes its growing top-level block. Modules can render progressively or provide `streaming.Loading`. Incomplete headers and inline syntax markers are deferred. Increment animations affect new content; temporary wrappers merge after animation completion once native selection leaves them. Streaming code retains existing text nodes, and final highlighting waits while its text is selected.
+
+Public source always retains the original input. Internally, the parser inserts markers for two-colon components and incomplete syntax, then maps positions back through sparse offsets. These internal markers never enter copied text, annotations, or persisted data. Custom transforms must preserve original UTF-16 positions and honor locality. Embedded references and application annotations enter separately and merge in the React layer.
+
+## Typography and source mapping
+
+Standard mode uses browser layout by default. KP loads on the client: preparation caches glyph measurements, hyphenation, legal breakpoints, and prefix sums; solving runs TeX paragraph dynamic programming. Stable paragraphs near the viewport take priority and retain their DOM offscreen. Width changes reuse preparation and text containers. Selected paragraphs keep their native Range and defer layout until selection clears. Original source offsets and annotations remain unchanged; see [styles](styles.md) and [performance](performance.md).
+
+Atomic selection text serializes complete original source; surrounding ordinary text retains its rendered spelling and explicit line breaks. Mapped attributes, children, and nested atoms follow the enclosing plugin block’s atomic selection contract.
+
+## State and resources
+
+Update configuration immutably and keep static references stable. Scrolling and parameter updates do not require parsing. A provider manages one primary body; document state and annotation requests are isolated between providers.
+
+Annotation loading uses bounded per-reader caching; releasing consumers can cancel unused requests. Pure Shiki token results use a bounded module-level cache, separate from user annotation data. Mermaid uses bounded result caching and serializes global initialization with rendering so readers using different themes cannot interfere. The library supplies no model service, authentication, database, or automatic persistence.
+
+## Fallback behavior
+
+Unknown HTML/custom tags remain inert source text. In the default configuration, unknown directives render their children. Unknown annotation types retain data and show generic markers/unavailable content rather than silently disappearing. Syntax recovery, transform diagnostics, and client renderer boundaries have distinct scopes; see [extensions](extensions.md).
+
+## Validation boundaries
+
+The repository includes parser/offset/SSR unit tests, real Chromium interaction regressions, and separate React 18/19 npm-consumer checks. Intercepted media, mobile viewport simulation, and performance fixtures are not proof of remote playback, physical-device acceptance, or universal performance.

package/docs/en/extensions.md

@@ -0,0 +1,208 @@
+# 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 existing nodes or a matching subset | components / rendererOverrides |
+| 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>`, paired `::notice{title="Tip"}` / `::`, and `:::` containers. 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 |
+| incomplete | Whether this particular syntax node is unclosed |
+| 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, literal, 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. Plugins must 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. Registered incomplete tags and containers carry node.incomplete and are retried on append; unfinished headers stay hidden or use the module loading view. Invalid JSX can still fall back with diagnostics. 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.
+
+## Streaming presentation
+
+`pending` describes a growing top-level block; `incomplete` describes this particular unclosed syntax node. Every registered tag also accepts component directive syntax. `defineBlock` accepts `streaming.Loading`; omit it to render progressively, using `incomplete` in your component. Component identity is retained while children grow. Default definition, question, extras, video, figure and callout directives use a small themed ring; Mermaid waits for closure before asynchronously drawing. Code, math, GFM and translations show usable partial content. Blockquote-style callouts can grow progressively once their header is complete. Unclosed citation definitions do not register incomplete data.
+
+```tsx
+import { defineBlock, defineExtension } from '@linloir/limr';
+
+export const chart = defineBlock({
+  name: 'chart',
+  component: ({ children }) => <section>{children}</section>,
+  streaming: { Loading: () => <span role="status">Preparing chart…</span> },
+});
+export const streamMotion = defineExtension({
+  name: 'example:stream-motion',
+  streaming: {
+    effect: {
+      className: 'my-stream-increment',
+      keyframes: [{ opacity: 0.25 }, { opacity: 1 }],
+      timing: { duration: 320, easing: 'ease-out' },
+    },
+  },
+});
+```
+
+The last extension providing `streaming.effect` wins. The reader's `streamEffect` overrides it; `false` disables the effect. Keyframes and timing use the Web Animations API. Reduced-motion preferences suppress new animations. Default text/block entrances change opacity without adding a background tint. Text wrappers are compacted after completion, once the native selection leaves them. Use `children`, `renderChildren` and `renderValue` to retain this behavior; a plugin that replaces its own DOM owns its selection and animation behavior.
+
+`SyntaxExtension.literal` protects directive bodies from Markdown/JSX interpretation. Literal modules read their original `source` or transform the resulting component. It does not execute attribute expressions, YAML or JavaScript.
+
+## Conditional component replacement
+
+A module's `rendererOverrides` can restrict replacement by node type, language, ancestors or streaming state. Rules apply only inside that Reader. The last matching rule wins; Reader rules take precedence over extension rules and component mappings. Unmatched nodes retain their existing renderer.
+
+```tsx
+import { defineExtension, type NodeRenderer } from '@linloir/limr';
+
+const JavaScriptCode: NodeRenderer = ({ renderValue }) => <pre>{renderValue()}</pre>;
+export const customCode = defineExtension({
+  name: 'example:javascript-code',
+  rendererOverrides: [{
+    type: 'code',
+    when: (node, context) => node.lang === 'js' && !context.incomplete,
+    component: JavaScriptCode,
+  }],
+});
+```
+
+`when` also receives `pending` and `ancestors`. An explicit replacement owns its intermediate rendering while retaining LiMR's source wrapper, atomic selection and error boundary. Use `renderValue`, `renderAttribute` and `renderChildren` to preserve mappings. These restrictions scope rendering rules; they are not a JavaScript security sandbox.

package/docs/en/getting-started.md

@@ -0,0 +1,69 @@
+# 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.
+
+Typography defaults to `standard`; `knuth-plass` and `justify` are also available, as shown in [integration](integration.md). Defaults include Mermaid, nested callouts, `==highlights==`, and footnote cards; do not append duplicate modules. See [built-in modules](modules.md).
+
+## 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.