diff --git a/plugins/EXTRACTING-A-PLUGIN.md b/plugins/EXTRACTING-A-PLUGIN.md index 03fbde06..ac3fde9f 100644 --- a/plugins/EXTRACTING-A-PLUGIN.md +++ b/plugins/EXTRACTING-A-PLUGIN.md @@ -116,8 +116,12 @@ A normal refresh is enough; the shell is `no-store`. When the log's last line ap ## Music specifically — READ THIS BEFORE STARTING **Music is not a bigger offscale. It does not fit the shape, and three of its parts have nowhere to go.** -Mapped 2026-08-15. Decide what to do about each *before* moving a file, or the extraction strands -half-done. +Mapped 2026-08-15. + +**Decide these yourself. Do not stop to ask.** Every one of them has two defensible answers, the owner has +said either is fine, and a corrected decision is cheap where a stalled extraction is not. Record what you +chose and why — in the manifest, in a comment, in the commit message — and keep going. The failure mode to +avoid is not a wrong call; it is a tree left half-moved with a question attached. ### What has no home yet @@ -166,16 +170,27 @@ take `homedir()` as their root independently. So a granted member's favourites a `/stream` serves them the **owner's** files and cliamp spawns a process in the **owner's** home. The app-store entry promises a configurable `library` folder and **nothing reads it**. -### Suggested order +### How to decide the three, if you want a default -**Do not** invent the visibility model during the move. Extract with the semantics it already has, or the -two changes tangle and a bug in either is a bug in both. +Each of these is "close the platform gap" or "leave the piece behind". **Closing the gap is better when +you have the runway**, because every later plugin needs it too — but a music that works with cliamp left +in the platform is worth far more than a perfect design that did not land. -1. Decide the three homeless parts first — close the platform gaps, or leave those pieces behind and say - so explicitly in the manifest. Either is defensible; drifting is not. -2. `assertCapabilityTotality` should be fixed **before** this one: the cliamp routes are the live example - of the exact drift it cannot currently see. -3. Then the move, in the order above. +| Part | Close the gap | Leave it behind | +| --- | --- | --- | +| websockets | wire `server.reload({ routes })` — already proven, never called — so a manifest can declare ws providers | leave `cliamp`/`cliamp-audio` and the relay in the platform, note it in the manifest | +| global overlay | add one slot the shell renders from installed plugins | leave `MusicPlayerHost` in `DashboardLayout`, gated on the permission as it already is | +| widget | let a plugin contribute `widgetRegistryMetas` | leave `widgets/MusicPlayer` where it is | + +Whatever you pick, the plugin must **install, enable, disable and uninstall cleanly** at the end. A piece +left in the platform is a documented seam; a piece left dangling is a bug. + +`assertCapabilityTotality` is worth fixing on the way past if you touch the websocket path — the cliamp +routes are the live example of the drift it cannot currently see (routes upgrading into commented-out +handlers). Not required. + +**Do not** invent music's per-user visibility model during the move. Extract with the semantics it has, or +the two changes tangle and a bug in either is a bug in both. ---