@linloir/limr 0.0.0-stage → 1.0.0

package/dist/translations-DHnYMg4h.d.ts

@@ -0,0 +1,318 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, CSSProperties } from 'react';
+import { l as SyntaxExtension, M as MarkdownNode, A as Annotation, b as AnnotationOccurrence, g as HighlightData, k as SourceRange, h as SelectionSnapshot, f as DocumentSnapshot, c as DocumentEngine } from './engine-43u8B4yt.js';
+
+interface NodeRendererProps {
+    node: MarkdownNode;
+    children: ReactNode;
+    pending: boolean;
+    source: string;
+    /** Render an existing subtree without parsing strings again. */
+    renderChildren: (nodes: readonly MarkdownNode[], options?: {
+        trailing?: ReactNode;
+    }) => ReactNode;
+    /** Render a literal node value with optional syntax tokens, preserving source
+     * selection, highlights and annotation insertion. Token offsets are UTF-16. */
+    renderValue: (tokens?: readonly TextToken[]) => ReactNode;
+    /** Render a text attribute with source selection, highlights and annotations. */
+    renderAttribute: (name: string) => ReactNode;
+}
+interface TextToken {
+    content: string;
+    offset: number;
+    style?: CSSProperties;
+}
+type NodeRenderer = ComponentType<NodeRendererProps>;
+type AnnotationPresentation = 'preview' | 'expanded' | 'sidebar';
+interface AnnotationExpansion {
+    /** Grow beside the marker, or center within the page's visual viewport. */
+    placement: 'anchor' | 'center';
+    /** CSS lengths or pixels. Unset height fits content; centered width defaults to 640px. */
+    width?: number | string;
+    height?: number | string;
+    maxHeight?: number | string;
+}
+interface AnnotationContentProps<T = unknown> {
+    annotation: Annotation<T>;
+    presentation: AnnotationPresentation;
+    expanded: boolean;
+    /** Shared editor state, preserved when switching between sidebar and overlay. */
+    editing: boolean;
+    data: T | undefined;
+    loading: boolean;
+    error: Error | null;
+    retry: () => void;
+}
+/** A compact sidebar summary from local annotation data; rendering it never
+ * invokes the annotation's loader. The first annotation owns a grouped preview. */
+interface AnnotationSidebarPreviewProps<T = unknown> {
+    annotation: Annotation<T>;
+    data: T | undefined;
+    occurrence: AnnotationOccurrence;
+    annotations: readonly Annotation[];
+    referenceText: string;
+}
+/** The registering module owns the entire inside of the floating surface.
+ * `children` renders the occurrence's Content components, sharing their cache
+ * and preserving their state between preview and expanded presentations. */
+interface AnnotationOverlayCardProps<T = unknown> {
+    annotation: Annotation<T>;
+    occurrence: AnnotationOccurrence;
+    presentation: 'preview' | 'expanded';
+    expanded: boolean;
+    pinned: boolean;
+    canExpand: boolean;
+    expand: () => void;
+    collapse: () => void;
+    close: () => void;
+    children: ReactNode;
+}
+interface AnnotationType<T = unknown> {
+    type: string;
+    /** Resolve labels from the reader locale without recreating the plugin. */
+    label: string | ((locale: LiMRLocale) => string);
+    icon?: ReactNode | ComponentType;
+    color?: string;
+    /** Highlight referenced text in the marker color while hovered or active. */
+    highlight?: 'hover' | false;
+    Content?: ComponentType<AnnotationContentProps<T>>;
+    Marker?: ComponentType<{
+        annotation: Annotation<T>;
+        active: boolean;
+    }>;
+    overlay?: {
+        /** Render the full card, including its title, body and controls. */
+        Card?: ComponentType<AnnotationOverlayCardProps<T>>;
+        /** CSS length or pixels, constrained to the visual viewport. */
+        previewWidth?: number | string;
+        /** Expansion is opt-in. A resolver may vary the layout per annotation. */
+        expand?: false | AnnotationExpansion | ((annotation: Annotation<T>) => false | AnnotationExpansion);
+    };
+    sidebar?: {
+        /** Collapsed summary below the title. Return null or use false to hide it. */
+        Preview?: ComponentType<AnnotationSidebarPreviewProps<T>> | false;
+        /** Maximum summary lines. Default: 2. */
+        previewLines?: number;
+        previewColor?: string;
+        /** Card accent; defaults to the marker color. CSS colors/variables are accepted. */
+        color?: string;
+        /** Resting decorative border; defaults to the card accent. */
+        borderColor?: string;
+        /** Title defaults to the accent; body and excerpt keep the reader text colors. */
+        titleColor?: string;
+        textColor?: string;
+        excerptColor?: string;
+        /** Toggle an expanded card by clicking its noninteractive content. Default: false. */
+        collapseOnContentClick?: boolean;
+    };
+    /** Only called when content is displayed; requests share a per-reader cache. */
+    load?: (annotation: Annotation<T>, context: {
+        signal: AbortSignal;
+    }) => Promise<T>;
+}
+interface RendererExtension extends SyntaxExtension {
+    /** Register document parameter defaults. Plugins extend RendererParameters
+     * through TypeScript declaration merging and read them with useRendererParameter. */
+    parameters?: Readonly<RendererParameters>;
+    components?: Readonly<Record<string, NodeRenderer>>;
+    annotationTypes?: readonly AnnotationType<any>[];
+    actions?: readonly SelectionAction[];
+}
+/** Open to module augmentation; parameter names and semantics belong to plugins. */
+interface RendererParameters {
+}
+interface DocumentCommands {
+    /** Content annotations get a shared highlight unless disabled or their type
+     * uses hover highlighting. An explicit appearance still creates a saved highlight. */
+    addAnnotation: (annotation: Annotation, options?: {
+        highlight?: HighlightData | false;
+        edit?: boolean;
+    }) => void;
+    updateAnnotation: (id: string, update: Partial<Annotation>) => void;
+    removeAnnotation: (id: string) => void;
+    /** Remove all annotations bound to these exact fragments, preserving other anchors. */
+    removeAnnotationsAt: (ranges: readonly SourceRange[]) => void;
+    editAnnotation: (id: string | null) => void;
+    /** Open the first occurrence of an annotation, or an explicit occurrence ID. */
+    activateAnnotation: (id: string | null) => void;
+}
+interface ActionContext extends DocumentCommands {
+    selection: SelectionSnapshot;
+    /** Annotations bound to the selected fragment, including its highlight. */
+    annotations: readonly Annotation[];
+    highlight: Annotation<HighlightData> | null;
+    document: DocumentSnapshot;
+    locale: LiMRLocale;
+    clearSelection: () => void;
+    /** Aborted when this reader is disposed, not when its menu closes. */
+    signal: AbortSignal;
+}
+interface ToolbarActionContext extends ActionContext {
+    busy: boolean;
+    expanded: boolean;
+    highlightAppearance: HighlightData;
+    setHighlightAppearance: (appearance: HighlightData) => void;
+    expand: () => void;
+    collapse: () => void;
+    /** Run a panel operation through the toolbar's busy/error handling. */
+    run: (operation: (context: ActionContext) => void | Promise<void>) => Promise<void>;
+}
+interface SelectionAction {
+    id: string;
+    label: string | ((context: ActionContext) => string);
+    /** Required, decorative, ideally a rounded SVG with a square viewBox. */
+    icon: NonNullable<ReactNode> | ((context: ActionContext) => ReactNode);
+    placement?: 'start' | 'end';
+    tone?: 'danger';
+    /** Optional transient success feedback after run() resolves. */
+    successLabel?: string | ((context: ActionContext) => string);
+    successIcon?: ReactNode;
+    visible?: (context: ActionContext) => boolean;
+    disabled?: (context: ActionContext) => boolean;
+    run?: (context: ToolbarActionContext) => void | Promise<void>;
+    onHover?: (context: ToolbarActionContext) => void;
+    /** Automatically opens on hover; also accessible by keyboard and touch. */
+    renderExpanded?: (context: ToolbarActionContext) => ReactNode;
+    render?: (context: ToolbarActionContext) => ReactNode;
+}
+interface LiMRLocale {
+    /** Optional language tag for plugin-owned translations. */
+    language?: string;
+    citation?: string;
+    contents: string;
+    annotations: string;
+    expand: string;
+    collapse: string;
+    close: string;
+    copy: string;
+    copied: string;
+    copyFailed: string;
+    copyImage: string;
+    copyFigures: string;
+    loading: string;
+    retry: string;
+    unavailable: string;
+    footnotes: string;
+    definition: string;
+    question: string;
+    note: string;
+    extra: string;
+    hint: string;
+    answer: string;
+    submit: string;
+    correct: string;
+    incorrect: string;
+    play: string;
+    highlight: string;
+    addHighlight: string;
+    editHighlight: string;
+    highlightColor: string;
+    highlightStyle: string;
+    highlightBackground: string;
+    highlightUnderline: string;
+    highlightDotted: string;
+    highlightWavy: string;
+    hideHighlight: string;
+    showHighlight: string;
+    deleteAnnotations: string;
+    deleteAnnotationsHint: string;
+}
+interface ViewConfiguration {
+    /** Document-wide overrides of parameters registered by extensions. */
+    parameters?: Readonly<RendererParameters>;
+    extensions?: readonly RendererExtension[];
+    /** Add installed plugins to the default extensions (or your extensions list). */
+    plugins?: readonly RendererExtension[];
+    /** CSS skin name, applied to every view including portalled controls. */
+    appearance?: string;
+    components?: Readonly<Record<string, NodeRenderer>>;
+    annotationTypes?: readonly AnnotationType<any>[];
+    annotations?: readonly Annotation[];
+    theme?: 'light' | 'dark' | 'auto';
+    /** Justify prose paragraphs and list items, leaving the last line start-aligned. */
+    justify?: boolean;
+    locale?: Partial<LiMRLocale>;
+    scrollRoot?: HTMLElement | null;
+    scrollOffset?: number;
+    onSelectionChange?: (selection: SelectionSnapshot | null) => void;
+    onAnnotationClick?: (occurrence: AnnotationOccurrence) => void;
+    onAnnotationHover?: (occurrence: AnnotationOccurrence | null) => void;
+    onDocumentChange?: (document: DocumentSnapshot) => void;
+    onAnnotationsChange?: (annotations: readonly Annotation[]) => void;
+    onHighlightHover?: (highlight: Annotation<HighlightData> | null) => void;
+    onHighlightClick?: (highlight: Annotation<HighlightData>) => void;
+}
+interface StyledProps {
+    className?: string;
+    style?: CSSProperties;
+}
+
+interface DocumentProviderProps extends ViewConfiguration {
+    source?: string;
+    streaming?: boolean;
+    documentId?: string;
+    children: ReactNode;
+}
+declare function DocumentProvider({ children, source, streaming, documentId, ...options }: DocumentProviderProps): react.JSX.Element;
+/** Only the requested value is subscribed; changing a parameter never reparses source. */
+declare function useRendererParameter<K extends keyof RendererParameters>(name: K): RendererParameters[K];
+declare function useDocument(): DocumentSnapshot;
+declare function useDocumentSelector<R>(select: (snapshot: DocumentSnapshot) => R): R;
+declare function useSelection(): SelectionSnapshot | null;
+declare function useLocale(): LiMRLocale;
+declare function useAnnotation(id: string): Annotation | undefined;
+declare function useAnnotations(): {
+    annotations: ReadonlyMap<string, Annotation<unknown>>;
+    occurrences: readonly AnnotationOccurrence[];
+};
+declare function useAnnotationState(): {
+    active: string | null;
+    hovered: string | null;
+    activate: (id: string | null) => void;
+    hover: (id: string | null) => void;
+};
+declare function useAnchor(id: string): {
+    element: HTMLElement | null;
+    rect: DOMRect | null;
+    contentRect: DOMRect | null;
+};
+declare function useLiMR(): {
+    document: DocumentEngine;
+    signal: AbortSignal;
+    clearSelection: () => void;
+    scrollToHeading: (id: string) => void;
+    scrollToAnnotation: (id: string) => void;
+    invalidateAnnotation: (id: string) => void;
+    addAnnotation: (annotation: Annotation, options?: {
+        highlight?: HighlightData | false;
+        edit?: boolean;
+    }) => void;
+    updateAnnotation: (id: string, update: Partial<Annotation>) => void;
+    removeAnnotation: (id: string) => void;
+    removeAnnotationsAt: (ranges: readonly SourceRange[]) => void;
+    editAnnotation: (id: string | null) => void;
+    activateAnnotation: (id: string | null) => void;
+};
+
+interface MarkdownProps extends Omit<DocumentProviderProps, 'children'>, StyledProps {
+    interactive?: boolean;
+    /** Follow generated output while the reader remains near the bottom. */
+    followOutput?: boolean;
+}
+declare function Markdown({ className, style, interactive, followOutput, justify, ...props }: MarkdownProps): react.JSX.Element;
+
+type TranslationMode = 'origin' | 'translation' | 'both';
+interface TranslationsOptions {
+    defaultMode?: TranslationMode;
+}
+declare module '@linloir/limr' {
+    interface RendererParameters {
+        /** Overrides every translations block. Undefined restores each block's local mode. */
+        translationMode?: TranslationMode;
+        /** With a global mode, markers request an update through this callback. */
+        onTranslationModeChange?: (mode: TranslationMode) => void;
+    }
+}
+declare function translations(options?: TranslationsOptions): RendererExtension;
+
+export { type ActionContext as A, type DocumentCommands as D, type LiMRLocale as L, Markdown as M, type NodeRenderer as N, type RendererExtension as R, type SelectionAction as S, type TextToken as T, type ViewConfiguration as V, type AnnotationContentProps as a, type AnnotationExpansion as b, type AnnotationOverlayCardProps as c, type AnnotationPresentation as d, type AnnotationSidebarPreviewProps as e, type AnnotationType as f, DocumentProvider as g, type DocumentProviderProps as h, type MarkdownProps as i, type NodeRendererProps as j, type RendererParameters as k, type StyledProps as l, type ToolbarActionContext as m, type TranslationMode as n, type TranslationsOptions as o, useAnnotation as p, useAnnotationState as q, useAnnotations as r, useDocument as s, translations as t, useAnchor as u, useDocumentSelector as v, useLiMR as w, useLocale as x, useRendererParameter as y, useSelection as z };

package/docs/README.md

@@ -0,0 +1,13 @@
+# LiMR 文档 / Documentation
+
+[简体中文](zh-CN/README.md) · [English](en/README.md)
+
+文档按阅读、接入与扩展开发场景组织；两种语言使用相同的文件结构，每页顶部可以切换语言。
+
+Documentation is organized around writing content, integrating LiMR, and developing extensions. Both languages use the same file structure, with a language switch on each page.
+
+- [中文入门](zh-CN/getting-started.md) / [Getting started](en/getting-started.md)
+- [默认语法](zh-CN/syntax.md) / [Default syntax](en/syntax.md)
+- [AI Skills 下载与导入](zh-CN/ai-skills.md) / [Download and install AI Skills](en/ai-skills.md)
+
+[项目首页](../README.md) · [Project overview](../README.en.md)

package/docs/api.md

@@ -0,0 +1,8 @@
+# API 参考 / API reference
+
+文档已整理到语言目录。This guide now lives in the language directories.
+
+- [简体中文](zh-CN/api.md)
+- [English](en/api.md)
+
+[文档目录 / Documentation](README.md)

package/docs/assets/rendered.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="240" viewBox="0 0 480 240" role="img" aria-label="Rendered document">
+  <rect width="480" height="240" rx="12" fill="#eef2ec"/>
+  <g fill="#364633" font-family="Georgia,serif">
+    <text x="32" y="60" font-size="32" font-weight="bold">Markdown</text>
+    <text x="32" y="108" font-size="24" font-weight="bold">Readable source</text>
+    <text x="32" y="156" font-size="24">• Write</text>
+    <text x="32" y="196" font-size="24">• Read</text>
+  </g>
+</svg>

package/docs/assets/source.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="240" viewBox="0 0 480 240" role="img" aria-label="Markdown source">
+  <rect width="480" height="240" rx="12" fill="#f3f1ee"/>
+  <g fill="#5a5650" font-family="monospace" font-size="24">
+    <text x="32" y="60"># Markdown</text>
+    <text x="32" y="108">**Readable source**</text>
+    <text x="32" y="156">- Write</text>
+    <text x="32" y="196">- Read</text>
+  </g>
+</svg>

package/docs/en/README.md

@@ -0,0 +1,26 @@
+# English documentation
+
+> 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/README) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/README.md)
+
+These pages describe the current public LiMR 1.0.0 implementation. Chinese is the default documentation language; every English page has a matching Chinese page.
+
+| What you want to do | Read |
+| --- | --- |
+| Install and render a first document | [Getting started](getting-started.md) |
+| Understand modules, included capabilities, and configuration | [Built-in modules](modules.md) |
+| Write Markdown, exercises, citations, figures, and translations | [Default syntax](syntax.md) |
+| Integrate React, streaming, custom layouts, or SSR | [Application integration](integration.md) |
+| Persist selections, highlights, citations, and custom annotations | [Annotations and selection](annotations.md) |
+| Add syntax, cards, selection actions, and parameters | [Extension development](extensions.md) |
+| Build a standalone npm plugin and import it into an app | [Plugin packages](plugin-packages.md) |
+| Customize themes, fonts, layouts, and portals | [Styles and fonts](styles.md) |
+| Look up component props, hooks, and core APIs | [API reference](api.md) |
+| Understand parsing, state, and resource boundaries | [Architecture and behavior](architecture.md) |
+| Understand measurements and validation boundaries | [Performance and limits](performance.md) |
+| Have an AI use LiMR or develop plugins | [AI Skills](ai-skills.md) |
+
+Start with `Reader`, split components when a custom layout is needed, and add plugins for application features. Local persistence, import/export, and simulated assistant responses in the Playground belong to the demo application, not to Reader itself.
+
+[Back to README](../../README.en.md) · [Live Playground](https://linloir.github.io/LiMR/)

package/docs/en/ai-skills.md

@@ -0,0 +1,57 @@
+# AI Skills: download, install, and use
+
+> 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/ai-skills) for the best reading experience.
+
+[Documentation](README.md) · [简体中文](../zh-CN/ai-skills.md)
+
+Skills are instruction bundles for AI agents, not RendererExtension modules or model services. Installing a Skill does not automatically change a project, install plugins, or connect an AI API.
+
+| Skill | Tasks |
+| --- | --- |
+| [limr-use](../../skills/limr-use/SKILL.md) | Integrate LiMR, choose components, author syntax, configure annotations/streaming/themes, import existing plugins |
+| [limr-plugin-development](../../skills/limr-plugin-development/SKILL.md) | Build new plugin packages with cards/syntax/actions/parameters and validate consumers |
+
+Instructions are in English and accept tasks written in Chinese. Human-facing documentation is bilingual. The development Skill includes a standalone starter; both include local references, so the entire repository is not required in the agent's context.
+
+## Import from the npm package
+
+Install a LiMR version containing Skills, then run in **your application project**:
+
+```sh
+npm install @linloir/limr
+mkdir -p .agents/skills
+cp -R node_modules/@linloir/limr/skills/limr-use .agents/skills/
+cp -R node_modules/@linloir/limr/skills/limr-plugin-development .agents/skills/
+```
+
+These commands illustrate a fresh installation. Review local customizations before replacing an existing directory, and update the whole folder to avoid stale templates. Copies are snapshots; npm upgrades do not update them automatically. Review compatibility when upgrading LiMR.
+
+## Import from the repository or ZIP
+
+Copy from the repository's skills directory, or generate ZIPs locally (requires Python 3):
+
+```sh
+pnpm pack:skills
+```
+
+Archives are written to artifacts/skills and mirrored to Playground public/downloads for Docs downloads. Each ZIP contains a complete top-level skill directory, not just SKILL.md. A versioned combined archive is also produced. Building the Docs site generates download assets automatically.
+
+After the corresponding site version is deployed, download [limr-use.zip](https://linloir.github.io/LiMR/downloads/limr-use.zip) or [limr-plugin-development.zip](https://linloir.github.io/LiMR/downloads/limr-plugin-development.zip). The local AI Skills page also has download buttons. ZIPs are transport archives, not a promise that every AI client supports one-click import; extract and copy the full folders where needed.
+
+## Codex locations and invocation
+
+Codex supports project skills in .agents/skills and user skills in ~/.agents/skills. Choose one scope to avoid duplicate names. Older clients may use a different supported directory. Changes are normally discovered automatically; restart if missing. Invoke through /skills or $skill-name. Source: [official OpenAI Skills documentation](https://developers.openai.com/codex/skills/).
+
+```text
+$limr-use Integrate LiMR into this React application with English labels, streaming answers, and controlled annotations.
+```
+
+```text
+$limr-plugin-development Create a glossary plugin package with a term block, selection action, expandable card, and sidebar preview, then import it into this application.
+```
+
+For other SKILL.md-compatible agents, use their supported project/user locations. Without automatic discovery, ask the AI to read SKILL.md and follow its reference/asset links. Do not assume one client's commands work everywhere.
+
+## Expected deliverables
+
+The use Skill should deliver working integration, stable configuration, and validation. The development Skill should deliver module source, exports/types/CSS, a host example, and real package-consumer verification. Both prioritize the installed API, avoid invented syntax and loss of persisted unknown annotations, and do not publish packages or modify external services unless instructed.

package/docs/en/annotations.md

@@ -0,0 +1,84 @@
+# 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 |
+| 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.
+
+## 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,107 @@
+# 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 |
+| 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, sparkles, highlight |
+
+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.