@linloir/limr 0.1.0 → 1.0.1

package/examples/notes.tsx

@@ -1,16 +1,18 @@
 import { useEffect, useLayoutEffect, useRef } from 'react';
-import { AnnotationMarkdown, ToolIcon, defineExtension, useLiMR, type AnnotationContentProps, type RendererExtension } from '@linloir/limr';
+import { AnnotationMarkdown, ToolIcon, defineExtension, useLiMR, useLocale, type AnnotationContentProps, type RendererExtension } from '@linloir/limr';
 
 interface NoteData { text: string; draft?: string }
 const kinds = [
-  { type: 'margin-note', label: '旁注', icon: 'comment', color: '#81B29A', hint: '在段落旁留下一个想法' },
-  { type: 'reading-note', label: '笔记', icon: 'note', color: '#6B9BD2', hint: '整理这一段的阅读笔记' },
-  { type: 'reader-question', label: '提问', icon: 'question', color: '#E5A06E', hint: '写下还想进一步理解的问题' },
-  { type: 'reader-footnote', label: '脚注', icon: 'footnote', color: '#B39DDB', hint: '补充解释或参考来源' },
+  { type: 'margin-note', label: '旁注', icon: 'comment', color: '#81B29A', hint: '在段落旁留下一个想法', labelEn: 'Margin note', hintEn: 'Leave a thought beside this passage' },
+  { type: 'reading-note', label: '笔记', icon: 'note', color: '#6B9BD2', hint: '整理这一段的阅读笔记', labelEn: 'Note', hintEn: 'Write a reading note' },
+  { type: 'reader-question', label: '提问', icon: 'question', color: '#E5A06E', hint: '写下还想进一步理解的问题', labelEn: 'Question', hintEn: 'What would you like to understand?' },
+  { type: 'reader-footnote', label: '脚注', icon: 'footnote', color: '#B39DDB', hint: '补充解释或参考来源', labelEn: 'Footnote', hintEn: 'Add an explanation or a source' },
 ] as const;
 
 function NoteContent({ annotation, data, editing, presentation }: AnnotationContentProps<NoteData>) {
   const commands = useLiMR();
+  const locale = useLocale();
+  const zh = locale.language?.startsWith('zh') ?? false;
   const text = data?.draft ?? data?.text ?? '';
   const isEditing = editing || data?.draft !== undefined;
   const input = useRef<HTMLTextAreaElement>(null);
@@ -45,25 +47,30 @@ function NoteContent({ annotation, data, editing, presentation }: AnnotationCont
   };
   return <div className="demo-note-content" data-limr-card-interactive="true">
     {isEditing ? <form onSubmit={event => { event.preventDefault(); save(); }}>
-      <textarea className="demo-note-editor" ref={input} aria-label={`${kind.label}内容`} rows={1} value={text} onChange={event => commands.updateAnnotation(annotation.id, { data: { text: data?.text ?? '', draft: event.target.value } })} placeholder={kind.hint} onKeyDown={event => {
+      <textarea className="demo-note-editor" ref={input} aria-label={zh ? `${kind.label}内容` : `${kind.labelEn} content`} rows={1} value={text} onChange={event => commands.updateAnnotation(annotation.id, { data: { text: data?.text ?? '', draft: event.target.value } })} placeholder={zh ? kind.hint : kind.hintEn} onKeyDown={event => {
         if (event.nativeEvent.isComposing) return;
         if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); cancel(); }
         else if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) { event.preventDefault(); save(); }
       }} />
-      <div className="demo-note-actions"><button type="button" onClick={cancel}><ToolIcon name="close" /><span className="limr-underline">取消</span></button><button type="submit" className="demo-note-submit" disabled={!text.trim()}><ToolIcon name="check" /><span className="limr-underline">提交</span></button></div>
-    </form> : <><AnnotationMarkdown source={data?.text || '还没有内容。'} /><div className="demo-note-actions"><button type="button" onClick={() => { commands.updateAnnotation(annotation.id, { data: { text: data?.text ?? '', draft: data?.text ?? '' } }); commands.editAnnotation(annotation.id); }}><ToolIcon name="edit" /><span className="limr-underline">修改</span></button><button type="button" className="demo-note-delete" onClick={() => commands.removeAnnotation(annotation.id)}><ToolIcon name="trash" /><span className="limr-underline">删除</span></button></div></>}
+      <div className="demo-note-actions"><button type="button" onClick={cancel}><ToolIcon name="close" /><span className="limr-underline">{zh ? '取消' : 'Cancel'}</span></button><button type="submit" className="demo-note-submit" disabled={!text.trim()}><ToolIcon name="check" /><span className="limr-underline">{locale.submit}</span></button></div>
+    </form> : <><AnnotationMarkdown source={data?.text || (zh ? '还没有内容。' : 'No content yet.')} /><div className="demo-note-actions"><button type="button" onClick={() => { commands.updateAnnotation(annotation.id, { data: { text: data?.text ?? '', draft: data?.text ?? '' } }); commands.editAnnotation(annotation.id); }}><ToolIcon name="edit" /><span className="limr-underline">{zh ? '修改' : 'Edit'}</span></button><button type="button" className="demo-note-delete" onClick={() => commands.removeAnnotation(annotation.id)}><ToolIcon name="trash" /><span className="limr-underline">{locale.deleteAnnotations}</span></button></div></>}
   </div>;
 }
 
+function NotePreview({ data }: { data?: NoteData }) {
+  const locale = useLocale();
+  return <span>{data?.text || (locale.language?.startsWith('zh') ? '正在编辑…' : 'Editing…')}</span>;
+}
+
 /** Modules bind every footnote/note/question through the same annotation API. */
 export function readingNotes(): RendererExtension {
   return defineExtension({
     name: 'reading-notes',
-    annotationTypes: kinds.map(kind => ({ type: kind.type, label: kind.label, color: kind.color, icon: <ToolIcon name={kind.icon} />, Content: NoteContent,
-      sidebar: { Preview: ({ data }: { data?: NoteData }) => <span>{data?.text || '正在编辑…'}</span> },
+    annotationTypes: kinds.map(kind => ({ type: kind.type, label: locale => locale.language?.startsWith('zh') ? kind.label : kind.labelEn, color: kind.color, icon: <ToolIcon name={kind.icon} />, Content: NoteContent,
+      sidebar: { Preview: NotePreview },
       overlay: { previewWidth: 300, expand: { placement: 'center' as const, width: 400, maxHeight: '75dvh' } },
     })),
-    actions: kinds.map(kind => ({ id: `reading-notes:${kind.type}`, label: kind.label, icon: <ToolIcon name={kind.icon} />, run: context => {
+    actions: kinds.map(kind => ({ id: `reading-notes:${kind.type}`, label: context => context.locale.language?.startsWith('zh') ? kind.label : kind.labelEn, icon: <ToolIcon name={kind.icon} />, run: context => {
       context.addAnnotation({ id: `note-${crypto.randomUUID()}`, type: kind.type, data: { text: '', draft: '' } satisfies NoteData,
         anchors: context.selection.syntax.ranges.map(range => ({ range, documentId: context.document.id, quote: context.document.source.slice(range.start, range.end) })),
       }, { edit: true });

package/examples/packages/paper-theme/index.css

@@ -0,0 +1,25 @@
+/* Unlayered application/theme CSS overrides the built-in @layer limr. */
+[data-limr-appearance='paper'] {
+  --limr-accent: #185145;
+  --limr-link: #185145;
+  --limr-selection: #548b7440;
+  --limr-background: #fcfaf4;
+  --limr-heading: #283b34;
+}
+[data-limr-appearance='paper'][data-limr-theme='dark'] {
+  --limr-background: #1e2421;
+  --limr-heading: #d8e4db;
+  --limr-link: #a8cbb8;
+}
+[data-limr-appearance='paper'] .reading-tip {
+  border-inline-start: 3px solid var(--limr-accent);
+  padding: .8rem 1rem;
+  background: #548b7410;
+}
+
+/* The same appearance selector is applied to portalled toolbars. */
+.limr-selection-toolbar[data-limr-appearance='paper'] {
+  --limr-toolbar-radius: 3px;
+  --limr-toolbar-panel-max-height: 190px;
+  --limr-toolbar-accent: var(--limr-accent);
+}

package/examples/packages/paper-theme/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@limr-example/paper-theme",
+  "version": "0.0.0",
+  "private": true,
+  "exports": { ".": "./index.css" },
+  "sideEffects": ["**/*.css"]
+}

package/examples/packages/reading-tools/index.d.ts

@@ -0,0 +1,2 @@
+import type { RendererExtension } from '@linloir/limr';
+export declare function readingTools(): RendererExtension;

package/examples/packages/reading-tools/index.js

@@ -0,0 +1,25 @@
+import { createElement as h } from 'react';
+import { AnnotationCard, AnnotationMarkdown, defineBlock, defineExtension } from '@linloir/limr';
+
+// No renderer internals or application services are needed by an npm plugin.
+export function readingTools() {
+  const tip = defineBlock({ name: 'reading-tip', component: ({ children }) => h('aside', { className: 'reading-tip' }, children) });
+  return defineExtension({
+    ...tip,
+    name: 'reading-tools',
+    annotationTypes: [{
+      type: 'reading-note', label: 'Reading note', icon: '◇', color: '#548b74',
+      overlay: { Card: props => h(AnnotationCard, { ...props, title: 'Reading note' }), expand: { placement: 'anchor' } },
+      Content: ({ data }) => h(AnnotationMarkdown, { source: data?.text ?? '' }),
+    }],
+    actions: [{
+      id: 'reading-note:add', label: 'Save passage', icon: h('svg', { viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.7, strokeLinecap: 'round', strokeLinejoin: 'round' }, h('rect', { x: 5, y: 3, width: 14, height: 18, rx: 3 }), h('path', { d: 'M9 8h6M9 12h6M9 16h4' })),
+      run(context) {
+        const id = `reading-note-${crypto.randomUUID()}`;
+        context.addAnnotation({ id, type: 'reading-note', range: context.selection.syntax.ranges[0], data: { text: `**Saved passage**\n\n${context.selection.text}` } });
+        context.activateAnnotation(id);
+        context.clearSelection();
+      },
+    }],
+  });
+}

package/examples/packages/reading-tools/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@limr-example/reading-tools",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "peerDependencies": {
+    "@linloir/limr": "^1.0.0",
+    "react": "^18.3.0 || ^19.0.0"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linloir/limr",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "Linloir's limr Is a Markdown Renderer — extensible reading and streaming components for React",
   "type": "module",
   "license": "MIT",
@@ -23,9 +23,11 @@
   "files": [
     "dist",
     "README.md",
+    "README.en.md",
     "LICENSE",
-    "docs/*.md",
-    "examples/*.tsx",
+    "docs",
+    "skills",
+    "examples",
     "benchmarks/results/*.json"
   ],
   "exports": {
@@ -62,12 +64,16 @@
   },
   "dependencies": {
     "@floating-ui/react": "^0.27.20",
+    "hyphenation.en-us": "^0.2.1",
+    "hypher": "^0.2.5",
     "katex": "^0.19.0",
+    "linebreak": "^1.1.0",
     "mdast-util-directive": "^3.1.1",
     "mdast-util-from-markdown": "^2.1.0",
     "mdast-util-gfm": "^3.1.0",
     "mdast-util-math": "^3.0.0",
     "mdast-util-mdx-jsx": "^3.2.0",
+    "mermaid": "^12.2.0",
     "micromark-extension-directive": "^4.0.0",
     "micromark-extension-gfm": "^3.0.0",
     "micromark-extension-math": "^3.1.0",
@@ -84,12 +90,14 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^5.2.0",
+    "markstream-react": "2.0.19",
     "react": "^19",
     "react-dom": "^19",
     "react-markdown": "^10.1.0",
     "rehype-katex": "^7.0.1",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
+    "stream-diffs": "0.0.2",
     "tsup": "^8.5.1",
     "tsx": "^4.23.15",
     "typescript": "^5.9.3",
@@ -97,17 +105,21 @@
     "vitest": "^3.2.7"
   },
   "scripts": {
-    "dev": "vite --host 127.0.0.1",
+    "dev": "pnpm pack:skills && vite --host 127.0.0.1",
     "build": "tsup && node scripts/build-assets.mjs",
-    "build:playground": "vite build --base=/LiMR/",
+    "build:playground": "pnpm pack:skills && vite build --base=/LiMR/",
     "preview:playground": "vite preview --host 127.0.0.1 --base=/LiMR/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:browser": "playwright test",
     "test:package": "node scripts/package-smoke.mjs",
+    "test:docs": "node scripts/check-docs.mjs",
+    "pack:skills": "python3 scripts/package-skills.py",
     "bench": "tsx benchmarks/run.ts",
+    "bench:streaming": "tsx benchmarks/streaming.ts",
     "bench:browser": "tsx benchmarks/browser.ts",
     "bench:selection": "tsx benchmarks/selection.ts",
+    "bench:markstream": "tsx benchmarks/markstream/run.ts",
     "check": "pnpm typecheck && pnpm test && pnpm build"
   }
 }

package/skills/limr-plugin-development/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: limr-plugin-development
+description: Develop, package, and integrate new @linloir/limr extension modules with custom syntax, annotation cards, selection actions, parameters, or CSS themes. Use for reusable LiMR plugin packages; ordinary application integration belongs to limr-use.
+---
+
+# Develop a LiMR plugin
+
+Deliver the requested extension as a package plus a working host import. Inspect the installed LiMR version and public declarations before choosing APIs. This bundle describes 1.0.0, including its locale APIs.
+
+Read [the contract](references/contract.md) for source mapping, annotation presentation, actions, resources, and localization. Start from [plugin-template](assets/plugin-template/README.md) when a standalone TypeScript/ESM package is useful. Copy the complete template to the requested project destination, rename its example package and IDs, and remove capabilities not needed by the task. Do not edit the installed skill as the project implementation.
+
+Choose the smallest public contract: defineBlock for a block; defineAnnotation for a type; defineExtension to combine capabilities. Keep React/LiMR as peers and build externals, export declarations, and expose CSS separately with sideEffects. Import no renderer internals and bundle no second React or LiMR runtime.
+
+Preserve original source positions. Reuse children/renderChildren, renderValue, and renderAttribute. Store every selected range with documentId and its original quote. A transform defaults to document scope; scope:local is valid only for subtree-local, prefix-independent work.
+
+Let the module own card meaning and controls through Content, overlay.Card, and sidebar.Preview. Reuse AnnotationCard and AnnotationMarkdown where suitable. LiMR owns shared positioning, portals, focus, and motion. Preview must not fetch; long tasks honor context.signal. The application owns services and credentials.
+
+Support host localization when requested: on 1.0.0 use useLocale() in components, locale.language for plugin dictionaries, label(locale) for annotation names, and context.locale in actions. Preserve stored user text across language changes. Older hosts require explicit plugin options instead; reflect the actual minimum in peerDependencies.
+
+Integrate with a stable plugins array and explicit CSS imports. Use extensions + replaceExtension for default replacements; duplicate names/tags/directives are errors. Do not silently discard persisted unknown annotations.
+
+Validate the built package in an independent consumer, not just a source alias. Check TypeScript, SSR, retained built-ins, syntax/source mapping/finalized streaming where relevant, and desktop/mobile card interactions for UI features. Exercise supported React major versions and both languages/themes when claimed. Report the package path and verified limits. Publishing remains a separate user action unless explicitly requested.

package/skills/limr-plugin-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Develop LiMR Plugins"
+  short_description: "Build and integrate LiMR extension packages"
+  default_prompt: "Use $limr-plugin-development to build a LiMR plugin package and import it into this application."

package/skills/limr-plugin-development/assets/plugin-template/README.md

@@ -0,0 +1,30 @@
+# LiMR reading-tools starter / 插件模板
+
+Copy this entire folder into your project, rename the example package/extension/type/action IDs, and adapt the implementation. It requires LiMR 1.0.0 for useLocale and localized annotation labels. The @example package is not on npm. private: true permits local packing while preventing accidental publication under the sample name.
+
+复制完整目录到项目，替换示例包名和各 ID。模板需要 LiMR 1.0.0 的语言接口；未发布版本可先安装维护者提供的本地 LiMR tgz。
+
+```sh
+npm install
+npm run typecheck
+npm run build
+npm pack
+```
+
+Install the generated tgz in a separate host application, then:
+
+```tsx
+import { Reader, chinese } 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()];
+export function Article({ source }: { source: string }) {
+  return <Reader source={source} plugins={plugins} locale={chinese} />;
+}
+```
+
+Supports <reading-tip title="Tip"> with Markdown inside, plus a selection action creating an example:note annotation with original-source anchors. English/Chinese labels follow the reader locale; options.label explicitly overrides both. User note text is never translated. Persist annotations in the host with annotations/onAnnotationsChange. The plugin includes no service connection or storage.
+
+Test the actual archive in each supported React major, SSR, desktop/mobile cards, and both locales before claiming compatibility. Keep React and LiMR external and declare them as peers. The CSS import is explicit.

package/skills/limr-plugin-development/assets/plugin-template/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@example/limr-reading-tools",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@linloir/limr": "^1.0.0",
+    "react": "^18.3.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0"
+  }
+}

package/skills/limr-plugin-development/assets/plugin-template/src/index.tsx

@@ -0,0 +1,50 @@
+import { AnnotationCard, AnnotationMarkdown, defineBlock, defineExtension, ToolIcon, useLocale,
+  type AnnotationContentProps, type AnnotationOverlayCardProps, type AnnotationSidebarPreviewProps,
+  type AnnotationType, type LiMRLocale, type RendererExtension } from '@linloir/limr';
+
+export interface ReadingNoteData { text: string }
+export interface ReadingToolsOptions { label?: string }
+const isChinese = (locale: LiMRLocale) => locale.language?.startsWith('zh') ?? false;
+
+export function readingTools(options: ReadingToolsOptions = {}): RendererExtension {
+  const label = (locale: LiMRLocale) => options.label ?? (isChinese(locale) ? '阅读笔记' : 'Reading note');
+  function Content({ data }: AnnotationContentProps<ReadingNoteData>) {
+    return <AnnotationMarkdown source={data?.text ?? ''} />;
+  }
+  function Card(props: AnnotationOverlayCardProps<ReadingNoteData>) {
+    return <AnnotationCard {...props} title={label(useLocale())} />;
+  }
+  function Preview({ data }: AnnotationSidebarPreviewProps<ReadingNoteData>) {
+    return data?.text ? <span>{data.text}</span> : null;
+  }
+  const note: AnnotationType<ReadingNoteData> = {
+    type: 'example:note', label, icon: <ToolIcon name="note" />, color: '#548b74', Content,
+    sidebar: { Preview },
+    overlay: { Card, previewWidth: 320, expand: { placement: 'center', width: 600, maxHeight: '80dvh' } },
+  };
+  const tip = defineBlock({
+    name: 'reading-tip',
+    component: ({ children, renderAttribute, node }) => <aside className="example-reading-tip">
+      {node.attributes?.title && <header>{renderAttribute('title')}</header>}
+      {children}
+    </aside>,
+  });
+  return defineExtension({
+    ...tip, name: 'example:reading-tools', annotationTypes: [note],
+    actions: [{
+      id: 'example:save-passage', label: context => label(context.locale), icon: <ToolIcon name="note" />,
+      visible: ({ selection }) => selection.settled && selection.quality !== 'unmapped'
+        && selection.syntax.ranges.some(range => range.end > range.start),
+      run(context) {
+        const id = `example-note-${crypto.randomUUID()}`;
+        context.addAnnotation({ id, type: note.type, data: { text: context.selection.text } satisfies ReadingNoteData,
+          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();
+      },
+    }],
+  });
+}

package/skills/limr-plugin-development/assets/plugin-template/src/styles.css

@@ -0,0 +1,9 @@
+.example-reading-tip {
+  padding: 1rem;
+  border-inline-start: 3px solid var(--limr-accent, #548b74);
+  background: var(--limr-surface, #f3f1ee);
+  color: var(--limr-text, #3d3a36);
+}
+.example-reading-tip > header { font-weight: 600; }
+.example-reading-tip > :first-child { margin-block-start: 0; }
+.example-reading-tip > :last-child { margin-block-end: 0; }

package/skills/limr-plugin-development/assets/plugin-template/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "declaration": true
+  },
+  "include": [
+    "src",
+    "tsup.config.ts"
+  ]
+}

package/skills/limr-plugin-development/assets/plugin-template/tsup.config.ts

@@ -0,0 +1,8 @@
+import { cp } from 'node:fs/promises';
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.tsx'], format: ['esm'], target: 'es2022', dts: true, clean: true,
+  external: ['@linloir/limr', 'react', 'react/jsx-runtime', 'react-dom'],
+  onSuccess: async () => { await cp('src/styles.css', 'dist/styles.css'); },
+});

package/skills/limr-plugin-development/references/contract.md

@@ -0,0 +1,51 @@
+# Public plugin contract
+
+## Syntax and rendering
+
+RendererExtension extends SyntaxExtension with components, rendererOverrides, streaming, annotationTypes, actions, and parameters. SyntaxExtension has name, micromark, mdast, tags, directives, transform(root, context), display, selection, scope, and literal. Extension/tag/directive names are validated independently; registered tags also accept matching component directives. Check the installed package's exports before depending on repository additions.
+
+defineBlock({ name, component, tags?, directives?, selection?, streaming? }) registers a block with default tag/directive [name], content selection, and local scope. Paired ::name components support nesting, as do existing ::: containers. defineAnnotation<T>(type) returns an extension named annotation:<type>. defineExtension returns the supplied RendererExtension.
+
+NodeRendererProps contains node, children, pending, incomplete, source (node slice), renderChildren(nodes, {trailing?}), renderValue(tokens?), and renderAttribute(name). pending describes a growing top-level block; incomplete identifies this particular open node. Do not reparse children or replace the original source. Token offsets and node positions are UTF-16. Use atomic selection for widgets without character correspondence. A custom visual boundary can use data-limr-selection-surface. InlineMarker inserts action-only markers; it is not an annotation.
+
+streaming.Loading renders a module-owned intermediate view; omit it to render progressive content using incomplete. streaming.effect supplies className, keyframes, and timing for new text/blocks. The last configured extension effect wins; Reader.streamEffect overrides it and false disables it. Default motion uses opacity alone and respects reduced motion. Reuse children/renderValue/renderChildren to retain text selection and control identity. literal keeps directive bodies from being interpreted as Markdown/JSX; parse original source without changing its public offsets.
+
+rendererOverrides rules contain type, component, and optional when(node,{pending,incomplete,ancestors}). The last matching rule wins, with host rules taking final precedence over extensions and components. Explicit replacements own intermediate rendering and keep LiMR's mapping/error boundaries. These are scoped matching rules, not a sandbox for third-party code.
+
+Unknown tags are inert literal source, unknown directives under standard() render child Markdown, and malformed JSX can fall back with diagnostics. A document-scoped transform disables tail-only parsing. Declaring local means no dependence on prior/future blocks and no mutation of retained prefixes.
+
+## Annotation UI
+
+AnnotationType<T> has type, label, optional icon/color/highlight, Content, Marker, overlay, sidebar, and load. highlight:'hover' paints temporary referenced-text feedback and suppresses the automatic persistent highlight unless explicitly requested. In 1.0.0 label can be a string or (locale: LiMRLocale) => string; stable factory instances can switch names without reparsing.
+
+Content receives annotation, data, loading, error, retry, presentation ('preview'|'expanded'|'sidebar'), expanded, and editing. It renders the resource/loading/error/editor states. AnnotationMarkdown renders nested Markdown with an isolated selection scope.
+
+overlay.Card receives annotation, occurrence, presentation, expanded, pinned, canExpand, expand, collapse, close, and children. It owns the full interior; children contains shared Content. AnnotationCard is an optional layout requiring title. Expansion is opt-in: {placement:'anchor'|'center',width?,height?,maxHeight?}, false, or an annotation resolver. previewWidth is independent. Preserve keyboard-accessible controls when drawing a custom card.
+
+sidebar.Preview receives local annotation/data, occurrence, all annotations in the group, and referenceText. It must not trigger load. Return null or set Preview:false to omit it. previewLines defaults to 2. Color fields include previewColor, color, borderColor, titleColor, textColor, excerptColor. collapseOnContentClick defaults to false. The first annotation type owns grouped preview/presentation. Do not duplicate shell padding; use shared CSS variables.
+
+load(annotation,{signal}) returns Promise<T> on visible content. The reader deduplicates requests and cancels when unused. Data changes/invalidation refresh resources. Do not put credentials in source, Markdown, or shipped templates. Implement service adapters in the host.
+
+## Selection actions and storage
+
+SelectionAction requires id, label, icon, and may provide run/visible/disabled/onHover/renderExpanded/render. label can resolve from ActionContext; icon can resolve from context. Custom panel operations use ToolbarActionContext.run for shared busy/error state. Expanded panels inherit the current action-row width; they cannot enlarge the toolbar. Use min-width: 0 and wrapping layouts for controls, with left-aligned whole-item wrapping.
+
+ActionContext includes selection, document, annotations, highlight, locale, clearSelection, signal, and document commands. The signal aborts on reader disposal, not menu close. selection.raw/syntax/blocks contain ranges and sourceText; quality is exact/atomic/unmapped, settled is false during adjustment. Keep all selected ranges and use original source slices as quote, not rendered text.
+
+For atomic widgets, selection.text and default/native copy preserve the entire original range, including delimiters, mapped attributes, and nested content. Outermost atomic ownership takes precedence. Ordinary text adjacent to an atom keeps rendered spelling. Partial code selections remain supported. A single atomic block anchors the toolbar below the block; custom block-local copy actions define their own copied value. Default copy feedback measures changing button width and uses eased width/opacity/scale transitions with reduced-motion support.
+
+Commands: addAnnotation(annotation,{highlight?,edit?}), updateAnnotation(id,partial), removeAnnotation(id), removeAnnotationsAt(ranges), editAnnotation(id|null), activateAnnotation(id|null). Updates shallow-merge annotation fields and replace data. Preserve immutable data and fields such as the initial question during answer streaming. Controlled hosts must return onAnnotationsChange results.
+
+Unknown types still produce generic/unavailable UI. Never delete hidden records to simulate plugin uninstallation. A plugin-only action should not create data for a type it fails to register.
+
+## Parameters, locales, and styles
+
+Augment RendererParameters through declare module '@linloir/limr', register defaults in extension.parameters, and read useRendererParameter. Host parameters override defaults without reparsing. Export augmentation in .d.ts.
+
+On 1.0.0 useLocale() exposes the merged locale. language is an optional BCP-47-style tag, with en and zh-CN in built-ins. Use it to select plugin-owned dictionaries, with a sensible fallback. Existing string labels remain valid. Plugins are responsible for translating their own editor buttons, placeholders, summaries, prompts, and status text; do not translate saved data.
+
+CSS is explicitly imported. For themes use [data-limr-appearance='your-theme']; reader ancestor selectors miss portals. Keep annotation IDs and CSS names unique. Use the provided .limr-underline on an inline span inside a layout wrapper: a direct flex child becomes a block and cannot paint an underline per text line. Labels that must remain on one line need intrinsic-width buttons; allow button groups to wrap on narrow screens.
+
+## Consumer verification
+
+Build ESM and .d.ts, pack, install into a temporary React consumer without source aliases, and exercise exported CSS. Test supported React versions rather than claiming compatibility from one host. Check final streaming vs one-shot parse equivalence for syntax changes, source offsets for entities/emoji, and actual browser states for card/toolbar/portal behavior. Test loader cancellation and isolation if adding remote data. No real network service is required by the starter.

package/skills/limr-use/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: limr-use
+description: Integrate @linloir/limr into React applications, author its supported Markdown, configure streaming, annotations, locales and themes, or import existing LiMR plugins. Use for LiMR consumers; new reusable plugin packages belong to limr-plugin-development.
+---
+
+# Use LiMR
+
+Deliver a working integration using the host application's installed LiMR API. These references cover the 1.0.0 contract; inspect package.json and exported declarations before assuming a newer or older version behaves identically.
+
+- Read [integration.md](references/integration.md) for components, styles, state, streaming, and installed plugin imports.
+- Read [syntax.md](references/syntax.md) when authoring or converting content. Preserve original source and do not invent tag/attribute support.
+
+Choose Reader for the complete UI, Markdown for body-only rendering, or one DocumentProvider with one primary Markdown for a custom layout. Inside a provider, omit Markdown.source to share the document.
+
+Append third-party factories through a stable plugins array. extensions replaces the entire list; use standard() and replaceExtension() to change defaults. Verify package existence and public exports before suggesting an npm install. Repository @limr-example packages are unpublished examples.
+
+Persist controlled annotations immutably and return every onAnnotationsChange value. Keep unknown types in storage even if the host filters them from a view. Unknown annotation types currently show generic/unavailable UI, not silent omission. Use original UTF-16 ranges, stable document IDs, and quotes; avoid DOM-derived offsets.
+
+Use locale={chinese} or english for built-in labels. locale does not translate source. In 1.0.0, plugins can use the public useLocale() hook and locale.language, and AnnotationType.label may resolve from the locale. Confirm these exports before using them against 0.1.0.
+
+For streaming, pass the accumulated source and finalize with streaming=false. Transport, authentication, storage, and stopping generation belong to the app. No AI provider is installed by this skill.
+
+Follow the existing project layout and stylesheet conventions. Validate a real rendered page, relevant interactions, and type/build checks. When changing portals or responsive layouts, inspect desktop and narrow containers. Report what was verified locally and what still needs the host environment; do not publish or deploy unless requested.

package/skills/limr-use/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Use LiMR"
+  short_description: "Integrate LiMR readers and existing plugins"
+  default_prompt: "Use $limr-use to integrate LiMR into this React application."

package/skills/limr-use/references/integration.md

@@ -0,0 +1,49 @@
+# Consumer contract
+
+## Minimal integration
+
+```tsx
+import { Reader, chinese } from '@linloir/limr';
+import '@linloir/limr/styles.css';
+import '@linloir/limr/math.css';
+
+export function Article({ source }: { source: string }) {
+  return <Reader source={source} locale={chinese} theme="auto" />;
+}
+```
+
+React/React DOM 18.3 or 19, Node 20+, ESM. Choose styles.css or styles/base.css; the latter avoids browser requests for Maple but leaves fonts in the installed package. math.css is separate. CSS themes are imported separately and selected with appearance; that scope reaches portals.
+
+Markdown is body-only, with no automatic toolbar. A composed DocumentProvider contains one primary <Markdown /> plus TableOfContents, AnnotationSidebar or AnnotationOverlay, and SelectionToolbar. A Markdown with source creates another document. Synchronized body/sidebar share one scroll container and unscaled coordinates; the host/grid supplies sidebar height. Use sync="none" for a separately scrolling annotation list.
+
+## State and commands
+
+Reader supports annotations/onAnnotationsChange. Supplying annotations makes it controlled; updates require a callback and a new array. Store data per article and supply a stable documentId. Changing Reader.key resets its internal state, not host state.
+
+Annotation is { id, type, data?, range?, anchors? }. Anchors are { range, documentId?, revision?, quote?, id? }. All offsets use the unmodified source's UTF-16 indices with an exclusive end. A quote relocates only when it matches uniquely; ambiguous or mismatched anchors can be omitted.
+
+Selection exposes text, quality, settled, and raw/syntax/blocks (each with ranges and sourceText). Preserve all selected ranges and quote each original slice. Syntax absorbs adjacent standard delimiters, not unselected words or custom outer tags. Code can be selected partially; math/images/Mermaid and selection:atomic widgets select as a whole. Toolbar/native copying serializes each atom's complete original source, including $ delimiters, fences, or custom tags; surrounding ordinary text remains rendered text. A single atomic block anchors its toolbar below the block. Block-local copy buttons may deliberately copy only code, a URL, or another module-specific value.
+
+useLiMR() exposes addAnnotation, updateAnnotation, removeAnnotation, removeAnnotationsAt, editAnnotation, activateAnnotation, clearSelection, invalidateAnnotation, and the engine. data updates replace the entire data object. addAnnotation normally adds a shared persistent highlight; highlight:false disables that. highlight:'hover' types skip automatic persistent highlights unless an explicit appearance is supplied. highlight annotations need no plugin and support background/underline/dotted/wavy plus hidden.
+
+## Streaming and resources
+
+Pass the complete accumulated text to source and set streaming=false at completion. followOutput is opt-in and pauses after upward scrolling. Keep extensions/plugins stable. Appends and eligible finalization reuse stable prefixes; full-document transforms, changed definitions, and middle edits may require complete parsing. Growing code fences have a literal fast path.
+
+New text and special blocks fade in without a background tint. streamEffect overrides animation keyframes/timing/className; false disables it. Extensions can provide streaming.effect and streaming.Loading. Incomplete code/math may render progressively while Mermaid waits for closure. Existing control state and selected text are retained; honor reduced motion in custom components.
+
+typography defaults to standard; choose justify for browser justification or knuth-plass for TeX paragraph optimization with English Knuth–Liang hyphenation. The client adapter caches preparation, retains offscreen DOM, and protects active selections on width changes. knuthPlass configures tolerances, penalties, emergencyStretch, looseness, and hyphenate. Browser font shaping is not pixel-identical to TeX PDF; compare workloads using the repository performance report rather than promising universal timing parity.
+
+SSR renders code text without client Shiki and a loading view for Mermaid; KP begins with standard layout and runs on the client. Await preloadMath() before synchronous SSR when complete formula HTML is needed. Framework client boundaries still apply to interactive components. Annotation loaders start when content is shown on the client; Preview only uses local data. Do not infer physical-device acceptance from Chromium mobile emulation.
+
+## Importing a plugin
+
+Read the actual installed package exports/peer dependencies. Import its factory, create a stable array, pass plugins, and import its CSS if required. Plugins add to defaults; extensions replaces them. Duplicate extension/tag/directive names throw. Parameter overrides belong in parameters and do not reparse source.
+
+rendererOverrides replaces views without changing syntax: each rule has type, component, and optional when(node,{pending,incomplete,ancestors}). Last matching rules win; host rules override extension rules. This restricts where a renderer applies, not what third-party JavaScript can execute.
+
+Missing plugin annotations retain data but show generic markers/unavailable cards. The Playground's plugin switches disable action entries while leaving renderers installed. If an application wants to hide unsupported types, merge untouched hidden records back into persistence on edits.
+
+Use docs shipped under node_modules/@linloir/limr/docs when available. Public source: https://github.com/Linloir/LiMR . Do not rely on internal src/dist imports.
+
+The Playground always refreshes to its default document and standard typography. Edits are stored only through explicit Save, then opened manually from the saved-draft menu; locale preference persists separately. Reader itself supplies no persistence.

package/skills/limr-use/references/syntax.md

@@ -0,0 +1,20 @@
+# Built-in syntax
+
+React defaults install gfm, math, code-highlight, mermaid, callout, definition, question, extras, video, figures, citation, translations, inline-highlights, and footnotes. Core createDocument defaults to basic CommonMark. Check the installed package's exports and version before using new APIs; these references describe the repository implementation.
+
+- Standard Markdown: headings, emphasis, lists, links, images, fenced/inline code, blockquotes. GFM adds tables, tasks, strikethrough, autolinks, and named footnote parsing; the default footnotes module presents notes as comment markers and sidebar/floating cards instead of superscripts/endnotes.
+- Math uses $…$ and $$ fences; import math.css.
+- Mermaid uses mermaid code fences or a paired ::mermaid component. Open streaming diagrams show loading; completed diagrams render on the client and fade in. One shared toolbar copies the diagram body, zooms, and switches source/image views. Drag to pan; arrow keys and wheel scroll, Shift+wheel scrolls horizontally. Selection is atomic in both views, and selection-toolbar/native copying retains the entire original fence/component. Override --limr-mermaid-max-height and --limr-mermaid-scrollbar through CSS.
+- Obsidian callouts use > [!type] Title. Types: note, abstract, info, todo, tip, success, question, warning, failure, danger, bug, example, quote; common Obsidian aliases work. A + suffix starts expanded, - starts collapsed. Blockquotes and callouts can nest. ::callout{type="tip" title="Title" fold="-"} is the component form.
+- ==highlight== creates a read-only blue source highlight; its toolbar offers copy plus a localized hint. Override --limr-inline-highlight or replace inlineHighlights({ color }). Named [^id] definitions and inline ^[Markdown content] create footnote cards. ==highlight==[^id] and ==highlight==^[note] attach the footnote to the highlight. Removing footnotes() restores GFM superscripts/endnotes.
+- <definition title="Term"> supports Markdown body. <title> and <content> child tags support richer content.
+- <question> supports question-content, question-hint, question-answer, question-sel-grp and question-sel. Use string attributes multi="true" and answer="[0,2]"; indices start at zero. This is an exercise, not an AI annotation.
+- <extras> contains <extra title="Title" url="https://example.com" desc="Description" />.
+- <citation id="a" title="Source" url="https://example.com" description="Markdown body" summary="Short preview" /> defines data; <ref id="a" /> or <ref ids='["a","b"]' /> inserts a marker. Legacy cite-id, cite-from-ids, and desc work. Standard [^footnote] syntax is a separate feature.
+- <figure src="/a.png" alt="A" caption="Caption" /> works alone or inside <figures columns="2">. Use figcaption children for Markdown. Limits: min-width/min-height 220/120, max-width/max-height 560/480; none/false removes maxima. Columns/rows, responsive, and gap control grouping. Media-local copy buttons copy image URLs or group Markdown; selection copying follows the selected atomic source range, including Markdown image syntax when present.
+- <video src="/clip.mp4" provider="native" /> and <md-video url="…" /> support native, YouTube, and Bilibili. loading defaults to visible (200px proximity), not click. Use loading="click" to defer until interaction. Remote playback is not guaranteed by local iframe tests.
+- <translations default="both"> contains <origin> and <translation>. Modes: origin/translation/both; both shows translation first. It displays supplied content, not an automatic translation service. Global parameters.translationMode overrides local mode; onTranslationModeChange accepts switch requests.
+
+Use static string/boolean attributes, never JavaScript expressions or spread props. Separate block tags and Markdown with blank lines. Only registered tags execute React renderers. Unknown tags show the full original text; unknown directives under standard() render children without their outer marker. Streaming defers partial headers and inline delimiters; recognized unclosed components carry incomplete and use module-owned loading/progressive rendering. Finish with streaming=false to apply final Markdown interpretation.
+
+Every registered tag also supports its matching directive, including child tags and citation/ref. Paired ::name{key="value"} and a closing :: support nested Markdown components; ::: containers and single-colon inline directives remain supported. Code/math/Mermaid directive bodies are literal. An unpaired two-colon line in a finalized document keeps its legacy leaf-directive meaning. This compatibility covers scalar attributes and nesting, not CoMark YAML properties, named slots, or frontmatter.