blots-editor 0.0.11 → 0.0.13

package/asset/language/en.json

@@ -7,9 +7,13 @@
   "settings.language": "Language",
   "settings.language.en": "English",
   "settings.language.zh": "中文",
+  "settings.sensitivity.cursor": "Cursor Wheel Sensitivity",
+  "settings.sensitivity.view": "View Scroll Sensitivity",
+  "settings.sensitivity.hint": "Click or drag to adjust",
   "settings.back": "Back",
   "editor.mode.insert": "INSERT",
   "editor.mode.normal": "NORMAL",
   "command.prompt": "Command",
-  "command.unknown": "Unknown command: {cmd}"
+  "command.unknown": "Unknown command: {cmd}",
+  "toolbar.fileTree": "File Tree"
 }

package/asset/language/zh.json

@@ -7,9 +7,13 @@
   "settings.language": "语言",
   "settings.language.en": "英文",
   "settings.language.zh": "中文",
+  "settings.sensitivity.cursor": "光标滚动灵敏度",
+  "settings.sensitivity.view": "视图滚动灵敏度",
+  "settings.sensitivity.hint": "点击或拖动调整",
   "settings.back": "返回",
   "editor.mode.insert": "插入",
   "editor.mode.normal": "普通",
   "command.prompt": "命令",
-  "command.unknown": "未知命令：{cmd}"
+  "command.unknown": "未知命令：{cmd}",
+  "toolbar.fileTree": "文件树"
 }

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

@@ -19,6 +19,7 @@ export declare class Document {
     private _scrollTop;
     private _wrapWidth;
     private _viewScrollTop;
+    private _scrollRemainder;
     readonly indentWidth: number;
     constructor(text: string, options?: DocumentOptions);
     get lineCount(): number;
@@ -93,8 +94,9 @@ export declare class Document {
     movePageDown(height: number): void;
     /**
      * Scroll the viewport by `delta` visual lines without moving the cursor,
-     * clamped to the document range. Locks the view in place (Ctrl+wheel
-     * browsing) until the cursor moves.
+     * clamped to the document range. Fractional deltas (wheel sensitivity)
+     * accumulate and round to whole visual lines over successive notches.
+     * Locks the view in place (Ctrl+wheel browsing) until the cursor moves.
      */
     scrollView(delta: number, height: number): number;
     /**

package/dist/core/document/document.js

@@ -18,6 +18,8 @@ export class Document {
     // Non-null while the user is scrolling the view manually (Ctrl+wheel):
     // updateScroll keeps this position instead of following the cursor.
     _viewScrollTop = null;
+    // Fractional view-scroll remainder, so e.g. 3.5 cells/notch scrolls 3,4,3,4…
+    _scrollRemainder = 0;
     indentWidth;
     constructor(text, options = {}) {
         this._lines = text.split(/\r?\n/).map((t) => new TextLine(t));
@@ -298,7 +300,10 @@ export class Document {
     }
     /** Page up: move the cursor up by `height - 1` visual lines (one line of overlap), keeping the visual column. */
     movePageUp(height) {
-        const target = Math.max(0, this.cursorVisualLine - Math.max(1, height - 1));
+        // `height` may be fractional (wheel sensitivity): round to whole
+        // visual lines, keeping the one-line overlap.
+        const step = Math.max(1, Math.round(height) - 1);
+        const target = Math.max(0, this.cursorVisualLine - step);
         const seg = this.visualLineAt(target);
         if (!seg) {
             return;
@@ -306,7 +311,8 @@ export class Document {
         this.moveToSegment(seg);
     }
     movePageDown(height) {
-        const target = Math.min(this.visualLineCount - 1, this.cursorVisualLine + Math.max(1, height - 1));
+        const step = Math.max(1, Math.round(height) - 1);
+        const target = Math.min(this.visualLineCount - 1, this.cursorVisualLine + step);
         const seg = this.visualLineAt(target);
         if (!seg) {
             return;
@@ -315,15 +321,19 @@ export class Document {
     }
     /**
      * Scroll the viewport by `delta` visual lines without moving the cursor,
-     * clamped to the document range. Locks the view in place (Ctrl+wheel
-     * browsing) until the cursor moves.
+     * clamped to the document range. Fractional deltas (wheel sensitivity)
+     * accumulate and round to whole visual lines over successive notches.
+     * Locks the view in place (Ctrl+wheel browsing) until the cursor moves.
      */
     scrollView(delta, height) {
         const total = this.visualLineCount;
         const effectiveH = height > 0 ? height : total;
         const maxScroll = Math.max(0, total - effectiveH);
         const base = this._viewScrollTop ?? this._scrollTop;
-        const vs = Math.max(0, Math.min(base + delta, maxScroll));
+        this._scrollRemainder += delta;
+        const move = Math.trunc(this._scrollRemainder);
+        this._scrollRemainder -= move;
+        const vs = Math.max(0, Math.min(base + move, maxScroll));
         this._viewScrollTop = vs;
         this._scrollTop = vs;
         return vs;

package/dist/core/settings/schema.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+/**
+ * Editor settings schema.
+ *
+ * This is the single source of truth for persisted user settings: extending
+ * the editor with a new option means adding a field here (plus a defaults
+ * entry and a UI row in the settings screen) — validation, persistence and
+ * reactivity all flow from this schema.
+ */
+/** Wheel sensitivity in visual lines per notch, 1.0–10.0, 0.5 steps. */
+export declare const sensitivitySchema: z.ZodDefault<z.ZodNumber>;
+export declare const settingsSchema: z.ZodObject<{
+    language: z.ZodDefault<z.ZodString>;
+    wheel: z.ZodDefault<z.ZodObject<{
+        cursor: z.ZodDefault<z.ZodNumber>;
+        view: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type EditorSettings = z.infer<typeof settingsSchema>;
+export type WheelSensitivity = EditorSettings["wheel"];
+export declare const DEFAULT_SETTINGS: EditorSettings;
+/** Parse an unknown persisted value, falling back to defaults on any failure. */
+export declare function parseSettings(raw: unknown): EditorSettings;

package/dist/core/settings/schema.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+/**
+ * Editor settings schema.
+ *
+ * This is the single source of truth for persisted user settings: extending
+ * the editor with a new option means adding a field here (plus a defaults
+ * entry and a UI row in the settings screen) — validation, persistence and
+ * reactivity all flow from this schema.
+ */
+/** Wheel sensitivity in visual lines per notch, 1.0–10.0, 0.5 steps. */
+export const sensitivitySchema = z
+    .number()
+    .min(1)
+    .max(10)
+    .step(0.5)
+    .default(1);
+const DEFAULT_WHEEL = { cursor: 1, view: 3 };
+export const settingsSchema = z.object({
+    /** Persisted UI language (validated at the app layer; unknown codes fall back). */
+    language: z.string().min(1).default("en"),
+    wheel: z
+        .object({
+        /** Plain wheel: how many visual lines the CURSOR moves per notch. */
+        cursor: sensitivitySchema,
+        /** Ctrl+wheel: how many visual lines the VIEW scrolls per notch. */
+        view: sensitivitySchema,
+    })
+        .default(DEFAULT_WHEEL),
+});
+export const DEFAULT_SETTINGS = {
+    language: "en",
+    wheel: DEFAULT_WHEEL,
+};
+/** Parse an unknown persisted value, falling back to defaults on any failure. */
+export function parseSettings(raw) {
+    const parsed = settingsSchema.safeParse(raw);
+    return parsed.success ? parsed.data : structuredClone(DEFAULT_SETTINGS);
+}

package/dist/core/settings/store.d.ts

@@ -0,0 +1,34 @@
+import { type EditorSettings } from "./schema.js";
+/**
+ * JSON persistence for editor settings at `~/.config/blots-editor/settings.json`.
+ *
+ * A plain observable store (no React): the view layer wraps it with
+ * `useSyncExternalStore`. Reads are lazy and tolerant — a missing, corrupt or
+ * schema-invalid file falls back to defaults; writes are best-effort and never
+ * throw into the render path.
+ */
+export declare class SettingsStore {
+    private _settings;
+    private readonly listeners;
+    private _filePath;
+    /** Injectable for tests; defaults to `~/.config/blots-editor/settings.json`. */
+    constructor(filePath?: string);
+    get filePath(): string;
+    /** Current settings (lazily loaded on first access). */
+    get settings(): EditorSettings;
+    private load;
+    /** Update in memory and notify subscribers; no disk write (drag in progress). */
+    update(settings: EditorSettings): void;
+    /** Persist to disk, update memory, and notify subscribers. */
+    persist(settings: EditorSettings): void;
+    /** Persist whatever is currently in memory (drag end / click). */
+    commit(): void;
+    /**
+     * Test helper: repoint the store at a fresh file and drop cached state,
+     * so tests never touch the real `~/.config` file.
+     */
+    reset(filePath: string): void;
+    subscribe: (listener: () => void) => (() => void);
+    /** Notify React subscribers that settings changed. */
+    notify(): void;
+}

package/dist/core/settings/store.js

@@ -0,0 +1,82 @@
+import { homedir } from "node:os";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DEFAULT_SETTINGS, parseSettings } from "./schema.js";
+/**
+ * JSON persistence for editor settings at `~/.config/blots-editor/settings.json`.
+ *
+ * A plain observable store (no React): the view layer wraps it with
+ * `useSyncExternalStore`. Reads are lazy and tolerant — a missing, corrupt or
+ * schema-invalid file falls back to defaults; writes are best-effort and never
+ * throw into the render path.
+ */
+export class SettingsStore {
+    _settings = null;
+    listeners = new Set();
+    _filePath = null;
+    /** Injectable for tests; defaults to `~/.config/blots-editor/settings.json`. */
+    constructor(filePath) {
+        this._filePath = filePath ?? null;
+    }
+    get filePath() {
+        this._filePath ??= join(homedir(), ".config", "blots-editor", "settings.json");
+        return this._filePath;
+    }
+    /** Current settings (lazily loaded on first access). */
+    get settings() {
+        if (!this._settings) {
+            this._settings = this.load();
+        }
+        return this._settings;
+    }
+    load() {
+        try {
+            const raw = JSON.parse(readFileSync(this.filePath, "utf8"));
+            return parseSettings(raw);
+        }
+        catch {
+            // Missing file, unreadable JSON, or an fs error — start from defaults.
+            return structuredClone(DEFAULT_SETTINGS);
+        }
+    }
+    /** Update in memory and notify subscribers; no disk write (drag in progress). */
+    update(settings) {
+        this._settings = settings;
+        this.notify();
+    }
+    /** Persist to disk, update memory, and notify subscribers. */
+    persist(settings) {
+        this._settings = settings;
+        try {
+            mkdirSync(dirname(this.filePath), { recursive: true });
+            writeFileSync(this.filePath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+        }
+        catch {
+            // Persistence is best-effort: a read-only home dir must not crash
+            // the editor or block the settings screen.
+        }
+        this.notify();
+    }
+    /** Persist whatever is currently in memory (drag end / click). */
+    commit() {
+        if (this._settings) {
+            this.persist(this._settings);
+        }
+    }
+    /**
+     * Test helper: repoint the store at a fresh file and drop cached state,
+     * so tests never touch the real `~/.config` file.
+     */
+    reset(filePath) {
+        this._filePath = filePath;
+        this._settings = null;
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    /** Notify React subscribers that settings changed. */
+    notify() {
+        this.listeners.forEach((fn) => fn());
+    }
+}

package/dist/core/settings/useSettings.d.ts

@@ -0,0 +1,25 @@
+import type { EditorSettings, WheelSensitivity } from "./schema.js";
+import { SettingsStore } from "./store.js";
+/**
+ * Shared settings store for the whole editor. One instance serves the
+ * settings screen (writes) and the editor view (reads), so changes propagate
+ * instantly.
+ */
+export declare const settingsStore: SettingsStore;
+export type SettingsApi = {
+    settings: EditorSettings;
+    /** Set a sensitivity and persist it immediately (click / keyboard). */
+    setSensitivity: (key: keyof WheelSensitivity, value: number) => void;
+    /** Update in memory only (while dragging); disk write happens on commit. */
+    setDraft: (key: keyof WheelSensitivity, value: number) => void;
+    /** Persist the in-memory settings (drag end / click). */
+    commit: () => void;
+    /** Persist the UI language (called alongside the i18n `setLanguage`). */
+    setLanguage: (code: string) => void;
+};
+/**
+ * React binding for the shared {@link settingsStore}. Re-renders subscribers
+ * whenever the store changes, keeping the editor view and the settings screen
+ * in sync.
+ */
+export declare function useSettings(): SettingsApi;

package/dist/core/settings/useSettings.js

@@ -0,0 +1,27 @@
+import { useSyncExternalStore } from "react";
+import { SettingsStore } from "./store.js";
+/**
+ * Shared settings store for the whole editor. One instance serves the
+ * settings screen (writes) and the editor view (reads), so changes propagate
+ * instantly.
+ */
+export const settingsStore = new SettingsStore();
+/**
+ * React binding for the shared {@link settingsStore}. Re-renders subscribers
+ * whenever the store changes, keeping the editor view and the settings screen
+ * in sync.
+ */
+export function useSettings() {
+    const settings = useSyncExternalStore(settingsStore.subscribe, () => settingsStore.settings, () => settingsStore.settings);
+    const next = (key, value) => ({
+        ...settings,
+        wheel: { ...settings.wheel, [key]: value },
+    });
+    return {
+        settings,
+        setSensitivity: (key, value) => settingsStore.persist(next(key, value)),
+        setDraft: (key, value) => settingsStore.update(next(key, value)),
+        commit: () => settingsStore.commit(),
+        setLanguage: (code) => settingsStore.persist({ ...settings, language: code }),
+    };
+}

package/dist/index.js

@@ -3,6 +3,7 @@ import { render } from "ink";
 import React from "react";
 import { CurrentScreen, KeyboardProvider, LanguageProvider, registerComponent, ScenarioManagementProvider, } from "ink-cartridge";
 import { resources } from "./i18n-resources.js";
+import { settingsStore } from "./core/settings/useSettings.js";
 import { MainMenu } from "./view/main-menu.js";
 import { Editor } from "./view/editor.js";
 import { Settings } from "./view/settings.js";
@@ -10,6 +11,6 @@ registerComponent(MainMenu, {});
 registerComponent(Editor, {}, { parent: MainMenu });
 registerComponent(Settings, {}, { parent: MainMenu });
 render(React.createElement(ScenarioManagementProvider, { defaultScreen: MainMenu, fullScreen: true },
-    React.createElement(LanguageProvider, { resources: resources, defaultLanguage: "en", fallbackLanguage: "en" },
+    React.createElement(LanguageProvider, { resources: resources, defaultLanguage: settingsStore.settings.language, fallbackLanguage: "en" },
         React.createElement(KeyboardProvider, { autoTab: false, mouse: true, modes: ["insert", "normal"], defaultMode: "insert" },
             React.createElement(CurrentScreen, null)))));

package/dist/view/editor.js

@@ -1,10 +1,16 @@
 import { Box, Text, useBoxMetrics, useCursor } from "ink";
-import { applyElementToModalLayer, openModalLayer, useI18n, useKeyboard, useMouseRegion, } from "ink-cartridge";
+import { applyElement, applyElementToModalLayer, closeLayer, openLayer, openModalLayer, useI18n, useKeyboard, useMouseRegion, } from "ink-cartridge";
 import React, { useCallback, useEffect, useRef, useState } from "react";
 import { EditorController } from "../core/editor-controller.js";
+import { useSettings } from "../core/settings/useSettings.js";
 import { clickToPosition } from "./click-mapping.js";
 import { CommandBar } from "./command-bar.js";
 import { InformationBar } from "./information-bar.js";
+import { ToolBar } from "./tool-bar.js";
+/** Layer hosting the floating toolbar; below modal layers so it never
+ *  intercepts keys meant for a modal (e.g. the command bar). */
+const TOOLBAR_LAYER_ID = "toolbar";
+const TOOLBAR_Z_INDEX = 1;
 /**
  * Main editor view: renders the status bar + line numbers + text, routes
  * every keystroke to the controller as a named command, and splits
@@ -26,6 +32,7 @@ export function Editor({ value: initialText = "", lineNumberRightSpacing = 1, cu
     const { setCursorPosition } = useCursor();
     const { boundKeyboard, enableWildcardPriority, getCurrentMode, registryCompositionKey, removeCompositionKey, setMode, } = useKeyboard();
     const { t } = useI18n();
+    const { settings } = useSettings();
     // The engine keeps modes in a ref (no React notification), so we mirror
     // switches locally to keep the status bar live.
     const [mode, setLocalMode] = useState(() => getCurrentMode());
@@ -40,6 +47,37 @@ export function Editor({ value: initialText = "", lineNumberRightSpacing = 1, cu
             element: CommandBar,
         });
     }, []);
+    // The toolbar lives in a regular layer (below modal layers) so it floats
+    // above the document without taking over the keyboard. The editor owns the
+    // layer lifecycle and the ctrl+tab toggle because the layer's element
+    // unmounts when it closes — a binding inside it could never re-open it.
+    const [toolbarOpen, setToolbarOpen] = useState(true);
+    useEffect(() => {
+        return () => closeLayer(TOOLBAR_LAYER_ID);
+    }, []);
+    // Opening must wait one tick: passive effects run child-first on mount, so
+    // when the editor IS the initial screen this effect races the provider's
+    // dispatcher registration and openLayer would throw. ctrl+tab toggles hit
+    // the same deferred path — the one-tick delay is imperceptible. Closing is
+    // safe immediately because the dispatcher is registered by then.
+    useEffect(() => {
+        if (!toolbarOpen) {
+            closeLayer(TOOLBAR_LAYER_ID);
+            return;
+        }
+        const timer = setTimeout(() => {
+            openLayer(TOOLBAR_LAYER_ID, TOOLBAR_Z_INDEX);
+            applyElement(TOOLBAR_LAYER_ID, {
+                elementId: "toolbar",
+                element: ToolBar,
+                props: { mode },
+            });
+        }, 0);
+        return () => clearTimeout(timer);
+    }, [toolbarOpen, mode]);
+    useEffect(() => {
+        return boundKeyboard(["ctrl+tab"], () => setToolbarOpen((open) => !open));
+    }, [boundKeyboard]);
     useEffect(() => {
         const removeWildcard = enableWildcardPriority();
         const unbinds = [];
@@ -142,14 +180,17 @@ export function Editor({ value: initialText = "", lineNumberRightSpacing = 1, cu
                 return;
             }
             if (event.ctrl) {
+                // Ctrl+wheel scrolls the view at `view` lines per notch
+                // (clamped to the document); the cursor does not move.
                 controller.execute("view.scroll", {
-                    delta: up ? -1 : 1,
+                    delta: up ? -settings.wheel.view : settings.wheel.view,
                     height,
                 });
                 return;
             }
+            // Plain wheel moves the cursor at `cursor` lines per notch.
             controller.execute(up ? "cursor.pageUp" : "cursor.pageDown", {
-                height: 1,
+                height: settings.wheel.cursor,
             });
         },
     });

package/dist/view/frame-clamp.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Clamp a frame's top-left corner (0-based terminal coordinates) so the
+ * whole frame stays inside the terminal. `Math.max(0, ...)` on the max side
+ * keeps the frame at 0 when the terminal is smaller than the frame itself —
+ * a negative position would push the border off-screen on both sides.
+ */
+export declare function clampFrame(left: number, top: number, columns: number, rows: number, width: number, height: number): {
+    left: number;
+    top: number;
+};

package/dist/view/frame-clamp.js

@@ -0,0 +1,12 @@
+/**
+ * Clamp a frame's top-left corner (0-based terminal coordinates) so the
+ * whole frame stays inside the terminal. `Math.max(0, ...)` on the max side
+ * keeps the frame at 0 when the terminal is smaller than the frame itself —
+ * a negative position would push the border off-screen on both sides.
+ */
+export function clampFrame(left, top, columns, rows, width, height) {
+    return {
+        left: Math.min(Math.max(0, left), Math.max(0, columns - width)),
+        top: Math.min(Math.max(0, top), Math.max(0, rows - height)),
+    };
+}

package/dist/view/modal-frame.d.ts

@@ -0,0 +1,16 @@
+import React, { type ReactNode } from "react";
+type ModalFrameProps = {
+    title: string;
+    children: ReactNode;
+    footer?: ReactNode;
+    width?: number;
+};
+/**
+ * Shared draggable modal frame used by the language and sensitivity pickers.
+ *
+ * Centered by flex layout until the user grabs it, then switches to absolute
+ * positioning and follows the cursor (clamped to the terminal). Border turns
+ * green while dragging. Callers provide the title, body and optional footer.
+ */
+export declare function ModalFrame({ title, children, footer, width, }: ModalFrameProps): React.JSX.Element;
+export {};

package/dist/view/modal-frame.js

@@ -0,0 +1,43 @@
+import { Box, Text, useWindowSize } from "ink";
+import { useMouseRegion } from "ink-cartridge";
+import React, { useRef, useState } from "react";
+import { clampFrame } from "./frame-clamp.js";
+/**
+ * Shared draggable modal frame used by the language and sensitivity pickers.
+ *
+ * Centered by flex layout until the user grabs it, then switches to absolute
+ * positioning and follows the cursor (clamped to the terminal). Border turns
+ * green while dragging. Callers provide the title, body and optional footer.
+ */
+export function ModalFrame({ title, children, footer, width = 36, }) {
+    const { columns, rows } = useWindowSize();
+    // null = centered by flex layout; set once dragging starts so the frame
+    // keeps following the cursor via absolute positioning (0-based coords).
+    const [pos, setPos] = useState(null);
+    const [dragging, setDragging] = useState(false);
+    // Where inside the frame the cursor was grabbed, so the frame doesn't
+    // jump so its top-left lands under the cursor on the first drag move.
+    const grabOffsetRef = useRef({ dx: 0, dy: 0 });
+    const frameRef = useMouseRegion({
+        onDragStart: (event, rect) => {
+            grabOffsetRef.current = {
+                dx: event.x - rect.x,
+                dy: event.y - rect.y,
+            };
+            // Switch from flex centering to absolute positioning at the
+            // current rect — seamless, no jump on the first frame.
+            setPos({ top: rect.y - 1, left: rect.x - 1 });
+            setDragging(true);
+        },
+        onDragMove: (event, rect) => {
+            const { dx, dy } = grabOffsetRef.current;
+            setPos(clampFrame(event.x - dx - 1, event.y - dy - 1, columns, rows, rect.width, rect.height));
+        },
+        onDragEnd: () => setDragging(false),
+    });
+    return (React.createElement(Box, { width: "100%", height: "100%", justifyContent: "center", alignItems: "center" },
+        React.createElement(Box, { ref: frameRef, position: pos ? "absolute" : undefined, top: pos?.top, left: pos?.left, flexDirection: "column", borderStyle: "bold", borderColor: dragging ? "green" : "white", backgroundColor: "black", width: width, alignItems: "center", paddingX: 4, paddingY: 1, gap: 1 },
+            React.createElement(Text, { bold: true }, title),
+            children,
+            footer)));
+}

package/dist/view/sensitivity-bar.d.ts

@@ -0,0 +1,24 @@
+import React from "react";
+export declare const SENSITIVITY_MIN = 1;
+export declare const SENSITIVITY_MAX = 10;
+export declare const SENSITIVITY_STEP = 0.5;
+/** Bar cells: (10 - 1) / 0.5 steps, so every cell maps to exactly one step. */
+export declare const BAR_WIDTH: number;
+/** Map a 0..1 ratio to a sensitivity value in 0.5 steps. */
+export declare function valueFromRatio(ratio: number): number;
+/** Clamp value + dir*step to the valid 1..10 range (0.5 steps). */
+export declare function snapSensitivity(value: number, dir: 1 | -1): number;
+type SensitivityBarProps = {
+    value: number;
+    /** Called on click/drag with the new value (in-memory draft). */
+    onChange: (value: number) => void;
+    /** Called when the interaction ends — persist the draft. */
+    onCommit: () => void;
+};
+/**
+ * Mouse-driven sensitivity slider. Clicking or dragging anywhere on the bar
+ * sets the value proportionally (0.5 steps); the fuller the bar, the higher
+ * the sensitivity, and the 1..10 range caps it by construction.
+ */
+export declare function SensitivityBar({ value, onChange, onCommit }: SensitivityBarProps): React.JSX.Element;
+export {};

package/dist/view/sensitivity-bar.js

@@ -0,0 +1,48 @@
+import { Box, Text } from "ink";
+import { useI18n, useMouseRegion } from "ink-cartridge";
+import React from "react";
+export const SENSITIVITY_MIN = 1;
+export const SENSITIVITY_MAX = 10;
+export const SENSITIVITY_STEP = 0.5;
+/** Bar cells: (10 - 1) / 0.5 steps, so every cell maps to exactly one step. */
+export const BAR_WIDTH = (SENSITIVITY_MAX - SENSITIVITY_MIN) / SENSITIVITY_STEP;
+/** Map a 0..1 ratio to a sensitivity value in 0.5 steps. */
+export function valueFromRatio(ratio) {
+    const r = Math.max(0, Math.min(1, ratio));
+    // BAR_WIDTH cells span exactly the 1..10 range (18 steps of 0.5).
+    return SENSITIVITY_MIN + Math.round(r * BAR_WIDTH) * SENSITIVITY_STEP;
+}
+/** Clamp value + dir*step to the valid 1..10 range (0.5 steps). */
+export function snapSensitivity(value, dir) {
+    return Math.min(SENSITIVITY_MAX, Math.max(SENSITIVITY_MIN, value + dir * SENSITIVITY_STEP));
+}
+/**
+ * Mouse-driven sensitivity slider. Clicking or dragging anywhere on the bar
+ * sets the value proportionally (0.5 steps); the fuller the bar, the higher
+ * the sensitivity, and the 1..10 range caps it by construction.
+ */
+export function SensitivityBar({ value, onChange, onCommit }) {
+    const { t } = useI18n();
+    // priority 1: the bar sits inside the draggable ModalFrame, whose region
+    // overlaps it — the child control must always win the hit test, no matter
+    // the registration order after frame drags.
+    const ref = useMouseRegion({
+        onClick: (event, rect) => {
+            onChange(valueFromX(event.x - rect.x));
+            onCommit();
+        },
+        onDragStart: (event, rect) => onChange(valueFromX(event.x - rect.x)),
+        onDragMove: (event, rect) => onChange(valueFromX(event.x - rect.x)),
+        onDragEnd: () => onCommit(),
+    }, { priority: 1 });
+    const filled = Math.round((value - SENSITIVITY_MIN) / SENSITIVITY_STEP);
+    return (React.createElement(Box, { flexDirection: "column", alignItems: "center", gap: 1 },
+        React.createElement(Box, { ref: ref, flexDirection: "row" },
+            React.createElement(Text, null, filled > 0 ? "█".repeat(filled) : ""),
+            React.createElement(Text, { dimColor: true }, "░".repeat(BAR_WIDTH - filled))),
+        React.createElement(Text, { dimColor: true }, t("settings.sensitivity.hint"))));
+}
+/** Value for a click at `localX` cells inside the bar (0-based). */
+function valueFromX(localX) {
+    return valueFromRatio(localX / BAR_WIDTH);
+}

package/dist/view/settings.js

@@ -1,13 +1,18 @@
 import { Box, Text } from "ink";
 import { back, ModalLayerElementContext, useI18n, useKeyboard, useMouseRegion, useScreenSystem, } from "ink-cartridge";
-import React, { useCallback, useContext, useEffect, useState } from "react";
+import React, { useCallback, useContext, useEffect, useMemo, useState, } from "react";
+import { useSettings } from "../core/settings/useSettings.js";
+import { ModalFrame } from "./modal-frame.js";
+import { SensitivityBar, snapSensitivity } from "./sensitivity-bar.js";
 const LANGUAGES = [
     { code: "en", labelKey: "settings.language.en" },
     { code: "zh", labelKey: "settings.language.zh" },
 ];
 /** Selectable language row with the same hover-highlight style as the menu. */
 function LanguageRow({ label, selected, active, onEnter, onLeave, onClick, }) {
-    const ref = useMouseRegion({ onEnter, onLeave, onClick });
+    // priority 1: rows live inside the draggable ModalFrame; the child must
+    // always win the hit test over the overlapping frame region.
+    const ref = useMouseRegion({ onEnter, onLeave, onClick }, { priority: 1 });
     return (React.createElement(Box, { ref: ref, paddingLeft: 1, paddingRight: 1 },
         React.createElement(Text, { inverse: active },
             active ? "> " : "  ",
@@ -21,11 +26,16 @@ function LanguageRow({ label, selected, active, onEnter, onLeave, onClick, }) {
  */
 function LanguagePicker() {
     const ctx = useContext(ModalLayerElementContext);
-    const { t, setLanguage, currentLanguage } = useI18n();
+    const { t, setLanguage: setI18nLanguage, currentLanguage } = useI18n();
+    const { setLanguage: persistLanguage } = useSettings();
     const { boundKeyboard } = useKeyboard();
     const { closeModalLayer } = useScreenSystem();
     const [index, setIndex] = useState(0);
     const [hovered, setHovered] = useState(null);
+    const applyLanguage = useCallback((code) => {
+        setI18nLanguage(code);
+        persistLanguage(code);
+    }, [setI18nLanguage, persistLanguage]);
     useEffect(() => {
         if (!ctx) {
             return;
@@ -34,27 +44,56 @@ function LanguagePicker() {
             boundKeyboard(["up"], () => setIndex((i) => Math.max(0, i - 1)), { elementId: ctx.id }),
             boundKeyboard(["down"], () => setIndex((i) => Math.min(LANGUAGES.length - 1, i + 1)), { elementId: ctx.id }),
             boundKeyboard(["return"], () => {
-                setLanguage(LANGUAGES[index].code);
+                applyLanguage(LANGUAGES[index].code);
                 closeModalLayer(ctx.modalLayer.layerId);
             }, { elementId: ctx.id }),
             boundKeyboard(["escape"], () => closeModalLayer(ctx.modalLayer.layerId), { elementId: ctx.id }),
         ];
         return () => unbinds.forEach((fn) => fn());
-    }, [boundKeyboard, closeModalLayer, ctx, index, setLanguage]);
+    }, [applyLanguage, boundKeyboard, closeModalLayer, ctx, index]);
     const apply = (code) => {
         if (!ctx) {
             return;
         }
-        setLanguage(code);
+        applyLanguage(code);
         closeModalLayer(ctx.modalLayer.layerId);
     };
-    return (React.createElement(Box, { width: "100%", height: "100%", justifyContent: "center", alignItems: "center" },
-        React.createElement(Box, { flexDirection: "column", borderStyle: "bold", borderColor: "white", backgroundColor: "black", width: 36, alignItems: "center", paddingX: 4, paddingY: 1, gap: 1 },
-            React.createElement(Text, { bold: true }, t("settings.language")),
-            LANGUAGES.map((lang, i) => (React.createElement(LanguageRow, { key: lang.code, label: t(lang.labelKey), selected: currentLanguage === lang.code, active: i === index || hovered === i, onEnter: () => setHovered(i), onLeave: () => setHovered((h) => (h === i ? null : h)), onClick: () => apply(lang.code) }))),
-            React.createElement(Text, { dimColor: true },
-                t("settings.back"),
-                " (Esc)"))));
+    return (React.createElement(ModalFrame, { title: t("settings.language"), footer: React.createElement(Text, { dimColor: true },
+            t("settings.back"),
+            " (Esc)") }, LANGUAGES.map((lang, i) => (React.createElement(LanguageRow, { key: lang.code, label: t(lang.labelKey), selected: currentLanguage === lang.code, active: i === index || hovered === i, onEnter: () => setHovered(i), onLeave: () => setHovered((h) => (h === i ? null : h)), onClick: () => apply(lang.code) })))));
+}
+/**
+ * Modal slider for one wheel sensitivity (cursor or view). The bar is
+ * drag/click driven; dragging updates in memory only, release/click persists.
+ */
+function SensitivityPicker({ sensitivityKey }) {
+    const ctx = useContext(ModalLayerElementContext);
+    const { t } = useI18n();
+    const { boundKeyboard } = useKeyboard();
+    const { closeModalLayer } = useScreenSystem();
+    const { settings, setDraft, setSensitivity, commit } = useSettings();
+    const value = settings.wheel[sensitivityKey];
+    useEffect(() => {
+        if (!ctx) {
+            return;
+        }
+        const unbinds = [
+            boundKeyboard(["left"], () => setSensitivity(sensitivityKey, snapSensitivity(value, -1)), { elementId: ctx.id }),
+            boundKeyboard(["right"], () => setSensitivity(sensitivityKey, snapSensitivity(value, 1)), { elementId: ctx.id }),
+            boundKeyboard(["escape"], () => closeModalLayer(ctx.modalLayer.layerId), { elementId: ctx.id }),
+        ];
+        return () => unbinds.forEach((fn) => fn());
+    }, [boundKeyboard, closeModalLayer, ctx, sensitivityKey, value, setSensitivity]);
+    const labelKey = sensitivityKey === "cursor"
+        ? "settings.sensitivity.cursor"
+        : "settings.sensitivity.view";
+    return (React.createElement(ModalFrame, { title: t(labelKey), footer: React.createElement(Text, { dimColor: true },
+            t("settings.back"),
+            " (Esc)") },
+        React.createElement(SensitivityBar, { value: value, onChange: (v) => setDraft(sensitivityKey, v), onCommit: commit }),
+        React.createElement(Text, null,
+            value.toFixed(1),
+            "\u00D7")));
 }
 /** A single settings entry: label plus its current value; opens a picker on activation. */
 function SettingRow({ label, value, active, onEnter, onLeave, onClick, }) {
@@ -69,7 +108,9 @@ export function Settings() {
     const { t, currentLanguage } = useI18n();
     const { boundKeyboard } = useKeyboard();
     const { openModalLayer, applyElementToModalLayer } = useScreenSystem();
-    const [hovered, setHovered] = useState(false);
+    const { settings } = useSettings();
+    const [index, setIndex] = useState(0);
+    const [hovered, setHovered] = useState(null);
     const openLanguagePicker = useCallback(() => {
         openModalLayer("language", 50);
         applyElementToModalLayer("language", {
@@ -77,19 +118,57 @@ export function Settings() {
             element: LanguagePicker,
         });
     }, [applyElementToModalLayer, openModalLayer]);
+    const openSensitivityPicker = useCallback((key) => {
+        const id = `sensitivity-${key}`;
+        // `element` is a component type; wrap so the picker receives its key.
+        const Picker = () => React.createElement(SensitivityPicker, { sensitivityKey: key });
+        openModalLayer(id, 50);
+        applyElementToModalLayer(id, {
+            elementId: id,
+            element: Picker,
+        });
+    }, [applyElementToModalLayer, openModalLayer]);
+    const currentLabel = LANGUAGES.find((lang) => lang.code === currentLanguage)?.labelKey ??
+        "settings.language.en";
+    const entries = useMemo(() => [
+        {
+            id: "language",
+            label: t("settings.language"),
+            value: t(currentLabel),
+            open: openLanguagePicker,
+        },
+        {
+            id: "cursor",
+            label: t("settings.sensitivity.cursor"),
+            value: `${settings.wheel.cursor.toFixed(1)}×`,
+            open: () => openSensitivityPicker("cursor"),
+        },
+        {
+            id: "view",
+            label: t("settings.sensitivity.view"),
+            value: `${settings.wheel.view.toFixed(1)}×`,
+            open: () => openSensitivityPicker("view"),
+        },
+    ], [
+        t,
+        currentLabel,
+        settings.wheel.cursor,
+        settings.wheel.view,
+        openLanguagePicker,
+        openSensitivityPicker,
+    ]);
     useEffect(() => {
         const unbinds = [
-            boundKeyboard(["return"], () => openLanguagePicker()),
+            boundKeyboard(["up"], () => setIndex((i) => Math.max(0, i - 1))),
+            boundKeyboard(["down"], () => setIndex((i) => Math.min(entries.length - 1, i + 1))),
+            boundKeyboard(["return"], () => entries[index].open()),
             boundKeyboard(["escape", "backspace"], () => back()),
         ];
         return () => unbinds.forEach((fn) => fn());
-    }, [boundKeyboard, openLanguagePicker]);
-    const currentLabel = LANGUAGES.find((lang) => lang.code === currentLanguage)?.labelKey ??
-        "settings.language.en";
+    }, [boundKeyboard, entries, index]);
     return (React.createElement(Box, { flexDirection: "column", justifyContent: "center", alignItems: "center", width: "100%", height: "100%", gap: 2 },
         React.createElement(Text, { bold: true }, t("settings.title")),
-        React.createElement(Box, { flexDirection: "column", gap: 2, marginTop: 2 },
-            React.createElement(SettingRow, { label: t("settings.language"), value: t(currentLabel), active: hovered, onEnter: () => setHovered(true), onLeave: () => setHovered(false), onClick: openLanguagePicker })),
+        React.createElement(Box, { flexDirection: "column", gap: 2, marginTop: 2 }, entries.map((entry, i) => (React.createElement(SettingRow, { key: entry.id, label: entry.label, value: entry.value, active: i === index || hovered === i, onEnter: () => setHovered(i), onLeave: () => setHovered((h) => (h === i ? null : h)), onClick: entry.open })))),
         React.createElement(Box, { marginTop: 4 },
             React.createElement(Text, { dimColor: true },
                 t("settings.back"),

package/dist/view/tool-bar.d.ts

@@ -0,0 +1,51 @@
+import React from "react";
+import type { XtermMouseEvent } from "@cartridge-engine/keyboard-engine";
+/**
+ * Props for a single tool button.
+ *
+ * @prop priority - Hit-test priority over whatever sits underneath (the editor
+ *   surface). Buttons must win so clicking them does not also place the cursor.
+ * @prop onClick - Called on mouse click and on ctrl+enter selection; the event
+ *   is absent for the keyboard path.
+ * @prop text - The text to display on the button.
+ * @prop focused - Keyboard focus (normal-mode navigation); overrides hover.
+ * @prop onDragStart/onDragMove/onDragEnd - Forwarded from the toolbar. The
+ *   engine captures a drag on the pressed region only, so buttons must carry
+ *   the drag handlers or dragging from a button would not move the bar.
+ * @prop dragging - The bar is being dragged; buttons tint green like hover.
+ */
+export type ToolButtonProps = {
+    priority: number;
+    onClick: (event?: XtermMouseEvent) => void;
+    text: string;
+    focused?: boolean;
+    onDragStart?: (event: XtermMouseEvent) => void;
+    onDragMove?: (event: XtermMouseEvent) => void;
+    onDragEnd?: (event: XtermMouseEvent) => void;
+    dragging?: boolean;
+};
+/** One tool entry; the list is the extension point for future tools. */
+export type Tool = {
+    id: string;
+    /** i18n key for the button label. */
+    labelKey: string;
+    /** Placeholder until the file-tree feature lands. */
+    onClick: (event?: XtermMouseEvent) => void;
+};
+export type ToolBarProps = {
+    /** Current keyboard mode, passed down by the editor; drives focus display. */
+    mode?: string | null;
+    /** Tools to render, centered in the bar. Defaults to the file-tree entry. */
+    tools?: Tool[];
+};
+/**
+ * Floating toolbar, bottom-center of the terminal until the user drags it.
+ * Dragging switches it to absolute positioning and clamps it inside the
+ * terminal view (clampFrame). Purely presentational for now: one centered
+ * button with hover/focus states. The editor owns the layer that hosts this
+ * bar (and the ctrl+tab toggle); this component only adds the normal-mode
+ * keyboard navigation (ctrl+left/ctrl+right move the focus ring, ctrl+enter
+ * selects). Insert mode stays mouse-only because those bindings are
+ * mode-restricted and never fire there.
+ */
+export declare function ToolBar({ mode, tools }: ToolBarProps): React.JSX.Element;

package/dist/view/tool-bar.js

@@ -0,0 +1,92 @@
+import { Box, Text, measureElement, useWindowSize } from "ink";
+import { useI18n, useKeyboard, useMouseRegion } from "ink-cartridge";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { clampFrame } from "./frame-clamp.js";
+function ToolButton({ priority, onClick, text, focused = false, onDragStart, onDragMove, onDragEnd, dragging = false, }) {
+    const [hover, setHover] = useState(false);
+    const ref = useMouseRegion({
+        onClick: (event) => onClick(event),
+        onEnter: () => setHover(true),
+        onLeave: () => setHover(false),
+        onDragStart,
+        onDragMove,
+        onDragEnd,
+    }, { priority });
+    // Focus is the keyboard state, so it outranks the transient hover color.
+    const borderColor = focused ? "blue" : hover || dragging ? "green" : "white";
+    return (React.createElement(Box, { ref: ref, borderColor: borderColor, borderStyle: "bold", 
+        // Match the editor's surface so the floating bar reads as part of it.
+        backgroundColor: "#1e1e1e", height: "100%", justifyContent: "center", alignItems: "center", paddingLeft: 2, paddingRight: 2 },
+        React.createElement(Text, null, text)));
+}
+const DEFAULT_TOOLS = [
+    {
+        id: "file-tree",
+        labelKey: "toolbar.fileTree",
+        onClick: () => {
+            // Business logic (opening the file tree) lands here later.
+        },
+    },
+];
+/**
+ * Floating toolbar, bottom-center of the terminal until the user drags it.
+ * Dragging switches it to absolute positioning and clamps it inside the
+ * terminal view (clampFrame). Purely presentational for now: one centered
+ * button with hover/focus states. The editor owns the layer that hosts this
+ * bar (and the ctrl+tab toggle); this component only adds the normal-mode
+ * keyboard navigation (ctrl+left/ctrl+right move the focus ring, ctrl+enter
+ * selects). Insert mode stays mouse-only because those bindings are
+ * mode-restricted and never fire there.
+ */
+export function ToolBar({ mode = null, tools = DEFAULT_TOOLS }) {
+    const { rows, columns } = useWindowSize();
+    const { t } = useI18n();
+    const { boundKeyboard } = useKeyboard();
+    const [activeIndex, setActiveIndex] = useState(0);
+    // null = bar sits at the bottom-center via flex layout; once the user
+    // grabs it, absolute positioning takes over so it follows the cursor.
+    const [pos, setPos] = useState(null);
+    const [dragging, setDragging] = useState(false);
+    const barRef = useRef(null);
+    // Grab offset (where inside the bar the cursor went down) plus the bar's
+    // size at grab time, kept in a ref so drag moves need no re-measurement.
+    const grabRef = useRef({ dx: 0, dy: 0, width: 0, height: 0 });
+    const startDrag = useCallback((event) => {
+        const node = barRef.current;
+        if (!node) {
+            return;
+        }
+        // Measure the bar itself, not the hit region — a button may be the
+        // captured target, and its rect would put the bar's corner at the
+        // button's corner.
+        const m = measureElement(node);
+        grabRef.current = {
+            dx: event.x - m.x - 1,
+            dy: event.y - m.y - 1,
+            width: m.width,
+            height: m.height,
+        };
+        // Switch from flex centering to absolute positioning at the current
+        // rect — seamless, no jump on the first frame.
+        setPos({ top: m.y, left: m.x });
+        setDragging(true);
+    }, []);
+    const moveDrag = useCallback((event) => {
+        const { dx, dy, width, height } = grabRef.current;
+        setPos(clampFrame(event.x - dx - 1, event.y - dy - 1, columns, rows, width, height));
+    }, [columns, rows]);
+    const endDrag = useCallback(() => setDragging(false), []);
+    const showFocus = mode === "normal";
+    useEffect(() => {
+        const unbinds = [
+            boundKeyboard(["ctrl+left"], () => setActiveIndex((i) => (i - 1 + tools.length) % tools.length), { mode: "normal" }),
+            boundKeyboard(["ctrl+right"], () => setActiveIndex((i) => (i + 1) % tools.length), { mode: "normal" }),
+            boundKeyboard(["ctrl+return"], () => tools[activeIndex]?.onClick(), {
+                mode: "normal",
+            }),
+        ];
+        return () => unbinds.forEach((fn) => fn());
+    }, [boundKeyboard, tools, activeIndex]);
+    return (React.createElement(Box, { width: "100%", height: "100%", justifyContent: "center", alignItems: "flex-end" },
+        React.createElement(Box, { ref: barRef, position: pos ? "absolute" : undefined, top: pos?.top, left: pos?.left, height: 4, flexDirection: "row", justifyContent: "center", alignItems: "center" }, tools.map((tool, index) => (React.createElement(ToolButton, { key: tool.id, text: t(tool.labelKey), priority: 1, focused: showFocus && index === activeIndex, onClick: tool.onClick, dragging: dragging, onDragStart: startDrag, onDragMove: moveDrag, onDragEnd: endDrag }))))));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "blots-editor",
-	"version": "0.0.11",
+	"version": "0.0.13",
 	"description": "A lightweight Markdown editor for the terminal, built on ink-cartridge",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -56,7 +56,8 @@
 		"gradient-string": "^2.0.2",
 		"ink-cartridge": "*",
 		"oh-my-logo": "^0.5.0",
-		"string-width": "^8.2.2"
+		"string-width": "^8.2.2",
+		"zod": "^4.4.3"
 	},
 	"devDependencies": {
 		"@types/gradient-string": "^1.1.6",