@linloir/limr 0.0.0-stage → 0.1.0

package/docs/visual-upgrade.md

@@ -0,0 +1,148 @@
+# Visual and extension refinement
+
+This checklist records the requested acceptance scope. An item is complete only
+after its implementation and relevant browser/package evidence are recorded.
+
+- [x] Third-party pnpm plugins add to defaults with a small public API; a real
+  separate package consumer verifies syntax, actions and annotation content.
+- [x] CSS packages override the default skin, including portals and multiple
+  readers. Document stable tokens, layers, selectors and packaging.
+- [x] Local Maple Mono NF CN with ligatures, CJK/Nerd/multilingual glyphs, small
+  on-demand font subsets, swap fallback, versioned cacheable URLs and licenses.
+- [x] Rounded copy/check icons: frosted math button, transparent code button,
+  background hover/press and nonlinear success/reset; code header/body same
+  font, both themes. Hover/press translation was removed after review.
+- [x] Compact symmetric block spacing, question type label, animated diamond
+  choices, multiline underline, color feedback, single submit/retry, expandable
+  hint/answer sections with animated result and answer reveal.
+- [x] Reusable nonlinear multiline underline on TOC, extras, options and links.
+- [x] Nonlinear TOC/sidebar alignment, card expansion/collapse; reduced motion.
+- [x] Anchored overlay enter/exit and continuous preview-to-expanded transition,
+  animated content reveal, no remount/repeated request, focus/viewport handling.
+- [x] Square centered markers with independent hover/press animations.
+- [x] Unified line geometry for selection and highlights: text, partial inline
+  code, atomic inline/display math, partial fenced code with inline markers,
+  special blocks. Marker paint only when text on both sides is spanned; preserve
+  marker background/motion. No adjacent-code-line overlap.
+- [x] Mobile selection visual parity where browser APIs permit; document native
+  handles/platform limitations with evidence rather than removing accessibility.
+- [x] Playground common navigation and plugin styling, live two-column editor
+  and bidirectional source-aware scroll matching, responsive narrow layout.
+- [x] Unit/browser/package tests, visual evidence in light/dark/mobile, updated
+  performance checks for long documents and streams without unbounded repaint.
+
+Additional review requirements:
+
+- [x] Continuous drag regression: publish and paint during the gesture; measure
+  an 878k-character document, select-all/scroll, and 1,000 tokenized code lines.
+  The three browser regressions passed with one worker on 2026-10-12.
+- [x] All annotation buttons use the same fixed slot at 80% of the previous
+  citation size; active state must not persistently enlarge plugin markers;
+  oversized SVG/image/nested plugin content stays inside the slot.
+- [x] Whole collapsed sidebar card is clickable, localized expand/collapse text
+  and hover/state motion, balanced bottom spacing in nested Markdown.
+- [x] Standard blockquotes use a Note/注释 title and special-block background.
+- [x] Definition/extras have more bottom breathing room; question disclosures
+  sit farther below submit, with symmetric collapsed/expanded bottom spacing.
+- [x] Original pointed diamond paths and center-fill animation, now 15px;
+  first-line center alignment; empty space beside choices has no hover effect.
+- [x] Math/code copy buttons never translate on hover/press; code button is
+  smaller with visually balanced header insets.
+- [x] Atomic formula selection/highlights retain the painted surface's corners.
+
+Initial refinement validation on 2026-10-12:
+
+- `pnpm check`: TypeScript, 40 unit/SSR tests and library build passed.
+- `pnpm test:browser`: 23 Chromium tests passed, including continuous long
+  document/code drag, select-all/scroll, formula corners, adversarial plugin
+  icon sizes, question/sidebar controls, copy transitions, footnote selection,
+  overlay continuity, mobile viewport and bidirectional editor scrolling.
+- `pnpm test:package`: actual LiMR, syntax/action/annotation plugin and CSS
+  package tarballs install and work in independent React 18.3.1 and React 19
+  applications, including TypeScript, SSR, portals and theme isolation. Core
+  also imports when React imports are deliberately denied.
+- Production browser, selection and Node measurements are retained in
+  `benchmarks/results/`; see [performance.md](performance.md) for measured
+  budgets, slower cases and limits. Do not infer equal selection-processing
+  cost or a long-document SSR advantage from the browser frame statistics.
+- Inspected production screenshots are saved locally in `artifacts/visual/`:
+  `light.png`, `dark.png`, `question-collapsed.png`, `question-expanded.png`,
+  `sidebar-expanded.png`, `markers.png`, `math-selected.png`,
+  `math-highlighted.png`, `mobile.png` and `mobile-overlay.png`.
+  `evidence.json` records measured 15px diamonds, six equal 14.71875px marker
+  buttons, 4px formula selection corners, code themes and font requests.
+
+Physical iOS/Android selection handles and finger dragging were not tested.
+The mobile evidence covers Chromium touch emulation and programmatic Selection
+API geometry; platform controls remain native. Font cache headers belong to the
+host application; see [styles.md](styles.md). Plugin slots contain oversized
+elements but cannot repair an incorrectly centered intrinsic SVG drawing.
+
+Narrow-overlay follow-up on 2026-10-12:
+
+- The final card bounds and text width stay stable during a clip reveal. The
+  horizontal origin follows the current marker; vertical reveal follows the
+  resolved top/bottom placement. Positioning no longer measures animated widths
+  or heights, and a changed marker cannot reuse the previous positioning result.
+  Preview height is capped to available space on the resolved side; this cap is
+  released when switching to the expanded dialog.
+- Native scrollbars are hidden. A 3px overlaid thumb appears only while scrolling,
+  fades after 800ms of inactivity, supports dragging, and stays hidden throughout
+  card motion. It never reserves text width.
+- `pnpm check` passed (40 tests, TypeScript and build). The 16 tests in
+  `motion-playground.spec.ts` and `reader.spec.ts` passed, including motion frame
+  geometry, right/bottom edge placement, rapid reference changes, interrupted
+  exit/reopening, scrollbar behavior, touch viewport, focus restoration and
+  annotation request reuse.
+
+References reviewed: the previous renderer's Extras/Question/Citation styles,
+selection and highlight hooks, the web app's QuestionnaireView multiline
+gradient underline and diamond control, and UniDevice's rounded copy control. The new
+implementation keeps LiMR independent of those applications.
+
+Module-controlled cards and follow-up refinements on 2026-10-12:
+
+- Annotation modules opt into anchored content-height expansion or a centered
+  size such as 80dvh. Citation stays a pinnable preview; conversation and reading
+  plugin examples opt into their own expansion. Sidebar content-click collapse
+  is also opt-in; Citation items instead underline and follow their links.
+- Preview reveal/content animations sample their live frame on each direction
+  change, including repeated interruption. Retained overlays remeasure on reopening;
+  Floating UI's closed positioning state otherwise stranded the retained card.
+  Exit completion, rather than a fixed unmount timer, releases the subtree.
+  The painted shell connects preview and expanded bounds independently of text
+  and controls. Direct opening measures the module's preview first; closing
+  returns to that preview geometry while fading out. Preview entry/exit both
+  take 560ms, and preview/dialog transformations both take 480ms.
+- Modules own the full floating UI through `overlay.Card`, optionally reusing
+  `AnnotationCard`. Centered dialogs use the page viewport and module-specified
+  widths. Initial focus lands on the dialog container, with visible focus cues
+  retained for keyboard navigation. Mobile TOC toggles animate continuously.
+- Sidebar hover applies across the whole card and survives header collapse.
+  Close controls have background feedback. Attribute titles support source
+  selection/highlights. Question correct diamonds are filled green; the submit
+  label is shorter. Nested definition formula backgrounds have stronger contrast.
+- Citation spacing now follows the supplied screenshots: the preview item gap
+  is 6px smaller and trailing space 2px smaller; collapsed sidebar trailing
+  space grows 2px. Expanded sidebar heading space shrinks 2px, separator spacing
+  moves 2px from above to below, and trailing space shrinks 3px. The final
+  Markdown paragraph no longer overrides these gaps through margin collapse.
+- Video providers mount near the viewport, normalize watch/short/embed and BV/av
+  links, retain click-loading as an option, and share the math copy primitive.
+  YouTube uses the previous renderer's youtube.com/embed address with origin
+  referrer information. In the local real-network comparison, dQw4w9WgXcQ failed
+  with an auth player error even in the previous renderer's bare iframe setup;
+  M7lc1UVf-VE loaded its player. This is not evidence that the user's specific
+  video now plays. Automated provider tests intercept network responses.
+- Validation: TypeScript, all 50 unit/SSR cases, and all 33 browser cases passed.
+  After the final animation fix, the 20 motion/reader cases were rerun; the other
+  13 cases include video, visual selection and the three selection performance
+  checks. React 18.3.1 and React 19 tarball consumers passed types, SSR and browser
+  plugin/theme checks. The local tarball and production demo were rebuilt.
+- Production screenshots inspected: question-refined.png,
+  definition-math-refined-light.png, definition-math-refined-dark.png,
+  citation-overlay-refined.png, video-provider-refined.png in artifacts/visual/.
+  refinement-evidence.json records the compact retry button, filled correct
+  diamond, nested formula colors and the real official YouTube player's loaded
+  title/isPlayable state. Loading that player does not prove the reported Rick
+  Astley video plays in the user's browser.

package/examples/assistant.tsx

@@ -0,0 +1,52 @@
+import { AnnotationCard, AnnotationMarkdown, defineExtension, type AnnotationContentProps, type AnnotationOverlayCardProps, type AnnotationSidebarPreviewProps, type RendererExtension, type SelectionSnapshot } from '@linloir/limr';
+import type { ReactNode } from 'react';
+
+/** Your application owns transport, authentication and conversation storage. */
+export interface AssistantAdapter {
+  answer: (request: { selection: SelectionSnapshot; question: string; signal: AbortSignal }) => AsyncIterable<string>;
+}
+interface AnswerData { text: string; question?: string; status: 'streaming' | 'complete' | 'error'; error?: string }
+const assistantIcon = <svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="m8 2 1.8 4.2L14 8l-4.2 1.8L8 14l-1.8-4.2L2 8l4.2-1.8L8 2Z" fill="currentColor" /></svg>;
+
+/** Example application plugin. This is deliberately not a LiMR default module. */
+export function assistant({ adapter, type = 'assistant', label = 'Ask assistant', icon = assistantIcon, color = '#8b5cf6', prompt = selection => `Explain “${selection.text}”` }: {
+  adapter: AssistantAdapter; type?: string; label?: string; icon?: ReactNode; color?: string; prompt?: (selection: SelectionSnapshot) => string;
+}): RendererExtension {
+  function Card(props: AnnotationOverlayCardProps<AnswerData>) {
+    return <AnnotationCard {...props} title={label} />;
+  }
+  function Answer({ data }: AnnotationContentProps<AnswerData>) {
+    return <div aria-busy={data?.status === 'streaming'}>
+      <AnnotationMarkdown source={data?.text || '…'} streaming={data?.status === 'streaming'} />
+      {data?.status === 'error' && <p role="alert">{data.error}</p>}
+    </div>;
+  }
+  function Preview({ data, referenceText }: AnnotationSidebarPreviewProps<AnswerData>) {
+    const question = data?.question || referenceText;
+    return question ? <span title={question}>{question}</span> : null;
+  }
+  return defineExtension({
+    name: type,
+    annotationTypes: [{ type, label, icon, color, Content: Answer, sidebar: { Preview }, overlay: { Card, expand: { placement: 'center', width: 680, height: '80dvh' } } }],
+    actions: [{ id: `${type}:ask`, label, icon: icon ?? assistantIcon, async run(context) {
+      const id = `${type}-${crypto.randomUUID()}`;
+      const question = prompt(context.selection);
+      let text = '';
+      context.addAnnotation({ id, type, data: { text, question, status: 'streaming' } satisfies AnswerData, 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();
+      try {
+        for await (const chunk of adapter.answer({ selection: context.selection, question, signal: context.signal })) {
+          if (context.signal.aborted) return;
+          text += chunk;
+          context.updateAnnotation(id, { data: { text, question, status: 'streaming' } satisfies AnswerData });
+        }
+        if (!context.signal.aborted) context.updateAnnotation(id, { data: { text, question, status: 'complete' } satisfies AnswerData });
+      } catch (error) {
+        if (!context.signal.aborted) context.updateAnnotation(id, { data: { text, question, status: 'error', error: error instanceof Error ? error.message : String(error) } satisfies AnswerData });
+      }
+    } }],
+  });
+}

package/examples/notes.tsx

@@ -0,0 +1,73 @@
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import { AnnotationMarkdown, ToolIcon, defineExtension, useLiMR, 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: '补充解释或参考来源' },
+] as const;
+
+function NoteContent({ annotation, data, editing, presentation }: AnnotationContentProps<NoteData>) {
+  const commands = useLiMR();
+  const text = data?.draft ?? data?.text ?? '';
+  const isEditing = editing || data?.draft !== undefined;
+  const input = useRef<HTMLTextAreaElement>(null);
+  const kind = kinds.find(kind => kind.type === annotation.type)!;
+  useEffect(() => {
+    if (!isEditing) return;
+    if (presentation === 'preview') return;
+    const frame = requestAnimationFrame(() => {
+      const field = input.current;
+      if (field) { field.focus({ preventScroll: true }); field.selectionStart = field.selectionEnd = field.value.length; }
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [isEditing, presentation]);
+  useLayoutEffect(() => {
+    const field = input.current;
+    if (!field) return;
+    const resize = () => { field.style.height = 'auto'; field.style.height = `${field.scrollHeight}px`; };
+    resize();
+    // The same draft can move between a narrow card and the wider sidebar.
+    let width = field.clientWidth;
+    const observer = new ResizeObserver(() => { if (field.clientWidth !== width) { width = field.clientWidth; resize(); } });
+    observer.observe(field.parentElement!);
+    return () => observer.disconnect();
+  }, [isEditing, text]);
+  const save = () => {
+    if (!text.trim()) return;
+    commands.updateAnnotation(annotation.id, { data: { text } }); commands.editAnnotation(null);
+  };
+  const cancel = () => {
+    if (!data?.text.trim()) commands.removeAnnotation(annotation.id);
+    else { commands.updateAnnotation(annotation.id, { data: { text: data.text } }); commands.editAnnotation(null); }
+  };
+  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 => {
+        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>;
+}
+
+/** 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> },
+      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 => {
+      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 });
+      context.clearSelection();
+    } })),
+  });
+}

package/package.json

@@ -1,6 +1,113 @@
 {
   "name": "@linloir/limr",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Linloir's limr Is a Markdown Renderer — extensible reading and streaming components for React",
+  "type": "module",
+  "license": "MIT",
+  "author": "Linloir",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Linloir/LiMR.git"
+  },
+  "homepage": "https://linloir.github.io/LiMR/",
+  "bugs": {
+    "url": "https://github.com/Linloir/LiMR/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs/*.md",
+    "examples/*.tsx",
+    "benchmarks/results/*.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./extensions": {
+      "types": "./dist/extensions/index.d.ts",
+      "import": "./dist/extensions/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./styles/base.css": "./dist/base.css",
+    "./fonts.css": "./dist/fonts/maple.css",
+    "./math.css": "./dist/math.css",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@floating-ui/react": "^0.27.20",
+    "katex": "^0.19.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",
+    "micromark-extension-directive": "^4.0.0",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-extension-math": "^3.1.0",
+    "micromark-extension-mdx-jsx": "^3.0.2",
+    "micromark-util-decode-string": "^2.0.1",
+    "micromark-util-types": "^2.0.3",
+    "shiki": "^4.5.0"
+  },
+  "devDependencies": {
+    "@fontsource-variable/noto-serif-sc": "^5.3.1",
+    "@playwright/test": "^1.64.0",
+    "@types/katex": "^0.16.8",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    "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",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.7",
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsup && node scripts/build-assets.mjs",
+    "build:playground": "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",
+    "bench": "tsx benchmarks/run.ts",
+    "bench:browser": "tsx benchmarks/browser.ts",
+    "bench:selection": "tsx benchmarks/selection.ts",
+    "check": "pnpm typecheck && pnpm test && pnpm build"
+  }
 }