From 5ea843684d61d7c73e910ff5f0f3ea53b6182302 Mon Sep 17 00:00:00 2001
From: nyblnet <306268465+nyblnet@users.noreply.github.com>
Date: Wed, 9 Sep 2026 02:21:26 +0100
Subject: [PATCH 1/2] kernel: the shared menu primitive, and the knowledge four
 apps each paid for
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tier 1 of the UI-primitives project. kernel/src/ui/menu.ts + menu.css define
the menu/dropdown once; scripts/test-ui-menu.ts guards it. Kernel half only —
each app's migration is that app zone's own change.

Measured by CONCEPT rather than by selector name, seven UI primitives are
implemented independently in all four apps. The dropdown is one design copied
four times, and the tell is the offset from the trigger: slides calc(100% +
4px), spaces +5px, dash +6px, type +6px. Nobody designed 4, 5, 6, 6.

The cost was never bytes — each app is one self-contained file, so shared code
is bundled into each anyway. Measured, this adds 604 compressed bytes to the
slides shell while slides still carries its own menu code as well. What four
copies actually cost is that no piece of hard-won knowledge about menus has
anywhere to live: CLAUDE.md's hard-won details 9 and 10 (a flex item's z-index
is a ceiling that caps every descendant; overflow-y:auto also clips
horizontally) are recorded in slides', spaces' AND dash's own source, because
each hit the same wall independently. Type records only one. menu.css is now
the one place either lesson lives.

What differed between the four was invisible, which is why it went unfixed:
five of slides' eight dropdowns had no outside-press dismissal, none closed on
Escape, three of the four apps publish no aria-expanded anywhere, no app had
arrow-key navigation, and slides and spaces each add document listeners per
dropdown and remove none. The primitive takes dash's single delegated listener
pair and mutual exclusion, spaces' ARIA and row semantics, slides' split-button
and phone-fold structure, and adds the arrow navigation and focus-return that
no app had. Slides is the basis for the CSS; where it had the least, the fuller
implementation won and the source says which.

Token VALUES are deliberately not settled: dash has diverged forward
(--line-strong, --shadow-pop, --radius-lg, light-dark()) and which way that
resolves is the maintainer's ruling, a later tier. Every value reads through a
--bkm-* property whose fallback lands on whatever the host app already defines,
so adoption changes no app's appearance. Only the offset (6px) and the stacking
level (60) had to be picked; both are the majority of four and both override.

The kernel ships CSS for the first time. Verified end to end, not assumed: the
rules inflate intact out of the built, compressed shell, and no build change
was needed. menu.ts does not import its own stylesheet, which is what lets the
rig exercise the primitive in node with no build machinery.

Verification: test-ui-menu 41 checks (mutation-tested — disabling the
disabled-row skip, the shared listener, the focus return and the nested-menu
guard each turn it red). test-sync 45368, test-preview 28, test-storage,
test-blobs, test-theme, test-tokenize, test-return-gate, test-export-secrets,
test-ci-registered 290 all green. slides, spaces and type typecheck and build;
shell-gate passes on the slides shell. dash could not be built (no node_modules
in this checkout) and test-autosave/test-validate fail identically on main —
both pre-existing, neither touched by this change.
---
 .github/workflows/ci.yml |  10 ++
 docs/DECISIONS.md        |  66 ++++++++
 kernel/src/ui/menu.css   | 264 ++++++++++++++++++++++++++++++
 kernel/src/ui/menu.ts    | 342 +++++++++++++++++++++++++++++++++++++++
 scripts/test-ui-menu.ts  | 263 ++++++++++++++++++++++++++++++
 5 files changed, 945 insertions(+)
 create mode 100644 kernel/src/ui/menu.css
 create mode 100644 kernel/src/ui/menu.ts
 create mode 100644 scripts/test-ui-menu.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e977494d..e8cf2dd4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -329,6 +329,16 @@ jobs:
         # plus the theming guard (every colour chain reaches a token each of the
         # four apps defines and themes). Each is mutation-caught.
         run: node scripts/test-ui-panel.ts
+      - name: Shared menu primitive rig
+        # kernel/src/ui/menu.ts replaces four hand-rolled dropdowns, and what
+        # differed between them was all INVISIBLE: three of the four apps
+        # publish no aria-expanded at all, five of slides' eight dropdowns never
+        # dismissed on an outside press, no app closed a menu on Escape or let
+        # an arrow key move through one, and two apps added a document listener
+        # per dropdown and removed none. Each of those is a check here, because
+        # every one of them is a regression a sighted developer with a mouse
+        # would never notice.
+        run: node scripts/test-ui-menu.ts
 
       - name: First-page preview rig
         # Every save writes a static render of page one for file-manager
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 2a0a374f..6170d7a4 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -6578,3 +6578,69 @@ Pointers: `kernel/src/ui/panel.ts`, `kernel/src/ui/panel.css`,
 `scripts/test-ui-panel.ts` (62 checks; the drag/RTL/collapse/persistence/drawer
 behaviours are each mutation-caught, and the theming guard is reproduced from
 tier 1 — to be factored into one shared helper when both primitives have landed).
+## 2026-09-09 — Shared UI primitives live in the kernel; the menu is the first, and values stay the app's
+
+**Decision.** The seven UI primitives every Bento app implements independently
+move into `kernel/src/ui/`, one at a time, each as its own serialized kernel PR.
+The menu/dropdown is first: `kernel/src/ui/menu.ts` + `menu.css`, guarded by
+`scripts/test-ui-menu.ts`. **This lands the shared definition only — each app's
+migration is that app zone's own change**, per the kernel zone's rule that a
+kernel PR never carries the app half.
+
+**Why, and it is not bytes.** Each Bento app is one self-contained file, so
+shared code is bundled into each anyway; measured, the primitive adds 604
+compressed bytes to the slides shell while slides still carries its own menu
+code as well. A general primitive can easily cost more than the specific thing
+one app needed. The return is elsewhere.
+
+Comparing CSS selector NAMES across the apps finds nothing — two apps
+implementing the identical dropdown as `.ed-menu` and `.dv-menu` register as
+zero overlap, which is why an earlier count of 11 shared selectors out of 2,156
+concluded, wrongly, that there was nothing to share. Compared by CONCEPT, seven
+primitives are implemented four times over. The dropdown is one design copied
+four times, and the tell is the offset from the trigger: slides `calc(100% +
+4px)`, spaces `+5px`, dash `+6px`, type `+6px`. Nobody designed 4, 5, 6, 6.
+
+**The real cost is that hard-won knowledge has nowhere to live.** CLAUDE.md's
+hard-won details 9 and 10 — a flex item's `z-index` is a CEILING that caps every
+descendant, and `overflow-y: auto` also clips HORIZONTALLY — cost slides real
+debugging. Slides, spaces AND dash each record both traps in their own source,
+because each hit the same wall independently. Type records only one. Three teams
+paid for the same two lessons, and the only home either lesson had was a comment
+in one app's CSS. `menu.css` is now that home.
+
+**What differed between the four was invisible, and that is what the primitive
+fixes.** Of slides' eight dropdowns, five had no outside-press dismissal at all,
+one hand-rolled it inline and two called a helper; none closed on Escape. Three
+of the four apps publish no `aria-expanded` anywhere. No app had arrow-key
+navigation. slides and spaces each add document listeners per dropdown and
+remove none. So the primitive takes dash's single delegated listener pair and
+mutual exclusion, spaces' ARIA and disabled/selected row semantics, slides'
+split-button and phone-fold structure — and adds the arrow-key navigation and
+focus-return that no app had.
+
+**"Slides is the basis" is true of the CSS and false of the behaviour.** It was
+the maintainer's default and it holds for structure; where slides has the least,
+the fuller implementation wins on its merits and this entry says which.
+
+**Token VALUES are deliberately NOT settled here.** slides, spaces and type
+agree; dash has diverged forward with `--line-strong`, `--shadow-pop`,
+`--radius-lg` and a `light-dark()` dark mode. Which way that resolves is a
+maintainer's ruling and a later tier of this work. Until then every value in
+`menu.css` reads through a `--bkm-*` property whose fallback chain lands on
+whatever the host app already defines, so an app that adopts the primitive keeps
+the appearance it has today. Only two values had to be picked, because a shared
+rule cannot hold four: the trigger offset (6px) and the stacking level (60),
+each the majority of the four and each overridable per app.
+
+**The kernel ships CSS now, which it never did before.** Verified end to end
+rather than assumed: an app's `import '../../kernel/src/ui/menu.css'` is folded
+by Vite into the single stylesheet that `scripts/postbuild-compress.mjs`
+deflates into the `#bento-rt-css` payload, and the rules inflate intact out of
+the built shell. No build change was needed. `menu.ts` deliberately does NOT
+import its own stylesheet: keeping them separate is what lets the rig exercise
+the whole primitive in node with no build machinery and no CSS-import stub.
+
+Pointers: `kernel/src/ui/menu.ts` (the four-app comparison, function by
+function), `kernel/src/ui/menu.css` (details 9 and 10, written down once),
+`scripts/test-ui-menu.ts` (what each check guards, and which app's gap it is).
diff --git a/kernel/src/ui/menu.css b/kernel/src/ui/menu.css
new file mode 100644
index 00000000..614029cf
--- /dev/null
+++ b/kernel/src/ui/menu.css
@@ -0,0 +1,264 @@
+/* SPDX-License-Identifier: MIT
+   Copyright (c) 2026 The Bento authors
+
+   THE SHARED MENU PRIMITIVE'S STYLES. See menu.ts for why this exists and what
+   each of the four apps contributed.
+
+   THIS IS THE FIRST CSS THE KERNEL HAS EVER SHIPPED. It reaches a build the way
+   every other kernel module does — an app imports it, and Vite folds it into the
+   one stylesheet that `scripts/postbuild-compress.mjs` then deflates into the
+   `#bento-rt-css` payload. Nothing in the build needed changing for that, but it
+   is worth stating plainly, because that script matches exactly ONE
+   `<style rel="stylesheet">` and has been fooled before by a `<style>` that was
+   really a JS string literal.
+
+   ————— VALUES ARE THE HOST APP'S, STRUCTURE AND BEHAVIOUR ARE SHARED —————
+
+   The four apps disagree about tokens. slides, spaces and type agree with each
+   other; dash has diverged FORWARD — `--line-strong`, `--shadow-pop`,
+   `--radius-lg`, and a `light-dark()` dark mode — and nobody decided that, it
+   happened. Resolving it is a maintainer's ruling and it is tier 4 of this
+   project, so this file does not pre-empt it either way.
+
+   Instead every value reads through a `--bkm-*` property whose fallback chain
+   lands on whatever the host already defines. An app that defines
+   `--line-strong` (dash) gets its stronger edge; an app that does not (the
+   other three) falls through to `--line`. Adopting this primitive therefore
+   changes no app's appearance, which is what makes tier 1 safe to land before
+   the token question is settled. An app that wants something else sets
+   `--bkm-*` on its own root — type will need `--bkm-bg: var(--field)`, because
+   it paints menus on `--field` where the other three use `--surface`.
+
+   Two values could not be deferred, because a shared rule has to pick one:
+
+     the offset from the trigger   4px / 5px / 6px / 6px  →  6px
+     the stacking level            50 / 60 / 60 / 60      →  60
+
+   Both are the majority of the four, and both stay overridable. slides moves
+   2px and spaces 1px on adoption; that difference was never designed. */
+
+.bkm {
+  /* The wrapper is the positioning context. It must be `relative` and it must
+     not establish anything else — see the z-index note below. */
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+
+.bkm-menu {
+  display: none;
+  position: absolute;
+  top: calc(100% + var(--bkm-gap, 6px));
+  inset-inline-start: 0;
+  flex-direction: column;
+  min-width: var(--bkm-min-width, 200px);
+  padding: 5px;
+  background: var(--bkm-bg, var(--surface, #fff));
+  border: 1px solid var(--bkm-border, var(--line-strong, var(--line, #e3e8ef)));
+  border-radius: var(--bkm-radius, var(--radius-lg, var(--radius, 10px)));
+  box-shadow: var(--bkm-shadow, var(--shadow-pop, 0 12px 32px rgb(20 30 45 / 0.16)));
+
+  /* ————— HARD-WON DETAIL 9, and the reason this primitive exists —————
+
+     `z-index` on the BAR that contains a menu is a CEILING, not just an order.
+     A topbar is a flex item of the app root, and a flex item honours `z-index`
+     even at `position: static` — so the value opens a stacking context that
+     caps every descendant. In slides the bar sat at 20 and this menu asked for
+     50; it was clamped to 20, and the phone panel drawers at 40 painted
+     straight over it. The menu rendered in full and every click landed on the
+     panel behind it. Raising THIS number can never fix that — only the
+     ceiling moves.
+
+     Diagnose it with `document.elementsFromPoint()`, which is how it was found:
+     the menu sat fourth in the stack under its own coordinates.
+
+     slides, spaces and dash each hit this independently and each wrote it down
+     in their own source. Type hit it and did not. This comment is the first
+     place that knowledge lives once rather than three times. */
+  z-index: var(--bkm-z, 60);
+}
+
+.bkm.bkm-open > .bkm-menu {
+  display: flex;
+}
+
+/* DIRECT child, not any descendant. Phone chrome demotes whole dropdown widgets
+   into a ⋯ menu, so a descendant selector opens their popups too — slides' ⋯
+   came up with the entire language list already unrolled inside it. Every
+   `.bkm-menu` is appended straight onto its own `.bkm`, so `>` is exact. */
+
+/* A menu hanging off a control near the inline-end edge grows AWAY from the
+   screen if it is start-anchored. Three of the four apps discovered this and
+   each wrote a bespoke selector for it — `.ed-topbar.ed-bar-fold .ed-menu`,
+   `.sp-dd:last-child .sp-ddmenu`, `.dx-data-dd > .dx-menu`. It is an option
+   here instead. */
+.bkm.bkm-end > .bkm-menu {
+  inset-inline-start: auto;
+  inset-inline-end: 0;
+}
+
+/* Never wider than the screen. dash's save menu is 260px and hangs off a button
+   in the right half of the bar; on a phone a start-anchored panel that wide
+   simply walks off the edge. */
+.bkm-menu {
+  max-width: calc(100vw - 16px);
+}
+
+/* ————— rows ————— */
+
+.bkm-item {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  width: 100%;
+  font: inherit;
+  font-size: var(--bkm-font-size, 13px);
+  color: var(--bkm-ink, var(--ink-2, var(--ink, #1e2a3a)));
+  text-align: start;
+  background: transparent;
+  border: 0;
+  border-radius: var(--bkm-item-radius, 7px);
+  padding: 7px 9px;
+  cursor: pointer;
+}
+
+.bkm-item:hover {
+  background: var(--bkm-hover, var(--hover, var(--chrome-2, rgb(0 0 0 / 0.05))));
+}
+
+/* The keyboard has to leave as clear a trail as the mouse does. No app's menu
+   had arrow-key navigation at all, so none of them needed this; all four
+   inherit both at once. `:focus-visible` rather than `:focus` so a pointer user
+   never sees a ring they did not ask for. */
+.bkm-item:focus-visible {
+  outline: 2px solid var(--bkm-focus, var(--accent-ink, currentColor));
+  outline-offset: -2px;
+  background: var(--bkm-hover, var(--hover, var(--chrome-2, rgb(0 0 0 / 0.05))));
+}
+
+/* Present but not runnable — folded undo/redo on a phone. DISABLED, not hidden,
+   so the menu does not change shape as you edit. 0.35 is dash's figure for a
+   dead control and it is the one with a reason attached. */
+.bkm-item.bkm-off {
+  opacity: 0.35;
+  cursor: default;
+  pointer-events: none;
+}
+
+.bkm-item.bkm-selected .bkm-text {
+  font-weight: 700;
+}
+
+.bkm-ico {
+  display: inline-flex;
+  color: var(--bkm-ico, var(--muted, #6b7789));
+  flex: none;
+}
+
+.bkm-ico svg {
+  display: block;
+}
+
+.bkm-body {
+  display: block;
+  min-width: 0;
+}
+
+/* A row that TEACHES rather than naming a command needs to WRAP. dash cut
+   "Typed columns — for volume, joins and charts" mid-phrase inside a 220px
+   menu, because the row inherited a one-line ellipsis meant for "Rename". A
+   truncated explanation of a central concept explains nothing and reads as a
+   bug. */
+.bkm-hint {
+  display: block;
+  font-size: var(--bkm-hint-size, 12px);
+  line-height: 1.35;
+  color: var(--muted, #6b7789);
+  white-space: normal;
+}
+
+.bkm-text {
+  display: block;
+}
+
+.bkm-sep {
+  height: 1px;
+  background: var(--bkm-border, var(--line, #e3e8ef));
+  margin: 4px 6px;
+}
+
+/* ————— HARD-WON DETAIL 10: a scrolling menu is a CLIPPING BOX —————
+
+   A menu that can outgrow the screen needs a `max-height`, and `overflow-y:
+   auto` cannot be had on its own: set either axis to a non-`visible` value and
+   the browser computes the OTHER to `auto` too. So the moment a menu scrolls,
+   it clips horizontally as well.
+
+   slides paid for this. Phone chrome demotes whole dropdown widgets (Share,
+   Language) into the ⋯ menu, and the share popover is 250px anchored to its
+   parent's end — inside a 200px menu it hung 55px off the left and 69px below,
+   both silently cut, and the properties panel underneath showed THROUGH the
+   gap, so the popover looked interleaved with the panel behind it.
+
+   A floating child can never escape a scroll container. So it stops floating:
+   a menu nested inside a scrolling menu renders as a SECTION of the list,
+   scrolling with it and taking its width. Nothing can be clipped because
+   nothing overhangs.
+
+   dash has two menus built this way today with nothing floating inside them
+   yet. Nothing stopped the next person putting something there; now this rule
+   does, for every app at once. */
+.bkm-menu.bkm-scroll {
+  max-height: var(--bkm-max-height, calc(100dvh - 96px));
+  overflow-y: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+.bkm-menu.bkm-scroll .bkm-menu {
+  position: static;
+  min-width: 0;
+  max-width: none;
+  max-height: none;
+  overflow: visible;
+  box-shadow: none;
+  background: transparent;
+  border: 0;
+  border-radius: 0;
+  border-block: 1px solid var(--bkm-border, var(--line, #e3e8ef));
+  margin-block: 3px;
+  padding-inline: 6px;
+}
+
+/* ————— a bar that scrolls —————
+
+   Below the fold's floor a topbar scrolls itself: fully folded slides' bar
+   still needs ~356px and an iPhone SE is 320px, so the excess was simply cut
+   off and ⋯ could not be reached at all. A scroll container clips BOTH axes
+   (see above), so a menu hanging off a button in that bar would now be cut off
+   by the bar itself. `fixed` takes it out of that clip. It costs nothing extra
+   to anchor, because a bar this narrow pins its menus to the end of the screen
+   rather than to their trigger anyway.
+
+   The one thing this cannot read from CSS is where the bar ENDS, because that
+   moves with the safe-area insets — the app publishes it as `--bkm-bar-bottom`
+   (slides already computes exactly this as `--ed-bar-bottom`). */
+.bkm-fixed.bkm-open > .bkm-menu {
+  position: fixed;
+  top: calc(var(--bkm-bar-bottom, 56px) + var(--bkm-gap, 6px));
+  inset-inline-end: max(6px, env(safe-area-inset-right), var(--tray-safe-right, 0px));
+  inset-inline-start: auto;
+}
+
+/* Touch targets. A menu row on a phone is a 44px target like everything else. */
+@media (max-width: 700px) {
+  .bkm-item {
+    padding-block: 11px;
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  /* Deliberately no open/close animation. Three of the four apps have none, the
+     fourth animates only its phone sheet, and a menu that fades is a menu whose
+     first click can land before it is there. Kept as an explicit note so the
+     absence reads as a decision rather than an oversight. */
+}
diff --git a/kernel/src/ui/menu.ts b/kernel/src/ui/menu.ts
new file mode 100644
index 00000000..7b866d5b
--- /dev/null
+++ b/kernel/src/ui/menu.ts
@@ -0,0 +1,342 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+//
+// THE SHARED MENU / DROPDOWN PRIMITIVE — the first of the kernel UI primitives.
+//
+// WHY THIS EXISTS. Four apps had four dropdowns, and they are one design copied
+// four times. The tell is the offset from the trigger: slides `calc(100% + 4px)`,
+// spaces `+5px`, dash `+6px`, type `+6px`. Nobody designed 4, 5, 6, 6 — that is
+// copy-paste-and-tweak, and it is history rather than intent.
+//
+// The cost was never bytes. Each app is one self-contained file, so shared code
+// is bundled into each anyway and this primitive may well make the shells
+// slightly BIGGER. What four copies actually cost is that no piece of hard-won
+// knowledge about menus has anywhere to live. CLAUDE.md's hard-won details 9 and
+// 10 — a flex item's z-index is a CEILING that caps every descendant, and
+// `overflow-y: auto` also clips HORIZONTALLY — were paid for by slides, and
+// reached spaces and dash only because each of them independently hit the same
+// wall. Type records only one of the two. Three teams bought the same two
+// lessons. A shared primitive is the only place that knowledge can live once.
+//
+// WHAT EACH APP CONTRIBUTED, because "slides is the basis" is true of the CSS
+// and false of the behaviour, and the difference is the whole point:
+//
+//   slides  the richest STRUCTURE — the split button, and the phone treatment
+//           where a folded bar scrolls and its menus go `position: fixed`
+//           against `--ed-bar-bottom` to escape the scroller's clip. Also the
+//           WEAKEST behaviour of the four: of its eight dropdowns, five have no
+//           outside-press dismissal at all, one hand-rolls it inline, two call a
+//           helper — and not one of them closes on Escape or carries a single
+//           `aria-haspopup` or `aria-expanded`.
+//   dash    the best BEHAVIOUR — one delegated listener pair for every menu in
+//           the app rather than a fresh pair per instance, mutual exclusion
+//           (opening one shuts the others), Escape, and dismiss-on-choose.
+//   spaces  the only real ACCESSIBILITY — `aria-haspopup`, `aria-expanded`,
+//           `role=menu`/`menuitem`, `aria-current` for a selected row and
+//           `aria-disabled` for a row that exists but cannot run right now.
+//           Also the only viewport-aware placement (`place()`), and the phone
+//           bottom-sheet.
+//   type    the thinnest, and the one that shows what copying costs: it hides
+//           with the `hidden` attribute rather than a state class (a fifth
+//           mechanism), hardcodes its radius and shadow instead of using
+//           tokens, and paints on `--field` where the other three use
+//           `--surface`.
+//
+// So this primitive takes dash's delegation, spaces' semantics, and slides'
+// structure — and adds the one thing NO app has: arrow-key navigation. A menu
+// you can open with the keyboard and then not move through is a menu a keyboard
+// user is not actually inside.
+//
+// WHAT THIS DELIBERATELY DOES NOT DECIDE. The four apps disagree on token
+// VALUES — dash has diverged forward with `--line-strong`, `--shadow-pop`,
+// `--radius-lg` and a `light-dark()` dark mode, against the other three's
+// `--line`, a literal shadow and `--radius`. Which way that resolves is the
+// maintainer's ruling and it is tier 4 of this project, not this file's to make.
+// So every value here reads through a `--bkm-*` custom property whose fallback
+// chain lands on whatever the host app already defines (see menu.css). An app
+// adopting this primitive keeps the look it has today; only the structure and
+// the behaviour are shared. The two places that could not be deferred are the
+// trigger offset and the stacking level, where a single value had to be picked:
+// 6px and 60, each the majority of the four, each overridable per app.
+
+/** A row in a menu. `off` is a command that exists but cannot run right now;
+ *  `selected` is the choice a view is currently on. They are different things —
+ *  spaces learned that when they arrived as two separate 5th parameters on two
+ *  branches — and a row may be neither. */
+export interface MenuItemOpts {
+  /** Inline SVG (or any markup) for the row's leading icon. */
+  icon?: string
+  /** Secondary line under the label. */
+  hint?: string
+  /** Present but not runnable: dimmed, unfocusable, announced `aria-disabled`. */
+  off?: boolean
+  /** The option currently in force: announced `aria-current`. */
+  selected?: boolean
+  /** Skip the default "choosing a row closes the menu". */
+  keepOpen?: boolean
+}
+
+export interface MenuOpts {
+  /** Extra classes for the wrapper, e.g. an app's own `ed-split`. */
+  className?: string
+  /** Extra classes for the popup itself, e.g. an app's `ed-share-pop`. */
+  menuClass?: string
+  /** Anchor the popup to the end of the trigger rather than the start. Used by
+   *  a menu that hangs off a control near the inline-end edge, where a
+   *  start-anchored popup grows off the screen. */
+  alignEnd?: boolean
+  /** Rebuild the rows every time it opens. A row's label can be a function of
+   *  state — "Hide comments" becomes "Show comments" — and rendering it once at
+   *  mount leaves it permanently wrong after the first use. */
+  fill?: (menu: HTMLElement, close: () => void) => void
+}
+
+export interface Menu {
+  /** The positioned wrapper. Put this in the bar. */
+  readonly root: HTMLElement
+  /** The button that opens it. */
+  readonly trigger: HTMLButtonElement
+  /** The popup. Append rows here, or let `fill` do it. */
+  readonly menu: HTMLElement
+  readonly isOpen: boolean
+  open(): void
+  close(): void
+  toggle(): void
+  /** Build a row. Appends to the popup unless `into` says otherwise. */
+  item(label: string, onClick: () => void, opts?: MenuItemOpts): HTMLButtonElement
+  /** A hairline between groups of rows. */
+  separator(): HTMLElement
+  /** Drop the wrapper and forget this menu. Safe to call twice. */
+  destroy(): void
+}
+
+const OPEN = 'bkm-open'
+
+/** Every live menu, so one document listener can serve all of them.
+ *
+ *  This is dash's model and it is the correct one. slides and spaces both add a
+ *  `document.addEventListener` (two, in spaces' case) per dropdown and remove
+ *  neither, so a long-lived editor accumulates a listener for every menu it has
+ *  ever built — including menus whose elements are long gone. Here the document
+ *  listeners are installed once, on the first menu, and removed again when the
+ *  last one is destroyed. */
+const live = new Set<MenuState>()
+
+interface MenuState {
+  root: HTMLElement
+  trigger: HTMLButtonElement
+  menu: HTMLElement
+  close(): void
+}
+
+let wired = false
+
+function onDocPointerDown(ev: Event): void {
+  const target = ev.target as Node | null
+  for (const m of live) {
+    if (!m.root.classList.contains(OPEN)) continue
+    if (target && m.root.contains(target)) continue
+    m.close()
+  }
+}
+
+function onDocKeyDown(ev: KeyboardEvent): void {
+  const open = [...live].find((m) => m.root.classList.contains(OPEN))
+  if (!open) return
+  if (ev.key === 'Escape') {
+    ev.stopPropagation()
+    open.close()
+    // Focus goes back to the trigger, not to nowhere. Escaping a menu into
+    // `document.body` is how a keyboard user loses their place entirely.
+    open.trigger.focus()
+    return
+  }
+  if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp' || ev.key === 'Home' || ev.key === 'End') {
+    const rows = focusableRows(open.menu)
+    if (!rows.length) return
+    ev.preventDefault()
+    const at = rows.indexOf(document.activeElement as HTMLElement)
+    let next: number
+    if (ev.key === 'Home') next = 0
+    else if (ev.key === 'End') next = rows.length - 1
+    else if (ev.key === 'ArrowDown') next = at < 0 ? 0 : (at + 1) % rows.length
+    else next = at < 0 ? rows.length - 1 : (at - 1 + rows.length) % rows.length
+    rows[next].focus()
+  }
+}
+
+/** Rows a keyboard may land on: not the disabled ones, and not a nested menu's
+ *  rows. A demoted widget's popup renders INSIDE the ⋯ list on a phone (see
+ *  menu.css), so a bare descendant query would walk into it. */
+function focusableRows(menu: HTMLElement): HTMLElement[] {
+  return [...menu.querySelectorAll<HTMLElement>('.bkm-item')].filter(
+    (b) => b.getAttribute('aria-disabled') !== 'true' && b.closest('.bkm-menu') === menu,
+  )
+}
+
+function wire(): void {
+  if (wired) return
+  wired = true
+  document.addEventListener('pointerdown', onDocPointerDown)
+  document.addEventListener('keydown', onDocKeyDown)
+}
+
+function unwire(): void {
+  if (!wired || live.size) return
+  wired = false
+  document.removeEventListener('pointerdown', onDocPointerDown)
+  document.removeEventListener('keydown', onDocKeyDown)
+}
+
+/**
+ * Build a dropdown menu.
+ *
+ * `label` may be empty for an icon-only trigger, but `tip` never is: an
+ * icon-only control leans on its `title` for its name, and that name is also
+ * what `aria-label` publishes.
+ */
+export function createMenu(label: string, tip: string, opts: MenuOpts = {}): Menu {
+  const root = document.createElement('div')
+  root.className = 'bkm' + (opts.className ? ' ' + opts.className : '')
+
+  const trigger = document.createElement('button')
+  trigger.type = 'button'
+  trigger.className = 'bkm-trigger'
+  trigger.title = tip
+  trigger.setAttribute('aria-label', tip)
+  trigger.setAttribute('aria-haspopup', 'menu')
+  trigger.setAttribute('aria-expanded', 'false')
+  if (label) {
+    // The word is a SPAN, not a bare text node, so a narrow bar can drop the
+    // label and keep the icon. Both slides and spaces arrived at this
+    // independently; it is the only way to collapse a labelled control without
+    // also losing it.
+    const span = document.createElement('span')
+    span.className = 'bkm-label'
+    span.textContent = label
+    trigger.appendChild(span)
+  }
+
+  const menu = document.createElement('div')
+  menu.className = 'bkm-menu' + (opts.menuClass ? ' ' + opts.menuClass : '')
+  menu.setAttribute('role', 'menu')
+  if (opts.alignEnd) root.classList.add('bkm-end')
+
+  let dead = false
+
+  const state: MenuState = {
+    root,
+    trigger,
+    menu,
+    close(): void {
+      root.classList.remove(OPEN)
+      trigger.setAttribute('aria-expanded', 'false')
+    },
+  }
+
+  const open = (): void => {
+    if (dead) return
+    // Mutual exclusion: opening one menu shuts every other. Without it a bar
+    // ends up with two popups overlapping each other, which dash fixed and the
+    // other three did not.
+    for (const m of live) if (m !== state) m.close()
+    if (opts.fill) {
+      menu.replaceChildren()
+      opts.fill(menu, state.close)
+    }
+    root.classList.add(OPEN)
+    trigger.setAttribute('aria-expanded', 'true')
+  }
+
+  const api: Menu = {
+    root,
+    trigger,
+    menu,
+    get isOpen(): boolean {
+      return root.classList.contains(OPEN)
+    },
+    open,
+    close: state.close,
+    toggle(): void {
+      if (root.classList.contains(OPEN)) state.close()
+      else open()
+    },
+    item(text: string, onClick: () => void, io: MenuItemOpts = {}): HTMLButtonElement {
+      const b = document.createElement('button')
+      b.type = 'button'
+      b.className =
+        'bkm-item' + (io.off ? ' bkm-off' : '') + (io.selected ? ' bkm-selected' : '')
+      b.setAttribute('role', 'menuitem')
+      if (io.off) b.setAttribute('aria-disabled', 'true')
+      if (io.selected) b.setAttribute('aria-current', 'true')
+      if (io.icon) {
+        const ico = document.createElement('span')
+        ico.className = 'bkm-ico'
+        ico.innerHTML = io.icon
+        b.appendChild(ico)
+      }
+      const body = document.createElement('span')
+      body.className = 'bkm-body'
+      const strong = document.createElement('span')
+      strong.className = 'bkm-text'
+      strong.textContent = text
+      body.appendChild(strong)
+      if (io.hint) {
+        const hint = document.createElement('span')
+        hint.className = 'bkm-hint'
+        hint.textContent = io.hint
+        body.appendChild(hint)
+      }
+      b.appendChild(body)
+      b.addEventListener('click', (ev) => {
+        ev.stopPropagation()
+        if (io.off) return
+        if (!io.keepOpen) state.close()
+        onClick()
+      })
+      menu.appendChild(b)
+      return b
+    },
+    separator(): HTMLElement {
+      const sep = document.createElement('div')
+      sep.className = 'bkm-sep'
+      // A hairline is decoration; a screen reader walking the menu should not
+      // stop on it.
+      sep.setAttribute('role', 'separator')
+      menu.appendChild(sep)
+      return sep
+    },
+    destroy(): void {
+      if (dead) return
+      dead = true
+      live.delete(state)
+      root.remove()
+      unwire()
+    },
+  }
+
+  trigger.addEventListener('click', (ev) => {
+    ev.stopPropagation()
+    api.toggle()
+  })
+  // ArrowDown on a CLOSED trigger opens it and lands on the first row — the
+  // standard menu-button gesture, and the one that makes the arrow handling
+  // above reachable without a mouse.
+  trigger.addEventListener('keydown', (ev) => {
+    if (ev.key !== 'ArrowDown' || root.classList.contains(OPEN)) return
+    ev.preventDefault()
+    open()
+    focusableRows(menu)[0]?.focus()
+  })
+
+  root.append(trigger, menu)
+  live.add(state)
+  wire()
+  return api
+}
+
+/** Close every open menu. For an app that needs to shut the bar on its own
+ *  events — starting a presentation, entering a modal. */
+export function closeAllMenus(): void {
+  for (const m of live) m.close()
+}
diff --git a/scripts/test-ui-menu.ts b/scripts/test-ui-menu.ts
new file mode 100644
index 00000000..4a24c167
--- /dev/null
+++ b/scripts/test-ui-menu.ts
@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// The shared kernel MENU primitive — behaviour rig.
+//
+//   node scripts/test-ui-menu.ts        (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. `kernel/src/ui/menu.ts` replaces four hand-rolled dropdowns
+// with one, and the case for doing that was never bytes — it was that the
+// INVISIBLE behaviour differed in every app and no app had all of it. Every
+// check below guards a gap that is real in the tree today:
+//
+//   1. ARIA. Three of the four apps publish nothing. `aria-haspopup` appears
+//      once in spaces and nowhere else; `aria-expanded` is absent from slides
+//      and dash entirely. A menu that does not say it is a menu, or whether it
+//      is open, is a menu a screen reader cannot describe.
+//   2. OUTSIDE-PRESS DISMISSAL. slides builds eight dropdowns; two call its
+//      `closeOnOutsidePress` helper, one hand-rolls the same listener inline,
+//      and five have no dismissal at all — they stay open until you click the
+//      trigger again.
+//   3. ESCAPE. slides has no Escape handling on any dropdown. The 74 `Escape`
+//      matches in its source are dialogs and overlays.
+//   4. FOCUS RETURN. Escaping a menu into `document.body` loses a keyboard
+//      user's place. Focus goes back to the trigger.
+//   5. ARROW-KEY NAVIGATION. NO app has it. A menu you can open with the
+//      keyboard and then not move through is a menu you are not inside.
+//   6. MUTUAL EXCLUSION. Only dash shuts the other menus when one opens; the
+//      others will happily overlap two popups.
+//   7. THE LISTENER LEAK. slides and spaces both add document listeners PER
+//      DROPDOWN and remove none — spaces adds two. A long-lived editor
+//      accumulates a listener for every menu it has ever built, including ones
+//      whose elements are long gone. This rig asserts the count directly,
+//      because it is the kind of regression that is invisible until a profile.
+//   8. ROWS REBUILT ON OPEN. A row's label can be a function of state — "Hide
+//      comments" becomes "Show comments" — and rendering it once at mount
+//      leaves it permanently wrong after the first use. Type hit this and
+//      wrote `refreshMenuLabels` for it.
+//   9. A NESTED MENU IS NOT PART OF THE OUTER ONE. Phone chrome demotes whole
+//      dropdown widgets into a ⋯ list, so a bare descendant query walks into
+//      the nested popup — which is how slides' ⋯ once came up with the entire
+//      language list already unrolled inside it.
+
+import { installDom, fireDoc } from './lib/dash-dom.ts'
+
+const { doc } = installDom()
+const bar = doc.createElement('div')
+doc.body.appendChild(bar)
+
+const { createMenu, closeAllMenus } = await import('../kernel/src/ui/menu.ts')
+
+let failures = 0
+let checks = 0
+function ok(what: string, cond: unknown): void {
+  checks++
+  if (cond) return
+  failures++
+  console.error(`  FAIL  ${what}`)
+}
+function eq(what: string, got: unknown, want: unknown): void {
+  checks++
+  if (got === want) return
+  failures++
+  console.error(`  FAIL  ${what}\n        got  ${String(got)}\n        want ${String(want)}`)
+}
+
+const click = (el: unknown): void =>
+  (el as { dispatchEvent(e: unknown): void }).dispatchEvent({
+    type: 'click', preventDefault() {}, stopPropagation() {},
+  })
+const key = (k: string): void =>
+  fireDoc(doc, 'keydown', { key: k, preventDefault() {}, stopPropagation() {} })
+const triggerKey = (el: unknown, k: string): void =>
+  (el as { dispatchEvent(e: unknown): void }).dispatchEvent({
+    type: 'keydown', key: k, preventDefault() {}, stopPropagation() {},
+  })
+const pressOutside = (): void => fireDoc(doc, 'pointerdown', { target: doc.body })
+// deno-lint-ignore no-explicit-any
+const A = (el: unknown, k: string): string | null => (el as any).getAttribute(k)
+
+// ————— 1. structure and ARIA —————
+{
+  const m = createMenu('Insert', 'Insert an element')
+  bar.appendChild(m.root as never)
+  eq('trigger announces a menu', A(m.trigger, 'aria-haspopup'), 'menu')
+  eq('trigger starts collapsed', A(m.trigger, 'aria-expanded'), 'false')
+  eq('trigger carries its name', A(m.trigger, 'aria-label'), 'Insert an element')
+  eq('popup is a menu', A(m.menu, 'role'), 'menu')
+
+  const row = m.item('Picture', () => {})
+  eq('a row is a menuitem', A(row, 'role'), 'menuitem')
+
+  const off = m.item('Redo', () => {}, { off: true })
+  eq('an unrunnable row says so', A(off, 'aria-disabled'), 'true')
+  const sel = m.item('Board', () => {}, { selected: true })
+  eq('the current choice says so', A(sel, 'aria-current'), 'true')
+  ok('a separator is not an item', A(m.separator(), 'role') === 'separator')
+
+  click(m.trigger)
+  ok('clicking the trigger opens it', m.isOpen)
+  eq('open is published', A(m.trigger, 'aria-expanded'), 'true')
+  click(m.trigger)
+  ok('clicking again closes it', !m.isOpen)
+  eq('closed is published', A(m.trigger, 'aria-expanded'), 'false')
+  m.destroy()
+}
+
+// ————— 2. outside press dismisses; inside press does not —————
+{
+  const m = createMenu('File', 'File')
+  bar.appendChild(m.root as never)
+  const row = m.item('Save', () => {})
+  m.open()
+  fireDoc(doc, 'pointerdown', { target: row })
+  ok('a press INSIDE the menu leaves it open', m.isOpen)
+  pressOutside()
+  ok('a press outside dismisses it', !m.isOpen)
+  m.destroy()
+}
+
+// ————— 3/4. Escape closes, and focus goes back to the trigger —————
+{
+  const m = createMenu('View', 'View')
+  bar.appendChild(m.root as never)
+  const row = m.item('Zoom', () => {})
+  m.open()
+  ;(row as unknown as { focus(): void }).focus()
+  key('Escape')
+  ok('Escape closes the menu', !m.isOpen)
+  eq('focus returns to the trigger', doc.activeElement, m.trigger)
+  m.destroy()
+}
+
+// ————— 5. arrow-key navigation, which no app has —————
+{
+  const m = createMenu('Go', 'Go')
+  bar.appendChild(m.root as never)
+  const a = m.item('First', () => {})
+  const dead = m.item('Unavailable', () => {}, { off: true })
+  const c = m.item('Last', () => {})
+
+  triggerKey(m.trigger, 'ArrowDown')
+  ok('ArrowDown on a closed trigger opens it', m.isOpen)
+  eq('…and lands on the first row', doc.activeElement, a)
+
+  key('ArrowDown')
+  eq('ArrowDown skips the disabled row', doc.activeElement, c)
+  key('ArrowDown')
+  eq('ArrowDown wraps to the top', doc.activeElement, a)
+  key('ArrowUp')
+  eq('ArrowUp wraps to the bottom', doc.activeElement, c)
+  key('Home')
+  eq('Home goes to the first row', doc.activeElement, a)
+  key('End')
+  eq('End goes to the last row', doc.activeElement, c)
+  ok('the disabled row was never focused', doc.activeElement !== dead)
+  m.destroy()
+}
+
+// ————— 6. mutual exclusion —————
+{
+  const one = createMenu('One', 'One')
+  const two = createMenu('Two', 'Two')
+  bar.append(one.root as never, two.root as never)
+  one.open()
+  two.open()
+  ok('opening the second closes the first', !one.isOpen)
+  ok('the second is open', two.isOpen)
+  closeAllMenus()
+  ok('closeAllMenus shuts everything', !two.isOpen)
+  one.destroy()
+  two.destroy()
+}
+
+// ————— 7. THE LISTENER LEAK —————
+{
+  const before = {
+    down: doc.docListeners.get('pointerdown')?.length ?? 0,
+    key: doc.docListeners.get('keydown')?.length ?? 0,
+  }
+  const menus = Array.from({ length: 8 }, (_, i) => createMenu(`M${i}`, `M${i}`))
+  for (const m of menus) bar.appendChild(m.root as never)
+  eq('eight menus install ONE pointerdown listener',
+    (doc.docListeners.get('pointerdown')?.length ?? 0) - before.down, 1)
+  eq('eight menus install ONE keydown listener',
+    (doc.docListeners.get('keydown')?.length ?? 0) - before.key, 1)
+
+  for (const m of menus) m.destroy()
+  eq('destroying them all removes the pointerdown listener',
+    doc.docListeners.get('pointerdown')?.length ?? 0, before.down)
+  eq('destroying them all removes the keydown listener',
+    doc.docListeners.get('keydown')?.length ?? 0, before.key)
+
+  // destroy() twice must not double-remove somebody else's listener
+  menus[0].destroy()
+  eq('a second destroy is a no-op', doc.docListeners.get('keydown')?.length ?? 0, before.key)
+}
+
+// ————— 8. rows are rebuilt every time it opens —————
+{
+  let hidden = false
+  const m = createMenu('More', 'More', {
+    fill: (menu, close) => {
+      const b = doc.createElement('button')
+      b.className = 'bkm-item'
+      b.textContent = hidden ? 'Show comments' : 'Hide comments'
+      b.addEventListener('click', () => { hidden = !hidden; close() })
+      menu.appendChild(b as never)
+    },
+  })
+  bar.appendChild(m.root as never)
+  m.open()
+  eq('first open reads the state', m.menu.textContent, 'Hide comments')
+  click(m.menu.querySelector('.bkm-item'))
+  ok('choosing the row closed the menu', !m.isOpen)
+  m.open()
+  eq('second open re-reads the state', m.menu.textContent, 'Show comments')
+  m.destroy()
+}
+
+// ————— choosing a row closes, unless it asks not to —————
+{
+  const m = createMenu('Act', 'Act')
+  bar.appendChild(m.root as never)
+  let ran = 0
+  const once = m.item('Run', () => { ran++ })
+  const sticky = m.item('Toggle', () => { ran++ }, { keepOpen: true })
+  const dead = m.item('Nope', () => { ran++ }, { off: true })
+
+  m.open()
+  click(once)
+  eq('the row ran', ran, 1)
+  ok('choosing a row closes the menu', !m.isOpen)
+
+  m.open()
+  click(sticky)
+  eq('a keepOpen row ran', ran, 2)
+  ok('a keepOpen row leaves the menu up', m.isOpen)
+
+  click(dead)
+  eq('a disabled row does NOT run', ran, 2)
+  m.destroy()
+}
+
+// ————— 9. a nested menu's rows are not the outer menu's —————
+{
+  const outer = createMenu('⋯', 'More')
+  bar.appendChild(outer.root as never)
+  const mine = outer.item('Mine', () => {})
+  const inner = createMenu('Language', 'Language')
+  outer.menu.appendChild(inner.root as never)
+  inner.item('Deutsch', () => {})
+  inner.item('Français', () => {})
+
+  outer.open()
+  triggerKey(outer.trigger, 'ArrowDown')
+  key('End')
+  eq('End stops at the outer menu\'s own last row', doc.activeElement, mine)
+  outer.destroy()
+  inner.destroy()
+}
+
+console.log(failures ? `\ntest-ui-menu: ${failures} FAILED of ${checks}` : `test-ui-menu: ${checks} checks OK`)
+process.exit(failures ? 1 : 0)

From 6c4522a4a1b15286356bcfec8b2cd08b29b0e53d Mon Sep 17 00:00:00 2001
From: nyblnet <306268465+nyblnet@users.noreply.github.com>
Date: Wed, 9 Sep 2026 02:29:16 +0100
Subject: [PATCH 2/2] kernel/menu: fix a dark-mode fallback, and guard the
 whole class
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

type has no --surface — its chrome surface token is --field, themed #ffffff →
#12151a and commented "form-control surface — CHROME, not paper". So
--bkm-bg's chain fell through to its light-only literal #fff, and a type menu
in dark mode would have painted white under light ink. The comment in menu.css
had already NAMED that gap and the fallback was still wrong, which is the
argument for a check rather than a note.

scripts/test-ui-menu.ts now asserts statically that every colour chain in
menu.css reaches a token each of the four apps both DEFINES and THEMES. It
accepts all three theming mechanisms in the tree — [data-theme="dark"], a
prefers-color-scheme media query, and dash's light-dark() — because "is this
themed" has four apps and three answers. Mutation-tested: restoring the old
chain turns it red on type alone. shadow is exempt and says why: only dash has
a shadow token, and a translucent shadow that ignores the theme is not a
legibility failure the way a background is.

Also corrects a premise this branch had inherited and repeated. dash was
described as having "diverged forward" with a light-dark() dark mode the others
lack; that is false — all four have a dark theme, and --ink: #e7eaf0 sits in
slides:39, spaces:165 and type:75. What actually differs is the MECHANISM, and
that matters more here: a shared sheet must not express themed values with
light-dark(), because it resolves off color-scheme and slides sets
`color-scheme: only light` deliberately (styles.css:96) to stop dark-mode
phones rendering native controls dark under dark ink. Under `only light` every
light-dark() value pins to its light half, so a shared sheet built on it would
silently cost slides the dark theme it has. The fallback chains sidestep this
by consuming whatever the host already themes, by whichever mechanism it uses —
which is why one sheet survives four mechanisms without picking one.

Recorded for tier 4, not settled here: menus are chrome and chrome should
follow the theme; the document must not, per kernel/src/theme.ts:17-18. type
draws that line correctly with --paper for the page and --field for chrome, and
the shared token set should make it explicit rather than inherit whichever
app's habit arrives first.

test-ui-menu 94 checks (was 41). test-ci-registered 290, test-preview 28,
test-theme 38 green; slides typechecks, builds, and passes shell-gate.
---
 docs/DECISIONS.md       | 52 ++++++++++++++++++++-----
 kernel/src/ui/menu.css  | 55 ++++++++++++++++++++++++---
 scripts/test-ui-menu.ts | 84 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 176 insertions(+), 15 deletions(-)

diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 6170d7a4..38495f31 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -6623,15 +6623,49 @@ focus-return that no app had.
 the maintainer's default and it holds for structure; where slides has the least,
 the fuller implementation wins on its merits and this entry says which.
 
-**Token VALUES are deliberately NOT settled here.** slides, spaces and type
-agree; dash has diverged forward with `--line-strong`, `--shadow-pop`,
-`--radius-lg` and a `light-dark()` dark mode. Which way that resolves is a
-maintainer's ruling and a later tier of this work. Until then every value in
-`menu.css` reads through a `--bkm-*` property whose fallback chain lands on
-whatever the host app already defines, so an app that adopts the primitive keeps
-the appearance it has today. Only two values had to be picked, because a shared
-rule cannot hold four: the trigger offset (6px) and the stacking level (60),
-each the majority of the four and each overridable per app.
+**Token VALUES are deliberately NOT settled here**, and neither is the theming
+MECHANISM. dash has `--line-strong`, `--shadow-pop`, `--radius-lg` and `--hover`
+that the other three lack, and a `--radius` of 7px against their 10px. Separately
+— and more importantly for a shared sheet — the four theme by three different
+mechanisms: slides and type via `:root[data-theme="dark"]`, spaces via that AND a
+`prefers-color-scheme` media query, dash via `light-dark()`, which resolves off
+`color-scheme`. All four DO have a dark theme; what differs is who decides.
+
+**A shared stylesheet therefore cannot express themed values with
+`light-dark()`.** slides sets `:root { color-scheme: only light }` deliberately
+(`slides/src/styles.css:96`) because without it a dark-mode phone renders native
+form controls dark under the app's dark ink — "blank" dropdowns — and Chrome on
+Android may force-darken the page. Under `only light`, every `light-dark()`
+value pins to its light half forever, so a shared sheet built on it would
+silently cost slides the dark theme it already has.
+
+`menu.css` sidesteps all of it: every value reads through a `--bkm-*` property
+whose fallback chain **consumes whatever themed token the host app already
+defines, by whichever mechanism that app themes it**. That is why one sheet
+survives four theming mechanisms without picking one, why adoption is
+appearance-neutral, and why tier 1 did not have to wait for the mechanism
+ruling. Only two values had to be picked, because a shared rule cannot hold
+four: the trigger offset (6px) and the stacking level (60), each the majority
+and each overridable per app.
+
+**The literal at the end of a themed chain is a latent dark-mode bug**, and this
+is the one defect tier 1 actually shipped and then caught. A chain ends in a
+light-only literal so the rule is never invalid; an app defining none of the
+tokens above it silently gets that literal in DARK mode. `type` has no
+`--surface` — its chrome surface token is `--field` — so `--bkm-bg` fell through
+to `#fff`, which would have painted a white menu under light ink. Fixed by
+extending the chain, and guarded by `scripts/test-ui-menu.ts`, which now asserts
+statically that every colour chain reaches a token each of the four apps both
+DEFINES and THEMES. A comment naming the gap was not enough; it named this one
+and the fallback was still wrong.
+
+**A boundary for tier 4, found here and not settled here.** Menus are chrome,
+and chrome should follow the theme — every app already themes the token this
+sheet consumes. The DOCUMENT must not, which `kernel/src/theme.ts:17-18` states
+outright. `type` draws that line explicitly and correctly, with `--paper` for
+the page and `--field` commented "form-control surface — CHROME, not paper".
+The shared token set should make that distinction explicit rather than inherit
+whichever app's habit arrives first.
 
 **The kernel ships CSS now, which it never did before.** Verified end to end
 rather than assumed: an app's `import '../../kernel/src/ui/menu.css'` is folded
diff --git a/kernel/src/ui/menu.css b/kernel/src/ui/menu.css
index 614029cf..dcef4a2e 100644
--- a/kernel/src/ui/menu.css
+++ b/kernel/src/ui/menu.css
@@ -14,11 +14,45 @@
 
    ————— VALUES ARE THE HOST APP'S, STRUCTURE AND BEHAVIOUR ARE SHARED —————
 
-   The four apps disagree about tokens. slides, spaces and type agree with each
-   other; dash has diverged FORWARD — `--line-strong`, `--shadow-pop`,
-   `--radius-lg`, and a `light-dark()` dark mode — and nobody decided that, it
-   happened. Resolving it is a maintainer's ruling and it is tier 4 of this
-   project, so this file does not pre-empt it either way.
+   The four apps disagree about tokens: dash has `--line-strong`,
+   `--shadow-pop`, `--radius-lg` and `--hover`, which the other three lack, and
+   a `--radius` of 7px against their 10px. Resolving that is a maintainer's
+   ruling and it is tier 4 of this project, so this file does not pre-empt it.
+
+   They ALSO disagree about the theming MECHANISM, which matters more here and
+   is the reason this sheet imposes none:
+
+     slides   :root[data-theme="dark"]   + :root { color-scheme: only light }
+     type     :root[data-theme="dark"]
+     spaces   [data-theme="dark"] AND a prefers-color-scheme media query
+     dash     light-dark() + a media query — i.e. color-scheme, i.e. the OS
+
+   All four DO have a dark theme; `--ink: #e7eaf0` sits in three of the dark
+   blocks (slides:39, spaces:165, type:75). What differs is who decides.
+
+   A SHARED SHEET MUST NOT USE `light-dark()`. It resolves off `color-scheme`,
+   and slides sets `:root { color-scheme: only light }` deliberately
+   (styles.css:96) — without it, dark-mode phones render native form controls
+   dark while the app's ink stays dark ("blank" dropdowns), and Chrome on
+   Android may force-darken the page. Under `only light` every `light-dark()`
+   value pins to its LIGHT half forever, so a shared sheet built on it would
+   silently cost slides the dark theme it already has.
+
+   The fallback chains below sidestep the whole question: they CONSUME whatever
+   themed token the host app already defines, by whichever mechanism that app
+   themes it. That is why this one sheet survives four different theming
+   mechanisms without picking one, and it is why tier 1 does not have to wait
+   for the tier 4 ruling.
+
+   A NOTE FOR TIER 4, found here and not settled here. Menus are CHROME, and
+   chrome SHOULD follow the theme — every app already themes the token this
+   sheet consumes for it. The document must not. type draws that line
+   explicitly and correctly: `--paper` is the page, `--field` is "form-control
+   surface — CHROME, not paper", and only the second is a menu's business. The
+   shared token set should make that boundary explicit rather than inherit
+   whichever app's habit arrives first. kernel/src/theme.ts:17-18 already says
+   a theme is a viewer preference and the document does not invert; the token
+   names are where an app either honours that or quietly does not.
 
    Instead every value reads through a `--bkm-*` property whose fallback chain
    lands on whatever the host already defines. An app that defines
@@ -53,7 +87,16 @@
   flex-direction: column;
   min-width: var(--bkm-min-width, 200px);
   padding: 5px;
-  background: var(--bkm-bg, var(--surface, #fff));
+  /* `--field` is in the chain because type has no `--surface` — its chrome
+     surface token is `--field`, themed #ffffff → #12151a and commented "form-
+     control surface — CHROME, not paper". Without it this fell through to the
+     literal below, which is LIGHT-ONLY, so a type menu in dark mode would have
+     painted white under light ink. A hardcoded literal at the end of a themed
+     chain is a dark-mode bug waiting for the first app that misses the token,
+     which is why `scripts/test-ui-menu.ts` now asserts every chain here
+     resolves to a token each app actually defines, rather than trusting this
+     comment to be remembered. */
+  background: var(--bkm-bg, var(--surface, var(--field, #fff)));
   border: 1px solid var(--bkm-border, var(--line-strong, var(--line, #e3e8ef)));
   border-radius: var(--bkm-radius, var(--radius-lg, var(--radius, 10px)));
   box-shadow: var(--bkm-shadow, var(--shadow-pop, 0 12px 32px rgb(20 30 45 / 0.16)));
diff --git a/scripts/test-ui-menu.ts b/scripts/test-ui-menu.ts
index 4a24c167..d2f009ca 100644
--- a/scripts/test-ui-menu.ts
+++ b/scripts/test-ui-menu.ts
@@ -259,5 +259,89 @@ const A = (el: unknown, k: string): string | null => (el as any).getAttribute(k)
   inner.destroy()
 }
 
+// ————— 10. EVERY THEMED FALLBACK CHAIN REACHES A TOKEN THE APP ACTUALLY THEMES
+//
+// menu.css styles CHROME, and chrome follows the theme. Each colour reads
+// through a chain like `var(--bkm-bg, var(--surface, var(--field, #fff)))`, and
+// the literal at the end is LIGHT-ONLY — it exists so the rule is never
+// invalid, not because any app should reach it. An app that defines none of the
+// tokens in a chain silently gets that light literal in DARK mode: a white menu
+// under light ink, which is the mirror of the dark-on-dark bug slides fixed with
+// `color-scheme: only light`.
+//
+// This was not hypothetical. `type` has no `--surface` at all — its chrome
+// surface token is `--field` — so the first version of the chain fell through
+// to `#fff` for the one app whose gap the comment had already noted and whose
+// fallback had not been fixed. A comment is not a guard. This is.
+//
+// The four apps theme by three different MECHANISMS (slides and type via
+// `[data-theme="dark"]`, spaces via both that and a media query, dash via
+// `light-dark()`), so "is this token themed" has to accept all three.
+{
+  const { readFileSync } = await import('node:fs')
+  const APPS = ['slides', 'spaces', 'dash', 'type']
+  const css = readFileSync(new URL('../kernel/src/ui/menu.css', import.meta.url), 'utf8')
+
+  /** Every `--token` a chain falls through, in order, ignoring our own. */
+  const chains: Array<{ prop: string; tokens: string[] }> = []
+  for (const line of css.split('\n')) {
+    const decl = /^\s*(background|color|border|box-shadow|outline)?[^:]*:\s*var\(--bkm-([a-z-]+),(.*)$/.exec(line)
+    if (!decl) continue
+    // `--[a-z-]+` stopped at the digit in `--chrome-2` and reported a token
+    // nobody defines. Digits are part of a custom-property name.
+    const tokens = [...decl[3].matchAll(/var\(\s*(--[a-z0-9-]+)/g)].map((m) => m[1])
+    if (tokens.length) chains.push({ prop: decl[2], tokens })
+  }
+  ok('found the themed chains to check', chains.length >= 4)
+
+  /** Tokens an app defines at all, and the subset it actually themes. */
+  function tokensOf(app: string): { all: Set<string>; themed: Set<string> } {
+    const src = readFileSync(new URL(`../${app}/src/styles.css`, import.meta.url), 'utf8')
+    const all = new Set<string>()
+    const themed = new Set<string>()
+    for (const m of src.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      all.add(m[1])
+      // dash themes by resolving against color-scheme, in the value itself
+      if (m[2].includes('light-dark(')) themed.add(m[1])
+    }
+    // …the other three theme by re-declaring inside a dark block. Brace-count
+    // from each one so a nested rule inside a media query is still counted.
+    for (const start of [...src.matchAll(/\[data-theme=["']dark["']\][^{]*\{|@media[^{]*prefers-color-scheme:\s*dark[^{]*\{/g)]) {
+      let depth = 0
+      let i = start.index! + start[0].length - 1
+      for (; i < src.length; i++) {
+        if (src[i] === '{') depth++
+        else if (src[i] === '}') { depth--; if (!depth) break }
+      }
+      for (const m of src.slice(start.index!, i).matchAll(/(--[a-z0-9-]+)\s*:/g)) themed.add(m[1])
+    }
+    return { all, themed }
+  }
+
+  // Only the colour-bearing chains must be THEMED. A radius or a font size is
+  // the same in both themes by design, so requiring it here would be noise.
+  const COLOUR = new Set(['bg', 'border', 'ink', 'hover', 'ico', 'focus'])
+
+  // `shadow` is deliberately exempt from BOTH checks. Only dash has a shadow
+  // token (`--shadow-pop`); spaces has none at all, and slides and type write
+  // their menu shadow as a literal today. So the literal here IS the intended
+  // value for three of four apps rather than a gap — and unlike a background or
+  // an ink, a translucent shadow that does not follow the theme is not a
+  // legibility failure. If tier 4 mints a shared shadow token, move `shadow`
+  // into COLOUR above and this becomes a real check.
+  const EXEMPT = new Set(['shadow'])
+
+  for (const app of APPS) {
+    const { all, themed } = tokensOf(app)
+    for (const { prop, tokens } of chains) {
+      if (EXEMPT.has(prop)) continue
+      const defined = tokens.find((t) => all.has(t))
+      ok(`${app}: --bkm-${prop} reaches a token ${app} defines (${tokens.join(' → ')})`, defined)
+      if (!defined || !COLOUR.has(prop)) continue
+      ok(`${app}: --bkm-${prop} lands on ${defined}, which ${app} themes`, themed.has(defined))
+    }
+  }
+}
+
 console.log(failures ? `\ntest-ui-menu: ${failures} FAILED of ${checks}` : `test-ui-menu: ${checks} checks OK`)
 process.exit(failures ? 1 : 0)