Brazen Framework - Configuration Manager

Configuration management for the Brazen user scripts framework

This script should not be not be installed directly. It is a library for other scripts to include with the meta directive // @require https://update.greasyfork.org/scripts/418665/1901979/Brazen%20Framework%20-%20Configuration%20Manager.js

Ask a question, post a review, or report the script.

Author: brazenvoid
Version: 7.1.0
Created: 2020-12-15
Updated: 2026-08-14
Size: 172 KB
License: GPL-3.0-only

Brazen Framework — Configuration Manager (developer guide)

Typed settings schema, pluggable storage drivers (localStorage + Tampermonkey GM), cross-tab sync, backup/restore, and DOM factories bound to View Layer widgets.

Greasy Fork: Configuration Manager · Requires: Utilities, View Layer · Used by: Framework core

When to use / when not to use

Use this module when your script needs user-configurable settings, persistence, backup/restore, and a consistent way to bind those settings to UI controls.
Don’t use ad-hoc GM_setValue blobs for settings in apps. Prefer defining fields here so the framework can apply/save/reset consistently and include values in backups.
Don’t make settings conditional on the current page at definition time. Define fields unconditionally (constructor), and gate behavior later in the framework lifecycle.

Quick start

Define fields in your app’s constructor, then mount them into the settings panel during UI composition.

// constructor (define schema)
this._configurationManager.registerFieldSeed('enable-feature', true)
this._configurationManager
  .addFlagField('enable-feature')
  .setTitle('Enable Feature')
  .setHelp('Turns the feature on/off.')

this._configurationManager.registerFieldSeed('tag-blacklist', {
  templateId: 'tag-blacklist',
  config: {autoSort: true, sortMode: 'natural-asc', groupingEnabled: false, hideTagTypes: false},
})
this._configurationManager
  .addRulesetField('tag-blacklist')
  .setTitle('Tag Blacklist')
  .setRows(15)
  .setHelp('One rule per line.')
  .setSortRules(true)
  .setGroupingAvailable(true)

// UI composition (mount controls)
this._userInterface = [
  this._uiGen.createTabsSection(['Filters'], [
    this._uiGen.createTabPanel('Filters', true).append([
      this._configurationManager.createElement('enable-feature'),
      this._configurationManager.createElement('tag-blacklist'),
    ]),
  ]),
]

Constructor

new BrazenConfigurationManager(scriptPrefix, uiGenerator, tagSelectorGenerator)

Parameter	Role
`scriptPrefix`	Prefix for storage keys (per driver)
`uiGenerator`	`BrazenViewLayer` instance
`tagSelectorGenerator`	`(tag: string) => string` — optional site hook (legacy selector highlights removed)

Framework exposes this as this._configurationManager. Register fields in the subclass constructor; call initialize() during init() before UI build.

Features

Field keys and titles (stable identity vs label)

Each field has:

A stable key (field.key) used for persistence, lookups, docking relationships, and backup/restore.
A display title (field.title) used only for UI labels.

The value you pass as the first argument to add*Field(key) is normalized via Utilities.toKebabCase(...) and stored as field.key.

To decouple label text from persistence, use kebab-case keys in code and set the UI label via setTitle(...):

const FILTER_TAG_BLACKLIST = 'tag-blacklist'

this._configurationManager.addRulesetField(FILTER_TAG_BLACKLIST).
  setTitle('Tag Blacklist').
  setRows(15).
  setHelp('One rule per line.')

Defining a schema: field types and registration

What it does: You define a stable settings schema by adding typed fields. Fields become the single source of truth for UI binding, persistence, validation gating, and backup/restore.

How it works (developer-relevant):

Each add*Field(...) returns the field object so you can chain configuration (setHelp, setRows, setGroupingAvailable, etc.).
Declare defaults with registerFieldSeed(key, value) or registerFieldSeeds({...}) before or after field registration; _seedAllFields() (fresh install) and schema migration handlers write them to IndexedDB once. Reads return stored values verbatim — no runtime default merge.
Fields default to local storage. Use field.attachStorage('gm') when a value should live in GM storage.
Some fields are self-managed (persist: false) and use driver primitives directly (bookmarks, ledger).

Constant	`add*` method	Stored `value` type	UI
`CONFIG_TYPE_FLAG`	`addFlagField(name)`	`boolean`	Checkbox
`CONFIG_TYPE_TEXT`	`addTextField(name)`	`string`	Text input; empty → seed default on read
`CONFIG_TYPE_NUMBER`	`addNumberField(name, min, max)`	`number`	Number input
`CONFIG_TYPE_COLOR`	`addColorField(name)`	color string	Color input
`CONFIG_TYPE_RANGE`	`addRangeField(name, min, max)`	`{ minimum, maximum }`	Two number inputs
`CONFIG_TYPE_SELECT`	`addSelectField(name, pairs)`	option value	See known limitation in spec
`CONFIG_TYPE_CHECKBOXES_GROUP`	`addCheckboxesGroup(name, pairs)`	`string[]` of checked `data-value`s	Checkbox group
`CONFIG_TYPE_RADIOS_GROUP`	`addRadiosGroup(name, pairs)`	selected `data-value`	Radio group
`CONFIG_TYPE_RULESET`	`addRulesetField(name)`	`string[]` lines / IDB rows	Ruleset panel (`createRulesetPanel`); use `.setTemplate('bookmarks')` for bookmarks
`CONFIG_TYPE_ACTION`	`addActionField(name)`	n/a (`persist: false`)	Form button or dock-only action
`CONFIG_TYPE_LEDGER`	`addLedgerField(name)`	self-managed id set (not in aggregate blob)	No UI — IndexedDB `ledgerEntries`

All add*Field methods return the field object. Chain setHelp, setRows, bookmark/ledger/dock setters (setDockButton, applyDockTemplate, setDockSlideOut), then field.attachStorage('local'|'gm') as needed (default driver: local). Manager methods (onExternalConfigurationChange, setDockActive, …) return the manager.

applyDockTemplate(name, args?) — named recipes (tagBlacklist, exploredTags, autoNextPage, defaultTags, resolutionFilter, hideOlderPosts, invertedFiltersMaster, skipDuplicates, hideDownloaded; plus escape-hatch flagToggle). Records field.dock.templateName.

this._configurationManager.registerFieldSeed('enable-feature', true)
this._configurationManager.addFlagField('Enable Feature').setHelp('…')
this._configurationManager.addRulesetField('Tag Blacklist').setRows(15).setHelp('…').setSortRules(true)

Filename substitutions can use a controlled composer (read-only list + Subject → Alias add row):

```javascript
this._configurationManager.addRulesetField('filename-tag-substitutions').
    setSubstitutionComposer({
      normalize: (tag) => normalizeTag(tag),
      subjectPlaceholder: 'Subject',
      aliasPlaceholder: 'Alias',
    })

setSubstitutionComposer implies setReadOnly(true). Adds call setTagSubstitution; Save does not re-import the textarea when IndexedDB is active.


---

### Rulesets: the Apply/Save pipeline and optimized output

**What it does:** Ruleset fields turn user-edited textarea lines into a cleaned list of rules, optionally sorted/deduplicated, and optionally optimized into a runtime-friendly structure.

**Apply/Save pipeline** (`setFromUserInterface`, used by Apply/Save):

On **Apply/Save** (`setFromUserInterface`):

1. Split textarea by `REGEX_LINE_BREAK`; trim empty lines.
2. Optional `sortRules: true` — locale-aware sort (string lines only).
3. `onTranslateFromUI(values)` — normalize (optional; may return a non-array map, e.g. text sanitization).
4. Deduplicate when the value is an array (case-sensitive; first occurrence kept). Non-arrays pass through. Refreshes the textarea when array duplicates are removed.
5. `onOptimize(values)` — store result in `field.optimized` (filters read this at runtime).

**Registry / ruleset fields:** panel widgets (`createRulesetPanel`) persist rows in `rulesetEntries`; sidebar toggles and template APIs write the same store. New rows dedupe natively in `RulesetEntryRepository.add` by trimmed `rawLine`. `ensureRulesetFieldsCompiled()` refreshes combo maps after boot or attribute toggles.

`addRulesetField(key).setTemplate('tag-blacklist' | 'explored-tags' | …)` registers a ruleset field with template-driven panel UI and compile hooks.

**Ruleset subject copy:**

Each ruleset field names what it stores with a singular subject noun. Default is `rule`; override via `setRulesetSubject('bookmark')` or a template `subject` on `RulesetTemplateRegistry`. Configuration Manager derives panel empty/search/sort strings, add-entry repeater, batch submit label, and detail pane titles from the subject (pluralized where needed).

| Setter | Role |
|--------|------|
| `setRulesetSubject(text)` | Singular noun for entries (default `rule`; bookmarks template uses `bookmark`) |
| `setSortHelpText(text)` | Optional toolbar ⇅ tooltip override (default `Sort {plural}`) |

**Derived examples** (subject `rule` / `bookmark`):

| String | rule | bookmark |
|--------|------|----------|
| Empty state | No rules yet. | No bookmarks yet. |
| Add entry (repeater / + tooltip) | Add Rule | Add Bookmark |
| Batch submit | Add Rules | Add Bookmarks |
| Create detail title | `{title} - Add Rules` | `{title} - Add Bookmarks` |
| Edit detail title | `{title} - Edit Rule` | `{title} - Edit Bookmark` |

**Detail pane CRUD:** Create opens the multi-form shell (scrollable bordered cards + batch submit). Edit opens a single bordered form + **Save**. Empty create entries are skipped on submit.

**Per-rule API (programmatic edits):**

Every ruleset field exposes methods for programmatic add/remove without going through the textarea. Callers get the field via `getField(name)` and invoke these directly; side effects (`save()`, compliance refresh, UI refresh elsewhere) remain the caller's responsibility.

| Method | Role |
|--------|------|
| `onMatchRule(storedRule, target)` | Optional matcher callback; default is strict equality (`storedRule === target`) |
| `setRules(lines)` | Canonical write: `onTranslateFromUI` → optional `sortRules` (arrays only) → `value` → `onOptimize` → `updateUserInterface` |
| `findRuleIndex(target)` | Index of first matching rule, or `-1` |
| `hasRule(target)` | Membership test via `onMatchRule` |
| `addRule(rule, target?)` | Upsert: remove matches for `target` (defaults to `rule`), append `rule`, then `setRules` |
| `removeRule(target)` | Drop all matches, then `setRules` |
| `toggleRule(rule, target?)` | Add or remove via `hasRule` |
| `clearRules()` | `setRules([])` |

`setRules` does not deduplicate (preserves programmatic edits). IDB-backed ruleset fields dedupe natively when rows are added (`RulesetEntryRepository.add` compares trimmed `rawLine`). Legacy array rulesets still dedupe via `_deduplicateRulesetRules` on Apply/Save.

**Tag rule syntax** (one rule per line):

- `&` — AND (all tags in segment must match)
- `|` — OR within a segment
- ` // ` — comment suffix (ignored after split)

Optimized output: array of arrays (each inner array = one conjunctive rule). Sorted shortest-first.

---

### Bookmarks: `addRulesetField('bookmarks').setTemplate('bookmarks')`

**What it does:** Bookmarks are a ruleset template backed by IndexedDB `rulesetEntries`, rendered via View Layer `createRulesetPanel`. Legacy GM/local `{prefix}bookmarks` import once during setup via `BrazenLegacyImporter` when `legacyScriptPrefix` is set; `migrateBookmarksToRuleset` copies legacy `bookmarks` store rows.

**Typical use cases:**
- “Pages I visit often” lists, with optional “current page bookmarked?” UI signals.

```javascript
this._configurationManager.registerFieldSeed('bookmarks', { autoSort: true, sortMode: 'date-desc', hideTagTypes: false })
this._configurationManager.addRulesetField('bookmarks').
  setTemplate('bookmarks').
  setTitle('Bookmarks').
  setHelp('Add pages you visit often.').
  setShowAddButton(true).
  setPageMatch({ getCurrentUrl, normalizeUrl, onMatchChange, watchSelectors, isActive }).
  setOnRemove((id) => { /* … */ }).
  setAttributeActionsConfig({ host, tokenize, normalize, blacklist, explore, … })

Framework-owned blacklist/explore remediation on bookmark rows is enabled via setAttributeActionsConfig({ host: frameworkInstance, tokenize, … }). CM composes those buttons (and tag-cache prefetch) before any consumer getRowActions / onBeforeRender.

Behaviour	Detail
`persist`	`false` — not in aggregate settings blob; IndexedDB `rulesetEntries` under the bookmarks `fieldKey`
Field API	`reload()`, add/edit/remove via ruleset panel or `rulesetEntries` repo
`widget`	Ruleset panel from `createRulesetPanel` (`bookmarks` template)
`setFromUserInterface`	No-op — panel CRUD writes IDB directly
`updateUserInterface`	Re-renders `_rulesetRows` + `checkPageMatch`
`reload()`	Loads ruleset page cache + rebuilds bookmark tag index

UI binding: `createElement` (mounting fields)

What it does: Builds the View Layer DOM for a field, stores a reference on the field (field.element), and returns the mountable node.

this._configurationManager.createElement('My Setting')  // display name

Invokes the field's createElement() which:

Builds View Layer DOM (HTMLElement).
Stores the node on field.element (HTMLElement|null).
Returns the mountable node, or null when the dock is active and the field is docked (panel XOR dock — empty sentinel is null, not an empty jQuery set).

createDockElement(name) similarly returns HTMLElement|null and stores on field.dockElement.

Fields without createElement called remain memory-only until mounted.

Each field implements:

Callback	When
`createElement()`	First mount
`setFromUserInterface()`	Apply/Save — read DOM → `field.value` (+ ruleset optimize)
`updateUserInterface()`	Load/reset/tab switch — write `field.value` → DOM

Reading values at runtime

this._configurationManager.getValue('My Setting')
this._configurationManager.getField('My Setting')       // ConfigurationField | null
this._configurationManager.getFieldOrFail('My Setting') // throws if missing
this._configurationManager.hasField('My Setting')

ConfigurationField properties: title, type, element (HTMLElement|null), dockElement (HTMLElement|null), value, optimized?, help, minimum, maximum, options, persist, widget, ruleset callbacks.

Persistence (drivers, aggregate blobs, self-managed fields)

Each field has a storage driver key (local by default). Simple fields persist in a per-driver aggregate blob; self-managed types (persist: false, e.g. ledger, bookmarks) use driver primitives directly and participate in backup v2 when they implement serializeForBackup.

Store	Driver	Key	Content
Settings	`local`	`{scriptPrefix}settings`	JSON object: kebab keys → values (skips `persist: false`)
Sync id	`local`	`{scriptPrefix}settings-id`	`{ id: number }` — bumps on save
Settings	`gm`	`{scriptPrefix}settings`	Same shape in GM namespace (lazy; only when a field uses `gm`)
Sync id	`gm`	`{scriptPrefix}settings-id`	Same in GM namespace

`initialize()` (IndexedDB)

Opens per-script IndexedDB (brazen-{prefix}).
Framework may call getPendingMigrationPlan() first. When schemaTooNew is true (installed IDB schema exceeds IDB_SCHEMA_VERSION), it shows a schema-too-new panel (Retry after upgrading the script / Reset database). When consentRequired is true, it shows a consent panel (Start update / Reset database); both gates are skipped for peer-wait-only tabs, pending wipe, _disableUI, and healthy boots.
When migration work is needed (!healthy, setupInProgress, pendingIsDiscoveredBackfill, or !rulesetMigrated), auto-downloads a pre-migration safety backup (createPreMigrationSafetyBackup) — v3 zip including legacy tagRules / tagRuleSets when still present.
Runs setup, backfill, or ruleset migration; invokes options.onMigrationProgress({ phase, label, detail?, current?, total?, indeterminate? }) for each phase.
Throws on failure (getMigrationError()); Framework shows migration failure panel with downgrade/restore guidance.

onMigrationStatus (string) is still accepted as a shorthand for onMigrationProgress.

Legacy driver-based init (local/GM aggregate blobs) applies only when IndexedDB is unavailable.

Save / apply / restore

Method	Behaviour
`update()`	All mounted fields: `setFromUserInterface()` (rulesets: trim → optional sort → `onTranslateFromUI` → dedupe rules case-sensitively → `onOptimize`)
`save()`	`update()` → write store → bump sync id
`revertChanges()`	Re-read store into fields + `updateInterface()`
`updateInterface()`	All mounted fields: `updateUserInterface()`

Framework button wiring:

Apply — update() + re-run compliance (no disk).
Save — apply + save().
Reset — revertChanges() + compliance.

Backup format (v2)

backup() downloads {scriptPrefix}backup.json:

{
  "version": 2,
  "id": 123456789,
  "drivers": {
    "local": {
      "tag-blacklist": ["rule1", "rule2"],
      "pagination-threshold": 20
    },
    "gm": {
      "download-ledger": { "postIds": ["123", "456"] },
      "bookmarks": [{ "id": "…", "label": "…", "tags": "…", "url": "…" }]
    }
  }
}

Legacy flat backups (no version / drivers) still import as local values.

restore(response) — fetch/Response with JSON body; each field's applyFromBackup handles semantics (ledger merges ids; bookmarks replace list); restores values + sync id; alerts success/failure. Legacy v1 backups without a bookmarks key leave local bookmarks untouched.

Cross-tab sync

onExternalConfigurationChange(handler) — (manager) => void when another tab saved. Framework registers compliance re-run.

Revision cursor: BrazenStorageRepositories accepts optional onRevisionBump(revisionId). Configuration Manager wires it so every local meta.bumpRevision() advances _syncedRevisionId immediately. Same-tab visibilitychange after your own writes is then a no-op and does not wipe unsaved panel edits. Foreign revision sync clears TagRuntime RAM so sidebar / filters refetch attributes instead of reusing stale ensureNames cache entries.

Tag runtime warm cache: After tag registry writes, _commitTagFieldChange calls TagRuntime.warmCache() (marks ready) and relies on _cacheEntry / ensureNames — it does not reload the full tags table into RAM.

Tag discovery bulk reset: resetAllTagsDiscovered(onProgress?) delegates to TagRepository.resetAllTagsDiscovered, clears TagRuntime RAM, then _commitTagFieldChange() so other tabs and sidebar/discovery chrome refresh via tags notify. Does not alter rulesets, bookmarks, or queues. Exposed in Framework Toolbox → Database → Reset Tag Discovery (confirm + inline progress). See tagging.spec.md for isDiscovered writer conventions.

Validation helper: `generateValidationCallback`

generateValidationCallback(configKey) → default enable checks:

Type	Active when
flag / radios / select	truthy value
checkboxes	`length > 0`
number	`value > 0`
range	`minimum > 0 \
ruleset / text	`length > 0`

Used by framework _addItemComplianceFilter when no custom validate callback is supplied.

Integration checklist (apps)

Register all fields before init() builds UI.
Use stable English labels — they appear in the panel and backup JSON keys.
Mount with createElement inside tab panels.
Pair enable flags with filters (addFlagField + ruleset).
Self-managed fields (addLedgerField) use IndexedDB stores — no ad-hoc GM_setValue in apps.
Config defaults ownership — declare defaults in registerFieldSeed(s); _seedAllFields() / schema migrations write IDB once; registration never upserts defaults; new defaults for existing installs need a schema version bump + handler. See spec Config defaults ownership + PR checklist.
Set #bv-ui userScript reference if tabs need updateInterface from custom widgets.

Next in stack: optional Tag Query Engine → optional Paginator / Subscriptions Loader → Framework core.

Public API reference (index)

Field creation: addFlagField, addTextField, addNumberField, addColorField, addRangeField, addSelectField, addCheckboxesGroup, addRadiosGroup, addRulesetField, addActionField, addLedgerField
Mounting fields: createElement(name)
Reading: getValue, getField, getFieldOrFail, hasField
Lifecycle: initialize, getPendingMigrationPlan, getSchemaVersionConflict, createPreMigrationSafetyBackup, getPreMigrationBackupFilenameHint, getMigrationError, update, save, revertChanges, updateInterface
Sync/backups: backup, restore, onExternalConfigurationChange
Helpers: generateValidationCallback

Integration notes (grants, load order, pitfalls)

Load order: after Utilities, View Layer, and IndexedDB Storage, before optional Tag Query Engine and Framework core.
Pitfall: define fields unconditionally (constructor). Page-dependent behavior belongs in the framework lifecycle hooks, not in “field exists / doesn’t exist” logic.