themes are installable, like plugins

`platform/themes/<id>/` — untracked, same rule as `plugins/`, only the instructions
tracked. Drop a directory in and the theme appears in the picker on the next page load.

  themes/my-theme/theme.css     required — `[data-theme='my-theme'] { … }`
  themes/my-theme/theme.json    required — { name, family, dark }
  themes/my-theme/assets/       optional — wallpaper, logo

── Why this is cheaper than installing a plugin ──

A plugin is code: it needs a manifest module, mounting, and a frontend rebuild to reach
the bundler. A theme is a block of CSS custom properties, so it needs none of that. The
server reads the directory at request time and the client adds a `<link>`. No install
step, no rebuild, no restart — which is the whole reason this is eighty lines of
discovery rather than four hundred.

The id is the DIRECTORY NAME, not a manifest field, for the same reason a plugin's
`appName` is not one: an id that can disagree with where its files sit eventually will.
Discovery checks that the CSS actually targets its own directory name, because the
failure is otherwise silent — the theme appears, is selected, and nothing changes.

── Problems are reported, not swallowed ──

A malformed theme returns a reason rather than vanishing:

  broken-probe: theme.css does not target [data-theme='broken-probe']

The client logs those, so an author has somewhere to look instead of wondering why
their theme never appeared.

── Boundaries kept ──

The `theme` package still performs no IO. It gained an `extraThemes` prop; Officer
fetches and injects, exactly as it supplies the panel registry to `workspaces`. A
failure to fetch is not an error — no server, no session, no directory all mean "you get
the built-in themes", which is a complete product.

`/api/themes` is a `core` capability: read-only, and not deniable, because an account
that cannot read the theme list renders unstyled. Installing remains a directory on
disk; an upload endpoint would be a way to write arbitrary CSS into the page from a
request.

Verified in-process: listing, the problem report, CSS served as text/css, and a
traversal attempt answered 404.

── Needs a restart ──

Server-side change. Until then the client's fetch 404s and silently keeps the built-ins,
so nothing breaks in the meantime.

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

.gitignore

@@ -107,3 +107,8 @@ src/databases/officer_db/migrations/
 
 # Visual baselines for the theme extraction — large, machine-specific, regenerate with scripts/theme-snapshot.ts
 .snapshots/
+
+# Installed themes, same rule as plugins: a theme is somebody's own work dropped into this directory, not
+# this repository's content. Only the instructions are tracked.
+themes/*
+!themes/*.md

src/apps/officer-web/frontend.tsx

@@ -5,7 +5,7 @@ import { App } from './App';
 import { seedAppRegistry, seedWidgetRegistry } from 'officerdev';
 import { plugins } from './Plugins.gen';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { ColorModeProvider } from '@/components/ui/ThemeProvider';
+import { InstalledThemes } from '@/state/InstalledThemes';
 import { I18nBridge } from '@/lib/I18nBridge';
 import { Toaster as Sonner } from 'sonner';
 import { TooltipProvider } from '@/components/ui/tooltip';
@@ -32,14 +32,14 @@ const elem = document.getElementById('root')!;
 const app = (
   <StrictMode>
     <QueryClientProvider client={queryClient}>
-      <ColorModeProvider>
+      <InstalledThemes>
         <I18nBridge>
           <TooltipProvider>
             <Sonner position="top-center" toastOptions={{ style: { padding: '16px 20px', fontSize: '16px' } }} />
             <App />
           </TooltipProvider>
         </I18nBridge>
-      </ColorModeProvider>
+      </InstalledThemes>
     </QueryClientProvider>
   </StrictMode>
 );

src/apps/officer-web/state/InstalledThemes.tsx

@@ -0,0 +1,80 @@
+import type { ReactNode } from 'react';
+import { useEffect, useState } from 'react';
+import { ThemeProvider, type Theme } from '@/components/ui/ThemeProvider';
+
+/**
+ * Themes installed on this machine, folded in beside the ones this build ships.
+ *
+ * `platform/themes/<id>/` — untracked, like `plugins/` — holds a `theme.css` and a `theme.json`. This asks
+ * the server what is there, injects each stylesheet, and hands the list to the provider so they appear in
+ * the picker and under the keyboard shortcuts.
+ *
+ * ── Why no rebuild is needed ──
+ *
+ * A plugin is code and has to reach the bundler. A theme is a block of CSS custom properties, so it can be
+ * a `<link>` added at runtime — drop a directory in, reload, it is there. That difference is the whole
+ * reason installing a theme is cheaper than installing a plugin.
+ *
+ * ── Why the fetch lives here and not in the package ──
+ *
+ * The `theme` package performs no IO, for the same reason `workspaces` does not: it has to work for a host
+ * that has no server. Officer knows it has one, so Officer asks.
+ *
+ * A failure is not an error. No server, no session, no themes directory — all of them mean "you get the
+ * built-in themes", which is a complete product.
+ */
+
+type InstalledTheme = { id: string; name: string; family: string; dark: boolean };
+
+const STYLESHEET_ID = (id: string) => `officer-theme-${id}`;
+
+export const InstalledThemes = ({ children }: { children: ReactNode }) => {
+  const [installed, setInstalled] = useState<Theme[]>([]);
+
+  useEffect(() => {
+    let alive = true;
+
+    const load = async () => {
+      let payload: { themes?: InstalledTheme[]; problems?: { id: string; problem: string }[] };
+      try {
+        // The same token `useClient` uses. Read directly because this runs above the app's providers.
+        const token =
+          localStorage.getItem('PERTENTO_EDITOR_AUTH_TOKEN') ||
+          localStorage.getItem('BEARER_TOKEN') ||
+          sessionStorage.getItem('BEARER_TOKEN');
+        const headers: Record<string, string> = token ? { authorization: `Bearer ${token}` } : {};
+
+        const res = await fetch('/api/themes', { headers });
+        if (!res.ok) return;
+        payload = await res.json();
+      } catch {
+        return; // Offline, signed out, or no server. The built-ins are enough.
+      }
+      if (!alive || !payload.themes?.length) return;
+
+      // Loud about a theme that nearly works: a typo in theme.json otherwise just means it never appears,
+      // and the author has nowhere to look.
+      for (const p of payload.problems ?? []) {
+        console.warn(`[themes] ${p.id}: ${p.problem}`);
+      }
+
+      for (const theme of payload.themes) {
+        if (document.getElementById(STYLESHEET_ID(theme.id))) continue;
+        const link = document.createElement('link');
+        link.id = STYLESHEET_ID(theme.id);
+        link.rel = 'stylesheet';
+        link.href = `/api/themes/${theme.id}/theme.css`;
+        document.head.appendChild(link);
+      }
+
+      setInstalled(payload.themes.map((t) => ({ id: t.id, name: t.name, family: t.family, applyDarkClass: t.dark })));
+    };
+
+    void load();
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  return <ThemeProvider extraThemes={installed}>{children}</ThemeProvider>;
+};

src/servers/api/themes/themes.ts

@@ -0,0 +1,41 @@
+import type { Context } from 'hono';
+import { createRouter } from '../../create-router';
+import { discoverThemes, readThemeCss } from '../../themes/discover';
+
+/**
+ * Installed themes — the ones in `platform/themes/`, not the ones the platform ships.
+ *
+ * The shipped themes are compiled into the bundle and need no server. These are read off disk at request
+ * time, so dropping a directory in makes a theme appear on the next page load. No install step, no
+ * rebuild, no restart — a theme is CSS custom properties, and none of that needs compiling.
+ *
+ * Read-only on purpose. Installing a theme is `git clone` into a directory, exactly as it is for plugins;
+ * an upload endpoint would be a way to write arbitrary CSS into the page from a request, which is a worse
+ * trade than a shell command.
+ */
+export const themesRouter = createRouter();
+
+// GET /themes — what is installed, and what is nearly installed.
+//
+// `problems` is returned rather than swallowed: a theme with a typo in its JSON otherwise just fails to
+// appear, and the author has nowhere to look. The app store can render these.
+themesRouter.get('/', async (ctx: Context) => {
+  const { themes, problems } = discoverThemes();
+  return ctx.json({ themes, problems });
+});
+
+// GET /themes/:id/theme.css — the stylesheet, injected by the client as a <link>.
+//
+// Served as CSS rather than embedded in the JSON above so the browser caches it, and so a theme with a
+// syntax error breaks only itself rather than the payload that lists every theme.
+themesRouter.get('/:id/theme.css', async (ctx: Context) => {
+  const css = readThemeCss(ctx.req.param('id'));
+  if (css === null) return ctx.text('/* no such theme */', 404, { 'content-type': 'text/css; charset=utf-8' });
+
+  return ctx.body(css, 200, {
+    'content-type': 'text/css; charset=utf-8',
+    // Short, because editing a theme and reloading is the whole authoring loop. Long enough that a page
+    // load does not refetch fourteen stylesheets.
+    'cache-control': 'public, max-age=60',
+  });
+});

src/servers/hono.ts

@@ -5,6 +5,7 @@ import type { HonoVariables } from './create-router';
 import { authRouter } from './api/auth';
 import { serverSettingsRouter } from './api/server-settings/server-settings';
 import { landingPageDataRouter } from './api/landing-page-data/landing-page-data';
+import { themesRouter } from './api/themes/themes';
 import { waitlistRouter } from './api/waitlist/waitlist';
 import { usersRouter } from './api/users/users-router';
 import { apiKeysRouter } from './api/api-keys/router';
@@ -198,6 +199,7 @@ export function buildHonoApp(plugins: MountedPlugin[] = []): Hono<{ Variables: H
   app.get('/api', (ctx) => ctx.json({ officerAPI: 'ok' }));
   app.route('/api/auth', authRouter);
   app.route('/api/landing-page-data', landingPageDataRouter);
+  app.route('/api/themes', themesRouter);
   app.route('/api/waitlist', waitlistRouter);
   // Vaultwarden reverse-proxy — mounted TOP-LEVEL (not under protectedRouter): the Bitwarden client
   // carries its own bearer token, not a platform session JWT, so userMiddleware would 401 it. The

src/servers/permissions/registry.ts

@@ -123,6 +123,17 @@ const CORE_REGISTRY: Permission[] = [
     api: ['/user', '/dock', '/api-keys'],
     routes: ['/settings/profile'],
   },
+  {
+    key: 'themes',
+    label: 'Themes',
+    description: 'Read the themes installed on this machine',
+    // `core`, and not deniable. Themes are how the interface looks; an account that could not read the
+    // list would render unstyled, which is not a permission decision anyone means to make. It is read-only
+    // — installing a theme is a directory on disk, not a request.
+    kind: 'core',
+    api: ['/themes'],
+    routes: [],
+  },
   {
     key: 'bug-report',
     label: 'Report a problem',

src/servers/themes/discover.ts

@@ -0,0 +1,128 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { PLATFORM_DIR } from '../data-path';
+
+/**
+ * Themes installed on this machine, as opposed to the ones the platform ships.
+ *
+ * ── Why this is simpler than plugin discovery ──
+ *
+ * A plugin is code: it has a manifest module, routers, tables, a sidecar, panels, and the platform has to
+ * import and mount it. A theme is a block of CSS custom properties. Nothing to import, nothing to mount,
+ * nothing to bundle — which is why an installed theme takes effect without a frontend rebuild, and why
+ * this file is eighty lines rather than four hundred.
+ *
+ * Discovery is by CONVENTION, the same as plugins. Presence is the declaration:
+ *
+ *   themes/<id>/theme.css     required — `[data-theme='<id>'] { … }`
+ *   themes/<id>/theme.json    required — the name a person sees, and how to group it
+ *   themes/<id>/assets/       optional — a wallpaper, a logo; served at /themes/<id>/assets/…
+ *
+ * The id is the DIRECTORY NAME and is not declared in the manifest, for the reason `appName` is not
+ * declared in a plugin's: an id that can disagree with where the files sit eventually will.
+ *
+ * ── What this does not do ──
+ *
+ * It answers "what is on disk". It does not read the database, validate colour values, or care whether a
+ * theme is any good. A theme whose CSS is nonsense will simply look wrong, which is the author's business
+ * and is visible immediately.
+ */
+
+/** Where installed themes live. Sibling of `plugins/`, and gitignored the same way. */
+export const THEMES_DIR = join(PLATFORM_DIR, 'themes');
+
+export type InstalledTheme = {
+  /** The directory name. Also the `data-theme` value its CSS must target. */
+  id: string;
+  name: string;
+  family: string;
+  /**
+   * Whether to put `.dark` on the document alongside `data-theme`.
+   *
+   * A compatibility flag, not a description: several hundred `dark:` utilities are still written into
+   * components and resolve against that class. A dark theme wants it.
+   */
+  dark: boolean;
+};
+
+export type ThemeProblem = { id: string; problem: string };
+
+const isDir = (path: string): boolean => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Read one directory as a theme, or say why it is not one.
+ *
+ * Returns problems rather than throwing, and never stops the scan: one malformed theme must not hide the
+ * eleven good ones next to it. The problems are reported so the app store can render them, which is the
+ * same posture `discoverPlugins` takes.
+ */
+function readTheme(id: string): InstalledTheme | ThemeProblem {
+  const dir = join(THEMES_DIR, id);
+  const cssPath = join(dir, 'theme.css');
+  const manifestPath = join(dir, 'theme.json');
+
+  if (!existsSync(cssPath)) return { id, problem: 'no theme.css' };
+  if (!existsSync(manifestPath)) return { id, problem: 'no theme.json' };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch (err) {
+    return { id, problem: `theme.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  const manifest = parsed as { name?: unknown; family?: unknown; dark?: unknown };
+  if (typeof manifest.name !== 'string' || !manifest.name.trim()) return { id, problem: 'theme.json needs a "name"' };
+
+  /*
+    The CSS must target its own directory name.
+
+    Checked because the failure is otherwise silent and baffling: the theme appears in the picker, is
+    selected, and nothing changes — because its rules are scoped to a `data-theme` value nobody sets.
+  */
+  const css = readFileSync(cssPath, 'utf-8');
+  if (!css.includes(`[data-theme='${id}']`) && !css.includes(`[data-theme="${id}"]`)) {
+    return { id, problem: `theme.css does not target [data-theme='${id}'] — it must match the directory name` };
+  }
+
+  return {
+    id,
+    name: manifest.name,
+    family: typeof manifest.family === 'string' && manifest.family.trim() ? manifest.family : manifest.name,
+    dark: manifest.dark === true,
+  };
+}
+
+export function discoverThemes(): { themes: InstalledTheme[]; problems: ThemeProblem[] } {
+  if (!existsSync(THEMES_DIR)) return { themes: [], problems: [] };
+
+  const themes: InstalledTheme[] = [];
+  const problems: ThemeProblem[] = [];
+
+  for (const id of readdirSync(THEMES_DIR).sort()) {
+    if (id.startsWith('.') || !isDir(join(THEMES_DIR, id))) continue;
+    const result = readTheme(id);
+    if ('problem' in result) problems.push(result);
+    else themes.push(result);
+  }
+
+  return { themes, problems };
+}
+
+/** The CSS of one installed theme, or null. `id` is validated, so it cannot climb out of the directory. */
+export function readThemeCss(id: string): string | null {
+  if (!/^[a-z0-9][a-z0-9-]*$/i.test(id)) return null;
+  const path = join(THEMES_DIR, id, 'theme.css');
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}

src/workspaces/theme/src/ThemeProvider.tsx

@@ -60,10 +60,30 @@ function initialTheme(): ThemeId {
   return DEFAULT_THEME;
 }
 
-export const ThemeProvider = ({ children }: { children: ReactNode }) => {
+export type ThemeProviderProps = {
+  children: ReactNode;
+  /**
+   * Themes installed on the machine, discovered at runtime and merged with the ones this build ships.
+   *
+   * The package does no IO — the host fetches them and injects their stylesheets, exactly as it supplies
+   * the panel registry to `workspaces`. All this needs is their names, so it can list them and so
+   * `isKnownTheme` stops rejecting a perfectly real theme it has never heard of.
+   */
+  extraThemes?: readonly Theme[];
+};
+
+export const ThemeProvider = ({ children, extraThemes }: ThemeProviderProps) => {
   const [themeId, setThemeId] = useState<ThemeId>(initialTheme);
 
-  const theme = useMemo(() => findTheme(themeId) ?? findTheme(DEFAULT_THEME)!, [themeId]);
+  // Shipped first, installed second: a local theme may deliberately replace one of ours by using its id.
+  const all = useMemo<readonly Theme[]>(() => {
+    if (!extraThemes?.length) return THEMES;
+    const byId = new Map(THEMES.map((t) => [t.id, t]));
+    for (const t of extraThemes) byId.set(t.id, t);
+    return [...byId.values()];
+  }, [extraThemes]);
+
+  const theme = useMemo(() => all.find((t) => t.id === themeId) ?? findTheme(DEFAULT_THEME)!, [all, themeId]);
 
   useEffect(() => {
     const root = document.documentElement;
@@ -74,19 +94,23 @@ export const ThemeProvider = ({ children }: { children: ReactNode }) => {
     root.style.colorScheme = theme.applyDarkClass ? 'dark' : 'light';
   }, [theme]);
 
-  const setTheme = useCallback((id: ThemeId) => {
-    if (!isKnownTheme(id)) return;
+  const setTheme = useCallback(
+    (id: ThemeId) => {
+      // Against the MERGED list, not the shipped one: an installed theme is as real as a built-in.
+      if (!all.some((t) => t.id === id)) return;
       setThemeId(id);
       try {
         window.localStorage.setItem(STORAGE_KEY, id);
       } catch {
         // Not fatal: the theme still applies for this session, it just will not survive a reload.
       }
-  }, []);
+    },
+    [all],
+  );
 
   const value = useMemo<ThemeContextValue>(
-    () => ({ theme, themeId: theme.id, setTheme, themes: THEMES }),
-    [theme, setTheme],
+    () => ({ theme, themeId: theme.id, setTheme, themes: all }),
+    [theme, setTheme, all],
   );
 
   return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;

themes/CLAUDE.md

@@ -0,0 +1,118 @@
+# Themes
+
+Drop a theme in here and it appears in the picker on the next page load. No install step, no rebuild, no
+restart — a theme is a block of CSS custom properties, and none of that needs compiling.
+
+**This directory is untracked**, exactly like `plugins/`. Only this file is in the repository. Your themes
+are yours; the platform's own live in `src/workspaces/theme/css/themes/`.
+
+---
+
+## The shape
+
+```
+themes/
+  my-theme/
+    theme.css     required — the values
+    theme.json    required — the name a person reads
+    assets/       optional — a wallpaper, a logo
+```
+
+The directory name **is** the theme's id. It is not repeated in the manifest, because an id that can
+disagree with where its files sit eventually will.
+
+### `theme.json`
+
+```json
+{
+  "name": "My Theme",
+  "family": "My Theme",
+  "dark": true
+}
+```
+
+| | |
+|---|---|
+| `name` | required — what the picker shows |
+| `family` | optional — groups variants together, like `Duck Light` and `Duck Dark`. Defaults to `name` |
+| `dark` | optional — adds the `.dark` class. Set it for a dark theme; several hundred `dark:` utilities still resolve against it |
+
+### `theme.css`
+
+Must target its own directory name, or nothing will happen and it will be baffling:
+
+```css
+[data-theme='my-theme'] {
+  --background: #1e1e2e;
+  --foreground: #cdd6f4;
+  /* …the rest */
+}
+```
+
+The server checks this on discovery and reports it rather than letting you wonder.
+
+---
+
+## What to put in it
+
+**Twenty tokens are required.** They are the standard shadcn set, which is what every published palette
+already ships — Tokyo Night, Catppuccin, Gruvbox, Nord all come in this vocabulary, so porting one is
+mostly copy-paste.
+
+```
+background foreground · card card-foreground · popover popover-foreground
+primary primary-foreground · secondary secondary-foreground
+muted muted-foreground · accent accent-foreground
+destructive destructive-foreground · border input ring · radius
+```
+
+**Everything else is derived from those.** Panels, the header, the dock, glass, grid lines, scrollbars —
+all computed from `card`, `border`, `background` and `foreground`. A palette theme never mentions them.
+
+**Four more are worth setting**, because the standard set has no notion of them and the defaults are
+generic: `--success`, `--warning`, `--info`, `--busy`, each with a `-foreground`. `busy` means *running*,
+not *warning* — it is what a live job wears.
+
+**Anything else you want to change, you can.** Declaring a variable in your theme beats the derived
+default, because both land on `<html>` and yours is more specific. That is how a theme gets a *texture*
+rather than just a palette:
+
+```css
+[data-theme='my-theme'] {
+  --panel-bg: rgba(255, 255, 255, 0.08);   /* glass instead of a flat card */
+  --panel-blur: 20px;
+  --panel-radius: 0;                        /* square panels */
+  --page-bg-src: '/themes/my-theme/assets/wallpaper.webp';
+  --logo-src: '/themes/my-theme/assets/logo.svg';
+}
+```
+
+The full list of what you can override is in `src/workspaces/theme/README.md`, and
+`src/workspaces/theme/css/themes/duck-dark.css` is a worked example of a textured theme.
+
+**Assets are quoted paths, not `url(...)`.** The bundler resolves `url()` at build time and your files are
+served at runtime, so a `url()` token would break. The app wraps the path for you.
+
+---
+
+## Writing one
+
+Start from `src/workspaces/theme/css/themes/plain.css` rather than from a Duck theme. Plain is white,
+black and grey throughout, so every value you change is one you decided about, with nothing inherited from
+someone else's brand.
+
+Then: reload the page, open the picker or press `ctrl+shift+space`, and use `j`/`k` to browse. `l` applies
+the focused theme to the app behind the list, so you can watch your own theme against real screens.
+
+Editing `theme.css` and reloading is the whole loop. The stylesheet is cached for a minute.
+
+---
+
+## Checking your work
+
+Render the app under **Plain** first if something looks wrong under yours. Anything still coloured under
+Plain is a component painting itself rather than reading a token — that is a platform bug, not yours, and
+worth reporting.
+
+`bun run check:theme` counts hardcoded colours in the platform. It does not check themes, but it is why
+your theme has a chance of working: the number can only go down.