@timurproko/a1 0.1.8-dev.472 → 0.1.8-dev.508

package/dist/ui/apps/index.d.ts

@@ -1,3 +1,5 @@
-export * from "./contracts.js";
-export * from "./host.js";
-export * from "./registry.js";
+export { assertAppRegistration } from "./contracts.js";
+export type { AppHostServices, AppRegistration, AppSize, UiApp, UiRouteHost, UiRouteSurface } from "./contracts.js";
+export { UiAppHost } from "./host.js";
+export type { AppHostOptions, AppHostSurface } from "./host.js";
+export { UiAppRegistry } from "./registry.js";

package/dist/ui/apps/index.js

@@ -1,3 +1,3 @@
-export * from "./contracts.js";
-export * from "./host.js";
-export * from "./registry.js";
+export { assertAppRegistration } from "./contracts.js";
+export { UiAppHost } from "./host.js";
+export { UiAppRegistry } from "./registry.js";

package/dist/ui/components/index.d.ts

@@ -1,25 +1,47 @@
-export * from "./dialog-panel.js";
-export * from "./frame.js";
-export * from "./label.js";
-export * from "./line-input.js";
-export * from "./prompt-input.js";
-export * from "./list-block.js";
-export * from "./list-view.js";
-export * from "./mouse.js";
-export * from "./pane.js";
-export * from "./progress-status.js";
-export * from "./revision.js";
-export * from "./selection-copy.js";
-export * from "./scrollbar.js";
-export * from "./shortcuts.js";
-export * from "./spans.js";
-export * from "./visible-hyperlinks.js";
-export * from "./status-line.js";
-export * from "./submitted-prompt.js";
-export * from "./stepper.js";
-export * from "./transcript-viewport.js";
-export * from "./surface.js";
-export * from "./text.js";
-export * from "./text-selection.js";
-export * from "./theme.js";
-export * from "./value-menu.js";
+export { dialogRowAt, dialogValueColumn, renderDialogPanel } from "./dialog-panel.js";
+export type { DialogPanelFrame, DialogPanelState, DialogRow } from "./dialog-panel.js";
+export { FrameContractError, assertPaneRect, finalizeFrame, validateFrame } from "./frame.js";
+export type { PaneRect } from "./frame.js";
+export { humanizeLabel, humanizeTitle } from "./label.js";
+export { LineInput, caretCell, handleLineInputKey, renderInputRow, wordLeft, wordRight } from "./line-input.js";
+export type { InputRow, InputRowOptions, LineInputOutcome, LineInputView } from "./line-input.js";
+export { PROMPT_GLYPH, PROMPT_PREFIX_WIDTH, PromptInput, promptArrow, promptRule, promptRuleText } from "./prompt-input.js";
+export type { PromptInputBody, PromptInputMetrics } from "./prompt-input.js";
+export { blockJumpTarget, blockRowSpan, clampScroll, indexOfKey, layoutList, maxScrollFor, moveSelection, rowKey, scrollForSelection, selectableIndexes, stickyHeaderFor, topPaddingRows, visibleRowCount, } from "./list-block.js";
+export type { ListLayout, ListRow, ListRowSpan } from "./list-block.js";
+export { STEPPER_RESERVE, placementFor, regionAt, renderGroupHeader, renderListRow, renderNote, valueColumnFor } from "./list-view.js";
+export type { ListRegion, ListRowPlacement, ListRowState, ListViewRow } from "./list-view.js";
+export { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput, routeMouseInput } from "./mouse.js";
+export type { ParsedMouseInput, RoutedMouseInput } from "./mouse.js";
+export { isInsidePane, toPaneLocalMouse } from "./pane.js";
+export type { Pane, PaneInputResult, PaneMouseEvent } from "./pane.js";
+export { progressStatusText } from "./progress-status.js";
+export { FrameCache, RENDER_REVISION_KINDS, RenderRevisionTracker, ZERO_REVISIONS, normalizeRevisions, revisionsEqual } from "./revision.js";
+export type { RenderCacheContract, RenderRevisionKind, RenderRevisions } from "./revision.js";
+export { MAX_COPY_ROWS, MAX_COPY_SOURCE_UNITS, selectionCopyLineContent, selectionCopyRowText } from "./selection-copy.js";
+export type { SelectionCopyPrompt, SelectionCopyRow, SelectionCopySnapshot } from "./selection-copy.js";
+export { ScrollbarRails, isThumbRow, scrollForThumbRow, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, scrollbarReservesSpace, scrollbarSelectionRows, scrollbarWheelRows, } from "./scrollbar.js";
+export type { RailPointer, RailPosition, ScrollbarAppearance, ScrollbarGeometry, ScrollbarInput, ScrollbarPresentation, ScrollbarPresentationInput, ScrollbarSpeed, ScrollbarStyle, } from "./scrollbar.js";
+export { GLOBAL_SCOPE, ShortcutRegistry, assembleShortcuts, assertNoShortcutConflicts } from "./shortcuts.js";
+export type { ShortcutConflict, ShortcutDeclaration, ShortcutRegistryResult } from "./shortcuts.js";
+export { backgroundSgrSpan, heldNativeHyperlinkStyle, hyperlinkSgrSpan, hyperlinkTargetAtColumn, nativeHyperlinkStyle, overlaySpan } from "./spans.js";
+export { readVisibleHyperlinks } from "./visible-hyperlinks.js";
+export type { VisibleHyperlinkRange, VisibleHyperlinkRow } from "./visible-hyperlinks.js";
+export { renderStatusLine, statusText } from "./status-line.js";
+export type { StatusLineInput } from "./status-line.js";
+export { SUBMITTED_PROMPT_PREFIX_WIDTH, composeSubmittedPromptRows, formatSubmittedPromptTime, submittedPromptLayout } from "./submitted-prompt.js";
+export type { SubmittedPromptLayout, SubmittedPromptStyle } from "./submitted-prompt.js";
+export { numericValues, steppedValue, stepperEnds } from "./stepper.js";
+export type { NumericRange } from "./stepper.js";
+export { TranscriptViewport, assertTranscriptViewportFrameDescriptor } from "./transcript-viewport.js";
+export type { TranscriptPromptAnchor, TranscriptViewportConfig, TranscriptViewportFrame, TranscriptViewportFrameDescriptor, TranscriptViewportFrameInput, TranscriptViewportHitRegions, TranscriptViewportTheme, } from "./transcript-viewport.js";
+export { RAIL_COLUMNS, renderEmptyState, withScrollbarRail } from "./surface.js";
+export type { RailOptions } from "./surface.js";
+export { displayColumnSlice, displayWidth, displayWordColumnRange, faint, padToWidth, stripAnsi, truncateToWidth } from "./text.js";
+export type { DisplayColumnRange, DisplayColumnSlice } from "./text.js";
+export { TEXT_SELECTION_MULTI_CLICK_MS, extendTextSelection, orderedTextSelection, plainTextBetweenColumns, pressTextSelection, releaseTextSelection, textSelectionLineExtendColumn, textSelectionPointAt, textSelectionText, usefulTextLineContent, } from "./text-selection.js";
+export type { OrderedTextSelection, TextSelection, TextSelectionClick, TextSelectionLineContent, TextSelectionPoint, TextSelectionPressInput, } from "./text-selection.js";
+export { PLAIN_THEME } from "./theme.js";
+export type { UiTheme, UiThemeToken } from "./theme.js";
+export { menuRowAt, renderValueMenu, valueMenuFrame } from "./value-menu.js";
+export type { ValueMenuAnchor, ValueMenuFrame, ValueMenuLayout, ValueMenuState } from "./value-menu.js";

package/dist/ui/components/index.js

@@ -1,25 +1,25 @@
-export * from "./dialog-panel.js";
-export * from "./frame.js";
-export * from "./label.js";
-export * from "./line-input.js";
-export * from "./prompt-input.js";
-export * from "./list-block.js";
-export * from "./list-view.js";
-export * from "./mouse.js";
-export * from "./pane.js";
-export * from "./progress-status.js";
-export * from "./revision.js";
-export * from "./selection-copy.js";
-export * from "./scrollbar.js";
-export * from "./shortcuts.js";
-export * from "./spans.js";
-export * from "./visible-hyperlinks.js";
-export * from "./status-line.js";
-export * from "./submitted-prompt.js";
-export * from "./stepper.js";
-export * from "./transcript-viewport.js";
-export * from "./surface.js";
-export * from "./text.js";
-export * from "./text-selection.js";
-export * from "./theme.js";
-export * from "./value-menu.js";
+export { dialogRowAt, dialogValueColumn, renderDialogPanel } from "./dialog-panel.js";
+export { FrameContractError, assertPaneRect, finalizeFrame, validateFrame } from "./frame.js";
+export { humanizeLabel, humanizeTitle } from "./label.js";
+export { LineInput, caretCell, handleLineInputKey, renderInputRow, wordLeft, wordRight } from "./line-input.js";
+export { PROMPT_GLYPH, PROMPT_PREFIX_WIDTH, PromptInput, promptArrow, promptRule, promptRuleText } from "./prompt-input.js";
+export { blockJumpTarget, blockRowSpan, clampScroll, indexOfKey, layoutList, maxScrollFor, moveSelection, rowKey, scrollForSelection, selectableIndexes, stickyHeaderFor, topPaddingRows, visibleRowCount, } from "./list-block.js";
+export { STEPPER_RESERVE, placementFor, regionAt, renderGroupHeader, renderListRow, renderNote, valueColumnFor } from "./list-view.js";
+export { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput, routeMouseInput } from "./mouse.js";
+export { isInsidePane, toPaneLocalMouse } from "./pane.js";
+export { progressStatusText } from "./progress-status.js";
+export { FrameCache, RENDER_REVISION_KINDS, RenderRevisionTracker, ZERO_REVISIONS, normalizeRevisions, revisionsEqual } from "./revision.js";
+export { MAX_COPY_ROWS, MAX_COPY_SOURCE_UNITS, selectionCopyLineContent, selectionCopyRowText } from "./selection-copy.js";
+export { ScrollbarRails, isThumbRow, scrollForThumbRow, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, scrollbarReservesSpace, scrollbarSelectionRows, scrollbarWheelRows, } from "./scrollbar.js";
+export { GLOBAL_SCOPE, ShortcutRegistry, assembleShortcuts, assertNoShortcutConflicts } from "./shortcuts.js";
+export { backgroundSgrSpan, heldNativeHyperlinkStyle, hyperlinkSgrSpan, hyperlinkTargetAtColumn, nativeHyperlinkStyle, overlaySpan } from "./spans.js";
+export { readVisibleHyperlinks } from "./visible-hyperlinks.js";
+export { renderStatusLine, statusText } from "./status-line.js";
+export { SUBMITTED_PROMPT_PREFIX_WIDTH, composeSubmittedPromptRows, formatSubmittedPromptTime, submittedPromptLayout } from "./submitted-prompt.js";
+export { numericValues, steppedValue, stepperEnds } from "./stepper.js";
+export { TranscriptViewport, assertTranscriptViewportFrameDescriptor } from "./transcript-viewport.js";
+export { RAIL_COLUMNS, renderEmptyState, withScrollbarRail } from "./surface.js";
+export { displayColumnSlice, displayWidth, displayWordColumnRange, faint, padToWidth, stripAnsi, truncateToWidth } from "./text.js";
+export { TEXT_SELECTION_MULTI_CLICK_MS, extendTextSelection, orderedTextSelection, plainTextBetweenColumns, pressTextSelection, releaseTextSelection, textSelectionLineExtendColumn, textSelectionPointAt, textSelectionText, usefulTextLineContent, } from "./text-selection.js";
+export { PLAIN_THEME } from "./theme.js";
+export { menuRowAt, renderValueMenu, valueMenuFrame } from "./value-menu.js";

package/dist/ui/components/prompt-input.js

@@ -15,10 +15,7 @@ export function promptArrow(text, theme) {
 export class PromptInput {
     theme;
     metrics;
-    constructor(theme = PLAIN_THEME, metrics = { measure: displayWidth, truncate: truncateToWidth }) {
-        this.theme = theme;
-        this.metrics = metrics;
-    }
+    constructor(theme = PLAIN_THEME, metrics = { measure: displayWidth, truncate: truncateToWidth }) { this.theme = theme; this.metrics = metrics; }
     styleRule(text) { return promptRuleText(text); }
     geometry(width, padding = 0) {
         const prefixWidth = Math.min(PROMPT_PREFIX_WIDTH, Math.max(0, width));

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

@@ -17,6 +17,125 @@ export interface OwnedUiSettingDeclaration {
 }
 /** Playback lengths the quit outro offers, in milliseconds. */
 export declare const QUIT_EFFECT_DURATIONS_MS: readonly number[];
+/**
+ * Every A1 setting, keyed by its id. The table is the one declaration: ids, defaults, and allowed
+ * values are read from it, and `OwnedSettingValueOf` derives each getter's type from it.
+ */
+export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
+    readonly quitAnimation: Readonly<{
+        id: "quitAnimation";
+        label: "Exit animation";
+        section: Readonly<{
+            id: "generic";
+            title: "Generic";
+        }>;
+        description: "Play the quit effect when the session quits. Off returns to the terminal immediately.";
+        application: "live";
+        defaultValue: true;
+        allowedValues: readonly [true, false];
+    }>;
+    readonly scrollbarAppearance: Readonly<{
+        id: "scrollbarAppearance";
+        label: "Scrollbar mode";
+        section: Readonly<{
+            id: "scroll";
+            title: "Scroll";
+        }>;
+        description: "When the session transcript scrollbar is visible.";
+        application: "live";
+        defaultValue: "auto";
+        allowedValues: readonly ["auto", "always", "hidden"];
+    }>;
+    readonly scrollbarStyle: Readonly<{
+        id: "scrollbarStyle";
+        label: "Scrollbar style";
+        section: Readonly<{
+            id: "scroll";
+            title: "Scroll";
+        }>;
+        description: "Visual weight of the session transcript scrollbar.";
+        application: "live";
+        defaultValue: "thin";
+        allowedValues: readonly ["thin", "thick"];
+    }>;
+    readonly scrollbarSpeed: Readonly<{
+        id: "scrollbarSpeed";
+        label: "Speed";
+        section: Readonly<{
+            id: "scroll";
+            title: "Scroll";
+        }>;
+        description: "Distance moved by each session transcript wheel event.";
+        application: "live";
+        defaultValue: "normal";
+        allowedValues: readonly ["normal", "fast", "high"];
+    }>;
+    readonly promptHistoryEnabled: Readonly<{
+        id: "promptHistoryEnabled";
+        label: "Persistent history";
+        section: Readonly<{
+            id: "history";
+            title: "History";
+        }>;
+        description: "Retain reusable prompts across sessions. Applies on next start; disabling does not erase saved history or stop existing instances.";
+        application: "restart";
+        defaultValue: true;
+        allowedValues: readonly [true, false];
+    }>;
+    readonly promptHistoryMaxItems: Readonly<{
+        id: "promptHistoryMaxItems";
+        label: "History limit";
+        section: Readonly<{
+            id: "history";
+            title: "History";
+        }>;
+        description: "Maximum recent unique prompts after next start. Byte limits also apply; increasing the limit cannot restore pruned entries.";
+        application: "restart";
+        defaultValue: 100;
+        allowedValues: readonly [10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
+    }>;
+    readonly quitEffect: Readonly<{
+        id: "quitEffect";
+        label: "Effect";
+        section: Readonly<{
+            id: "quit";
+            title: "Quit";
+        }>;
+        description: "Animation played over the last screen when the session quits.";
+        application: "live";
+        defaultValue: "fall";
+        allowedValues: readonly ["fall", "dissolve", "starburst", "waves"];
+    }>;
+    readonly quitEffectDurationMs: Readonly<{
+        id: "quitEffectDurationMs";
+        label: "Duration";
+        section: Readonly<{
+            id: "quit";
+            title: "Quit";
+        }>;
+        description: "Milliseconds the quit animation plays before the terminal is restored.";
+        application: "live";
+        defaultValue: 800;
+        allowedValues: readonly number[];
+    }>;
+    readonly promptSuggestions: Readonly<{
+        id: "promptSuggestions";
+        label: "Prompt suggestions";
+        section: Readonly<{
+            id: "agent";
+            title: "Agent";
+        }>;
+        description: "Predict likely next prompts with one additional background request using the selected model.";
+        application: "live";
+        defaultValue: true;
+        allowedValues: readonly [true, false];
+    }>;
+}>;
+export type OwnedSettingId = keyof typeof OWNED_SETTING_DECLARATIONS;
+/** The value type a setting's declaration allows: a literal union for a choice, `number` for a stepped range. */
+export type OwnedSettingValueOf<Id extends OwnedSettingId> = (typeof OWNED_SETTING_DECLARATIONS)[Id]["allowedValues"][number];
+/** The declarations in declaration order, for resolution, persistence, and the settings screen. */
 export declare const OWNED_UI_SETTING_DECLARATIONS: readonly OwnedUiSettingDeclaration[];
+export declare function isOwnedSettingId(id: string): id is OwnedSettingId;
 export declare function assertOwnedUiSettingDeclarations(declarations: readonly OwnedUiSettingDeclaration[]): void;
 export declare function findOwnedUiSettingDeclaration(declarations: readonly OwnedUiSettingDeclaration[], id: string): OwnedUiSettingDeclaration | null;

package/dist/ui/settings/declarations.js

@@ -7,8 +7,12 @@ const SCROLL_SECTION = Object.freeze({ id: "scroll", title: "Scroll" });
 const QUIT_SECTION = Object.freeze({ id: "quit", title: "Quit" });
 /** Playback lengths the quit outro offers, in milliseconds. */
 export const QUIT_EFFECT_DURATIONS_MS = Object.freeze(Array.from({ length: 18 }, (_, index) => 300 + index * 100));
-export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
-    Object.freeze({
+/**
+ * Every A1 setting, keyed by its id. The table is the one declaration: ids, defaults, and allowed
+ * values are read from it, and `OwnedSettingValueOf` derives each getter's type from it.
+ */
+export const OWNED_SETTING_DECLARATIONS = Object.freeze({
+    quitAnimation: Object.freeze({
         id: "quitAnimation",
         label: "Exit animation",
         section: GENERIC_SECTION,
@@ -17,7 +21,7 @@ export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
         defaultValue: true,
         allowedValues: Object.freeze([true, false]),
     }),
-    Object.freeze({
+    scrollbarAppearance: Object.freeze({
         id: "scrollbarAppearance",
         label: "Scrollbar mode",
         section: SCROLL_SECTION,
@@ -26,7 +30,7 @@ export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
         defaultValue: "auto",
         allowedValues: Object.freeze(["auto", "always", "hidden"]),
     }),
-    Object.freeze({
+    scrollbarStyle: Object.freeze({
         id: "scrollbarStyle",
         label: "Scrollbar style",
         section: SCROLL_SECTION,
@@ -35,7 +39,7 @@ export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
         defaultValue: "thin",
         allowedValues: Object.freeze(["thin", "thick"]),
     }),
-    Object.freeze({
+    scrollbarSpeed: Object.freeze({
         id: "scrollbarSpeed",
         label: "Speed",
         section: SCROLL_SECTION,
@@ -44,7 +48,7 @@ export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
         defaultValue: "normal",
         allowedValues: Object.freeze(["normal", "fast", "high"]),
     }),
-    Object.freeze({
+    promptHistoryEnabled: Object.freeze({
         id: "promptHistoryEnabled",
         label: "Persistent history",
         section: Object.freeze({ id: "history", title: "History" }),
@@ -53,7 +57,7 @@ export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
         defaultValue: true,
         allowedValues: Object.freeze([true, false]),
     }),
-    Object.freeze({
+    promptHistoryMaxItems: Object.freeze({
         id: "promptHistoryMaxItems",
         label: "History limit",
         section: Object.freeze({ id: "history", title: "History" }),
@@ -62,7 +66,7 @@ export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
         defaultValue: 100,
         allowedValues: Object.freeze([10, 20, 30, 40, 50, 60, 70, 80, 90, 100]),
     }),
-    Object.freeze({
+    quitEffect: Object.freeze({
         id: "quitEffect",
         label: "Effect",
         section: QUIT_SECTION,
@@ -71,7 +75,7 @@ export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
         defaultValue: "fall",
         allowedValues: Object.freeze(["fall", "dissolve", "starburst", "waves"]),
     }),
-    Object.freeze({
+    quitEffectDurationMs: Object.freeze({
         id: "quitEffectDurationMs",
         label: "Duration",
         section: QUIT_SECTION,
@@ -80,7 +84,7 @@ export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
         defaultValue: 800,
         allowedValues: QUIT_EFFECT_DURATIONS_MS,
     }),
-    Object.freeze({
+    promptSuggestions: Object.freeze({
         id: "promptSuggestions",
         label: "Prompt suggestions",
         section: Object.freeze({ id: "agent", title: "Agent" }),
@@ -89,7 +93,12 @@ export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
         defaultValue: true,
         allowedValues: Object.freeze([true, false]),
     }),
-]);
+});
+/** The declarations in declaration order, for resolution, persistence, and the settings screen. */
+export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze(Object.values(OWNED_SETTING_DECLARATIONS));
+export function isOwnedSettingId(id) {
+    return Object.hasOwn(OWNED_SETTING_DECLARATIONS, id);
+}
 export function assertOwnedUiSettingDeclarations(declarations) {
     const seen = new Set();
     for (const declaration of declarations) {

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

@@ -1,6 +1,10 @@
-export * from "./declarations.js";
-export * from "./migrations.js";
-export * from "./resolution.js";
-export * from "./sections.js";
-export * from "./session.js";
-export * from "./store.js";
+export { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, QUIT_EFFECT_DURATIONS_MS, assertOwnedUiSettingDeclarations, findOwnedUiSettingDeclaration, isOwnedSettingId, } from "./declarations.js";
+export type { OwnedSettingId, OwnedSettingValueOf, OwnedUiSettingApplication, OwnedUiSettingDeclaration, OwnedUiSettingValue } from "./declarations.js";
+export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom } from "./migrations.js";
+export type { OwnedUiSettingsMigration } from "./migrations.js";
+export { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, settingValue } from "./resolution.js";
+export type { OwnedUiResolvedSetting, OwnedUiSettingSource, OwnedUiSettingsDocument, OwnedUiSettingsNotice, OwnedUiSettingsNoticeCode, OwnedUiSettingsResolution, ResolveOwnedUiSettingsInput, } from "./resolution.js";
+export { AGENT_SECTION_ID, buildOwnedUiSettingsSections, findOwnedUiSettingsEntry } from "./sections.js";
+export type { AgentSettingsSnapshot, BuildOwnedUiSettingsSectionsInput, OwnedUiSettingsBackend, OwnedUiSettingsEntry, OwnedUiSettingsSection, } from "./sections.js";
+export { OwnedSettingsManager } from "./manager.js";
+export type { OwnedSettingsManagerOptions, OwnedUiSettingsChangeOutcome, OwnedUiSettingsListener } from "./manager.js";

package/dist/ui/settings/index.js

@@ -1,6 +1,5 @@
-export * from "./declarations.js";
-export * from "./migrations.js";
-export * from "./resolution.js";
-export * from "./sections.js";
-export * from "./session.js";
-export * from "./store.js";
+export { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, QUIT_EFFECT_DURATIONS_MS, assertOwnedUiSettingDeclarations, findOwnedUiSettingDeclaration, isOwnedSettingId, } from "./declarations.js";
+export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom } from "./migrations.js";
+export { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, settingValue } from "./resolution.js";
+export { AGENT_SECTION_ID, buildOwnedUiSettingsSections, findOwnedUiSettingsEntry } from "./sections.js";
+export { OwnedSettingsManager } from "./manager.js";

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

@@ -0,0 +1,54 @@
+import type { AgentJsonValue, AgentSettingApplicationBoundary, AgentSettingsPort } from "../../contracts/agent-engine/index.js";
+import { type OwnedSettingId, type OwnedSettingValueOf, type OwnedUiSettingDeclaration, type OwnedUiSettingValue } from "./declarations.js";
+import { type OwnedUiSettingsMigration } from "./migrations.js";
+import { type OwnedUiSettingsResolution } from "./resolution.js";
+import { type OwnedUiSettingsBackend, type OwnedUiSettingsSection } from "./sections.js";
+export interface OwnedSettingsManagerOptions {
+    /** A1 configuration root. Settings live under `<configDir>/settings/`. */
+    readonly configDir: string;
+    readonly profileId: string;
+    readonly declarations?: readonly OwnedUiSettingDeclaration[];
+    readonly migrations?: readonly OwnedUiSettingsMigration[];
+    readonly agent?: AgentSettingsPort | null;
+    readonly agentProvider?: () => AgentSettingsPort | null;
+    readonly hiddenAgentSettingIds?: readonly string[];
+}
+export interface OwnedUiSettingsChangeOutcome {
+    readonly status: "applied" | "deferred" | "unavailable" | "failed";
+    readonly applied: boolean;
+    /** Compatibility projection for existing A1 restart-bound declarations. */
+    readonly pendingRestart: boolean;
+    readonly application: AgentSettingApplicationBoundary | null;
+    readonly storedValue: AgentJsonValue | null;
+    readonly effectiveValue: AgentJsonValue | null;
+    readonly limitationReason: string | null;
+    readonly failure: string | null;
+}
+export type OwnedUiSettingsListener = (manager: OwnedSettingsManager) => void;
+/**
+ * One profile's A1 settings: resolves the declaration table against the stored document,
+ * persists each accepted change atomically without discarding unknown keys, offers the
+ * grouped sections a surface presents, and routes every accepted change only to its
+ * owning backend, with agent settings reached through the engine settings port.
+ */
+export declare class OwnedSettingsManager {
+    #private;
+    constructor(options: OwnedSettingsManagerOptions);
+    get file(): string;
+    get resolution(): OwnedUiSettingsResolution;
+    /** Reads and resolves the stored document. Never throws: every failure becomes a notice. */
+    read(): OwnedUiSettingsResolution;
+    load(): Promise<void>;
+    sections(): readonly OwnedUiSettingsSection[];
+    /**
+     * The value in effect for a declared setting, typed by its declaration. A restart-bound
+     * setting reads as the value the session started with until the next start.
+     */
+    value<Id extends OwnedSettingId>(id: Id): OwnedSettingValueOf<Id>;
+    /** The value in effect for any setting id, or null when nothing declares it. */
+    valueOf(id: string): OwnedUiSettingValue | null;
+    pendingValue(id: string): OwnedUiSettingValue | null;
+    onChange(listener: OwnedUiSettingsListener): () => void;
+    changeStructured(backend: OwnedUiSettingsBackend, id: string, value: Readonly<Record<string, unknown>>): Promise<OwnedUiSettingsChangeOutcome>;
+    change(backend: OwnedUiSettingsBackend, id: string, value: OwnedUiSettingValue): Promise<OwnedUiSettingsChangeOutcome>;
+}

package/dist/ui/settings/{session.js → manager.js}

@@ -1,8 +1,22 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
 import { assertAgentSettingDescriptor } from "../../contracts/agent-engine/index.js";
+import { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, } from "./declarations.js";
+import { OWNED_UI_SETTINGS_MIGRATIONS } from "./migrations.js";
+import { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, } from "./resolution.js";
 import { buildOwnedUiSettingsSections, findOwnedUiSettingsEntry, } from "./sections.js";
-/** Routes every accepted setting change only to its owning backend. */
-export class OwnedUiSettingsSession {
-    #store;
+const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const MAX_DOCUMENT_BYTES = 256 * 1024;
+/**
+ * One profile's A1 settings: resolves the declaration table against the stored document,
+ * persists each accepted change atomically without discarding unknown keys, offers the
+ * grouped sections a surface presents, and routes every accepted change only to its
+ * owning backend, with agent settings reached through the engine settings port.
+ */
+export class OwnedSettingsManager {
+    #file;
+    #declarations;
+    #migrations;
     #agent;
     #agentProvider;
     #listeners = new Set();
@@ -12,21 +26,56 @@ export class OwnedUiSettingsSession {
     #pending = new Map();
     #restartEffective = new Map();
     constructor(options) {
-        this.#store = options.store;
+        if (!PROFILE_ID_PATTERN.test(options.profileId)) {
+            throw new Error(`owned UI settings profile id is not a bounded slug: ${options.profileId}`);
+        }
+        this.#file = path.join(path.resolve(options.configDir), "settings", `${options.profileId}.json`);
+        this.#declarations = options.declarations ?? OWNED_UI_SETTING_DECLARATIONS;
+        this.#migrations = options.migrations ?? OWNED_UI_SETTINGS_MIGRATIONS;
         this.#agent = options.agent ?? null;
         this.#agentProvider = options.agentProvider ?? null;
         this.#hiddenAgentSettingIds = new Set(options.hiddenAgentSettingIds ?? []);
-        this.#resolution = options.store.read();
+        this.#resolution = this.read();
         for (const setting of this.#resolution.settings) {
             if (setting.declaration.application === "restart")
                 this.#restartEffective.set(setting.declaration.id, setting.value);
         }
     }
+    get file() {
+        return this.#file;
+    }
     get resolution() {
         return this.#resolution;
     }
+    /** Reads and resolves the stored document. Never throws: every failure becomes a notice. */
+    read() {
+        let raw = null;
+        let unreadable = null;
+        try {
+            raw = readFileSync(this.#file, "utf8");
+        }
+        catch (error) {
+            if (!isMissing(error))
+                unreadable = `${this.#file} could not be read: ${describe(error)}`;
+        }
+        if (raw !== null && Buffer.byteLength(raw, "utf8") > MAX_DOCUMENT_BYTES) {
+            unreadable = `${this.#file} exceeds the ${MAX_DOCUMENT_BYTES}-byte settings limit and was ignored`;
+            raw = null;
+        }
+        const document = raw === null ? null : parseOwnedUiSettingsDocument(raw);
+        if (raw !== null && document === null && unreadable === null) {
+            unreadable = `${this.#file} is not a valid settings document and was ignored`;
+        }
+        return resolveOwnedUiSettings({
+            declarations: this.#declarations,
+            migrations: this.#migrations,
+            document,
+            ...(unreadable === null ? {} : { unreadableDetail: unreadable }),
+            currentVersion: OWNED_UI_SETTINGS_VERSION,
+        });
+    }
     async load() {
-        this.#resolution = this.#store.read();
+        this.#resolution = this.read();
         const agent = this.#currentAgent();
         this.#agentSnapshot = agent === null ? null : await snapshotOf(agent, this.#hiddenAgentSettingIds);
         this.#notify();
@@ -39,7 +88,15 @@ export class OwnedUiSettingsSession {
                 : entry),
         }));
     }
+    /**
+     * The value in effect for a declared setting, typed by its declaration. A restart-bound
+     * setting reads as the value the session started with until the next start.
+     */
     value(id) {
+        return (this.valueOf(id) ?? OWNED_SETTING_DECLARATIONS[id].defaultValue);
+    }
+    /** The value in effect for any setting id, or null when nothing declares it. */
+    valueOf(id) {
         return this.#restartEffective.get(id) ?? this.#resolution.settings.find(setting => setting.declaration.id === id)?.value ?? null;
     }
     pendingValue(id) {
@@ -63,11 +120,11 @@ export class OwnedUiSettingsSession {
         return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgentValue(id, value);
     }
     #changeOwned(id, value) {
-        const outcome = this.#store.write(this.#resolution, id, value);
+        const outcome = this.#write(this.#resolution, id, value);
         if (!outcome.stored)
             return failed(outcome.failure ?? `${id} could not be stored`);
         const previous = this.#resolution;
-        this.#resolution = this.#store.read();
+        this.#resolution = this.read();
         const previousSetting = previous.settings.find(setting => setting.declaration.id === id);
         if (previousSetting?.declaration.application === "restart") {
             this.#pending.set(id, value);
@@ -78,6 +135,38 @@ export class OwnedUiSettingsSession {
         this.#notify();
         return changed("applied", "live", value, value);
     }
+    // Invariant: the resolved form is written with `id` set to `value` and undeclared keys preserved.
+    // Concurrency: a temporary sibling is renamed over the target, so an interrupted write leaves
+    // either the complete previous document or the complete new one.
+    #write(resolution, id, value) {
+        const declaration = this.#declarations.find(candidate => candidate.id === id);
+        if (!declaration)
+            return { stored: false, failure: `unknown owned UI setting: ${id}` };
+        if (!declaration.allowedValues.includes(value)) {
+            return { stored: false, failure: `value ${JSON.stringify(value)} is not allowed for ${id}` };
+        }
+        const current = documentFrom(resolution);
+        const next = {
+            version: OWNED_UI_SETTINGS_VERSION,
+            values: { ...current.values, [id]: value },
+        };
+        const temporary = `${this.#file}.${process.pid}.tmp`;
+        try {
+            mkdirSync(path.dirname(this.#file), { recursive: true, mode: 0o700 });
+            writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+            renameSync(temporary, this.#file);
+            return { stored: true, failure: null };
+        }
+        catch (error) {
+            try {
+                rmSync(temporary, { force: true });
+            }
+            catch {
+                // 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)}` };
+        }
+    }
     async #changeAgentValue(id, value) {
         const agent = this.#currentAgent();
         if (agent === null)
@@ -87,7 +176,7 @@ export class OwnedUiSettingsSession {
         }
         let result;
         try {
-            // Invariant: the coordinator behind the port owns effect installation, persistence,
+            // Invariant: the bridge behind the port owns effect installation, persistence,
             // flush, and rollback. A second surface-level flush would split authority.
             result = await agent.writeSetting(id, value);
         }
@@ -159,6 +248,9 @@ function fromAgentOutcome(result) {
         failure: result.failure,
     };
 }
+function isMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
 function describe(error) {
     return error instanceof Error ? error.message : String(error);
 }