@aicayzer/inkkit 0.0.8 → 0.0.9

package/README.md

@@ -2,9 +2,9 @@
 
 InkKit is a reusable Markdown editor for simple writing tools and richer document apps. It provides formatted editing, source preservation, portable clipboard content and optional host-managed images, while your app controls its appearance, files and interface.
 
-Write in formatted or source mode with shared undo/redo. Edit tables, task lists, footnotes, reference links, highlights and callouts. Preview bounded Mermaid diagrams offline. Copy readable text and semantic HTML, explicitly copy Markdown source, or capture a complete printable document. Unsupported syntax remains editable literal Markdown.
+Write in formatted or source mode with shared undo/redo. Edit tables, task lists, footnotes, reference links, highlights and callouts. Preview bounded Mermaid diagrams offline. Copy readable text and semantic HTML, explicitly copy Markdown source, or capture a complete printable document. Native hosts can use scoped readable-text ranges and demand-driven geometry with their own search controls and viewport insets. Unsupported syntax remains editable literal Markdown.
 
-**Version status:** 0.0.7 is published. This branch documents the **unpublished 0.0.8 candidate**, adding read-only and text-input policies, command availability, scoped appearance, labels and shortcuts. Installing from npm currently gets the published release; the new controls require the candidate.
+Host controls, read-only and text-input policies, command availability, scoped appearance, labels and shortcuts are available from 0.0.8. Check the [releases](https://github.com/aicayzer/inkkit/releases) for published versions and verification evidence.
 
 ```sh
 npm install @aicayzer/inkkit
@@ -43,6 +43,6 @@ InkKit runs on the web and in offline web views. Hosts use its public TypeScript
 
 Start with the [feature guide](docs/supported-syntax.md) and [simple and rich integration examples](docs/integration.md). The [documentation index](docs/README.md) links to precise API, preservation, playground, verification and publication guidance.
 
-Scope and release status live in the [InkKit Project](https://github.com/users/aicayzer/projects/3) and [version milestones](https://github.com/aicayzer/inkkit/milestones). Planned search, viewport and media extensions are tracked there; they are not capabilities of this candidate.
+Scope and release status live in the [InkKit Project](https://github.com/users/aicayzer/projects/3) and [version milestones](https://github.com/aicayzer/inkkit/milestones). Optional media extensions are tracked there. Only documented, released features form the supported package contract.
 
 MIT licensed. InkKit builds on the public PadPad and Memos editors; see [NOTICE](NOTICE).

package/dist/editor.d.ts

@@ -1,6 +1,6 @@
 import { type EditorLabels } from './labels.js';
 import { type TableCommand, type TableOptions } from './tables.js';
-import { type DocumentInput, type DocumentSnapshot, type ImageAdapter, type ClipboardInput, type ClipboardOutput, type PrintableDocument } from './types.js';
+import { type DocumentInput, type DocumentSnapshot, type ImageAdapter, type ClipboardInput, type ClipboardOutput, type PrintableDocument, type TextRange, type ReadableTextSnapshot, type TextRect, type ViewportOptions, type ViewportSnapshot } from './types.js';
 import { type Heading } from './outline.js';
 export type Mark = 'bold' | 'italic' | 'strikethrough' | 'highlight' | 'code' | 'link';
 export type Block = {
@@ -110,6 +110,10 @@ export declare class InkKitEditor {
     private generation;
     private reportingSuppressed;
     private loading;
+    private readonly textIdentity;
+    private textScope?;
+    private viewportContainer?;
+    private viewportInsets;
     private writable;
     private inputPreferences;
     private policyEpoch;
@@ -155,6 +159,22 @@ export declare class InkKitEditor {
     static mount(root: HTMLElement, events: EditorEvents, options?: EditorOptions): Promise<InkKitEditor>;
     loadDocument(input: DocumentInput): void;
     reloadDocument(input: DocumentInput): void;
+    setViewport(options: ViewportOptions): void;
+    viewport(): ViewportSnapshot;
+    private readableScope;
+    textSnapshot(expectedGeneration?: number): ReadableTextSnapshot;
+    private validateTextRange;
+    selectTextRange(range: TextRange, options?: {
+        focus?: boolean;
+        reveal?: boolean;
+    }): void;
+    replaceTextRange(range: TextRange, text: string): boolean;
+    textRangeRects(range: TextRange): readonly TextRect[];
+    visibleTextRanges(snapshotId: string): readonly TextRange[];
+    revealTextRange(range: TextRange): void;
+    private revealRects;
+    private revealCurrentSelection;
+    private revealLiteralSelection;
     private load;
     find(text: string, expectedGeneration?: number): void;
     replace(search: string, replacement: string, expectedGeneration?: number): boolean;

package/dist/editor.js

@@ -17,19 +17,20 @@ import { codeCopyPlugin, placeholderPlugin } from './decorations.js';
 import { labelsCtx, defaultLabels } from './labels.js';
 import { createDialect, stringifyOptions } from './dialect.js';
 import { Preservation } from './preserve.js';
-import { sourceAttribute, cleanSourceDoc, editedPlainSource, sourceSelection, revealSourceCaret, rawOffset, normalizedOffset, } from './source.js';
+import { sourceAttribute, cleanSourceDoc, editedPlainSource, sourceSelection, rawOffset, normalizedOffset, } from './source.js';
 import { normaliseLabel, referenceDefinitions, footnoteDefinitions, } from './references.js';
 import { selectionMarkdown, selectionContent, referenceMetadata, withReferenceMetadata, } from './reference-clipboard.js';
 import { imageView } from './images.js';
 import { tablePlugins, tableCommand, tableCommands, tableAvailability, tableContext, configureTableMovement, } from './tables.js';
 import { InkKitError, } from './types.js';
+import { readableProjection, projectionPosition, projectionOffset, validateOffsets, formattedRects, literalRects, literalVisibleRanges, intersectsViewport, textRect, } from './text-ranges.js';
 import { highlightPlugin } from './highlight.js';
 import { highlightKeymap, toggleHighlightCommand } from './inline-highlight.js';
 import { commentSelectionContent, setCommentVisibility } from './comments.js';
 import { PasteController } from './paste.js';
 import { selectionPlugin } from './selection.js';
 import { search, SearchQuery, setSearchState } from 'prosemirror-search';
-import { findFormatted, findLiteral, replaceFormatted, replaceLiteral, } from './search.js';
+import { findFormatted, findLiteral, replaceFormatted, replaceLiteral, replaceFormattedRange, } from './search.js';
 import { collectFormattedHeadings, collectSourceHeadings, navigateFormattedHeading, sourceHeadingPosition, } from './outline.js';
 import { taskListPlugin, toggleTaskList } from './tasks.js';
 import { isMermaid, mermaidPreview } from './mermaid.js';
@@ -239,6 +240,7 @@ function joinLists(tr, start, index) {
     if (before && after && isList(before) && after.type === before.type)
         tr.join($start.posAtIndex(index));
 }
+let editorSequence = 0;
 export class InkKitEditor {
     events;
     options;
@@ -270,6 +272,15 @@ export class InkKitEditor {
     generation = 0;
     reportingSuppressed = false;
     loading = false;
+    textIdentity = ++editorSequence;
+    textScope;
+    viewportContainer;
+    viewportInsets = {
+        top: 0,
+        right: 0,
+        bottom: 0,
+        left: 0,
+    };
     writable = true;
     inputPreferences = {};
     policyEpoch = 0;
@@ -300,7 +311,7 @@ export class InkKitEditor {
                         this.plain.value = markdown;
                     if (!this.plainComposing) {
                         this.plain.setSelectionRange(Math.min(from, this.plain.value.length), Math.min(to, this.plain.value.length));
-                        revealSourceCaret(this.plain);
+                        this.revealLiteralSelection();
                     }
                 }
                 if (markdown === this.lastMarkdown)
@@ -574,6 +585,12 @@ export class InkKitEditor {
             throw new RangeError('Editing mode must be source or formatted');
         if (this.formatType === 'txt' || this.mode === mode)
             return false;
+        const view = this.editor.ctx.get(editorViewCtx);
+        const focused = this.literalSurface
+            ? this.plain.ownerDocument.activeElement === this.plain
+            : view.hasFocus();
+        const container = this.viewportContainer ?? this.root;
+        const top = container.scrollTop, left = container.scrollLeft;
         const text = this.snapshot().text;
         this.mode = mode;
         this.outlineEpoch += 1;
@@ -591,6 +608,14 @@ export class InkKitEditor {
         finally {
             this.reportingSuppressed = suppressed;
         }
+        if (focused) {
+            if (this.literalSurface)
+                this.plain.focus({ preventScroll: true });
+            else
+                view.focus();
+        }
+        container.scrollTop = top;
+        container.scrollLeft = left;
         this.events.stateChanged(this.literalSurface
             ? { marks: [], block: { type: 'paragraph' }, quoted: false }
             : caretState(this.editor.ctx.get(editorViewCtx).state));
@@ -1013,11 +1038,13 @@ export class InkKitEditor {
             unbind(codeBlockKeymap);
             unbind(bulletListKeymap);
             unbind(orderedListKeymap);
-            // The caret is kept above the fade under the formatting bar.
             ctx.update(editorViewOptionsCtx, (options) => ({
                 ...options,
-                scrollThreshold: { top: 8, right: 0, bottom: 24, left: 0 },
-                scrollMargin: { top: 8, right: 0, bottom: 24, left: 0 },
+                handleScrollToSelection: () => {
+                    if (!instance.loading && instance.ready)
+                        instance.revealCurrentSelection();
+                    return true;
+                },
             }));
         })
             .use(labelsCtx)
@@ -1242,6 +1269,11 @@ export class InkKitEditor {
     }
     loadDocument(input) {
         this.assertAlive();
+        const container = this.viewportContainer ?? this.root;
+        const top = container.scrollTop, left = container.scrollLeft;
+        const focused = this.literalSurface
+            ? this.plain.ownerDocument.activeElement === this.plain
+            : this.editor.ctx.get(editorViewCtx).hasFocus();
         this.ready = false;
         this.pasteController.cancelPending();
         this.documentEpoch += 1;
@@ -1256,11 +1288,20 @@ export class InkKitEditor {
         this.formatType = input.format;
         this.revision = 0;
         this.plain.value = input.text;
+        this.plain.setSelectionRange(this.plain.value.length, this.plain.value.length);
         this.load(input.format === 'txt' ? '' : input.text, input.generation);
         this.originalSource = input.text;
         this.lastMarkdown = input.text;
         this.updateSurface();
         this.ready = true;
+        if (focused) {
+            if (this.literalSurface)
+                this.plain.focus({ preventScroll: true });
+            else
+                this.editor.ctx.get(editorViewCtx).focus();
+        }
+        container.scrollTop = top;
+        container.scrollLeft = left;
         this.events.stateChanged(this.literalSurface
             ? { marks: [], block: { type: 'paragraph' }, quoted: false }
             : caretState(this.editor.ctx.get(editorViewCtx).state));
@@ -1272,11 +1313,19 @@ export class InkKitEditor {
         const wasLiteral = this.literalSurface;
         const previousMode = this.editingMode;
         const previousFormat = this.formatType;
+        const selectedNode = !wasLiteral && view.state.selection instanceof NodeSelection
+            ? view.state.selection.node
+            : undefined;
         const at = wasLiteral
             ? this.plain.selectionStart
-            : view.state.selection.from;
-        const end = wasLiteral ? this.plain.selectionEnd : at;
-        const top = this.root.scrollTop;
+            : view.state.selection.anchor;
+        const end = wasLiteral ? this.plain.selectionEnd : view.state.selection.head;
+        const direction = this.plain.selectionDirection;
+        const container = this.viewportContainer ?? this.root;
+        const top = container.scrollTop, left = container.scrollLeft;
+        const focused = wasLiteral
+            ? document.activeElement === this.plain
+            : view.hasFocus();
         const plainTop = this.plain.scrollTop, plainLeft = this.plain.scrollLeft;
         this.reportingSuppressed = true;
         try {
@@ -1286,10 +1335,24 @@ export class InkKitEditor {
                 previousMode === 'source')
                 this.setEditingMode('source', input.generation);
             if (this.literalSurface)
-                this.plain.setSelectionRange(Math.min(at, this.plain.value.length), Math.min(end, this.plain.value.length));
-            else
-                view.dispatch(view.state.tr.setSelection(Selection.near(view.state.doc.resolve(Math.min(at, view.state.doc.content.size)))));
-            this.root.scrollTop = top;
+                this.plain.setSelectionRange(Math.min(at, this.plain.value.length), Math.min(end, this.plain.value.length), direction);
+            else {
+                const anchor = Math.min(at, view.state.doc.content.size);
+                const node = view.state.doc.nodeAt(anchor);
+                view.dispatch(view.state.tr.setSelection(selectedNode &&
+                    node?.type === selectedNode.type &&
+                    NodeSelection.isSelectable(node)
+                    ? NodeSelection.create(view.state.doc, anchor)
+                    : TextSelection.between(view.state.doc.resolve(anchor), view.state.doc.resolve(Math.min(end, view.state.doc.content.size)))));
+            }
+            if (focused) {
+                if (this.literalSurface)
+                    this.plain.focus({ preventScroll: true });
+                else
+                    view.focus();
+            }
+            container.scrollTop = top;
+            container.scrollLeft = left;
             if (wasLiteral && this.literalSurface) {
                 this.plain.scrollTop = plainTop;
                 this.plain.scrollLeft = plainLeft;
@@ -1300,6 +1363,301 @@ export class InkKitEditor {
             this.publishCommandState();
         }
     }
+    setViewport(options) {
+        this.assertAlive();
+        const container = options.scrollContainer ?? this.root;
+        if (container !== this.root && !container.contains(this.root))
+            throw new RangeError('The scroll container must be the editor root or an ancestor');
+        const insets = { top: 0, right: 0, bottom: 0, left: 0, ...options.insets };
+        if (Object.values(insets).some((value) => !Number.isFinite(value) || value < 0))
+            throw new RangeError('Viewport insets must be finite non-negative CSS pixel values');
+        this.viewportContainer = container;
+        this.viewportInsets = insets;
+    }
+    viewport() {
+        this.assertAlive();
+        const container = this.viewportContainer ?? this.root;
+        const bounds = container.getBoundingClientRect();
+        const root = this.root.getBoundingClientRect();
+        const insets = this.viewportInsets;
+        const window = this.root.ownerDocument.defaultView;
+        const left = Math.max(bounds.left + container.clientLeft, root.left, 0);
+        const top = Math.max(bounds.top + container.clientTop, root.top, 0);
+        const right = Math.max(left, Math.min(bounds.left + container.clientLeft + container.clientWidth, root.right, window.innerWidth));
+        const bottom = Math.max(top, Math.min(bounds.top + container.clientTop + container.clientHeight, root.bottom, window.innerHeight));
+        let rect = textRect({ left, top, right, bottom });
+        if (this.literalSurface) {
+            const plain = this.plain.getBoundingClientRect();
+            const literalLeft = Math.max(rect.left, plain.left + this.plain.clientLeft);
+            const literalTop = Math.max(rect.top, plain.top + this.plain.clientTop);
+            rect = textRect({
+                left: literalLeft,
+                top: literalTop,
+                right: Math.max(literalLeft, Math.min(rect.right, plain.left + this.plain.clientLeft + this.plain.clientWidth)),
+                bottom: Math.max(literalTop, Math.min(rect.bottom, plain.top + this.plain.clientTop + this.plain.clientHeight)),
+            });
+        }
+        const insetLeft = Math.min(rect.right, rect.left + insets.left);
+        const insetTop = Math.min(rect.bottom, rect.top + insets.top);
+        rect = textRect({
+            left: insetLeft,
+            top: insetTop,
+            right: Math.max(insetLeft, rect.right - insets.right),
+            bottom: Math.max(insetTop, rect.bottom - insets.bottom),
+        });
+        return Object.freeze({
+            rect: Object.freeze(rect),
+            insets: Object.freeze({ ...insets }),
+            scrollTop: container.scrollTop + (this.literalSurface ? this.plain.scrollTop : 0),
+            scrollLeft: container.scrollLeft +
+                (this.literalSurface ? this.plain.scrollLeft : 0),
+        });
+    }
+    readableScope() {
+        const key = `${this.documentEpoch}:${this.revision}:${this.outlineEpoch}:${this.editingMode}`;
+        if (this.textScope?.key !== key)
+            this.textScope = {
+                key,
+                id: `${this.textIdentity}:${key}`,
+                projection: this.literalSurface
+                    ? { text: this.plain.value, spans: [] }
+                    : readableProjection(this.editor.ctx.get(editorViewCtx).state.doc),
+            };
+        return this.textScope;
+    }
+    textSnapshot(expectedGeneration) {
+        this.assertCurrent(expectedGeneration);
+        const scope = this.readableScope();
+        const selection = this.editor.ctx.get(editorViewCtx).state.selection;
+        return Object.freeze({
+            snapshotId: scope.id,
+            documentId: this.documentId,
+            generation: this.generation,
+            revision: this.revision,
+            format: this.formatType,
+            mode: this.editingMode,
+            text: scope.projection.text,
+            selection: Object.freeze({
+                snapshotId: scope.id,
+                from: this.literalSurface
+                    ? this.plain.selectionStart
+                    : projectionOffset(scope.projection, selection.from),
+                to: this.literalSurface
+                    ? this.plain.selectionEnd
+                    : projectionOffset(scope.projection, selection.to),
+            }),
+        });
+    }
+    validateTextRange(range) {
+        this.assertCurrent();
+        const scope = this.readableScope();
+        if (range.snapshotId !== scope.id)
+            throw new InkKitError('stale-document', 'The readable text snapshot changed');
+        validateOffsets(scope.projection.text, range.from, range.to);
+        return scope.projection;
+    }
+    selectTextRange(range, options = {}) {
+        const projection = this.validateTextRange(range);
+        if (this.literalSurface)
+            this.plain.setSelectionRange(range.from, range.to);
+        else {
+            for (const span of projection.spans)
+                if (span.kind === 'embed' &&
+                    ((range.from > span.from && range.from < span.to) ||
+                        (range.to > span.from && range.to < span.to)))
+                    throw new InkKitError('invalid-range', 'Embedded labels must be selected as complete ranges');
+            const view = this.editor.ctx.get(editorViewCtx);
+            const from = projectionPosition(projection, range.from, 1);
+            const to = projectionPosition(projection, range.to, range.from === range.to ? 1 : -1);
+            const embed = projection.spans.find((span) => span.kind === 'embed' &&
+                span.from === range.from &&
+                span.to === range.to);
+            view.dispatch(view.state.tr.setSelection(embed && view.state.doc.nodeAt(embed.start)
+                ? NodeSelection.create(view.state.doc, embed.start)
+                : TextSelection.between(view.state.doc.resolve(from), view.state.doc.resolve(to))));
+        }
+        if (options.focus) {
+            if (this.literalSurface)
+                this.plain.focus({ preventScroll: true });
+            else
+                this.editor.ctx.get(editorViewCtx).focus();
+        }
+        if (options.reveal)
+            this.revealTextRange(range);
+        this.publishCommandState();
+    }
+    replaceTextRange(range, text) {
+        const projection = this.validateTextRange(range);
+        this.assertMutation();
+        if (typeof text !== 'string')
+            throw new TypeError('Replacement must be a string');
+        if (this.literalSurface) {
+            const raw = this.currentText();
+            const from = rawOffset(raw, range.from), to = rawOffset(raw, range.to);
+            const ending = /\r\n|\r|\n/.exec(raw)?.[0] ?? '\n';
+            const value = text.replace(/\r\n?/g, '\n');
+            const replaced = raw.slice(0, from) + value.replaceAll('\n', ending) + raw.slice(to);
+            return this.applySource(replaced, true, range.from, range.from + value.length);
+        }
+        if (projection.spans.some((span) => (span.kind === 'embed' &&
+            range.from > span.from &&
+            range.from < span.to) ||
+            (span.kind === 'embed' &&
+                range.to > span.from &&
+                range.to < span.to) ||
+            (span.to > range.from &&
+                span.from < range.to &&
+                span.kind !== 'text')))
+            throw new InkKitError('invalid-range', 'Replacement cannot remove embedded content or structural separators');
+        const from = projectionPosition(projection, range.from, 1);
+        const to = projectionPosition(projection, range.to, range.from === range.to ? 1 : -1);
+        return replaceFormattedRange(this.editor.ctx.get(editorViewCtx), from, to, text, (doc) => {
+            this.currentText(doc);
+        });
+    }
+    textRangeRects(range) {
+        const projection = this.validateTextRange(range);
+        const rects = this.literalSurface
+            ? literalRects(this.plain, range.from, range.to)
+            : formattedRects(this.editor.ctx.get(editorViewCtx), projection, range.from, range.to);
+        return Object.freeze(rects.map((rect) => Object.freeze(rect)));
+    }
+    visibleTextRanges(snapshotId) {
+        const snapshot = this.textSnapshot();
+        this.validateTextRange({ snapshotId, from: 0, to: 0 });
+        const viewport = this.viewport().rect;
+        if (this.literalSurface)
+            return Object.freeze(literalVisibleRanges(this.plain, viewport).map((range) => Object.freeze({ snapshotId, ...range })));
+        const visible = (rect) => intersectsViewport(rect, viewport);
+        const ranges = [];
+        const projection = this.readableScope().projection;
+        const view = this.editor.ctx.get(editorViewCtx);
+        for (const span of projection.spans) {
+            const current = { text: projection.text, spans: [span] };
+            if (span.kind === 'separator' ||
+                !formattedRects(view, current, span.from, span.to).some(visible))
+                continue;
+            for (let from = span.from; from < span.to;) {
+                const to = from + (snapshot.text.codePointAt(from) > 0xffff ? 2 : 1);
+                if (formattedRects(view, current, from, to).some(visible)) {
+                    const previous = ranges.at(-1);
+                    if (previous?.to === from)
+                        previous.to = to;
+                    else
+                        ranges.push({ snapshotId, from, to });
+                }
+                from = to;
+            }
+        }
+        return Object.freeze(ranges.map((range) => Object.freeze(range)));
+    }
+    revealTextRange(range) {
+        const projection = this.validateTextRange(range);
+        if (!this.literalSurface) {
+            const view = this.editor.ctx.get(editorViewCtx);
+            const position = projectionPosition(projection, range.from, 1);
+            const at = view.domAtPos(position).node;
+            let element = at instanceof Element ? at : at.parentElement;
+            while (element && this.root.contains(element)) {
+                if (element.matches('.inkkit-callout[data-inkkit-folded="true"]'))
+                    element
+                        .querySelector(':scope > .inkkit-callout-header [data-inkkit-callout-toggle]')
+                        ?.click();
+                element = element.parentElement;
+            }
+        }
+        this.revealRects(this.textRangeRects(range));
+    }
+    revealRects(rects) {
+        if (!rects.length)
+            return;
+        const viewport = this.viewport().rect;
+        const leading = rects[0];
+        const envelope = {
+            top: leading.top,
+            bottom: leading.bottom,
+            left: leading.left,
+            right: leading.right,
+        };
+        for (const rect of rects) {
+            envelope.top = Math.min(envelope.top, rect.top);
+            envelope.bottom = Math.max(envelope.bottom, rect.bottom);
+            envelope.left = Math.min(envelope.left, rect.left);
+            envelope.right = Math.max(envelope.right, rect.right);
+        }
+        const fitsHeight = envelope.bottom - envelope.top <= viewport.height;
+        const fitsWidth = envelope.right - envelope.left <= viewport.width;
+        const rect = {
+            top: fitsHeight ? envelope.top : leading.top,
+            bottom: fitsHeight
+                ? envelope.bottom
+                : Math.min(leading.bottom, leading.top + viewport.height),
+            left: fitsWidth ? envelope.left : leading.left,
+            right: fitsWidth
+                ? envelope.right
+                : Math.min(leading.right, leading.left + viewport.width),
+        };
+        const vertical = viewport.height <= 0
+            ? 0
+            : rect.top < viewport.top
+                ? rect.top - viewport.top
+                : rect.bottom > viewport.bottom
+                    ? rect.bottom - viewport.bottom
+                    : 0;
+        const horizontal = viewport.width <= 0
+            ? 0
+            : rect.left < viewport.left
+                ? rect.left - viewport.left
+                : rect.right > viewport.right
+                    ? rect.right - viewport.right
+                    : 0;
+        let remainingTop = vertical, remainingLeft = horizontal;
+        if (this.literalSurface) {
+            const top = this.plain.scrollTop, left = this.plain.scrollLeft;
+            this.plain.scrollTop += vertical;
+            this.plain.scrollLeft += horizontal;
+            remainingTop -= this.plain.scrollTop - top;
+            remainingLeft -= this.plain.scrollLeft - left;
+        }
+        let container = this.viewportContainer ?? this.root;
+        const document = this.root.ownerDocument;
+        while (container &&
+            container !== document.body &&
+            container !== document.documentElement) {
+            const top = container.scrollTop, left = container.scrollLeft;
+            container.scrollTop += remainingTop;
+            container.scrollLeft += remainingLeft;
+            remainingTop -= container.scrollTop - top;
+            remainingLeft -= container.scrollLeft - left;
+            container = container.parentElement;
+        }
+        if (remainingTop || remainingLeft)
+            document.defaultView.scrollBy(remainingLeft, remainingTop);
+    }
+    revealCurrentSelection() {
+        if (this.loading || !this.ready)
+            return;
+        if (this.literalSurface) {
+            this.revealLiteralSelection();
+            return;
+        }
+        const view = this.editor.ctx.get(editorViewCtx);
+        const projection = this.readableScope().projection;
+        const from = projectionOffset(projection, view.state.selection.from);
+        const to = projectionOffset(projection, view.state.selection.to);
+        if (this.composing || this.pasteController.pending) {
+            this.revealRects(formattedRects(view, projection, from, to));
+            return;
+        }
+        this.revealTextRange({
+            snapshotId: this.readableScope().id,
+            from,
+            to,
+        });
+    }
+    revealLiteralSelection() {
+        this.revealRects(literalRects(this.plain, this.plain.selectionStart, this.plain.selectionEnd));
+    }
     load(markdown, generation) {
         this.generation = generation;
         this.originalSource = markdown;
@@ -1319,7 +1677,7 @@ export class InkKitEditor {
         const { doc } = view.state;
         const end = Selection.findFrom(doc.resolve(doc.content.size), -1, true) ??
             Selection.atEnd(doc);
-        view.dispatch(setSearchState(view.state.tr.setSelection(end).scrollIntoView(), new SearchQuery({ search: '' })));
+        view.dispatch(setSearchState(view.state.tr.setSelection(end), new SearchQuery({ search: '' })));
     }
     find(text, expectedGeneration) {
         this.assertCurrent(expectedGeneration);
@@ -1349,10 +1707,11 @@ export class InkKitEditor {
             else if (this.plainSearch)
                 this.plain.setSelectionRange(this.plain.selectionEnd, this.plain.selectionEnd);
             this.plainSearch = text;
-            revealSourceCaret(this.plain);
+            this.revealLiteralSelection();
             return;
         }
-        findFormatted(this.editor.ctx.get(editorViewCtx), text);
+        if (findFormatted(this.editor.ctx.get(editorViewCtx), text))
+            this.revealCurrentSelection();
     }
     replace(search, replacement, expectedGeneration) {
         this.assertMutation(expectedGeneration);
@@ -1417,7 +1776,7 @@ export class InkKitEditor {
             const position = sourceHeadingPosition(this.editor.ctx, this.plain.value, heading, this.outlineContext());
             this.plain.setSelectionRange(position, position);
             this.plain.focus({ preventScroll: true });
-            revealSourceCaret(this.plain);
+            this.revealLiteralSelection();
             return true;
         }
         return navigateFormattedHeading(this.editor.ctx.get(editorViewCtx), heading, this.outlineContext());

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export type { EditorEvents, EditorOptions, TextInputPreferences, CommandState, E
 export type { TableCommand, TableOptions } from './tables.js';
 export type { Heading } from './outline.js';
 export { InkKitError } from './types.js';
-export type { DocumentFormat, DocumentContext, DocumentInput, DocumentSnapshot, EditorErrorCode, ImageAdapter, CapturedImage, PortableImage, ClipboardInput, ClipboardOutput, ClipboardImage, ClipboardDiagram, PrintableDocument, PrintableWarning, } from './types.js';
+export type { DocumentFormat, DocumentContext, DocumentInput, DocumentSnapshot, EditorErrorCode, ImageAdapter, CapturedImage, PortableImage, ClipboardInput, ClipboardOutput, ClipboardImage, ClipboardDiagram, PrintableDocument, PrintableWarning, TextRange, ReadableTextSnapshot, TextRect, ViewportInsets, ViewportOptions, ViewportSnapshot, } from './types.js';
 export type { EditorLabels } from './labels.js';

package/dist/search.d.ts

@@ -10,5 +10,6 @@ export interface LiteralReplacement extends TextMatch {
 }
 export declare function findLiteral(text: string, search: string, from?: number): TextMatch | undefined;
 export declare function replaceLiteral(text: string, search: string, replacement: string, selection: TextMatch, all?: boolean): LiteralReplacement;
-export declare function findFormatted(view: EditorView, text: string): void;
+export declare function findFormatted(view: EditorView, text: string): boolean;
 export declare function replaceFormatted(view: EditorView, search: string, replacement: string, preflight: (doc: ProseNode) => void, all?: boolean): number;
+export declare function replaceFormattedRange(view: EditorView, from: number, to: number, replacement: string, preflight: (doc: ProseNode) => void): boolean;

package/dist/search.js

@@ -1,6 +1,6 @@
 import { Fragment, Slice } from '@milkdown/kit/prose/model';
 import { closeHistory } from '@milkdown/kit/prose/history';
-import { Selection, TextSelection } from '@milkdown/kit/prose/state';
+import { Selection, TextSelection, } from '@milkdown/kit/prose/state';
 import { SearchQuery, setSearchState, getSearchState } from 'prosemirror-search';
 import { InkKitError } from './types.js';
 function escapedPattern(text) {
@@ -82,21 +82,44 @@ export function findFormatted(view, text) {
     const query = formattedQuery(text);
     const previous = getSearchState(view.state)?.query.search;
     let tr = setSearchState(view.state.tr, query);
+    let found = false;
     if (text) {
         const start = previous === query.search
             ? view.state.selection.to
             : view.state.selection.from;
         const match = query.findNext(view.state, start) ?? query.findNext(view.state, 0);
-        if (match)
+        if (match) {
+            found = true;
             tr = tr
                 .setSelection(TextSelection.create(tr.doc, match.from, match.to))
                 .scrollIntoView();
+        }
         else
             tr = tr.setSelection(Selection.near(view.state.selection.$to));
     }
     else if (previous)
         tr = tr.setSelection(Selection.near(view.state.selection.$to));
     view.dispatch(tr);
+    return found;
+}
+function replacementSlice(state, from, to, value) {
+    const start = state.doc.resolve(from), end = state.doc.resolve(to);
+    const marks = start.marksAcross(end) ?? start.marks();
+    const nodes = [];
+    if (start.parent.type.spec.code) {
+        if (value)
+            nodes.push(state.schema.text(value, marks));
+    }
+    else {
+        const lines = value.split('\n');
+        lines.forEach((line, index) => {
+            if (index)
+                nodes.push(state.schema.nodes.hardbreak.create({ isHTML: index === lines.length - 1 && line === '' }, null, marks));
+            if (line)
+                nodes.push(state.schema.text(line, marks));
+        });
+    }
+    return new Slice(Fragment.fromArray(nodes), 0, 0);
 }
 export function replaceFormatted(view, search, replacement, preflight, all = false) {
     if (!search)
@@ -132,26 +155,7 @@ export function replaceFormatted(view, search, replacement, preflight, all = fal
         return 0;
     let tr = setSearchState(state.tr, query);
     for (const match of [...changed].reverse()) {
-        const from = state.doc.resolve(match.from);
-        const to = state.doc.resolve(match.to);
-        const marks = from.marksAcross(to) ?? from.marks();
-        let content = Fragment.empty;
-        if (from.parent.type.spec.code) {
-            if (value)
-                content = Fragment.from(state.schema.text(value, marks));
-        }
-        else {
-            const nodes = [];
-            const lines = value.split('\n');
-            lines.forEach((line, index) => {
-                if (index)
-                    nodes.push(state.schema.nodes.hardbreak.create({ isHTML: index === lines.length - 1 && line === '' }, null, marks));
-                if (line)
-                    nodes.push(state.schema.text(line, marks));
-            });
-            content = Fragment.fromArray(nodes);
-        }
-        tr.replace(match.from, match.to, new Slice(content, 0, 0));
+        tr.replace(match.from, match.to, replacementSlice(state, match.from, match.to, value));
     }
     if (!all) {
         const match = changed[0];
@@ -169,3 +173,30 @@ export function replaceFormatted(view, search, replacement, preflight, all = fal
     view.dispatch(closeHistory(view.state.tr).setMeta('addToHistory', false));
     return changed.length;
 }
+export function replaceFormattedRange(view, from, to, replacement, preflight) {
+    const start = view.state.doc.resolve(from);
+    const end = view.state.doc.resolve(to);
+    let textOnly = start.parent === end.parent && start.parent.inlineContent;
+    view.state.doc.nodesBetween(from, to, (node) => {
+        if (!node.isText && !node.isTextblock)
+            textOnly = false;
+    });
+    if (!textOnly)
+        throw new InkKitError('invalid-range', 'Replacement requires literal text within one block');
+    const value = replacement.replace(/\r\n?/g, '\n');
+    if (view.state.doc.textBetween(from, to) === value)
+        return false;
+    const tr = closeHistory(view.state.tr.replace(from, to, replacementSlice(view.state, from, to, value)));
+    tr.setSelection(TextSelection.create(tr.doc, from, tr.mapping.map(to, 1)));
+    try {
+        preflight(tr.doc);
+    }
+    catch (error) {
+        if (error instanceof InkKitError)
+            throw error;
+        throw new InkKitError('preservation', error instanceof Error ? error.message : 'Cannot preserve replacement');
+    }
+    view.dispatch(tr);
+    view.dispatch(closeHistory(view.state.tr).setMeta('addToHistory', false));
+    return true;
+}

package/dist/source.d.ts

@@ -14,4 +14,3 @@ export declare function sourceSelection(source: string, start: number, end: numb
     markdown: string;
     shareable: string;
 };
-export declare function revealSourceCaret(plain: HTMLTextAreaElement): void;

package/dist/source.js

@@ -55,63 +55,3 @@ export function sourceSelection(source, start, end) {
     shareable += source.slice(cursor, to);
     return { markdown: source.slice(from, to), shareable };
 }
-export function revealSourceCaret(plain) {
-    if (!plain.clientWidth || !plain.clientHeight)
-        return;
-    const document = plain.ownerDocument;
-    const style = document.defaultView.getComputedStyle(plain);
-    const mirror = document.createElement('div');
-    for (const property of [
-        'font',
-        'font-family',
-        'font-size',
-        'font-weight',
-        'font-style',
-        'font-stretch',
-        'font-variant',
-        'line-height',
-        'letter-spacing',
-        'word-spacing',
-        'tab-size',
-        'padding',
-        'text-indent',
-        'text-transform',
-        'direction',
-        'word-break',
-    ])
-        mirror.style.setProperty(property, style.getPropertyValue(property));
-    Object.assign(mirror.style, {
-        position: 'fixed',
-        visibility: 'hidden',
-        left: '-10000px',
-        top: '0',
-        width: `${plain.clientWidth}px`,
-        boxSizing: 'border-box',
-        whiteSpace: plain.wrap === 'off' ? 'pre' : 'pre-wrap',
-        overflowWrap: plain.wrap === 'off' ? 'normal' : 'break-word',
-    });
-    mirror.setAttribute('aria-hidden', 'true');
-    const caret = document.createElement('span');
-    caret.setAttribute('data-inkkit-source-caret', '');
-    caret.textContent = plain.value.slice(plain.selectionStart) || '\u200b';
-    mirror.append(document.createTextNode(plain.value.slice(0, plain.selectionStart)), caret);
-    document.body.append(mirror);
-    try {
-        // Textareas expose selection offsets but no caret geometry; matching their layout also accounts for wrapped lines.
-        const rect = caret.getClientRects()[0] ?? caret.getBoundingClientRect();
-        const top = rect.top - mirror.getBoundingClientRect().top;
-        const lineHeight = Math.max(rect.height, Number.parseFloat(style.lineHeight) || rect.height);
-        const insetTop = Number.parseFloat(style.paddingTop) || 0;
-        const insetBottom = Number.parseFloat(style.paddingBottom) || 0;
-        if (plain.selectionStart === 0)
-            plain.scrollTop = 0;
-        else if (top < plain.scrollTop + insetTop)
-            plain.scrollTop = Math.max(0, top - insetTop);
-        else if (top + lineHeight >
-            plain.scrollTop + plain.clientHeight - insetBottom)
-            plain.scrollTop = Math.max(0, top + lineHeight - plain.clientHeight + insetBottom);
-    }
-    finally {
-        mirror.remove();
-    }
-}

package/dist/text-ranges.d.ts

@@ -0,0 +1,26 @@
+import type { Node as ProseNode } from '@milkdown/kit/prose/model';
+import type { EditorView } from '@milkdown/kit/prose/view';
+import { type TextRect } from './types.js';
+export interface TextSpan {
+    from: number;
+    to: number;
+    start: number;
+    end: number;
+    kind: 'text' | 'break' | 'embed' | 'separator';
+}
+export interface TextProjection {
+    text: string;
+    spans: TextSpan[];
+}
+export declare function readableProjection(doc: ProseNode): TextProjection;
+export declare function projectionPosition(projection: TextProjection, offset: number, side: -1 | 1): number;
+export declare function projectionOffset(projection: TextProjection, position: number): number;
+export declare function validateOffsets(text: string, from: number, to: number): void;
+export declare function textRect(rect: Pick<TextRect, 'left' | 'top' | 'right' | 'bottom'>): TextRect;
+export declare function formattedRects(view: EditorView, projection: TextProjection, from: number, to: number): TextRect[];
+export declare function literalRects(plain: HTMLTextAreaElement, from: number, to: number): TextRect[];
+export declare function intersectsViewport(rect: Pick<TextRect, 'top' | 'right' | 'bottom' | 'left'>, viewport: TextRect): boolean;
+export declare function literalVisibleRanges(plain: HTMLTextAreaElement, viewport: TextRect): {
+    from: number;
+    to: number;
+}[];

package/dist/text-ranges.js

@@ -0,0 +1,228 @@
+import { InkKitError } from './types.js';
+export function readableProjection(doc) {
+    const result = { text: '', spans: [] };
+    let blocks = 0;
+    const append = (text, start, end, kind) => {
+        const from = result.text.length;
+        result.text += text;
+        result.spans.push({ from, to: result.text.length, start, end, kind });
+    };
+    const block = (start) => {
+        if (blocks++)
+            append('\n', result.spans.at(-1)?.end ?? start, start, 'separator');
+    };
+    doc.descendants((node, position) => {
+        const name = node.type.name;
+        if (name === 'comment_inline' ||
+            name === 'comment_block' ||
+            name === 'reference_definition')
+            return false;
+        if (name === 'inkkit_callout') {
+            block(position);
+            append(node.attrs.title ||
+                String(node.attrs.kind).replace(/^./, (value) => value.toUpperCase()), position, position + 1, 'embed');
+            return true;
+        }
+        if (node.isTextblock) {
+            block(position + 1);
+            if (!node.content.size)
+                append('', position + 1, position + 1, 'text');
+            return true;
+        }
+        if (node.isText) {
+            append(node.text ?? '', position, position + node.nodeSize, 'text');
+            return false;
+        }
+        if (name === 'hardbreak' || name === 'hard_break') {
+            append('\n', position, position + node.nodeSize, 'break');
+            return false;
+        }
+        if (name === 'image' || name === 'footnote_reference') {
+            append(name === 'image'
+                ? String(node.attrs.alt ?? '').replace(/\|\d{1,5}$/, '') || 'Image'
+                : `[${node.attrs.label}]`, position, position + node.nodeSize, 'embed');
+            return false;
+        }
+        return true;
+    });
+    return result;
+}
+export function projectionPosition(projection, offset, side) {
+    const spans = projection.spans;
+    const span = spans.find((span) => (offset > span.from && offset < span.to) ||
+        (side > 0 ? offset === span.from : offset === span.to)) ?? (side > 0 ? spans.at(-1) : spans[0]);
+    if (!span)
+        return 0;
+    if (span.kind === 'text')
+        return (span.start +
+            Math.max(0, Math.min(offset - span.from, span.to - span.from)));
+    return offset <= span.from ? span.start : span.end;
+}
+export function projectionOffset(projection, position) {
+    for (const span of projection.spans) {
+        if (position < span.start)
+            return span.from;
+        if (position <= span.end)
+            return span.kind === 'text'
+                ? span.from + Math.max(0, position - span.start)
+                : position === span.start
+                    ? span.from
+                    : span.to;
+    }
+    return projection.text.length;
+}
+export function validateOffsets(text, from, to) {
+    const split = (offset) => offset > 0 &&
+        offset < text.length &&
+        /[\uD800-\uDBFF]/.test(text[offset - 1]) &&
+        /[\uDC00-\uDFFF]/.test(text[offset]);
+    if (!Number.isInteger(from) ||
+        !Number.isInteger(to) ||
+        from < 0 ||
+        to < from ||
+        to > text.length ||
+        split(from) ||
+        split(to))
+        throw new InkKitError('invalid-range', 'Range must use valid UTF-16 boundaries in the text snapshot');
+}
+export function textRect(rect) {
+    return {
+        left: rect.left,
+        top: rect.top,
+        right: rect.right,
+        bottom: rect.bottom,
+        width: Math.max(0, rect.right - rect.left),
+        height: Math.max(0, rect.bottom - rect.top),
+    };
+}
+export function formattedRects(view, projection, from, to) {
+    if (from === to) {
+        const position = projectionPosition(projection, from, 1);
+        const dom = view.domAtPos(position);
+        const element = dom.node.nodeType === 1 ? dom.node : dom.node.parentElement;
+        if (!element?.getClientRects().length)
+            return [];
+        return [textRect(view.coordsAtPos(position))];
+    }
+    const rects = [];
+    for (const span of projection.spans) {
+        if (span.to <= from || span.from >= to || span.kind === 'separator')
+            continue;
+        if (span.kind === 'embed' || span.kind === 'break') {
+            const node = view.nodeDOM(span.start);
+            if (node instanceof Element) {
+                const label = node.matches('.inkkit-callout')
+                    ? (node.querySelector(':scope > .inkkit-callout-header > .inkkit-callout-title') ?? node)
+                    : node;
+                rects.push(...Array.from(label.getClientRects(), textRect));
+            }
+            continue;
+        }
+        const start = view.domAtPos(span.start + Math.max(0, from - span.from), 1);
+        const end = view.domAtPos(span.start + Math.min(span.to - span.from, to - span.from), -1);
+        const range = view.dom.ownerDocument.createRange();
+        range.setStart(start.node, start.offset);
+        range.setEnd(end.node, end.offset);
+        rects.push(...Array.from(range.getClientRects(), textRect));
+    }
+    return rects.filter((rect) => rect.height > 0 && rect.width >= 0);
+}
+function withLiteralLayout(plain, measure) {
+    if (!plain.clientWidth || !plain.clientHeight)
+        return undefined;
+    const document = plain.ownerDocument;
+    const style = document.defaultView.getComputedStyle(plain);
+    const mirror = document.createElement('div');
+    for (const property of [
+        'font',
+        'font-family',
+        'font-size',
+        'font-weight',
+        'font-style',
+        'font-stretch',
+        'font-variant',
+        'line-height',
+        'letter-spacing',
+        'word-spacing',
+        'tab-size',
+        'padding',
+        'text-indent',
+        'text-transform',
+        'direction',
+        'word-break',
+    ])
+        mirror.style.setProperty(property, style.getPropertyValue(property));
+    const origin = plain.getBoundingClientRect();
+    Object.assign(mirror.style, {
+        position: 'fixed',
+        visibility: 'hidden',
+        pointerEvents: 'none',
+        left: `${origin.left + plain.clientLeft - plain.scrollLeft}px`,
+        top: `${origin.top + plain.clientTop - plain.scrollTop}px`,
+        width: `${plain.clientWidth}px`,
+        boxSizing: 'border-box',
+        whiteSpace: plain.wrap === 'off' ? 'pre' : 'pre-wrap',
+        overflowWrap: plain.wrap === 'off' ? 'normal' : 'break-word',
+    });
+    mirror.setAttribute('aria-hidden', 'true');
+    const text = document.createTextNode(plain.value + '\u200b');
+    mirror.append(text);
+    document.body.append(mirror);
+    try {
+        return measure(text);
+    }
+    finally {
+        mirror.remove();
+    }
+}
+export function literalRects(plain, from, to) {
+    return (withLiteralLayout(plain, (text) => {
+        const range = plain.ownerDocument.createRange();
+        range.setStart(text, from);
+        range.setEnd(text, from === to ? Math.min(to + 1, text.length) : to);
+        return Array.from(range.getClientRects(), (rect) => textRect({
+            left: rect.left,
+            right: from === to ? rect.left : rect.right,
+            top: rect.top,
+            bottom: rect.bottom,
+        }));
+    }) ?? []);
+}
+export function intersectsViewport(rect, viewport) {
+    return (viewport.width > 0 &&
+        viewport.height > 0 &&
+        rect.bottom > viewport.top &&
+        rect.top < viewport.bottom &&
+        rect.right >= viewport.left &&
+        rect.left < viewport.right);
+}
+export function literalVisibleRanges(plain, viewport) {
+    return (withLiteralLayout(plain, (text) => {
+        const range = plain.ownerDocument.createRange();
+        const ranges = [];
+        const visible = (from, to) => {
+            range.setStart(text, from);
+            range.setEnd(text, to);
+            return Array.from(range.getClientRects()).some((rect) => intersectsViewport(rect, viewport));
+        };
+        for (let start = 0; start < plain.value.length;) {
+            const newline = plain.value.indexOf('\n', start);
+            const end = newline < 0 ? plain.value.length : newline + 1;
+            if (visible(start, end)) {
+                for (let from = start; from < end;) {
+                    const to = from + (plain.value.codePointAt(from) > 0xffff ? 2 : 1);
+                    if (visible(from, to)) {
+                        const previous = ranges.at(-1);
+                        if (previous?.to === from)
+                            previous.to = to;
+                        else
+                            ranges.push({ from, to });
+                    }
+                    from = to;
+                }
+            }
+            start = end;
+        }
+        return ranges;
+    }) ?? []);
+}

package/dist/types.d.ts

@@ -14,7 +14,7 @@ export interface DocumentSnapshot extends DocumentInput {
     revision: number;
     dirty: boolean;
 }
-export type EditorErrorCode = 'not-ready' | 'stale-document' | 'composition' | 'read-only' | 'operation-pending' | 'destroyed' | 'preservation' | 'image-unavailable' | 'diagram-unavailable';
+export type EditorErrorCode = 'not-ready' | 'stale-document' | 'composition' | 'read-only' | 'operation-pending' | 'destroyed' | 'preservation' | 'image-unavailable' | 'diagram-unavailable' | 'invalid-range';
 export declare class InkKitError extends Error {
     readonly code: EditorErrorCode;
     constructor(code: EditorErrorCode, message: string);
@@ -78,3 +78,42 @@ export interface PrintableDocument {
     assets: readonly PortableImage[];
     warnings: readonly PrintableWarning[];
 }
+export interface TextRange {
+    snapshotId: string;
+    from: number;
+    to: number;
+}
+export interface ReadableTextSnapshot {
+    snapshotId: string;
+    documentId: string;
+    generation: number;
+    revision: number;
+    format: DocumentFormat;
+    mode: 'source' | 'formatted';
+    text: string;
+    selection: TextRange;
+}
+export interface TextRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+export interface ViewportInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export interface ViewportOptions {
+    scrollContainer?: HTMLElement;
+    insets?: Partial<ViewportInsets>;
+}
+export interface ViewportSnapshot {
+    rect: TextRect;
+    insets: ViewportInsets;
+    scrollTop: number;
+    scrollLeft: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicayzer/inkkit",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "A preserving Markdown editor for offline web views and the web",
   "license": "MIT",
   "type": "module",