@origingame/engine 0.0.0-stage → 0.1.0

package/src/ui-kit/store.ts

@@ -0,0 +1,222 @@
+// Collections: the shop, the inventory (drag and drop between slots), the
+// level select and the leaderboard. Each is a dialog-shaped screen with a
+// focus scope; Back closes it.
+
+import type * as Api from "@origingame/engine";
+import { kit } from "./bind.ts";
+import { capsule, fit, fmt, frame, grow, iconOr, px, token } from "./util.ts";
+
+/** A screen panel: a dialog over the game, wide on desktop, full width on a phone. With `scrim` a press on the backdrop closes it too. */
+function screen(id: string, title: string, width: number, build: () => void, scrim = false): boolean {
+  const { phone, viewport } = frame();
+  const m = kit.modal(id, true, { title, width: phone ? grow() : px(Math.min(width, viewport.width - 48)), ignoreBackdrop: !scrim }, build);
+  return m.dismissed;
+}
+
+/** An item's picture: its icon, else its initial on the slot. */
+function picture(id: string, icon: string | undefined, name: string, size: number): void {
+  if (icon && kit.hasIcon(icon)) kit.icon(id, icon, { size });
+  else kit.label(id, name.slice(0, 1).toUpperCase(), { step: "xl2", font: "display", color: token("fgMuted"), nowrap: true });
+}
+
+export function shopScreen(id: string, desc: Api.ShopDesc = {}): Api.ShopResult {
+  const { t, phone } = frame();
+  const out: { bought: string | null; refused: string | null; closed: boolean } = { bought: null, refused: null, closed: false };
+  const cats = desc.categories ?? [];
+  let cat = Math.min(kit.memory(`${id}.cat`, 0), Math.max(0, cats.length - 1));
+  const all = desc.items ?? [];
+  const items = cats.length === 0 ? all : all.filter((i) => (i.category || cats[0]) === cats[cat]);
+  let sel = Math.min(kit.memory(`${id}.sel`, 0), Math.max(0, items.length - 1));
+  const balance = desc.balance ?? 0;
+  out.closed = screen(id, desc.title ?? "Shop", 760, () => {
+    kit.row("Bar", { width: grow(), gap: t.sm, cross: "center", align: "spaceBetween" }, () => {
+      if (cats.length > 0) {
+        const r = kit.tabs("Categories", cats, cat, {});
+        if (r.response.changed) sel = 0;
+        cat = r.selected;
+      } else {
+        kit.spacer("Gap", null);
+      }
+      capsule("Balance", () => {
+        if (desc.currencyIcon) iconOr("Icon", desc.currencyIcon, 18, token("accent"));
+        kit.counter("Amount", balance, { font: "mono", step: "base" });
+        kit.label("Unit", desc.currency ?? "coins", { step: "base", color: token("fgMuted"), nowrap: true });
+      });
+    });
+    const body = (): void => {
+      const g = kit.grid("Items", { count: items.length, cellWidth: phone ? 96 : 112, cellHeight: phone ? 112 : 124, height: fit(0, phone ? 260 : 320), width: grow(), selected: sel }, (i) => {
+        const it = items[i]!;
+        picture("Picture", it.icon, it.name ?? "", 36);
+        kit.label("Name", it.name ?? "", { step: "base", nowrap: true });
+        if (it.owned) kit.badge("Owned", desc.ownedLabel ?? "Owned", "success");
+        else kit.label("Price", fmt(it.price ?? 0), { step: "meta", font: "mono", color: token(balance >= (it.price ?? 0) ? "accentInk" : "fgSubtle"), nowrap: true });
+      });
+      if (g.clicked !== null && g.clicked !== undefined) sel = g.clicked;
+      const it = items[sel];
+      kit.column("Detail", { width: phone ? grow() : px(220), gap: t.sm }, () => {
+        if (!it) {
+          kit.label("Empty", desc.emptyLabel ?? "Nothing for sale here", { color: token("fgMuted") });
+          return;
+        }
+        kit.label("Name", it.name ?? "", { step: "lg", width: grow() });
+        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("fgMuted"), width: grow() });
+        kit.keyValue("Price", desc.priceLabel ?? "Price", `${fmt(it.price ?? 0)} ${desc.currency ?? "coins"}`, true);
+        const short = balance < (it.price ?? 0);
+        // Short of the price, Buy still answers: it refuses, shaking with the error sound.
+        const r = kit.button("Buy", it.owned ? (desc.ownedLabel ?? "Owned") : short ? (desc.shortLabel ?? "Not enough") : (desc.buyLabel ?? "Buy"), { variant: short ? "secondary" : "primary", width: grow(), disabled: it.owned }) as Api.Response;
+        if (r.clicked && !it.owned && short) {
+          kit.shake({ sound: true });
+          out.refused = it.id ?? null;
+        }
+        if (r.clicked && !it.owned && !short) out.bought = it.id ?? null;
+      });
+    };
+    if (phone) kit.column("Body", { width: grow(), gap: t.md }, body);
+    else kit.row("Body", { width: grow(), gap: t.lg }, body);
+  });
+  kit.remember(`${id}.cat`, cat);
+  kit.remember(`${id}.sel`, sel);
+  if (out.bought !== null) desc.onBuy?.(out.bought);
+  return out;
+}
+
+export function inventoryScreen(id: string, desc: Api.InventoryDesc = {}): Api.InventoryResult {
+  const { t, phone } = frame();
+  const slots = desc.slots ?? 24;
+  const bySlot = new Map<number, Api.InventoryItem>();
+  for (const it of desc.items ?? []) bySlot.set(it.slot ?? 0, it);
+  let sel = kit.memory(`${id}.sel`, -1);
+  const out: { selected: number | null; moved: Api.SlotMove | null; used: string | null; closed: boolean } = { selected: null, moved: null, used: null, closed: false };
+  const cell = phone ? 64 : 72;
+  const columns = desc.columns ?? 0;
+  // Wide enough for the stated columns at the slot size (the grid shares
+  // what is left between them if the screen is narrower): the dialog's
+  // padding, the detail panel and the gap beside the grid, and room for
+  // its scrollbar.
+  const chrome = 2 * t.xl + 200 + t.lg;
+  const width = columns > 0 ? Math.max(680, chrome + columns * (cell + t.sm) - t.sm + 2 * t.sm) : 680;
+  out.closed = screen(id, desc.title ?? "Inventory", width, () => {
+    const body = (): void => {
+      const g = kit.grid("Slots", { count: slots, cellWidth: cell, cellHeight: cell, columns, height: px(phone ? 300 : 340), width: grow(), selected: sel >= 0 ? sel : null }, (i) => {
+        const it = bySlot.get(i);
+        if (!it) return;
+        picture("Picture", it.icon, it.name ?? "", cell * 0.5);
+        if ((it.count ?? 0) > 1) kit.label("Count", `${it.count}`, { step: "xs", font: "mono", color: token("fgMuted"), nowrap: true });
+      });
+      if (g.clicked !== null && g.clicked !== undefined) sel = g.clicked;
+      if (g.dropFrom !== null && g.dropFrom !== undefined && g.dropTo !== null && g.dropTo !== undefined && bySlot.has(g.dropFrom)) {
+        out.moved = { from: g.dropFrom, to: g.dropTo };
+        sel = g.dropTo;
+      }
+      const it = sel >= 0 ? bySlot.get(sel) : undefined;
+      kit.column("Detail", { width: phone ? grow() : px(200), gap: t.sm }, () => {
+        if (!it) {
+          kit.label("Hint", desc.hintLabel ?? "Select an item. Drag it to another slot to move it.", { step: "meta", color: token("fgMuted"), width: grow() });
+          return;
+        }
+        kit.label("Name", it.name ?? "", { step: "lg", width: grow() });
+        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("fgMuted"), width: grow() });
+        if ((it.count ?? 0) > 1) kit.keyValue("Count", desc.countLabel ?? "Count", `${it.count}`, true);
+        if (desc.useLabel !== "") {
+          if ((kit.button("Use", desc.useLabel ?? "Use", { variant: "primary", width: grow() }) as Api.Response).clicked) out.used = it.id ?? null;
+        }
+      });
+    };
+    if (phone) kit.column("Body", { width: grow(), gap: t.md }, body);
+    else kit.row("Body", { width: grow(), gap: t.lg }, body);
+  });
+  kit.remember(`${id}.sel`, sel);
+  out.selected = sel >= 0 ? sel : null;
+  return out;
+}
+
+export function levelSelect(id: string, desc: Api.LevelSelectDesc = {}): Api.LevelSelectResult {
+  const { t, phone } = frame();
+  const levels = desc.levels ?? [];
+  const earned = levels.reduce((n, l) => n + Math.min(3, l.stars ?? 0), 0);
+  const out: { chosen: number | null; closed: boolean } = { chosen: null, closed: false };
+  // A screen reader hears the stars as the desc words them ("2 of 3 stars"),
+  // never the icons' English names: the first star carries it, the others
+  // are decoration; a locked card is named by its level, not "lock".
+  const starsLabel = (stars: number, max: number): string => (desc.starsLabel ?? "{stars} of {max} stars").replaceAll("{stars}", `${stars}`).replaceAll("{max}", `${max}`);
+  let back = false;
+  // Back from every input: the button, a press on the scrim, Escape, B.
+  out.closed = screen(id, desc.title ?? "Levels", 720, () => {
+    kit.row("Total", { gap: t.xs, cross: "center" }, () => {
+      iconOr("Star", "star", 18, token("accent"), starsLabel(earned, levels.length * 3));
+      kit.label("Count", `${earned} / ${levels.length * 3}`, { font: "mono", color: token("fgMuted"), nowrap: true });
+    });
+    // A numeral is the card's face, in display type on a square card; a
+    // name takes a wider card and a smaller step, wrapped to two lines (cut
+    // with an ellipsis past them), so it is read, never clipped. With
+    // `columns` the cards share the screen's width, so two columns are two
+    // wide cards.
+    const named = levels.some((l) => [...(l.name ?? "")].length > 3);
+    const cell = phone ? 84 : 104;
+    const g = kit.grid("Levels", { count: levels.length, cellWidth: named ? (phone ? 136 : 168) : cell, cellHeight: cell, columns: desc.columns ?? 0, height: fit(0, phone ? 420 : 400), width: grow() }, (i) => {
+      const l = levels[i]!;
+      const name = l.name ?? `${i + 1}`;
+      if (l.locked) {
+        iconOr("Lock", "lock", 28, token("fgSubtle"), (desc.lockedLabel ?? "{name}, locked").replaceAll("{name}", name));
+        return;
+      }
+      if ([...name].length > 3) kit.label("Name", name, { step: phone ? "base" : "lg", font: "display", align: "center", width: grow(), maxLines: 2, ellipsis: true });
+      else kit.label("Name", name, { step: "xl3", font: "display", nowrap: true });
+      const stars = Math.min(3, l.stars ?? 0);
+      kit.row("Stars", { gap: 2 }, () => {
+        for (let k = 0; k < 3; k++) iconOr(kit.idi("Star", k), "star", 14, token(k < stars ? "accent" : "fillStrong"), k === 0 ? starsLabel(stars, 3) : "");
+      });
+    });
+    if (g.clicked !== null && g.clicked !== undefined && !levels[g.clicked]?.locked) out.chosen = g.clicked;
+    kit.row("Footer", { width: grow(), align: "end" }, () => {
+      if ((kit.button("Back", desc.backLabel ?? "Back", {}) as Api.Response).clicked) back = true;
+    });
+  }, true);
+  out.closed ||= back;
+  return out;
+}
+
+const MEDALS: readonly Api.ThemeColor[] = ["warn", "fgMuted", "accentInk"];
+
+export function leaderboardScreen(id: string, desc: Api.LeaderboardDesc = {}): Api.LeaderboardResult {
+  const { t, phone } = frame();
+  const scopes = desc.scopes ?? [];
+  let scope = Math.min(kit.memory(`${id}.scope`, 0), Math.max(0, scopes.length - 1));
+  const out = { scope, changed: false, retry: false, closed: false };
+  const entries = desc.entries ?? [];
+  out.closed = screen(id, desc.title ?? "Leaderboard", 520, () => {
+    if (scopes.length > 0) {
+      const r = kit.tabs("Scopes", scopes, scope, { fill: true, width: grow() });
+      out.changed = r.response.changed;
+      scope = r.selected;
+    }
+    const height = px(phone ? 380 : 360);
+    if (desc.loading) {
+      // Honest loading: skeleton rows, never invented scores.
+      kit.column("Loading", { width: grow(), gap: t.md, height }, () => {
+        for (let i = 0; i < 6; i++) kit.skeleton(kit.idi("Row", i), { height: t.controlSm });
+      });
+    } else if (desc.error) {
+      kit.column("Error", { width: grow(), gap: t.md, height, align: "center", cross: "center" }, () => {
+        kit.label("Message", desc.error!, { color: token("danger"), align: "center", width: grow() });
+        if ((kit.button("Retry", desc.retryLabel ?? "Retry", {}) as Api.Response).clicked) out.retry = true;
+      });
+    } else if (entries.length === 0) {
+      kit.column("Empty", { width: grow(), height, align: "center", cross: "center" }, () => {
+        kit.label("Message", desc.empty ?? "No scores yet", { color: token("fgMuted"), align: "center", width: grow() });
+      });
+    } else {
+      const player = entries.findIndex((e) => e.player);
+      kit.list("Rows", { count: entries.length, rowHeight: t.row, height, width: grow(), selected: player >= 0 ? player : null }, (i) => {
+        const e = entries[i]!;
+        const rank = e.rank ?? i + 1;
+        kit.label("Rank", `${rank}`, { width: px(40), font: "mono", step: rank <= 3 ? "lg" : "body", color: token(rank <= 3 ? MEDALS[rank - 1]! : "fgMuted"), nowrap: true });
+        kit.label("Name", e.name ?? "", { width: grow(), nowrap: true });
+        kit.label("Score", e.score ?? "", { font: "mono", nowrap: true });
+      });
+    }
+  });
+  kit.remember(`${id}.scope`, scope);
+  out.scope = scope;
+  return out;
+}

package/src/ui-kit/story.ts

@@ -0,0 +1,89 @@
+// Story and teaching: the cutscene (letterbox and dialogue box) and the
+// onboarding overlay (a spotlight on each step's target and a callout).
+
+import type * as Api from "@origingame/engine";
+import { kit } from "./bind.ts";
+import { all, frame, grow, pct, px, token } from "./util.ts";
+
+export function cutscene(id: string, desc: Api.CutsceneDesc = {}): Api.CutsceneResult {
+  const { t, phone } = frame();
+  const lines = desc.lines ?? [];
+  let index = Math.min(desc.index ?? 0, Math.max(0, lines.length - 1));
+  const out = { index, finished: false, skipped: false };
+  const open = (desc.open ?? false) && lines.length > 0;
+  if (!open) return out;
+  kit.setNavigation(true);
+  const letterbox = desc.letterbox ?? true;
+  if (letterbox) {
+    for (const [name, anchor] of [["Top", "top"], ["Bottom", "bottom"]] as const) {
+      kit.anchor(`${id}.${name}`, { anchor, margin: 0, width: grow(), height: pct(0.1), background: token("stage") }, () => {});
+    }
+  }
+  const line = lines[index]!;
+  kit.anchor(`${id}.box`, { anchor: "bottom", width: phone ? grow() : px(Math.min(760, frame().viewport.width - 64)), offsetY: letterbox ? -frame().viewport.height * 0.04 : 0 }, () => {
+    const r = kit.dialogue("Dialogue", { speaker: line.speaker ?? "", text: line.text ?? "", portraitIcon: line.portrait ?? "" });
+    if (r.advanced) {
+      if (index + 1 >= lines.length) out.finished = true;
+      else index += 1;
+    }
+  });
+  if (desc.skippable ?? true) {
+    kit.anchor(`${id}.skip`, { anchor: "topRight", offsetY: letterbox ? frame().viewport.height * 0.1 : 0 }, () => {
+      if ((kit.button("Skip", desc.skipLabel ?? "Skip", { variant: "quiet", size: "small" }) as Api.Response).clicked) out.skipped = true;
+    });
+    if (kit.back()) out.skipped = true;
+  }
+  out.index = index;
+  return out;
+}
+
+export function tutorialOverlay(id: string, desc: Api.TutorialDesc = {}): Api.TutorialResult {
+  const { t, viewport } = frame();
+  const steps = desc.steps ?? [];
+  const index = Math.min(desc.index ?? 0, Math.max(0, steps.length - 1));
+  const out = { index, finished: false, skipped: false };
+  if (!(desc.open ?? false) || steps.length === 0) return out;
+  const step = steps[index]!;
+  const hole = step.target ? kit.bounds(step.target) : null;
+  kit.spotlight(id, hole, {});
+  // The callout beside the hole: under it when there is room, else over it.
+  const width = Math.min(320, viewport.width - 2 * t.gutter);
+  const last = kit.bounds(`${id}.callout`);
+  const height = last?.height ?? 160;
+  const safe = viewport.safeArea;
+  let x = viewport.width / 2 - width / 2;
+  let y = viewport.height / 2 - height / 2;
+  if (hole) {
+    x = Math.min(Math.max(hole.x, safe.left + t.gutter), viewport.width - safe.right - t.gutter - width);
+    const below = hole.y + hole.height + t.lg;
+    y = below + height <= viewport.height - safe.bottom - t.gutter ? below : Math.max(safe.top + t.gutter, hole.y - t.lg - height);
+  }
+  kit.anchor(`${id}.callout`, {
+    anchor: "topLeft",
+    over: true,
+    margin: 0,
+    offsetX: x - safe.left,
+    offsetY: y - safe.top,
+    width: px(width),
+    direction: "column",
+    gap: t.sm,
+    padding: all(t.lg),
+    background: token("surfaceRaised"),
+    radius: t.panel,
+  }, () => {
+    const count = (desc.stepLabel ?? "{step} of {count}").replaceAll("{step}", `${index + 1}`).replaceAll("{count}", `${steps.length}`);
+    kit.label("Count", count, { step: "meta", color: token("fgMuted") });
+    if (step.title) kit.label("Title", step.title, { step: "lg", width: grow() });
+    if (step.text) kit.label("Text", step.text, { step: "reading", color: token("fgMuted"), width: grow() });
+    kit.row("Actions", { width: grow(), gap: t.sm, align: "spaceBetween", cross: "center" }, () => {
+      if ((kit.button("Skip", desc.skipLabel ?? "Skip", { variant: "quiet", size: "small" }) as Api.Response).clicked) out.skipped = true;
+      const lastStep = index + 1 >= steps.length;
+      if ((kit.button("Next", lastStep ? (desc.doneLabel ?? "Done") : (desc.nextLabel ?? "Next"), { variant: "primary", size: "small" }) as Api.Response).clicked) {
+        if (lastStep) out.finished = true;
+        else out.index = index + 1;
+      }
+    });
+  });
+  if (kit.back()) out.skipped = true;
+  return out;
+}

package/src/ui-kit/util.ts

@@ -0,0 +1,106 @@
+// Small helpers the screen templates share: sizes, insets, the frame's
+// tokens, number and time formats, and HUD capsules. Nothing here keeps
+// state: what must persist lives in the UI's memory (og.ui.memory).
+
+import type * as Api from "@origingame/engine";
+import { kit } from "./bind.ts";
+
+export const px = (n: number): Api.Size => ({ kind: "fixed", px: n });
+export const grow = (min?: number, max?: number): Api.Size => ({ kind: "grow", ...(min === undefined ? {} : { min }), ...(max === undefined ? {} : { max }) });
+export const fit = (min?: number, max?: number): Api.Size => ({ kind: "fit", ...(min === undefined ? {} : { min }), ...(max === undefined ? {} : { max }) });
+export const pct = (fraction: number): Api.Size => ({ kind: "percent", fraction });
+export const all = (n: number): Api.Insets => ({ left: n, top: n, right: n, bottom: n });
+export const xy = (x: number, y: number): Api.Insets => ({ left: x, top: y, right: x, bottom: y });
+export const token = (name: Api.ThemeColor, alpha?: number): Api.Paint => (alpha === undefined ? { token: name } : { token: name, alpha });
+
+/** The tokens of the frame being built, read once per UI tick. */
+let cached: { tick: number; theme: Api.UiTheme; viewport: Api.Viewport } | null = null;
+export function frame(): { theme: Api.UiTheme; viewport: Api.Viewport; t: Tokens; phone: boolean; touch: boolean } {
+  const tick = kit.tick();
+  if (!cached || cached.tick !== tick) cached = { tick, theme: kit.frameTheme(), viewport: kit.frameViewport() };
+  const { theme, viewport } = cached;
+  const phone = viewport.breakpoint === "phonePortrait" || viewport.breakpoint === "phoneLandscape";
+  return { theme, viewport, t: tokens(theme), phone, touch: viewport.coarsePointer || phone || viewport.breakpoint === "tablet" };
+}
+
+export interface Tokens {
+  xxs: number; xs: number; sm: number; md: number; lg: number; xl: number; xxl: number; xl3: number;
+  card: number; panel: number; block: number; button: number;
+  controlSm: number; controlMd: number; controlLg: number; gutter: number; row: number;
+}
+
+function tokens(t: Api.UiTheme): Tokens {
+  const s = (k: string): number => t.space[k] ?? 0;
+  const r = (k: string): number => t.radius[k] ?? 0;
+  return {
+    xxs: s("xxs"), xs: s("xs"), sm: s("sm"), md: s("md"), lg: s("lg"), xl: s("xl"), xxl: s("xxl"), xl3: s("xl3"),
+    card: r("card"), panel: r("panel"), block: r("block"), button: r("button"),
+    controlSm: t.sizes.controlSm, controlMd: t.sizes.controlMd, controlLg: t.sizes.controlLg, gutter: t.sizes.gutter, row: t.sizes.row,
+  };
+}
+
+/** A count for a HUD: 12,840 below a million, then 3.40M, 1.20B, 7.00T, then 1.2e15. */
+export function fmt(n: number): string {
+  if (!Number.isFinite(n)) return "—";
+  const a = Math.abs(n);
+  const sign = n < 0 ? "-" : "";
+  if (a < 1_000_000) return sign + Math.floor(a).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  const units: Array<[number, string]> = [[1e12, "T"], [1e9, "B"], [1e6, "M"]];
+  for (const [v, u] of units) {
+    if (a >= v && a < v * 1000) {
+      const x = a / v;
+      return sign + (x < 100 ? x.toFixed(x < 10 ? 2 : 1) : Math.floor(x).toString()) + u;
+    }
+  }
+  return sign + a.toExponential(1).replace("+", "");
+}
+
+/** Seconds as m:ss (or m:ss.mmm with `millis`); negative is 0:00. */
+export function clock(seconds: number, millis = false): string {
+  const s = Math.max(0, seconds);
+  const m = Math.floor(s / 60);
+  const rest = s - m * 60;
+  const whole = Math.floor(rest);
+  const head = `${m}:${whole.toString().padStart(2, "0")}`;
+  return millis ? `${head}.${Math.floor((rest - whole) * 1000).toString().padStart(3, "0")}` : head;
+}
+
+/** A finished time as m:ss.mmm, cut to the millisecond as race timing is, but never a millisecond short by a float's last bit (96.233 s is 1:36.233, where 96.233 * 1000 is 96232.99999999999); negative is 0:00.000. */
+export function lapTime(seconds: number): string {
+  const ms = Math.floor(Math.max(0, seconds) * 1000 + 1e-6);
+  const m = Math.floor(ms / 60000);
+  const s = Math.floor(ms / 1000) % 60;
+  return `${m}:${s.toString().padStart(2, "0")}.${(ms % 1000).toString().padStart(3, "0")}`;
+}
+
+/** A HUD capsule: a translucent dark pill (material-thick) that keeps text legible over any art. */
+export function capsule(id: string, build: () => void, desc: { gap?: number; padX?: number; height?: number } = {}): Api.Response {
+  const { t } = frame();
+  return kit.row(id, {
+    padding: xy(desc.padX ?? t.md, 0),
+    height: px(desc.height ?? t.controlMd),
+    gap: desc.gap ?? t.sm,
+    cross: "center",
+    background: token("materialThick"),
+    radius: t.button,
+    frame: "capsule",
+  }, build) as Api.Response;
+}
+
+/** An icon of the atlas, or a small solid mark of the same ink when the atlas lacks it; `label` names it for a screen reader (IconDesc.label: empty is decoration). */
+export function iconOr(id: string, name: string, size: number, tint: Api.Paint, label?: string): void {
+  if (kit.hasIcon(name)) kit.icon(id, name, label === undefined ? { size, tint } : { size, tint, label });
+  else kit.image(id, { tint, width: px(size * 0.6), height: px(size * 0.6), label: label ?? "" });
+}
+
+/** Menu items with defaults filled in, the first primary unless one is. */
+export function menuItems(items: readonly Api.MenuItem[] | undefined, fallback: ReadonlyArray<[string, string]>): Required<Pick<Api.MenuItem, "id" | "label" | "disabled" | "primary">>[] {
+  const list: readonly Api.MenuItem[] = items && items.length > 0 ? items : fallback.map(([id, label]) => ({ id, label }));
+  const anyPrimary = list.some((i) => i.primary);
+  return list.map((i, k) => ({
+    id: i.id ?? `item${k}`,
+    label: i.label ?? i.id ?? "",
+    disabled: i.disabled ?? false,
+    primary: anyPrimary ? (i.primary ?? false) : k === 0,
+  }));
+}