Follow-up to #3588506, which added the theme discovery mechanism and the per owner-modeler **Theme** select. ## Problem Today a theme only takes effect once an administrator visits the settings form and picks it. If a module such as Maestro is installed and ships a theme intended for its own models, nothing happens until someone configures it by hand. The desirable behavior is that such a theme applies on installation, without the site owner having to know it exists. ## Why "configure it automatically when the setting is empty" does not work The obvious implementation — detect that no theme is configured for an owner-modeler combination and write one in — is not reliable, because "no theme is configured" stops being an answerable question very early in a site's life. - The module ships no `config/install/modeler_api.settings.yml`, so before the settings form has ever been saved the key really is absent and `Settings::value()` returns its `$default` argument. - But `Settings::submitForm()` writes the theme key for **every** owner-modeler combination unconditionally, whatever the administrator actually came to change. So the first save of that form — even one made only to switch a storage option — persists `theme: default` for every combination. From that point on, "never configured" and "deliberately chose the modeler's own look and feel" are the same stored value and cannot be told apart. An auto-configure-if-empty feature would therefore fire at most once per site, and would never fire at all on a site where the settings form had been saved before the theme-providing module was installed. It would work in a fresh test environment and be silently absent in production, with nothing logged either way. Writing the config from an install hook instead has its own drawbacks: - A module installation would silently modify site configuration. - On a site that manages configuration in code, the next configuration import reverts the value, and the install hook does not run a second time to reapply it. - The result depends on whether the theme provider is installed before or after the model owner. - Uninstalling the provider leaves a stored theme ID that no longer resolves. `Api::attachTheme()` already falls back gracefully, so nothing breaks, but the stored configuration no longer reflects reality. ## Proposed resolution Resolve the theme at render time instead of persisting a guess, and let the stored option carry the intent explicitly rather than inferring it from absence. Extend the Theme select with a third kind of value: | Value | Meaning | | --- | --- | | `auto` | Let the Modeler API choose an applicable theme. **Also the fallback when the key is absent.** | | `default` | Explicitly keep the modeler's own look and feel. Unchanged. | | a theme ID | Explicitly pin one theme. Unchanged. | `Api::attachTheme()` already resolves the setting on every request, so `auto` adds no new machinery: it asks `ThemePluginManager::getThemesFor()` for the themes that apply to the combination and selects one. Benefits over persisting a value: - No configuration is written, so nothing can drift, be reverted by a configuration import, or go stale. - A theme starts applying the moment its module is installed and stops the moment it is uninstalled. - An administrator can always override the automatic choice, and `default` remains available as an explicit opt-out. ## Open decisions Two questions are product decisions rather than implementation details. A recommendation is given for each. ### 1. Which themes may be selected automatically? **Recommendation: only themes that opt in.** An `auto: true` flag in the theme's YAML definition is preferable to inferring candidacy from the `owners:` constraint, because it states the intent directly. Without an opt-in, any module shipping an unconstrained theme — one with no `owners:` and no `modelers:` list, which by design applies everywhere — would restyle every canvas on the site as soon as it is installed. Being chosen automatically should be something a theme author asks for. ### 2. How is a tie broken when several themes qualify? **Recommendation: an optional `weight:` key in the theme definition, with the theme ID as the final tie-break.** Two themes restricted to the same owner need a deterministic winner. Discovery order reflects module weight and is too unstable to depend on, so it should not decide the outcome. ## Scope - `ThemePluginManager` / `Theme`: the `auto` opt-in flag and the optional `weight`, plus a resolution method that returns the best applicable theme for an owner-modeler combination. - `Api::attachTheme()`: handle `auto`, and treat a missing key as `auto`. - `Form\Settings`: offer the new option in the select, with a description explaining the three meanings. - Documentation: `docs/plugin-managers/theme/index.md` and `docs/guide/yaml-plugins.md`. - Unit test coverage for the resolution order, the opt-in filter, and the tie-break. ## Compatibility Sites that already store `theme: default` keep the modeler's own look and feel, because `default` retains its meaning. Automatic selection then applies only where an administrator switches the option to `auto`. That is the conservative direction: no site changes appearance on update.