@timurproko/a1 0.1.8-dev.182 → 0.1.8-dev.214

package/dist/ui/components/transcript-viewport.js

@@ -1,8 +1,9 @@
 import { isThumbRow, scrollbarGeometry, scrollbarPresentation, } from "./scrollbar.js";
 import { backgroundSgrSpan, overlaySpan } from "./spans.js";
 import { faint, truncateToWidth, displayWidth, stripAnsi } from "./text.js";
-import { extendTextSelection, orderedTextSelection, pressTextSelection, releaseTextSelection, textSelectionLineExtendColumn, textSelectionText, usefulTextLineContent, } from "./text-selection.js";
+import { extendTextSelection, orderedTextSelection, pressTextSelection, releaseTextSelection, textSelectionLineExtendColumn, textSelectionPointAt, textSelectionText, usefulTextLineContent, } from "./text-selection.js";
 const CONTROL_STYLE_RESET = "\u001b]8;;\u001b\\\u001b[0m";
+const IDENTITY_ROW = (row) => row;
 const DEFAULT_CONFIG = {
     scrollbarAppearance: "auto",
     scrollbarStyle: "thin",
@@ -32,16 +33,26 @@ export class TranscriptViewport {
     #bottomHovered = false;
     #selection;
     #selectionClick;
+    #selectionRevision = 0;
+    #paintedRowCache = new Map();
+    #baseRowCache = new Map();
+    #selectedRowCache = new Map();
+    #finalRowCache = new Map();
+    #functionIds = new WeakMap();
+    #nextFunctionId = 1;
+    #previousVisibleStates = [];
     #documentRows = [];
     #selectableDocumentRowCount = 0;
     #promptAnchors = [];
     #contentWidth = 0;
+    #frameId = 0;
     #frame = null;
     get scrollTop() { return this.#scrollTop; }
     get maxScroll() { return this.#maxScroll; }
     get followingEnd() { return this.#followingEnd; }
     get newMessages() { return this.#newMessages; }
     get frame() { return this.#frame; }
+    get selectionRevision() { return this.#selectionRevision; }
     /** Counts one completed assistant reply while detached; tool rows never call this. */
     noteNewMessage() {
         if (this.#followingEnd)
@@ -83,6 +94,7 @@ export class TranscriptViewport {
         });
         this.#selection = pressed.selection;
         this.#selectionClick = pressed.click;
+        this.#selectionRevision += 1;
         return true;
     }
     extendSelection(column, viewportRow, now = Date.now(), autoScroll = true) {
@@ -90,7 +102,7 @@ export class TranscriptViewport {
         const viewportHeight = this.#frame?.hits.viewportHeight ?? 0;
         if (selection?.selecting !== true || viewportHeight <= 0 || this.#documentRows.length === 0)
             return false;
-        // Pointer motion updates only the endpoint; the shell's fixed-cadence timer
+        // Performance: pointer motion updates only the endpoint; the shell's fixed-cadence timer
         // owns edge scrolling. This option prevents high-rate motion reports from
         // adding irregular extra rows between timer ticks.
         if (autoScroll && viewportRow > viewportHeight)
@@ -105,19 +117,28 @@ export class TranscriptViewport {
         const targetColumn = selection.fullRow
             ? textSelectionLineExtendColumn(selection, line, this.#contentWidth)
             : clamp(column, 1, this.#contentWidth);
-        this.#selection = extendTextSelection(selection, { line, column: targetColumn });
+        const point = selection.fullRow
+            ? { line, column: targetColumn }
+            : textSelectionPointAt(line, targetColumn, this.#documentRows[line] ?? "");
+        const next = extendTextSelection(selection, point);
+        if (next !== selection) {
+            this.#selection = next;
+            this.#selectionRevision += 1;
+        }
         return true;
     }
     releaseSelection() {
         if (this.#selection?.selecting !== true)
             return false;
         this.#selection = releaseTextSelection(this.#selection);
+        this.#selectionRevision += 1;
         return true;
     }
     clearSelection() {
         if (this.#selection === undefined)
             return false;
         this.#selection = undefined;
+        this.#selectionRevision += 1;
         return true;
     }
     selectedText() {
@@ -142,7 +163,7 @@ export class TranscriptViewport {
         const next = clamp(position, 0, this.#maxScroll);
         const changed = next !== this.#scrollTop || this.#followingEnd;
         this.#scrollTop = next;
-        // Every scrolling path that reaches the final legal top row resumes follow.
+        // Invariant: every scrolling path that reaches the final legal top row resumes follow.
         this.#followingEnd = next >= this.#maxScroll;
         if (this.#followingEnd)
             this.#newMessages = 0;
@@ -166,7 +187,7 @@ export class TranscriptViewport {
             if (anchor.firstRow < this.#scrollTop && anchor.firstRow > target)
                 target = anchor.firstRow;
         }
-        // The first prompt owns the document's opening breathing row. At that final
+        // Invariant: the first prompt owns the document's opening breathing row. At that final
         // navigation stop, reveal the spacer too rather than pinning the prompt to
         // terminal row one as later prompt jumps do.
         const destination = target === earliest ? 0 : target;
@@ -177,7 +198,7 @@ export class TranscriptViewport {
         if (this.#promptAnchors.length === 0)
             return false;
         const earliest = Math.min(...this.#promptAnchors.map(anchor => anchor.firstRow));
-        // Scroll position zero is the first-prompt stop because it includes that
+        // Invariant: scroll position zero is the first-prompt stop because it includes that
         // prompt's opening spacer. Do not spend an extra keypress moving one row.
         const after = this.#scrollTop === 0 ? earliest : this.#scrollTop;
         let target = Number.POSITIVE_INFINITY;
@@ -192,8 +213,15 @@ export class TranscriptViewport {
         this.#maxScroll = 0;
         this.#followingEnd = true;
         this.#newMessages = 0;
+        if (this.#selection !== undefined)
+            this.#selectionRevision += 1;
         this.#selection = undefined;
         this.#selectionClick = undefined;
+        this.#paintedRowCache.clear();
+        this.#baseRowCache.clear();
+        this.#selectedRowCache.clear();
+        this.#finalRowCache.clear();
+        this.#previousVisibleStates = [];
         this.#documentRows = [];
         this.#selectableDocumentRowCount = 0;
         this.#promptAnchors = [];
@@ -212,6 +240,7 @@ export class TranscriptViewport {
         const width = Math.max(1, input.width);
         const height = Math.max(0, input.height);
         const theme = input.theme ?? PLAIN_THEME;
+        const previousDescriptor = this.#frame?.descriptor ?? null;
         const dock = input.dockRows.length > height ? input.dockRows.slice(-height) : [...input.dockRows];
         const viewportHeight = Math.max(0, height - dock.length);
         this.#maxScroll = Math.max(0, input.documentRows.length - viewportHeight);
@@ -227,7 +256,7 @@ export class TranscriptViewport {
             contentLength: input.documentRows.length,
             viewportHeight,
             scroll: this.#scrollTop,
-            // The session rail deliberately starts one line below the viewport top.
+            // Compatibility: the session rail deliberately starts one line below the viewport top.
             trackHeight: Math.max(0, viewportHeight - 1),
         });
         const presentation = scrollbarPresentation({
@@ -244,62 +273,82 @@ export class TranscriptViewport {
         this.#selectableDocumentRowCount = clamp(input.selectableDocumentRowCount ?? input.documentRows.length, 0, input.documentRows.length);
         this.#promptAnchors = input.promptAnchors;
         this.#contentWidth = contentWidth;
-        const paintDocumentRow = input.paintDocumentRow ?? (row => row);
+        const paintDocumentRow = input.paintDocumentRow ?? IDENTITY_ROW;
+        const cacheLimit = Math.max(32, viewportHeight * 6);
+        trimCache(this.#paintedRowCache, cacheLimit);
+        trimCache(this.#baseRowCache, cacheLimit);
+        trimCache(this.#selectedRowCache, cacheLimit);
+        trimCache(this.#finalRowCache, cacheLimit);
+        const paintId = this.#functionId(paintDocumentRow);
+        const paintRecomputedRows = new Set();
         const visible = input.documentRows
             .slice(this.#scrollTop, this.#scrollTop + viewportHeight)
-            .map(paintDocumentRow);
+            .map((row, index) => {
+            const painted = cachedString(this.#paintedRowCache, `${paintId}\u0000${row}`, cacheLimit, () => paintDocumentRow(row));
+            if (!painted.reused)
+                paintRecomputedRows.add(index);
+            return painted.value;
+        });
         while (visible.length < viewportHeight)
             visible.push("");
         const governing = governingPrompt(input.promptAnchors, this.#scrollTop);
         const stickyActive = governing !== null && governing.firstRow < this.#scrollTop;
         if (stickyActive && visible.length > 0) {
             const quiet = this.#scrollTop > governing.lastRow;
-            // Sticky prompts use the same normal/hover surface roles as the bottom
+            // Compatibility: sticky prompts use the same normal/hover surface roles as the bottom
             // control. Hover always starts from the full source row, so a quiet prompt
             // becomes prominent again with its timestamp intact.
-            const sticky = theme.sticky(paintDocumentRow(governing.sourceRow), this.#stickyHovered);
+            const source = cachedString(this.#paintedRowCache, `${paintId}\u0000${governing.sourceRow}`, cacheLimit, () => paintDocumentRow(governing.sourceRow));
+            if (!source.reused)
+                paintRecomputedRows.add(0);
+            const sticky = theme.sticky(source.value, this.#stickyHovered);
             visible[0] = quiet && !this.#stickyHovered ? theme.quietSticky(sticky) : sticky;
         }
+        const selectionPainterId = this.#functionId(theme.selection);
+        // Concurrency: a painter may synchronously route input in tests or host integrations.
+        // Label this frame with the exact selection snapshot it began composing.
+        const composingSelectionRevision = this.#selectionRevision;
         const orderedSelection = orderedTextSelection(this.#selection);
+        const recomputedRows = [];
+        const reusedRows = [];
+        const selectionDamagedRows = [];
+        const visibleStates = [];
         for (let row = 0; row < visible.length; row += 1) {
-            let line = padRowPreservingBackground(visible[row] ?? "", width);
-            if (orderedSelection !== undefined && !(stickyActive && row === 0)) {
-                const documentLine = this.#scrollTop + row;
-                if (documentLine < this.#selectableDocumentRowCount
-                    && documentLine >= orderedSelection.start.line
-                    && documentLine <= orderedSelection.end.line) {
-                    const fullVisualRow = orderedSelection.fullRow === true
-                        || (orderedSelection.start.line !== orderedSelection.end.line
-                            && documentLine !== orderedSelection.start.line
-                            && documentLine !== orderedSelection.end.line);
-                    const from = fullVisualRow || documentLine !== orderedSelection.start.line
-                        ? 0
-                        : orderedSelection.start.column - 1;
-                    const throughFinalColumn = documentLine === orderedSelection.end.line
-                        && orderedSelection.throughFinalColumn === true;
-                    const to = fullVisualRow || documentLine !== orderedSelection.end.line || throughFinalColumn
-                        ? width
-                        : orderedSelection.end.column;
-                    if (to > from)
-                        line = theme.selection(line, from, Math.min(width, to));
-                }
-            }
-            // Paint the rail after selection. Full-row selection reaches the terminal
+            const documentLine = this.#scrollTop + row;
+            const painted = visible[row] ?? "";
+            const base = cachedString(this.#baseRowCache, `${width}\u0000${painted}`, cacheLimit, () => padRowPreservingBackground(painted, width));
+            let rowRecomputed = paintRecomputedRows.has(row) || !base.reused;
+            const range = stickyActive && row === 0
+                ? null
+                : selectionRangeForLine(orderedSelection, documentLine, this.#selectableDocumentRowCount, width);
+            const rangeKey = range === null ? "-" : `${range.from}:${range.to}`;
+            const selected = range === null
+                ? { value: base.value, reused: true }
+                : cachedString(this.#selectedRowCache, `${selectionPainterId}\u0000${rangeKey}\u0000${base.value}`, cacheLimit, () => theme.selection(base.value, range.from, range.to));
+            rowRecomputed ||= !selected.reused;
+            // Invariant: paint the rail after selection. Full-row selection reaches the terminal
             // edge, while the foreground thumb/track remains visible above that
             // background instead of disappearing into it.
-            // Row zero is the intentional one-line breathing room above the rail.
+            let railCell = "";
             if (presentation.visible && geometry !== null && row > 0) {
                 const trackRow = row - 1;
                 const thumb = isThumbRow(geometry, trackRow);
                 const glyph = thumb ? presentation.thumbGlyph : presentation.trackGlyph;
-                const cell = thumb ? theme.thumb(glyph, this.#railHovered || this.#railDragging) : theme.track(glyph);
-                line = overlaySpan(line, width - 1, width, cell);
+                railCell = thumb ? theme.thumb(glyph, this.#railHovered || this.#railDragging) : theme.track(glyph);
             }
-            visible[row] = line;
+            const final = cachedString(this.#finalRowCache, `${width}\u0000${railCell}\u0000${selected.value}`, cacheLimit, () => railCell.length === 0 ? selected.value : overlaySpan(selected.value, width - 1, width, railCell));
+            rowRecomputed ||= !final.reused;
+            visible[row] = final.value;
+            (rowRecomputed ? recomputedRows : reusedRows).push(row + 1);
+            const state = `${width}\u0000${documentLine}\u0000${painted}\u0000${rangeKey}\u0000${range === null ? "" : selectionPainterId}\u0000${railCell}`;
+            visibleStates.push(state);
+            if (this.#previousVisibleStates[row] !== state)
+                selectionDamagedRows.push(row + 1);
         }
+        this.#previousVisibleStates = visibleStates;
         const frameRows = [...visible, ...dock].slice(0, height);
         let bottomHit = null;
-        if (geometry !== null && !this.#followingEnd && frameRows.length > 0) {
+        if (this.#maxScroll > 0 && !this.#followingEnd && frameRows.length > 0) {
             const genericLabel = " Jump to bottom (End) ";
             const countedLabel = this.#newMessages > 0
                 ? ` ${this.#newMessages} new message${this.#newMessages === 1 ? "" : "s"} (End) `
@@ -314,6 +363,48 @@ export class TranscriptViewport {
                 bottomHit = { row: row + 1, columnStart: left + 1, columnEnd: left + labelWidth };
             }
         }
+        const nextDocumentRange = {
+            start: this.#scrollTop,
+            end: Math.min(input.documentRows.length, this.#scrollTop + viewportHeight),
+        };
+        const previousDocumentRange = previousDescriptor?.nextDocumentRange ?? null;
+        const sameGeometry = previousDescriptor !== null
+            && previousDescriptor.width === width
+            && previousDescriptor.height === height
+            && sameRectangle(previousDescriptor.transcript, viewportHeight === 0 ? null : { rowStart: 1, rowEnd: viewportHeight })
+            && sameRectangle(previousDescriptor.dock, dock.length === 0 ? null : { rowStart: viewportHeight + 1, rowEnd: height });
+        const verticalShiftRows = previousDocumentRange === null ? 0 : nextDocumentRange.start - previousDocumentRange.start;
+        const safeVerticalShift = sameGeometry
+            && previousDescriptor?.followingEnd === true
+            && this.#followingEnd
+            && this.#selection === undefined
+            && verticalShiftRows > 0
+            && verticalShiftRows < viewportHeight;
+        const descriptor = {
+            frameId: ++this.#frameId,
+            width,
+            height,
+            transcript: viewportHeight === 0 ? null : { rowStart: 1, rowEnd: viewportHeight },
+            dock: dock.length === 0 ? null : { rowStart: viewportHeight + 1, rowEnd: height },
+            previousDocumentRange,
+            nextDocumentRange,
+            previousFollowingEnd: previousDescriptor?.followingEnd ?? null,
+            followingEnd: this.#followingEnd,
+            verticalShiftRows,
+            safeVerticalShift,
+            selectionRevision: composingSelectionRevision,
+            selectionDamagedRows,
+            cause: previousDescriptor === null
+                ? "initial"
+                : !sameGeometry
+                    ? "geometry-change"
+                    : !this.#followingEnd
+                        ? "detached"
+                        : safeVerticalShift
+                            ? "follow-shift"
+                            : "steady",
+        };
+        assertTranscriptViewportFrameDescriptor(descriptor);
         const hits = {
             viewportHeight,
             rail: geometry === null || this.#config.scrollbarAppearance === "hidden" ? null : {
@@ -332,10 +423,77 @@ export class TranscriptViewport {
             maxScroll: this.#maxScroll,
             followingEnd: this.#followingEnd,
             hits,
+            descriptor,
+            selectionDamage: {
+                revision: composingSelectionRevision,
+                recomputedRows,
+                reusedRows,
+                cacheEntries: this.#paintedRowCache.size + this.#baseRowCache.size
+                    + this.#selectedRowCache.size + this.#finalRowCache.size,
+            },
         };
         this.#frame = frame;
         return frame;
     }
+    /** Reuses an established transcript frame when only same-height dock rows changed. */
+    composeDockOnly(dockRows, width, height) {
+        const previous = this.#frame;
+        const boundedWidth = Math.max(1, width);
+        const boundedHeight = Math.max(0, height);
+        if (previous === null || previous.descriptor.width !== boundedWidth || previous.descriptor.height !== boundedHeight
+            || previous.descriptor.selectionRevision !== this.#selectionRevision)
+            return null;
+        const dock = dockRows.length > boundedHeight ? dockRows.slice(-boundedHeight) : [...dockRows];
+        const viewportHeight = Math.max(0, boundedHeight - dock.length);
+        const expectedDock = dock.length === 0 ? null : { rowStart: viewportHeight + 1, rowEnd: boundedHeight };
+        const expectedTranscript = viewportHeight === 0 ? null : { rowStart: 1, rowEnd: viewportHeight };
+        if (!sameRectangle(previous.descriptor.dock, expectedDock)
+            || !sameRectangle(previous.descriptor.transcript, expectedTranscript))
+            return null;
+        const descriptor = {
+            frameId: ++this.#frameId,
+            width: boundedWidth,
+            height: boundedHeight,
+            transcript: expectedTranscript,
+            dock: expectedDock,
+            previousDocumentRange: previous.descriptor.nextDocumentRange,
+            nextDocumentRange: previous.descriptor.nextDocumentRange,
+            previousFollowingEnd: previous.followingEnd,
+            followingEnd: previous.followingEnd,
+            verticalShiftRows: 0,
+            safeVerticalShift: false,
+            selectionRevision: this.#selectionRevision,
+            selectionDamagedRows: [],
+            cause: "dock-input",
+        };
+        assertTranscriptViewportFrameDescriptor(descriptor);
+        const frame = {
+            rows: [...previous.rows.slice(0, viewportHeight), ...dock].slice(0, boundedHeight),
+            contentWidth: previous.contentWidth,
+            scrollTop: previous.scrollTop,
+            maxScroll: previous.maxScroll,
+            followingEnd: previous.followingEnd,
+            hits: previous.hits,
+            descriptor,
+            selectionDamage: {
+                revision: this.#selectionRevision,
+                recomputedRows: [],
+                reusedRows: Array.from({ length: viewportHeight }, (_, index) => index + 1),
+                cacheEntries: previous.selectionDamage.cacheEntries,
+            },
+        };
+        this.#frame = frame;
+        return frame;
+    }
+    #functionId(value) {
+        const existing = this.#functionIds.get(value);
+        if (existing !== undefined)
+            return existing;
+        const id = this.#nextFunctionId;
+        this.#nextFunctionId += 1;
+        this.#functionIds.set(value, id);
+        return id;
+    }
     #lineContentAt(line) {
         const plain = stripAnsi(this.#documentRows[line] ?? "");
         const prompt = this.#promptAnchors.find(anchor => line >= anchor.firstRow && line <= anchor.lastRow);
@@ -354,6 +512,42 @@ export class TranscriptViewport {
         return content;
     }
 }
+function selectionRangeForLine(selection, documentLine, selectableRowCount, width) {
+    if (selection === undefined || documentLine >= selectableRowCount
+        || documentLine < selection.start.line || documentLine > selection.end.line)
+        return null;
+    const fullVisualRow = selection.fullRow === true
+        || (selection.start.line !== selection.end.line
+            && documentLine !== selection.start.line
+            && documentLine !== selection.end.line);
+    const from = fullVisualRow || documentLine !== selection.start.line
+        ? 0
+        : selection.start.column;
+    const throughFinalColumn = documentLine === selection.end.line && selection.throughFinalColumn === true;
+    const to = fullVisualRow || documentLine !== selection.end.line || throughFinalColumn
+        ? width
+        : selection.end.column;
+    const boundedFrom = clamp(from, 0, width);
+    const boundedTo = clamp(to, boundedFrom, width);
+    return boundedTo > boundedFrom ? { from: boundedFrom, to: boundedTo } : null;
+}
+function cachedString(cache, key, limit, create) {
+    const existing = cache.get(key);
+    if (existing !== undefined) {
+        cache.delete(key);
+        cache.set(key, existing);
+        return { value: existing, reused: true };
+    }
+    const value = create();
+    cache.set(key, value);
+    while (cache.size > limit)
+        cache.delete(cache.keys().next().value);
+    return { value, reused: false };
+}
+function trimCache(cache, limit) {
+    while (cache.size > limit)
+        cache.delete(cache.keys().next().value);
+}
 function governingPrompt(anchors, scrollTop) {
     let result = null;
     for (const anchor of anchors) {
@@ -376,6 +570,60 @@ function padRowPreservingBackground(line, width) {
         return `${shown}${reverse}${" ".repeat(padding)}\u001b[27m`;
     return shown + " ".repeat(padding);
 }
+export function assertTranscriptViewportFrameDescriptor(descriptor) {
+    if (!Number.isSafeInteger(descriptor.frameId) || descriptor.frameId < 1)
+        throw new TypeError("viewport frame descriptor identity is invalid");
+    if (!Number.isSafeInteger(descriptor.width) || descriptor.width < 1)
+        throw new TypeError("viewport frame descriptor width is invalid");
+    if (!Number.isSafeInteger(descriptor.height) || descriptor.height < 0)
+        throw new TypeError("viewport frame descriptor height is invalid");
+    assertRectangle(descriptor.transcript, descriptor.height, "transcript");
+    assertRectangle(descriptor.dock, descriptor.height, "dock");
+    if (descriptor.transcript !== null && descriptor.dock !== null && descriptor.transcript.rowEnd >= descriptor.dock.rowStart) {
+        throw new TypeError("viewport frame descriptor regions overlap");
+    }
+    assertDocumentRange(descriptor.nextDocumentRange, "next");
+    if (descriptor.previousDocumentRange !== null)
+        assertDocumentRange(descriptor.previousDocumentRange, "previous");
+    if (!Number.isSafeInteger(descriptor.verticalShiftRows))
+        throw new TypeError("viewport frame descriptor shift is invalid");
+    if (descriptor.previousDocumentRange === null && descriptor.verticalShiftRows !== 0) {
+        throw new TypeError("viewport frame descriptor initial shift is invalid");
+    }
+    if (descriptor.previousDocumentRange !== null
+        && descriptor.verticalShiftRows !== descriptor.nextDocumentRange.start - descriptor.previousDocumentRange.start) {
+        throw new TypeError("viewport frame descriptor shift disagrees with document ranges");
+    }
+    if (descriptor.safeVerticalShift && (descriptor.verticalShiftRows <= 0
+        || descriptor.previousFollowingEnd !== true
+        || !descriptor.followingEnd
+        || descriptor.cause !== "follow-shift")) {
+        throw new TypeError("viewport frame descriptor marks an unsafe shift");
+    }
+    if (!Number.isSafeInteger(descriptor.selectionRevision) || descriptor.selectionRevision < 0) {
+        throw new TypeError("viewport frame descriptor selection revision is invalid");
+    }
+    if (descriptor.selectionDamagedRows.some((row, index) => !Number.isSafeInteger(row)
+        || row < 1 || row > descriptor.height || (index > 0 && row <= descriptor.selectionDamagedRows[index - 1]))) {
+        throw new TypeError("viewport frame descriptor selection damage is invalid");
+    }
+}
+function assertRectangle(rectangle, height, label) {
+    if (rectangle === null)
+        return;
+    if (!Number.isSafeInteger(rectangle.rowStart) || !Number.isSafeInteger(rectangle.rowEnd)
+        || rectangle.rowStart < 1 || rectangle.rowEnd < rectangle.rowStart || rectangle.rowEnd > height) {
+        throw new TypeError(`viewport frame descriptor ${label} region is invalid`);
+    }
+}
+function assertDocumentRange(range, label) {
+    if (!Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end < range.start) {
+        throw new TypeError(`viewport frame descriptor ${label} document range is invalid`);
+    }
+}
+function sameRectangle(left, right) {
+    return left === null ? right === null : right !== null && left.rowStart === right.rowStart && left.rowEnd === right.rowEnd;
+}
 function clamp(value, minimum, maximum) {
     return Math.min(Math.max(value, minimum), maximum);
 }

package/dist/ui/settings/sections.d.ts

@@ -15,8 +15,6 @@ export interface OwnedUiSettingsEntry {
     readonly storedValue: unknown;
     readonly effectiveValue: unknown;
     readonly editable: boolean;
-    readonly available: boolean;
-    readonly limitationReason: string | null;
     readonly choices: readonly OwnedUiSettingValue[] | null;
     /** True when the value is a structured object edited through its own surface. */
     readonly structured: boolean;

package/dist/ui/settings/sections.js

@@ -15,8 +15,6 @@ export function buildOwnedUiSettingsSections(input) {
             storedValue: setting.value,
             effectiveValue: setting.value,
             editable: true,
-            available: true,
-            limitationReason: null,
             structured: false,
             minimum: null,
             maximum: null,
@@ -52,9 +50,12 @@ function agentSection(snapshot) {
         return frozenSection(`Agent settings are unavailable: ${snapshot.failure}`, null, []);
     }
     if (snapshot.descriptors.length === 0) {
-        return frozenSection("The agent engine reported no settings", null, []);
+        return { id: AGENT_SECTION_ID, title: "Agent", entries: Object.freeze([]), unavailableReason: null, readOnlyReason: null };
     }
-    const entries = snapshot.descriptors.map(descriptor => {
+    const presented = snapshot.writeAdvertised
+        ? snapshot.descriptors.filter(descriptor => descriptor.writable && descriptor.available)
+        : [];
+    const entries = presented.map(descriptor => {
         const raw = descriptor.storedValue;
         return {
             id: descriptor.key,
@@ -65,33 +66,26 @@ function agentSection(snapshot) {
             rawValue: raw,
             storedValue: descriptor.storedValue,
             effectiveValue: descriptor.effectiveValue,
-            available: descriptor.available,
-            limitationReason: descriptor.limitationReason,
-            // A structured value is editable through its own surface rather than a
-            // value menu, so it stays reachable instead of being reported as fixed.
-            editable: snapshot.writeAdvertised && descriptor.writable && descriptor.available,
+            // Invariant: unavailable and non-writable descriptors are filtered before projection.
+            // Every presented structured value remains editable through its own surface.
+            editable: true,
             structured: descriptor.valueType === "json",
             minimum: descriptor.minimum ?? null,
             maximum: descriptor.maximum ?? null,
             flags: descriptor.flags ?? [],
-            // A boolean is a two-value choice even when the engine names no choices,
+            // Protocol: a boolean is a two-value choice even when the engine names no choices,
             // so it opens the same menu as any other enumerated setting.
             choices: descriptor.valueType === "boolean" ? BOOLEAN_CHOICES : choicesOf(descriptor.choices),
             origin: "engine",
             application: descriptor.application,
         };
     });
-    const readOnlyReason = snapshot.writeAdvertised
-        ? (entries.some(entry => entry.editable)
-            ? null
-            : "The agent engine reports no writable settings")
-        : "The agent engine does not support changing settings from this surface";
     return {
         id: AGENT_SECTION_ID,
         title: "Agent",
         entries: Object.freeze(entries),
         unavailableReason: null,
-        readOnlyReason,
+        readOnlyReason: null,
     };
 }
 function frozenSection(unavailableReason, readOnlyReason, entries) {

package/dist/ui/settings/session.js

@@ -49,7 +49,7 @@ export class OwnedUiSettingsSession {
         if (entry === null)
             return failed(`unknown ${backend} setting: ${id}`);
         if (!entry.editable)
-            return failed(entry.limitationReason ?? `${id} is not editable from this surface`);
+            return failed(`${id} is not editable from this surface`);
         return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgentValue(id, value);
     }
     #changeOwned(id, value) {
@@ -78,7 +78,7 @@ export class OwnedUiSettingsSession {
         }
         let result;
         try {
-            // The coordinator behind the port owns effect installation, persistence,
+            // Invariant: the coordinator behind the port owns effect installation, persistence,
             // flush, and rollback. A second surface-level flush would split authority.
             result = await agent.writeSetting(id, value);
         }
@@ -102,10 +102,11 @@ async function snapshotOf(agent, hidden) {
         const listed = await agent.listSettings();
         for (const descriptor of listed)
             assertAgentSettingDescriptor(descriptor);
-        const descriptors = listed.filter(descriptor => !hidden.has(descriptor.key));
+        const writeAdvertised = agent.capabilities.write && typeof agent.writeSetting === "function";
+        const descriptors = listed.filter(descriptor => !hidden.has(descriptor.key) && writeAdvertised && descriptor.writable && descriptor.available);
         return {
             descriptors,
-            writeAdvertised: agent.capabilities.write && typeof agent.writeSetting === "function",
+            writeAdvertised,
             failure: null,
         };
     }

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

@@ -13,6 +13,7 @@ export interface OwnedUiSettingsWriteOutcome {
     /** Present when the write failed; the caller must not report the change as saved. */
     readonly failure: string | null;
 }
+/** Resolves and atomically persists one profile's owned settings without discarding unknown keys. */
 export declare class OwnedUiSettingsStore {
     #private;
     constructor(options: OwnedUiSettingsStoreOptions);

package/dist/ui/settings/store.js

@@ -5,6 +5,7 @@ import { OWNED_UI_SETTINGS_MIGRATIONS } from "./migrations.js";
 import { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, } from "./resolution.js";
 const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const MAX_DOCUMENT_BYTES = 256 * 1024;
+/** Resolves and atomically persists one profile's owned settings without discarding unknown keys. */
 export class OwnedUiSettingsStore {
     #file;
     #declarations;
@@ -76,7 +77,7 @@ export class OwnedUiSettingsStore {
                 rmSync(temporary, { force: true });
             }
             catch {
-                // A leftover temporary file is inert: read() only ever opens the target path.
+                // Security: a leftover temporary file is inert: read() only ever opens the target path.
             }
             return { stored: false, failure: `${this.#file} could not be written: ${describe(error)}` };
         }