every plugin route renders a workspace, and it is not a rule you can forget

an exclusionary rule, made structural. a plugin does not render a screen: it
contributes panels and says how they are arranged, and the shell renders
WorkspaceView around them.

    web/panels.ts   appRegistryMetas — at least one panel
    web/layout.ts   defaultLayout — how they are arranged

both required the moment web/ exists, and missing either is refused at discovery
by name and with the reason. tested:

    probeplug: has a web/ directory but is missing web/layout.ts.
    Every plugin route renders a Workspace: contribute panels and a layout,
    not a screen.

there is deliberately no way to export a component. one that could would be free
to render a bare div, a full-page form, or its own navigation, and the platform
would become a shell hosting strangers' layouts rather than one application.
non-compliance is not so much refused as unrepresentable — there is nowhere to
put a screen.

the shell registers <prefix> and <prefix>/:section, exactly as the core screens
do, so a plugin's sections stay addressable and cmd-clickable, and panels read
useParams independently rather than passing state between themselves.
appTypes.allowed is pinned to that plugin's own keys, so a persisted layout
naming something else falls back instead of rendering another plugin's panel
inside this screen.

the example plugin is rebuilt to model it — two panels, a layout, one of them
calling its own /api/example/ping through useClient — because the reference
implementation is what everyone copies.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/server.tsx

@@ -207,8 +207,21 @@ const serveBuilt = async (req: Request): Promise<Response> => {
 
   // An asset if it exists, the shell otherwise. A client-side route like `/offscale/servers` is not a file
   // and must return index.html, which is what makes deep links work at all.
+  // A request that LOOKS like an asset and is not one must 404, never fall through to the shell. Serving
+  // HTML with a JS content-type produces "Unexpected token '<'" and a blank page — a failure mode that
+  // reads as a broken build rather than a missing file.
+  if (/\.(js|css|map|png|svg|ico|webmanifest|woff2?)$/.test(path)) {
+    const file = Bun.file(join(BUILD_DIR, path.slice(1)));
+    if (!(await file.exists())) return new Response('Not found', { status: 404 });
+    return new Response(file, { headers: { 'cache-control': 'public, max-age=31536000, immutable' } });
+  }
+
   const asset = Bun.file(join(BUILD_DIR, path === '/' ? SHELL_FILE : path.slice(1)));
-  if (path !== '/' && (await asset.exists())) return new Response(asset);
+  if (path !== '/' && (await asset.exists())) {
+    // Content-hashed, so the name changes whenever the bytes do and this can be cached hard. The shell
+    // below is the opposite case and must not be.
+    return new Response(asset, { headers: { 'cache-control': 'public, max-age=31536000, immutable' } });
+  }
 
   const shell = Bun.file(join(BUILD_DIR, SHELL_FILE));
   if (!(await shell.exists())) {
@@ -219,7 +232,18 @@ const serveBuilt = async (req: Request): Promise<Response> => {
       headers: { 'content-type': 'text/plain' },
     });
   }
-  return new Response(shell, { headers: { 'content-type': 'text/html' } });
+  // NEVER cache the shell.
+  //
+  // It names the hashed chunks, so a cached shell is a browser pinned to a build that no longer exists on
+  // disk — every asset it asks for 404s, or worse it renders an old app against a current API. Served with
+  // no cache headers at all until now, which leaves it to the browser's heuristics: a plugin could be
+  // installed, the bundle rebuilt, and the tab keep running the previous one with no way to tell.
+  return new Response(shell, {
+    headers: {
+      'content-type': 'text/html',
+      'cache-control': 'no-cache, no-store, must-revalidate',
+    },
+  });
 };
 
 const isProduction = process.env.NODE_ENV === 'production';