rework settings, add descriptions

Author: foxnne

docs/PLUGINS.md

@@ -47,7 +47,7 @@ the first time; use it as reference after that.
 | `Plugin` | A plugin's identity + **vtable** of optional hooks. The shell calls these; a plugin implements only what it needs. |
 | `DocHandle` | Opaque handle to an open document: `{ ptr, id, owner: *Plugin }`. The shell stores these per tab and **routes every document operation to `owner`** — it never inspects `ptr`. |
 | `regions` | The contribution structs a plugin registers: `SidebarView`, `BottomView`, `CenterProvider`, `MenuContribution`, `Command`, `LanguageSupport`, … There is no settings region here — see `sdk.settings` below. |
-| `sdk.settings` (`settings.zig`) | Comptime settings API: `sdk.settings.Schema(struct { … })` derives a persisted-values type + a `SettingsSchema` you register with the Host. The shell's settings pane draws it for you — no hand-rolled dvui settings section. |
+| `sdk.settings` (`settings.zig`) | Comptime settings API: `sdk.settings.Schema(struct { … })` over `Value(T, .{ .description = … })` cells derives a persisted-values type + a `SettingsSchema` you register with the Host. The shell's settings pane draws it for you — no hand-rolled dvui settings section. |
 | `dylib` / `dvui_context` | The C-ABI entry contract + dvui-context injection used when a plugin is loaded as a runtime library. |
 
 **The shell owns no features.** Each frame it iterates the Host registries and draws whatever
@@ -327,15 +327,22 @@ fallback when a loaded plugin has no fetchable `ICON.png` (e.g. a sideloaded dyl
 
 There is no `registerSettingsSection` and no author-written settings schema in
 `plugin.zig.zon`. Persisted settings are declared as a plain Zig struct (build-options-style,
-comptime-derived), then registered from `register(host)`:
+comptime-derived) whose every field is a self-describing `sdk.settings.Value` cell, then
+registered from `register(host)`:
 
 ```zig
 const MySettings = sdk.settings.Schema(struct {
-    insert_spaces_on_tab: bool = true,
-    tab_size: enum(u8) { two = 2, four = 4, eight = 8 } = .four,
-    format_on_save: bool = false,
+    insert_spaces_on_tab: sdk.settings.Value(bool, .{
+        .description = "Insert spaces instead of a tab character when pressing Tab.",
+    }) = .init(true),
+    tab_size: sdk.settings.Value(enum(u8) { two = 2, four = 4, eight = 8 }, .{
+        .description = "How many columns a tab occupies.",
+    }) = .init(.four),
+    format_on_save: sdk.settings.Value(bool, .{
+        .description = "Reformat the document each time it is saved.",
+    }) = .init(false),
 });
-var settings: MySettings.Value = .{};
+var settings: MySettings.Cells = .{};
 
 pub fn register(host: *sdk.Host) !void {
     plugin.state = @ptrCast(&plugin_state);
@@ -347,18 +354,41 @@ pub fn register(host: *sdk.Host) !void {
         .value = &settings,                                // shell draws shared controls
     });
 }
+
+// Read a value with `.get()`, write one with `.set()`:
+if (settings.format_on_save.get()) formatDocument(doc);
 ```
 
-`Schema(T)` comptime-walks `T`'s fields (`bool`/`int`/`float`/`enum`/`[]const u8`) into a
-`Setting` table — each entry's `kind: Kind` is a `union(TypeTag)` carrying only the metadata that
+**Every setting describes itself.** A cell's second (comptime) parameter is
+`settings.Options{ description, name, min, max, step }`, and `description` has no default — a
+setting declared without one is a compile error. The pane has a permanent place for it (see the
+row shape below), so there is no shell-side table of strings that can drift from the plugin that
+owns the setting. Metadata lives entirely in the *type*: `@sizeOf(Value(T, …)) == @sizeOf(T)`,
+and only the payload is ever stored or persisted.
+
+The shell draws each setting as one group, VSCode-style: the name (derived from the field name —
+`insert_spaces_on_tab` → `Insert spaces on tab`, or `Options.name` to override), the zon key
+underneath in smaller dim mono, the wrapped description, and then the control at full width.
+Booleans are the exception — their checkbox sits before the description on one line. Both the
+name and the key are matched by the settings search, so users can find a row by either.
+
+`Schema(T)` comptime-walks `T`'s cells into a `Setting` table (`key`, `label`, `description`,
+`kind`) — each entry's `kind: Kind` is a `union(TypeTag)` carrying only the metadata that payload
 type actually uses (`IntKind{min,max,choices}`, `FloatKind{min,max,step}`, `EnumKind{choices}`,
-void for bool/string/color), rather than one flat struct with every type's bounds fields present
-on every entry — and generates `Value` (= `T`), `load`/`store` (a zon round-trip through
+void for bool/string/color/other), rather than one flat struct with every type's bounds fields
+present on every entry — and generates `Cells` (= `T`), `Payloads` (the bare-value mirror that is
+what actually round-trips through zon), `load`/`store` (through
 `Host.loadPluginSettings`/`storePluginSettings`), `applyZon` (parse a blob directly into the live
 value — the primitive `Access.applyBlob` wraps with a `settingsChanged` notification, used by
 external-change reconciliation, see below), and `register` (wires a `SettingsSchema` + typed
 `Access` vtable into the Host).
 
+**Any type is a legal setting.** `bool`/int/float/`enum`/`[]const u8` get dedicated controls;
+anything else `std.zon` can round-trip (a struct, an array, an optional) is `TypeTag.other` and
+the pane draws it as its zon text in an editable entry — text that doesn't parse simply doesn't
+commit. The on-disk shape is always the bare payload (`.tab_size = 8`), never the cell, so
+`settings.zon` files written before cells existed keep loading unchanged.
+
 Every plugin's block lives as a real, hand-editable nested ZON struct literal keyed by plugin
 id inside the shell's own `{config}/settings.zon`:
 
@@ -382,7 +412,7 @@ scalars/enums. Don't free a string field yourself, and don't assign one directly
 persisted — go through the settings pane or `applyZon`, or you'll leak the schema's copy.
 
 Author fields live under `.settings` so they can never collide with the shell-reserved
-`.enabled`. Only fields that differ from `T`'s own declared defaults are written; an all-default
+`.enabled`. Only fields whose payload differs from the cell's declared default is written; an all-default
 value removes that plugin's `.settings` (and if also disabled, the whole `.plugins.<id>` entry).
 `src/editor/SettingsPluginsZon.zig` locates/composes fields by source byte-span via the same
 `std.zig.Ast`/`ZonGen` machinery `std.zon.parse` uses, so nothing else in the file is

docs/PLUGIN_MANIFEST_PLAN.md

@@ -36,6 +36,7 @@
 | R13 — Shell fields persist non-default-only too | done | 2026-07-26 — R12's non-default-only rule applied to the *other* half of `settings.zon`: `Settings.serialize` now diffs every shell field against `const default_value: Settings = .{}` and emits only what differs (an untouched shell serializes to `.{}`, which `composeMergedText` already splices `.plugins` onto — covered by a new unit test). A field hand-written back at its default drops out on the next write, matching plugin blocks. One ownership consequence: with fields now routinely absent from disk, `std.zon.parse` fills them from the struct's declared defaults — and `theme`'s default is a comptime string literal, so the old `std.zon.parse.free(gpa, parsed)` calls would have handed a non-allocated pointer to the allocator. New `Settings.freeParsed` zeroes that field before the whole-struct free (`Allocator.free` early-returns on an empty slice) and is used at all three parse sites; `Settings`' process-lifetime `loaded` snapshot is gone with it, since `load` can now free its parse immediately after duping `theme`. No SDK/fingerprint change (shell-only). Verified: `zig build`/`test`/`check-web`, plus a live macOS run in an isolated `HOME`/`TMPDIR` sandbox — an all-defaults-spelled-out file migrated down to just `.content_opacity`, a hand-edited `.font_body_size` at its default was dropped on the reconcile-triggered rewrite while a non-default `.theme` survived, and a clean quit showed no invalid free. |
 | R14 — String settings ownership rule | done | 2026-07-26 — the plugin-side half of the same hazard R13 fixed for the shell, found while doing R13 and fixed before a plugin could hit it. `Schema(T).applyZon` used to `std.zon.parse.free` the whole previous value, so **any plugin with a `[]const u8` setting whose default is non-empty would have invalid-freed a string literal on its very first `load()`** — and again on every reconcile, since R12 omits default fields from disk and `std.zon.parse` fills those from the same literals. Now one explicit rule, stated once and used everywhere: *a string field's bytes are schema-owned (host allocator) unless the slice is exactly `T`'s declared default*, tested by pointer identity (`freeOwned`/`fieldIsOwned`). Persistence comparisons stay content-based, so an allocated copy equal to the default still prunes out of settings.zon. Consequences: new `Schema(T).deinit(value)` for plugins to call on teardown (no-op for scalar-only structs, documented in `docs/PLUGINS.md` §3.1.1); `Access.setString` implemented at last (dupe + release the old value under the same rule), which retires the "read-only until setString owns allocation policy" TODO in `PluginSettingsPane` — string settings now draw an editable text entry (commit on Enter; re-seeds from the live value while unfocused, so an abandoned edit reverts and an externally reconciled change shows up without a pane-side notification). No SDK boundary change — `Access` already had the member, fingerprint/`test-sdk-version` unchanged. Verified: `zig build`/`test-all`/`check-web`/`test-sdk-version`; new `Schema` unit tests under `test-integration` (`testing.allocator` catches both the invalid free and a leak) — note these live in the *integration* layer, `zig build test` alone does not run them; plus a live macOS sandbox run with a temporary string setting added to `text`: loaded from disk at register, hand-edited twice (allocated → allocated → back to the default), no crash, block correctly pruned when the value returned to its default. |
 | R13 follow-up — shutdown-write use-after-free | done | 2026-07-26 — R13's first real run panicked (`incorrect alignment` in `std.hash_map`) at quit. Pre-existing latent bug in `Editor.deinit`, surfaced by R13: `deinit` stops the watchers first (correct), but `stop()` *is* the watcher's teardown — `std.HashMapUnmanaged.deinit` leaves the maps `undefined` — and `deinit` then goes on to call `saveSettingsRaw` → `writeMergedSettings` → `notifyPathChanged` → `by_path.get` on that dead map. It only bites when the shutdown write actually happens (`writeMergedSettings` returns early on an unchanged hash), which is why it survived until R13 made "the composed text differs from what's on disk" the common case. Fix: `Editor.deinit` clears `document_watcher`/`settings_watcher` after stopping them (clearing is part of stopping, not tidiness — it also prevents `SettingsWatcher.stop`'s `config_folder` double-free), plus `DocumentWatcher.stop` now resets its maps to `.empty` instead of leaving them undefined, making a late query an empty-map miss rather than garbage. A/B verified in the macOS sandbox: same seeded config + edit-then-quit-inside-the-debounce sequence panics with the fix stashed and quits cleanly with it applied, writing the normalized file either way. |
+| R15 — Self-describing setting cells + VSCode-shaped rows | done | 2026-07-28 — a settings struct field is no longer a bare `bool`/`u8`/enum but a `sdk.settings.Value(T, .{ .description = … }) = .init(default)` **cell**: payload type, default, and a **required** description, all comptime (metadata lives in the type, so `@sizeOf(Value(T, …)) == @sizeOf(T)` and only the payload is ever stored). Omitting the description is a compile error at the declaration site — the point being that the pane now has a permanent place for it, and no shell-side table of strings can drift from the plugin that owns the setting. `Setting` gained `description` and a real `label` (derived from the field name in sentence case, `insert_spaces_on_tab` → `Insert spaces on tab`, overridable via `Options.name`); `key` stays the field/zon name. **On-disk format is unchanged**: everything persistence touches goes through a new comptime `Plain(T)` mirror (built with 0.16's `@Struct`) that has the same field names but bare payload types and the cells' defaults, so `applyZon`/`diffSerialize`/`fullSerialize` still read and write `.{ .tab_size = 8 }` exactly as before — no migration, and R11 reconciliation / R12 diff-only persistence needed no changes. **Any type is now a legal setting**: `kindFor` no longer `@compileError`s on an unsupported type, it returns the new `TypeTag.other`, and `Access` gained `getZonText`/`setZonText` so the pane can draw such a value as editable zon text (a parse failure simply doesn't commit — the entry re-seeds from the live value). **UI** (`src/editor/SettingRow.zig`, new): one row drawer shared by shell and plugin settings so they cannot drift — bold name, dim mono key underneath, wrapped description, then the full-width control (VSCode's order), with booleans the one exception (plain `dvui.checkbox` *before* the description on one line, since a full-width control for two states is all frame and no information). The short-lived full-width toggle button in `core.dvui` was deleted — this replaced it. Search (`SettingsTree.scoreLeaf`) now scores the zon key alongside the label/path/keywords, and both name and key are highlight-rendered, so a row that survived on a key match can show why. Fizzy's own settings (`explorer/settings.zig`) grew required `key`/`description` fields (plus `inline_control`) and all 11 items were filled in, keeping shell and plugin rows identical. sdk **0.1.46** (fingerprint `0xf5802c523f9bbc82` — `Setting` gained a field, `Kind`/`TypeTag` gained `other`, `Access` gained two members). Verified: `zig build`, `zig build test`, `zig build test-sdk-version`, `zig build test-integration` (23 SDK tests, incl. new cases for label derivation, `Options` bound refinement, the `.other` zon round-trip, and a diff-serialize assertion that the on-disk shape has no `.v` in it — confirmed actually executing via `-Dtest-filter`), and the text plugin's standalone `cd src/plugins/text && zig build`. |
 | Old Phase 2 (sidecar enforcement) | **cancelled** | superseded by this revision |
 
 ---

sdk/sdk_version.zig

@@ -5,5 +5,5 @@ const std = @import("std");
 pub const sdk_version = std.SemanticVersion{
     .major = 0,
     .minor = 1,
-    .patch = 45,
+    .patch = 46,
 };

src/core/dvui.zig

@@ -90,6 +90,45 @@ pub fn labelHighlighted(
     }
 }
 
+/// `labelHighlighted`'s body, for callers that already own a `TextLayoutWidget` — appends `text`
+/// to `tl` with the bytes `query` matched tinted, everything else in `plain_color`. Used for the
+/// settings tree's rows, where the caller controls wrapping and font.
+pub fn addHighlightedText(
+    tl: *dvui.TextLayoutWidget,
+    text: []const u8,
+    query: *const fuzzy.Query,
+    plain: bool,
+    plain_color: dvui.Color,
+) void {
+    if (query.isEmpty()) {
+        tl.addText(text, .{ .color_text = plain_color });
+        return;
+    }
+
+    var buf: [fuzzy.highlight_buf_len]usize = undefined;
+    const hits = fuzzy.highlight(text, query, &buf, .{ .plain = plain });
+    if (hits.len == 0) {
+        tl.addText(text, .{ .color_text = plain_color });
+        return;
+    }
+
+    const matched = dvui.themeGet().color(.highlight, .fill);
+    var i: usize = 0;
+    var h: usize = 0;
+    while (i < text.len) {
+        if (h < hits.len and hits[h] == i) {
+            // Consume the whole contiguous run of matched bytes in one addText.
+            const start = i;
+            while (h < hits.len and hits[h] == i) : (h += 1) i += 1;
+            tl.addText(text[start..i], .{ .color_text = matched });
+        } else {
+            const start = i;
+            i = if (h < hits.len) hits[h] else text.len;
+            tl.addText(text[start..i], .{ .color_text = plain_color });
+        }
+    }
+}
+
 /// Reserve one tree-row glyph slot: a box of exactly `treeRowGlyphSize()`, into which the caller
 /// draws a caret, an icon, an image, or a letter.
 ///
@@ -116,69 +155,6 @@ pub fn treeRowGlyph(src: std.builtin.SourceLocation, opts: dvui.Options) *dvui.B
     return dvui.box(src, .{ .dir = .horizontal }, defaults.override(opts));
 }
 
-/// A full-width boolean control shaped like the settings dropdowns and sliders rather than dvui's
-/// bare checkbox: one wide button whose whole surface toggles, with the state word ("Enabled" /
-/// "Disabled") and a purely decorative checkmark parked at the right edge (`gravity_x = 1.0`),
-/// exactly where a dropdown puts its current value and triangle.
-///
-/// The checkmark is drawn with `dvui.checkmark` into a spacer rect, so it picks up the same
-/// theme colours as a real checkbox but takes no events — the button is the only hit target.
-///
-/// Returns true (and flips `target`) on the frame it was clicked.
-pub fn toggle(src: std.builtin.SourceLocation, target: *bool, opts: dvui.Options) bool {
-    const defaults: dvui.Options = .{
-        .name = "Toggle",
-        .role = .check_box,
-        .margin = dvui.Rect.all(4),
-        .padding = dvui.Rect.all(6),
-        .corners = dvui.CornerRect.all(1000),
-        .background = true,
-        .style = .control,
-        .expand = .horizontal,
-    };
-    const options = defaults.override(opts);
-
-    var bw: dvui.ButtonWidget = undefined;
-    bw.init(src, .{}, options);
-    bw.processEvents();
-    bw.drawBackground();
-    bw.drawFocus();
-
-    {
-        var hbox = dvui.box(@src(), .{ .dir = .horizontal }, .{
-            .expand = .vertical,
-            .gravity_x = 1.0,
-            .background = false,
-        });
-        defer hbox.deinit();
-
-        dvui.label(@src(), "{s}", .{if (target.*) "Enabled" else "Disabled"}, .{
-            .gravity_y = 0.5,
-            .margin = .all(0),
-            .padding = .all(0),
-        });
-
-        const check_size = options.fontGet().textHeight();
-        const s = dvui.spacer(@src(), .{
-            .min_size_content = dvui.Size.all(check_size),
-            .max_size_content = .size(dvui.Size.all(check_size)),
-            .gravity_y = 0.5,
-            .margin = .{ .x = 6 },
-        });
-        if (bw.data().visible()) {
-            dvui.checkmark(target.*, false, s.borderRectScale(), bw.pressed(), bw.hovered(), .{
-                .corners = dvui.CornerRect.all(2),
-            });
-        }
-    }
-
-    const clicked = bw.clicked();
-    bw.deinit();
-
-    if (clicked) target.* = !target.*;
-    return clicked;
-}
-
 /// Currently this is specialized for the layers paned widget, just includes icon and dragging flag so we know when the pane is dragging
 pub fn paned(src: std.builtin.SourceLocation, init_opts: PanedWidget.InitOptions, opts: dvui.Options) *PanedWidget {
     var ret = dvui.widgetAlloc(PanedWidget);