@timurproko/a1 0.1.8-dev.137 → 0.1.8-dev.151

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

@@ -0,0 +1,381 @@
+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";
+const CONTROL_STYLE_RESET = "\u001b]8;;\u001b\\\u001b[0m";
+const DEFAULT_CONFIG = {
+    scrollbarAppearance: "auto",
+    scrollbarStyle: "thin",
+};
+const PLAIN_THEME = {
+    track: text => text,
+    thumb: text => text,
+    sticky: (text, hovered) => hovered ? `\u001b[7m${text}\u001b[27m` : text,
+    quietSticky: faint,
+    bottomControl: (text, hovered) => hovered ? `\u001b[7m${text}\u001b[27m` : `\u001b[7m${text}\u001b[27m`,
+    selection: (line, from, to) => backgroundSgrSpan(line, from, to),
+};
+/**
+ * A1-owned viewport state. It knows only rows and semantic prompt anchors; Pi
+ * components and transcript payloads remain outside this neutral boundary.
+ */
+export class TranscriptViewport {
+    #config = DEFAULT_CONFIG;
+    #scrollTop = 0;
+    #maxScroll = 0;
+    #followingEnd = true;
+    #newMessages = 0;
+    #activeUntil = 0;
+    #railHovered = false;
+    #railDragging = false;
+    #stickyHovered = false;
+    #bottomHovered = false;
+    #selection;
+    #selectionClick;
+    #documentRows = [];
+    #selectableDocumentRowCount = 0;
+    #promptAnchors = [];
+    #contentWidth = 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; }
+    /** Counts one completed assistant reply while detached; tool rows never call this. */
+    noteNewMessage() {
+        if (this.#followingEnd)
+            return false;
+        this.#newMessages += 1;
+        return true;
+    }
+    setConfig(config) {
+        this.#config = config;
+        if (config.scrollbarAppearance === "hidden") {
+            this.#railHovered = false;
+            this.#railDragging = false;
+        }
+    }
+    noteScrollActivity(now = Date.now(), lingerMs = 900) {
+        this.#activeUntil = Math.max(this.#activeUntil, now + lingerMs);
+    }
+    setRailHovered(hovered) { this.#railHovered = hovered; }
+    setRailDragging(dragging) { this.#railDragging = dragging; }
+    setStickyHovered(hovered) { this.#stickyHovered = hovered; }
+    setBottomHovered(hovered) { this.#bottomHovered = hovered; }
+    get selectionActive() { return this.#selection?.selecting === true; }
+    get hasSelection() { return orderedTextSelection(this.#selection) !== undefined; }
+    pressSelection(column, viewportRow, now = Date.now()) {
+        const viewportHeight = this.#frame?.hits.viewportHeight ?? 0;
+        if (viewportRow < 1 || viewportRow > viewportHeight || column < 1 || column > this.#contentWidth)
+            return false;
+        const line = clamp(this.#scrollTop + viewportRow - 1, 0, Math.max(0, this.#documentRows.length - 1));
+        if (line >= this.#selectableDocumentRowCount)
+            return false;
+        const pressed = pressTextSelection({
+            line,
+            column,
+            contentWidth: this.#contentWidth,
+            lineText: this.#documentRows[line] ?? "",
+            lineContent: this.#lineContentAt(line),
+            ...(this.#selectionClick === undefined ? {} : { previousClick: this.#selectionClick }),
+            now,
+        });
+        this.#selection = pressed.selection;
+        this.#selectionClick = pressed.click;
+        return true;
+    }
+    extendSelection(column, viewportRow, now = Date.now(), autoScroll = true) {
+        const selection = this.#selection;
+        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
+        // owns edge scrolling. This option prevents high-rate motion reports from
+        // adding irregular extra rows between timer ticks.
+        if (autoScroll && viewportRow > viewportHeight)
+            this.scrollBy(1, now);
+        else if (autoScroll && viewportRow <= 1 && this.#scrollTop > 0)
+            this.scrollBy(-1, now);
+        const lastSelectableLine = Math.min(this.#documentRows.length, this.#selectableDocumentRowCount) - 1;
+        if (lastSelectableLine < 0)
+            return false;
+        const visibleRow = clamp(viewportRow, 1, viewportHeight);
+        const line = clamp(this.#scrollTop + visibleRow - 1, 0, lastSelectableLine);
+        const targetColumn = selection.fullRow
+            ? textSelectionLineExtendColumn(selection, line, this.#contentWidth)
+            : clamp(column, 1, this.#contentWidth);
+        this.#selection = extendTextSelection(selection, { line, column: targetColumn });
+        return true;
+    }
+    releaseSelection() {
+        if (this.#selection?.selecting !== true)
+            return false;
+        this.#selection = releaseTextSelection(this.#selection);
+        return true;
+    }
+    clearSelection() {
+        if (this.#selection === undefined)
+            return false;
+        this.#selection = undefined;
+        return true;
+    }
+    selectedText() {
+        const selection = orderedTextSelection(this.#selection);
+        if (selection === undefined)
+            return null;
+        return textSelectionText(selection, this.#documentRows.slice(0, this.#selectableDocumentRowCount), line => this.#lineContentAt(line));
+    }
+    scrollBy(lines, now = Date.now()) {
+        if (this.#maxScroll <= 0 || lines === 0)
+            return false;
+        const base = this.#followingEnd ? this.#maxScroll : this.#scrollTop;
+        const next = clamp(base + lines, 0, this.#maxScroll);
+        this.#scrollTop = next;
+        this.#followingEnd = next >= this.#maxScroll;
+        if (this.#followingEnd)
+            this.#newMessages = 0;
+        this.noteScrollActivity(now);
+        return true;
+    }
+    scrollTo(position, now = Date.now()) {
+        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.
+        this.#followingEnd = next >= this.#maxScroll;
+        if (this.#followingEnd)
+            this.#newMessages = 0;
+        this.noteScrollActivity(now);
+        return changed;
+    }
+    scrollToEnd(now = Date.now()) {
+        const changed = !this.#followingEnd || this.#scrollTop !== this.#maxScroll;
+        this.#followingEnd = true;
+        this.#scrollTop = this.#maxScroll;
+        this.#newMessages = 0;
+        this.noteScrollActivity(now);
+        return changed;
+    }
+    /** Jumps to the pinned prompt governing this position, then earlier prompts. */
+    scrollToPreviousPrompt(now = Date.now()) {
+        let target = -1;
+        let earliest = Number.POSITIVE_INFINITY;
+        for (const anchor of this.#promptAnchors) {
+            earliest = Math.min(earliest, anchor.firstRow);
+            if (anchor.firstRow < this.#scrollTop && anchor.firstRow > target)
+                target = anchor.firstRow;
+        }
+        // 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;
+        return target >= 0 && this.scrollTo(destination, now);
+    }
+    /** Jumps to the next submitted prompt after the prompt at the current stop. */
+    scrollToNextPrompt(now = Date.now()) {
+        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
+        // 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;
+        for (const anchor of this.#promptAnchors) {
+            if (anchor.firstRow > after && anchor.firstRow < target)
+                target = anchor.firstRow;
+        }
+        return Number.isFinite(target) && this.scrollTo(target, now);
+    }
+    reset() {
+        this.#scrollTop = 0;
+        this.#maxScroll = 0;
+        this.#followingEnd = true;
+        this.#newMessages = 0;
+        this.#selection = undefined;
+        this.#selectionClick = undefined;
+        this.#documentRows = [];
+        this.#selectableDocumentRowCount = 0;
+        this.#promptAnchors = [];
+        this.#contentWidth = 0;
+        this.clearTransient();
+        this.#frame = null;
+    }
+    clearTransient() {
+        this.#activeUntil = 0;
+        this.#railHovered = false;
+        this.#railDragging = false;
+        this.#stickyHovered = false;
+        this.#bottomHovered = false;
+    }
+    compose(input) {
+        const width = Math.max(1, input.width);
+        const height = Math.max(0, input.height);
+        const theme = input.theme ?? PLAIN_THEME;
+        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);
+        if (this.#followingEnd)
+            this.#scrollTop = this.#maxScroll;
+        else
+            this.#scrollTop = clamp(this.#scrollTop, 0, this.#maxScroll);
+        if (this.#scrollTop >= this.#maxScroll)
+            this.#followingEnd = true;
+        if (this.#followingEnd)
+            this.#newMessages = 0;
+        const geometry = scrollbarGeometry({
+            contentLength: input.documentRows.length,
+            viewportHeight,
+            scroll: this.#scrollTop,
+            // The session rail deliberately starts one line below the viewport top.
+            trackHeight: Math.max(0, viewportHeight - 1),
+        });
+        const presentation = scrollbarPresentation({
+            geometry,
+            appearance: this.#config.scrollbarAppearance,
+            style: this.#config.scrollbarStyle,
+            hovered: this.#railHovered,
+            dragging: this.#railDragging,
+            activeUntil: this.#activeUntil,
+            now: input.now ?? Date.now(),
+        });
+        const contentWidth = presentation.reservesSpace ? Math.max(1, width - 1) : width;
+        this.#documentRows = input.documentRows;
+        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 visible = input.documentRows
+            .slice(this.#scrollTop, this.#scrollTop + viewportHeight)
+            .map(paintDocumentRow);
+        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
+            // 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);
+            visible[0] = quiet && !this.#stickyHovered ? theme.quietSticky(sticky) : sticky;
+        }
+        const orderedSelection = orderedTextSelection(this.#selection);
+        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
+            // 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.
+            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);
+            }
+            visible[row] = line;
+        }
+        const frameRows = [...visible, ...dock].slice(0, height);
+        let bottomHit = null;
+        if (geometry !== null && !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) `
+                : genericLabel;
+            const label = displayWidth(countedLabel) <= contentWidth ? countedLabel : genericLabel;
+            const labelWidth = displayWidth(label);
+            if (labelWidth <= contentWidth) {
+                const fallbackRow = Math.max(0, viewportHeight - 1);
+                const row = clamp(input.bottomControlRow ?? fallbackRow, 0, frameRows.length - 1);
+                const left = Math.floor((contentWidth - labelWidth) / 2);
+                frameRows[row] = overlaySpan(padRowPreservingBackground(frameRows[row] ?? "", width), left, left + labelWidth, `${CONTROL_STYLE_RESET}${theme.bottomControl(label, this.#bottomHovered)}`);
+                bottomHit = { row: row + 1, columnStart: left + 1, columnEnd: left + labelWidth };
+            }
+        }
+        const hits = {
+            viewportHeight,
+            rail: geometry === null || this.#config.scrollbarAppearance === "hidden" ? null : {
+                column: width,
+                rowStart: 2,
+                trackHeight: Math.max(0, viewportHeight - 1),
+                geometry,
+            },
+            sticky: stickyActive ? { row: 1, target: governing.firstRow, width: contentWidth } : null,
+            bottom: bottomHit,
+        };
+        const frame = {
+            rows: frameRows,
+            contentWidth,
+            scrollTop: this.#scrollTop,
+            maxScroll: this.#maxScroll,
+            followingEnd: this.#followingEnd,
+            hits,
+        };
+        this.#frame = frame;
+        return frame;
+    }
+    #lineContentAt(line) {
+        const plain = stripAnsi(this.#documentRows[line] ?? "");
+        const prompt = this.#promptAnchors.find(anchor => line >= anchor.firstRow && line <= anchor.lastRow);
+        if (prompt !== undefined) {
+            if (line === prompt.firstRow) {
+                const timestamp = /\s+\d{2}:\d{2}\s*$/.exec(plain);
+                if (timestamp !== null)
+                    return usefulTextLineContent(plain.slice(0, timestamp.index), 3);
+            }
+            return usefulTextLineContent(plain, 3);
+        }
+        const from = plain.trim().length === 0 || (plain.startsWith(" ") && !plain.startsWith("  ")) ? 2 : 1;
+        const content = usefulTextLineContent(plain, from);
+        if (plain.trim().length === 0)
+            return { from, to: from + 1 };
+        return content;
+    }
+}
+function governingPrompt(anchors, scrollTop) {
+    let result = null;
+    for (const anchor of anchors) {
+        if (anchor.firstRow > scrollTop)
+            break;
+        result = anchor;
+    }
+    return result;
+}
+function padRowPreservingBackground(line, width) {
+    const shown = displayWidth(line) > width ? truncateToWidth(line, width) : line;
+    const padding = Math.max(0, width - displayWidth(shown));
+    if (padding === 0)
+        return shown;
+    const background = /\u001b\[(?:4[0-8]|10[0-7]|48;(?:2;\d+;\d+;\d+|5;\d+))m/.exec(line)?.[0];
+    const reverse = /\u001b\[(?:7(?:;[0-9]+)*|[0-9;]*;7(?:;[0-9]+)*)m/.exec(line)?.[0];
+    if (background)
+        return `${shown}${background}${" ".repeat(padding)}\u001b[49m`;
+    if (reverse)
+        return `${shown}${reverse}${" ".repeat(padding)}\u001b[27m`;
+    return shown + " ".repeat(padding);
+}
+function clamp(value, minimum, maximum) {
+    return Math.min(Math.max(value, minimum), maximum);
+}

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

@@ -1,8 +1,15 @@
-export declare const OWNED_UI_SETTINGS_VERSION = 1;
+export declare const OWNED_UI_SETTINGS_VERSION = 3;
 export type OwnedUiSettingValue = string | number | boolean;
 export type OwnedUiSettingApplication = "live" | "restart";
 export interface OwnedUiSettingDeclaration {
     readonly id: string;
+    /** Optional presentation label; the id remains the persistence key. */
+    readonly label?: string;
+    /** Optional settings-screen group for related owned controls. */
+    readonly section?: {
+        readonly id: string;
+        readonly title: string;
+    };
     readonly description: string;
     readonly application: OwnedUiSettingApplication;
     readonly defaultValue: OwnedUiSettingValue;

package/dist/ui/settings/declarations.js

@@ -1,13 +1,34 @@
-export const OWNED_UI_SETTINGS_VERSION = 1;
+export const OWNED_UI_SETTINGS_VERSION = 3;
 const MAX_ID_LENGTH = 64;
 const ID_PATTERN = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
+const SCROLL_SECTION = Object.freeze({ id: "scroll", title: "Scroll" });
 export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
     Object.freeze({
-        id: "transcriptDensity",
-        description: "Vertical density of transcript content. Reserved for the custom-viewport milestone; no visible effect yet.",
+        id: "scrollbarAppearance",
+        label: "Scrollbar mode",
+        section: SCROLL_SECTION,
+        description: "When the session transcript scrollbar is visible.",
         application: "live",
-        defaultValue: "comfortable",
-        allowedValues: Object.freeze(["comfortable", "compact"]),
+        defaultValue: "auto",
+        allowedValues: Object.freeze(["auto", "always", "hidden"]),
+    }),
+    Object.freeze({
+        id: "scrollbarStyle",
+        label: "Scrollbar style",
+        section: SCROLL_SECTION,
+        description: "Visual weight of the session transcript scrollbar.",
+        application: "live",
+        defaultValue: "thin",
+        allowedValues: Object.freeze(["thin", "thick"]),
+    }),
+    Object.freeze({
+        id: "scrollbarSpeed",
+        label: "Speed",
+        section: SCROLL_SECTION,
+        description: "Distance moved by each session transcript wheel event.",
+        application: "live",
+        defaultValue: "normal",
+        allowedValues: Object.freeze(["normal", "fast", "high"]),
     }),
 ]);
 export function assertOwnedUiSettingDeclarations(declarations) {
@@ -19,6 +40,13 @@ export function assertOwnedUiSettingDeclarations(declarations) {
         if (seen.has(declaration.id))
             throw new Error(`duplicate owned UI setting id: ${declaration.id}`);
         seen.add(declaration.id);
+        if (declaration.label !== undefined && declaration.label.trim().length === 0) {
+            throw new Error(`owned UI setting has an empty label: ${declaration.id}`);
+        }
+        if (declaration.section !== undefined
+            && (declaration.section.id.trim().length === 0 || declaration.section.title.trim().length === 0)) {
+            throw new Error(`owned UI setting has an invalid section: ${declaration.id}`);
+        }
         if (declaration.description.trim().length === 0) {
             throw new Error(`owned UI setting has no description: ${declaration.id}`);
         }

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

@@ -6,7 +6,7 @@ export interface OwnedUiSettingsMigration {
 }
 /**
  * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
- * is the first stored shape, so nothing precedes it and the list is empty.
+ * is the first stored shape.
  */
 export declare const OWNED_UI_SETTINGS_MIGRATIONS: readonly OwnedUiSettingsMigration[];
 export declare function assertOwnedUiSettingsMigrations(migrations: readonly OwnedUiSettingsMigration[], currentVersion?: number): void;

package/dist/ui/settings/migrations.js

@@ -1,9 +1,28 @@
 import { OWNED_UI_SETTINGS_VERSION } from "./declarations.js";
 /**
  * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
- * is the first stored shape, so nothing precedes it and the list is empty.
+ * is the first stored shape.
  */
-export const OWNED_UI_SETTINGS_MIGRATIONS = Object.freeze([]);
+export const OWNED_UI_SETTINGS_MIGRATIONS = Object.freeze([
+    Object.freeze({
+        to: 2,
+        description: "Rename scrollbar speed high to fast.",
+        migrate(values) {
+            return values.scrollbarSpeed === "high"
+                ? { ...values, scrollbarSpeed: "fast" }
+                : { ...values };
+        },
+    }),
+    Object.freeze({
+        to: 3,
+        description: "Match Pi's auto scrollbar appearance name and ordering.",
+        migrate(values) {
+            return values.scrollbarAppearance === "hover"
+                ? { ...values, scrollbarAppearance: "auto" }
+                : { ...values };
+        },
+    }),
+]);
 export function assertOwnedUiSettingsMigrations(migrations, currentVersion = OWNED_UI_SETTINGS_VERSION) {
     const firstProduced = currentVersion - migrations.length + 1;
     if (migrations.length > 0 && firstProduced < 2) {

package/dist/ui/settings/sections.js

@@ -1,12 +1,13 @@
 export const AGENT_SECTION_ID = "agent";
 const BOOLEAN_CHOICES = Object.freeze([true, false]);
 export function buildOwnedUiSettingsSections(input) {
-    const ownedSection = {
-        id: "a1",
-        title: "A1",
-        entries: Object.freeze(input.resolution.settings.map(setting => ({
+    const grouped = new Map();
+    for (const setting of input.resolution.settings) {
+        const section = setting.declaration.section ?? { id: "a1", title: "A1" };
+        const group = grouped.get(section.id) ?? { title: section.title, entries: [] };
+        group.entries.push({
             id: setting.declaration.id,
-            label: null,
+            label: setting.declaration.label ?? null,
             backend: "a1",
             description: setting.declaration.description,
             value: setting.value,
@@ -19,11 +20,17 @@ export function buildOwnedUiSettingsSections(input) {
             choices: setting.declaration.allowedValues,
             origin: setting.source,
             application: setting.declaration.application,
-        }))),
+        });
+        grouped.set(section.id, group);
+    }
+    const ownedSections = [...grouped].map(([id, group]) => ({
+        id,
+        title: group.title,
+        entries: Object.freeze(group.entries),
         unavailableReason: null,
         readOnlyReason: null,
-    };
-    return Object.freeze([ownedSection, agentSection(input.agent)]);
+    }));
+    return Object.freeze([...ownedSections, agentSection(input.agent)]);
 }
 export function findOwnedUiSettingsEntry(sections, id, backend) {
     for (const section of sections) {

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

@@ -19,6 +19,8 @@ export interface OwnedUiSettingsSessionOptions {
      * whose runtime is not up yet. Takes precedence over `agent`.
      */
     readonly agentProvider?: () => AgentSettingsPort | null;
+    /** Agent-owned controls fixed by this product surface and therefore omitted. */
+    readonly hiddenAgentSettingIds?: readonly string[];
 }
 export type OwnedUiSettingsListener = (session: OwnedUiSettingsSession) => void;
 /**

package/dist/ui/settings/session.js

@@ -9,6 +9,7 @@ export class OwnedUiSettingsSession {
     #agent;
     #agentProvider;
     #listeners = new Set();
+    #hiddenAgentSettingIds;
     #resolution;
     #agentSnapshot = null;
     #pending = new Map();
@@ -16,6 +17,7 @@ export class OwnedUiSettingsSession {
         this.#store = options.store;
         this.#agent = options.agent ?? null;
         this.#agentProvider = options.agentProvider ?? null;
+        this.#hiddenAgentSettingIds = new Set(options.hiddenAgentSettingIds ?? []);
         this.#resolution = options.store.read();
     }
     get resolution() {
@@ -25,7 +27,7 @@ export class OwnedUiSettingsSession {
     async load() {
         this.#resolution = this.#store.read();
         const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
-        this.#agentSnapshot = agent === null ? null : await snapshotOf(agent);
+        this.#agentSnapshot = agent === null ? null : await snapshotOf(agent, this.#hiddenAgentSettingIds);
         this.#notify();
     }
     sections() {
@@ -61,7 +63,7 @@ export class OwnedUiSettingsSession {
         catch (error) {
             return failed(`${id} could not be written to the agent engine: ${describe(error)}`);
         }
-        this.#agentSnapshot = await snapshotOf(agent);
+        this.#agentSnapshot = await snapshotOf(agent, this.#hiddenAgentSettingIds);
         this.#notify();
         return { applied: true, pendingRestart: false, failure: null };
     }
@@ -105,7 +107,7 @@ export class OwnedUiSettingsSession {
         catch (error) {
             return failed(`${id} could not be written to the agent engine: ${describe(error)}`);
         }
-        this.#agentSnapshot = await snapshotOf(agent);
+        this.#agentSnapshot = await snapshotOf(agent, this.#hiddenAgentSettingIds);
         this.#notify();
         return { applied: true, pendingRestart: false, failure: null };
     }
@@ -114,9 +116,9 @@ export class OwnedUiSettingsSession {
             listener(this);
     }
 }
-async function snapshotOf(agent) {
+async function snapshotOf(agent, hidden) {
     try {
-        const descriptors = await agent.listSettings();
+        const descriptors = (await agent.listSettings()).filter(descriptor => !hidden.has(descriptor.key));
         const values = {};
         for (const descriptor of descriptors) {
             try {

package/docs/architecture/boundaries.md

@@ -13,9 +13,9 @@ mutable a1 entry
   -> owned Pi-backed composition, with A1 surfaces enabled only for bare a1
 ```
 
-Launch-instance ownership is plural. The supervisor tracks any number of independently authenticated `a1`, `a1 pi`, and `a1 sandbox` instances and never uses one product-wide foreground mutex. Closing one instance closes only its verified process tree. Persisted rows alone do not prove liveness, and uncertainty never authorizes terminating an unrelated process.
+Launch-instance ownership is plural. The supervisor tracks any number of independently authenticated `a1` and `a1 pi` instances and never uses one product-wide foreground mutex. Closing one instance closes only its verified process tree. Persisted rows alone do not prove liveness, and uncertainty never authorizes terminating an unrelated process.
 
-Neither guardian reads ordinary terminal input, parses or relays runtime output, renders cells, infers frames, synthesizes terminal responses, or emits display control. All profiles use the same owned rendering and input pipeline. Bare `a1` exposes A1-owned surfaces; `a1 pi` and `a1 sandbox` withhold those surfaces and select their own profile roots. The private guardian boundary carries only bounded identity, readiness, stop, and outcome data.
+Neither guardian reads ordinary terminal input, parses or relays runtime output, renders cells, infers frames, synthesizes terminal responses, or emits display control. Both profiles use the same owned rendering and input pipeline. Bare `a1` exposes A1-owned surfaces; `a1 pi` withholds those surfaces and uses Pi's ordinary profile root. The private guardian boundary carries only bounded identity, readiness, stop, and outcome data.
 
 The owned Pi-backed surface is not an arbitrary-CLI terminal multiplexer. A feature that requires resident arbitrary CLI sessions, internal tabs, terminal-state reconnection, or A1-authoritative scrollback must introduce and certify the separate composed-terminal authority rather than reactivating the retired transparent attachment path.
 
@@ -30,7 +30,7 @@ The owned Pi-backed surface is not an arbitrary-CLI terminal multiplexer. A feat
 - `protocol`: additive control handshake, bounded line framing, authenticated launch-instance commands, typed stop intent, snapshots, and command results.
 - `storage`: SQLite migrations, prior-boot reconciliation, and plural launch-instance persistence. Legacy foreground rows are historical migration input and never authorize current ownership.
 - `supervisor`: endpoint identity, plural cohort ownership, per-instance reconciliation, and aggregate release shutdown coordination. It owns no terminal surface.
-- `pi-engine-adapter`, `pi-component-adapter`, `pi-tui-runtime-adapter`, and `pi-owned-ui-integration`: isolate pinned Pi engine and presentation knowledge behind neutral contracts; product features do not import them directly.
+- `pi-engine-adapter`, `pi-component-adapter`, `pi-tui-runtime-adapter`, and `pi-session-ui-integration`: isolate pinned Pi engine and presentation knowledge behind neutral contracts; product features do not import them directly. The session UI render root assembles semantic document and dock rows, while its focused viewport controller owns follow state, pointer routing, selection, and interaction timers. Owned-app route lifecycle belongs to the neutral `ui-apps` owner and is only hosted by the Pi session UI.
 - release/update/bootstrap: package-derived immutable release identity, process-guardian integrity, cohort selection, durable update transactions, rollback, and dependency-light command entry.
 
 ## Dependency direction

package/docs/architecture/project-structure.md

@@ -23,7 +23,7 @@ src/
     pi/
       components/                  pinned Pi component and theme adaptation
       engine/                      pinned Pi engine, settings, resource, package, and workflow integration
-      owned-ui/                    Pi-backed owned session shell and route host
+      session-ui/                  Pi-backed session shell and A1 viewport integration
       tui-runtime/                 neutral presentation runtime over pinned Pi TUI
   foundation/
     launch-guardian/               authenticated launch-instance coordination
@@ -97,7 +97,7 @@ Build output mirrors the production namespaces directly under ignored `dist/`, w
 
 ## Terminal capability boundary
 
-All interactive profiles use the owned rendering pipeline. Bare `a1` exposes A1-owned surfaces; `a1 pi` and `a1 sandbox` withhold those surfaces while using their respective Pi profile roots. The retired transparent attachment owner is not part of the production tree or dependency map.
+Both interactive profiles use the owned rendering pipeline. Bare `a1` exposes A1-owned surfaces; `a1 pi` withholds those surfaces while using Pi's ordinary profile root. The retired transparent attachment owner is not part of the production tree or dependency map.
 
 The current JavaScript control plane does not provide arbitrary-CLI tabs. Such tabs require the separately bounded console terminal host to own PTYs, authoritative terminal state, rendering, input routing, inactive-surface lifecycle, and reconnection. JavaScript may exchange typed identity, topology revision, capability, lifecycle, status, and recovery messages only; it must not relay terminal output, per-event child input, or rendered cells.
 

package/docs/architecture/resource-and-data-policy.md

@@ -46,7 +46,7 @@ Sanitization must classify before logging or storing. Unknown or untyped values
 
 - Structured/RPC semantics must not be inferred from ANSI text, terminal timing, or visual content.
 - Native-host protocol code must not carry PTY bytes, per-event child input, rendered cells, cell grids, framebuffers, or screen buffers.
-- `a1 pi` and `a1 sandbox` must not import, initialize, launch, or connect to composed terminal-host infrastructure.
+- `a1 pi` must not import, initialize, launch, or connect to composed terminal-host infrastructure.
 - Transparent direct attachment must remain independent of composed infrastructure and must not relay terminal data.
 - Recovery records store identity and bounded references, not terminal streams, authentication material, or arbitrary environment values.
 - A failed in-terminal 2×2 proof cannot be waived to merge composed infrastructure.