@linloir/limr 0.1.0 → 1.0.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,45 @@
+# Public plugin contract
+
+## Syntax and rendering
+
+RendererExtension extends SyntaxExtension with components, annotationTypes, actions, and parameters. SyntaxExtension has name, micromark, mdast, tags, directives, transform(root, context), display, selection, and scope. Extension/tag/directive names are validated independently.
+
+defineBlock({ name, component, tags?, directives?, selection? }) registers a block with default tag/directive [name], content selection, and local scope. defineAnnotation<T>(type) returns an extension named annotation:<type>. defineExtension returns the supplied RendererExtension.
+
+NodeRendererProps contains node, children, pending, source (node slice), renderChildren(nodes, {trailing?}), renderValue(tokens?), and renderAttribute(name). 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.
+
+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.
+
+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,41 @@
+# 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 are atomic.
+
+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; full-document transforms, changed definitions, middle edits, and finalization require complete parsing.
+
+SSR renders code text without client Shiki. 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.
+
+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.

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

@@ -0,0 +1,17 @@
+# Built-in syntax
+
+React defaults install gfm, math, code-highlight, definition, question, extras, video, figures, citation, and translations. Core createDocument defaults to basic CommonMark.
+
+- Standard Markdown: headings, emphasis, lists, links, images, fenced/inline code, blockquotes. GFM adds tables, tasks, strikethrough, autolinks, and document-end footnotes.
+- Math uses $…$ and $$ fences; import math.css.
+- <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. Images copy URLs, groups copy Markdown.
+- <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. Incomplete JSX falls back and retries during streaming.
+
+Directives are registered separately: definition/question/extras/video have their main directive; figures has figures/figure/figcaption; translations has translations/origin/translation. Citation/ref do not register directives. Do not invent directives for every child tag. There is no built-in ==highlight== syntax.