Library features (#1109)
A per-library switchboard for the macro features, gated on every surface. Written before the code (2026-10-19), as the plan the work follows; the screens and the decisions taken with them are in docs/design/features, and the groups — what each owns, what off means, what it needs — are tabled there.
The constraint that shapes all of it: off is inert. A switch hides a feature everywhere and stops its background work; it never deletes, moves or rewrites a note, a state file or a setting. Turning it back on is the whole undo.
The model (phase 1)
LibraryFeature, an enum in its own file (lib/src/core/settings/library_features.dart): each value carries a stable id (search,quickNote,templates,capture,todo,journal,calendar,kinds.list,kinds.shopping,kinds.audio,transcription,kinds.slides,kinds.flashcards,readers,annotations,ocr,home,widgets), its parent (kinds.shopping→kinds.list,transcription→kinds.audio,annotations→readers) and its string keys. It is the only place a feature is named.Features, an immutable value over the rawMap<String, bool>:- an id missing from the map reads as on, so a feature a later build adds is born on;
- an id this build does not know is kept and written back, the rule
NavigationLayoutalready follows; own(f)is the row’s own switch,isOn(f)the effective value — its own and its parent’s — which is what every surface asks;- the four presets are constant maps, and
presetOf(features)answers the one the switches match, or none (Custom).
- Storage.
LibraryConfigreads and writes two keys and holds no logic of its own (it is past 1 400 lines):features: only the switches that differ from on, so a library that never touches the screen keeps asettings.jsonbyte for byte as today;featuresReviewed: the introduction’s flag, false when absent. Both live in.niman/settings.json, travel and sync with it, and go through the settings merge as every other key does.
- The session exposes the library’s
Featuresas a listenable; every surface rebuilds from it, none keeps a boolean of its own.
Tests: the presets and presetOf, dependencies (a child keeps its own
value under an off parent), unknown ids preserved, absent keys reading as
defaults, the round trip through settings.json, and a library with no
features key writing none.
The seam (phase 2)
A feature gate in each catalogue, written as an exhaustive switch
that answers the LibraryFeature an entry belongs to, or null for core:
featureOf(AppCommand), besidecommandNeeds(lib/src/ui/palette/command_needs.dart);featureOfTab(ShellTab),featureOfArea(SettingsAreaId), the Home tile kinds’, andfeatureOfKind(type)for the note kinds.
An exhaustive switch does not compile while a case is missing, so a new command, destination, tile or area cannot ship unclassified — stronger than the test the issue asked for, which remains only for the dependencies.
Every surface that offers a command asks one question,
available = needs met && feature on: the palette, the keys, the row and
context menus, the toolbar, the phone Insert sheet, the dock. A command
whose feature is off is not offered and does not fire from its key. The
Commands page lists it greyed, with Off in Features. The palette, when
a query matched only such commands, adds the quiet line under its key
hints (Desktop-5).
Destinations are two layers: shown when the feature is on and Navigation
does not hide them. Nothing is written to navigation; Navigation’s row
keeps its place, greyed, with the link to Features (Desktop-4). Opens on
follows the shown destinations as it already does for a hidden one.
The screen and the introduction (phase 3)
- Settings → Library → Features, the group’s first row: the presets strip pinned on top, the cards, the dependency rule, the snackbar after a switch that cancelled reminders (with Undo), and Show this introduction again at the foot.
- The areas follow the switches: the area list and the settings
search drop what belongs to a feature that is off
(
featureOfArea). - The introduction.
- A library whose
settings.jsonhas nofeaturesReviewed, opened by a normal open (the picker, the switcher, the last library at launch), opens Settings → Features once — the floating window on a desktop, the screen on a phone — with the card of Desktop-2. - A share, a widget tap, a notification, a reminder and a deep link open their target and leave the flag as it was.
- A folder with no
.niman/settings.jsonis a library being created: the card is What is this library for? with the presets as large cards (Desktop-3), Everything preselected. - The flag is written when the screen is left (Done, back,
Esc), never when it opens.
- A library whose
- Strings: every label, line, preset, card and snackbar in all 37 languages, in this phase.
The surfaces (phase 4)
- Home: a tile or an action whose feature is off is not built; Home
itself follows
home. - Note kinds:
NoteKinds.forType(type, features)answers null for a kind that is off, so the note opens in the plain editor; the tree’s kind icon follows the same answer. The note’s bytes are not touched. - Readers: a PDF or an EPUB with
readersoff opens in the system app, through the path an unsupported attachment already takes. - Intents: shared text with Quick note off goes to Import; a deep link or a notification for a feature that is off opens one sentence, not a broken screen.
The background (phase 5)
- Reminders: turning
todo(orcalendar) off cancels the alarms already scheduled for it and answers how many, for the snackbar; turning it on schedules them again from the file. Nothing is scheduled while it is off. - Downloads: no Tesseract or whisper model is fetched while
ocrortranscriptionis off. - Widgets: a widget whose feature (or
widgets) is off is sent the off payload — the sentence and Open Features — and nothing else is written for it (Phone-4). - The index: the FTS index keeps being written whatever
searchsays — links, properties and the tree read it, and turning search back on is instant. Measure before ever revisiting this. - Sync is untouched: it is not a feature (see the design’s decisions).
Docs (phase 6)
docs/user/features.md (the groups, what each owns, what off means),
Settings → Features in docs/user/settings.md, and
docs/user/platforms.md. The changelog when it ships.
How it lands
AGENTS.md: work in several steps stays on one branch, each step committed
and pushed there, and goes into main with one pull request. The
branch is feat/library-features-1109; the phases above are its commits,
in order. Every phase leaves every feature on by default, so the branch is
releasable at each step. The owner chose all the groups at once: the
screen is not released until every group is gated on every surface.
Tests, beyond each phase’s own
- For each feature, off: a built shell offers none of its commands — palette, keys, row and context menus, Insert sheet, dock, Home, settings search, navigation — and on again brings them back.
- A note of a kind that is off opens as Markdown, its bytes unchanged; on again restores the kind’s view.
- A toggle leaves every file under
.niman/byte for byte as it was, andsettings.jsonkeeps the ids it does not know. - The introduction: shown once per library on a normal open; not on a
share, a widget, a notification or a deep link, which leave the flag
false; a kill while it is open leaves it false; Done sets it; it round
trips and merges in
settings.json; Show this introduction again shows the card and changes nothing. - An integration smoke run on Linux of Notes only: open, edit, search, export; no todo, journal or kind UI; no reminder scheduled. One manual pass on Android.