babavoss 0.12.6 → 0.13.1

package/src/build/project.ts

@@ -12,9 +12,14 @@ const harness = join(framework, "src/runtime/worker.ts");
 const ENTRY = "/babavoss/entry.ts";
 
 export async function bundleProject(project: Project): Promise<string> {
+  // The agentic instructions: every .mdx under .baba/agents/, in name order, each a document the baba is given.
+  const docs = [...new Bun.Glob("agents/*.mdx").scanSync({ cwd: project.baba })].sort().map((f) => join(project.baba, f));
   const text = [
-    `import v from ${JSON.stringify(project.entry)};`,
+    `import entry from ${JSON.stringify(project.entry)};`,
+    `import { instructed } from "babavoss";`,
     `import { serve } from ${JSON.stringify(harness)};`,
+    ...docs.map((f, i) => `import doc${i} from ${JSON.stringify(f)};`),
+    `const v = instructed(entry, [${docs.map((_, i) => `doc${i}`).join(", ")}]);`,
     `export default v;`,
     `serve(v);`,
   ].join("\n") + "\n";

package/src/build/views.ts

@@ -27,9 +27,9 @@ export const names: Record<string, string> = {
   "babavoss/web": join(framework, "src/web/index.tsx"),
   "babavoss/test": join(framework, "src/test/index.ts"),
   "babavoss/bench": join(framework, "src/bench/index.ts"),
-  "babavoss/prompt": join(framework, "src/prompt/index.ts"),
-  "babavoss/prompt/jsx-runtime": join(framework, "src/prompt/jsx-runtime.ts"),
-  "babavoss/prompt/jsx-dev-runtime": join(framework, "src/prompt/jsx-dev-runtime.ts"),
+  "babavoss/instructions": join(framework, "src/instructions/index.ts"),
+  "babavoss/instructions/jsx-runtime": join(framework, "src/instructions/jsx-runtime.ts"),
+  "babavoss/instructions/jsx-dev-runtime": join(framework, "src/instructions/jsx-dev-runtime.ts"),
 };
 
 /**

package/src/desktop/desktop.css

@@ -5,34 +5,24 @@
 .desktop { position: relative; display: flex; flex-direction: column; height: 100dvh; min-height: 320px; overflow: hidden; color: var(--foreground); background: var(--desk); font: 13px/20px var(--font-sans, system-ui);
   /* Everything that sits on the desk is ink over it, translucent, never a surface of its own. */
   --desktop-ink: color-mix(in oklch, var(--foreground) 6%, transparent); --desktop-ink-strong: color-mix(in oklch, var(--foreground) 11%, transparent); --desktop-ink-top: color-mix(in oklch, var(--foreground) 20%, transparent); }
-.desktop button, .desktop input, .desktop select { font: inherit; color: inherit; }
+/* Of no weight, so a control's own class, a primary button's colours among them, always wins over it. */
+:where(.desktop) :where(button, input, select) { font: inherit; color: inherit; }
 .desktop button { cursor: pointer; }
 .desktop button:disabled { cursor: default; }
 .desktop button:focus-visible, .desktop select:focus-visible { outline: 2px solid var(--primary); outline-offset: -2px; }
 
-/* The bar sits on the desk itself: the mark at the far left, always; then a pill per open window, or the desktop's name while nothing is open. */
+/* The bar sits on the desk itself and holds tabs only: the mark at the far left, always, then a pill per open window. */
 .desktop-bar { position: relative; z-index: 3; flex-shrink: 0; display: flex; align-items: stretch; height: 40px; padding: 6px 8px; gap: 4px; user-select: none; }
-.desktop-logo { display: grid; place-items: center; width: 28px; padding: 0; border: 0; border-radius: 999px; background: transparent; color: var(--foreground); }
-.desktop-logo:hover { background: var(--desktop-ink); }
-.desktop-logo.is-selected { background: var(--desktop-ink-top); }
-.desktop-logo.is-selected { color: var(--primary); }
+/* The mark is the launcher's tab, a pill with the baba's name, filled while the launcher shows; it never closes, its way out leaves the baba. */
+.desktop-pill-mark { color: var(--foreground); }
+/* With no way out, an embedded desktop's, its eyes stay where they are. */
+.desktop-pill-mark:not(:has(.desktop-pill-close)) .desktop-pill-label > .desktop-pill-icon { opacity: 1; transform: none; }
 .desktop-eyes { display: block; }
 /* With the larger eye away, the smaller one moves to the middle; in user units, 50 - 71.5. */
 .desktop-eye-large { transition: opacity .12s; }
 .desktop-eye-small { transition: transform .22s cubic-bezier(.3, 1.2, .3, 1); }
 .desktop-eyes.is-alone .desktop-eye-large { opacity: 0; }
 .desktop-eyes.is-alone .desktop-eye-small { transform: translateX(-21.5px); }
-/* When the launcher closes the eyes settle back, with a small overshoot: the smaller one from the middle to its place, the larger one back from where it left as the dot. */
-.desktop-eyes circle { transform-box: fill-box; transform-origin: center; }
-.desktop-eyes.is-settling .desktop-eye-small { animation: desktop-eye-home .34s cubic-bezier(.3, 1.6, .4, 1); }
-.desktop-eyes.is-settling .desktop-eye-large { animation: desktop-eye-back .34s cubic-bezier(.3, 1.6, .4, 1); }
-@keyframes desktop-eye-home { from { transform: translateX(-21.5px); } }
-@keyframes desktop-eye-back { from { transform: scale(0); } }
-@media (prefers-reduced-motion: reduce) { .desktop-eyes.is-settling circle { animation: none; } }
-.desktop-bar-title { display: flex; align-items: center; padding: 0 8px; color: var(--muted-foreground); white-space: pre; }
-.desktop-bar-root { color: var(--muted-foreground); text-decoration: none; border-radius: 4px; padding: 0 2px; margin: 0 -2px; }
-.desktop-bar-root:hover, .desktop-bar-root:focus-visible { color: var(--foreground); background: var(--muted); outline: none; }
-.desktop-bar-gap { flex: 1; }
 /* One pill per open window, the one in front filled; pointing at a pill shows its × over its right end. */
 .desktop-pills { display: flex; align-items: stretch; gap: 4px; min-width: 0; overflow-x: auto; scrollbar-width: none; scroll-behavior: smooth; }
 .desktop-pills::-webkit-scrollbar { display: none; }
@@ -67,42 +57,48 @@
 @keyframes desktop-marquee-start { to { transform: translateX(var(--ease)); } }
 @keyframes desktop-marquee-fade { to { --desktop-fade-left: 12px; } }
 @media (prefers-reduced-motion: reduce) { .desktop-pill:hover .desktop-pill-text.is-overflowing, .desktop-pill:hover .desktop-pill-text.is-overflowing .desktop-pill-track, .desktop-pill:hover .desktop-pill-text.is-overflowing .desktop-pill-track > span { animation: none; } }
-.desktop-content { flex: 1; min-width: 0; min-height: 0; overflow: hidden; display: flex; flex-direction: column; }
+.desktop-content { flex: 1; min-width: 0; min-height: 0; overflow: hidden; display: flex; flex-direction: column; isolation: isolate; }
+/* Isolated, so nothing an app stacks rises over the launcher. */
 /* An app's window is a sheet under the bar, a line along its top; it scrolls, and the app brings its own gutters. */
 .desktop-app { flex: 1; min-height: 0; overflow: auto; background: var(--background); border-top: 1px solid var(--border); }
 .desktop-app[hidden] { display: none; }
+/* The app in front while the launcher shows: kept as it is, scroll and all, but not drawn, so nothing of it shows through. */
+.desktop-app.is-behind { visibility: hidden; }
 
-/* The launcher covers the page: the bar's row is the search, the pills sit on the next row as they are, and the apps fill the rest as pills under their groups. */
-.desktop-launcher { position: absolute; inset: 0; z-index: 5; display: flex; flex-direction: column; background: var(--desk); }
-.desktop-search { flex: 1; min-width: 0; height: 100%; padding: 0 10px 0 6px; background: transparent; border: 0; font-size: 13px; }
+/* The launcher is the mark's tab: it takes the content's place under the bar as any app's window does, a sheet with a line along its top, and a palette sits in its middle, a little above, as a command palette does. It appears at once. */
+.desktop-launcher { position: absolute; inset: 40px 0 0; z-index: 5; display: flex; justify-content: center; align-items: flex-start; padding: max(16px, 14vh) 16px 16px; background: var(--background); border-top: 1px solid var(--border); }
+/* The quick launcher, ⌘P's, over the app in front: the app shows through, dimmed, and the palette floats on a piece of desk. A press around it goes back. */
+.desktop-launcher.is-quick { background: color-mix(in oklch, var(--desk) 55%, transparent); border-top-color: transparent; }
+.desktop-launcher.is-quick .desktop-palette { max-height: min(100%, 520px); padding: 8px; border-radius: 26px; background: var(--desk); }
+.desktop-palette { display: flex; flex-direction: column; gap: 8px; width: min(560px, 100%); max-height: 100%; }
+/* The search is a pill of ink, its icon as far in from the pill's round end as the pill is tall allows; with focus it gains a line. */
+.desktop-launcher-search { display: flex; align-items: center; flex-shrink: 0; height: 36px; padding: 0 4px 0 6px; gap: 3px; border: 1px solid transparent; border-radius: 999px; background: var(--desktop-ink); color: var(--muted-foreground); }
+.desktop-launcher-search:focus-within { border-color: var(--border); }
+.desktop-search { flex: 1; min-width: 0; height: 100%; padding: 0 10px 0 0; background: transparent; border: 0; font-size: 13px; color: var(--foreground); }
 .desktop-search::placeholder { color: var(--muted-foreground); }
-/* Where this level is, at the search row's end, quiet. */
 .desktop .desktop-search:focus { outline: none; }
-/* The palette under the search: one column of rows, and one dot. The dot, under the mark, says which row is chosen, by the keys or the pointer, and glides between rows; the chosen row's content draws toward it. */
-.desktop-launcher-body { flex: 1; min-height: 0; overflow: auto; padding: 4px 8px 24px calc(8px + 28px + 4px); }
-/* The larger eye, out of the mark, at its own size: its centre is where the transform puts it, so it can be born where the eye was. It hangs from the mark by a string, a hairline straight down from the mark's lower edge, on the eye's own vertical, to the dot's upper edge. */
-.desktop-dot { position: absolute; top: 0; left: 0; width: 6.5px; height: 6.5px; margin: -3.25px 0 0 -3.25px; border-radius: 50%; background: var(--primary); opacity: 0; pointer-events: none; transition: opacity .12s; will-change: transform; z-index: 1; }
-.desktop-string { position: absolute; top: 0; left: 0; width: 1px; height: 1px; margin-left: -0.5px; transform-origin: 0 0; background: color-mix(in oklch, var(--foreground) 35%, transparent); opacity: 0; pointer-events: none; transition: opacity .12s; will-change: transform; }
-/* A row is a pill laid out like the bar's, stacked: the same 3px inset, 22px icon box, 3px gap and 10px end, its × in the icon's place. Rows begin where the bar's pills begin, after the mark's column, so icons, group titles and the search's text share one left edge. */
-.desktop-group { display: flex; flex-direction: column; gap: 4px; margin: 0 0 8px; }
-.desktop-group-title { margin: 10px 0 2px 6px; font-size: 10px; line-height: 16px; font-weight: 600; letter-spacing: .1em; text-transform: uppercase; color: var(--muted-foreground); }
-.desktop-row { position: relative; display: flex; align-items: center; width: 100%; height: 28px; padding: 0; border: 0; border-radius: 999px; background: transparent; color: var(--muted-foreground); text-align: left; transition: translate .18s cubic-bezier(.3, 1.2, .3, 1); }
+/* The rows under the search: one column, the chosen one filled as a pill. */
+.desktop-launcher-body { flex: 1; min-height: 0; overflow: auto; }
+/* Where the rows have more beyond an edge, they fade into what is behind them there. */
+.desktop-launcher-body.is-faded-top { mask-image: linear-gradient(to bottom, transparent, #000 32px); }
+.desktop-launcher-body.is-faded-bottom { mask-image: linear-gradient(to bottom, #000 calc(100% - 32px), transparent); }
+.desktop-launcher-body.is-faded-top.is-faded-bottom { mask-image: linear-gradient(to bottom, transparent, #000 32px, #000 calc(100% - 32px), transparent); }
+/* A row is a pill laid out like the bar's, stacked: the same 3px inset, 22px icon box, 3px gap and 10px end, its × in the icon's place; group titles start where the labels do. */
+.desktop-group { display: flex; flex-direction: column; gap: 2px; margin: 0 0 8px; }
+.desktop-group-title { margin: 10px 0 2px 28px; font-size: 10px; line-height: 16px; font-weight: 600; letter-spacing: .1em; text-transform: uppercase; color: var(--muted-foreground); }
+.desktop-row { position: relative; display: flex; align-items: center; flex-shrink: 0; width: 100%; height: 28px; padding: 0; border: 0; border-radius: 999px; background: transparent; color: var(--muted-foreground); text-align: left; }
 .desktop-row-app, .desktop-row-main { display: flex; align-items: center; gap: 3px; min-width: 0; padding: 0 10px 0 3px; border: 0; border-radius: 999px; background: transparent; color: inherit; text-align: left; }
-/* One state only, chosen: the text brightens and the row eases toward the dot, its × with it. */
 .desktop-row-main { flex: 1; align-self: stretch; }
-.desktop-row.is-cursor { color: var(--foreground); translate: -6px 0; }
+.desktop-row.is-cursor { color: var(--foreground); background: var(--desktop-ink-strong); }
 .desktop-row-label { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .desktop-row-note { padding-left: 8px; font-size: 11px; color: var(--muted-foreground); white-space: nowrap; }
 .desktop-row-window:hover .desktop-pill-icon, .desktop-row-window:has(:focus-visible) .desktop-pill-icon { opacity: 0; transform: scale(.5); }
 .desktop-row-window:hover .desktop-pill-close, .desktop-row-window:has(:focus-visible) .desktop-pill-close { opacity: 1; transform: none; pointer-events: auto; }
-/* Rows and titles drop into place from above, one after another, quickly. */
-.desktop-row, .desktop-group-title { animation: desktop-arrive .16s cubic-bezier(.2, .7, .2, 1) both; animation-delay: calc(min(var(--i, 0), 14) * 14ms); }
-@keyframes desktop-arrive { from { opacity: 0; transform: translateY(-6px); } }
-@media (prefers-reduced-motion: reduce) { .desktop-row, .desktop-group-title { animation: none; } .desktop-eye-small, .desktop-row, .desktop-pill-icon, .desktop-pill-close { transition: none; } }
+@media (prefers-reduced-motion: reduce) { .desktop-eye-small, .desktop-pill-icon, .desktop-pill-close { transition: none; } }
 .desktop-icon { display: block; flex-shrink: 0; }
-.desktop-muted { color: var(--muted-foreground); font-size: 11px; margin: 8px 0 8px 6px; }
+.desktop-muted { color: var(--muted-foreground); font-size: 11px; margin: 8px 0 8px 28px; }
 /* The legend at the foot: the keys, as small pills, and what they do. */
-.desktop-launcher-legend { display: flex; flex-wrap: wrap; gap: 6px 16px; flex-shrink: 0; padding: 10px 16px 12px; font-size: 11px; color: var(--muted-foreground); }
+.desktop-launcher-legend { display: flex; flex-wrap: wrap; gap: 6px 16px; flex-shrink: 0; padding: 4px 3px; font-size: 11px; color: var(--muted-foreground); }
 .desktop-launcher-legend span { display: inline-flex; align-items: center; gap: 4px; }
 .desktop-launcher-legend kbd { display: inline-grid; place-items: center; min-width: 18px; height: 18px; padding: 0 5px; border-radius: 999px; background: var(--desktop-ink); color: var(--foreground); font: inherit; font-size: 10px; }
 .desktop-empty { padding: 24px; }

package/src/desktop/index.ts

@@ -17,9 +17,10 @@
 // key in its own storage, so a reload lands back in it; a link with
 // `?session=KEY` joins it. A call that names no session reaches the current one, the last
 // touched, so the CLI's `desktop-open` lands in the tab last used; a session
-// left empty for a day goes on its own. The theme is the baba's, one resource,
-// not a session's. The launcher is the page's: it shows while its search has
-// focus, or while nothing is in front. An app's icon is a Lucide name; the
+// left empty for a day goes on its own. The baba's own theme is one resource,
+// not a session's, which the Maker's frames show; voss's pages wear the
+// person's, from voss's settings. The launcher is the page's: the mark's tab,
+// or quick over the app in front, and what is shown while nothing is. An app's icon is a Lucide name; the
 // system reads its drawing from the baba's Lucide package once and keeps it on
 // the app, so every door draws the same icon. An app may declare its routes,
 // the paths its windows may be at; a path none of them takes is refused.
@@ -41,6 +42,7 @@ export const sessionNames = [
   "laurel", "magnolia", "myrtle", "sequoia", "sycamore", "acacia", "baobab", "ginkgo",
 ] as const;
 export type { AppSpec } from "../ecs/baba.ts";
+export { keyCommands, keymapOf, commandOf, bindingOf, formatBinding, normalBinding, bindingNote, applyKeyChanges, type KeyCommand, type Keymap, type KeyOverrides, type KeyChanges } from "./keys.ts";
 export { route, matchRoute, canonicalPath, type RouteParams, type RouteMatch } from "./routes.ts";
 import type { AppSpec } from "../ecs/baba.ts";
 /** The old name. */
@@ -76,7 +78,7 @@ export function desktop(options: DesktopOptions) {
       desktopAnswer: { session: s.nullable(s.entity()), error: s.nullable(s.string()) },
       /** An app's icon, drawn: the shapes of the Lucide icon its `icon` names, none when the baba has no such icon. */
       desktopIcon: { name: s.string(), shapes: s.array(s.object({ tag: s.enum(...iconTags), attrs: s.object({}, { open: true }) })) },
-      /** The baba's settings, the same on every page: its theme. */
+      /** The baba's settings: its theme, which voss's own pages follow voss's settings over; kept for the Maker's frames and older states. */
       desktopSettings: resource(settingsShape, { theme: "system" }),
     },
     effects: {
@@ -262,7 +264,7 @@ export function desktop(options: DesktopOptions) {
       }),
 
       p.action("desktop-settings", {
-        summary: "set the baba's theme, the same on every page", args: { ...sessionArg, theme: s.optional(s.enum(...themes)) },
+        summary: "set the baba's own theme, as its frames in the Maker show it; voss's pages follow the theme in voss's settings", args: { ...sessionArg, theme: s.optional(s.enum(...themes)) },
         run: (w, a) => {
           sync(w); if (a.theme) w.set(settings, { theme: a.theme });
         },
@@ -293,8 +295,8 @@ export const vossApps = [
   { key: "maker", title: "Maker", icon: "hammer", group: "Voss" },
   { key: "state", title: "State", icon: "database", group: "Voss" },
   { key: "contract", title: "Contract", icon: "square-terminal", group: "Voss" },
-  { key: "promptware", title: "Promptware", icon: "book-open-text", group: "Voss" },
-  { key: "settings", title: "Settings", icon: "settings", group: "Voss" },
+  { key: "instructions", title: "Instructions", icon: "book-open-text", group: "Voss" },
+  { key: "settings", title: "Settings", icon: "settings", group: "Voss", routes: ["/", "/appearance", "/keyboard", "/about"] },
 ] as const satisfies readonly AppSpec[];
 export type VossApp = typeof vossApps[number]["key"];
 /** The app a baba that declares none has: its interface, whatever it is, in one window. */

package/src/desktop/keys.ts

@@ -0,0 +1,153 @@
+// The shell's keys: the commands a key can run, their default bindings, and a
+// binding's one spelling. A binding is written `Mod+Shift+K`: `Mod` is ⌘ on a
+// Mac and Ctrl elsewhere, then `Ctrl`, `Alt`, `Shift`, `Meta` as the keyboard
+// names them, in that order, and one key named as it sits on the keyboard,
+// not by what it types, so ⌥ on a Mac still binds the letter. The keys are
+// the person's, not a baba's: voss keeps those remapped in its own settings,
+// the same on every baba's desktop. A command not remapped has its default,
+// and a command may have none, so it runs only once a key is given it:
+// closing a tab, whose ⌘W browsers and the apps around them keep for closing
+// themselves, a press away from losing the page. The launcher's own keys, the
+// arrows, Enter and Escape, are fixed: they are how a palette is worked.
+
+/** The commands a key can run on the desktop, in the order the settings list them. */
+export const keyCommands: readonly { id: "launcher" | "previousTab" | "nextTab" | "closeTab"; title: string; summary: string; default: string | null }[] = [
+  { id: "launcher", title: "Quick launcher", summary: "Open the launcher over the app in front, and close it again.", default: "Mod+P" },
+  { id: "previousTab", title: "Previous tab", summary: "Go to the tab on the left; from the first, the launcher's.", default: "Mod+J" },
+  { id: "nextTab", title: "Next tab", summary: "Go to the tab on the right; from the last, the launcher's.", default: "Mod+K" },
+  { id: "closeTab", title: "Close tab", summary: "Close the window in front; its × and a middle click do too.", default: null },
+];
+export type KeyCommand = typeof keyCommands[number]["id"];
+/** A command's binding, each command's own or its default; null for a command no key runs. */
+export type Keymap = Record<KeyCommand, string | null>;
+/** What the settings keep: only the commands remapped. */
+export type KeyOverrides = Partial<Record<KeyCommand, string>>;
+
+const modifiers = ["Mod", "Ctrl", "Alt", "Shift", "Meta"] as const;
+type Modifier = typeof modifiers[number];
+/** Keys by `KeyboardEvent.code`: letters and digits, the punctuation, the arrows and the function keys. */
+const named: Record<string, string> = {
+  Minus: "-", Equal: "=", BracketLeft: "[", BracketRight: "]", Backslash: "\\", Semicolon: ";", Quote: "'", Backquote: "`", Comma: ",", Period: ".", Slash: "/",
+  ArrowLeft: "Left", ArrowRight: "Right", ArrowUp: "Up", ArrowDown: "Down", Space: "Space", Tab: "Tab", Enter: "Enter", Backspace: "Backspace", Delete: "Delete",
+  Home: "Home", End: "End", PageUp: "PageUp", PageDown: "PageDown",
+};
+const keyOfCode = (code: string): string | null => {
+  const m = /^(?:Key([A-Z])|Digit([0-9])|Numpad([0-9])|(F(?:[1-9]|1[0-2])))$/.exec(code);
+  if (m) return m[1] ?? m[2] ?? m[3] ?? m[4]!;
+  return named[code] ?? null;
+};
+const keys = new Set([..."ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", ...Object.values(named), ...Array.from({ length: 12 }, (_, i) => `F${i + 1}`)]);
+
+/** A binding's parts, or null when it is not one: one key, after modifiers each at most once; a key with no modifier only when it is a function key. */
+export function parseBinding(text: string): { mods: Modifier[]; key: string } | null {
+  const parts = text.split("+").map((p) => p.trim());
+  // A binding of the plus key itself is not offered: the key is `=` with Shift.
+  if (parts.some((p) => !p)) return null;
+  const key = parts.pop()!;
+  const k = key.length === 1 ? key.toUpperCase() : key;
+  const mods: Modifier[] = [];
+  for (const p of parts) {
+    const m = modifiers.find((x) => x.toLowerCase() === p.toLowerCase());
+    if (!m || mods.includes(m)) return null;
+    mods.push(m);
+  }
+  if (!keys.has(k)) return null;
+  // A plain key, or Shift with one, is what typing is: only function keys may go without a modifier.
+  if (!mods.some((m) => m !== "Shift") && !/^F\d+$/.test(k)) return null;
+  return { mods: modifiers.filter((m) => mods.includes(m)), key: k };
+}
+
+/** A binding in its one spelling, modifiers in order; null when it is not one. */
+export function normalBinding(text: string): string | null {
+  const b = parseBinding(text);
+  return b ? [...b.mods, b.key].join("+") : null;
+}
+
+/** Whether this is a Mac, where `Mod` is ⌘; elsewhere it is Ctrl. */
+export const isMac = (): boolean => {
+  // Read off the global, not typed by the DOM: the desktop system imports this module, and a baba's backend has no browser.
+  const nav = (globalThis as { navigator?: { userAgentData?: { platform?: string }; platform?: string; userAgent?: string } }).navigator;
+  return !!nav && /mac|iphone|ipad/i.test(nav.userAgentData?.platform ?? nav.platform ?? nav.userAgent ?? "");
+};
+
+/** The binding a key press spells, or null for a press of a modifier alone or of a key not offered. */
+export function bindingOf(e: { code: string; metaKey: boolean; ctrlKey: boolean; altKey: boolean; shiftKey: boolean }, mac = isMac()): string | null {
+  const key = keyOfCode(e.code);
+  if (!key) return null;
+  const mods: Modifier[] = [];
+  if (mac ? e.metaKey : e.ctrlKey) mods.push("Mod");
+  if (mac && e.ctrlKey) mods.push("Ctrl");
+  if (e.altKey) mods.push("Alt");
+  if (e.shiftKey) mods.push("Shift");
+  if (!mac && e.metaKey) mods.push("Meta");
+  return [...mods, key].join("+");
+}
+
+/** Each command's binding: the person's own where they remapped one, else the default. */
+export function keymapOf(overrides: KeyOverrides | undefined): Keymap {
+  return Object.fromEntries(keyCommands.map((c) => [c.id, overrides?.[c.id] ?? c.default])) as Keymap;
+}
+
+/** A binding as this keyboard presses it: off a Mac Ctrl is Mod, on one Meta is Mod, so a binding written with either still fires. */
+export function bindingOn(binding: string, mac = isMac()): string | null {
+  const b = parseBinding(binding);
+  if (!b) return null;
+  const same: Modifier = mac ? "Meta" : "Ctrl";
+  const mods = new Set(b.mods.map((m) => (m === same ? "Mod" : m)));
+  return [...modifiers.filter((m) => mods.has(m)), b.key].join("+");
+}
+
+/** The command a key press runs, if any. */
+export function commandOf(keymap: Keymap, e: Parameters<typeof bindingOf>[0], mac = isMac()): KeyCommand | null {
+  const b = bindingOf(e, mac);
+  if (!b) return null;
+  return keyCommands.find((c) => keymap[c.id] !== null && bindingOn(keymap[c.id]!, mac) === b)?.id ?? null;
+}
+
+/** A binding as people read it: `⌘⇧K` on a Mac, `Ctrl+Shift+K` elsewhere. */
+export function formatBinding(text: string, mac = isMac()): string {
+  const b = parseBinding(text);
+  if (!b) return text;
+  const arrows: Record<string, string> = { Left: "←", Right: "→", Up: "↑", Down: "↓" };
+  if (mac) {
+    const sign: Record<Modifier, string> = { Mod: "⌘", Ctrl: "⌃", Alt: "⌥", Shift: "⇧", Meta: "⌘" };
+    return [...b.mods.map((m) => sign[m]), arrows[b.key] ?? b.key].join("");
+  }
+  const word: Record<Modifier, string> = { Mod: "Ctrl", Ctrl: "Ctrl", Alt: "Alt", Shift: "Shift", Meta: "Win" };
+  return [...b.mods.map((m) => word[m]), arrows[b.key] ?? b.key].join("+");
+}
+
+/** What the browser keeps for itself, or does that people rely on: a page can take some of these, never all, and taking them costs something. */
+const browserKeys: Record<string, string> = {
+  "Mod+L": "the browser's address bar", "Mod+T": "a new browser tab", "Mod+N": "a new browser window", "Mod+Shift+N": "a private window",
+  "Mod+Shift+T": "reopening a closed tab", "Mod+Q": "quitting the browser", "Mod+R": "reloading the page", "Mod+F": "finding in the page",
+  "Mod+W": "closing the browser tab, or the app the page runs in", "Mod+Shift+W": "closing the browser window", "Mod+Tab": "switching browser tabs", "Ctrl+Tab": "switching browser tabs", "Mod+C": "copy", "Mod+V": "paste", "Mod+X": "cut", "Mod+Z": "undo", "Mod+A": "select all",
+  ...Object.fromEntries(Array.from({ length: 9 }, (_, i) => [`Mod+${i + 1}`, "switching browser tabs"])),
+};
+/** Why a binding is a poor choice, when the browser or the system already uses it; null when it is free. */
+export function bindingNote(binding: string): string | null {
+  const n = normalBinding(binding);
+  const why = n && browserKeys[n];
+  return why ? `Also ${why}: the browser may keep it.` : null;
+}
+
+/** A change to the keys: a binding per command, or null for its default. */
+export type KeyChanges = Partial<Record<KeyCommand, string | null>>;
+/** The remapped keys after a change: each binding spelled once, a default not kept as a remapping; refused when a binding is not one, or when two commands would share one. */
+export function applyKeyChanges(now: KeyOverrides | undefined, changes: KeyChanges): KeyOverrides {
+  const next: KeyOverrides = { ...now };
+  for (const c of keyCommands) {
+    const v = changes[c.id];
+    if (v === undefined) continue;
+    if (v === null) { delete next[c.id]; continue; }
+    const n = normalBinding(v);
+    if (!n) throw new Error(`${v} is not a binding: modifiers from Mod, Ctrl, Alt, Shift, Meta, then one key, as Mod+Shift+K`);
+    if (n === c.default) delete next[c.id]; else next[c.id] = n;
+  }
+  const bound = keyCommands.map((c) => [c, next[c.id] ?? c.default] as const);
+  for (const [c, b] of bound) {
+    const other = b !== null && bound.find(([o, ob]) => o.id !== c.id && ob === b);
+    if (other) throw new Error(`${b} would run both ${c.title} and ${other[0].title}`);
+  }
+  return next;
+}