H4: string and path settings controls, live completion and tooltip settings

- Settings dialog: every string setting gets a text field with in-place
  hints (quotes or spaces around a path, control characters, length);
  keys ending in path/executable also get "Browse…" through the dialog
  plugin's native picker (new desktop IPC pick_file). git.executable
  from M4.1 gets the control without UI changes.
- settings.open {section?, query?} for agents and live checks.
- New keys editor.completion.autoPopup, editor.completion.delayMs and
  editor.hover.delayMs; the assist module reads them live through
  CodeMirror compartments.
- Tests: engine settings test, control/engine key lists, Vitest for the
  controls and the live wiring. Docs: architecture, ui-parity, parity
  Settings row, gaps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-25 13:10:19 +01:00
parent b0f8550aeb
commit 197d5b7d27
19 changed files with 1149 additions and 41 deletions

View file

@ -10,7 +10,7 @@ import { renderMarkdown } from "./markdown";
import { engineAssistTransport, queryAt } from "./request";
import { toHover, type AssistBuffer, type AssistTransport } from "./types";
/** Milliseconds the pointer rests before the hover is asked for. */
/** Default milliseconds the pointer rests before the hover is asked for (`editor.hover.delayMs`). */
export const HOVER_DELAY = 350;
/**
@ -60,10 +60,15 @@ export async function hoverAt(
*
* @param buffer - the buffer the editor state shows.
* @param transport - how to reach the engine.
* @param delay - milliseconds the pointer rests before the hover is asked for.
*/
export function lspHover(buffer: AssistBuffer, transport: AssistTransport = engineAssistTransport): Extension {
export function lspHover(
buffer: AssistBuffer,
transport: AssistTransport = engineAssistTransport,
delay: number = HOVER_DELAY,
): Extension {
return hoverTooltip((view, pos) => hoverAt(view, pos, buffer, transport), {
hoverTime: HOVER_DELAY,
hoverTime: delay,
hideOnChange: true,
});
}

View file

@ -5,8 +5,10 @@
* queries, see `request.ts`).
*
* {@link assistExtensions} is the hook the editor uses: PHP files of a
* buffer get the extensions, everything else none. Colours come from
* `--lt-*` tokens only; strings from the catalog.
* buffer get the extensions, everything else none. Completion and hover
* follow the assist settings live (`settings.ts`: auto popup, completion
* delay, hover delay). Colours come from `--lt-*` tokens only; strings
* from the catalog.
*/
import { autocompletion } from "@codemirror/autocomplete";
import type { Extension } from "@codemirror/state";
@ -17,6 +19,7 @@ import { itemOf, lspCompletionSource } from "./completion";
import { lspHover } from "./hover";
import { kindIcon } from "./icons";
import { engineAssistTransport } from "./request";
import { liveAssistSettings, storeAssistSettings, type AssistSettings, type AssistSettingsSource } from "./settings";
import { lspSignatureHelp } from "./signature";
import type { AssistBuffer, AssistTransport } from "./types";
@ -122,30 +125,48 @@ const assistTheme: Extension = EditorView.theme({
},
});
/**
* The completion extension for given settings: typing opens the list only
* with auto popup on, after the completion delay.
*
* @param buffer - the buffer the editor state shows.
* @param transport - how to reach the engine.
* @param settings - the assist settings.
*/
function completionExtension(buffer: AssistBuffer, transport: AssistTransport, settings: AssistSettings): Extension {
return autocompletion({
override: [lspCompletionSource(buffer, transport)],
activateOnTyping: settings.autoPopup,
activateOnTypingDelay: settings.completionDelay,
icons: false,
addToOptions: [{ render: (completion) => kindIcon(completion.type ?? "text"), position: 20 }],
optionClass: (completion) => (itemOf.get(completion)?.deprecated === true ? "lt-assist-deprecated" : ""),
});
}
/**
* The assist extensions of an editor state.
*
* @param path - project-relative path of the file.
* @param buffer - the buffer it shows; none for states without one.
* @param transport - how to reach the engine.
* @param settings - where the assist settings come from; the settings store by default.
* @returns the extensions; empty unless a PHP file of a buffer.
*/
export function assistExtensions(
path: string,
buffer: AssistBuffer | undefined,
transport: AssistTransport = engineAssistTransport,
settings: AssistSettingsSource = storeAssistSettings,
): Extension {
if (!buffer || languageOf(path) !== "php") {
return [];
}
return [
autocompletion({
override: [lspCompletionSource(buffer, transport)],
icons: false,
addToOptions: [{ render: (completion) => kindIcon(completion.type ?? "text"), position: 20 }],
optionClass: (completion) => (itemOf.get(completion)?.deprecated === true ? "lt-assist-deprecated" : ""),
}),
lspHover(buffer, transport),
liveAssistSettings(settings, [
(values) => completionExtension(buffer, transport, values),
(values) => lspHover(buffer, transport, values.hoverDelay),
]),
lspSignatureHelp(buffer, transport),
assistTracker(buffer, transport),
assistTheme,

View file

@ -0,0 +1,195 @@
/**
* The settings of code assistance (H4), read live from the settings store:
*
* - `editor.completion.autoPopup` (bool, default true): whether typing
* opens the completion list; the completion shortcut always does.
* - `editor.completion.delayMs` (0–2000, default 0): how long typing has
* to pause before completion is asked for.
* - `editor.hover.delayMs` (100–3000, default 350): how long the pointer
* rests before the hover documentation is asked for.
*
* {@link liveAssistSettings} keeps an editor state's completion and hover
* extensions in step with these values: a change from the dialog, the
* control channel or an agent reconfigures every open editor at once.
*/
import type { Extension } from "@codemirror/state";
import { Compartment, StateEffect, StateField } from "@codemirror/state";
import { ViewPlugin, type EditorView } from "@codemirror/view";
import { getActivePinia } from "pinia";
import { watch } from "vue";
import { useSettingsStore } from "../../../stores/settings";
/** The assist settings with values the editor can use. */
export interface AssistSettings {
/** Whether typing opens the completion list. */
autoPopup: boolean;
/** Milliseconds typing pauses before completion is asked for. */
completionDelay: number;
/** Milliseconds the pointer rests before the hover is asked for. */
hoverDelay: number;
}
/** Setting keys of the assist settings. */
export const ASSIST_SETTING_KEYS = {
autoPopup: "editor.completion.autoPopup",
completionDelay: "editor.completion.delayMs",
hoverDelay: "editor.hover.delayMs",
} as const;
/** The engine's defaults, used while a value is missing or unusable. */
export const ASSIST_DEFAULTS: Readonly<AssistSettings> = {
autoPopup: true,
completionDelay: 0,
hoverDelay: 350,
};
/** Where the assist settings come from, and how changes are followed. */
export interface AssistSettingsSource {
/** The current values. */
current(): AssistSettings;
/**
* Calls `listener` after the values change.
*
* @returns a function that stops following.
*/
subscribe(listener: () => void): () => void;
}
/**
* A whole number from untrusted data, clamped to a range.
*
* @param value - the data.
* @param min - smallest value.
* @param max - largest value.
* @param fallback - used when the data is no finite number.
*/
function clampInt(value: unknown, min: number, max: number, fallback: number): number {
if (typeof value !== "number" || !Number.isFinite(value)) {
return fallback;
}
return Math.min(max, Math.max(min, Math.round(value)));
}
/**
* Reads the assist settings from setting values (unchecked), with the
* defaults for missing or malformed values and numbers clamped to the
* engine's ranges.
*
* @param values - setting values by key.
*/
export function toAssistSettings(values: Readonly<Record<string, unknown>>): AssistSettings {
const autoPopup = values[ASSIST_SETTING_KEYS.autoPopup];
return {
autoPopup: typeof autoPopup === "boolean" ? autoPopup : ASSIST_DEFAULTS.autoPopup,
completionDelay: clampInt(values[ASSIST_SETTING_KEYS.completionDelay], 0, 2000, ASSIST_DEFAULTS.completionDelay),
hoverDelay: clampInt(values[ASSIST_SETTING_KEYS.hoverDelay], 100, 3000, ASSIST_DEFAULTS.hoverDelay),
};
}
/**
* Whether two sets of assist settings are equal.
*
* @param a - one set.
* @param b - the other.
*/
export function sameAssistSettings(a: AssistSettings, b: AssistSettings): boolean {
return a.autoPopup === b.autoPopup && a.completionDelay === b.completionDelay && a.hoverDelay === b.hoverDelay;
}
/**
* The settings store of the active Pinia as a source. Without an active
* Pinia (an editor used outside the app) it gives the defaults and never
* changes.
*/
export const storeAssistSettings: AssistSettingsSource = {
current() {
const pinia = getActivePinia();
return pinia ? toAssistSettings(useSettingsStore(pinia).values) : { ...ASSIST_DEFAULTS };
},
subscribe(listener) {
const pinia = getActivePinia();
if (!pinia) {
return () => undefined;
}
const store = useSettingsStore(pinia);
return watch(
() => toAssistSettings(store.values),
(next, previous) => {
if (!sameAssistSettings(next, previous)) {
listener();
}
},
);
},
};
/** Records which settings an editor state's assist extensions were built with. */
const applied = StateEffect.define<AssistSettings>();
/** The settings the state's assist extensions use. */
const appliedField = StateField.define<AssistSettings>({
create: () => ({ ...ASSIST_DEFAULTS }),
update: (value, tr) => {
for (const effect of tr.effects) {
if (effect.is(applied)) {
return effect.value;
}
}
return value;
},
});
/** Builds an extension for the given settings. */
export type SettingsBuilder = (settings: AssistSettings) => Extension;
/**
* Extensions that depend on the assist settings and follow them live.
* Each builder sits in its own compartment; when the source reports a
* change (or a view gets a state built with older values), the
* compartments are reconfigured with the new values. The reconfiguration
* is dispatched outside any editor update.
*
* @param source - where the settings come from.
* @param builders - one builder per settings-dependent extension.
* @returns the extensions, built with the current values.
*/
export function liveAssistSettings(source: AssistSettingsSource, builders: readonly SettingsBuilder[]): Extension {
const initial = source.current();
const slots = builders.map((build) => ({ build, compartment: new Compartment() }));
const sync = (view: EditorView): void => {
const next = source.current();
if (sameAssistSettings(next, view.state.field(appliedField))) {
return;
}
view.dispatch({
effects: [
...slots.map((slot) => slot.compartment.reconfigure(slot.build(next))),
applied.of(next),
],
});
};
const follower = ViewPlugin.define((view) => {
let live = true;
const stop = source.subscribe(() => {
if (live) {
sync(view);
}
});
queueMicrotask(() => {
if (live) {
sync(view);
}
});
return {
destroy() {
live = false;
stop();
},
};
});
return [
appliedField.init(() => initial),
...slots.map((slot) => slot.compartment.of(slot.build(initial))),
follower,
];
}