Say what a plugin settings tab can actually do, and catch a declaration that cannot work

Finding F12 of the architectural review, checked against the code and found
worse than reported: the dynamic component import cannot be rewritten by the
bundler, so the built file ships the unresolved path and a plugin tab answers
404 in every production build, staged or not. It works only under the dev
server. Nothing shipping is affected, because the one plugin that declares a
tab also registers the same page as an ordinary route, and that is the one
sites reach.

- The ADR draft now carries a "Constraints as implemented" section: only the
  model catalog hub registers plugin tabs, registration happens when that hub
  mounts so a tab is not deep-linkable and does not survive a refresh, and the
  build finding above with the bundler's own warning. The two ways out are
  stated as the open decision rather than taken.
- The hook's docstring reads as instructions to a plugin author, and its
  example no longer names a path that does not exist at build time.
- A route declared for a hub that cannot render it is dropped with an error
  naming the plugin, the hub and the hubs that do work, and the same is logged
  at startup. Enabling the plugin still succeeds: a tab nobody can reach is no
  reason to take a working backend offline.
- Tests hold the two halves together: no bundled plugin may declare a hub the
  frontend does not implement, and the list in the server must equal the hubs
  that really register routes, so the two cannot drift apart again.

docs/wiki-drafts/ADR-019-Plugin-Dynamic-Settings-Routes.md

@@ -84,7 +84,7 @@ def get_plugin_settings_routes():
     return success_response({'routes': routes})
 ```
 
-**Auth:** Deliberately anonymous (`jwt_required(optional=True)`) so unauthenticated pages (kiosks, TV displays) can load plugin routes.
+**Auth:** the endpoint is gated on `settings.view`. It was written anonymous, on the reasoning that unauthenticated pages (kiosks, TV displays) register plugin tabs before login. Nothing does: its only caller is `ModelCatalogHub.vue`, which sits behind `requiresAuth` and `requiresAdmin`. Open, it handed an anonymous caller the enabled plugin list, the settings hub layout and the internal Vue component paths, so it was closed.
 
 ### Frontend: Dynamic Route Registration
 
@@ -163,6 +163,80 @@ onMounted(async () => {
 - Components lazy-load when the tab is clicked (code-splitting preserved)
 - Tabs only appear if the plugin is enabled and staged
 
+## Constraints as implemented
+
+What the sections above describe is the mechanism as designed. What ships is
+narrower, and a plugin author reading only the hook signature would not find
+this out until a tab failed to appear in front of a user. The three constraints
+below are the ones the contract does not express.
+
+**One hub draws plugin tabs: Model Catalog.** `router.addRoute` appears exactly
+once in the frontend, in `frontend/src/views/settings/ModelCatalogHub.vue`.
+`AssetConfigHub`, `SiteConfigHub`, `NetworkHub`, `SecurityHub`, `LocationsHub`,
+`IntegrationsHub` and `AssetTypeHub` render their own tabs and nothing else, so
+a route declaring any of their ids is accepted by the hook, returned by the API
+and drawn by nobody. Adding a hub to the supported set means writing the
+fetch-and-register code into that hub's `.vue` file, not editing a list. The
+supported set is named once, in `SETTINGS_HUBS_WITH_PLUGIN_TABS`
+(`shopdb/plugins/base.py`); `/api/plugins/settings-routes` drops a route outside
+it and logs an error naming the plugin and the hub, the plugin manager logs the
+same finding at startup, and `tests/test_core/test_plugin_settings_hubs.py`
+fails if a bundled plugin declares an unsupported hub or if the list and the
+frontend drift apart.
+
+**A plugin tab is not deep-linkable.** The hub registers its plugin routes in
+`onMounted`. Before the hub has mounted, the router has no such route, so
+navigating straight to a plugin tab URL - from a link, a bookmark, or a refresh
+while sitting on one - resolves against a router that does not know the path.
+Only arriving through the parent hub works. This is a real limit on what a
+plugin settings page can be: it cannot be somewhere you send a person.
+
+**The component does not load in a production build at all.** The `component`
+field is a server-supplied string interpolated into a dynamic import,
+``() => import(`../../${tab.component}`)``. Vite refuses that template - it has
+no static file extension - and says so during every build:
+
+	[plugin vite:dynamic-import-vars] src/views/settings/ModelCatalogHub.vue:
+	invalid import "../../${tab.component}". A file extension must be included
+	in the static part of the import.
+
+The build still succeeds, and the emitted chunk carries the expression verbatim
+(`import(`../../${e.component}`)`), rewritten to nothing. At runtime the browser
+resolves it against the chunk's own URL under `/assets/` and asks the server for
+a `.vue` file; `dist/` contains no `.vue` files, so the request 404s and the tab
+throws when it is clicked. Under `npm run dev` the same import works, because
+the dev server serves sources by path. So the mechanism as it stands is a
+development-only path: a tab that appears in production and fails on the click.
+
+Nothing visibly broke because the one plugin using it does not depend on it.
+`plugins/computers/frontend/routes.js` also registers the same page statically
+at `/settings/operatingsystems`, and that route - a normal static import, a real
+URL - is what production actually uses. The dynamic tab is a duplicate way in.
+
+Two ways out, and this ADR does not pick one: give the template a static
+extension (declare `component` without `.vue` and import ``${component}.vue``),
+which makes Vite glob every `.vue` under `frontend/src` at build time and makes
+the tab real for staged plugins while staying build-time bound; or accept that
+plugin settings pages are ordinary plugin routes and drop the hub-tab mechanism.
+Deciding that is the open question the architectural review raised.
+
+**What a plugin author must therefore do:**
+
+1. Declare `hub: 'model-catalog'` or declare nothing. For a settings page that
+   belongs anywhere else, own a full page under the plugin's own routes
+   (`plugins/<name>/frontend/routes.js`), which is statically registered, deep-
+   linkable and not subject to any of this.
+2. Register the page in `plugins/<name>/frontend/routes.js` even when you do
+   declare a tab, and treat that route as the real one. A tab whose component is
+   reachable no other way is a page nobody can open in production.
+   `tests/test_core/test_plugin_settings_hubs.py` enforces this.
+3. Point `component` at the staged path - `.plugins-staged/<name>/views/X.vue`,
+   relative to `frontend/src` - and keep the source at
+   `plugins/<name>/frontend/views/X.vue` so staging finds it.
+4. Expect the frontend to be rebuilt when the plugin is added to a site.
+   Enabling the plugin alone does not put its component in the bundle.
+5. Do not publish, link to or bookmark the tab's URL. Send people to the hub.
+
 ## Consequences
 
 ### Benefits
@@ -171,7 +245,7 @@ onMounted(async () => {
 
 **Plugins self-contain their UI:** Adding a settings page to a plugin no longer requires touching core code. The plugin declares the route; the framework discovers it.
 
-**Runtime flexibility:** Enabling/disabling a plugin (via `/api/plugins/{name}` PUT) changes what routes are returned. After an app restart, the tabs appear or disappear automatically.
+**Runtime flexibility:** Enabling/disabling a plugin (via `/api/plugins/{name}` PUT) changes what routes are returned. After an app restart, the tabs appear or disappear automatically - for a plugin whose frontend is in the running bundle. Enabling one that was never staged adds a tab whose component cannot be resolved (see "Constraints as implemented").
 
 **Composability:** Multiple plugins can contribute to the same hub. Model Catalog could have tabs from `computers` (Operating Systems), `printers` (Printer Models), `machines` (Machine Types), etc., with no conflicts.
 
@@ -179,7 +253,11 @@ onMounted(async () => {
 
 **Route registration is async:** The tabs appear after mount, not at router initialization. In practice this is <100ms and visually seamless, but the router doesn't know about plugin routes at build time.
 
-**Component paths are strings:** The `component` field is a string path that gets interpolated into `import()`. This prevents static analysis tools from tracing the dependency, though Vite's glob imports during the plugin staging step ensure the files are bundled.
+**Component paths are strings:** The `component` field is a string path that gets interpolated into `import()`. This prevents static analysis tools from tracing the dependency, and as written Vite will not rewrite the import at all, so it resolves in the dev server and 404s in a build (see "Constraints as implemented").
+
+**Composability is one hub wide:** "Multiple plugins contribute to the same hub" is true of Model Catalog and of no other hub, because no other hub page registers plugin routes. See "Constraints as implemented".
+
+**A plugin tab has no URL worth sharing:** routes register at hub mount, so the tab is not reachable by link, bookmark or refresh.
 
 **No SSR for plugin tabs:** Server-side rendering can't evaluate `router.addRoute()` at build time. ShopDB doesn't use SSR, so this is not a concern, but it would block SSR adoption without refactoring.
 

docs/wiki-drafts/README.md

@@ -14,6 +14,8 @@ This directory contains drafted wiki pages based on work completed Q3 2026. Copy
 - Decision: Backend hook + frontend dynamic route registration
 - Implementation: BasePlugin hook, /api/plugins/settings-routes endpoint, ModelCatalogHub integration
 - Benefits: Lean builds work, plugins self-contain UI, runtime flexibility
+- Constraints as implemented: Model Catalog is the only hub that draws plugin
+  tabs, the tabs are not deep-linkable, and the component is bound at build time
 
 **Related commits:** fe09d2745e, d59d0c3194
 
@@ -109,12 +111,36 @@ class ComputersPlugin(BasePlugin):
 
 The frontend fetches routes from `/api/plugins/settings-routes` and registers them dynamically via `router.addRoute()`.
 
+### Rules for declaring one
+
+1. **Declare `hub: 'model-catalog'` or declare nothing.** Model Catalog is the
+   only hub whose page registers plugin tabs. A route naming any other hub
+   (`asset-config`, `security`, `network`, ...) is dropped by the API with an
+   error in the log, because nothing would draw it. For a settings page that
+   belongs elsewhere, own a full page in `plugins/<name>/frontend/routes.js`
+   instead: it is statically registered and behaves like any other route.
+2. **Your frontend must be staged into the build.** `component` is a path
+   relative to `frontend/src`, so it must be the staged copy -
+   `.plugins-staged/<name>/views/X.vue`, made by `scripts/stage-frontend.mjs`
+   from `plugins/<name>/frontend/views/X.vue`. Enabling the plugin at runtime
+   does not put the file in a bundle that was built without it; that needs a
+   frontend rebuild.
+3. **Register the page in your `routes.js` too, and treat that as the real
+   route.** The hub's import of your component is not rewritten by Vite (no
+   static file extension in the template), so it resolves under `npm run dev`
+   and 404s in a production build. The tab is a convenience on top of a normal
+   plugin route, not a way to ship a page. A gate test enforces this.
+4. **Do not link directly to your tab's URL.** The hub registers the route when
+   it mounts, so the URL only resolves for someone who reached it through the
+   hub. A bookmark, a link in an email, or a refresh on the tab lands nowhere.
+
 **Benefits:**
 - Lean builds work (no hardcoded plugin imports)
 - Plugins self-contain their UI extensions
-- Runtime flexibility (enable/disable plugin affects tabs)
+- Enable/disable changes the tabs, for a plugin already in the build
 
-**Reference:** ADR-019 Plugin Dynamic Settings Routes
+**Reference:** ADR-019 Plugin Dynamic Settings Routes, section "Constraints as
+implemented"
 ```
 
 ---
@@ -125,9 +151,9 @@ The frontend fetches routes from `/api/plugins/settings-routes` and registers th
 ```markdown
 ## GET /api/plugins/settings-routes
 
-Returns settings routes contributed by all enabled plugins via `get_settings_routes()` hook.
+Returns settings routes contributed by all enabled plugins via `get_settings_routes()` hook. A route naming a hub that does not draw plugin tabs is dropped, with an error in the server log naming the plugin and the hub.
 
-**Auth:** None (jwt-optional, deliberately anonymous for kiosk/TV displays)
+**Auth:** `settings.view` (it names the enabled plugins, the hub layout and the internal component paths; no pre-login page calls it)
 
 **Response:**
 ```json
@@ -147,7 +173,7 @@ Returns settings routes contributed by all enabled plugins via `get_settings_rou
 }
 ```
 
-**Used by:** Settings hub pages (ModelCatalogHub, AssetConfigHub, etc.) to dynamically register plugin tabs.
+**Used by:** ModelCatalogHub, to register plugin tabs. It is the only hub page that does; the others draw their own tabs only.
 
 **Reference:** ADR-019 Plugin Dynamic Settings Routes
 ```