@linloir/limr 1.0.0 → 1.0.1

package/dist/styles.css

@@ -1,5 +1,10 @@
 /* LiMR classic skin. Local assets only; unlayered application CSS wins. */
 @import "./fonts/maple.css";
+/* Viewport coordinates change on every scroll. They belong to the mask host,
+   never its text descendants; inheriting them invalidates the entire article. */
+@property --limr-fade-start { syntax: '<length>'; inherits: false; initial-value: 0px; }
+@property --limr-fade-end { syntax: '<length>'; inherits: false; initial-value: 0px; }
+
 @layer limr {
   :where([data-limr-appearance]) {
     --limr-ease: cubic-bezier(.16, 1, .3, 1);
@@ -62,8 +67,21 @@
       --limr-link: #8bb8e3; --limr-selection: #6e88c955; --limr-shadow: #0006;
     }
   }
-  .limr-prose { width: 100%; min-width: 0; font-size: var(--limr-font-size, 1rem); line-height: var(--limr-line-height, 1.8); font-feature-settings: var(--limr-font-features, 'palt' 1); overflow-wrap: break-word; --limr-paragraph-align: start; }
+  .limr-prose { width: 100%; min-width: 0; font-size: var(--limr-font-size, 1rem); line-height: var(--limr-line-height, 1.8); font-feature-settings: var(--limr-font-features, normal); text-spacing-trim: var(--limr-punctuation-spacing, space-all); overflow-wrap: break-word; --limr-paragraph-align: start; }
   .limr-prose[data-limr-justify='true'] { --limr-paragraph-align: justify; }
+  .limr-prose[data-limr-typography='pretty'] :where(p,.limr-paragraph,li,figcaption) { text-wrap: pretty; }
+  .limr-prose[data-limr-typography='pretty'] :where(h1,h2,h3,h4,h5,h6) { text-wrap: balance; }
+  /* Stable native wrapping prevents earlier lines moving for every token. */
+  .limr-prose[data-limr-typography='pretty'] :where([data-pending], [data-pending] p, [data-pending] li, [data-pending] .limr-paragraph) { text-wrap: wrap; text-wrap: stable; }
+  .limr-block-loading { display: flex; align-items: center; min-height: 3rem; padding-block: .5rem; }
+  .limr-loading { display: inline-flex; flex: none; width: 22px; height: 22px; line-height: 0; color: var(--limr-secondary, #7b7975); }
+  .limr-loading svg { display: block; width: 100%; height: 100%; overflow: visible; }
+  .limr-loading circle { fill: none; stroke-width: 4; }
+  .limr-loading-track { stroke: currentColor; opacity: .17; }
+  .limr-loading-orbit { transform-box: view-box; transform-origin: 16px 16px; animation: limr-loading-orbit 1.55s cubic-bezier(.65,0,.35,1) infinite; }
+  .limr-loading-arc { stroke: currentColor; stroke-linecap: round; stroke-dasharray: 3 97; transform: rotate(-90deg); transform-box: view-box; transform-origin: 16px 16px; animation: limr-loading-arc 1.55s cubic-bezier(.65,0,.35,1) infinite; }
+  @keyframes limr-loading-orbit { 0% { transform: rotate(0deg); } 50% { transform: rotate(300deg); } 100% { transform: rotate(720deg); } }
+  @keyframes limr-loading-arc { 0% { stroke-dasharray: 3 97; stroke-dashoffset: 0; } 46%,57% { stroke-dasharray: 92 8; stroke-dashoffset: -4; } 100% { stroke-dasharray: 3 97; stroke-dashoffset: -100; } }
   .limr-prose :where(p,.limr-paragraph,li) { text-align: var(--limr-paragraph-align); text-align-last: start; text-justify: auto; }
   .limr-prose ::selection { background: var(--limr-selection, #667eea4d); }
   .limr-prose { position: relative; isolation: isolate; transition: translate var(--limr-motion) var(--limr-ease); }
@@ -399,8 +417,9 @@
   .limr-toolbar-item { display: flex; align-items: center; border-radius: 3px; transition: color 240ms var(--limr-ease); }
   [data-ready] .limr-toolbar-item { animation: limr-tool-float 330ms cubic-bezier(.16,1,.3,1) calc(30ms + var(--limr-tool-index) * 22ms) both, limr-tool-fade 210ms cubic-bezier(.22,.7,.3,1) calc(65ms + var(--limr-tool-index) * 22ms) both; }
   .limr-toolbar-action { display: inline-grid; place-items: center; flex: none; min-height: 34px; padding: 5px 7px; border: 0; border-radius: 3px; background: transparent; white-space: nowrap; line-height: 1.5; }
-  .limr-tool-face { display: flex; align-items: center; justify-self: start; grid-area: 1 / 1; gap: 5px; width: 0; min-width: 0; line-height: 1.5; opacity: 0; pointer-events: none; transition: opacity 240ms var(--limr-ease); }
-  .limr-tool-face[data-visible] { width: auto; opacity: 1; }
+  .limr-tool-faces { display: inline-grid; min-width: 0; transition: width 320ms var(--limr-ease); }
+  .limr-tool-face { display: flex; align-items: center; justify-self: start; grid-area: 1 / 1; gap: 5px; width: max-content; min-width: 0; line-height: 1.5; opacity: 0; transform: translateY(2px) scale(.94); transform-origin: left center; pointer-events: none; transition: opacity 220ms var(--limr-ease), transform 320ms var(--limr-ease); }
+  .limr-tool-face[data-visible] { opacity: 1; transform: none; }
   .limr-tool-label { display: block; flex: none; padding-block-end: 1px; }
   .limr-tool-face > .limr-tool-icon { animation: limr-tool-fade 240ms var(--limr-ease) both; }
   .limr-toolbar-item[data-status='success'] { color: var(--limr-success, #52885e); }
@@ -423,6 +442,8 @@
   .limr-toolbar-delete-warning[aria-hidden='true'] { visibility: hidden; }
   [data-placement^='top'] .limr-toolbar-delete-warning { order: -1; }
   .limr-toolbar-delete-hint { margin: 4px 8px 5px; font-size: 11px; color: var(--limr-error, #b45858); }
+  .limr-selection-toolbar[data-readonly] { width: max-content; }
+  .limr-toolbar-readonly-hint { margin: 4px 8px 5px; font-size: 11px; line-height: 1.6; color: var(--limr-secondary, #7b756e); white-space: nowrap; text-align: start; }
   .limr-highlight-settings fieldset { border: 0; padding: 0; margin: 0 0 12px; min-width: 0; }
   .limr-highlight-settings legend { margin-bottom: 7px; padding: 0; color: var(--limr-secondary, #7b756e); font-size: 11px; }
   .limr-highlight-colors { display: flex; flex-wrap: wrap; justify-content: flex-start; gap: 9px; }
@@ -452,3 +473,62 @@
     .limr-prose pre { white-space: pre-wrap; }
   }
 }
+
+@layer limr { .limr-stream-block { display: contents; } }
+
+@layer limr {
+  .limr-mermaid-display { padding: 0; overflow: hidden; }
+  .limr-mermaid-loading { display: grid; place-items: center; min-height: 80px; }
+  .limr-mermaid-viewport { overflow: auto; max-width: 100%; max-height: var(--limr-mermaid-max-height, min(70vh, 36rem)); padding: .75rem 1rem; box-sizing: border-box; scrollbar-width: thin; scrollbar-color: var(--limr-mermaid-scrollbar, #87837866) transparent; cursor: grab; user-select: none; -webkit-user-select: none; }
+  .limr-mermaid-viewport * { user-select: none; -webkit-user-select: none; }
+  .limr-mermaid-viewport[data-dragging] { cursor: grabbing; }
+  .limr-mermaid-viewport:focus-visible { outline-offset: -2px; }
+  .limr-mermaid-viewport::-webkit-scrollbar { width: 5px; height: 5px; }
+  .limr-mermaid-viewport::-webkit-scrollbar-track,.limr-mermaid-viewport::-webkit-scrollbar-corner { background: transparent; }
+  .limr-mermaid-viewport::-webkit-scrollbar-thumb { background: var(--limr-mermaid-scrollbar, #87837866); border-radius: 8px; }
+  .limr-mermaid-viewport::-webkit-scrollbar-button { display: none; }
+  .limr-mermaid-viewport[hidden],.limr-prose .limr-mermaid-source[hidden] { display: none; }
+  .limr-mermaid-canvas { margin-inline: auto; min-width: 0; transition: width var(--limr-motion) var(--limr-ease); }
+  .limr-mermaid-canvas > svg { display: block; width: 100%; height: auto; max-width: none !important; }
+  .limr-prose .limr-mermaid-source { background: transparent; padding: .75rem 1rem; }
+  .limr-mermaid-error { color: var(--limr-secondary); font-size: .8em; margin-bottom: .5rem; }
+  .limr-mermaid-error button { border: 0; background: transparent; text-decoration: underline; }
+  .limr-block-tools { position: absolute; inset-block-start: .45rem; inset-inline-end: .5rem; display: flex; align-items: center; padding: 2px; gap: 1px; border-radius: 9px; background: #ffffff99; backdrop-filter: blur(12px); -webkit-backdrop-filter: blur(12px); box-shadow: 0 1px 5px #29231d0a, inset 0 0 0 1px #ffffff80; color: #6b6760; z-index: 1; opacity: 0; transition: opacity var(--limr-motion-fast) var(--limr-ease); }
+  .limr-mermaid-block:hover .limr-block-tools,.limr-mermaid-block:focus-within .limr-block-tools { opacity: 1; }
+  @media (hover: none) { .limr-block-tools { opacity: 1; } }
+  .limr-block-tools > button { display: inline-grid; place-items: center; position: relative; width: 28px; height: 28px; padding: 0; border: 0; border-radius: 7px; background: transparent; color: inherit; transition: color var(--limr-motion-fast) var(--limr-ease), background-color var(--limr-motion-fast) var(--limr-ease), opacity var(--limr-motion-fast) var(--limr-ease); }
+  .limr-block-tools > button > svg { width: 19px; height: 19px; }
+  .limr-block-tools > button:enabled:hover { background: #87837822; color: #2c2925; }
+  .limr-block-tools > button:enabled:active { background: #87837838; }
+  .limr-block-tools > button[aria-pressed='true'] { color: var(--limr-heading); }
+  [data-limr-theme='dark'] .limr-block-tools { background: #37332dcc; box-shadow: 0 1px 5px #0002, inset 0 0 0 1px #ffffff10; color: #c7c0b6; }
+  [data-limr-theme='dark'] .limr-block-tools > button:enabled:hover { color: #f0ebe4; }
+  @media (prefers-color-scheme: dark) {
+    [data-limr-theme='auto'] .limr-block-tools { background: #37332dcc; box-shadow: 0 1px 5px #0002, inset 0 0 0 1px #ffffff10; color: #c7c0b6; }
+    [data-limr-theme='auto'] .limr-block-tools > button:enabled:hover { color: #f0ebe4; }
+  }
+  .limr-callout { border-color: var(--limr-callout-color); background: color-mix(in srgb, var(--limr-callout-color) 8%, transparent); }
+  .limr-callout-title { display: flex; align-items: center; gap: .5em; color: var(--limr-callout-color); text-transform: none; letter-spacing: .02em; font-size: .9em; }
+  .limr-callout-title > svg { width: 18px; height: 18px; flex: none; }
+  .limr-callout-title > span { flex: 1; }
+  .limr-callout-toggle { border: 0; border-radius: 5px; background: transparent; padding: 2px; display: inline-flex; }
+  .limr-callout-toggle:hover { background: color-mix(in srgb, var(--limr-callout-color) 12%, transparent); }
+  .limr-callout-toggle > svg { width: 18px; height: 18px; transition: transform var(--limr-motion) var(--limr-ease); }
+  .limr-callout-toggle[aria-expanded='false'] > svg { transform: rotate(-90deg); }
+  .limr-callout > .limr-collapse > .limr-collapse-inner > .limr-block-content { min-height: 0; }
+  @media (prefers-reduced-motion: reduce) { .limr-mermaid-canvas,.limr-block-tools,.limr-block-tools > button,.limr-callout-toggle > svg { transition: none; } }
+  @media print {
+    .limr-mermaid-viewport { max-height: none; overflow: visible; }
+    .limr-mermaid-canvas { width: 100% !important; }
+    .limr-block-tools { display: none; }
+  }
+}
+
+@layer limr {
+  [data-limr-kp] { white-space: nowrap; text-align: start; text-wrap: nowrap !important; }
+  [data-limr-kp][data-limr-kp-stale='clip'] { overflow-x: clip; }
+  [data-limr-kp][data-limr-kp-stale='wrap'] { white-space: normal; text-wrap: wrap !important; }
+  @media print { [data-limr-kp][data-limr-kp-stale] { overflow: visible; white-space: normal; text-wrap: wrap !important; } }
+  .limr-kp-glue { display: inline-block; font-size: 0; line-height: 0; white-space: pre; }
+  .limr-kp-hyphen::before { content: '-'; }
+}

package/dist/{translations-DHnYMg4h.d.ts → translations-BXzSwLBJ.d.ts}

@@ -1,11 +1,13 @@
 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';
+import { n as SyntaxExtension, M as MarkdownNode, A as Annotation, b as AnnotationOccurrence, g as HighlightData, m as SourceRange, j as SelectionSnapshot, f as DocumentSnapshot, K as KnuthPlassOptions, c as DocumentEngine } from './knuth-plass-C8mgFm7W.js';
 
 interface NodeRendererProps {
     node: MarkdownNode;
     children: ReactNode;
     pending: boolean;
+    /** True only for this unclosed construct, not every child of a growing block. */
+    incomplete?: boolean;
     source: string;
     /** Render an existing subtree without parsing strings again. */
     renderChildren: (nodes: readonly MarkdownNode[], options?: {
@@ -23,6 +25,18 @@ interface TextToken {
     style?: CSSProperties;
 }
 type NodeRenderer = ComponentType<NodeRendererProps>;
+interface RendererOverride {
+    /** AST type, or the registered name of a component. */
+    type: string;
+    component: NodeRenderer;
+    /** Limits the replacement; false falls back to the next match or built-in. */
+    when?: (node: MarkdownNode, context: {
+        pending: boolean;
+        incomplete: boolean;
+        ancestors: readonly MarkdownNode[];
+    }) => boolean;
+}
+type TypographyMode = 'knuth-plass' | 'standard' | 'justify';
 type AnnotationPresentation = 'preview' | 'expanded' | 'sidebar';
 interface AnnotationExpansion {
     /** Grow beside the marker, or center within the page's visual viewport. */
@@ -111,13 +125,28 @@ interface AnnotationType<T = unknown> {
     }) => Promise<T>;
 }
 interface RendererExtension extends SyntaxExtension {
+    streaming?: {
+        /** Optional module-owned intermediate state. Omit to render progressively. */
+        Loading?: NodeRenderer;
+        /** Last configured effect wins. The reader may override it. */
+        effect?: StreamEffect | false;
+    };
     /** Register document parameter defaults. Plugins extend RendererParameters
      * through TypeScript declaration merging and read them with useRendererParameter. */
     parameters?: Readonly<RendererParameters>;
     components?: Readonly<Record<string, NodeRenderer>>;
+    /** Ordered, reader-local overrides. Last matching entry wins. */
+    rendererOverrides?: readonly RendererOverride[];
     annotationTypes?: readonly AnnotationType<any>[];
     actions?: readonly SelectionAction[];
 }
+/** Animation applies to newly appended text and newly appearing blocks. CSS can style the supplied
+ * class; keyframes/timing use the Web Animations API. No source rewriting. */
+interface StreamEffect {
+    className?: string;
+    keyframes?: Keyframe[];
+    timing?: KeyframeAnimationOptions;
+}
 /** Open to module augmentation; parameter names and semantics belong to plugins. */
 interface RendererParameters {
 }
@@ -214,6 +243,7 @@ interface LiMRLocale {
     highlightWavy: string;
     hideHighlight: string;
     showHighlight: string;
+    inlineHighlightHint?: string;
     deleteAnnotations: string;
     deleteAnnotationsHint: string;
 }
@@ -226,11 +256,18 @@ interface ViewConfiguration {
     /** CSS skin name, applied to every view including portalled controls. */
     appearance?: string;
     components?: Readonly<Record<string, NodeRenderer>>;
+    /** Reader rules take precedence over extension rules and component mappings. */
+    rendererOverrides?: readonly RendererOverride[];
     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;
+    /** TeX Knuth–Plass, standard (default), or browser justification.
+     * pretty/normal remain compatible native-CSS aliases. */
+    typography?: TypographyMode | 'pretty' | 'normal';
+    knuthPlass?: KnuthPlassOptions;
+    streamEffect?: StreamEffect | false;
     locale?: Partial<LiMRLocale>;
     scrollRoot?: HTMLElement | null;
     scrollOffset?: number;
@@ -315,4 +352,4 @@ declare module '@linloir/limr' {
 }
 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 };
+export { type ActionContext as A, useLocale as B, useRendererParameter as C, type DocumentCommands as D, useSelection as E, 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 RendererOverride as k, type RendererParameters as l, type StreamEffect as m, type StyledProps as n, type ToolbarActionContext as o, type TranslationMode as p, type TranslationsOptions as q, type TypographyMode as r, useAnnotation as s, translations as t, useAnchor as u, useAnnotationState as v, useAnnotations as w, useDocument as x, useDocumentSelector as y, useLiMR as z };

package/docs/en/README.md

@@ -4,18 +4,18 @@
 
 [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.
+These pages describe the current repository implementation, including the new streaming, typography, and module capabilities. Check installed exports and types when consuming an npm release. 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) |
+| Write Markdown, Mermaid, callouts, highlights, footnotes, and two-colon components | [Default syntax](syntax.md) |
+| Integrate React, typography modes, streaming, custom layouts, or SSR | [Application integration](integration.md) |
+| Persist selections, highlights, citations, and annotations; understand atomic copying | [Annotations and selection](annotations.md) |
+| Add syntax, cards, actions, streaming effects, or conditional renderers | [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) |
+| Customize themes, fonts, KP layout, animation, and diagrams | [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) |
@@ -23,4 +23,6 @@ These pages describe the current public LiMR 1.0.0 implementation. Chinese is th
 
 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.
 
+Playground uses standard typography by default; its menu also offers Knuth–Plass and justification, and the streaming demo runs at a slower pace. Refresh opens the default document without restoring the previous article or edits. Explicitly saved drafts can be loaded manually; locale preference persists separately. Docs links open the selected page directly, and switching between Docs and Playground preserves edits during the current session.
+
 [Back to README](../../README.en.md) · [Live Playground](https://linloir.github.io/LiMR/)

package/docs/en/annotations.md

@@ -36,7 +36,7 @@ Persist source, a stable documentId, annotation ID/type/data/anchors, and your a
 
 | Field | Meaning |
 | --- | --- |
-| text | Readable selected text |
+| text | Readable selected text; settled atomic content uses its complete original source |
 | raw | Mapped original ranges and source |
 | syntax | Absorbs adjacent standard Markdown delimiters at each edge, without selecting extra words or outer custom tags |
 | blocks | Ranges and source for touched blocks |
@@ -46,6 +46,8 @@ Persist source, a stable documentId, annotation ID/type/data/anchors, and your a
 
 Each result has ranges and sourceText. Notes usually use syntax.ranges. Store document.source.slice(start, end) as quote for **every range**. Code supports partial selection; math and images are atomic. Do not infer offsets from DOM textContent lengths: entities, escapes, and emoji make those coordinates differ.
 
+The default selection toolbar and browser copy serialize atomic content as a whole, retaining its original delimiters (`$…$`, `$$…$$`, image syntax, Mermaid fences/directives, or plugin block tags). Surrounding ordinary text keeps its rendered spelling and explicit line breaks. This also applies when reopening an existing highlight. A plugin's `selection: 'atomic'` covers its mapped attributes, children, and nested atoms; block-local copy buttons may offer their own specialized format.
+
 ## Highlights and commands
 
 highlight needs no extra AnnotationType. Its data supports color, style (background / underline / dotted / wavy), and hidden. Deleting content annotations differs from hiding their highlight.

package/docs/en/api.md

@@ -37,6 +37,10 @@ Reader, Markdown, and DocumentProvider accept:
 | appearance | classic; CSS scope propagated to portals |
 | locale | english; accepts chinese or Partial<LiMRLocale> |
 | justify | false; justify prose/list text |
+| typography | standard (default), knuth-plass, or justify; legacy CSS modes pretty / normal remain available |
+| knuthPlass | TeX paragraph parameters; see [styles](styles.md) |
+| rendererOverrides | Ordered, reader-scoped rules with type, component and optional when predicate |
+| streamEffect | Increment animation override; false disables |
 | scrollRoot | null/omitted means window |
 | scrollOffset | 24px |
 | onDocumentChange | DocumentSnapshot after updates |
@@ -63,7 +67,7 @@ The default locale is english. Missing partial keys fall back to English. locale
 | 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 |
+| ToolIcon | name and SVG props; e.g. note, copy, highlight, comment, zoom-in, zoom-out, source, image |
 
 Shared views/hooks require a provider, except standalone Markdown and Reader. AnnotationCard is an interior template, not its own portal. sidebar.renderCard receives occurrence/active/activate; toolbar.render receives context/actions/run.
 
@@ -105,3 +109,7 @@ Core defaults to extensions=[]. Use SyntaxExtension with micromark/mdast for a s
 DocumentSnapshot contains id, revision, source, streaming, blocks, headings, definitions, footnotes, footnoteOrder, annotations, occurrences, diagnostics, and metrics. Its annotations are **parsed from source**. Use useAnnotations for merged external data.
 
 Other core exports include walk, textContent, rangeOf, intersects, safeUrl, mapText, selectionFromRange, replaceExtension, resolveAnnotationAnchors, annotationReferenceRange, sameRange, defaultHighlight, LruCache, and ResourceCache. ResourceCache.acquire returns promise/release; invalidate clears a key or everything.
+
+`inlineHighlights({ color?, component? })` and `footnotes(annotationTypeOptions?)` are included in `standard()`. `HighlightData.readOnly` limits the default highlight toolbar to copying and a hint; `AnnotationOccurrence.referenceRange` separates a marker's source location from the text it references.
+
+Core also exports `knuthPlass(items, lengths, options?)`, `prepareKnuthPlass(items)`, `texBadness`, and their types. The prepared function reuses prefix sums when solving the same paragraph at multiple widths.

package/docs/en/architecture.md

@@ -14,15 +14,23 @@ Docs navigation and Playground persistence/loading/language menus belong to the
 
 ## Append parsing
 
-Streaming reparses from the unstable final top-level block and reuses earlier stable blocks. Late Markdown reference/footnote definitions may change earlier semantics and trigger full correction. Middle edits, document-scoped transforms, extension changes, and finalization also reparse fully. Long lists, code fences, or unclosed tags can still make tail reparsing expensive.
+Streaming reparses from the unstable final top-level block, reusing stable prefixes, line indexes, and node semantic indexes. Growing code fences can use a literal fast path. Finalization can also reparse only the tail rather than always parsing the whole document. Late Markdown reference/footnote definitions, middle edits, document-scoped transforms, or extension changes can still require a full parse. Long paragraphs, lists, and complex unclosed tags retain tail-parsing costs.
 
-Source is not rewritten before parsing, and public coordinates preserve UTF-16 offsets. Custom transforms must preserve positions and honor locality. Embedded references and application annotations enter separately and merge in the React layer.
+`incomplete` identifies an unclosed node; `pending` describes its growing top-level block. Modules can render progressively or provide `streaming.Loading`. Incomplete headers and inline syntax markers are deferred. Increment animations affect new content; temporary wrappers merge after animation completion once native selection leaves them. Streaming code retains existing text nodes, and final highlighting waits while its text is selected.
+
+Public source always retains the original input. Internally, the parser inserts markers for two-colon components and incomplete syntax, then maps positions back through sparse offsets. These internal markers never enter copied text, annotations, or persisted data. Custom transforms must preserve original UTF-16 positions and honor locality. Embedded references and application annotations enter separately and merge in the React layer.
+
+## Typography and source mapping
+
+Standard mode uses browser layout by default. KP loads on the client: preparation caches glyph measurements, hyphenation, legal breakpoints, and prefix sums; solving runs TeX paragraph dynamic programming. Stable paragraphs near the viewport take priority and retain their DOM offscreen. Width changes reuse preparation and text containers. Selected paragraphs keep their native Range and defer layout until selection clears. Original source offsets and annotations remain unchanged; see [styles](styles.md) and [performance](performance.md).
+
+Atomic selection text serializes complete original source; surrounding ordinary text retains its rendered spelling and explicit line breaks. Mapped attributes, children, and nested atoms follow the enclosing plugin block’s atomic selection contract.
 
 ## State and resources
 
 Update configuration immutably and keep static references stable. Scrolling and parameter updates do not require parsing. A provider manages one primary body; document state and annotation requests are isolated between providers.
 
-Annotation loading uses bounded per-reader caching; releasing consumers can cancel unused requests. Pure Shiki token results use a bounded module-level cache, separate from user annotation data. The library supplies no model service, authentication, database, or automatic persistence.
+Annotation loading uses bounded per-reader caching; releasing consumers can cancel unused requests. Pure Shiki token results use a bounded module-level cache, separate from user annotation data. Mermaid uses bounded result caching and serializes global initialization with rendering so readers using different themes cannot interfere. The library supplies no model service, authentication, database, or automatic persistence.
 
 ## Fallback behavior
 

package/docs/en/extensions.md

@@ -13,7 +13,7 @@ Start with [built-in modules](modules.md) for module objects, factories, names,
 | A new block with Markdown content | defineBlock |
 | A standalone annotation type | defineAnnotation |
 | Combined syntax, annotations, actions, and parameters | defineExtension / RendererExtension |
-| A different view for an existing node | components |
+| A different view for existing nodes or a matching subset | components / rendererOverrides |
 | New parsing rules | micromark + mdast, with transform when needed |
 | Visual changes only | CSS theme package + appearance |
 
@@ -51,7 +51,7 @@ export const notice = defineBlock({
 });
 ```
 
-This supports `<notice title="Tip">…</notice>` and `:::notice{title="Tip"}`. name becomes the tag and directive name unless tags/directives overrides them. defineBlock defaults to display: block, selection: content, and scope: local.
+This supports `<notice title="Tip">…</notice>`, paired `::notice{title="Tip"}` / `::`, and `:::` containers. name becomes the tag and directive name unless tags/directives overrides them. defineBlock defaults to display: block, selection: content, and scope: local.
 
 | NodeRendererProps | Use |
 | --- | --- |
@@ -59,6 +59,7 @@ This supports `<notice title="Tip">…</notice>` and `:::notice{title="Tip"}`. n
 | children | Already-rendered subtree; reuse it where possible |
 | source | Source for **this node**, not the entire document |
 | pending | Whether its tail block is still streaming |
+| incomplete | Whether this particular syntax node is unclosed |
 | renderChildren(nodes, { trailing? }) | Rearrange an existing subtree or append an action-only marker |
 | renderValue(tokens?) | Render literals/tokens while preserving selection and annotation insertion |
 | renderAttribute(name) | Render attribute text with original source coordinates |
@@ -148,12 +149,60 @@ The host overrides defaults with parameters={{ exampleDetail: 'full' }}. Paramet
 
 ## Parsing and streaming constraints
 
-SyntaxExtension supports micromark, mdast, tags, directives, display, selection, transform, and scope. Transforms default to document scope. Declare scope: local only if the transform depends on the current subtree and never revises earlier content or needs document-wide semantics. context.source is the original whole document; positions remain original UTF-16 offsets. Do not regex-rewrite source before parsing.
+SyntaxExtension supports micromark, mdast, tags, directives, display, selection, literal, transform, and scope. Transforms default to document scope. Declare scope: local only if the transform depends on the current subtree and never revises earlier content or needs document-wide semantics. context.source is the original whole document; positions remain original UTF-16 offsets. Plugins must not regex-rewrite source before parsing.
 
-Unknown custom tags display their complete original text, including Markdown inside. Unknown directives in the default configuration render their inner Markdown without outer directive markers; with no directive extension installed, basic Markdown parsing applies. Incomplete tags fall back with diagnostics and retry on append. Finish with finish() or streaming=false. Transform exceptions become diagnostics. Client renderer boundaries can fall back to source, but React error boundaries do not catch server-rendering exceptions.
+Unknown custom tags display their complete original text, including Markdown inside. Unknown directives in the default configuration render their inner Markdown without outer directive markers; with no directive extension installed, basic Markdown parsing applies. Registered incomplete tags and containers carry node.incomplete and are retried on append; unfinished headers stay hidden or use the module loading view. Invalid JSX can still fall back with diagnostics. Finish with finish() or streaming=false. Transform exceptions become diagnostics. Client renderer boundaries can fall back to source, but React error boundaries do not catch server-rendering exceptions.
 
 Validate tags/directives, Chinese/emoji, offsets, equivalence between finalized streams and one-shot parsing, SSR, and browser behavior for new interactions. For distribution, test actual packed consumption as described in [plugin packages](plugin-packages.md).
 
 ## Plugin localization
 
 From 1.0.0, components can read the merged locale through useLocale() and select their own dictionary by locale.language. AnnotationType.label accepts a string or `(locale) => string`; actions use context.locale. Citation titles switch between Citation and 引用. A stable plugin instance can update labels without rewriting source. Saved user notes are never translated.
+
+## Streaming presentation
+
+`pending` describes a growing top-level block; `incomplete` describes this particular unclosed syntax node. Every registered tag also accepts component directive syntax. `defineBlock` accepts `streaming.Loading`; omit it to render progressively, using `incomplete` in your component. Component identity is retained while children grow. Default definition, question, extras, video, figure and callout directives use a small themed ring; Mermaid waits for closure before asynchronously drawing. Code, math, GFM and translations show usable partial content. Blockquote-style callouts can grow progressively once their header is complete. Unclosed citation definitions do not register incomplete data.
+
+```tsx
+import { defineBlock, defineExtension } from '@linloir/limr';
+
+export const chart = defineBlock({
+  name: 'chart',
+  component: ({ children }) => <section>{children}</section>,
+  streaming: { Loading: () => <span role="status">Preparing chart…</span> },
+});
+export const streamMotion = defineExtension({
+  name: 'example:stream-motion',
+  streaming: {
+    effect: {
+      className: 'my-stream-increment',
+      keyframes: [{ opacity: 0.25 }, { opacity: 1 }],
+      timing: { duration: 320, easing: 'ease-out' },
+    },
+  },
+});
+```
+
+The last extension providing `streaming.effect` wins. The reader's `streamEffect` overrides it; `false` disables the effect. Keyframes and timing use the Web Animations API. Reduced-motion preferences suppress new animations. Default text/block entrances change opacity without adding a background tint. Text wrappers are compacted after completion, once the native selection leaves them. Use `children`, `renderChildren` and `renderValue` to retain this behavior; a plugin that replaces its own DOM owns its selection and animation behavior.
+
+`SyntaxExtension.literal` protects directive bodies from Markdown/JSX interpretation. Literal modules read their original `source` or transform the resulting component. It does not execute attribute expressions, YAML or JavaScript.
+
+## Conditional component replacement
+
+A module's `rendererOverrides` can restrict replacement by node type, language, ancestors or streaming state. Rules apply only inside that Reader. The last matching rule wins; Reader rules take precedence over extension rules and component mappings. Unmatched nodes retain their existing renderer.
+
+```tsx
+import { defineExtension, type NodeRenderer } from '@linloir/limr';
+
+const JavaScriptCode: NodeRenderer = ({ renderValue }) => <pre>{renderValue()}</pre>;
+export const customCode = defineExtension({
+  name: 'example:javascript-code',
+  rendererOverrides: [{
+    type: 'code',
+    when: (node, context) => node.lang === 'js' && !context.incomplete,
+    component: JavaScriptCode,
+  }],
+});
+```
+
+`when` also receives `pending` and `ancestors`. An explicit replacement owns its intermediate rendering while retaining LiMR's source wrapper, atomic selection and error boundary. Use `renderValue`, `renderAttribute` and `renderChildren` to preserve mappings. These restrictions scope rendering rules; they are not a JavaScript security sandbox.

package/docs/en/getting-started.md

@@ -36,6 +36,8 @@ export function Article() {
 
 Wide containers show contents, body, and annotations. Below `sidebarBreakpoint` (1120px by default), annotations use an overlay. Contents become a collapsible list on narrow screens.
 
+Typography defaults to `standard`; `knuth-plass` and `justify` are also available, as shown in [integration](integration.md). Defaults include Mermaid, nested callouts, `==highlights==`, and footnote cards; do not append duplicate modules. See [built-in modules](modules.md).
+
 ## Body only
 
 ```tsx

package/docs/en/integration.md

@@ -21,7 +21,31 @@ export function StreamingAnswer({ answer, generating }: {
 }
 ```
 
-The application owns transport and appends each chunk to the complete answer. Do not pass only the newest chunk as source. The final update must set streaming to false to complete semantic correction. followOutput follows only while the reader remains near the bottom. The core engine supports append(chunk) / finish(); React props take the accumulated string.
+The application owns transport and appends each chunk to the complete answer. Do not pass only the newest chunk as source. The final update must set streaming to false to finalize syntax and semantics. Finalization can reuse stable prefixes; definition changes and other global dependencies may still require a full parse. followOutput follows only while the reader remains near the bottom. The core engine supports append(chunk) / finish(); React props take the accumulated string.
+
+New text and special blocks fade through opacity by default, without replaying the entrance when a paragraph finishes. Use `streamEffect={false}` to disable it or supply `className`, `keyframes`, and `timing`; reduced-motion preferences take precedence. Unclosed modules can show loading states while code/math render progressively. Reuse `children`, `renderChildren`, and `renderValue` to preserve controls and selections. See [extensions](extensions.md).
+
+## Paragraph typography
+
+```tsx
+import { useState } from 'react';
+import { Reader, type TypographyMode } from '@linloir/limr';
+
+export function TypographyReader({ source }: { source: string }) {
+  const [mode, setMode] = useState<TypographyMode>('standard');
+  return <>
+    <select aria-label="Typography" value={mode}
+      onChange={event => setMode(event.target.value as TypographyMode)}>
+      <option value="standard">Standard</option>
+      <option value="knuth-plass">Knuth–Plass</option>
+      <option value="justify">Justified</option>
+    </select>
+    <Reader source={source} typography={mode} />
+  </>;
+}
+```
+
+`standard` is the default; `justify` uses browser justification; `knuth-plass` enables the paragraph optimizer. `knuthPlass` configures TeX parameters and hyphenation. Streaming tails participate in KP once stable. See [styles](styles.md) and [performance](performance.md) for behavior and measurement boundaries.
 
 ## Nested scroll containers
 
@@ -111,7 +135,7 @@ export async function renderArticle(source: string) {
 }
 ```
 
-React streaming SSR can also handle Suspense. Shiki adds highlighting on the client; SSR already includes code text. Annotation load requests start when a card is shown on the client. Put preloaded data in annotation.data if needed. The host must still serve CSS and fonts.
+React streaming SSR can also handle Suspense. Shiki adds highlighting on the client; SSR already includes code text. Mermaid emits a loading state on the server and fades in after client rendering. KP measures fonts and typesets on the client; SSR retains ordinary text layout. Annotation load requests start when a card is shown on the client. Put preloaded data in annotation.data if needed. The host must still serve CSS and fonts.
 
 ## Existing plugins and themes
 

package/docs/en/modules.md

@@ -40,13 +40,13 @@ The names need not match. The code-highlighting factory is `codeHighlight()`, it
 
 `video({ loading: 'click' })` sets module defaults for that Reader. A `<video loading="eager" … />` tag overrides the setting for one video. Available options vary by module; see [default syntax](syntax.md).
 
-## Ten default modules included with LiMR
+## Default modules included with LiMR
 
-These modules ship in `@linloir/limr`; they do not require ten separate npm installations. `standard()` returns an array containing the following ten module objects, each with its default settings.
+These modules ship in `@linloir/limr`; no separate npm installations are required. `standard()` returns the following module objects with their default settings.
 
 | Factory function | Object's `name` | Capability and content syntax |
 | --- | --- | --- |
-| `gfm()` | `gfm` | Tables, `~~strikethrough~~`, tasks, autolinks, `[^id]` endnotes |
+| `gfm()` | `gfm` | Tables, `~~strikethrough~~`, tasks, autolinks, `[^id]` footnote parsing |
 | `math()` | `math` | `$…$` inline and `$$…$$` display math; also import math.css |
 | `codeHighlight()` | `code-highlight` | Shiki colors for code fences with a language identifier |
 | `definition()` | `definition` | `<definition>` cards with a title and Markdown body |
@@ -56,12 +56,16 @@ These modules ship in `@linloir/limr`; they do not require ten separate npm inst
 | `figures()` | `figures` | `<figures>` / `<figure>` responsive groups, single figures, and captions |
 | `citation()` | `citation` | `<citation>` source definitions and `<ref>` markers with cards |
 | `translations()` | `translations` | `<translations>` original, translated, and parallel views |
+| `mermaid()` | `mermaid` | Mermaid fences / `::mermaid`, image/source, zoom and copy |
+| `callout()` | `callout` | Obsidian callout types, aliases and nested quotes / `::callout` |
+| `inlineHighlights()` | `inline-highlights` | `==text==` and `::highlight`, blue read-only highlights |
+| `footnotes()` | `footnotes` | `[^id]` / `^[body]`, comment markers and cards; `::footnote` / `::footnote-ref` |
 
-Import these functions from `@linloir/limr` or `@linloir/limr/extensions`. `standard()` is a convenience function returning an array, not an eleventh module.
+Import these functions from `@linloir/limr` or `@linloir/limr/extensions`. `standard()` is a convenience function returning an array, not an additional module.
 
 `Reader`, standalone `Markdown`, and `DocumentProvider` automatically use `standard()` when `extensions` is omitted. Your first `<Reader source={source} />` therefore supports these capabilities. Components inside a shared Provider inherit its configuration. Core-only `createDocument()` starts with CommonMark; extensions must be explicit, and it does not display React UI.
 
-Highlight, copy, and annotation deletion are built-in toolbar actions. Highlights are saved as annotation data, not a separate Markdown tag. The Playground's margin notes, reading notes, questions, footnote annotations, and simulated assistant come from example plugins and **are not automatically installed in every Reader**. The `question()` exercise module is also separate from question annotations.
+Highlight, copy, and annotation deletion are built-in toolbar actions. Default modules recognize `==text==` and Markdown footnotes. Source-authored highlights offer copying but no toolbar editing. The Playground's editable margin notes, reading notes, questions, footnote annotations, and simulated assistant come from example plugins and **are not automatically installed in every Reader**. The `question()` exercise module is also separate from question annotations.
 
 ## Choosing a configuration
 

package/docs/en/performance.md

@@ -4,7 +4,7 @@
 
 [Documentation](README.md) · [简体中文](../zh-CN/performance.md)
 
-These are the repository's **2026-10-12 historical measurements**, retained for comparison. They were not rerun for this documentation/Playground update and are not guarantees.
+The first sections retain the repository's **2026-10-12 historical measurements** for comparison. The **2026-10-13** section below records this optimization's measurements. Neither set is a performance guarantee.
 
 Environment: Intel Core i7-13700, WSL2/Linux, Node 20.19.5, Chromium 156.0.8078.4, React 19 production. Baseline: react-markdown 10.1.0 + remark-gfm 4.0.1.
 
@@ -37,7 +37,7 @@ Large-document SSR varied substantially: LiMR samples were 2.64–9.10s and base
 
 Keeping the full DOM supports search, selection, and printing, but initial long-document rendering still costs time. Incremental parsing reuses stable prefixes; long tail blocks, document-scoped transforms, definition changes, middle edits, and finalization can remain expensive. Keep extensions/plugins stable and limit highlighting languages/length when appropriate.
 
-The measurements do not cover large formula collections, Shiki cold starts, dense annotations, third-party plugins, full Reader layouts, or physical mobile devices. Installed font size also differs from browser transfers; see [styles and fonts](styles.md).
+The historical measurements above exclude full Reader layouts; the newer KP comparison below includes one complete Reader workload. Neither set covers large formula collections, Shiki cold starts, arbitrary dense annotations/plugins, or physical mobile devices. Installed font size also differs from browser transfers; see [styles and fonts](styles.md).
 
 ## Reproduce in the repository
 
@@ -51,3 +51,43 @@ pnpm bench:selection
 ```
 
 Avoid concurrent builds/benchmarks. Scripts write benchmarks/results. Reevaluate using your hardware, content, and built version rather than treating historical numbers as current-package acceptance.
+
+## 2026-10-13: streaming and layout measurements
+
+This compares the working implementation with pre-change commit `ebab991` in one process, using the same dependencies, UTF-16 input and chunk boundaries. Five warmed trials alternate order; values are the sample with median total time. Core append and finalization only: React, layout, async highlighting and network are excluded. Environment and raw samples: [streaming.json](../../benchmarks/results/streaming.json).
+
+| Scenario | Characters | Before total | After total |
+| --- | ---: | ---: | ---: |
+| GFM | 34,860 | 139.22ms | 89.07ms |
+| Default modules | 34,860 | 141.40ms | 94.63ms |
+| Growing code fence | 43,209 | 1335.87ms | 29.05ms |
+| Single long paragraph | 7,840 | 72.43ms | 74.32ms |
+
+Changes include incremental line indexes, cached semantic facts for retained nodes, local finalization, an append path for growing code fences, and lazy code character maps. Complex growing paragraphs still need reparsing. Differences for a single long paragraph are small and subject to runtime variance; these results do not establish equal improvements for all content.
+
+Run `pnpm bench:streaming` to measure the current core. For the alternating comparison, set `LIMR_BENCH_BASELINE` to a separate untouched checkout of `ebab991`, with the same dependencies available there. The script writes `benchmarks/results/streaming.json`; it does not recreate the historical hardware or timings.
+
+Production Chromium 156, including synchronous React commits, forced layout, default typography and increment animations: a 34,860-character stream with default modules had **3.9ms P95**, 7.3ms maximum; a 43,211-character code stream had **2.6ms P95**, 12.4ms maximum. Three isolated font-ready pages per scenario, 256-character chunks; idle rAF time and async highlighting excluded. No old-browser-implementation comparison was made, and this is not physical-device input-to-display latency. Data: [streaming-browser.json](../../benchmarks/results/streaming-browser.json).
+
+KP has a separate production benchmark using the complete scikit-learn Playground, including its TOC, sidebar and annotations. Three fresh pages per mode run three downward/upward sweeps each, then 32 viewport changes across 1100–1420px. The first sweep includes newly visible paragraphs; later sweeps reuse their typesetting. The table pools 1,080 scroll samples and 96 resize samples per mode, without CPU throttling.
+
+| Measurement | Standard | Knuth–Plass |
+| --- | ---: | ---: |
+| Scroll median / P95 / maximum | 16.6 / 17.0 / 18.5ms | 16.6 / 19.8 / 46.5ms |
+| Resize median / P95 / maximum | 11.2 / 24.1 / 31.9ms | 17.7 / 41.6 / 49.9ms |
+| Scroll samples over 50ms | 0 / 1,080 | 0 / 1,080 |
+| Resize samples over 50ms | 0 / 96 | 0 / 96 |
+
+Source anchor lookup prunes unrelated source bindings and stops at the first visible character, avoiding a full KP DOM traversal for every sidebar item.
+
+Scroll timings span `scrollTo` through the next rAF; resize timings include the viewport update, protocol overhead and the next rAF. KP still costs more during resizing, but this run did not reproduce the earlier long stalls. These are local Chromium measurements, not physical-device input latency or a guarantee for arbitrary plugins. Raw samples and exact boundaries: [layout.json](../../benchmarks/results/layout.json).
+
+```sh
+pnpm build:playground
+pnpm preview:playground --port 4174
+# In another terminal, with no concurrent build or test:
+pnpm exec tsx benchmarks/layout.ts
+BENCH_URL=http://127.0.0.1:4174/LiMR pnpm exec tsx benchmarks/streaming-browser.ts
+```
+
+Preparation caches font measurements, hyphenation, legal breakpoints and prefix sums independently of line width. Rendering uses a word-spacing run per line instead of an element per space. Width changes patch glue in place when the breaks match, or reuse text containers when they change. A shared synchronous measurement Range avoids retaining thousands of live ranges across DOM mutations. Highlight geometry is cached in paragraph coordinates, adjacent KP paint fragments merge into lines, and paint writes do not force a layout per rectangle. Viewport-mask coordinates do not inherit into the article. Scrolling retains typeset nodes and does not rerun the paragraph solver.