@gavin-hu/my-pi-agent 0.13.1 → 0.15.0

package/extensions/bytefly/panel/settings.ts

@@ -6,44 +6,56 @@
  * views, cycling, validation, and grouping — so the screen and the runtime share
  * one definition and the tests need no host.
  *
- * The catalogue covers every scalar preference: booleans, enums, short strings,
- * and — with `doctor.timeoutMs` — a number. Each row states its own rule, so a
- * value the screen accepts is a value the loader keeps. Arrays (`doctor.skip`),
- * the `rates` table, and `price.peak` stay JSON edits: a list, a table, and a
- * nested object are not one row.
+ * The catalogue is curated rather than exhaustive: it holds the preferences a
+ * person changes, across every extension of the package, and each row states its
+ * own rule so a value the screen accepts is a value the loader keeps. The rest of
+ * the document stays JSON, reachable from the screen's JSON pane: a list
+ * (`doctor.skip`), a table (`price.rates`), and a schedule (`price.peak`) are not
+ * one row.
+ *
+ * Four sections have a normalizer here, so the screen shows what the footer, the
+ * notifier, and the doctor keep. The six owned by other extensions are read as the
+ * file states them, because importing their normalizer would be one extension
+ * importing another's module; each such row declares the loader's default, and
+ * `test/settings-coverage.test.ts` holds the pair together.
  */
 
 import { configSection, configValueAt } from "../../../lib/config.ts";
-import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import { DEFAULT_CHROME_CONFIG, isRailGlyph, normalizeChromeConfig } from "../chrome.ts";
-import { DEFAULT_CONFIG as DEFAULT_DOCTOR_CONFIG, normalizeConfig as normalizeDoctorConfig } from "../doctor/config.ts";
+import {
+	DEFAULT_CONFIG as DEFAULT_DOCTOR_CONFIG,
+	normalizeConfig as normalizeDoctorConfig,
+	TIMEOUT_MS_RANGE,
+} from "../doctor/config.ts";
 import {
 	CURRENCY_DEFAULTS,
 	DEFAULT_BYTEFLY_CONFIG,
 	DEFAULT_CURRENCY,
+	MAX_BUDGET,
+	MAX_DECIMALS,
 	normalizeByteflyConfig,
 } from "../footer/price/config.ts";
 import type { CurrencyCode } from "../footer/price/types.ts";
-import { DEFAULT_NOTIFY_CONFIG, normalizeNotifyConfig } from "../notify/config.ts";
+import { DEFAULT_NOTIFY_CONFIG, MAX_TITLE_LENGTH, normalizeNotifyConfig } from "../notify/config.ts";
 import type { Settings, WriteScope } from "../picker/types.ts";
 
 /** Where a preference is stored. */
-export type SettingSource = "app" | "bytefly";
+type SettingSource = "app" | "bytefly";
 
 /** The row control a preference uses. */
-export type SettingKind = "boolean" | "enum" | "text";
+type SettingKind = "boolean" | "enum" | "text";
 
 /** Where the effective value came from. */
-export type SettingOrigin = "default" | "global" | "project" | "inherited";
+type SettingOrigin = "default" | "global" | "project" | "inherited";
 
 /** One curated value a row can take. */
-export interface SettingOption {
+interface SettingOption {
 	value: string;
 	label: string;
 }
 
 /** What a text row accepts, checked before a write so the file cannot hold less. */
-export interface TextRule {
+interface TextRule {
 	/** Longest accepted value, in the units the loader slices with. */
 	maxLength: number;
 	/** Why `raw` cannot be stored, or `undefined` when it can. */
@@ -51,22 +63,32 @@ export interface TextRule {
 }
 
 /** One heading in the Settings list. */
-export interface SettingGroup {
+interface SettingGroup {
 	key: string;
 	label: string;
 }
 
 /** The `bytefly.json` sections the Settings section can read and write. */
-export type ConfigSectionName = "notify" | "chrome" | "doctor" | "price";
+export type ConfigSectionName =
+	| "notify"
+	| "chrome"
+	| "doctor"
+	| "price"
+	| "worktree"
+	| "rewind"
+	| "job"
+	| "watch"
+	| "memory"
+	| "goal";
 
 /** Where a `bytefly.json` row lives: a section, and the path to its leaf. */
-export interface SettingConfig {
+interface SettingConfig {
 	section: ConfigSectionName;
 	path: readonly string[];
 }
 
 /** One `bytefly.json` leaf a row writes alongside its own. */
-export interface SettingLeaf {
+interface SettingLeaf {
 	section: ConfigSectionName;
 	path: readonly string[];
 	value: unknown;
@@ -113,10 +135,12 @@ export interface SettingsSnapshot {
 	app: Settings;
 	global: Record<string, unknown>;
 	project: Record<string, unknown>;
+	/** Theme names the Theme row offers, narrowed to this package's palettes by the caller. */
+	themes: readonly string[];
 }
 
 /** One rendered group: its heading and the rows under it. */
-export interface GroupedSettings {
+interface GroupedSettings {
 	key: string;
 	label: string;
 	views: SettingView[];
@@ -130,6 +154,10 @@ export const SETTING_GROUPS: readonly SettingGroup[] = [
 	{ key: "pricing", label: "Pricing" },
 	{ key: "transcript", label: "Transcript" },
 	{ key: "terminal", label: "Terminal" },
+	{ key: "worktree", label: "Worktree" },
+	{ key: "snapshots", label: "Snapshots" },
+	{ key: "jobs", label: "Jobs and watchers" },
+	{ key: "memory", label: "Memory" },
 ];
 
 const ON_OFF: readonly SettingOption[] = [
@@ -147,8 +175,8 @@ const METHOD_OPTIONS: readonly SettingOption[] = [
 	{ value: "notify-send", label: "Linux" },
 ];
 
-/** Cost precision 0-4, the range the `price` section clamps `decimals` to. */
-const DECIMALS_OPTIONS: readonly SettingOption[] = [0, 1, 2, 3, 4].map((value) => ({
+/** Cost precision 0 through the loader's ceiling, the range `price` clamps `decimals` to. */
+const DECIMALS_OPTIONS: readonly SettingOption[] = Array.from({ length: MAX_DECIMALS + 1 }, (_, value) => ({
 	value: String(value),
 	label: String(value),
 }));
@@ -292,7 +320,7 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		fallback: "Pi",
 		options: [],
 		text: {
-			maxLength: 40,
+			maxLength: MAX_TITLE_LENGTH,
 			validate: (raw) => (raw.trim() === "" ? "A title is required." : undefined),
 		},
 		config: { section: "notify", path: ["title"] },
@@ -313,13 +341,13 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		id: "doctor.timeoutMs",
 		group: "diagnostics",
 		label: "Probe timeout",
-		description: "How long one doctor probe may take, in milliseconds; 100 to 30000.",
+		description: `How long one doctor probe may take, in milliseconds; ${TIMEOUT_MS_RANGE.min} to ${TIMEOUT_MS_RANGE.max}.`,
 		source: "bytefly",
 		kind: "text",
 		fallback: String(DEFAULT_DOCTOR_CONFIG.timeoutMs),
 		json: "number",
 		options: [],
-		text: integerRule(100, 30_000),
+		text: integerRule(TIMEOUT_MS_RANGE.min, TIMEOUT_MS_RANGE.max),
 		config: { section: "doctor", path: ["timeoutMs"] },
 	},
 	{
@@ -367,7 +395,7 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		fallback: "0",
 		json: "number",
 		options: [],
-		text: amountRule(0, 10_000_000),
+		text: amountRule(0, MAX_BUDGET),
 		config: { section: "price", path: ["budget"] },
 	},
 	{
@@ -377,11 +405,25 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		description: "The single-column glyph that leads a tool result or notice body, e.g. ╎ │ ┃ ▏.",
 		source: "bytefly",
 		kind: "text",
-		fallback: GLYPHS.divider,
+		fallback: DEFAULT_CHROME_CONFIG.rail,
 		options: [],
 		text: RAIL_RULE,
 		config: { section: "chrome", path: ["rail"] },
 	},
+	{
+		id: "goal.achieved",
+		group: "transcript",
+		label: "Achieved goal",
+		description: "How a completed goal renders: the dimmed rail line, or nothing.",
+		source: "bytefly",
+		kind: "enum",
+		fallback: "hide",
+		options: [
+			{ value: "show", label: "Show" },
+			{ value: "hide", label: "Hide" },
+		],
+		config: { section: "goal", path: ["achieved"] },
+	},
 	{
 		id: "outputPad",
 		group: "transcript",
@@ -396,6 +438,18 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 			{ value: "1", label: "1" },
 		],
 	},
+	{
+		id: "theme",
+		group: "terminal",
+		label: "Theme",
+		description:
+			"Pi's color theme, chosen from the palettes this package ships; `system` follows the terminal's colors. Takes effect after reload.",
+		source: "app",
+		kind: "enum",
+		fallback: "system",
+		// The host supplies this package's theme names in the snapshot; the static list stays empty.
+		options: [],
+	},
 	{
 		id: "showHardwareCursor",
 		group: "terminal",
@@ -407,28 +461,164 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		json: "boolean",
 		options: ON_OFF,
 	},
+	{
+		id: "worktree.baseRef",
+		group: "worktree",
+		label: "Base ref",
+		description: "Where a new worktree branches from: the remote default branch, or the current local HEAD.",
+		source: "bytefly",
+		kind: "enum",
+		fallback: "fresh",
+		options: [
+			{ value: "fresh", label: "Fresh" },
+			{ value: "head", label: "Head" },
+		],
+		config: { section: "worktree", path: ["baseRef"] },
+	},
+	{
+		id: "worktree.branchPrefix",
+		group: "worktree",
+		label: "Branch prefix",
+		description: "Prepended to every branch a managed worktree creates.",
+		source: "bytefly",
+		kind: "text",
+		fallback: "worktree-",
+		options: [],
+		text: {
+			// The loader trims and rejects an empty prefix but sets no ceiling; this
+			// only stops a runaway buffer.
+			maxLength: 80,
+			validate: (raw) => (raw.trim() === "" ? "A prefix is required." : undefined),
+		},
+		config: { section: "worktree", path: ["branchPrefix"] },
+	},
+	{
+		id: "worktree.fetchRemote",
+		group: "worktree",
+		label: "Fetch remote",
+		description: "Fetch the remote before branching, so a new worktree starts from its latest commit.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "worktree", path: ["fetchRemote"] },
+	},
+	{
+		id: "worktree.pruneAfterDays",
+		group: "worktree",
+		label: "Prune after (days)",
+		description: "Age at which `/worktree prune` removes a clean worktree nobody is using.",
+		source: "bytefly",
+		kind: "text",
+		fallback: "7",
+		json: "number",
+		options: [],
+		text: integerRule(0, 3650),
+		config: { section: "worktree", path: ["pruneAfterDays"] },
+	},
+	{
+		id: "rewind.autoSnapshots",
+		group: "snapshots",
+		label: "Automatic snapshots",
+		description: "Take one rewind snapshot per prompt, before the first mutating tool call.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "rewind", path: ["autoSnapshots"] },
+	},
+	{
+		id: "rewind.max",
+		group: "snapshots",
+		label: "Snapshots kept",
+		description: "Snapshot refs kept per repository, including pre-restore safety snapshots; 0 keeps none.",
+		source: "bytefly",
+		kind: "text",
+		fallback: "20",
+		json: "number",
+		options: [],
+		text: integerRule(0, 1000),
+		config: { section: "rewind", path: ["max"] },
+	},
+	{
+		id: "rewind.safetySnapshot",
+		group: "snapshots",
+		label: "Safety snapshot",
+		description: "Snapshot the current state before a restore, so a rewind can itself be undone.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "rewind", path: ["safetySnapshot"] },
+	},
+	{
+		id: "job.wakeOnFinish",
+		group: "jobs",
+		label: "Wake when a job finishes",
+		description: "Start one agent turn when any background job finishes.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "false",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "job", path: ["wakeOnFinish"] },
+	},
+	{
+		id: "job.detachedByDefault",
+		group: "jobs",
+		label: "Keep jobs after exit",
+		description: "Leave jobs running when the session ends, unless the job opts out.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "false",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "job", path: ["detachedByDefault"] },
+	},
+	{
+		id: "watch.wakeOnMatch",
+		group: "jobs",
+		label: "Wake on a match",
+		description: "Start one agent turn when a watcher matches while the agent is idle.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "false",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "watch", path: ["wakeOnMatch"] },
+	},
+	{
+		id: "memory.inject",
+		group: "memory",
+		label: "Inject notes",
+		description: "Put stored memory notes in context before each run.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "memory", path: ["inject"] },
+	},
 ];
 
+/** The one refusal for a Project write while the project is untrusted. */
+export const UNTRUSTED_SETTINGS_NOTE = "Project is not trusted; settings can only be changed in Global scope.";
+
 /** The rows a scope can write: app rows are personal-file only. */
 export function rowsForScope(scope: WriteScope): readonly SettingDescriptor[] {
 	return scope === "global" ? SETTING_ROWS : SETTING_ROWS.filter((row) => row.source === "bytefly");
 }
 
-/** The number of rows the section shows for `scope`. */
-export function countSettings(scope: WriteScope): number {
-	return rowsForScope(scope).length;
-}
-
-/** Whether `raw` is one of a row's curated options. */
-export function validValue(row: SettingDescriptor, raw: string): boolean {
-	return row.options.some((option) => option.value === raw);
-}
-
 /**
  * Why a text row cannot store `raw`, or `undefined` when it can.
  *
- * The limits mirror the loaders (`notify.title` is sliced to 40, the currency
- * symbol to 4) so the editor cannot save a value the next read shortens.
+ * The limits are the loaders' own (`notify.title` is sliced to `MAX_TITLE_LENGTH`,
+ * the rail to one column) so the editor cannot save a value the next read shortens.
+ * A row that is not text is refused here rather than in the caller, so a programmatic
+ * `setValue` gets the same reason the screen would show.
  */
 export function textError(row: SettingDescriptor, raw: string): string | undefined {
 	const rule = row.text;
@@ -439,9 +629,18 @@ export function textError(row: SettingDescriptor, raw: string): string | undefin
 	return rule.validate?.(raw);
 }
 
+/** The Theme row's values: `system` first, then the names the caller offers. */
+function themeOptions(themes: readonly string[]): readonly SettingOption[] {
+	const names = ["system", ...new Set(themes.filter((name) => name !== "" && name !== "system"))];
+	return names.map((name) => ({ value: name, label: name }));
+}
+
 /** The display label for `raw`, or the raw value when it is a valid custom one. */
 function labelFor(row: SettingDescriptor, raw: string): string {
-	return row.options.find((option) => option.value === raw)?.label ?? raw;
+	const option = row.options.find((entry) => entry.value === raw);
+	if (option) return option.label;
+	// A stored light/dark pair is Pi's automatic mode, not a missing theme.
+	return row.id === "theme" && raw.includes("/") ? `${raw} (automatic)` : raw;
 }
 
 /** Read an app preference and where it came from. */
@@ -449,18 +648,23 @@ function appValue(snapshot: SettingsSnapshot, row: SettingDescriptor): { value:
 	switch (row.id) {
 		case "byteflyUi": {
 			const quiet = snapshot.app.quietStartup;
-			return { value: quiet === true ? "true" : "false", origin: quiet === undefined ? "default" : "global" };
+			return { value: quiet === true ? "true" : row.fallback, origin: quiet === undefined ? "default" : "global" };
 		}
 		case "outputPad":
 			return {
-				value: snapshot.app.outputPad === 0 ? "0" : "1",
+				value: snapshot.app.outputPad === 0 ? "0" : row.fallback,
 				origin: snapshot.app.outputPad === undefined ? "default" : "global",
 			};
 		case "showHardwareCursor":
 			return {
-				value: snapshot.app.showHardwareCursor === true ? "true" : "false",
+				value: snapshot.app.showHardwareCursor === true ? "true" : row.fallback,
 				origin: snapshot.app.showHardwareCursor === undefined ? "default" : "global",
 			};
+		case "theme": {
+			const theme = snapshot.app.theme;
+			const set = typeof theme === "string" && theme !== "";
+			return { value: set ? theme : row.fallback, origin: set ? "global" : "default" };
+		}
 		default:
 			throw new Error(`Unknown app setting ${row.id}`);
 	}
@@ -473,7 +677,11 @@ function statesConfig(config: SettingConfig, document: Record<string, unknown>):
 
 /** Where the effective value came from: the project file, the personal one, or nothing. */
 function originFor(config: SettingConfig, snapshot: SettingsSnapshot, scope: WriteScope): SettingOrigin {
-	if (scope === "project") return statesConfig(config, snapshot.project) ? "project" : "inherited";
+	if (scope === "project") {
+		if (statesConfig(config, snapshot.project)) return "project";
+		if (statesConfig(config, snapshot.global)) return "inherited";
+		return "default";
+	}
 	return statesConfig(config, snapshot.global) ? "global" : "default";
 }
 
@@ -484,7 +692,11 @@ type SectionReader = (
 	path: readonly string[],
 ) => unknown;
 
-const SECTION_READERS: Record<ConfigSectionName, SectionReader> = {
+/**
+ * The four sections bytefly owns, each read through its own normalizer so the
+ * screen shows the value the loader keeps.
+ */
+const SECTION_READERS: Partial<Record<ConfigSectionName, SectionReader>> = {
 	notify: (globalRaw, projectRaw, path) =>
 		configValueAt(normalizeNotifyConfig(projectRaw, normalizeNotifyConfig(globalRaw, DEFAULT_NOTIFY_CONFIG)), path),
 	chrome: (globalRaw, projectRaw, path) =>
@@ -495,7 +707,22 @@ const SECTION_READERS: Record<ConfigSectionName, SectionReader> = {
 		configValueAt(normalizeByteflyConfig(projectRaw, normalizeByteflyConfig(globalRaw, DEFAULT_BYTEFLY_CONFIG)), path),
 };
 
-/** Read a `bytefly.json` preference, normalized over the global section. */
+/**
+ * Read a leaf whose owning extension owns the normalizer.
+ *
+ * A section without a reader here belongs to another extension, and importing its
+ * normalizer would be one extension importing another's module. So the row states
+ * the loader's default in `fallback`, `test/settings-coverage.test.ts` holds the
+ * two together, and the visible cost is that a hand-edited value outside the
+ * loader's clamp shows as written until it is reset.
+ */
+function rawLeaf(snapshot: SettingsSnapshot, config: SettingConfig, scope: WriteScope): unknown {
+	const projectLeaf =
+		scope === "project" ? configValueAt(configSection(snapshot.project, config.section), config.path) : undefined;
+	return projectLeaf ?? configValueAt(configSection(snapshot.global, config.section), config.path);
+}
+
+/** Read a `bytefly.json` preference: normalized where bytefly owns the section. */
 function byteflyValue(
 	snapshot: SettingsSnapshot,
 	row: SettingDescriptor,
@@ -505,8 +732,12 @@ function byteflyValue(
 	if (!config) throw new Error(`Setting ${row.id} has no config section`);
 	const globalRaw = configSection(snapshot.global, config.section);
 	const projectRaw = scope === "project" ? configSection(snapshot.project, config.section) : undefined;
-	const leaf = SECTION_READERS[config.section](globalRaw, projectRaw, config.path);
+	const reader = SECTION_READERS[config.section];
+	const leaf = reader ? reader(globalRaw, projectRaw, config.path) : rawLeaf(snapshot, config, scope);
 	return {
+		// A normalizer is total, so its fallback only covers a future row whose
+		// normalizer has no default yet; a raw read needs it when neither document
+		// states the key.
 		value: leaf === undefined ? row.fallback : String(leaf),
 		origin: originFor(config, snapshot, scope),
 	};
@@ -515,8 +746,10 @@ function byteflyValue(
 /** Build the rows for `scope` from a snapshot. */
 export function settingViews(snapshot: SettingsSnapshot, scope: WriteScope): SettingView[] {
 	return rowsForScope(scope).map((row) => {
+		const options = row.id === "theme" ? themeOptions(snapshot.themes) : row.options;
 		const { value, origin } = row.source === "app" ? appValue(snapshot, row) : byteflyValue(snapshot, row, scope);
-		return { ...row, value, valueLabel: labelFor(row, value), origin };
+		const view = { ...row, options, value };
+		return { ...view, valueLabel: labelFor(view, value), origin };
 	});
 }
 

package/extensions/bytefly/panel/themes.ts

@@ -0,0 +1,32 @@
+/**
+ * Which themes the Settings **Theme** row offers: this package's own two, not
+ * every theme in play.
+ *
+ * The host resolves Pi's built-ins, this package's palettes, and any user or
+ * project theme into one list, but the row writes Pi's single `theme`
+ * preference from a bytefly screen, so it offers only the palettes this package
+ * ships and can vouch for. The file's directory identifies a shipped theme, not
+ * its name: `themes/` is the manifest's own resource glob, so a renamed palette
+ * or a look-alike name cannot drift the list away from what the package loads.
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** This package's `themes/` directory. */
+export const SHIPPED_THEMES_DIR = resolve(fileURLToPath(new URL("../../../themes", import.meta.url)));
+
+/** One theme as the host reports it. */
+export interface HostTheme {
+	name: string;
+	path?: string;
+}
+
+/** The shipped theme names in the host's order; a pathless or foreign theme is dropped. */
+export function shippedThemeNames(themes: readonly HostTheme[]): string[] {
+	return themes.filter(isShipped).map((theme) => theme.name);
+}
+
+function isShipped(theme: HostTheme): boolean {
+	return theme.path !== undefined && dirname(resolve(theme.path)) === SHIPPED_THEMES_DIR;
+}

package/extensions/bytefly/panel/tui/editing.ts

@@ -0,0 +1,77 @@
+/**
+ * The panel's text-editing state machine.
+ *
+ * One key in, the next editing state out; the component owns the settings write,
+ * the write chain, and the repaint. Esc cancels the edit instead of closing the
+ * screen, Enter asks the caller to commit, and everything else the screen binds
+ * is inert until the editor closes.
+ */
+
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { isCloseKey } from "../../../../lib/tui/cursor.ts";
+
+/** Bracketed-paste markers a terminal wraps around pasted text. */
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+
+/** The text row being edited: its id, the buffer, and the caret offset. */
+export interface EditingState {
+	id: string;
+	buffer: string;
+	caret: number;
+}
+
+/** What one editing key asked for. */
+export type EditAction =
+	| { kind: "cancel" }
+	| { kind: "commit" }
+	| { kind: "update"; state: EditingState; changed: boolean };
+
+/**
+ * Apply one key to the editing state.
+ *
+ * `maxLength` comes from the setting's text rule; an undefined limit means the
+ * row has no text rule, so typed characters are refused rather than stored
+ * unvalidated. A key that changes nothing (Backspace at the start, a refused
+ * character) reports `changed: false`, so the caller does not ask for a frame.
+ */
+export function applyEditKey(data: string, state: EditingState, maxLength: number | undefined): EditAction {
+	if (isCloseKey(data)) return { kind: "cancel" };
+	if (matchesKey(data, Key.enter)) return { kind: "commit" };
+
+	const { buffer, caret } = state;
+	let next = state;
+	if (matchesKey(data, Key.backspace)) {
+		if (caret > 0) next = { ...state, buffer: buffer.slice(0, caret - 1) + buffer.slice(caret), caret: caret - 1 };
+	} else if (matchesKey(data, Key.delete)) {
+		if (caret < buffer.length) next = { ...state, buffer: buffer.slice(0, caret) + buffer.slice(caret + 1) };
+	} else if (matchesKey(data, Key.left)) {
+		next = { ...state, caret: Math.max(0, caret - 1) };
+	} else if (matchesKey(data, Key.right)) {
+		next = { ...state, caret: Math.min(buffer.length, caret + 1) };
+		// `Ctrl+A`/`Ctrl+E` are the emacs spellings of Home/End, which pi-tui's
+		// `Key.home`/`Key.end` do not match; both are offered because a terminal
+		// may send either.
+	} else if (matchesKey(data, Key.home) || matchesKey(data, "ctrl+a")) {
+		next = { ...state, caret: 0 };
+	} else if (matchesKey(data, Key.end) || matchesKey(data, "ctrl+e")) {
+		next = { ...state, caret: buffer.length };
+	} else if (matchesKey(data, "ctrl+u")) {
+		next = { ...state, buffer: "", caret: 0 };
+	} else {
+		// A pasted chunk arrives wrapped in bracketed-paste markers. Its ESC is
+		// dropped by the filter below, which would leave `[200~` in the value, so
+		// strip the markers first, the way Pi's own Input and Editor do.
+		const text = data.replaceAll(PASTE_START, "").replaceAll(PASTE_END, "");
+		// Anything else must be printable; control sequences are not text.
+		const typed = [...text].filter((char) => char >= " " && char !== "\u007f").join("");
+		if (typed && maxLength !== undefined && buffer.length + typed.length <= maxLength) {
+			next = {
+				...state,
+				buffer: buffer.slice(0, caret) + typed + buffer.slice(caret),
+				caret: caret + typed.length,
+			};
+		}
+	}
+	return { kind: "update", state: next, changed: next.buffer !== buffer || next.caret !== caret };
+}

package/extensions/bytefly/panel/tui/entries.ts

@@ -27,6 +27,30 @@ export function isSelectable(entry: PanelEntry | undefined): boolean {
 	return entryKey(entry) !== undefined;
 }
 
+/**
+ * One display window as ordinals over the selectable rows it contains.
+ *
+ * The range row counts rows, not entries: a list of twenty-nine settings in ten
+ * groups spans thirty-nine entries, but `showing 3–5 of 29` is what the user can
+ * focus. `formatRange` prints `start + 1` through `end`, so the ordinals here are
+ * zero-based and `end` is exclusive.
+ */
+export function selectableRange(
+	entries: readonly PanelEntry[],
+	window: { start: number; end: number },
+): { start: number; end: number; total: number } {
+	let before = 0;
+	let shown = 0;
+	let total = 0;
+	for (let index = 0; index < entries.length; index += 1) {
+		if (!isSelectable(entries[index])) continue;
+		total += 1;
+		if (index < window.start) before += 1;
+		else if (index < window.end) shown += 1;
+	}
+	return { start: before, end: before + shown, total };
+}
+
 /** The next selectable entry from `from` in `direction`, or `undefined`. */
 export function nextRow(entries: PanelEntry[], from: number, direction: -1 | 1): number | undefined {
 	for (let index = from + direction; index >= 0 && index < entries.length; index += direction) {