feat(client): Phase 2 — per-app settings panes, folder tree, multi-directory

Each app's settings were inlined in `group-settings.js` — TMDB, MusicBrainz,
and one folder picker per app, each with its own draft state and save handler
saying the same thing about a different key. They are one file per app now,
reached through the `apps.js` registry, and the page that renders them names no
application at all: adding one is a registry entry and a settings file.

The line between the two is what makes that true. What every app has — folders
— the page does generically, through one `saveDirectories` bound to the app.
What one app alone has, its pane does itself with the transport it is handed.
An app that only needs directories touches neither `group-settings.js` nor
`group-page.js`, which is `test_app_settings_plugin.py`'s subject.

`settings-ui.js` exists because a pane importing the page that renders it is a
cycle, and ES modules answer that with a temporal-dead-zone ReferenceError at
first render — a component that silently does not appear, the fault already
recorded in CLAUDE.md about hook ordering.

The flat depth-indented `<select>` of every folder in the library becomes a
modal tree. It asks the node for nothing: the tree is derived from paths the
client already holds, so it shows exactly what the group's index contains and
adds no folder-browsing protocol. For Chat's attachment folder — the one
directory that is written to rather than read — read-only roots are greyed
out, so the node's refusal arrives before the operator picks rather than when
somebody sends a file.

Videos and Music take a list of folders. A library on two drives could not be
described before; the only recourse was pointing the app at a parent containing
both, which pulls in everything else under it. The scalar shapes survive on the
wire alone, for a node speaking MNP 1.0, and the client reads them as a
one-element list.

Two things the tests caught that I would not have:

`test_asset_versioning` — six new modules were missing from `_ASSETS`. Reached
through the registry rather than imported by name, they are exactly the files
nothing else would notice changing, and a stale one is served from cache with
no version bump.

And `node --check foo.js` does **not** reliably report a module syntax error:
it accepted `${/* ... */''}` — htm template syntax pasted into a plain object
literal — and reported success. A `.mjs` copy forces the module parser and
reports it. The suite had no syntax check at all, which is how that reached a
file; `test_spa_syntax.py` does it for every module now, and pins that the
loose path is not what it uses.

Suite: 12 failures, all pre-existing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011pvMdvLBG92jyhvD5pD6us

2 files changed, 123 insertions, 6 deletions

diff --git a/docs/apps.md b/docs/apps.md
index 7ce1e73..7819dc9 100644
--- a/docs/apps.md
+++ b/docs/apps.md
@@ -146,6 +146,12 @@ async def set_enabled_apps(group_id, apps, set_by="") -> list[str]: ...
 from exactly one place: `webrtc_server.py`'s `_admin_exec_apps_enabled`, after
 `_verify_admin_sig` — nothing is applied before the signature checks out.
 
+**An app's directories are the same shape one level down** (2026-09-06):
+`ops.set_app_directories(state, group_id, app_key, paths)`, stored under
+`<app_key>_directories`, reached by one MNP message (`app_directories`) and one
+loopback route. Adding an app adds no function, no message type and no route —
+which is what "plugin architecture" has to mean to be worth the phrase.
+
 `_do_apps_enabled` in `webrtc_server.py` validates before it ever issues a
 challenge:
 - `apps` non-empty — the operator can never lock a group down to nothing.
@@ -170,6 +176,37 @@ table. Changing it broadcasts `apps_enabled_ack` to everyone already connected
 waiting for a reconnection. The root ops (`root_update_ack`, `root_eject_ack`,
 `root_plug_ack`) broadcast the same way, through `onRootsChanged`.
 
+### 3b. An app's settings
+
+Each app that has settings exports a component from
+`static/<app>-app-settings.js` and names it in its `apps.js` entry. The Settings
+page renders one collapsible section per registry entry, with the app's own
+on/off switch in the header — the toggle *is* the enablement control, rather
+than a checkbox list somewhere else that could disagree with it.
+
+Every pane takes the same props, and nothing else: `roots`, `dirs`, `settings`,
+`saveDirectories` (bound to this app), `transport`, `signFn`. The split is the
+point — **what every app has, the page does generically; what one app alone
+has, the pane does itself.** Pointing an app at folders goes through
+`saveDirectories`; a TMDB credential or a link-preview switch is the pane's own
+business, made with the transport it is handed. An app that only needs
+directories therefore touches neither `group-settings.js` nor `group-page.js`,
+and `test_app_settings_plugin.py` fails if either of them starts naming apps
+again.
+
+Two constraints that are not obvious:
+
+- **A pane must not import `group-settings.js`.** That is a cycle
+  (`group-settings` → `apps` → pane → `group-settings`), and ES modules answer
+  it with a temporal-dead-zone `ReferenceError` at first render — the component
+  does not appear, with nothing in the console to say why. The shared widgets
+  (`CollapsibleSection`, `ToggleSwitch`, `useSaver`) live in `settings-ui.js`
+  for this reason.
+- **A new module must be added to `_ASSETS`** in `meshbay_hub/api/webapp.py`.
+  A file reached through the registry is not imported by name anywhere, so
+  nothing else would notice it changing, and a browser would go on serving the
+  cached copy. `test_asset_versioning` enforces it.
+
 **Client side:** `apps.js`'s `visibleApps(enabledKeys)` filters the registry;
 `group-page.js` calls it with `enabledApps` state (from the ack, `null` until
 one arrives, which `visibleApps` reads as "show everything registered" — a
@@ -187,8 +224,17 @@ registry, so a newly-registered app gets a checkbox for free.
    `icon.js` — do not re-implement `formatSize`, the download pipeline, or
    `Icon`.
 2. **Register it** in `apps.js`'s `APPS` array: `{ key, icon, labelKey,
-   Component }`. `key` is the wire identifier — it must match what you add to
-   the node's allow-list next.
+   Component, Settings? }`. `key` is the wire identifier — it must match what
+   you add to the node's allow-list next, and it is also the row an app's
+   directories are stored under (`<key>_directories`). One identifier per app,
+   everywhere; `test_app_settings_plugin.py` checks the registry against
+   `ALLOWED_APPS`.
+2b. **`<name>-app-settings.js`**, if the app has anything to configure,
+   exporting a component that takes `{ roots, dirs, settings,
+   saveDirectories, transport, signFn }` and nothing else (§3b). Folders go
+   through `saveDirectories`; anything only this app has, it does itself with
+   the transport. **Do not import `group-settings.js`** — that is a cycle, and
+   it fails as a component that silently does not render.
 3. **Node-side allow-list**: add the key to `ALLOWED_APPS` in
    `webrtc_server.py`. Without this the node refuses `apps_enabled` for any
    set naming it (`"Unknown app(s): ..."`), so an operator can never turn it
@@ -196,7 +242,7 @@ registry, so a newly-registered app gets a checkbox for free.
 4. **i18n**: at minimum, a `group.tab_<name>` key (the tab's tooltip/label,
    reused as the Settings checkbox label) in all ten `static/locales/*.js`
    files. `test_locales.py` holds them to the same key set.
-5. **`webapp.py`'s `_ASSETS`** tuple: add the new file. This is the
+5. **`webapp.py`'s `_ASSETS`** tuple: add both new files. This is the
    cache-busting hash's input list — a file imported by the page but missing
    here can change without the served URL changing, which is the exact bug
    class `test_asset_versioning.py` exists for. Forgetting this step used to be
@@ -216,6 +262,11 @@ registry, so a newly-registered app gets a checkbox for free.
 
 No protocol change, no hub change, no `daemon.py` change — steps 3 and 6 are
 the only node-side touches, and both are allow-lists, not new wire messages.
+Directories in particular need nothing server-side at all: `app_directories` is
+one generic op keyed by the app's name (§3), and an app storing its folders
+under a key nobody wrote code for is the case
+`test_app_directories.py::test_an_app_nobody_wrote_code_for_stores_its_directories`
+pins.
 
 ## 5. What does not exist yet
 
diff --git a/docs/refactor-groups.md b/docs/refactor-groups.md
index 3d7412b..f94a18b 100644
--- a/docs/refactor-groups.md
+++ b/docs/refactor-groups.md
@@ -1,14 +1,14 @@
 # Groups Refactor — Per-Root Permissions & App Plugin Architecture
 
-> Status: **Phase 1 complete and reviewed** (2026-09-06). Phase 2 and 3 not started.
+> Status: **Phases 1 and 2 complete** (2026-09-06). Phase 3 not started.
 >
 > This is the most significant refactoring of the project. It changes how roots
 > are permissioned, how group applications are configured, and how the Settings
 > and Create Group pages are structured.
 >
 > §7b records what the review of Phase 1 found and how the plan below was wrong
-> where it was wrong. Read it before starting Phase 2 — two of its entries are
-> rules the later phases have to follow, not one-off fixes.
+> where it was wrong; §7c does the same for Phase 2. Read both before starting
+> Phase 3 — several entries are rules rather than one-off fixes.
 
 ---
 
@@ -752,3 +752,69 @@ configured directory.
 - `test_ops.py::test_a_backslash_path_written_into_node_toml_stays_parseable`
   fails on any non-Windows machine and always has — it builds a
   `PurePosixPath` from a Windows path. Unrelated to this refactor, left alone.
+
+---
+
+## 7c. Phase 2 as built (2026-09-06)
+
+The plan held. Four things were done differently, and one of them is a rule.
+
+### The rule
+
+**A settings key added to the client must be added ten times.** `test_locales`
+holds the nine other catalogues to `en.js`, so a missing key is a failing test
+rather than a silent gap — but Phase 2 added 27 keys, and doing them one file
+at a time is how the Phase 1 gap happened. Write the table, generate the
+insert.
+
+**And a second one, which cost a bug in this phase:** `node --check foo.js`
+does **not** reliably report a module syntax error. It accepted a file with
+`${/* ... */''}` — htm template syntax, pasted into a plain object literal —
+and reported success. Copying to `.mjs` first forces the module parser, which
+reports it. `test_spa_syntax.py` now does that for every module; the suite had
+no syntax check at all before, which is how the file was committed.
+
+### Done differently
+
+- **No migration script.** The plan (§4.3) called for one to rename
+  `video_root` → `video_directories` in `roster.db`. Instead the roster falls
+  back to the old key when the new one is unset, and the first save through the
+  new path leaves it behind. A script that has to be run by hand on the machine
+  where it matters is a step that does not happen; a fallback is one that
+  cannot be skipped.
+- **`music`, not `audio`.** The app's registry key was `music` while its
+  storage said `audio_root` and its ops said `set_audio_root`. One identifier
+  per app now — the registry key — with the correspondence in exactly one
+  table (`Roster.LEGACY_DIR_KEYS`).
+- **One storage shape.** `set_app_directory` (single) writes a one-element
+  list, so there is no scalar form anywhere below the wire. `video_root` and
+  friends survive on the handshake ack only, *derived* from the list rather
+  than stored beside it — a second stored value drifts within one run, which
+  reads as "it works after a restart".
+- **The panes call the transport themselves.** The plan had every pane report
+  through one `onSave`, which would have made the page a dispatcher naming
+  every app's settings keys — the thing the phase exists to remove. The line
+  is: what every app has (directories) the page does, generically; what one
+  app alone has (a TMDB key, a link-preview switch) the pane does with the
+  transport it is handed. An app that only wants directories touches neither
+  file, which is `test_app_settings_plugin.py`'s subject.
+
+### Worth knowing
+
+- `settings-ui.js` exists because `group-settings` → `apps` → a pane →
+  `group-settings` is an import cycle, and ES modules answer that with a
+  temporal-dead-zone `ReferenceError` at first render — the component simply
+  does not appear, which is the fault already recorded in CLAUDE.md about hook
+  ordering. The shared widgets live outside both.
+- The folder picker asks the node for **nothing**. The tree is derived from
+  paths the client already holds, so it shows what the group's index contains
+  and no more — a folder the node never indexed does not exist as far as the
+  group is concerned. There is no folder-browsing protocol and this does not
+  add one.
+- `_ASSETS` in `webapp.py` had to grow by six. Modules reached through the
+  registry rather than imported by name are exactly the ones nothing else would
+  notice changing, and a stale one is served from a browser cache with no
+  version bump. `test_asset_versioning` caught it.
+- **What Phase 3 still owes:** the HelloWorld app (§4.1) — which is the actual
+  proof of the above, since every test here reads source rather than adding an
+  app and watching it work — plus the CLI polish and the Windows pass.