Plugin settings

A plugin declares its settings; the shell builds the form in the settings dialog (gear icon in the top bar, or Ctrl+, / ⌘,).

const settings = ctx.defineSettings<{ limit: number; theme: string }>({
  title: ctx.i18n.key("settings.title"), // optional, defaults to the plugin name
  order: 20,                              // position in the section list
  settings: [
    {
      key: "limit",
      type: "number",                     // string | number | boolean | enum | color
      label: ctx.i18n.key("settings.limit"),
      description: ctx.i18n.key("settings.limitHint"),
      default: 200,
      min: 20,
      max: 2000,
      step: 20,
    },
    {
      key: "theme",
      type: "enum",
      label: ctx.i18n.key("settings.theme"),
      default: "dark",
      options: [{ value: "dark", label: ctx.i18n.key("settings.theme.dark") }],
    },
  ],
  // component: MyPanel, // optional custom panel rendered above the generated form
  //                       (in ui.json: "settings": { "component": "name" } from ctx.ui.define({ components }))
});

settings.get().limit;   // outside React
settings.use().limit;   // inside a component, re-renders on change
settings.set({ limit: 500 });
settings.reset();

Rules:

Labels and descriptions are i18n keys, translated at render time.
Values live in their own persisted settings slice, keyed by plugin id, so they survive disabling or reinstalling the plugin.
The dialog never mutates state directly: it emits settings/value.set ({ pluginId, key, value }) and settings/section.reset ({ pluginId }); the kernel handlers write the store and emit settings/changed.
Reading a value always overlays the saved value on the declared default, so adding a new setting later needs no migration.
A number setting with optional: true may be left empty: it is stored and read as "" (declare default: "" for “no value” by default), and a saved number is still read as that number, so an empty field can mean “send nothing”.
The shell’s own General section (language) uses the same mechanism.