blots-editor 0.0.6 → 0.0.8

package/dist/core/document/document.d.ts

@@ -0,0 +1,65 @@
+import type { CursorState } from "./position.js";
+export type DocumentOptions = {
+    indentWidth?: number;
+};
+/**
+ * Document model: array of lines + cursor + scroll state.
+ *
+ * Pure data and behavior: no React/Ink awareness, and no change
+ * notifications — `EditorController` owns those. The cursor stores only
+ * `{line, logical}`; `visual` is derived (see {@link CursorState}), so
+ * "logical column" and "display column" cannot diverge by construction.
+ *
+ * The document always has at least one line (empty document = one empty
+ * line), matching the result of `"".split(/\r?\n/)`.
+ */
+export declare class Document {
+    private _lines;
+    private _cursor;
+    private _scrollTop;
+    readonly indentWidth: number;
+    constructor(text: string, options?: DocumentOptions);
+    get lineCount(): number;
+    /** Snapshot of all line texts (for rendering; internally the model is `TextLine[]`). */
+    get lines(): string[];
+    getLine(i: number): string;
+    get cursor(): CursorState;
+    get scrollTop(): number;
+    /** Gutter width = decimal digit count of the last line number (at least 1). */
+    getLineNumberWidth(): number;
+    setLine(i: number, text: string): void;
+    /** Insert a line at index `i` (0 <= i <= lineCount), shifting the rest down. */
+    insertLineAt(i: number, text: string): void;
+    /** Remove line `i` and return its text. */
+    removeLineAt(i: number): string;
+    /** Set the cursor, clamping out-of-range values (line to `[0, lineCount-1]`, column to end of line). */
+    setCursor(line: number, logical: number): void;
+    /**
+     * Set the cursor by terminal column instead of code unit index — the
+     * entry point for mouse clicks. Snaps to the nearest valid position
+     * (see {@link TextLine.logicalAt}).
+     */
+    setCursorAtVisual(line: number, visual: number): void;
+    moveLeft(): void;
+    moveRight(): void;
+    /** Vertical movement aligns by visual column, so wide-character lines do not drift. */
+    moveUp(): void;
+    moveDown(): void;
+    moveToLineStart(): void;
+    moveToLineEnd(): void;
+    moveToDocumentStart(): void;
+    moveToDocumentEnd(): void;
+    /** A word is a run of non-whitespace; jump to the next word start (stays put at end of line). */
+    moveWordForward(): void;
+    /** A word is a run of non-whitespace; jump back to the current/previous word start. */
+    moveWordBackward(): void;
+    /** Page up: move the cursor up by `height - 1` lines (one line of overlap), keeping the visual column. */
+    movePageUp(height: number): void;
+    movePageDown(height: number): void;
+    /**
+     * Scroll the viewport so the cursor stays visible: if the cursor is above
+     * the viewport, scroll to its line; if below, scroll so it becomes the
+     * last visible line. Returns the new scrollTop.
+     */
+    updateScroll(height: number): number;
+}

package/dist/core/document/document.js

@@ -0,0 +1,175 @@
+import { TextLine } from "./text-line.js";
+/**
+ * Document model: array of lines + cursor + scroll state.
+ *
+ * Pure data and behavior: no React/Ink awareness, and no change
+ * notifications — `EditorController` owns those. The cursor stores only
+ * `{line, logical}`; `visual` is derived (see {@link CursorState}), so
+ * "logical column" and "display column" cannot diverge by construction.
+ *
+ * The document always has at least one line (empty document = one empty
+ * line), matching the result of `"".split(/\r?\n/)`.
+ */
+export class Document {
+    _lines;
+    _cursor;
+    _scrollTop = 0;
+    indentWidth;
+    constructor(text, options = {}) {
+        this._lines = text.split(/\r?\n/).map((t) => new TextLine(t));
+        this._cursor = { line: 0, logical: 0 };
+        this.indentWidth = options.indentWidth ?? 2;
+    }
+    get lineCount() {
+        return this._lines.length;
+    }
+    /** Snapshot of all line texts (for rendering; internally the model is `TextLine[]`). */
+    get lines() {
+        return this._lines.map((l) => l.text);
+    }
+    getLine(i) {
+        return this._lines[i].text;
+    }
+    get cursor() {
+        const line = this._lines[this._cursor.line];
+        return {
+            line: this._cursor.line,
+            logical: this._cursor.logical,
+            visual: line.visualAt(this._cursor.logical),
+        };
+    }
+    get scrollTop() {
+        return this._scrollTop;
+    }
+    /** Gutter width = decimal digit count of the last line number (at least 1). */
+    getLineNumberWidth() {
+        return Math.max(String(this._lines.length - 1).length, 1);
+    }
+    setLine(i, text) {
+        this._lines[i] = new TextLine(text);
+    }
+    /** Insert a line at index `i` (0 <= i <= lineCount), shifting the rest down. */
+    insertLineAt(i, text) {
+        this._lines.splice(i, 0, new TextLine(text));
+    }
+    /** Remove line `i` and return its text. */
+    removeLineAt(i) {
+        return this._lines.splice(i, 1)[0].text;
+    }
+    /** Set the cursor, clamping out-of-range values (line to `[0, lineCount-1]`, column to end of line). */
+    setCursor(line, logical) {
+        const l = Math.max(0, Math.min(line, this._lines.length - 1));
+        const len = this._lines[l].text.length;
+        this._cursor = { line: l, logical: Math.max(0, Math.min(logical, len)) };
+    }
+    /**
+     * Set the cursor by terminal column instead of code unit index — the
+     * entry point for mouse clicks. Snaps to the nearest valid position
+     * (see {@link TextLine.logicalAt}).
+     */
+    setCursorAtVisual(line, visual) {
+        const l = Math.max(0, Math.min(line, this._lines.length - 1));
+        this.setCursor(l, this._lines[l].logicalAt(visual));
+    }
+    moveLeft() {
+        const { line, logical } = this._cursor;
+        if (logical > 0) {
+            this.setCursor(line, logical - 1);
+        }
+    }
+    moveRight() {
+        const { line, logical } = this._cursor;
+        if (logical < this._lines[line].text.length) {
+            this.setCursor(line, logical + 1);
+        }
+    }
+    /** Vertical movement aligns by visual column, so wide-character lines do not drift. */
+    moveUp() {
+        const { line, logical } = this._cursor;
+        if (line > 0) {
+            const visual = this._lines[line].visualAt(logical);
+            this.setCursor(line - 1, this._lines[line - 1].logicalAt(visual));
+        }
+    }
+    moveDown() {
+        const { line, logical } = this._cursor;
+        if (line < this._lines.length - 1) {
+            const visual = this._lines[line].visualAt(logical);
+            this.setCursor(line + 1, this._lines[line + 1].logicalAt(visual));
+        }
+    }
+    moveToLineStart() {
+        this.setCursor(this._cursor.line, 0);
+    }
+    moveToLineEnd() {
+        this.setCursor(this._cursor.line, this._lines[this._cursor.line].text.length);
+    }
+    moveToDocumentStart() {
+        this.setCursor(0, 0);
+    }
+    moveToDocumentEnd() {
+        this.setCursor(this._lines.length - 1, this._lines[this._lines.length - 1].text.length);
+    }
+    /** A word is a run of non-whitespace; jump to the next word start (stays put at end of line). */
+    moveWordForward() {
+        const { line, logical } = this._cursor;
+        const text = this._lines[line].text;
+        const len = text.length;
+        let i = logical;
+        while (i < len && /\s/.test(text[i])) {
+            i++;
+        }
+        while (i < len && !/\s/.test(text[i])) {
+            i++;
+        }
+        while (i < len && /\s/.test(text[i])) {
+            i++;
+        }
+        this.setCursor(line, i);
+    }
+    /** A word is a run of non-whitespace; jump back to the current/previous word start. */
+    moveWordBackward() {
+        const { line, logical } = this._cursor;
+        const text = this._lines[line].text;
+        let i = logical;
+        while (i > 0 && /\s/.test(text[i - 1])) {
+            i--;
+        }
+        while (i > 0 && !/\s/.test(text[i - 1])) {
+            i--;
+        }
+        this.setCursor(line, i);
+    }
+    /** Page up: move the cursor up by `height - 1` lines (one line of overlap), keeping the visual column. */
+    movePageUp(height) {
+        const { line, logical } = this._cursor;
+        const visual = this._lines[line].visualAt(logical);
+        const target = Math.max(0, line - Math.max(1, height - 1));
+        this.setCursor(target, this._lines[target].logicalAt(visual));
+    }
+    movePageDown(height) {
+        const { line, logical } = this._cursor;
+        const visual = this._lines[line].visualAt(logical);
+        const target = Math.min(this._lines.length - 1, line + Math.max(1, height - 1));
+        this.setCursor(target, this._lines[target].logicalAt(visual));
+    }
+    /**
+     * Scroll the viewport so the cursor stays visible: if the cursor is above
+     * the viewport, scroll to its line; if below, scroll so it becomes the
+     * last visible line. Returns the new scrollTop.
+     */
+    updateScroll(height) {
+        const effectiveH = height > 0 ? height : this._lines.length;
+        let vs = this._scrollTop;
+        if (this._cursor.line < vs) {
+            vs = this._cursor.line;
+        }
+        else if (this._cursor.line >= vs + effectiveH) {
+            vs = this._cursor.line - effectiveH + 1;
+        }
+        const maxScroll = Math.max(0, this._lines.length - effectiveH);
+        vs = Math.max(0, Math.min(vs, maxScroll));
+        this._scrollTop = vs;
+        return vs;
+    }
+}

package/dist/core/document/operations.d.ts

@@ -0,0 +1,61 @@
+import type { Document } from "./document.js";
+/**
+ * Atomic edit operations, each implementing `apply` + `invert`.
+ *
+ * `invert` is the symmetric counterpart: executing it right after `apply`
+ * restores the document. Undo (P1) replays `invert` in reverse order, so no
+ * document snapshots are needed. The convention is that `invert` runs while
+ * the cursor is at the position `apply` left it at — history will restore the
+ * cursor before inverting.
+ */
+export type EditOperation = {
+    apply(doc: Document): void;
+    invert(doc: Document): void;
+};
+/** Insert a string at the cursor; invert deletes exactly the inserted text. */
+export declare class InsertTextOp implements EditOperation {
+    private readonly text;
+    constructor(text: string);
+    apply(doc: Document): void;
+    invert(doc: Document): void;
+}
+/** Backspace: delete the char before the cursor, or join with the previous line at column 0. */
+export declare class DeleteBeforeOp implements EditOperation {
+    private _deletedChar;
+    private _joined;
+    apply(doc: Document): void;
+    invert(doc: Document): void;
+}
+/** Delete key: remove the char after the cursor, or join with the next line at end of line. */
+export declare class DeleteAfterOp implements EditOperation {
+    private _deletedChar;
+    private _joined;
+    apply(doc: Document): void;
+    invert(doc: Document): void;
+}
+/** Enter: split the current line at the cursor; invert rejoins the two lines. */
+export declare class SplitLineOp implements EditOperation {
+    apply(doc: Document): void;
+    invert(doc: Document): void;
+}
+/**
+ * Join the next line into the current one. `apply` never moves the cursor,
+ * so `invert` cannot rely on the cursor position — it records the join point
+ * (end of the original current line) instead.
+ */
+export declare class JoinLineOp implements EditOperation {
+    private _joinAt;
+    apply(doc: Document): void;
+    invert(doc: Document): void;
+}
+/** Indent the current line by `indentWidth` spaces, moving the cursor along. */
+export declare class IndentOp implements EditOperation {
+    apply(doc: Document): void;
+    invert(doc: Document): void;
+}
+/** Outdent up to `indentWidth` leading spaces; invert re-adds exactly what was removed. */
+export declare class OutdentOp implements EditOperation {
+    private _removed;
+    apply(doc: Document): void;
+    invert(doc: Document): void;
+}

package/dist/core/document/operations.js

@@ -0,0 +1,176 @@
+/** Insert a string at the cursor; invert deletes exactly the inserted text. */
+export class InsertTextOp {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+    apply(doc) {
+        const { line, logical } = doc.cursor;
+        const cur = doc.getLine(line);
+        doc.setLine(line, cur.slice(0, logical) + this.text + cur.slice(logical));
+        doc.setCursor(line, logical + this.text.length);
+    }
+    invert(doc) {
+        const { line, logical } = doc.cursor;
+        const cur = doc.getLine(line);
+        const start = logical - this.text.length;
+        doc.setLine(line, cur.slice(0, start) + cur.slice(logical));
+        doc.setCursor(line, start);
+    }
+}
+/** Backspace: delete the char before the cursor, or join with the previous line at column 0. */
+export class DeleteBeforeOp {
+    _deletedChar = "";
+    _joined = false;
+    apply(doc) {
+        const { line, logical } = doc.cursor;
+        if (logical > 0) {
+            const cur = doc.getLine(line);
+            this._deletedChar = cur[logical - 1];
+            this._joined = false;
+            doc.setLine(line, cur.slice(0, logical - 1) + cur.slice(logical));
+            doc.setCursor(line, logical - 1);
+        }
+        else if (line > 0) {
+            const prev = doc.getLine(line - 1);
+            const cur = doc.getLine(line);
+            doc.setLine(line - 1, prev + cur);
+            doc.removeLineAt(line);
+            doc.setCursor(line - 1, prev.length);
+            this._joined = true;
+        }
+    }
+    invert(doc) {
+        if (!this._joined) {
+            const { line, logical } = doc.cursor;
+            const cur = doc.getLine(line);
+            doc.setLine(line, cur.slice(0, logical) + this._deletedChar + cur.slice(logical));
+            doc.setCursor(line, logical + 1);
+        }
+        else {
+            // Cursor sits at the end of the merged line; split it back at that point.
+            const { line, logical } = doc.cursor;
+            const cur = doc.getLine(line);
+            doc.setLine(line, cur.slice(0, logical));
+            doc.insertLineAt(line + 1, cur.slice(logical));
+            doc.setCursor(line + 1, 0);
+        }
+    }
+}
+/** Delete key: remove the char after the cursor, or join with the next line at end of line. */
+export class DeleteAfterOp {
+    _deletedChar = "";
+    _joined = false;
+    apply(doc) {
+        const { line, logical } = doc.cursor;
+        const cur = doc.getLine(line);
+        if (logical < cur.length) {
+            this._deletedChar = cur[logical];
+            this._joined = false;
+            doc.setLine(line, cur.slice(0, logical) + cur.slice(logical + 1));
+        }
+        else if (line < doc.lineCount - 1) {
+            const next = doc.getLine(line + 1);
+            doc.setLine(line, cur + next);
+            doc.removeLineAt(line + 1);
+            this._joined = true;
+        }
+    }
+    invert(doc) {
+        if (!this._joined) {
+            const { line, logical } = doc.cursor;
+            const cur = doc.getLine(line);
+            doc.setLine(line, cur.slice(0, logical) + this._deletedChar + cur.slice(logical));
+        }
+        else {
+            const { line, logical } = doc.cursor;
+            const cur = doc.getLine(line);
+            doc.setLine(line, cur.slice(0, logical));
+            doc.insertLineAt(line + 1, cur.slice(logical));
+        }
+    }
+}
+/** Enter: split the current line at the cursor; invert rejoins the two lines. */
+export class SplitLineOp {
+    apply(doc) {
+        const { line, logical } = doc.cursor;
+        const cur = doc.getLine(line);
+        doc.setLine(line, cur.slice(0, logical));
+        doc.insertLineAt(line + 1, cur.slice(logical));
+        doc.setCursor(line + 1, 0);
+    }
+    invert(doc) {
+        // Cursor is on the newly created line; the split point is its own start.
+        const { line } = doc.cursor;
+        const prev = doc.getLine(line - 1);
+        const cur = doc.getLine(line);
+        doc.setLine(line - 1, prev + cur);
+        doc.removeLineAt(line);
+        doc.setCursor(line - 1, prev.length);
+    }
+}
+/**
+ * Join the next line into the current one. `apply` never moves the cursor,
+ * so `invert` cannot rely on the cursor position — it records the join point
+ * (end of the original current line) instead.
+ */
+export class JoinLineOp {
+    _joinAt = 0;
+    apply(doc) {
+        const { line } = doc.cursor;
+        if (line >= doc.lineCount - 1) {
+            return;
+        }
+        const cur = doc.getLine(line);
+        const next = doc.getLine(line + 1);
+        this._joinAt = cur.length;
+        doc.setLine(line, cur + next);
+        doc.removeLineAt(line + 1);
+    }
+    invert(doc) {
+        const { line } = doc.cursor;
+        const cur = doc.getLine(line);
+        doc.setLine(line, cur.slice(0, this._joinAt));
+        doc.insertLineAt(line + 1, cur.slice(this._joinAt));
+    }
+}
+/** Indent the current line by `indentWidth` spaces, moving the cursor along. */
+export class IndentOp {
+    apply(doc) {
+        const { line, logical } = doc.cursor;
+        const cur = doc.getLine(line);
+        const spaces = " ".repeat(doc.indentWidth);
+        doc.setLine(line, spaces + cur);
+        doc.setCursor(line, logical + doc.indentWidth);
+    }
+    invert(doc) {
+        const { line, logical } = doc.cursor;
+        const cur = doc.getLine(line);
+        doc.setLine(line, cur.slice(doc.indentWidth));
+        doc.setCursor(line, Math.max(0, logical - doc.indentWidth));
+    }
+}
+/** Outdent up to `indentWidth` leading spaces; invert re-adds exactly what was removed. */
+export class OutdentOp {
+    _removed = 0;
+    apply(doc) {
+        const { line, logical } = doc.cursor;
+        const cur = doc.getLine(line);
+        const leading = /^ */.exec(cur)?.[0].length ?? 0;
+        const remove = Math.min(leading, doc.indentWidth);
+        this._removed = remove;
+        if (remove > 0) {
+            doc.setLine(line, cur.slice(remove));
+            doc.setCursor(line, Math.max(0, logical - remove));
+        }
+    }
+    invert(doc) {
+        if (this._removed === 0) {
+            return;
+        }
+        const { line, logical } = doc.cursor;
+        const cur = doc.getLine(line);
+        doc.setLine(line, " ".repeat(this._removed) + cur);
+        doc.setCursor(line, logical + this._removed);
+    }
+}

package/dist/core/document/position.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cursor coordinate types.
+ *
+ * Core of the dual-column design: editing uses `logical` (a code unit index,
+ * used for slicing/splicing), while display and cross-line movement use
+ * `visual` (terminal columns). Keeping them separate prevents cursor drift
+ * on wide characters (CJK/emoji).
+ */
+/** Cursor position in the document. Internal state stores only these two; `visual` is derived. */
+export type Position = {
+    line: number;
+    logical: number;
+};
+/** Exposed cursor state: `visual` is derived from the current line's prefix width. */
+export type CursorState = Position & {
+    visual: number;
+};

package/dist/core/document/position.js

@@ -0,0 +1,9 @@
+/**
+ * Cursor coordinate types.
+ *
+ * Core of the dual-column design: editing uses `logical` (a code unit index,
+ * used for slicing/splicing), while display and cross-line movement use
+ * `visual` (terminal columns). Keeping them separate prevents cursor drift
+ * on wide characters (CJK/emoji).
+ */
+export {};

package/dist/core/document/text-line.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A single line of text with its terminal width cached.
+ *
+ * `_prefix[i]` is the cumulative terminal width of the first `i` code units
+ * (0 at line start). Surrogate pairs (e.g. emoji) span 2 code units and share
+ * the same prefix at the middle index — the cursor never sits inside a
+ * surrogate pair, but aligning the array to code units lets `visualAt` /
+ * `logicalAt` use direct indexing and binary search instead of per-character
+ * scans on every call.
+ */
+export declare class TextLine {
+    readonly text: string;
+    private readonly _prefix;
+    readonly width: number;
+    constructor(text: string);
+    /** Terminal column of the given code unit index, clamped to `[0, text.length]`. */
+    visualAt(logical: number): number;
+    /**
+     * Terminal column → nearest valid cursor position (code unit index).
+     * When the target column falls inside a wide character, snap left
+     * (largest prefix not exceeding the target).
+     */
+    logicalAt(visual: number): number;
+}

package/dist/core/document/text-line.js

@@ -0,0 +1,60 @@
+import stringWidth from "string-width";
+/**
+ * A single line of text with its terminal width cached.
+ *
+ * `_prefix[i]` is the cumulative terminal width of the first `i` code units
+ * (0 at line start). Surrogate pairs (e.g. emoji) span 2 code units and share
+ * the same prefix at the middle index — the cursor never sits inside a
+ * surrogate pair, but aligning the array to code units lets `visualAt` /
+ * `logicalAt` use direct indexing and binary search instead of per-character
+ * scans on every call.
+ */
+export class TextLine {
+    text;
+    _prefix;
+    width;
+    constructor(text) {
+        this.text = text;
+        const prefix = [0];
+        let sum = 0;
+        for (let i = 0; i < text.length;) {
+            const cp = text.codePointAt(i);
+            const w = stringWidth(String.fromCodePoint(cp));
+            const units = cp > 0xffff ? 2 : 1;
+            for (let k = 0; k < units; k++) {
+                prefix.push(sum + w);
+            }
+            sum += w;
+            i += units;
+        }
+        this._prefix = prefix;
+        this.width = sum;
+    }
+    /** Terminal column of the given code unit index, clamped to `[0, text.length]`. */
+    visualAt(logical) {
+        const i = Math.max(0, Math.min(logical, this.text.length));
+        return this._prefix[i];
+    }
+    /**
+     * Terminal column → nearest valid cursor position (code unit index).
+     * When the target column falls inside a wide character, snap left
+     * (largest prefix not exceeding the target).
+     */
+    logicalAt(visual) {
+        if (visual <= 0) {
+            return 0;
+        }
+        let lo = 0;
+        let hi = this.text.length;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (this._prefix[mid] <= visual) {
+                lo = mid;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        return lo;
+    }
+}

package/dist/core/editor-controller.d.ts

@@ -0,0 +1,27 @@
+import { Document } from "./document/document.js";
+export type EditorOptions = {
+    indentWidth?: number;
+};
+export type EditorCommandArgs = Record<string, unknown> | undefined;
+export type EditorCommandHandler = (doc: Document, args: EditorCommandArgs) => void;
+type ChangeListener = () => void;
+/**
+ * Coordinator between the pure core and the keymap/render layers.
+ *
+ * Owns the document, a command registry (so P2 vim mode only swaps key
+ * bindings, never touching the core), and the change-notification channel
+ * the view subscribes to. Editing commands run operations that carry their
+ * own `invert`; the history stack (P1) will collect them.
+ */
+export declare class EditorController {
+    private readonly _document;
+    private readonly _commands;
+    private readonly _listeners;
+    constructor(text: string, options?: EditorOptions);
+    get document(): Document;
+    onChange(listener: ChangeListener): () => void;
+    defineCommand(id: string, handler: EditorCommandHandler): this;
+    execute(id: string, args?: EditorCommandArgs): void;
+    private _registerBuiltins;
+}
+export {};

package/dist/core/editor-controller.js

@@ -0,0 +1,90 @@
+import { Document } from "./document/document.js";
+import { DeleteAfterOp, DeleteBeforeOp, IndentOp, InsertTextOp, JoinLineOp, OutdentOp, SplitLineOp, } from "./document/operations.js";
+/**
+ * Coordinator between the pure core and the keymap/render layers.
+ *
+ * Owns the document, a command registry (so P2 vim mode only swaps key
+ * bindings, never touching the core), and the change-notification channel
+ * the view subscribes to. Editing commands run operations that carry their
+ * own `invert`; the history stack (P1) will collect them.
+ */
+export class EditorController {
+    _document;
+    _commands = new Map();
+    _listeners = new Set();
+    constructor(text, options = {}) {
+        this._document = new Document(text, { indentWidth: options.indentWidth });
+        this._registerBuiltins();
+    }
+    get document() {
+        return this._document;
+    }
+    onChange(listener) {
+        this._listeners.add(listener);
+        return () => {
+            this._listeners.delete(listener);
+        };
+    }
+    defineCommand(id, handler) {
+        this._commands.set(id, handler);
+        return this;
+    }
+    execute(id, args = undefined) {
+        const handler = this._commands.get(id);
+        if (!handler) {
+            throw new Error(`[ink-cartridge] Unknown editor command: ${id}`);
+        }
+        handler(this._document, args);
+        this._listeners.forEach((fn) => fn());
+    }
+    _registerBuiltins() {
+        this.defineCommand("editor.insertText", (doc, args) => {
+            const text = typeof args?.text === "string" ? args.text : "";
+            if (text) {
+                new InsertTextOp(text).apply(doc);
+            }
+        });
+        this.defineCommand("editor.deleteBefore", (doc) => {
+            new DeleteBeforeOp().apply(doc);
+        });
+        this.defineCommand("editor.deleteAfter", (doc) => {
+            new DeleteAfterOp().apply(doc);
+        });
+        this.defineCommand("editor.splitLine", (doc) => {
+            new SplitLineOp().apply(doc);
+        });
+        this.defineCommand("editor.joinLine", (doc) => {
+            new JoinLineOp().apply(doc);
+        });
+        this.defineCommand("editor.indent", (doc) => {
+            new IndentOp().apply(doc);
+        });
+        this.defineCommand("editor.outdent", (doc) => {
+            new OutdentOp().apply(doc);
+        });
+        this.defineCommand("cursor.moveLeft", (doc) => doc.moveLeft());
+        this.defineCommand("cursor.moveRight", (doc) => doc.moveRight());
+        this.defineCommand("cursor.moveUp", (doc) => doc.moveUp());
+        this.defineCommand("cursor.moveDown", (doc) => doc.moveDown());
+        this.defineCommand("cursor.lineStart", (doc) => doc.moveToLineStart());
+        this.defineCommand("cursor.lineEnd", (doc) => doc.moveToLineEnd());
+        this.defineCommand("cursor.wordForward", (doc) => doc.moveWordForward());
+        this.defineCommand("cursor.wordBackward", (doc) => doc.moveWordBackward());
+        this.defineCommand("cursor.documentStart", (doc) => doc.moveToDocumentStart());
+        this.defineCommand("cursor.documentEnd", (doc) => doc.moveToDocumentEnd());
+        this.defineCommand("cursor.pageUp", (doc, args) => {
+            const height = typeof args?.height === "number" ? args.height : 1;
+            doc.movePageUp(height);
+        });
+        this.defineCommand("cursor.pageDown", (doc, args) => {
+            const height = typeof args?.height === "number" ? args.height : 1;
+            doc.movePageDown(height);
+        });
+        // Mouse click: position the cursor by terminal column (not code units).
+        this.defineCommand("cursor.setPosition", (doc, args) => {
+            const line = typeof args?.line === "number" ? args.line : doc.cursor.line;
+            const visual = typeof args?.visual === "number" ? args.visual : doc.cursor.visual;
+            doc.setCursorAtVisual(line, visual);
+        });
+    }
+}

package/dist/index.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/dist/index.js

@@ -1,8 +1,9 @@
+#!/usr/bin/env node
 import { Box, render } from "ink";
 import React from "react";
-import { InformationBar } from "./core/view/information-bar.js";
+import { InformationBar } from "./view/information-bar.js";
 import { CurrentScreen, KeyboardProvider, registerComponent, ScenarioManagementProvider, } from "ink-cartridge";
-import { Editor } from "./core/view/editor.js";
+import { Editor } from "./view/editor.js";
 function App() {
     return (React.createElement(Box, { flexDirection: "column", height: "100%", width: "100%" },
         React.createElement(Box, { flexGrow: 1 },
@@ -12,5 +13,5 @@ function App() {
 }
 registerComponent(App, {});
 render(React.createElement(ScenarioManagementProvider, { defaultScreen: App, fullScreen: true },
-    React.createElement(KeyboardProvider, { autoTab: false },
+    React.createElement(KeyboardProvider, { autoTab: false, mouse: true },
         React.createElement(CurrentScreen, null))));

package/dist/view/click-mapping.d.ts

@@ -0,0 +1,23 @@
+export type ClickTarget = {
+    line: number;
+    visual: number;
+};
+/**
+ * Convert a 1-based terminal click (from `useMouseRegion`) into a document
+ * position, accounting for the line-number gutter and the vertical scroll
+ * offset.
+ *
+ * Assumes the region is the editor box itself with no padding, so
+ * `event.x - rect.x` is a 0-based cell column inside the region. Columns
+ * left of the gutter (clicks on the line numbers) snap to the text area's
+ * left edge; rows past the last document line clamp to it.
+ */
+export declare function clickToPosition(event: {
+    x: number;
+    y: number;
+}, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, gutterWidth: number, visibleStart: number, lineCount: number): ClickTarget;

package/dist/view/click-mapping.js

@@ -0,0 +1,17 @@
+/**
+ * Convert a 1-based terminal click (from `useMouseRegion`) into a document
+ * position, accounting for the line-number gutter and the vertical scroll
+ * offset.
+ *
+ * Assumes the region is the editor box itself with no padding, so
+ * `event.x - rect.x` is a 0-based cell column inside the region. Columns
+ * left of the gutter (clicks on the line numbers) snap to the text area's
+ * left edge; rows past the last document line clamp to it.
+ */
+export function clickToPosition(event, rect, gutterWidth, visibleStart, lineCount) {
+    const localX = event.x - rect.x;
+    const localY = event.y - rect.y;
+    const visual = Math.max(0, localX - gutterWidth);
+    const line = Math.max(0, Math.min(visibleStart + localY, lineCount - 1));
+    return { line, visual };
+}

package/dist/{core/view → view}/editor.d.ts

@@ -7,5 +7,10 @@ export type EditorContext = {
     cursorHeightOffset?: number;
     numberOfIndentationSpaces?: number;
 };
-export type { CursorCoordinates } from "../text/text-based-calculation.js";
+/**
+ * Main editor view: renders line numbers + text and routes every keystroke
+ * to the controller as a named command. Rendering diffs via the controller's
+ * change notifications; the controller lives in a ref so its state survives
+ * re-renders (same pattern the old TextCalculation used).
+ */
 export declare function Editor({ value: initialText, lineNumberRightSpacing, cursorOffset, cursorHeightOffset, numberOfIndentationSpaces, }: EditorContext): React.JSX.Element;

package/dist/view/editor.js

@@ -0,0 +1,85 @@
+import { Box, Text, useBoxMetrics, useCursor } from "ink";
+import { useKeyboard, useMouseRegion } from "ink-cartridge";
+import React, { useEffect, useRef, useState } from "react";
+import { EditorController } from "../core/editor-controller.js";
+import { clickToPosition } from "./click-mapping.js";
+/**
+ * Main editor view: renders line numbers + text and routes every keystroke
+ * to the controller as a named command. Rendering diffs via the controller's
+ * change notifications; the controller lives in a ref so its state survives
+ * re-renders (same pattern the old TextCalculation used).
+ */
+export function Editor({ value: initialText, lineNumberRightSpacing = 1, cursorOffset = 0, cursorHeightOffset = 2, numberOfIndentationSpaces = 2, }) {
+    const controllerRef = useRef(null);
+    if (!controllerRef.current) {
+        controllerRef.current = new EditorController(initialText, {
+            indentWidth: numberOfIndentationSpaces,
+        });
+    }
+    const controller = controllerRef.current;
+    const [, forceUpdate] = useState(0);
+    useEffect(() => {
+        return controller.onChange(() => forceUpdate((n) => n + 1));
+    }, [controller]);
+    const { setCursorPosition } = useCursor();
+    const { boundKeyboard, enableWildcardPriority } = useKeyboard();
+    useEffect(() => {
+        const removeWildcard = enableWildcardPriority();
+        const unbinds = [];
+        unbinds.push(boundKeyboard(["*"], (input) => controller.execute("editor.insertText", { text: input })));
+        unbinds.push(boundKeyboard(["return"], () => controller.execute("editor.splitLine")));
+        unbinds.push(boundKeyboard(["right"], () => controller.execute("cursor.moveRight")));
+        unbinds.push(boundKeyboard(["left"], () => controller.execute("cursor.moveLeft")));
+        // backspace deletes before the cursor; delete removes after it —
+        // the old prototype treated both as backspace.
+        unbinds.push(boundKeyboard(["backspace"], () => controller.execute("editor.deleteBefore")));
+        unbinds.push(boundKeyboard(["delete"], () => controller.execute("editor.deleteAfter")));
+        unbinds.push(boundKeyboard(["up"], () => controller.execute("cursor.moveUp")));
+        unbinds.push(boundKeyboard(["down"], () => controller.execute("cursor.moveDown")));
+        unbinds.push(boundKeyboard(["tab"], () => controller.execute("editor.indent")));
+        unbinds.push(boundKeyboard(["shift+tab"], () => controller.execute("editor.outdent")));
+        return () => {
+            removeWildcard();
+            unbinds.forEach((fn) => fn());
+        };
+    }, [boundKeyboard, enableWildcardPriority, controller]);
+    const ref = useRef(null);
+    const { height } = useBoxMetrics(ref);
+    const doc = controller.document;
+    const lineNumberWidth = doc.getLineNumberWidth();
+    const visibleStart = doc.updateScroll(height);
+    const effectiveH = height > 0 ? height : doc.lineCount;
+    const visibleLines = doc.lines.slice(visibleStart, visibleStart + effectiveH);
+    const cursor = doc.cursor;
+    const cursorX = cursor.visual + lineNumberWidth + lineNumberRightSpacing + cursorOffset;
+    const cursorY = cursor.line - visibleStart + cursorHeightOffset;
+    setCursorPosition({ x: cursorX, y: cursorY });
+    // Mouse: clicks position the cursor; the wheel scrolls one line at a time.
+    // The callbacks close over this render's metrics, and useMouseRegion keeps
+    // them fresh, so scrollTop/gutter always match what the user sees.
+    const mouseRef = useMouseRegion({
+        onClick: (event, rect) => {
+            const target = clickToPosition(event, rect, lineNumberWidth + lineNumberRightSpacing, doc.scrollTop, doc.lineCount);
+            controller.execute("cursor.setPosition", {
+                line: target.line,
+                visual: target.visual,
+            });
+        },
+        onWheel: (event) => {
+            if (event.button === "wheel-up") {
+                controller.execute("cursor.pageUp", { height: 1 });
+            }
+            else if (event.button === "wheel-down") {
+                controller.execute("cursor.pageDown", { height: 1 });
+            }
+        },
+    });
+    return (React.createElement(Box, { ref: mouseRef, height: "100%", width: "100%", backgroundColor: "#1e1e1e" },
+        React.createElement(Box, { ref: ref, height: "100%", width: "100%", flexDirection: "column" }, visibleLines.map((each, i) => {
+            const lineNumber = visibleStart + i;
+            return (React.createElement(Box, { key: lineNumber, flexDirection: "row" },
+                React.createElement(Box, { width: lineNumberWidth, justifyContent: "flex-end", marginRight: lineNumberRightSpacing },
+                    React.createElement(Text, { bold: cursor.line === lineNumber }, lineNumber)),
+                React.createElement(Text, null, each)));
+        }))));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "blots-editor",
-	"version": "0.0.6",
+	"version": "0.0.8",
 	"description": "A lightweight Markdown editor for the terminal, built on ink-cartridge",
 	"type": "module",
 	"main": "./dist/index.js",

package/dist/core/text/text-based-calculation.d.ts

@@ -1,41 +0,0 @@
-export type CursorCoordinates = {
-    line: number;
-    column: number;
-};
-export type TextCalcOptions = {
-    numberOfIndentationSpaces?: number;
-    cursorOffset?: number;
-    cursorHeightOffset?: number;
-    lineNumberRightSpacing?: number;
-};
-type ChangeListener = () => void;
-export declare class TextCalculation {
-    private _lines;
-    private _cursor;
-    private _scrollTop;
-    private _listeners;
-    readonly numberOfIndentationSpaces: number;
-    readonly cursorOffset: number;
-    readonly cursorHeightOffset: number;
-    readonly lineNumberRightSpacing: number;
-    constructor(text: string, options?: TextCalcOptions);
-    onChange(listener: ChangeListener): () => void;
-    private _notify;
-    get lines(): string[];
-    get cursor(): CursorCoordinates;
-    get lineCount(): number;
-    getLineNumberWidth(): number;
-    getCurrentLineText(): string;
-    getCursorX(lineNumberWidth: number): number;
-    updateScroll(height: number): number;
-    insertChar(char: string): void;
-    newLine(): void;
-    moveRight(): void;
-    moveLeft(): void;
-    moveUp(): void;
-    moveDown(): void;
-    backspace(): void;
-    indent(): void;
-    outdent(): void;
-}
-export {};

package/dist/core/text/text-based-calculation.js

@@ -1,161 +0,0 @@
-import stringWidth from "string-width";
-export class TextCalculation {
-    _lines;
-    _cursor;
-    _scrollTop;
-    _listeners = new Set();
-    numberOfIndentationSpaces;
-    cursorOffset;
-    cursorHeightOffset;
-    lineNumberRightSpacing;
-    constructor(text, options = {}) {
-        this._lines = text ? text.split(/\r?\n/) : [];
-        this._cursor = { line: 0, column: 0 };
-        this._scrollTop = 0;
-        this.numberOfIndentationSpaces = options.numberOfIndentationSpaces ?? 2;
-        this.cursorOffset = options.cursorOffset ?? 0;
-        this.cursorHeightOffset = options.cursorHeightOffset ?? 2;
-        this.lineNumberRightSpacing = Math.max(0, options.lineNumberRightSpacing ?? 1);
-    }
-    onChange(listener) {
-        this._listeners.add(listener);
-        return () => {
-            this._listeners.delete(listener);
-        };
-    }
-    _notify() {
-        this._listeners.forEach((fn) => fn());
-    }
-    get lines() {
-        return this._lines;
-    }
-    get cursor() {
-        return this._cursor;
-    }
-    get lineCount() {
-        return this._lines.length;
-    }
-    getLineNumberWidth() {
-        return Math.max(stringWidth(String(this._lines.length - 1)), 1);
-    }
-    getCurrentLineText() {
-        return this._lines[this._cursor.line] ?? "";
-    }
-    getCursorX(lineNumberWidth) {
-        const text = this.getCurrentLineText();
-        const clamped = Math.max(0, Math.min(text.length, this._cursor.column));
-        const visual = stringWidth(text.slice(0, clamped));
-        return (visual + lineNumberWidth + this.lineNumberRightSpacing + this.cursorOffset);
-    }
-    updateScroll(height) {
-        const effectiveH = height > 0 ? height : this._lines.length;
-        let vs = this._scrollTop;
-        if (this._cursor.line < vs) {
-            vs = this._cursor.line;
-        }
-        else if (this._cursor.line >= vs + effectiveH) {
-            vs = this._cursor.line - effectiveH + 1;
-        }
-        const maxScroll = Math.max(0, this._lines.length - effectiveH);
-        vs = Math.max(0, Math.min(vs, maxScroll));
-        this._scrollTop = vs;
-        return vs;
-    }
-    insertChar(char) {
-        const { line, column } = this._cursor;
-        this._lines[line] =
-            this._lines[line].slice(0, column) +
-                char +
-                this._lines[line].slice(column);
-        this._cursor = { line, column: column + char.length };
-        this._notify();
-    }
-    newLine() {
-        const { line, column } = this._cursor;
-        const current = this._lines[line];
-        this._lines[line] = current.slice(0, column);
-        this._lines.splice(line + 1, 0, current.slice(column));
-        this._cursor = { line: line + 1, column: 0 };
-        this._notify();
-    }
-    moveRight() {
-        const maxCol = this._lines[this._cursor.line]?.length ?? 0;
-        this._cursor = {
-            line: this._cursor.line,
-            column: Math.min(this._cursor.column + 1, maxCol),
-        };
-        this._notify();
-    }
-    moveLeft() {
-        this._cursor = {
-            line: this._cursor.line,
-            column: Math.max(this._cursor.column - 1, 0),
-        };
-        this._notify();
-    }
-    moveUp() {
-        const newLine = Math.max(this._cursor.line - 1, 0);
-        const maxCol = this._lines[newLine]?.length ?? 0;
-        this._cursor = {
-            line: newLine,
-            column: Math.min(maxCol, this._cursor.column),
-        };
-        this._notify();
-    }
-    moveDown() {
-        const newLine = Math.min(this._cursor.line + 1, this._lines.length - 1);
-        const maxCol = this._lines[newLine]?.length ?? 0;
-        this._cursor = {
-            line: newLine,
-            column: Math.min(maxCol, this._cursor.column),
-        };
-        this._notify();
-    }
-    backspace() {
-        const { line, column } = this._cursor;
-        if (column === 0 && line !== 0) {
-            const prevLen = this._lines[line - 1].length;
-            this._lines[line - 1] += this._lines[line];
-            this._lines.splice(line, 1);
-            this._cursor = { line: line - 1, column: prevLen };
-        }
-        else if (column > 0) {
-            this._lines[line] =
-                this._lines[line].slice(0, column - 1) +
-                    this._lines[line].slice(column);
-            this._cursor = { line, column: column - 1 };
-        }
-        this._notify();
-    }
-    indent() {
-        const { line } = this._cursor;
-        const spaces = " ".repeat(this.numberOfIndentationSpaces);
-        this._lines[line] = spaces + this._lines[line];
-        this._cursor = {
-            line,
-            column: this._cursor.column + this.numberOfIndentationSpaces,
-        };
-        this._notify();
-    }
-    outdent() {
-        const { line } = this._cursor;
-        const current = this._lines[line];
-        const leadingSpaces = current.match(/^ */)?.[0].length || 0;
-        const n = this.numberOfIndentationSpaces;
-        if (leadingSpaces >= n) {
-            this._lines[line] = current.slice(n);
-            this._cursor = {
-                line,
-                column: Math.max(0, this._cursor.column - n),
-            };
-        }
-        else if (leadingSpaces > 0) {
-            this._lines[line] = current.slice(leadingSpaces);
-            this._cursor = {
-                line,
-                column: Math.max(0, this._cursor.column - leadingSpaces),
-            };
-        }
-        this._notify();
-    }
-}

package/dist/core/view/editor.js

@@ -1,55 +0,0 @@
-import { Box, Text, useBoxMetrics, useCursor } from "ink";
-import { useKeyboard } from "ink-cartridge";
-import React, { useEffect, useRef, useState } from "react";
-import { TextCalculation } from "../text/text-based-calculation.js";
-export function Editor({ value: initialText, lineNumberRightSpacing, cursorOffset, cursorHeightOffset, numberOfIndentationSpaces, }) {
-    const calcRef = useRef(null);
-    if (!calcRef.current) {
-        calcRef.current = new TextCalculation(initialText, {
-            lineNumberRightSpacing,
-            cursorOffset,
-            cursorHeightOffset,
-            numberOfIndentationSpaces,
-        });
-    }
-    const calc = calcRef.current;
-    const [, forceUpdate] = useState(0);
-    useEffect(() => {
-        return calc.onChange(() => forceUpdate((n) => n + 1));
-    }, [calc]);
-    const { setCursorPosition } = useCursor();
-    const { boundKeyboard, enableWildcardPriority } = useKeyboard();
-    useEffect(() => {
-        const removeWildcard = enableWildcardPriority();
-        const unbinds = [];
-        unbinds.push(boundKeyboard(["*"], (input) => calc.insertChar(input)));
-        unbinds.push(boundKeyboard(["return"], () => calc.newLine()));
-        unbinds.push(boundKeyboard(["right"], () => calc.moveRight()));
-        unbinds.push(boundKeyboard(["left"], () => calc.moveLeft()));
-        unbinds.push(boundKeyboard(["backspace", "delete"], () => calc.backspace()));
-        unbinds.push(boundKeyboard(["up"], () => calc.moveUp()));
-        unbinds.push(boundKeyboard(["down"], () => calc.moveDown()));
-        unbinds.push(boundKeyboard(["tab"], () => calc.indent()));
-        unbinds.push(boundKeyboard(["shift+tab"], () => calc.outdent()));
-        return () => {
-            removeWildcard();
-            unbinds.forEach((fn) => fn());
-        };
-    }, [boundKeyboard, enableWildcardPriority, calc]);
-    const ref = useRef(null);
-    const { height } = useBoxMetrics(ref);
-    const lineNumberWidth = calc.getLineNumberWidth();
-    const visibleStart = calc.updateScroll(height);
-    const effectiveH = height > 0 ? height : calc.lineCount;
-    const visibleLines = calc.lines.slice(visibleStart, visibleStart + effectiveH);
-    const cursorX = calc.getCursorX(lineNumberWidth);
-    const cursorY = calc.cursor.line - visibleStart + calc.cursorHeightOffset;
-    setCursorPosition({ x: cursorX, y: cursorY });
-    return (React.createElement(Box, { ref: ref, height: "100%", width: "100%", backgroundColor: "#1e1e1e", flexDirection: "column" }, visibleLines.map((each, i) => {
-        const lineNumber = visibleStart + i;
-        return (React.createElement(Box, { key: lineNumber, flexDirection: "row" },
-            React.createElement(Box, { width: lineNumberWidth, justifyContent: "flex-end", marginRight: calc.lineNumberRightSpacing },
-                React.createElement(Text, { bold: calc.cursor.line === lineNumber }, lineNumber)),
-            React.createElement(Text, null, each)));
-    })));
-}