@deckbuilderkit/build 0.0.0-stage → 0.1.1

package/src/release.ts

@@ -0,0 +1,182 @@
+import { copyFileSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { bumpVersion, MANIFEST, MANIFEST_SIG, type ReleaseManifest, type VersionBump } from '@deckbuilderkit/server-core';
+import { type AppDir, workspaceRoot } from './app.ts';
+import { buildExe, buildWeb, releasePrefix, type Target } from './build.ts';
+import { loadSigningKey, signManifest } from './keys.ts';
+
+export const BUMPS: VersionBump[] = ['patch', 'minor', 'major'];
+
+export interface ReleaseOptions {
+  /** Release folder root; files go to `<to>/<app name>/`, where the updater's folderSource looks. */
+  to: string;
+  bump: VersionBump;
+  targets: Target[];
+  /** Publishes the same files, then puts package.json back and leaves git alone. */
+  dryRun: boolean;
+  /** Runs typecheck and tests first. */
+  checks: boolean;
+  /** Publishes without latest.json.sig; builds with an update key then refuse the release. */
+  unsigned: boolean;
+}
+
+/** The app's private signing key; throws without one, unless `unsigned` (then null and a warning). */
+function signingKey(app: AppDir, unsigned: boolean): string | null {
+  if (unsigned) {
+    console.warn(`warning: --unsigned: no ${MANIFEST_SIG}; builds with an update key refuse this release`);
+    return null;
+  }
+  const key = loadSigningKey(app.id);
+  if (!key) throw new Error('No signing key: run `deckbuilder keygen` (or pass --unsigned).');
+  return key;
+}
+
+interface ManifestFiles {
+  /** The exact bytes of latest.json. */
+  bytes: Uint8Array;
+  /** Their signature, or null when unsigned. */
+  sig: string | null;
+}
+
+function manifestFiles(manifest: ReleaseManifest, key: string | null): ManifestFiles {
+  const bytes = new TextEncoder().encode(`${JSON.stringify(manifest, null, 2)}\n`);
+  return { bytes, sig: key ? `${signManifest(bytes, key)}\n` : null };
+}
+
+/** Writes latest.json.sig, or removes a stale one when unsigned. */
+function writeSig(dir: string, sig: string | null): void {
+  if (sig) writeFileSync(join(dir, MANIFEST_SIG), sig);
+  else rmSync(join(dir, MANIFEST_SIG), { force: true });
+}
+
+/** Tags of an app's releases start with its folder name: `gallery-v0.3.0`. */
+const tagPrefix = (app: AppDir): string => `${basename(app.dir)}-v`;
+
+/** Runs git in the workspace root; returns trimmed stdout, throws with stderr on failure. */
+const rootGit =
+  (root: string) =>
+  (args: string[]): string => {
+    const r = Bun.spawnSync(['git', ...args], { cwd: root });
+    if (r.exitCode !== 0) throw new Error(`git ${args.join(' ')}: ${r.stderr.toString().trim()}`);
+    return r.stdout.toString().trim();
+  };
+
+const sha256 = async (path: string): Promise<string> => new Bun.CryptoHasher('sha256').update(await Bun.file(path).arrayBuffer()).digest('hex');
+
+/**
+ * Bumps the version, builds the exes and publishes them with latest.json, then commits the bump
+ * and tags `<app folder>-v<version>` locally. Never pushes.
+ */
+export async function release(app: AppDir, opts: ReleaseOptions): Promise<void> {
+  const root = await workspaceRoot(app.dir);
+  const git = rootGit(root);
+  const sh = (cmd: string[]) => {
+    console.log(`> ${cmd.join(' ')}`);
+    if (Bun.spawnSync(cmd, { cwd: root, stdio: ['ignore', 'inherit', 'inherit'] }).exitCode !== 0) throw new Error(`failed: ${cmd.join(' ')}`);
+  };
+
+  if (!opts.dryRun && git(['status', '--porcelain']) !== '') {
+    throw new Error('Commit or stash your changes first: the release is built from HEAD and tagged.');
+  }
+  const version = bumpVersion(app.version, opts.bump);
+  const prefix = tagPrefix(app);
+  const tag = `${prefix}${version}`;
+  if (git(['tag', '--list', tag]) !== '') throw new Error(`Tag ${tag} already exists.`);
+  const key = signingKey(app, opts.unsigned);
+  const notes = releaseNotes(git, prefix, version);
+
+  const pkgPath = join(app.dir, 'package.json');
+  const pkgText = readFileSync(pkgPath, 'utf8');
+  // The exe reads its version from package.json, so even a dry run builds with the bump.
+  writeFileSync(pkgPath, pkgText.replace(`"version": "${app.version}"`, `"version": "${version}"`));
+  try {
+    if (opts.checks) {
+      sh(['bun', 'run', 'typecheck']);
+      sh(['bun', 'test']);
+    }
+    const next = { ...app, version };
+    buildWeb(next);
+    const exes: string[] = [];
+    for (const target of opts.targets) exes.push(await buildExe(next, target));
+    const manifest = await buildManifest(next, exes, notes);
+    const dest = join(opts.to, app.name);
+    await publish(exes, dest, manifest, manifestFiles(manifest, key));
+    console.log(`published ${tag} to ${dest}`);
+  } catch (e) {
+    writeFileSync(pkgPath, pkgText);
+    throw e;
+  }
+
+  if (opts.dryRun) {
+    writeFileSync(pkgPath, pkgText);
+    console.log(`dry run: package.json stays ${app.version}; no commit, no tag ${tag}`);
+  } else {
+    git(['commit', '-m', `Release ${tag}`, '--', pkgPath]);
+    git(['tag', tag]);
+    console.log(`committed and tagged ${tag}; push it yourself when ready`);
+  }
+}
+
+/** The manifest for built exes named `<name>-<version>-<label>[.exe]`: label and sha256 per file. */
+export async function buildManifest(app: AppDir, exes: string[], notes: string): Promise<ReleaseManifest> {
+  const manifest: ReleaseManifest = { version: app.version, notes, date: new Date().toISOString(), files: {} };
+  const prefix = releasePrefix(app);
+  for (const exe of exes) {
+    const file = basename(exe);
+    if (!file.startsWith(prefix)) throw new Error(`${file} does not start with ${prefix}`);
+    manifest.files[file.slice(prefix.length).replace(/\.exe$/, '')] = { file, sha256: await sha256(exe) };
+  }
+  return manifest;
+}
+
+/**
+ * `deckbuilder manifest`: writes release/latest.json for the exes of the current version, with
+ * notes since the previous release tag (what the release workflow uploads next to the exes).
+ */
+export async function writeManifest(app: AppDir, unsigned: boolean): Promise<void> {
+  const key = signingKey(app, unsigned);
+  const dir = join(app.dir, 'release');
+  const prefix = releasePrefix(app);
+  const exes = readdirSync(dir)
+    .filter((f) => f.startsWith(prefix))
+    .map((f) => join(dir, f));
+  if (exes.length === 0) throw new Error(`No ${prefix}* files in ${dir}; run build first.`);
+  const git = rootGit(await workspaceRoot(app.dir));
+  const manifest = await buildManifest(app, exes, releaseNotes(git, tagPrefix(app), app.version));
+  const { bytes, sig } = manifestFiles(manifest, key);
+  writeSig(dir, sig);
+  writeFileSync(join(dir, MANIFEST), bytes);
+  console.log(`wrote ${join(dir, MANIFEST)}${sig ? ` and ${MANIFEST_SIG}` : ''} (${Object.keys(manifest.files).join(', ')})`);
+}
+
+/** Commit summaries since the app's last release tag, one `- ` line each. */
+export function releaseNotes(git: (args: string[]) => string, prefix: string, version: string): string {
+  let since: string;
+  try {
+    since = git(['describe', '--tags', '--abbrev=0', '--match', `${prefix}*`, '--exclude', `${prefix}${version}`]);
+  } catch {
+    return '- First release';
+  }
+  const lines = git(['log', '--format=%s', `${since}..HEAD`])
+    .split('\n')
+    .filter((s) => s && !s.startsWith('Release '));
+  return lines.length > 0 ? lines.map((s) => `- ${s}`).join('\n') : '- Maintenance release';
+}
+
+/**
+ * Copies the exes, then writes latest.json last and atomically, after every copy is verified. Its
+ * signature goes in first, so a reader never sees a new manifest without it.
+ */
+async function publish(exes: string[], dest: string, manifest: ReleaseManifest, { bytes, sig }: ManifestFiles): Promise<void> {
+  mkdirSync(dest, { recursive: true });
+  for (const exe of exes) {
+    const entry = Object.values(manifest.files).find((f) => f.file === basename(exe))!;
+    const target = join(dest, entry.file);
+    copyFileSync(exe, target);
+    if ((await sha256(target)) !== entry.sha256) throw new Error(`${target} does not match the built exe after copying`);
+  }
+  writeSig(dest, sig);
+  const tmp = join(dest, `${MANIFEST}.tmp`);
+  writeFileSync(tmp, bytes);
+  renameSync(tmp, join(dest, MANIFEST));
+}

package/template/app.ts

@@ -0,0 +1,10 @@
+import type { AppIdentity } from '@deckbuilderkit/server-core/protocol';
+
+/**
+ * Identity of the app, shared by the server, the build and the web UI.
+ * When starting a new app from this one, change these first (see README "New app").
+ */
+export const APP: AppIdentity = {
+  name: '__APP_NAME__',
+  id: '__APP_ID__',
+};

package/template/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@deckbuilderkit/__APP_DIR__",
+  "version": "0.1.0",
+  "description": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "deckbuilder dev",
+    "dev:window": "deckbuilder dev --window",
+    "start": "bun server/main.ts",
+    "start:browser": "bun server/main.ts --browser",
+    "build:web": "deckbuilder build:web",
+    "build": "deckbuilder build"
+  },
+  "dependencies": {
+    "@deckbuilderkit/platform": "workspace:*",
+    "@deckbuilderkit/server-core": "workspace:*",
+    "@deckbuilderkit/server-mods": "workspace:*",
+    "@deckbuilderkit/shell": "workspace:*",
+    "@deckbuilderkit/ui": "workspace:*",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@deckbuilderkit/build": "workspace:*",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^6.0.3"
+  }
+}

package/template/server/main.ts

@@ -0,0 +1,95 @@
+import { join } from 'node:path';
+import { appHome, createAutostart, pickFolder } from '@deckbuilderkit/platform';
+import { updatePublicKey } from '@deckbuilderkit/server-core';
+import {
+  createUpdater,
+  folderSource,
+  fromPlatform,
+  githubSource,
+  infoRoutes,
+  pickedPaths,
+  settingsRoutes,
+  settingsStore,
+  themeHead,
+  updateRoutes,
+  type BaseSettings,
+} from '@deckbuilderkit/server-mods';
+import { runApp } from '@deckbuilderkit/shell';
+import { type Keymap, validKeymap } from '@deckbuilderkit/ui/keybindings';
+import { APP } from '../app.ts';
+import pkg from '../package.json';
+import { routes } from './routes.ts';
+
+export interface Settings extends BaseSettings {
+  /** Keybinding overrides by command id, checked by `validKeymap`. */
+  keybindings?: Keymap;
+  /** Start at Windows login (exe only). */
+  autostart: boolean;
+  /** Tray icon, so closing the window keeps the app running; read at startup. */
+  closeToTray: boolean;
+  /**
+   * Folder `deckbuilder release --to` publishes to; empty: GitHub releases when `APP.repo` is set,
+   * else no update checks. Set only through the folder dialog of `POST /api/settings/update-folder`.
+   */
+  updateFolder: string;
+}
+
+const dataDir = appHome(APP.id);
+const autostart = createAutostart({ name: APP.name });
+/** The folder the update-folder dialog returned; `apply` takes it once. */
+const pickedUpdateFolder = pickedPaths({ max: 1 });
+const settings = settingsStore<Settings>({
+  dir: dataDir,
+  defaults: { theme: 'dark', autostart: false, closeToTray: false, updateFolder: '' },
+  apply(patch, next) {
+    if (typeof patch.autostart === 'boolean') next.autostart = patch.autostart;
+    if (typeof patch.closeToTray === 'boolean') next.closeToTray = patch.closeToTray;
+    // A client may only clear it: a typed path could be any UNC share.
+    if (patch.updateFolder === '' || (typeof patch.updateFolder === 'string' && pickedUpdateFolder.take(patch.updateFolder))) {
+      next.updateFolder = patch.updateFolder;
+    }
+    const keybindings = validKeymap(patch.keybindings);
+    if (keybindings) next.keybindings = keybindings;
+  },
+  onChange(next, prev) {
+    if (next.autostart !== prev.autostart) void autostart.set(next.autostart);
+    if (next.updateFolder !== prev.updateFolder) void updater.check();
+  },
+});
+const updater = createUpdater({
+  version: pkg.version,
+  publicKey: updatePublicKey(join(import.meta.dir, '..', 'update-key.pub')),
+  source: async () => {
+    const { updateFolder } = await settings.load();
+    if (updateFolder) return folderSource(updateFolder, { subfolder: APP.name });
+    return APP.repo ? githubSource({ repo: APP.repo, tagPrefix: '__APP_DIR__-v' }) : null;
+  },
+});
+
+const { closeToTray } = await settings.load();
+
+await runApp({
+  app: APP,
+  routes: (ctx) => ({
+    ...infoRoutes({ app: APP, version: pkg.version, dataDir }),
+    ...settingsRoutes(settings),
+    'POST /api/settings/update-folder': async ({ json }) => {
+      const { title } = await json<{ title?: unknown }>();
+      const path = await pickFolder({ title: typeof title === 'string' ? title : undefined }).catch(fromPlatform);
+      if (path === null) return settings.load();
+      pickedUpdateFolder.add(path);
+      return settings.save({ updateFolder: path });
+    },
+    ...updateRoutes(updater, ctx.quit),
+    ...routes(ctx),
+  }),
+  webDir: join(import.meta.dir, '../dist/web'),
+  transformIndex: themeHead(settings),
+  urlProtocol: true,
+  tray: closeToTray,
+  async onStart() {
+    updater.start();
+    // Repairs the Run entry after the exe moved.
+    if ((await settings.load()).autostart) await autostart.fixUp();
+  },
+});

package/template/server/routes.ts

@@ -0,0 +1,10 @@
+import type { Routes } from '@deckbuilderkit/server-core';
+import type { StartContext } from '@deckbuilderkit/shell';
+
+/**
+ * This app's own endpoints. Keys are "METHOD /path"; handlers return a JSON-serializable value
+ * or throw an AppError (`invalid`, `notFound`) that the UI shows translated as `error.<code>`.
+ */
+export const routes = (_ctx: StartContext): Routes => ({
+  // 'GET /api/things': async () => [],
+});

package/template/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "lib": ["ESNext"], "types": ["bun"] },
+  "include": ["app.ts", "server", "vite.config.ts"]
+}

package/template/vite.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { DEV_PORT } from '@deckbuilderkit/server-core/protocol';
+
+// Dev: `deckbuilder dev` runs the server on DEV_PORT; Vite proxies the API there. changeOrigin
+// stays false: the server's Origin check needs the browser's Origin and Host.
+export default defineConfig({
+  root: 'web',
+  plugins: [react()],
+  build: {
+    outDir: '../dist/web',
+    emptyOutDir: true,
+  },
+  server: {
+    proxy: {
+      // ws: the terminal socket lives under /api
+      '/api': { target: `http://127.0.0.1:${DEV_PORT}`, changeOrigin: false, ws: true },
+    },
+  },
+});

package/template/web/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" data-theme="dark" data-layout="original">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__APP_NAME__</title>
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/web/public/favicon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32">
+  <rect width="32" height="32" rx="7" fill="#120d2b"/>
+  <g transform="translate(4 4) scale(.75)">
+    <rect x="12" y="3" width="17" height="19" rx="3.5" fill="#9b8cff" fill-opacity=".4"/>
+    <rect x="7.5" y="7" width="17" height="19" rx="3.5" fill="#120d2b" stroke="#120d2b" stroke-width="4"/>
+    <rect x="7.5" y="7" width="17" height="19" rx="3.5" fill="#9b8cff" fill-opacity=".7"/>
+    <rect x="3" y="11" width="17" height="19" rx="3.5" fill="#120d2b" stroke="#120d2b" stroke-width="4"/>
+    <rect x="3" y="11" width="17" height="19" rx="3.5" fill="#9b8cff"/>
+  </g>
+</svg>

package/template/web/src/App.tsx

@@ -0,0 +1,187 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { PALETTES } from '@deckbuilderkit/server-core/palettes';
+import { AppFrame, type CommandDef, CommandPalette, detectLanguage, effectiveKeys, ErrorBanner, GLOBAL, Icon, type IconName, isDesktop, KeybindingProvider, LayoutProvider, paletteCommand, type PaletteItem, setLanguage, Sidebar, Spinner, useAsync, useCommand, useCommandPalette, useHashRoute, useHeartbeat, useKeybindings, useTheme, useZoom } from '@deckbuilderkit/ui';
+import { APP } from '../../app';
+import { api, type Settings } from './api';
+import { type MessageKey, t } from './i18n';
+import { Home } from './screens/Home';
+import { SettingsModal } from './screens/SettingsModal';
+
+const SCREENS = ['home'] as const;
+type ScreenId = (typeof SCREENS)[number];
+
+const NAV: Array<{ title: MessageKey; items: Array<{ id: ScreenId; label: MessageKey; icon: IconName }> }> = [
+  {
+    title: 'nav.section.main',
+    items: [
+      { id: 'home', label: 'nav.home', icon: 'home' },
+    ],
+  },
+];
+
+const navCommandId = (screen: ScreenId) => `nav.${screen}`;
+const SETTINGS_COMMAND = 'app.settings';
+const KEYS_COMMAND = 'app.keybindings';
+
+/** Every shortcut of the app; built at render so the labels follow the language. */
+function commands(): CommandDef[] {
+  const nav = NAV.flatMap((s) => s.items).map((item, i): CommandDef => ({
+    id: navCommandId(item.id), scope: GLOBAL, label: t(item.label), keys: [`Ctrl+${i + 1}`], inInput: true,
+  }));
+  // Settings and keybindings are modals over the screen, not screens; both are VS Code's keys.
+  const overlays: CommandDef[] = [
+    { id: SETTINGS_COMMAND, scope: GLOBAL, label: t('nav.settings'), keys: ['Ctrl+,'], inInput: true },
+    { id: KEYS_COMMAND, scope: GLOBAL, label: t('nav.keys'), keys: ['Ctrl+K Ctrl+S'], inInput: true },
+  ];
+  return [paletteCommand(), ...nav, ...overlays];
+}
+
+// Retrying can't revive a used launch code or a stale token; the user has to open the app again.
+const SESSION_ERRORS = ['invalidCode', 'invalidToken'];
+
+// Settings is a modal over the current screen, not a screen; 'keys' opens it at Keyboard › Shortcuts. App links
+// (toasts, second instances) still open them with `#/settings` and `#/keys`; `#/settings/<section key>` opens a section.
+type Overlay = 'settings' | 'keys' | `settings/${string}`;
+const overlayOfHash = (): Overlay | null => {
+  const m = /^#\/?(settings|keys)(?:\/([\w.-]+))?\/?$/.exec(window.location.hash);
+  if (!m) return null;
+  return m[1] === 'settings' && m[2] ? `settings/${m[2]}` : (m[1] as Overlay);
+};
+
+/** Loads the settings first, so the first paint already has the right theme and language. */
+export function App() {
+  const boot = useAsync(() => api.settings(), []);
+  if (boot.data?.language) setLanguage(boot.data.language);
+
+  if (boot.error) {
+    return <div className="boot"><ErrorBanner error={boot.error} onRetry={SESSION_ERRORS.includes(boot.error.code ?? '') ? undefined : boot.reload} /></div>;
+  }
+  if (!boot.data) {
+    return <div className="boot"><Spinner /> <span className="muted">{t('common.loading')}</span></div>;
+  }
+  return <Shell initialSettings={boot.data} />;
+}
+
+function Shell({ initialSettings }: { initialSettings: Settings }) {
+  const [settings, setSettings] = useState(initialSettings);
+  const [overlay, setOverlay] = useState(overlayOfHash);
+  const shown = useRef<ScreenId>('home');
+  // Before useHashRoute, so this listener runs first: it puts the shown screen back in the hash for the router.
+  useEffect(() => {
+    const take = () => {
+      const open = overlayOfHash();
+      if (!open) return;
+      window.history.replaceState(null, '', `#/${shown.current}`);
+      setOverlay(open);
+    };
+    take();
+    window.addEventListener('hashchange', take);
+    return () => window.removeEventListener('hashchange', take);
+  }, []);
+  const [screen, go] = useHashRoute(SCREENS, 'home');
+  shown.current = screen;
+  setLanguage(settings.language ?? detectLanguage());
+  return (
+    <KeybindingProvider defs={commands()} keymap={settings.keybindings ?? {}} scope={screen}>
+      <Main settings={settings} setSettings={setSettings} screen={screen} go={go} overlay={overlay} setOverlay={setOverlay} />
+    </KeybindingProvider>
+  );
+}
+
+interface MainProps {
+  settings: Settings;
+  setSettings: React.Dispatch<React.SetStateAction<Settings>>;
+  screen: ScreenId;
+  go: (screen: ScreenId) => void;
+  overlay: Overlay | null;
+  setOverlay: (overlay: Overlay | null) => void;
+}
+
+function Main({ settings, setSettings, screen, go, overlay, setOverlay }: MainProps) {
+  const [stopped, setStopped] = useState(false);
+  useHeartbeat();
+  const palette = useCommandPalette();
+
+  const { kind } = useTheme(settings);
+  useZoom(settings.zoom);
+
+  useEffect(() => {
+    const item = NAV.flatMap((s) => s.items).find((i) => i.id === screen);
+    document.title = item ? `${t(item.label)} · ${APP.name}` : APP.name;
+  }, [screen, settings.language]);
+
+  const save = useCallback((patch: Partial<Settings>) => {
+    setSettings((s) => ({ ...s, ...patch }));
+    api.saveSettings(patch).catch(() => { /* preferences are best-effort */ });
+  }, []);
+
+  const navItems = NAV.flatMap((s) => s.items);
+  const defs = commands();
+  // The nav list is a constant, so the hooks run in the same order every render.
+  for (const item of navItems) useCommand(defs.find((d) => d.id === navCommandId(item.id))!, () => go(item.id));
+  useCommand(defs.find((d) => d.id === SETTINGS_COMMAND)!, () => setOverlay('settings'));
+  useCommand(defs.find((d) => d.id === KEYS_COMMAND)!, () => setOverlay('keys'));
+  const keys = useKeybindings();
+  const chordOf = (id: string) => (keys ? effectiveKeys(keys.defs, keys.keymap).get(id)?.[0] : undefined);
+
+  const quit = useCallback(() => { api.quit().then(() => setStopped(true)).catch(() => { /* already gone */ }); }, []);
+  const nextTheme = kind === 'dark' ? 'light' : 'dark';
+  const items = useMemo<PaletteItem[]>(() => {
+    const goTo = navItems.map((i): PaletteItem => ({
+      id: `go:${i.id}`, group: t('palette.group.go'), label: t(i.label), hint: chordOf(navCommandId(i.id)), keywords: [i.id], run: () => go(i.id),
+    }));
+    const overlays: PaletteItem[] = [
+      { id: 'app:settings', group: t('palette.group.go'), label: t('nav.settings'), hint: chordOf(SETTINGS_COMMAND), keywords: ['settings', 'preferences'], run: () => setOverlay('settings') },
+      { id: 'app:keys', group: t('palette.group.go'), label: t('nav.keys'), hint: chordOf(KEYS_COMMAND), keywords: ['keybindings', 'shortcuts', 'keys'], run: () => setOverlay('keys') },
+    ];
+    const toggle: PaletteItem = {
+      id: 'theme:toggle', group: t('palette.group.theme'), label: t(`nav.theme.${nextTheme}`), keywords: ['theme', 'dark', 'light'],
+      run: () => save({ theme: nextTheme }),
+    };
+    const palettes = PALETTES.map((p): PaletteItem => ({
+      id: `palette:${p.id}`, group: t('palette.group.theme'), label: t('palette.theme', { name: p.label }), keywords: ['theme', p.family, p.kind],
+      run: () => save({ theme: p.kind, ...(p.kind === 'dark' ? { paletteDark: p.id } : { paletteLight: p.id }) }),
+    }));
+    const quitItem: PaletteItem[] = isDesktop ? [] : [{
+      id: 'app:quit', group: t('palette.group.app'), label: t('palette.quit', { name: APP.name }), keywords: ['quit', 'exit', 'stop'], run: quit,
+    }];
+    return [...goTo, ...overlays, toggle, ...palettes, ...quitItem];
+  }, [go, save, quit, nextTheme, settings.language, keys, setOverlay]);
+
+  if (stopped) return <div className="boot"><span>{t('app.stopped', { name: APP.name })}</span></div>;
+
+  const sections = NAV.map((s) => ({ title: t(s.title), items: s.items.map((i) => ({ ...i, label: t(i.label), hint: chordOf(navCommandId(i.id)) })) }));
+
+  const footer = (
+        <>
+          <button className="btn btn-ghost btn-sm btn-icon" onClick={() => save({ theme: nextTheme })} title={t(`nav.theme.${nextTheme}`)} aria-label={t(`nav.theme.${nextTheme}`)}>
+            <Icon name={kind === 'dark' ? 'sun' : 'moon'} />
+          </button>
+          <button className={`btn btn-ghost btn-sm${overlay ? ' active' : ''} btn-icon`} onClick={() => setOverlay('settings')} title={t('nav.settings')} aria-label={t('nav.settings')}>
+            <Icon name="settings" />
+          </button>
+          <button className="btn btn-ghost btn-sm btn-icon" onClick={() => palette.setOpen(true)} title={t('nav.palette')} aria-label={t('nav.palette')}>
+            <Icon name="search" />
+          </button>
+        </>
+  );
+
+  return (
+    <LayoutProvider layout={settings.layout} icons={settings.icons} mainMenu={settings.mainMenu} dock={settings.dock} layoutIcon={settings.layoutIcon}>
+    <AppFrame tools={footer} sidebar={<Sidebar name={APP.name} sections={sections} current={screen} onSelect={go} footer={footer} />}>
+      <main className="main">{renderScreen(screen)}</main>
+      {overlay && (
+        <SettingsModal key={overlay} settings={settings} onChange={save} onQuit={() => setStopped(true)} onClose={() => setOverlay(null)} initialSection={overlay === 'keys' ? 'keyboard.shortcuts' : overlay.startsWith('settings/') ? overlay.slice('settings/'.length) : undefined} />
+      )}
+      {palette.open && <CommandPalette items={items} onClose={() => palette.setOpen(false)} />}
+    </AppFrame>
+    </LayoutProvider>
+  );
+}
+
+function renderScreen(screen: ScreenId) {
+  switch (screen) {
+    default:
+      return <Home />;
+  }
+}

package/template/web/src/api.ts

@@ -0,0 +1,38 @@
+import type { ThemeSettings } from '@deckbuilderkit/server-core/palettes';
+import type { UpdateState } from '@deckbuilderkit/server-core/protocol';
+import { type Keymap, type Language, request } from '@deckbuilderkit/ui';
+
+export interface Settings extends ThemeSettings {
+  language?: Language;
+  /** The main menu shows only its icons. */
+  /** Keybinding overrides by command id; the server validates it. */
+  keybindings?: Keymap;
+  autostart: boolean;
+  /** Tray icon; read at startup. */
+  closeToTray: boolean;
+  updateFolder: string;
+}
+
+/** GET /api/info (infoRoutes in @deckbuilderkit/server-mods). */
+export interface Info {
+  name: string;
+  version: string;
+  platform: string;
+  arch: string;
+  hostname: string;
+  bun: string;
+  dataDir: string;
+  startedAt: string;
+}
+
+export const api = {
+  info: () => request<Info>('GET', '/api/info'),
+  settings: () => request<Settings>('GET', '/api/settings'),
+  saveSettings: (patch: Partial<Settings>) => request<Settings>('PUT', '/api/settings', {}, patch),
+  /** Shows the server's folder dialog and saves the result as `updateFolder` (unchanged when cancelled). */
+  pickUpdateFolder: (title: string) => request<Settings>('POST', '/api/settings/update-folder', {}, { title }),
+  update: () => request<UpdateState>('GET', '/api/update'),
+  checkUpdate: () => request<UpdateState>('POST', '/api/update/check'),
+  applyUpdate: () => request<{ version: string }>('POST', '/api/update/apply'),
+  quit: () => request<{ ok: true }>('POST', '/api/quit'),
+};