avtc-pi-settings-ui 1.0.8 → 1.0.9

package/README.md

@@ -102,7 +102,7 @@ Every setting has a `type` resolved through a first-class `TypeDefinition` regis
 
 | Type | Stored value | Notes |
 |------|-------------|-------|
-| `string` | `string` | Text; closed enums via presets (`["a", "b"]`) |
+| `string` | `string` | Text; closed enums via presets (`["a", "b"]`), or free-form with `supportsCustomValues: true` |
 | `number` | `number` \| `null` | Optional `min`/`max` bounds; `null` (unbounded/off) via a null preset |
 | `duration` | `number` \| `null` | Human-readable (`5m`, `1h`, `30s`, `14d`); stored as milliseconds. `null` = unbounded/off, via a null preset |
 | `compact-threshold` | `string` | Compact-context thresholds (`none`, `compact`, `compact>75K`, …) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "avtc-pi-settings-ui",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "A schema-driven settings UI for pi extensions — define your settings, get a tabbed modal, a /<name>:settings command, and layered persistence.",
   "type": "module",
   "main": "./index.ts",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "avtc-pi-logger": "^1.0.3",
-    "minimatch": "^10.0.0"
+    "minimatch": "^10.2.6"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",

package/src/normalization.ts

@@ -94,16 +94,29 @@ export function resolveSettingValue(raw: Record<string, unknown>, setting: Setti
 
   const typeDef = getTypeDefinition(setting.type);
 
+  // 3b. Empty string on a string-typed setting WITHOUT a null pair → null (unset). The null
+  //     display for preset-less strings IS the empty string, so this is what makes that
+  //     display round-trip: re-applying it unsets rather than storing a literal "".
+  if (value === "" && typeDef.valueType === "string" && nullLabel === undefined) {
+    value = null;
+  }
+
   // 4. null validity — keep null iff a null-preset exists (nullLabel derived from the effective
-  //    presets). A type with no null-preset rejects null. Legitimate nulls never reach parse.
+  //    presets) OR the type is inherently nullable (a resolver-function presets source — e.g.
+  //    the model list — only yields its null pair at modal-open, so the write gate would
+  //    otherwise reject null and the setting could never be unset back to Default). A type
+  //    with no null-preset and no nullable trait rejects null. Legitimate nulls never reach parse.
   if (value === null) {
-    return nullLabel !== undefined ? null : INVALID;
+    return nullLabel !== undefined || typeDef.nullable === true ? null : INVALID;
   }
 
   // 5. parse-if-string. Parse is string-only by signature; raw numbers/booleans
-  //    never enter it.
+  //    never enter it. An open-value override (supportsCustomValues: true) parses with the
+  //    presets stripped — preset matching is a UI affordance there, not a validity gate.
   if (typeof value === "string") {
-    const p = typeDef.parse(value, buildTypeContext(setting));
+    const openCtx: TypeContext = { presets: [], min: setting.min, max: setting.max };
+    const ctx = setting.supportsCustomValues === true ? openCtx : buildTypeContext(setting);
+    const p = typeDef.parse(value, ctx);
     if (p === undefined) return INVALID;
     value = p;
   }
@@ -275,9 +288,11 @@ export function getEffectiveValue(raw: Record<string, unknown>, setting: Setting
 export function computeRawInternalValue(settings: Record<string, unknown>, setting: SettingSchema): string {
   const value = settings[setting.id];
   if (value === null || value === undefined) {
-    // Display fallback only — the null label for nullable settings, or "Infinite" defensively
-    // for non-nullable settings that shouldn't hold null anyway.
-    return resolveNullLabel(setting) ?? "Infinite";
+    // Null display: the null-preset label when the setting has one, else a per-type fallback —
+    // "Infinite" for numeric/timeout-like values (null = no limit), EMPTY for strings (null =
+    // unset; a bare "Infinite" label is a number-ism that reads as a bogus string value).
+    if (resolveNullLabel(setting) !== undefined) return resolveNullLabel(setting) as string;
+    return getTypeDefinition(setting.type).valueType === "string" ? "" : "Infinite";
   }
   return String(value);
 }

package/src/schema.ts

@@ -61,6 +61,12 @@ export interface SettingSchema<T = unknown> {
    * atomic pass.
    */
   presets?: PresetsSource;
+  /** Open-value override for this setting. `true` = the setting accepts arbitrary values:
+   * the value picker offers a free-form "Custom value…" row and the gate's parse treats the
+   * raw value as open (preset matching not enforced). `false`/absent = the type-def's
+   * `supportsCustomValues` governs (string enums stay closed). The type's base parse still
+   * applies — e.g. a `number` setting parses integers regardless of this flag. */
+  supportsCustomValues?: boolean;
   /** Backward-compat field names (old keys that map to this setting's canonical id). */
   aliases?: string[];
   /** Legacy value aliases: old value → current raw value. Resolved before value-based matching. */
@@ -112,6 +118,9 @@ export interface SettingItem {
   description?: string;
   /** Cohesive preset list (labels + raw values + display strings derived from `presets` pairs). */
   presets?: readonly PresetItem[];
+  /** Effective open-value flag: the setting's `supportsCustomValues` override, else the
+   * type-def's flag. Drives the picker's "Custom value…" row. */
+  supportsCustomValues: boolean;
 }
 
 // ── Storage levels (which persistence targets a settings handle offers) ─────────

package/src/type-definitions.ts

@@ -59,6 +59,14 @@ export interface TypeDefinition<T = unknown> {
    * from the registry). Absent means this type offers no default presets.
    */
   presets?: PresetsSource;
+  /**
+   * Inherently nullable: `null` is always a valid value for this type, even when the
+   * effective presets yield no null pair at gate time (a resolver-function presets
+   * source — e.g. the model list — resolves its `["Default", null]` pair only at
+   * modal-open, so the write gate would otherwise reject null and a model setting
+   * could never be unset back to Default).
+   */
+  nullable?: boolean;
 }
 
 // ── Registry ────────────────────────────────────────────────────────────────
@@ -250,7 +258,7 @@ const booleanType: TypeDefinition<boolean> = {
 // ── The thinking-level built-in ─────────────────────────────────────────────
 
 /**
- * The six thinking levels, as `[label, value]` preset pairs (label equals value). The default
+ * The seven thinking levels, as `[label, value]` preset pairs (label equals value). The default
  * `presets` for the `thinking-level` type — a consumer writes only `{ type: "thinking-level" }`
  * and gets these without declaring `presets` (overridable per-setting: replace, not merge).
  */
@@ -261,15 +269,18 @@ export const THINKING_LEVEL_PRESETS = [
   ["medium", "medium"],
   ["high", "high"],
   ["xhigh", "xhigh"],
+  ["max", "max"],
 ] as const satisfies readonly PresetPair[];
 
 const thinkingLevelType: TypeDefinition<string> = {
   id: "thinking-level",
   valueType: "string",
-  // Membership check against the EFFECTIVE presets (the type-def default, or a per-setting
-  // override). An unknown level returns undefined → the load gate rejects it and falls back to
-  // the setting's defaultValue.
-  parse: (input, ctx) => matchPresetValue(input, ctx),
+  // Closed enum when effective presets exist (the type-def default, or a per-setting
+  // override): an unknown level returns undefined → the load gate rejects it and falls
+  // back to the setting's defaultValue. Empty ctx degrades to identity — the preset
+  // normalizer parses bare preset strings with an empty preset ctx, and a consumer may
+  // declare the level vocabulary as plain strings (the string type's same contract).
+  parse: (input, ctx) => (ctx.presets.length > 0 ? matchPresetValue(input, ctx) : input),
   format: (value) => value,
   presets: THINKING_LEVEL_PRESETS,
   supportsCustomValues: false,
@@ -296,11 +307,13 @@ const modelType: TypeDefinition<string> = {
   id: "model",
   valueType: "string",
   // Identity parse — a provider/id (even a stale one) loads unchanged. Null is valid via the
-  // gate's null-preset path (the resolver's ['Default', null] pair), not via parse.
+  // gate's null path (the `nullable` trait — the resolver's ['Default', null] pair only
+  // resolves at modal-open, too late for the write gate), not via parse.
   parse: (input) => input,
   format: (value) => formatModelValue(value),
   presets: resolveModelPresets,
   supportsCustomValues: false,
+  nullable: true,
   errorMessage: "Select a model",
 };
 

package/src/ui/schema-tabs.ts

@@ -127,6 +127,8 @@ export function buildSchemaTabGroups(
         type: settingSchema.type,
         description: settingSchema.description,
         presets: presetItems,
+        supportsCustomValues:
+          settingSchema.supportsCustomValues ?? getTypeDefinition(settingSchema.type).supportsCustomValues,
       });
     }
 

package/src/ui/settings-modal.ts

@@ -195,11 +195,13 @@ export class SettingsTabsModal implements Component {
         const rawValue = item.value ?? "";
         const itemPresets = item.presets;
         const itemType = item.type;
+        const itemSupportsCustom = item.supportsCustomValues;
         tuiItem.submenu = (_currentValue, done) => {
           return new ValuePickerSubmenu(
             itemPresets,
             rawValue,
             itemType,
+            itemSupportsCustom,
             this.theme,
             (selectedValue) => {
               if (selectedValue !== undefined) {

package/src/ui/value-picker.ts

@@ -51,6 +51,11 @@ export class ValuePickerSubmenu implements Component {
    *  via the global getter — NOT a constructor param. The pi `Theme` constructor param is used
    *  only for `fg("muted", ...)` model-span muting. */
   private readonly listTheme = getSettingsListTheme();
+  /** Effective open-value flag for THIS setting (per-setting override > type-def flag). */
+  private readonly supportsCustom: boolean;
+  /** True when the picker opened straight into text-entry (preset-less open setting): Esc
+   *  closes the editor instead of falling back to a filter list that has nothing to show. */
+  private directEntry = false;
   /** True iff this picker is for a `model`-type setting (constructor-time fact — muting applies). */
   private readonly isModel: boolean;
 
@@ -67,6 +72,7 @@ export class ValuePickerSubmenu implements Component {
     presets: readonly PresetItem[],
     currentRawValue: string,
     private settingType: SettingType,
+    supportsCustomValues: boolean,
     private theme: Theme,
     private done: (value?: unknown) => void,
     maxVisible: number,
@@ -74,6 +80,7 @@ export class ValuePickerSubmenu implements Component {
     this.maxVisible = maxVisible;
     this.filterInput = new Input();
     this.typeDef = getTypeDefinition(settingType);
+    this.supportsCustom = supportsCustomValues;
     this.isModel = settingType === "model";
     // Build a TypeContext from presets (a custom parse/format derives the null label itself from
     // ctx.presets — the pair whose value is null).
@@ -82,7 +89,9 @@ export class ValuePickerSubmenu implements Component {
     // Build entries: label for display, raw value for done callback.
     // currentRawValue (serialized string) is matched against preset displayValue to find the active preset.
     const matchIndex = presets.findIndex((p) => p.displayValue === currentRawValue);
-    const hasCustomIndicator = matchIndex < 0;
+    // An empty current raw value is the NULL display of a preset-less string — there is no
+    // current value to indicate, so no indicator row (just presets + the custom entry).
+    const hasCustomIndicator = matchIndex < 0 && currentRawValue !== "";
 
     this.entries = [];
     if (hasCustomIndicator) {
@@ -95,10 +104,11 @@ export class ValuePickerSubmenu implements Component {
     for (const preset of presets) {
       this.entries.push({ label: preset.label, rawValue: preset.rawValue, kind: "preset" });
     }
-    // Pinned "Custom value…" row (open types only): free-form entry via Up/Down + Enter, which
-    // switches the top field into text-entry mode. Distinguished by kind (rawValue is null, which
-    // is a valid preset value).
-    if (this.typeDef.supportsCustomValues) {
+    // Pinned "Custom value…" row (open settings only): free-form entry via Up/Down + Enter,
+    // which switches the top field into text-entry mode. Distinguished by kind (rawValue is
+    // null, which is a valid preset value). The flag is the EFFECTIVE per-setting one — a
+    // `supportsCustomValues: true` override opens an otherwise-closed type (e.g. string).
+    if (this.supportsCustom) {
       this.entries.push({ label: "Custom value…", rawValue: null, kind: "custom" });
     }
 
@@ -113,6 +123,14 @@ export class ValuePickerSubmenu implements Component {
 
     // The top field is the filter; in text-entry mode it builds a custom value.
     this.filterInput.focused = true;
+
+    // A preset-less OPEN setting has nothing to pick — open directly in text-entry mode,
+    // prefilled with the current value (edit-in-place), instead of a list whose only row
+    // is "Custom value…". Esc then closes the editor (there is no list to fall back to).
+    this.directEntry = presets.length === 0 && supportsCustomValues;
+    if (this.directEntry) {
+      this.enterTextEntry(currentRawValue);
+    }
   }
 
   /** Format a serialized raw value for display via the TypeDefinition. */
@@ -302,6 +320,12 @@ export class ValuePickerSubmenu implements Component {
       return;
     }
     if (kb.matches(data, "tui.select.cancel")) {
+      // Direct-entry editors have no list to return to — Esc closes the picker (cancel edit).
+      if (this.directEntry) {
+        this.closed = true;
+        this.done();
+        return;
+      }
       this.leaveTextEntry();
       return;
     }
@@ -309,21 +333,23 @@ export class ValuePickerSubmenu implements Component {
     this.filterInput.handleInput(data);
   }
 
-  /** Enter on the focused entry: preset/indicator → done(rawValue); Custom row → text-entry mode. */
+  /** Enter on the focused entry: preset/indicator → done(rawValue); Custom row → text-entry
+   *  mode (empty editor — the direct-open path is what prefills the current value). */
   private activateEntry(): void {
     const entry = this.visibleEntries[this.selectedIndex];
     if (!entry) return;
     if (entry.kind === "custom") {
-      this.enterTextEntry();
+      this.enterTextEntry("");
       return;
     }
     this.closed = true;
     this.done(entry.rawValue);
   }
 
-  private enterTextEntry(): void {
+  private enterTextEntry(prefill: string): void {
     this.customEntryFilterSnapshot = this.filterInput.getValue();
-    this.filterInput.setValue("");
+    // Prefill the editor with the given value (edit-in-place; "" starts empty).
+    this.filterInput.setValue(prefill);
     this.mode = "text-entry";
     this.errorMessage = "";
   }
@@ -338,7 +364,11 @@ export class ValuePickerSubmenu implements Component {
 
   /** Validate the typed custom value; on success fire done(rawValue), on failure show the error. */
   private submitCustomValue(): void {
-    const result = validateCustomValue(this.filterInput.getValue(), this.settingType, this.ctx);
+    // An override-opened closed type (e.g. string) validates custom text against the OPEN
+    // parse — preset matching is a picker affordance there, not a validity gate. Types that
+    // are natively open keep their full ctx (their parse handles arbitrary input anyway).
+    const customCtx = this.typeDef.supportsCustomValues ? this.ctx : null;
+    const result = validateCustomValue(this.filterInput.getValue(), this.settingType, customCtx);
     if (result === undefined) {
       this.errorMessage = `  \u26a0 ${this.typeDef.errorMessage}`;
       return;