@monster-orange/den 0.2.8 → 0.3.0

package/src/ui/server/public/version-label.js

@@ -0,0 +1,12 @@
+/**
+ * The header version pill's text: the running Den's own version (its
+ * package.json, from /api/server-info), prerelease suffix and all
+ * ("v0.3.0-dev.5"). The changelog's newest heading names the release being
+ * built ("0.3.0"), not this build, so it is only the fallback.
+ */
+export function versionLabel(serverVersion, changelog) {
+  const v =
+    (typeof serverVersion === "string" && serverVersion.trim()) ||
+    changelog?.[0]?.version;
+  return v ? `v${v}` : null;
+}

package/src/ui/server/public/workspace-picker.js

@@ -1,8 +1,8 @@
 /**
- * Workspace pill / picker models.
+ * The Workspace ▾ menu's model.
  *
  * Pure and DOM-free (like perf-report.js) so the shape of the header's
- * workspace menu is unit-testable under Jest's node environment; header.js
+ * Workspace menu is unit-testable under Jest's node environment; header.js
  * owns everything that touches the DOM.
  *
  * Input is always the `/api/workspaces` payload:
@@ -11,6 +11,28 @@
  * single string, which both helpers still accept.
  */
 
+/**
+ * The menu's en strings, for where there is no shell (a unit test). In a
+ * page, header.js passes the shell's t (R19), which has the same en text
+ * (i18n.test.ts holds them equal).
+ */
+export const EN_FALLBACK = {
+  "ws.all": "All active",
+  "ws.allN": "All active ({n})",
+  "ws.allTip":
+    "Every active workspace; a service several define is listed once",
+  "ws.noneLabel": "none",
+  "ws.viewTitle":
+    "View: what every page shows ({ws}). A view filter only: it starts, stops and routes nothing.",
+  "ws.viewTitleFocus":
+    "View: what every page shows ({ws}). A view filter only: it starts, stops and routes nothing, and focus ({focus}) stays the target for commands.",
+};
+function enT(key, vars) {
+  return String(EN_FALLBACK[key] ?? key).replace(/\{(\w+)\}/g, (m, k) =>
+    vars && vars[k] != null ? String(vars[k]) : m,
+  );
+}
+
 /** Active workspace names, normalised to an array. */
 function activeNames(data) {
   const active = data?.active;
@@ -26,44 +48,62 @@ function focusName(data) {
 }
 
 /**
- * Label + tooltip for the header pill.
- * Falls back to "default" so the pill never renders empty.
+ * The top bar's Workspace ▾ menu (R4, 0.3.0-dev.18), from the `/api/scope`
+ * and `/api/workspaces` payloads. It is the view scope: what every page,
+ * the health row and `status` show. Choosing an entry never moves the
+ * focus (the default target for commands); the focused workspace is
+ * marked, and `focusable` names the workspace in view when it is not the
+ * focus, for the menu's separate "Set <ws> as focus" item.
+ *
+ * "All active" is offered with two or more active workspaces; with one,
+ * it and that workspace are the same view.
  */
-export function buildWorkspacePillModel(data) {
+export function buildScopeMenuModel(scope, data, t = enT) {
   const active = activeNames(data);
-  const label = focusName(data) ?? "default";
+  const focus = scope?.focus ?? focusName(data);
+  const multi = active.length > 1;
+  const selected =
+    scope?.scope && scope.scope !== "all" && active.includes(scope.scope)
+      ? scope.scope
+      : "all";
+  const inView = Array.isArray(scope?.inView) ? scope.inView : active;
+  const one = multi ? (selected === "all" ? null : selected) : active[0];
+  const items = [
+    ...(multi
+      ? [
+          {
+            value: "all",
+            label: t("ws.allN", { n: active.length }),
+            checked: selected === "all",
+            focused: false,
+            title: t("ws.allTip"),
+          },
+        ]
+      : []),
+    ...active.map((n) => ({
+      value: n,
+      label: n,
+      checked: n === one,
+      focused: n === focus,
+    })),
+  ];
   return {
-    label,
-    // Only worth spelling out when more than one workspace is active —
-    // otherwise the pill text already says everything.
-    title:
-      active.length > 1
-        ? `Active: ${active.join(", ")} · Focus: ${label}`
-        : "Switch workspace",
+    label: active.length === 0 ? t("ws.noneLabel") : (one ?? t("ws.all")),
+    items,
+    focusable: one && one !== focus ? one : null,
+    title: t(focus ? "ws.viewTitleFocus" : "ws.viewTitle", {
+      ws: inView.join(", ") || t("ws.noneLabel"),
+      focus,
+    }),
   };
 }
 
 /**
- * Menu model for the pill's dropdown: every known workspace, active ones
- * first (they are the likely targets), each side alphabetical so the list
- * order is stable across polls.
+ * " · a, b" after a service that several workspaces in view define (it is
+ * listed once); "" when one does.
  */
-export function buildWorkspaceMenuModel(data) {
-  const active = new Set(activeNames(data));
-  const focus = focusName(data);
-  // Union of the catalog and the active set: a workspace listed as active but
-  // missing from `workspaces` still has to be selectable (and visible).
-  const names = new Set([...Object.keys(data?.workspaces ?? {}), ...active]);
-
-  const items = [...names].map((name) => ({
-    name,
-    active: active.has(name),
-    focused: name === focus,
-  }));
-  items.sort(
-    (a, b) =>
-      Number(b.active) - Number(a.active) || a.name.localeCompare(b.name),
-  );
-
-  return { focus, items };
+export function ownersLabel(owners) {
+  return Array.isArray(owners) && owners.length > 1
+    ? ` · ${owners.join(", ")}`
+    : "";
 }

package/src/ui/server/readonly-routes.ts

@@ -3,7 +3,10 @@
  *
  *   /api/stacks          what `stack ls` + `stack health` show
  *                        ?workspace=<den workspace>  ?health=0 skips docker
- *   /api/edge            what `edge status` shows: up/down, routes, cert names
+ *   /api/edge            what `edge status` shows: up/down, routes, cert names,
+ *                        the included files' routers, the TLS strategy
+ *                        ?probe=1  only { configured } (the rail's Edge
+ *                        page asks on every load: no Docker, no keychain)
  *   /api/security/plan   the security CLI's own dry run for ?env&mode&service:
  *                        target discovery and the owned-host check, nothing run
  *   /api/activity        the audit trail for one service (?address=repo/svc) or
@@ -46,6 +49,8 @@ export interface ReadonlyRouteDeps {
     stacks: StackStatus[];
   };
   edge: () => EdgeStatus;
+  /** The edge block reads (no Docker asked); throws with the reason if not. */
+  edgeConfig: () => void;
   actions: () => AuditEntry[];
   securityPlan: (args: SecurityPlanArgs) => Promise<SecurityPlanResult>;
 }
@@ -62,6 +67,7 @@ export const defaultReadonlyRouteDeps: ReadonlyRouteDeps = {
     };
   },
   edge: () => edgeStatus(readEdgeConfig()),
+  edgeConfig: () => void readEdgeConfig(),
   actions: recentActions,
   securityPlan: async ({ env, mode, service }) => {
     // The CLI's own entrypoint in --dry-run: the same discovery, mode
@@ -164,6 +170,11 @@ export async function handleReadonlyRoutes(
 
   if (pathname === "/api/edge") {
     try {
+      if (url.searchParams.get("probe") === "1") {
+        deps.edgeConfig();
+        sendJson(res, { configured: true });
+        return true;
+      }
       sendJson(res, { configured: true, ...deps.edge() });
     } catch (e) {
       // No edge configured is a state, not a server error.

package/src/ui/server/services-list.ts

@@ -1,7 +1,9 @@
 /**
  * The /api/services payload: every service of the legacy-discovered repos and
- * of the requested (or active) workspace, with commands, branch, deps and
- * graph rank.
+ * of the requested workspace (or, with none named, of every workspace the
+ * view scope has in view), with commands, branch, deps and graph rank. A
+ * service two workspaces in view share is listed once, with `inWorkspaces`
+ * naming both (focus first); its deps and autostart come from the first.
  *
  * Built off the request path's critical section: the per-repo branch lookups
  * (`git rev-parse`, ~40ms each) run as async child processes in parallel
@@ -15,20 +17,26 @@ import type { Environment } from "../../shared/types/index.js";
 import { discoverRepos } from "../../pillars/smoke/discover.js";
 import { readCatalog } from "../../shared/environment-manager/catalog.js";
 import {
-  getActiveWorkspace,
   listWorkspaceServices,
   noAutostartRepos,
   readWorkspacesFile,
   resolveDepAddress,
 } from "../../shared/environment-manager/workspaces.js";
 import { graphOrder } from "./graph-order.js";
-import { listDaemons } from "../../shared/environment-manager/service-runner.js";
+import { scopeView } from "../../shared/environment-manager/scope.js";
+import type { WorkspaceConfig } from "../../shared/types/index.js";
+import {
+  listDaemons,
+  resolveService,
+} from "../../shared/environment-manager/service-runner.js";
 import { loadManifest } from "../../shared/manifest/read-manifest.js";
 import { servicePlacement } from "../../shared/manifest/placement.js";
 import { depService } from "../../shared/manifest/deps.js";
 import { hasRuntime, repoKind } from "../../shared/repo-kind.js";
 import { readDenConfig } from "../../shared/den-config.js";
 import { GIT_REMOTE_TIMEOUT_MS } from "../../shared/constants.js";
+import { effectiveLocalCommands } from "../../shared/stacks/manifest-commands.js";
+import { resolveUpTargets } from "../../shared/environment-manager/up-targets.js";
 
 /** `repoPath`'s checked-out branch, or null (not a checkout, git failed). */
 export function currentBranch(repoPath: string): Promise<string | null> {
@@ -87,11 +95,19 @@ export async function buildServicesList(
   // Catalog entries (workspace-aware)
   const catalog = readCatalog();
   const wsFile = wsOverride ? readWorkspacesFile() : null;
-  const ws = wsOverride
+  const inView: { name: string; config: WorkspaceConfig }[] = wsOverride
     ? wsFile?.workspaces[wsOverride]
-      ? { name: wsOverride, config: wsFile.workspaces[wsOverride] }
-      : null
-    : getActiveWorkspace();
+      ? [{ name: wsOverride, config: wsFile.workspaces[wsOverride] }]
+      : []
+    : scopeView().workspaces.filter((w) => w.config);
+  // Every workspace in view that defines an address, focus first.
+  const ownersOf = new Map<string, string[]>();
+  for (const w of inView)
+    for (const r of listWorkspaceServices(w.config, catalog, w.name)) {
+      const o = ownersOf.get(r.address) ?? [];
+      if (!o.includes(w.name)) ownersOf.set(r.address, [...o, w.name]);
+    }
+  const seen = new Set<string>();
 
   // One lookup per checkout, all in flight at once; filled in below.
   const branches = new Map<string, Promise<string | null>>();
@@ -101,19 +117,53 @@ export async function buildServicesList(
     return p;
   };
 
-  const noAutostart = ws
-    ? noAutostartRepos(ws.config, catalog)
-    : new Set<string>();
+  const noAutostartBy = new Map(
+    inView.map((w) => [w.name, noAutostartRepos(w.config, catalog)] as const),
+  );
   const daemonOwners = new Map(
     listDaemons().map((d) => [d.address, d.workspaces ?? []] as const),
   );
+  // What starting a repo runs: the decision `up <repo>` makes
+  // (resolveUpTargets: its own up, a compose stack's, else its services'),
+  // so a repo row's Start/Restart offers exactly what `up` would start
+  // (0.3.0-dev.37). [] when it has no up at all. One per workspace + repo.
+  const upTargetsBy = new Map<string, string[]>();
+  const upTargetsOf = (ws: string, repo: string): string[] => {
+    const key = `${ws}\0${repo}`;
+    let t = upTargetsBy.get(key);
+    if (!t) {
+      try {
+        const up = resolveUpTargets([repo], ws, {
+          targets: new Set([repo]),
+        });
+        // As the table's rows name them: a bare repo is its entry service.
+        t = up.skippedNoUp.includes(repo)
+          ? []
+          : up.order.map((a) => {
+              const r = resolveService(a, ws);
+              return r ? `${r.repoName}/${r.subsystem}` : a;
+            });
+      } catch {
+        t = [];
+      }
+      upTargetsBy.set(key, t);
+    }
+    return t;
+  };
+
   // Modules and libraries have no runtime: no card, health or commands.
   // They show as contributors on the Applications tab instead.
   const pendingBranches: Promise<void>[] = [];
-  const catalogEntries = ws
-    ? listWorkspaceServices(ws.config, catalog, ws.name)
+  const catalogEntries = inView.flatMap((ws) => {
+    const noAutostart = noAutostartBy.get(ws.name) ?? new Set<string>();
+    return (
+      listWorkspaceServices(ws.config, catalog, ws.name)
         .filter((r) => hasRuntime(repoKind(r.repoPath)))
+        // A shared service is listed once: the first workspace in view
+        // (focus first) owns its entry.
+        .filter((r) => !seen.has(r.address) && !!seen.add(r.address))
         .flatMap((resolved) => {
+          const inWorkspaces = ownersOf.get(resolved.address) ?? [ws.name];
           // The manifest and the layers it was built from: repo or held,
           // plus override when manifests/<repo>.override.yml applied.
           const { manifest, layers: manifestLayers } = loadManifest(
@@ -141,6 +191,7 @@ export async function buildServicesList(
                 isEntrypoint: false,
                 autostart: !noAutostart.has(resolved.repoName),
                 owners: daemonOwners.get(resolved.address) ?? [],
+                inWorkspaces,
                 deps: [] as string[],
                 cloned: fs.existsSync(resolved.repoPath),
                 manifestLayers,
@@ -153,7 +204,23 @@ export async function buildServicesList(
             service: resolved.subsystem,
             address: resolved.address,
             repoPath: resolved.repoPath,
-            commands: withDown(Object.keys(svc.commands?.[env] ?? {})),
+            // Locally, a compose stack's synthesized up/down/restart count
+            // (what the runner runs), not just the declared ones.
+            commands: withDown(
+              Object.keys(
+                env === "local"
+                  ? effectiveLocalCommands(
+                      manifest,
+                      resolved.subsystem,
+                      resolved.repoName,
+                      ws.name,
+                    )
+                  : (svc.commands?.[env] ?? {}),
+              ),
+            ),
+            ...(env === "local"
+              ? { upTargets: upTargetsOf(ws.name, resolved.repoName) }
+              : {}),
             logs: svc.logs?.[env] ?? null,
             mode: resolved.mode,
             branch: resolved.branch as string | null,
@@ -161,6 +228,7 @@ export async function buildServicesList(
             isEntrypoint: manifest.entrypoint === resolved.subsystem,
             autostart: !noAutostart.has(resolved.repoName),
             owners: daemonOwners.get(resolved.address) ?? [],
+            inWorkspaces,
             deps: (svc.depends_on ?? []).map((d) =>
               resolveDepAddress(depService(d), catalog, ws.config, ws.name),
             ),
@@ -176,13 +244,16 @@ export async function buildServicesList(
             );
           return [entry];
         })
-    : [];
+    );
+  });
 
   // Merge: catalog entries take precedence over legacy for same repo.
   // When a workspace filter is active, also exclude legacy entries not in
   // the workspace (legacy discovery is not workspace-scoped).
   const catalogRepos = new Set(Object.keys(catalog));
-  const wsServiceKeys = ws ? new Set(Object.keys(ws.config.services)) : null;
+  const wsServiceKeys = inView.length
+    ? new Set(inView.flatMap((w) => Object.keys(w.config.services)))
+    : null;
   const merged = [
     ...legacyEntries.filter((e) => {
       if (catalogRepos.has(e.repo)) return false;
@@ -197,7 +268,13 @@ export async function buildServicesList(
   // health row and `den status` use. Added as a FIELD rather than by
   // re-sorting the array, because four pages consume this payload and some
   // rely on the current order.
-  const graphRank = new Map(graphOrder(ws?.name).map((repo, i) => [repo, i]));
+  // With several workspaces in view: the focus's order, then repos only the
+  // others define, in their own order.
+  const order: string[] = [];
+  for (const w of inView.length ? inView : [null])
+    for (const repo of graphOrder(w?.name))
+      if (!order.includes(repo)) order.push(repo);
+  const graphRank = new Map(order.map((repo, i) => [repo, i]));
   const infraRepo = readDenConfig()?.graph?.infra?.repo ?? null;
   await Promise.all(pendingBranches);
   return merged.map((e) => ({

package/src/ui/server/settings-distribution.ts

@@ -0,0 +1,74 @@
+/**
+ * What the distribution's tracked config sets, for the Settings page's
+ * read-only Distribution rows (R21, 0.3.0-dev.19). Read straight from the
+ * org config file (product().configFile), never from config/local/user.yml,
+ * so a row shows the distribution's value even when you override it.
+ *
+ * Read-only by design: nothing in the Settings page writes the
+ * distribution's config (it is tracked in git). Your own override of the
+ * same thing (a theme pick, `web.port` in user.yml) is a separate User row.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+import { product } from "../../shared/product.js";
+
+export interface DistributionSettings {
+  /** The org config file, relative to the distribution root. */
+  file: string;
+  /** brand.name */
+  brand: string | null;
+  /** brand.theme: the theme drawn when you have chosen none. */
+  theme: string | null;
+  github_org: string | null;
+  /** orgs: id → label (or the id when it has none). */
+  orgs: Record<string, string>;
+  /** web.port in the org config (your user.yml may override it). */
+  web_port: number | null;
+  environments: string[] | null;
+  /** edge.domain */
+  domain: string | null;
+}
+
+/** Your own `web.port` override in config/local/user.yml, or null. */
+export function userWebPort(user: Record<string, unknown>): number | null {
+  const p = (user.web as { port?: unknown } | undefined)?.port;
+  return typeof p === "number" && Number.isInteger(p) ? p : null;
+}
+
+const str = (v: unknown): string | null =>
+  typeof v === "string" && v.trim() ? v.trim() : null;
+
+/** The distribution's values; an unreadable file reads as nothing set. */
+export function distributionSettings(root: string): DistributionSettings {
+  const file = product().configFile;
+  let raw: Record<string, unknown> = {};
+  try {
+    raw =
+      (yaml.parse(fs.readFileSync(path.join(root, file), "utf-8")) as Record<
+        string,
+        unknown
+      > | null) ?? {};
+  } catch {
+    /* no or broken config: nothing set */
+  }
+  const brand = (raw.brand ?? {}) as Record<string, unknown>;
+  const orgs: Record<string, string> = {};
+  if (raw.orgs && typeof raw.orgs === "object" && !Array.isArray(raw.orgs))
+    for (const [id, v] of Object.entries(raw.orgs as Record<string, unknown>))
+      orgs[id] = str((v as { label?: unknown } | null)?.label) ?? id;
+  const port = (raw.web as { port?: unknown } | undefined)?.port;
+  const envs = Array.isArray(raw.environments)
+    ? raw.environments.filter((e): e is string => typeof e === "string")
+    : null;
+  return {
+    file,
+    brand: str(brand.name),
+    theme: str(brand.theme),
+    github_org: str(raw.github_org),
+    orgs,
+    web_port: typeof port === "number" && Number.isInteger(port) ? port : null,
+    environments: envs,
+    domain: str((raw.edge as { domain?: unknown } | undefined)?.domain),
+  };
+}

package/src/ui/server/shell-prefs.ts

@@ -0,0 +1,192 @@
+/**
+ * Shell preferences (0.3.0-dev.17): what this engineer pinned to the rail
+ * and whether the rail is collapsed; since 0.3.0-dev.19 (R21 Navigation)
+ * also the rail pages they hid and the order they put them in. Stored in the user config as `shell:`
+ * and served by /api/settings, like `graph:` and `appearance:`. A view
+ * preference only: pinning changes no edge route, container or service.
+ * The shell mirrors it to localStorage so the first paint does not wait on
+ * the server.
+ */
+
+export interface ShellPrefs {
+  /** Pinned repos or services (`repo` or `repo/service`), in pin order. */
+  pins: string[];
+  /** The rail shows icons only. */
+  collapsed: boolean;
+  /** NAV page ids the rail leaves out (Settings is never one). */
+  hidden: string[];
+  /** NAV page ids in the engineer's order; pages not listed keep theirs. */
+  order: string[];
+  /**
+   * The runs dock is open (R16a, 0.3.0-dev.30, Ward QA 2026-11-05): it
+   * starts collapsed to its bar; opening it is the engineer's choice and
+   * remembered, never forced by a run starting.
+   */
+  dock: boolean;
+  /** The open dock's output height in px; 0 is the default (170px). */
+  dockHeight: number;
+}
+
+export const SHELL_DEFAULTS: ShellPrefs = {
+  pins: [],
+  collapsed: false,
+  hidden: [],
+  order: [],
+  dock: false,
+  dockHeight: 0,
+};
+
+/** The dock height's bounds (the page also caps it at half the window). */
+export const DOCK_MIN = 60;
+export const DOCK_MAX = 2000;
+
+function checkDockHeight(
+  v: unknown,
+): { ok: true; value: number } | { ok: false; error: string } {
+  if (typeof v !== "number" || !Number.isFinite(v))
+    return { ok: false, error: dockHeightError() };
+  const h = Math.round(v);
+  if (h !== 0 && (h < DOCK_MIN || h > DOCK_MAX))
+    return { ok: false, error: dockHeightError() };
+  return { ok: true, value: h };
+}
+function dockHeightError(): string {
+  return `shell.dockHeight must be 0 (the default) or a number from ${DOCK_MIN} to ${DOCK_MAX}`;
+}
+
+/** How many page ids `hidden` and `order` keep. */
+export const MAX_NAV_IDS = 64;
+/** A NAV id, as shell.js's registerNav takes it. */
+const NAV_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+/** How many pins the rail keeps. */
+export const MAX_PINS = 24;
+const PIN =
+  /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}(\/[A-Za-z0-9][A-Za-z0-9._-]{0,99})?$/;
+
+const isObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+function checkPins(
+  v: unknown,
+): { ok: true; value: string[] } | { ok: false; error: string } {
+  if (!Array.isArray(v))
+    return { ok: false, error: "shell.pins must be a list" };
+  const out: string[] = [];
+  for (const p of v) {
+    if (typeof p !== "string" || !PIN.test(p))
+      return {
+        ok: false,
+        error: `shell.pins: "${String(p)}" is not a repo or repo/service name`,
+      };
+    if (!out.includes(p)) out.push(p);
+  }
+  if (out.length > MAX_PINS)
+    return { ok: false, error: `shell.pins: at most ${MAX_PINS}` };
+  return { ok: true, value: out };
+}
+
+function checkNavIds(
+  key: "hidden" | "order",
+  v: unknown,
+): { ok: true; value: string[] } | { ok: false; error: string } {
+  if (!Array.isArray(v))
+    return { ok: false, error: `shell.${key} must be a list` };
+  const out: string[] = [];
+  for (const id of v) {
+    if (typeof id !== "string" || !NAV_ID.test(id))
+      return {
+        ok: false,
+        error: `shell.${key}: "${String(id)}" is not a page id`,
+      };
+    if (!out.includes(id)) out.push(id);
+  }
+  if (out.length > MAX_NAV_IDS)
+    return { ok: false, error: `shell.${key}: at most ${MAX_NAV_IDS}` };
+  return { ok: true, value: out };
+}
+
+/** The stored block, normalised: a missing or hand-broken field is its default. */
+export function shellPrefs(stored: unknown): ShellPrefs {
+  const out: ShellPrefs = {
+    pins: [],
+    collapsed: false,
+    hidden: [],
+    order: [],
+    dock: false,
+    dockHeight: 0,
+  };
+  if (!isObject(stored)) return out;
+  if (typeof stored.dock === "boolean") out.dock = stored.dock;
+  if (stored.dockHeight !== undefined) {
+    const h = checkDockHeight(stored.dockHeight);
+    if (h.ok) out.dockHeight = h.value;
+  }
+  const pins = checkPins(stored.pins);
+  if (pins.ok) out.pins = pins.value;
+  if (typeof stored.collapsed === "boolean") out.collapsed = stored.collapsed;
+  for (const key of ["hidden", "order"] as const) {
+    const ids = checkNavIds(key, stored[key]);
+    if (ids.ok) out[key] = ids.value;
+  }
+  return out;
+}
+
+/** Merge a POSTed (partial) block over the current prefs; any bad field fails it. */
+export function mergeShellPrefs(
+  current: ShellPrefs,
+  patch: unknown,
+): { ok: true; value: ShellPrefs } | { ok: false; error: string } {
+  if (!isObject(patch)) return { ok: false, error: "shell must be an object" };
+  const out: ShellPrefs = {
+    ...current,
+    pins: [...current.pins],
+    hidden: [...current.hidden],
+    order: [...current.order],
+  };
+  for (const key of Object.keys(patch)) {
+    // null clears a pref back to its default (0.3.0-dev.32): the stored
+    // block drops it, so set-then-clear leaves user.yml as it was.
+    if (patch[key] === null && key in SHELL_DEFAULTS) {
+      const d = SHELL_DEFAULTS[key as keyof ShellPrefs];
+      (out as unknown as Record<string, unknown>)[key] = Array.isArray(d)
+        ? []
+        : d;
+      continue;
+    }
+    if (key === "pins") {
+      const p = checkPins(patch.pins);
+      if (!p.ok) return p;
+      out.pins = p.value;
+    } else if (key === "collapsed") {
+      if (typeof patch.collapsed !== "boolean")
+        return { ok: false, error: "shell.collapsed must be true or false" };
+      out.collapsed = patch.collapsed;
+    } else if (key === "dock") {
+      if (typeof patch.dock !== "boolean")
+        return { ok: false, error: "shell.dock must be true or false" };
+      out.dock = patch.dock;
+    } else if (key === "dockHeight") {
+      const h = checkDockHeight(patch.dockHeight);
+      if (!h.ok) return h;
+      out.dockHeight = h.value;
+    } else if (key === "hidden" || key === "order") {
+      const ids = checkNavIds(key, patch[key]);
+      if (!ids.ok) return ids;
+      out[key] = ids.value;
+    } else return { ok: false, error: `shell.${key} is not a setting` };
+  }
+  return { ok: true, value: out };
+}
+
+/** The block to store: none for the defaults, so user.yml stays lean. */
+export function storedShell(p: ShellPrefs): Partial<ShellPrefs> | undefined {
+  const out: Partial<ShellPrefs> = {};
+  if (p.pins.length) out.pins = p.pins;
+  if (p.collapsed) out.collapsed = true;
+  if (p.hidden.length) out.hidden = p.hidden;
+  if (p.order.length) out.order = p.order;
+  if (p.dock) out.dock = true;
+  if (p.dockHeight) out.dockHeight = p.dockHeight;
+  return Object.keys(out).length ? out : undefined;
+}