a plugin ships its own dock icon as a file, not a lucide name

The manifest's `icon` was a lucide NAME, resolved by `resolveIcon` — which
knows 106 glyphs out of lucide's ~1,500. A plugin naming one outside that set
silently rendered a neutral box, and a plugin from a marketplace had no way to
see the ceiling coming.

So the icon is a FILE now: `plugins/<name>/assets/icon.png`, discovered by
presence like everything else here. `manifest.icon` stays as an optional
fallback for a plugin with no artwork — example and offscale still use it — and
the file wins when both exist.

No new mechanism was needed. The app store already published sidecar assets:
`<dir>/assets/` → `public/plugins/<id>/`, served by a dynamic `/plugins/*`
route, with `DockItem.image` rendering an <img>. `pluginDockManifests()` simply
never emitted `image`. Install now publishes and uninstall unpublishes — the
one thing uninstall is allowed to delete, because these are copies whose
originals are still in the plugin's source.

Base64 in the manifest was considered and dropped. It would ride in every
/api/user/capabilities response for every user on every page load, can't be
cached separately, and puts a 5KB string literal in a source file — against the
rule this manifest keeps: what a directory listing can say, it says. It also
needs no support: `image` goes straight into <img src>, so a data: URL already
works for anyone who wants one.

Music ships OffMusic.png, resized 1254² → 256² (1.6MB → 108KB) with alpha
intact, sized for 3× DPI at the dock's 32px render. It also drops `icon` — the
artwork is a voxel duck in headphones, not a glyph.

The plugins page showed a generic Puzzle for every plugin; the list and detail
header now show the plugin's own icon when it has one.

Two bugs found while testing.

Dock.tsx imported 26 lucide icons and used 14. The twelve dead ones — Music,
Bitcoin, Receipt, Images, CalendarDays, Contact, Clapperboard, Mail, Network,
ArrowDownUp, FileText, FolderKanban, MonitorSmartphone — were residue from when
every feature had a hardcoded tile. Deleted.

And uninstalling a plugin left its icon URL answering 500, not 404. server.tsx
globs ./public at BOOT into one exact route per file, each holding a Bun.file
handle, spread into the route table AHEAD of the /plugins/* wildcard. So an
icon present at boot got an exact route that outlived the file, returning
ENOENT on every dock render with the error logged each time — exactly what the
wildcard's own comment says it exists to prevent. The comment covered the ADD
case; this is its mirror. `plugins/` is now excluded from the boot glob, so the
wildcard owns that prefix alone. Verified: 200 installed, 404 uninstalled, 200
reinstalled.

[open] A plugin's icon cannot be seen BEFORE installing it, which is the one
place an app store most wants to — assets are published at install by design,
and an authenticated icon route is no use to an <img>.

plugins/music/manifest.ts

@@ -10,6 +10,7 @@ import type { PluginManifest } from '@@/plugins/manifest';
 //   api/router.ts     the sidecar proxy, built here — thin, and it must never grow music knowledge
 //   cliamp/           the second playback path, parked
 //   widgets/          the dashboard widget, parked
+//   assets/icon.png   the dock tile, published to /plugins/music/ on install
 //   sidecar/          the whole /api/music contract: indexing, streaming, per-user state
 //   db/               music_favorites, _playlists, _playlist_items, _now_playing
 //   web/              the library panels; the shell renders the Workspace
@@ -44,7 +45,9 @@ export const manifest: PluginManifest = {
 
   label: 'Music',
   summary: 'The music library — browse, play, favourites and playlists',
-  icon: 'Music',
+  // No `icon` field: this plugin ships `assets/icon.png` and the file wins. A lucide name could only
+  // ever pick from the 106 glyphs the platform happens to bundle, which is a ceiling a plugin from a
+  // marketplace cannot see coming — and this one's artwork is a voxel duck in headphones, not a glyph.
   color: '#22c55e',
 
   // One permission gating the whole surface, grantable per role at read or write like every other.

src/apps/officer-web/Screens/Dashboard/Layout/Dock.tsx

@@ -126,27 +126,15 @@ export const Dock = ({ items, className, boundaryRef }: DockProps) => {
 import {
   Home,
   MessageCircle,
-  FileText,
   FolderOpen,
   Code,
   LayoutGrid,
-  FolderKanban,
   Monitor,
-  Mail,
   Globe,
-  MonitorSmartphone,
   Workflow,
   Music,
   Activity,
   Radio,
-  Network,
-  ArrowDownUp,
-  Bitcoin,
-  Receipt,
-  Images,
-  CalendarDays,
-  Contact,
-  Clapperboard,
   GitBranch,
   Store,
   Puzzle,

src/server.tsx

@@ -27,8 +27,22 @@ import type { SidecarRegistration } from './servers/sidecar/registration-protoco
 import { toShellUsername } from './servers/data-path';
 
 // Build static file routes from public/
+// A snapshot of ./public, taken once at boot: one exact route per file, each holding a `Bun.file`
+// handle opened now.
+//
+// `plugins/` is EXCLUDED, and that is not an optimisation. Everything under it is published and removed
+// at runtime by the plugin installer, and this map is spread into the route table ahead of the
+// `/plugins/*` wildcard — so an exact entry here WINS over the dynamic handler that knows how to say
+// 404. A plugin whose icon existed at boot and was then uninstalled left a route pointing at a deleted
+// file, which answered `500 ENOENT` on every dock render until the next restart, with the error in the
+// log each time. Precisely what the wildcard's own comment says it exists to avoid.
+//
+// The add case was already known and is why the wildcard exists at all. This is its mirror: a snapshot
+// cannot describe a directory that changes while the server runs, in either direction. So it does not
+// try — `/plugins/*` owns that prefix alone.
 const publicRoutes: Record<string, (req: Request) => Response> = {};
 for await (const file of new Bun.Glob('**').scan({ cwd: './public' })) {
+  if (file.startsWith('plugins/')) continue;
   const bunFile = Bun.file(`./public/${file}`);
   publicRoutes[`/${file}`] = () => new Response(bunFile);
 }

src/servers/api/plugins/router.ts

@@ -4,6 +4,7 @@ import { isSuperAdmin } from '../../super-admin';
 import { mountPrefix } from '../../plugins/manifest';
 import { snapshotPlugins } from '../../plugins/mount';
 import { manualInstallHint, reportDependencies } from '../../plugins/os-deps';
+import { iconUrl } from '../../app-store/assets';
 import {
   installPlugin,
   pluginProcessStatus,
@@ -65,6 +66,16 @@ pluginsRouter.get('/', async (ctx) => {
       label: plugin.manifest.label,
       summary: plugin.manifest.summary,
       icon: plugin.manifest.icon,
+      // The plugin's own artwork, once published. Only while INSTALLED: `publishAssets` copies
+      // `assets/` into `public/plugins/<appName>/` at install and `unpublishAssets` removes it, so a
+      // plugin that has never been installed has nothing at that URL and an <img> would 404. The list
+      // falls back to a generic glyph, which is what it drew for everything until now.
+      //
+      // `[open]` That means you cannot see a plugin's icon BEFORE installing it, which is the one place
+      // an app store most wants to. Fixing it means either publishing on discovery rather than install —
+      // which breaks "assets are a property of the install" — or an authenticated icon route, which an
+      // <img> cannot use because it sends no Authorization header.
+      ...(plugin.icon && install ? { image: iconUrl(plugin.appName) } : {}),
       color: plugin.manifest.color,
       publisher: plugin.manifest.publisher,
       version: plugin.manifest.version,

src/servers/plugins/discover.ts

@@ -21,6 +21,7 @@ import { manifestProblems, type DiscoveredPlugin, type PluginManifest } from './
 //   sidecar/index.ts   a process (`.mjs` instead means node — see below)
 //   web/panels.ts      panel apps — REQUIRED with web/
 //   web/layout.ts      how they are arranged — REQUIRED with web/
+//   assets/icon.png    the dock tile's image, published to public/plugins/<app-name>/ on install
 //
 // Nothing here reads the database. This answers "what is on disk", which is a different question from
 // "what is installed" — the install table answers that, and the two disagreeing is a state the app store
@@ -100,6 +101,11 @@ export async function loadPlugin(dir: string, appName: string): Promise<Discover
     appName,
     dir,
     manifest: manifest as PluginManifest,
+    // The dock tile's image. A FILE rather than a manifest field, because an icon is a file and
+    // "presence is the declaration" is how everything else here works — and because a lucide name
+    // could only ever name a glyph the platform had already bundled, which is a ceiling a plugin
+    // from a marketplace has no way to see coming.
+    icon: fileOrNull(join(dir, 'assets', 'icon.png')),
     api: fileOrNull(join(dir, 'api', 'router.ts')),
     schema: fileOrNull(join(dir, 'db', 'schema.ts')),
     sidecar: findSidecar(dir),

src/servers/plugins/install.ts

@@ -3,6 +3,7 @@ import { PLATFORM_DIR } from '../data-path';
 import { deleteProcess, processStatus, startProcess, stopProcess } from '../app-store/pm2';
 import { addPluginToEcosystem, pluginProcessName, removePluginFromEcosystem } from './ecosystem';
 import { discoverPlugins } from './discover';
+import { publishAssets, unpublishAssets } from '../app-store/assets';
 import { refreshPluginMounts, snapshotPlugins } from './mount';
 import { generatePluginSchemas, pushSchema } from './schema';
 import { installDependencies, manualInstallHint, reportDependencies, stillMissing } from './os-deps';
@@ -168,6 +169,16 @@ export async function installPlugin(appName: string, onStep?: OnStep): Promise<P
     await recordPluginInstall(appName, plugin.manifest.version);
     await step(steps, onStep, `recorded at ${plugin.manifest.version}`);
 
+    // The dock tile's artwork, copied where the browser can fetch it. Reuses the app store's publisher —
+    // `<dir>/assets/` → `public/plugins/<appName>/` — because it already solves the parts that are not
+    // obvious: the `/plugins/*` route is dynamic precisely so a first install does not show a broken
+    // image until the next restart, and uninstall is allowed to delete these because they are copies of
+    // files that still exist in the plugin's source.
+    if (plugin.icon) {
+      await publishAssets(appName, plugin.dir);
+      await step(steps, onStep, `assets: published to /plugins/${appName}/`);
+    }
+
     // MOUNT BEFORE STARTING THE SIDECAR, and the order is not cosmetic.
     //
     // `createSidecarProxy` learns its sidecar's port from a one-shot event (`<name>:server`), and it
@@ -229,7 +240,10 @@ export async function uninstallPlugin(appName: string, onStep?: OnStep): Promise
     await step(steps, onStep, 'sidecar: stopped, deleted, ecosystem entry removed');
   }
 
-  await step(steps, onStep, 'tables and data: untouched');
+  // The one thing uninstall IS allowed to delete: published assets are copies, and the originals are
+  // still in the plugin's own directory. Nothing a user made is in there.
+  await unpublishAssets(appName);
+  await step(steps, onStep, 'tables and data: untouched (published assets removed)');
   return { ok: true, appName, steps };
 }
 

src/servers/plugins/manifest.ts

@@ -97,8 +97,11 @@ export type PluginManifest = {
 
   label: string;
   summary: string;
-  /** A lucide icon name, resolved at render. */
-  icon: string;
+  /**
+   * A lucide icon name, resolved at render — the FALLBACK, used only when the plugin ships no
+   * `assets/icon.png`. Optional for that reason: a plugin with its own artwork has nothing to say here.
+   */
+  icon?: string;
   /** Tile colour. */
   color: string;
 
@@ -128,6 +131,14 @@ export type DiscoveredPlugin = {
   dir: string;
   manifest: PluginManifest;
 
+  /**
+   * `assets/icon.png` — the dock tile's image, published to `public/plugins/<appName>/` on install.
+   *
+   * Null means the plugin ships none and falls back to `manifest.icon`, a lucide NAME. The file wins
+   * because it has no ceiling: `resolveIcon` knows 106 glyphs out of lucide's ~1,500, and a plugin
+   * naming one outside that set silently renders a neutral box.
+   */
+  icon: string | null;
   /** `api/router.ts` — a backend router, mounted at `mountPrefix`. */
   api: string | null;
   /** `db/schema.ts` — tables, pushed on install. Every name must be prefixed `<appName>_`. */
@@ -250,7 +261,7 @@ export function manifestProblems(appName: string, manifest: Partial<PluginManife
   if (typeof manifest.publisher !== 'string' || !PUBLISHER_RE.test(manifest.publisher)) {
     problems.push('publisher must be lowercase letters, digits and dashes');
   }
-  for (const field of ['version', 'platform', 'label', 'summary', 'icon', 'color'] as const) {
+  for (const field of ['version', 'platform', 'label', 'summary', 'color'] as const) {
     if (typeof manifest[field] !== 'string' || !manifest[field]) problems.push(`${field} is required`);
   }
   if (!Array.isArray(manifest.permissions)) {

src/servers/plugins/mount.ts

@@ -5,6 +5,7 @@ import { setPluginPermissions, type Capability } from '../capabilities/registry'
 import { discoverPlugins } from './discover';
 import { mountPrefix, type DiscoveredPlugin } from './manifest';
 import { generatePluginsModule, rebuildFrontend } from './generate';
+import { iconUrl } from '../app-store/assets';
 
 // Turning what is on disk plus what is in the database into a mounted application.
 //
@@ -182,6 +183,7 @@ export async function pluginDockManifests(): Promise<
     capability: string | null;
     name: string;
     icon?: string;
+    image?: string;
     color: string;
     rootRoute: string;
     routes: string[];
@@ -196,7 +198,10 @@ export async function pluginDockManifests(): Promise<
         sidecarId: plugin.appName,
         capability: plugin.manifest.permissions[0]?.key ?? null,
         name: plugin.manifest.label,
-        icon: plugin.manifest.icon,
+        // A shipped `assets/icon.png` wins; the lucide NAME is the fallback for a plugin with no
+        // artwork of its own. The dock renders `image` as an <img> and `icon` through `resolveIcon`,
+        // and it already preferred the image — this is the first thing to give it one.
+        ...(plugin.icon ? { image: iconUrl(plugin.appName) } : { icon: plugin.manifest.icon }),
         color: plugin.manifest.color,
         rootRoute: prefix,
         routes: [prefix],

src/workspaces/officerdev/src/apps/Plugins/PluginDetail.tsx

@@ -120,8 +120,13 @@ export const PluginDetail = () => {
 
   return (
     <div className="h-full overflow-auto p-6">
+      <div className="flex items-center gap-3">
+        {plugin.image ? <img src={plugin.image} alt="" className="h-10 w-10 shrink-0 object-contain" /> : null}
+        <div className="min-w-0">
           <h2 className="text-lg font-semibold text-duck-dark">{plugin.label}</h2>
-      <p className="mt-1 text-sm text-duck-dark/60">{plugin.summary}</p>
+          <p className="mt-0.5 text-sm text-duck-dark/60">{plugin.summary}</p>
+        </div>
+      </div>
 
       <div className="mt-5 border-t border-duck-dark/10 pt-4">
         <Row label="Mounts at">

src/workspaces/officerdev/src/apps/Plugins/PluginsList.tsx

@@ -38,7 +38,13 @@ export const PluginsList = () => {
             selected === plugin.appName ? 'bg-duck-teal/10' : 'hover:bg-duck-dark/5'
           }`}
         >
+          {/* The plugin's own artwork when it ships some and is installed; otherwise the generic glyph
+              this drew for everything before plugins could carry an icon. */}
+          {plugin.image ? (
+            <img src={plugin.image} alt="" className="h-5 w-5 shrink-0 object-contain" />
+          ) : (
             <Puzzle className="h-4 w-4 shrink-0" style={{ color: plugin.color }} />
+          )}
           <div className="min-w-0 flex-1">
             <div className="truncate text-sm font-medium text-duck-dark">{plugin.label}</div>
             <div className="truncate text-xs text-duck-dark/50">{plugin.prefix}</div>

src/workspaces/officerdev/src/apps/Plugins/usePlugins.ts

@@ -46,7 +46,10 @@ export type PluginItem = {
   prefix: string;
   label: string;
   summary: string;
-  icon: string;
+  /** A lucide NAME, and only when the plugin ships no artwork of its own. */
+  icon?: string;
+  /** The plugin's own `assets/icon.png`, served from `/plugins/<appName>/`. Present only while installed. */
+  image?: string;
   color: string;
   publisher: string;
   version: string;