@timurproko/a1 0.2.7-dev.1252 → 0.2.7-dev.1255

package/dist/features/owned-ui/settings-app.js

@@ -1,5 +1,7 @@
 import { DIALOG_BACK_SHORTCUT_HINT, DIALOG_CLOSE_SHORTCUT_HINT } from "../../contracts/presentation/index.js";
-import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, assertNoShortcutConflicts, blockJumpTarget, configureDialogChoiceCapacity, configureDialogTextRows, configureDialogWidth, numericValues, RAIL_COLUMNS, renderCenteredDialogOverlay, renderDialogPanel, renderSteppedDialogPanel, renderEmptyState, renderGroupHeader, renderListRow, renderNote, renderShortcutHintsWithClose, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, truncateToWidth, valueColumnFor, valueMenuFrame, blockRowSpan, displayWidth, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, layoutList, moveSelection, rowKey, scrollForSelection, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, ScrollbarRails, scrollbarWheelRows, selectableIndexes, } from "../../ui/components/index.js";
+import { GLOBAL_SCOPE, LineInput, PLAIN_THEME, ShortcutRegistry, assertNoShortcutConflicts, blockJumpTarget, configureDialogChoiceCapacity, configureDialogTextRows, configureDialogWidth, numericValues, RAIL_COLUMNS, renderCenteredDialogOverlay, renderDialogPanel, renderSteppedDialogPanel, renderEmptyState, renderGroupHeader, renderListRow, renderNote, renderShortcutHintsWithClose, menuRowAt, regionAt, renderValueMenu, withScrollbarRail, stepperEnds, steppedValue, truncateToWidth, valueColumnFor, valueMenuFrame, blockRowSpan, displayWidth, handleLineInputKey, humanizeLabel, humanizeTitle, indexOfKey, layoutList, moveSelection, rowKey, scrollForSelection, scrollbarGeometry, scrollbarWheelRows, selectableIndexes, } from "../../ui/components/index.js";
+import { SettingsScrollRail } from "./settings-scroll-rail.js";
+import { SettingsEdits, changeFailure, replaceRecord, sameRecord, structuredValue } from "./settings-edits.js";
 import { SETTINGS_APP_ID } from "./settings-route.js";
 export { SETTINGS_APP_ID, SETTINGS_ROUTE } from "./settings-route.js";
 const SCOPE = SETTINGS_APP_ID;
@@ -14,11 +16,6 @@ const DIALOG_SCOPE = `${SETTINGS_APP_ID}-parts`;
 const MODEL_SCOPE = `${SETTINGS_APP_ID}-models`;
 const MODEL_LEVEL_SCOPE = `${SETTINGS_APP_ID}-model-levels`;
 const SCROLLBAR_TOP_INSET = 0;
-/** Identity of the settings list rail in the shared rail state. */
-const RAIL_KEY = "settings";
-// Compatibility: the transcript rail stays lit this long after a scroll, and repaints just after.
-const SCROLL_LINGER_MS = 900;
-const SCROLL_LINGER_REPAINT_MS = 925;
 /** What a structured value offers instead of printing itself. */
 const CONFIGURE = "configure";
 export const SETTINGS_SHORTCUTS = new ShortcutRegistry();
@@ -96,12 +93,7 @@ export class SettingsApp {
     #menu = null;
     #structured = null;
     // Invariant: pending values remain visible until the source reflects them.
-    #pending = new Map();
-    #undoHistory = [];
-    #editSequence = 0;
-    #undoRequests = 0;
-    #undoActive = false;
-    #closed = false;
+    #edits;
     #bodyTopForFrame = SETTINGS_TOP_RULE_ROWS + SETTINGS_TITLE_ROWS;
     #bodyHeightForFrame = 0;
     #panelTopForFrame = 0;
@@ -110,16 +102,12 @@ export class SettingsApp {
     #frameRows = [];
     #menuFrame = null;
     // Invariant: rail hover and drag live in the shared keyed state, as the transcript's do.
-    #rails = new ScrollbarRails();
+    #rail = new SettingsScrollRail();
     // Rationale: the rail as drawn in the last frame, or null when nothing can be pointed at.
-    #railFrame = null;
-    // Invariant: a scroll lights the rail until this time; the timer repaints once it has passed.
-    #activeUntil = 0;
-    #activityTimer;
-    #renderedScroll;
     #options;
     constructor(session, options) {
         this.#session = session;
+        this.#edits = new SettingsEdits(session, () => this.#structured);
         this.#options = {
             dialogPanel: options.dialogPanel ?? null,
         };
@@ -131,17 +119,14 @@ export class SettingsApp {
         };
     }
     onActivate(host) {
-        this.#closed = false;
+        this.#edits.open();
         void this.#session.load().then(() => host.requestRender());
     }
     onClose(_host) {
-        this.#closed = true;
-        this.#undoHistory.length = 0;
-        this.#undoRequests = 0;
+        this.#edits.close();
         this.#search.input?.setFocused(false);
         this.#search.input = null;
-        this.#clearActivityTimer();
-        this.#rails.clear();
+        this.#rail.dispose();
     }
     render(rect, host) {
         const theme = host.theme ?? PLAIN_THEME;
@@ -174,11 +159,7 @@ export class SettingsApp {
         this.#panelTopForFrame = topRows + contentHeight + dividerRows;
         this.#scroll = layout.scroll;
         const now = Date.now();
-        // Rationale: every way of scrolling ends in this frame, so a moved list is noticed here
-        // once rather than at each wheel, drag, key, and search branch.
-        if (this.#renderedScroll !== undefined && this.#renderedScroll !== layout.scroll)
-            this.#noteScrollActivity(host, now);
-        this.#renderedScroll = layout.scroll;
+        this.#rail.noteRenderedScroll(layout.scroll, now, () => host.requestRender());
         // Invariant: auto and always keep the rail columns while the list fits, so a revealed
         // rail never reflows the rows; hidden gives the columns back to the rows.
         const appearance = this.#scrollbarAppearance();
@@ -191,22 +172,10 @@ export class SettingsApp {
             scroll: layout.scroll,
             trackHeight: Math.max(0, titleRows + bodyHeight - SCROLLBAR_TOP_INSET),
         });
-        const presentation = scrollbarPresentation({
-            geometry,
-            appearance,
-            style: this.#scrollbarStyle(),
-            hovered: this.#rails.isHovered(RAIL_KEY),
-            dragging: this.#rails.isDragging(RAIL_KEY),
-            activeUntil: this.#activeUntil,
-            now,
-        });
-        this.#railFrame = reservesRail && geometry !== null
-            ? {
-                rail: { key: RAIL_KEY, column: rect.width, rowStart: topRows + SCROLLBAR_TOP_INSET, trackHeight: geometry.trackHeight },
-                geometry,
-                page: layout.visible,
-            }
-            : null;
+        const presentation = this.#rail.presentation({ geometry, appearance, style: this.#scrollbarStyle(), now });
+        this.#rail.setFrame(reservesRail && geometry !== null
+            ? { rail: { column: rect.width, rowStart: topRows + SCROLLBAR_TOP_INSET, trackHeight: geometry.trackHeight }, geometry, page: layout.visible }
+            : null);
         const body = [];
         this.#frameRows = [];
         if (rows.length === 0) {
@@ -275,7 +244,7 @@ export class SettingsApp {
                 const row = rows[selected];
                 if (row?.kind === "element" && (row.value.structured || isDefaultModelEntry(row.value)))
                     this.#openStructured(row.value);
-                else if (row?.kind === "element" && typeof this.#shownValue(row.value) === "number")
+                else if (row?.kind === "element" && typeof this.#edits.shown(row.value) === "number")
                     this.#cycle(rows, selected, 1);
                 else
                     this.#openMenu(rows, selected, true);
@@ -313,7 +282,7 @@ export class SettingsApp {
                 this.#cycle(rows, selected, action === "next-value" ? 1 : -1);
                 return { consumed: true };
             case "undo":
-                this.#undo();
+                this.#edits.undo();
                 return { consumed: true };
             default:
                 return { consumed: false };
@@ -355,7 +324,7 @@ export class SettingsApp {
             const value = menu.choices[overRow];
             this.#closeMenu(menu);
             if (value !== undefined)
-                this.#apply(menu.entry, value);
+                this.#edits.apply(menu.entry, value);
             return { consumed: true };
         }
         if (event.kind === "wheel-up" || event.kind === "wheel-down") {
@@ -380,7 +349,14 @@ export class SettingsApp {
             // cannot change its selection or act on the Settings list behind it.
             return { consumed: true, render: false };
         }
-        const rail = this.#railPointer(event);
+        const rail = this.#rail.pointer(event, this.#scroll);
+        if (rail.scroll !== undefined)
+            this.#scroll = rail.scroll;
+        // Invariant: the rail is not a row: pointing at it lights nothing in the list.
+        if (rail.overRail) {
+            this.#hoverKey = null;
+            this.#hoverRegion = "label";
+        }
         if (rail.owned)
             return { consumed: true };
         const row = this.#frameRows.find(candidate => candidate.screenRow === event.row - 1);
@@ -410,52 +386,6 @@ export class SettingsApp {
         const changed = previousKey !== this.#hoverKey || previousRegion !== this.#hoverRegion || rail.changed;
         return { consumed: event.kind !== "motion", render: changed };
     }
-    // Rationale: the rail takes its share of a pointer report first: hover, a thumb drag, or a
-    // track page. Owned means the list must not see the report; changed means the rail looks different.
-    #railPointer(event) {
-        const frame = this.#railFrame;
-        const wasHovered = this.#rails.isHovered(RAIL_KEY);
-        if (frame === null) {
-            this.#rails.clear();
-            return { owned: false, changed: wasHovered };
-        }
-        const pointer = { column: event.column, row: event.row - 1 };
-        if (this.#rails.isDragging(RAIL_KEY)) {
-            // Invariant: a drag keeps the pointer wherever it goes until the button comes up.
-            if (event.kind === "release")
-                this.#rails.endDrag();
-            else {
-                const target = this.#rails.dragTo(frame.rail, frame.geometry, pointer);
-                if (target !== null)
-                    this.#scroll = target;
-            }
-            return { owned: true, changed: true };
-        }
-        const over = this.#rails.notePointer([frame.rail], pointer) !== null;
-        if (!over)
-            return { owned: false, changed: wasHovered };
-        // Invariant: the rail is not a row: pointing at it lights nothing in the list.
-        this.#hoverKey = null;
-        this.#hoverRegion = "label";
-        if (event.kind === "press" && !this.#rails.beginDrag(frame.rail, frame.geometry, pointer)) {
-            this.#scroll = scrollForTrackPage(frame.geometry, pointer.row - frame.rail.rowStart, this.#scroll, frame.page);
-        }
-        return { owned: true, changed: true };
-    }
-    #noteScrollActivity(host, now) {
-        this.#activeUntil = Math.max(this.#activeUntil, now + SCROLL_LINGER_MS);
-        this.#clearActivityTimer();
-        this.#activityTimer = setTimeout(() => {
-            this.#activityTimer = undefined;
-            host.requestRender();
-        }, SCROLL_LINGER_REPAINT_MS);
-        this.#activityTimer.unref?.();
-    }
-    #clearActivityTimer() {
-        if (this.#activityTimer !== undefined)
-            clearTimeout(this.#activityTimer);
-        this.#activityTimer = undefined;
-    }
     #openMenu(rows, selected, selectCurrent = false) {
         const row = rows[selected];
         if (row === undefined || row.kind !== "element")
@@ -465,7 +395,7 @@ export class SettingsApp {
             this.#openStructured(entry);
             return;
         }
-        const shown = this.#shownValue(entry);
+        const shown = this.#edits.shown(entry);
         // Rationale: a number is stepped, not picked from a list: it has its own two controls,
         // and pointing at it is not a request for anything else.
         if (typeof shown === "number")
@@ -522,7 +452,7 @@ export class SettingsApp {
         // thing under the pointer, so it stops looking like it.
         this.#hoverKey = null;
         this.#hoverRegion = "label";
-        this.#rails.clear();
+        this.#rail.clear();
         const currentDefault = typeof entry.rawValue === "string" ? entry.rawValue : null;
         this.#structured = {
             entry,
@@ -557,7 +487,7 @@ export class SettingsApp {
                 this.#toggleFlag(open.index);
                 return { consumed: true };
             case "undo":
-                this.#undo();
+                this.#edits.undo();
                 return { consumed: true };
             default:
                 return { consumed: true, render: false };
@@ -689,14 +619,8 @@ export class SettingsApp {
         this.#saveStructured(open, previous, forward);
     }
     #saveStructured(open, previous, forward) {
-        const sequence = ++this.#editSequence;
-        void this.#session.changeStructured(open.entry.backend, open.entry.id, structuredValue(open.entry, forward)).then(outcome => {
-            const failure = changeFailure(outcome);
-            if (failure === null) {
-                this.#recordUndo({ kind: "structured", sequence, entry: open.entry, previous, forward });
-                return;
-            }
-            // Concurrency: only roll back the dialog if no later press has moved the record on.
+        // Concurrency: only roll back the dialog if no later press has moved the record on.
+        this.#edits.saveStructured(open.entry, previous, forward, () => {
             if (this.#structured === open && sameRecord(open.record, forward))
                 replaceRecord(open.record, previous);
         });
@@ -708,7 +632,7 @@ export class SettingsApp {
         const key = KEYS[data] ?? data;
         if (SETTINGS_SHORTCUTS.resolve(key, SCOPE) === "undo") {
             this.#closeMenu(menu);
-            this.#undo();
+            this.#edits.undo();
             return { consumed: true };
         }
         if (key === "escape") {
@@ -725,7 +649,7 @@ export class SettingsApp {
             const value = menu.choices[menu.index];
             this.#closeMenu(menu);
             if (value !== undefined)
-                this.#apply(menu.entry, value);
+                this.#edits.apply(menu.entry, value);
         }
         return { consumed: true };
     }
@@ -785,13 +709,13 @@ export class SettingsApp {
         const entry = row.value;
         if (!entry.editable)
             return;
-        const shown = this.#shownValue(entry);
+        const shown = this.#edits.shown(entry);
         if (typeof shown === "number") {
             // Rationale: at the end of the range there is nothing to say: the arrow already reads
             // as unavailable, so a message would only repeat it.
             const next = steppedValue(rangeOf(entry), shown, delta);
             if (next !== null)
-                this.#apply(entry, next);
+                this.#edits.apply(entry, next);
             return;
         }
         const choices = entry.choices;
@@ -802,82 +726,7 @@ export class SettingsApp {
             ? (delta > 0 ? 0 : choices.length - 1)
             : (current + delta + choices.length) % choices.length];
         if (next !== undefined)
-            this.#apply(entry, next);
-    }
-    #apply(entry, value) {
-        const key = `${entry.backend}:${entry.id}`;
-        const previous = this.#shownValue(entry);
-        const sequence = ++this.#editSequence;
-        // Invariant: shown immediately so the row never lags a keypress, and so the next press
-        // steps from here rather than from a value the source has not caught up to.
-        this.#pending.set(key, value);
-        void this.#session.change(entry.backend, entry.id, value).then(outcome => {
-            const failure = changeFailure(outcome);
-            if (failure !== null) {
-                if (this.#pending.get(key) === value)
-                    this.#pending.delete(key);
-                return;
-            }
-            if (previous !== null && previous !== value)
-                this.#recordUndo({ kind: "scalar", sequence, entry, previous });
-            // Concurrency: a later press may have moved on; only the last request clears itself.
-            if (this.#pending.get(key) === value)
-                this.#pending.delete(key);
-        });
-    }
-    #shownValue(entry) {
-        return this.#pending.get(`${entry.backend}:${entry.id}`) ?? entry.value;
-    }
-    #recordUndo(record) {
-        if (this.#closed)
-            return;
-        const after = this.#undoHistory.findIndex(candidate => candidate.sequence > record.sequence);
-        if (after < 0)
-            this.#undoHistory.push(record);
-        else
-            this.#undoHistory.splice(after, 0, record);
-    }
-    #undo() {
-        this.#undoRequests++;
-        this.#drainUndo();
-    }
-    #drainUndo() {
-        if (this.#undoActive || this.#undoRequests === 0)
-            return;
-        const record = this.#undoHistory.pop();
-        if (record === undefined) {
-            this.#undoRequests = 0;
-            return;
-        }
-        this.#undoRequests--;
-        this.#undoActive = true;
-        if (record.kind === "scalar") {
-            const key = `${record.entry.backend}:${record.entry.id}`;
-            this.#pending.set(key, record.previous);
-            void this.#session.change(record.entry.backend, record.entry.id, record.previous).then(outcome => {
-                if (this.#pending.get(key) === record.previous)
-                    this.#pending.delete(key);
-                this.#finishUndo(record, outcome);
-            });
-            return;
-        }
-        const open = this.#structured;
-        if (open !== null && sameEntry(open.entry, record.entry))
-            replaceRecord(open.record, record.previous);
-        void this.#session.changeStructured(record.entry.backend, record.entry.id, structuredValue(record.entry, record.previous)).then(outcome => {
-            const failure = changeFailure(outcome);
-            if (failure !== null && this.#structured === open && open !== null && sameRecord(open.record, record.previous)) {
-                replaceRecord(open.record, record.forward);
-            }
-            this.#finishUndo(record, outcome);
-        });
-    }
-    #finishUndo(record, outcome) {
-        const failure = changeFailure(outcome);
-        if (failure !== null)
-            this.#recordUndo(record);
-        this.#undoActive = false;
-        this.#drainUndo();
+            this.#edits.apply(entry, next);
     }
     #scrollbarSpeed() {
         const value = this.#scrollSetting("scrollbarSpeed");
@@ -895,7 +744,7 @@ export class SettingsApp {
         const entry = this.#session.sections()
             .flatMap(section => section.entries)
             .find(candidate => candidate.backend === "a1" && candidate.id === id);
-        return entry === undefined ? this.#session.value(id) : this.#shownValue(entry);
+        return entry === undefined ? this.#session.value(id) : this.#edits.shown(entry);
     }
     #jump(rows, target) {
         this.#select(rows, target);
@@ -967,7 +816,7 @@ export class SettingsApp {
     }
     #viewRow(entry) {
         const key = `${entry.backend}:${entry.id}`;
-        const shown = this.#shownValue(entry);
+        const shown = this.#edits.shown(entry);
         const value = entry.structured || isDefaultModelEntry(entry)
             ? CONFIGURE
             : shown === null
@@ -993,7 +842,7 @@ export class SettingsApp {
             ...(menu.entry.id === "accentColor" ? {
                 previews: menu.choices.map(choice => theme.accentPreview?.(String(choice), "■") ?? ""),
             } : {}),
-            current: this.#shownValue(menu.entry) === null ? null : displaySettingValue(menu.entry, this.#shownValue(menu.entry)),
+            current: this.#edits.shown(menu.entry) === null ? null : displaySettingValue(menu.entry, this.#edits.shown(menu.entry)),
             index: menu.index,
         };
         const frame = valueMenuFrame(state, {
@@ -1155,36 +1004,6 @@ function thinkingLevelDescription(level) {
         default: return "";
     }
 }
-function structuredValue(entry, record) {
-    // Invariant: a choice part at its fallback is unset, so the engine's default applies.
-    return Object.fromEntries(Object.entries(record).filter(([key, value]) => {
-        const part = entry.flags.find(candidate => candidate.key === key);
-        return part?.choices === undefined || value !== part.fallback;
-    }));
-}
-function sameEntry(left, right) {
-    return left.backend === right.backend && left.id === right.id;
-}
-function sameRecord(left, right) {
-    const leftEntries = Object.entries(left);
-    const rightEntries = Object.entries(right);
-    return leftEntries.length === rightEntries.length
-        && leftEntries.every(([key, value]) => right[key] === value);
-}
-function replaceRecord(target, source) {
-    for (const key of Object.keys(target))
-        delete target[key];
-    Object.assign(target, source);
-}
-function changeFailure(outcome) {
-    if (outcome.failure !== null)
-        return outcome.failure;
-    if (outcome.status === "failed")
-        return "the effect failed";
-    if (outcome.status === "unavailable")
-        return outcome.limitationReason ?? "the setting is unavailable";
-    return outcome.limitationReason;
-}
 function isDefaultModelEntry(entry) {
     return entry.backend === "agent" && entry.id === "defaultModel";
 }

package/dist/features/owned-ui/settings-edits.d.ts

@@ -0,0 +1,31 @@
+import type { OwnedUiSettingValue, OwnedUiSettingsChangeOutcome, OwnedUiSettingsEntry, OwnedSettingsManager } from "../../ui/settings/index.js";
+type SettingsRecord = Record<string, boolean | string>;
+/** The structured dialog an undo may need to roll back in place; null when none is open. */
+export interface OpenStructuredRecord {
+    readonly entry: OwnedUiSettingsEntry;
+    readonly record: SettingsRecord;
+}
+/**
+ * The settings screen's edits: values shown ahead of the source, and an undo history ordered by edit
+ * sequence. Undo requests drain one at a time so each restores against the result of the one before.
+ */
+export declare class SettingsEdits {
+    #private;
+    constructor(session: Pick<OwnedSettingsManager, "change" | "changeStructured">, openStructured: () => OpenStructuredRecord | null);
+    /** The value a row shows: a pending edit, or the source's value. */
+    shown(entry: OwnedUiSettingsEntry): OwnedUiSettingValue | null;
+    apply(entry: OwnedUiSettingsEntry, value: OwnedUiSettingValue): void;
+    /** Saves a structured dialog's record; `rollback` runs when the change fails. */
+    saveStructured(entry: OwnedUiSettingsEntry, previous: Readonly<SettingsRecord>, forward: Readonly<SettingsRecord>, rollback: () => void): void;
+    undo(): void;
+    open(): void;
+    /** Drops the history and queued requests; late results no longer record undo steps. */
+    close(): void;
+}
+/** The record the engine stores: a choice part at its fallback is unset, so the engine's default applies. */
+export declare function structuredValue(entry: OwnedUiSettingsEntry, record: Readonly<SettingsRecord>): SettingsRecord;
+export declare function sameRecord(left: Readonly<SettingsRecord>, right: Readonly<SettingsRecord>): boolean;
+export declare function replaceRecord(target: SettingsRecord, source: Readonly<SettingsRecord>): void;
+/** Why a change did not take effect, or null when it did. */
+export declare function changeFailure(outcome: OwnedUiSettingsChangeOutcome): string | null;
+export {};

package/dist/features/owned-ui/settings-edits.js

@@ -0,0 +1,139 @@
+/**
+ * The settings screen's edits: values shown ahead of the source, and an undo history ordered by edit
+ * sequence. Undo requests drain one at a time so each restores against the result of the one before.
+ */
+export class SettingsEdits {
+    #session;
+    #openStructured;
+    #pending = new Map();
+    #history = [];
+    #sequence = 0;
+    #requests = 0;
+    #active = false;
+    #closed = false;
+    constructor(session, openStructured) {
+        this.#session = session;
+        this.#openStructured = openStructured;
+    }
+    /** The value a row shows: a pending edit, or the source's value. */
+    shown(entry) {
+        return this.#pending.get(pendingKey(entry)) ?? entry.value;
+    }
+    apply(entry, value) {
+        const key = pendingKey(entry);
+        const previous = this.shown(entry);
+        const sequence = ++this.#sequence;
+        // Invariant: shown immediately so the row never lags a keypress, and so the next press
+        // steps from here rather than from a value the source has not caught up to.
+        this.#pending.set(key, value);
+        void this.#session.change(entry.backend, entry.id, value).then(outcome => {
+            const failed = changeFailure(outcome) !== null;
+            if (!failed && previous !== null && previous !== value)
+                this.#record({ kind: "scalar", sequence, entry, previous });
+            // Concurrency: a later press may have moved on; only the last request clears itself.
+            if (this.#pending.get(key) === value)
+                this.#pending.delete(key);
+        });
+    }
+    /** Saves a structured dialog's record; `rollback` runs when the change fails. */
+    saveStructured(entry, previous, forward, rollback) {
+        const sequence = ++this.#sequence;
+        void this.#session.changeStructured(entry.backend, entry.id, structuredValue(entry, forward)).then(outcome => {
+            if (changeFailure(outcome) === null)
+                this.#record({ kind: "structured", sequence, entry, previous, forward });
+            else
+                rollback();
+        });
+    }
+    undo() {
+        this.#requests++;
+        this.#drain();
+    }
+    open() { this.#closed = false; }
+    /** Drops the history and queued requests; late results no longer record undo steps. */
+    close() {
+        this.#closed = true;
+        this.#history.length = 0;
+        this.#requests = 0;
+    }
+    #record(record) {
+        if (this.#closed)
+            return;
+        const after = this.#history.findIndex(candidate => candidate.sequence > record.sequence);
+        if (after < 0)
+            this.#history.push(record);
+        else
+            this.#history.splice(after, 0, record);
+    }
+    #drain() {
+        if (this.#active || this.#requests === 0)
+            return;
+        const record = this.#history.pop();
+        if (record === undefined) {
+            this.#requests = 0;
+            return;
+        }
+        this.#requests--;
+        this.#active = true;
+        if (record.kind === "scalar") {
+            const key = pendingKey(record.entry);
+            this.#pending.set(key, record.previous);
+            void this.#session.change(record.entry.backend, record.entry.id, record.previous).then(outcome => {
+                if (this.#pending.get(key) === record.previous)
+                    this.#pending.delete(key);
+                this.#finish(record, outcome);
+            });
+            return;
+        }
+        const open = this.#openStructured();
+        const target = open !== null && sameEntry(open.entry, record.entry) ? open : null;
+        if (target !== null)
+            replaceRecord(target.record, record.previous);
+        void this.#session.changeStructured(record.entry.backend, record.entry.id, structuredValue(record.entry, record.previous)).then(outcome => {
+            if (changeFailure(outcome) !== null && target !== null && this.#openStructured() === target && sameRecord(target.record, record.previous)) {
+                replaceRecord(target.record, record.forward);
+            }
+            this.#finish(record, outcome);
+        });
+    }
+    #finish(record, outcome) {
+        if (changeFailure(outcome) !== null)
+            this.#record(record);
+        this.#active = false;
+        this.#drain();
+    }
+}
+function pendingKey(entry) {
+    return `${entry.backend}:${entry.id}`;
+}
+/** The record the engine stores: a choice part at its fallback is unset, so the engine's default applies. */
+export function structuredValue(entry, record) {
+    return Object.fromEntries(Object.entries(record).filter(([key, value]) => {
+        const part = entry.flags.find(candidate => candidate.key === key);
+        return part?.choices === undefined || value !== part.fallback;
+    }));
+}
+export function sameRecord(left, right) {
+    const leftEntries = Object.entries(left);
+    const rightEntries = Object.entries(right);
+    return leftEntries.length === rightEntries.length
+        && leftEntries.every(([key, value]) => right[key] === value);
+}
+export function replaceRecord(target, source) {
+    for (const key of Object.keys(target))
+        delete target[key];
+    Object.assign(target, source);
+}
+/** Why a change did not take effect, or null when it did. */
+export function changeFailure(outcome) {
+    if (outcome.failure !== null)
+        return outcome.failure;
+    if (outcome.status === "failed")
+        return "the effect failed";
+    if (outcome.status === "unavailable")
+        return outcome.limitationReason ?? "the setting is unavailable";
+    return outcome.limitationReason;
+}
+function sameEntry(left, right) {
+    return left.backend === right.backend && left.id === right.id;
+}

package/dist/features/owned-ui/settings-scroll-rail.d.ts

@@ -0,0 +1,29 @@
+import { type PaneMouseEvent, type RailPosition, type ScrollbarGeometry, type ScrollbarPresentation, type ScrollbarPresentationInput } from "../../ui/components/index.js";
+/** Where the rail was painted in the last frame, with the list page it scrolls by. */
+export interface SettingsRailFrame {
+    readonly rail: RailPosition;
+    readonly geometry: ScrollbarGeometry;
+    readonly page: number;
+}
+/** How a pointer report landed on the rail: owned keeps it from the list, and `scroll` is the list's new offset. */
+export interface SettingsRailPointer {
+    readonly owned: boolean;
+    readonly changed: boolean;
+    readonly overRail: boolean;
+    readonly scroll?: number;
+}
+/** The settings list's scrollbar rail: hover, thumb drag, track paging, and the lingering highlight after a scroll. */
+export declare class SettingsScrollRail {
+    #private;
+    /** Notes the frame's scroll; a moved list keeps the rail lit and repaints once the highlight lapses. */
+    noteRenderedScroll(scroll: number, now: number, requestRender: () => void): void;
+    presentation(input: Omit<ScrollbarPresentationInput, "hovered" | "dragging" | "activeUntil">): ScrollbarPresentation;
+    /** Records where the rail was painted, or null when this frame has no rail. */
+    setFrame(frame: Omit<SettingsRailFrame, "rail"> & {
+        readonly rail: Omit<RailPosition, "key">;
+    } | null): void;
+    pointer(event: PaneMouseEvent, scroll: number): SettingsRailPointer;
+    /** Drops hover and any drag, as when a dialog takes the screen. */
+    clear(): void;
+    dispose(): void;
+}