@origingame/engine 0.2.0 → 0.4.0

package/src/trace.ts

@@ -0,0 +1,169 @@
+// The run's trace in the Chrome trace format (the Trace Event Format's JSON
+// object form, which Perfetto and chrome://tracing open), the same document
+// on both hosts: native `og run --trace` (src/node/run.ts) and the web
+// Worker (src/web/worker.ts, read through the shell's `trace()`).
+//
+// The engine records every span where it ran and hands them over as Chrome
+// trace events on its own clock (crates/og-runtime/src/trace.rs: `{ now,
+// events }`, `ts` in µs); a take is placed on the document's origin (Unix
+// milliseconds) by the difference between the host's time and the engine's
+// clock read together. Threads of process 1: 1 engine, 2 render, 3 load,
+// 4 cook (og's, natively), 5 gpu, 16 + n og-lanes' pool thread n, 48 + n
+// the cook's thread n; threads that appear mid-run arrive with their names.
+
+export type TraceEvent = Record<string, unknown> & { ph: string; pid: number; tid: number; name: string; ts?: number; dur?: number };
+
+/** A Chrome trace document as written to a file. */
+export type TraceDocument = {
+  traceEvents: TraceEvent[];
+  displayTimeUnit: "ms";
+  otherData: { originUnixMs: number; producer: string; [k: string]: unknown };
+};
+
+/** The fixed threads and their names. */
+export const TRACE_THREADS: readonly (readonly [number, string])[] = [
+  [1, "engine"],
+  [2, "render"],
+  [3, "load"],
+  [4, "cook"],
+  [5, "gpu"],
+];
+
+/** The process and fixed threads' metadata events. */
+export function traceMetadata(process: string): TraceEvent[] {
+  const out: TraceEvent[] = [{ name: "process_name", ph: "M", pid: 1, tid: 0, args: { name: process } }];
+  for (const [tid, name] of TRACE_THREADS) {
+    out.push({ name: "thread_name", ph: "M", pid: 1, tid, args: { name } });
+    out.push({ name: "thread_sort_index", ph: "M", pid: 1, tid, args: { sort_index: tid } });
+  }
+  return out;
+}
+
+/** Unix milliseconds, to the microsecond where the clock has it. */
+export function unixMs(): number {
+  return performance.timeOrigin + performance.now();
+}
+
+/** A trace being recorded: takes appended as they come, the document at the end. */
+export class Trace {
+  readonly events: TraceEvent[];
+  readonly origin: number;
+  readonly producer: string;
+  /** Thread names already in the document (a take names a thread once per engine trace; a document may hold several). */
+  private named = new Set<number>();
+  /** µs from the engine's clock to the document's origin, set by the first take. */
+  private shift: number | undefined;
+
+  /** A new document from `origin` (Unix ms), or one continued from `prior` (og's prelude: the cook). */
+  constructor(opts: { origin?: number; prior?: Partial<TraceDocument>; producer: string; process?: string }) {
+    this.producer = opts.producer;
+    if (opts.prior?.traceEvents) {
+      this.events = [...opts.prior.traceEvents];
+      this.origin = opts.prior.otherData?.originUnixMs ?? opts.origin ?? unixMs();
+    } else {
+      this.events = traceMetadata(opts.process ?? opts.producer);
+      this.origin = opts.origin ?? unixMs();
+    }
+    for (const e of this.events) if (e.ph === "M" && e.name === "thread_name") this.named.add(e.tid);
+  }
+
+  /**
+   * Places one take of the engine (`og_*_trace_take`'s JSON) on the
+   * document's origin: `hostNow` is the host's Unix ms read beside the take.
+   */
+  append(taken: string | { now: number; events: TraceEvent[] }, hostNow: number = unixMs()): void {
+    const t = typeof taken === "string" ? (JSON.parse(taken) as { now: number; events: TraceEvent[] }) : taken;
+    // One shift for the whole trace, from the first take: both clocks are
+    // monotonic at the same rate, and a shift read again at every take
+    // would move spans that abut across two takes by its jitter (tens of
+    // µs), so that they overlap.
+    this.shift ??= Math.round((hostNow - t.now - this.origin) * 1000);
+    const shift = this.shift;
+    for (const e of t.events) {
+      if (e.ph === "M") {
+        if (e.name === "thread_name") {
+          if (this.named.has(e.tid)) continue;
+          this.named.add(e.tid);
+        }
+        this.events.push(e);
+        continue;
+      }
+      this.events.push({ ...e, ts: (e.ts ?? 0) + shift });
+    }
+  }
+
+  document(extra: Record<string, unknown> = {}): TraceDocument {
+    return { traceEvents: this.events, displayTimeUnit: "ms", otherData: { originUnixMs: this.origin, producer: this.producer, ...extra } };
+  }
+}
+
+/** What {@link checkTrace} found. */
+export type TraceCheck = { errors: string[]; spans: number; threads: Record<number, string> };
+
+/**
+ * Holds a document to the format as Perfetto's importer reads it, and to
+ * what this engine's traces promise: `traceEvents` a list; every `X` event
+ * a name, integer `ts`, `dur` ≥ 0 and integer `pid`/`tid`; metadata with
+ * `args.name`; every span on a thread nested inside the one it starts in
+ * (never overlapping it); and spans that lie where they ran. A thread whose
+ * children are laid end to end from their parent's start in every parent
+ * (the first child at the parent's `ts`, each next one where the previous
+ * ended), over at least `endToEndAfter` parents with two or more children,
+ * is reported: recorded starts leave gaps somewhere. The GPU's passes
+ * (`cat` "gpu") are exempt: one timestamp ends a pass and begins the next,
+ * so they are back to back by the measurement's construction.
+ */
+export function checkTrace(doc: unknown, endToEndAfter = 8): TraceCheck {
+  const errors: string[] = [];
+  const threads: Record<number, string> = {};
+  const d = doc as Partial<TraceDocument> | null;
+  if (!d || !Array.isArray(d.traceEvents)) return { errors: ["traceEvents is not a list"], spans: 0, threads };
+  const byTid = new Map<number, { ts: number; dur: number; name: string }[]>();
+  const backToBack = new Set<number>();
+  for (const e of d.traceEvents) {
+    if (!Number.isInteger(e.pid) || !Number.isInteger(e.tid)) errors.push(`${e.name}: pid/tid not integers`);
+    if (e.ph === "M") {
+      const name = (e.args as { name?: unknown } | undefined)?.name;
+      if ((e.name === "thread_name" || e.name === "process_name") && typeof name !== "string") errors.push(`${e.name} metadata without args.name`);
+      if (e.name === "thread_name" && typeof name === "string") threads[e.tid] = name;
+      continue;
+    }
+    if (e.ph !== "X") continue;
+    if (typeof e.name !== "string" || !Number.isInteger(e.ts) || !Number.isInteger(e.dur) || (e.dur as number) < 0) {
+      errors.push(`malformed span ${JSON.stringify(e).slice(0, 120)}`);
+      continue;
+    }
+    let list = byTid.get(e.tid);
+    if (!list) byTid.set(e.tid, (list = []));
+    list.push({ ts: e.ts as number, dur: e.dur as number, name: e.name });
+    if (e.cat === "gpu") backToBack.add(e.tid);
+  }
+  let spans = 0;
+  for (const [tid, list] of byTid) {
+    if (!(tid in threads)) errors.push(`thread ${tid} has spans and no name`);
+    spans += list.length;
+    // Parents first: earlier start, then the longer one.
+    list.sort((a, b) => a.ts - b.ts || b.dur - a.dur);
+    const stack: { ts: number; end: number; name: string; children: { ts: number; end: number }[] }[] = [];
+    const closed: { ts: number; children: { ts: number; end: number }[] }[] = [];
+    const close = () => closed.push(stack.pop()!);
+    for (const s of list) {
+      const end = s.ts + s.dur;
+      while (stack.length && stack[stack.length - 1]!.end <= s.ts) close();
+      const top = stack[stack.length - 1];
+      if (top && end > top.end) {
+        errors.push(`thread ${tid}: ${s.name} [${s.ts}, ${end}] overlaps ${top.name} [${top.ts}, ${top.end}] without nesting`);
+        continue;
+      }
+      top?.children.push({ ts: s.ts, end });
+      stack.push({ ts: s.ts, end, name: s.name, children: [] });
+    }
+    while (stack.length) close();
+    const parents = closed.filter((p) => p.children.length >= 2);
+    const laid = parents.filter((p) => p.children[0]!.ts === p.ts && p.children.every((c, i) => i === 0 || c.ts === p.children[i - 1]!.end));
+    if (!backToBack.has(tid) && parents.length >= endToEndAfter && laid.length === parents.length) {
+      errors.push(`thread ${tid} (${threads[tid] ?? "?"}): the children of all ${parents.length} parents are laid end to end from the parent's start: starts were derived, not recorded`);
+    }
+  }
+  return { errors, spans, threads };
+}

package/src/ui-kit/huds.ts

@@ -8,7 +8,7 @@
 
 import type * as Api from "@origingame/engine";
 import { kit } from "./bind.ts";
-import { all, capsule, clock, fit, fmt, frame, grow, iconOr, lapTime, px, token } from "./util.ts";
+import { all, hudBox, clock, fit, fmt, frame, grow, iconOr, lapTime, px, token } from "./util.ts";
 
 type Hud = { paused: boolean; action: string | null; moveX: number; moveY: number; held: string[] };
 
@@ -27,7 +27,7 @@ function pauseButton(out: Hud, label: string): void {
 function stat(id: string, value: string, caption: string, step: Api.TypeStepName = "xl3", align: Api.TextAlign = "start"): void {
   kit.column(id, { gap: 0, cross: align === "end" ? "end" : align === "center" ? "center" : "start" }, () => {
     kit.label("Value", value, { step, font: "mono", nowrap: true, align });
-    kit.label("Caption", caption, { step: "meta", color: token("fgMuted"), nowrap: true, align });
+    kit.label("Caption", caption, { step: "meta", color: token("inkMuted"), nowrap: true, align });
   });
 }
 
@@ -58,36 +58,36 @@ export function platformerHud(id: string, desc: Api.PlatformerHudDesc = {}): Api
   const { t, touch } = frame();
   const out = hud();
   // What the game leaves out is not drawn: no hearts with maxLives 0 (and
-  // no health bar), no coins or score capsule without coins or score.
+  // no health bar), no coins or score box without coins or score.
   const health = desc.health ?? null;
   const maxLives = desc.maxLives ?? 3;
   const coins = desc.coins ?? null;
   const score = desc.score ?? null;
   if (health !== null || maxLives > 0 || desc.level) {
     kit.anchor(`${id}.left`, { anchor: "topLeft", direction: "column", gap: t.sm }, () => {
-      if (health !== null) capsule("Lives", () => kit.meter("Health", health, 1, { width: px(120) }));
+      if (health !== null) hudBox("Lives", () => kit.meter("Health", health, 1, { width: px(120) }));
       else if (maxLives > 0) {
-        capsule("Lives", () => {
-          for (let i = 0; i < maxLives; i++) iconOr(kit.idi("Life", i), "heart", 20, token(i < (desc.lives ?? 0) ? "danger" : "fillStrong"));
+        hudBox("Lives", () => {
+          for (let i = 0; i < maxLives; i++) iconOr(kit.idi("Life", i), "heart", 20, token(i < (desc.lives ?? 0) ? "danger" : "controlStrong"));
         });
       }
-      if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("fgMuted"), nowrap: true });
+      if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("inkMuted"), nowrap: true });
     });
   }
   if (desc.timeLeft !== null && desc.timeLeft !== undefined) {
     const low = desc.timeLeft <= 10;
     kit.anchor(`${id}.top`, { anchor: "top" }, () => {
-      capsule("Timer", () => kit.label("Time", clock(desc.timeLeft!), { step: "lg", font: "mono", color: token(low ? "danger" : "fg"), nowrap: true }));
+      hudBox("Timer", () => kit.label("Time", clock(desc.timeLeft!), { step: "lg", font: "mono", color: token(low ? "danger" : "ink"), nowrap: true }));
     });
   }
   kit.anchor(`${id}.right`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
     if (coins !== null) {
-      capsule("Coins", () => {
-        iconOr("Coin", "coin", 20, token("accent"));
+      hudBox("Coins", () => {
+        iconOr("Coin", "coin", 20, token("gold"));
         kit.label("Count", fmt(coins), { font: "mono", nowrap: true });
       });
     }
-    if (score !== null) capsule("Score", () => kit.label("Points", fmt(score), { font: "mono", nowrap: true }));
+    if (score !== null) hudBox("Score", () => kit.label("Points", fmt(score), { font: "mono", nowrap: true }));
     pauseButton(out, desc.pauseLabel ?? "Pause");
   });
   if ((desc.touch ?? false) && touch) touchControls(out, { dpad: true, buttons: [{ id: "jump", label: desc.jumpLabel ?? "Jump", primary: true }] });
@@ -96,7 +96,7 @@ export function platformerHud(id: string, desc: Api.PlatformerHudDesc = {}): Api
 
 /** A crosshair at the centre: four short strokes and a gap. */
 function crosshair(): void {
-  const ink = token("fg", 0.9);
+  const ink = token("ink", 0.9);
   const bar = (id: string, w: number, h: number): void => kit.image(id, { tint: ink, width: px(w), height: px(h) });
   kit.anchor("Crosshair", { anchor: "center", direction: "column", cross: "center", gap: 6 }, () => {
     bar("N", 2, 8);
@@ -121,9 +121,9 @@ export function shooterHud(id: string, desc: Api.ShooterHudDesc = {}): Api.HudRe
   });
   if (desc.map && !showTouch) kit.anchor(`${id}.map`, { anchor: "topLeft" }, () => kit.minimap("Map", desc.map!));
   kit.anchor(`${id}.top`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
-    capsule("Kills", () => {
+    hudBox("Kills", () => {
       kit.label("Count", fmt(desc.kills ?? 0), { font: "mono", nowrap: true });
-      kit.label("Unit", desc.killsLabel ?? "kills", { step: "meta", color: token("fgMuted"), nowrap: true });
+      kit.label("Unit", desc.killsLabel ?? "kills", { step: "meta", color: token("inkMuted"), nowrap: true });
     });
     pauseButton(out, desc.pauseLabel ?? "Pause");
   });
@@ -131,10 +131,10 @@ export function shooterHud(id: string, desc: Api.ShooterHudDesc = {}): Api.HudRe
     const mag = desc.magazine ?? 0;
     const ammo = desc.ammo ?? 0;
     kit.row("Rounds", { gap: t.xs, cross: "end" }, () => {
-      kit.label("Ammo", `${ammo}`, { step: "xl5", font: "mono", color: token(mag > 0 && ammo <= Math.floor(mag / 4) ? "warn" : "fg"), nowrap: true });
-      kit.label("Reserve", `/ ${desc.reserve ?? 0}`, { step: "lg", font: "mono", color: token("fgMuted"), nowrap: true });
+      kit.label("Ammo", `${ammo}`, { step: "xl5", font: "mono", color: token(mag > 0 && ammo <= Math.floor(mag / 4) ? "warn" : "ink"), nowrap: true });
+      kit.label("Reserve", `/ ${desc.reserve ?? 0}`, { step: "lg", font: "mono", color: token("inkMuted"), nowrap: true });
     });
-    if (desc.weapon) kit.label("Weapon", desc.weapon, { step: "meta", color: token("fgMuted"), nowrap: true });
+    if (desc.weapon) kit.label("Weapon", desc.weapon, { step: "meta", color: token("inkMuted"), nowrap: true });
   });
   const abilities = desc.abilities ?? [];
   if (abilities.length > 0) {
@@ -158,20 +158,20 @@ export function puzzleHud(id: string, desc: Api.PuzzleHudDesc = {}): Api.HudResu
   const score = desc.score ?? 0;
   const marks = desc.stars && desc.stars.length > 0 ? desc.stars : [Math.round(target / 3), Math.round((2 * target) / 3), target];
   kit.anchor(`${id}.left`, { anchor: "topLeft", direction: "column", gap: t.xs }, () => {
-    if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("fgMuted"), nowrap: true });
+    if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("inkMuted"), nowrap: true });
     if (desc.moves !== null && desc.moves !== undefined) stat("Moves", `${desc.moves}`, desc.movesLabel ?? "moves left", "xl3");
   });
   kit.anchor(`${id}.score`, { anchor: "top", direction: "column", cross: "center", gap: t.xs, width: px(260) }, () => {
     kit.label("Score", fmt(score), { step: "displaySm", font: "display", align: "center", width: grow() });
-    kit.meter("Progress", score, target, { kind: "accent", width: grow(), segments: 3 });
+    kit.meter("Progress", score, target, { kind: "primary", width: grow(), segments: 3 });
     kit.row("Stars", { gap: t.sm, cross: "center" }, () => {
-      marks.slice(0, 3).forEach((m, i) => iconOr(kit.idi("Star", i), "star", 20, token(score >= m ? "accent" : "fillStrong")));
-      kit.label("Target", (desc.targetLabel ?? "Target {target}").replaceAll("{target}", fmt(target)), { step: "meta", color: token("fgMuted"), nowrap: true });
+      marks.slice(0, 3).forEach((m, i) => iconOr(kit.idi("Star", i), "star", 20, token(score >= m ? "primary" : "controlStrong")));
+      kit.label("Target", (desc.targetLabel ?? "Target {target}").replaceAll("{target}", fmt(target)), { step: "meta", color: token("inkMuted"), nowrap: true });
     });
   });
   kit.anchor(`${id}.right`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
     if (desc.timeLeft !== null && desc.timeLeft !== undefined) {
-      capsule("Timer", () => kit.label("Time", clock(desc.timeLeft!), { font: "mono", color: token(desc.timeLeft! <= 10 ? "danger" : "fg"), nowrap: true }));
+      hudBox("Timer", () => kit.label("Time", clock(desc.timeLeft!), { font: "mono", color: token(desc.timeLeft! <= 10 ? "danger" : "ink"), nowrap: true }));
     }
     pauseButton(out, desc.pauseLabel ?? "Pause");
   });
@@ -185,8 +185,8 @@ export function idleHud(id: string, desc: Api.IdleHudDesc = {}): Api.HudResult {
   const generators = desc.generators ?? [];
   kit.anchor(`${id}.wallet`, { anchor: "top", gap: t.sm, cross: "center" }, () => {
     currencies.forEach((c, i) => {
-      capsule(c.id ?? kit.idi("Currency", i), () => {
-        if (c.icon) iconOr("Icon", c.icon, 20, token("accent"));
+      hudBox(c.id ?? kit.idi("Currency", i), () => {
+        if (c.icon) iconOr("Icon", c.icon, 20, token("primary"));
         kit.label("Amount", fmt(c.amount ?? 0), { step: i === 0 ? "lg" : "body", font: "mono", nowrap: true });
         if ((c.perSecond ?? 0) !== 0) kit.label("Rate", (desc.rateLabel ?? "+{rate}/s").replaceAll("{rate}", fmt(c.perSecond ?? 0)), { step: "meta", color: token("success"), nowrap: true });
       }, { height: i === 0 ? t.controlLg : t.controlMd });
@@ -204,13 +204,13 @@ export function idleHud(id: string, desc: Api.IdleHudDesc = {}): Api.HudResult {
     kit.panel("Generators", { width: grow(), padding: all(t.sm), gap: t.xs }, () => {
       kit.list("List", { count: generators.length, rowHeight: 64, gap: t.xs, height: fit(0, listHeight), width: grow() }, (i) => {
         const g = generators[i]!;
-        if (g.icon) iconOr("Icon", g.icon, 32, token("fg"));
+        if (g.icon) iconOr("Icon", g.icon, 32, token("ink"));
         kit.column("Text", { width: grow(), gap: t.xxs }, () => {
           kit.row("Head", { gap: t.sm, cross: "center", width: grow() }, () => {
             kit.label("Name", g.name ?? g.id ?? "", { step: "lg", nowrap: true, width: grow() });
             kit.badge("Level", (desc.levelLabel ?? "Lv {level}").replaceAll("{level}", `${g.level ?? 0}`), "neutral");
           });
-          kit.meter("Cycle", g.progress ?? 0, 1, { kind: "accent", height: 4, width: grow() });
+          kit.meter("Cycle", g.progress ?? 0, 1, { kind: "primary", height: 4, width: grow() });
         });
         const buy = kit.button("Buy", fmt(g.cost ?? 0), { size: "small", variant: g.affordable ? "primary" : "secondary", disabled: !g.affordable }) as Api.Response;
         if (buy.clicked) out.action = `buy:${g.id ?? i}`;
@@ -229,7 +229,7 @@ function deltaText(seconds: number): string {
 
 /** A delta's ink: ahead (negative) success, behind danger, even muted. */
 function deltaInk(seconds: number): Api.Paint {
-  return token(seconds < 0 ? "success" : seconds > 0 ? "danger" : "fgMuted");
+  return token(seconds < 0 ? "success" : seconds > 0 ? "danger" : "inkMuted");
 }
 
 export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResult {
@@ -244,7 +244,7 @@ export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResu
     if (racers > 0) {
       kit.row("Position", { gap: t.xxs, cross: "end" }, () => {
         kit.label("Place", `${desc.position ?? 1}`, { step: "displayXl", font: "display", nowrap: true });
-        kit.label("Of", `/${racers}`, { step: "xl", font: "mono", color: token("fgMuted"), nowrap: true });
+        kit.label("Of", `/${racers}`, { step: "xl", font: "mono", color: token("inkMuted"), nowrap: true });
       });
     }
     stat("Lap", `${Math.min(desc.lap ?? 1, desc.laps ?? 3)}/${desc.laps ?? 3}`, desc.lapLabel ?? "lap", "xl3");
@@ -258,16 +258,16 @@ export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResu
     if (delta !== null) kit.label("Delta", deltaText(delta), { step: "lg", font: "mono", color: deltaInk(delta), nowrap: true });
     if (desc.best !== null && desc.best !== undefined) {
       // A finished lap: m:ss.mmm as lapTime cuts it (30.717 s is 0:30.717, where the running clock's floor reads 0:30.716).
-      kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", lapTime(desc.best)), { step: "meta", font: "mono", color: token("fgMuted"), nowrap: true });
+      kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", lapTime(desc.best)), { step: "meta", font: "mono", color: token("inkMuted"), nowrap: true });
     }
     const splits = desc.splits ?? [];
     if (splits.length > 0) {
       kit.column("Splits", { gap: 0, cross: "end" }, () => {
         splits.forEach((sp, i) => {
           kit.row(kit.idi("Split", i), { gap: t.sm, cross: "center" }, () => {
-            kit.label("Label", sp.label ?? "", { step: "meta", color: token("fgMuted"), nowrap: true });
+            kit.label("Label", sp.label ?? "", { step: "meta", color: token("inkMuted"), nowrap: true });
             const time = sp.time ?? null;
-            kit.label("Time", time === null ? "-:--.---" : lapTime(time), { step: "meta", font: "mono", color: token(time === null ? "fgSubtle" : "fg"), nowrap: true });
+            kit.label("Time", time === null ? "-:--.---" : lapTime(time), { step: "meta", font: "mono", color: token(time === null ? "inkFaint" : "ink"), nowrap: true });
             const d = sp.delta ?? null;
             if (d !== null) kit.label("Delta", deltaText(d), { step: "meta", font: "mono", color: deltaInk(d), nowrap: true });
           });
@@ -280,11 +280,11 @@ export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResu
     kit.row("Speed", { gap: t.sm, cross: "end", width: grow(), align: "end" }, () => {
       kit.label("Value", `${Math.round(desc.speed ?? 0)}`, { step: "displayXl2", font: "display", nowrap: true });
       kit.column("Side", { cross: "end" }, () => {
-        kit.label("Gear", desc.gear ?? "N", { step: "xl", font: "mono", color: token("accentInk"), nowrap: true });
-        kit.label("Unit", desc.unit ?? "km/h", { step: "meta", color: token("fgMuted"), nowrap: true });
+        kit.label("Gear", desc.gear ?? "N", { step: "xl", font: "mono", color: token("highlight"), nowrap: true });
+        kit.label("Unit", desc.unit ?? "km/h", { step: "meta", color: token("inkMuted"), nowrap: true });
       });
     });
-    kit.meter("Rev", desc.speed ?? 0, desc.maxSpeed ?? 300, { kind: "accent", width: grow(), height: 6 });
+    kit.meter("Rev", desc.speed ?? 0, desc.maxSpeed ?? 300, { kind: "primary", width: grow(), height: 6 });
     if (boost !== null) kit.meter("Boost", boost, 1, { color: token("info"), label: boostLabel, width: grow(), segments: 4 });
   });
   if (showTouch) {

package/src/ui-kit/menus.ts

@@ -36,17 +36,17 @@ export function mainMenu(id: string, desc: Api.MainMenuDesc = {}): Api.MenuResul
     cross: "center",
     width: phone ? grow() : px(380),
     padding: all(phone ? t.lg : t.xl),
-    background: token("materialThick"),
+    background: token("hud"),
     radius: t.panel,
     instant: desc.instant ?? false,
   }, () => {
     kit.column("Heading", { gap: t.xs, cross: "center", width: grow() }, () => {
       kit.label("Title", desc.title ?? "", { step: phone ? "displayMd" : "displayLg", font: "display", align: "center", width: grow(), heading: true });
-      if (desc.subtitle) kit.label("Subtitle", desc.subtitle, { color: token("fgMuted"), align: "center", width: grow() });
+      if (desc.subtitle) kit.label("Subtitle", desc.subtitle, { color: token("inkMuted"), align: "center", width: grow() });
     });
     // A title menu is not a dialog, so it takes the focus itself: Enter and the pad's A answer at once.
     chosen = menuColumn("Items", items, grow(), true);
-    if (desc.footer) kit.label("Footer", desc.footer, { step: "meta", color: token("fgSubtle"), align: "center", width: grow() });
+    if (desc.footer) kit.label("Footer", desc.footer, { step: "meta", color: token("inkFaint"), align: "center", width: grow() });
   });
   if (chosen !== null) desc.onSelect?.(chosen);
   return { selected: chosen };
@@ -68,7 +68,7 @@ export function confirmDialog(id: string, desc: Api.ConfirmDesc = {}): Api.Confi
   let confirmed = false;
   let cancelled = false;
   const m = kit.modal(id, desc.open ?? false, { title: desc.title ?? "" }, () => {
-    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("fgMuted"), width: grow() });
+    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("inkMuted"), width: grow() });
     kit.row("Actions", { width: grow(), gap: t.sm, align: "end", padding: { left: 0, top: t.sm, right: 0, bottom: 0 } }, () => {
       if ((kit.button("Cancel", desc.cancelLabel ?? "Cancel", {}) as Api.Response).clicked) cancelled = true;
       if ((kit.button("Confirm", desc.confirmLabel ?? "Confirm", { variant: desc.danger ? "danger" : "primary" }) as Api.Response).clicked) confirmed = true;
@@ -82,7 +82,7 @@ export function alertDialog(id: string, desc: Api.AlertDesc = {}): boolean {
   const { t } = frame();
   let done = false;
   const m = kit.modal(id, desc.open ?? false, { title: desc.title ?? "" }, () => {
-    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("fgMuted"), width: grow() });
+    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("inkMuted"), width: grow() });
     kit.row("Actions", { width: grow(), align: "end", padding: { left: 0, top: t.sm, right: 0, bottom: 0 } }, () => {
       if ((kit.button("Ok", desc.okLabel ?? "OK", { variant: "primary" }) as Api.Response).clicked) done = true;
     });
@@ -94,7 +94,7 @@ export function loadingScreen(id: string, desc: Api.LoadingDesc = {}): void {
   const { t } = frame();
   const tips = desc.tips ?? [];
   const tip = tips.length > 0 ? tips[Math.floor(kit.seconds() / Math.max(1, desc.tipSeconds ?? 4)) % tips.length]! : "";
-  kit.modal(id, true, { locked: true, bare: true, backdrop: token("bg"), transition: "fade", width: px(Math.min(380, frame().viewport.width - 32)) }, () => {
+  kit.modal(id, true, { locked: true, bare: true, backdrop: token("backdrop"), transition: "fade", width: px(Math.min(380, frame().viewport.width - 32)) }, () => {
     kit.label("Title", desc.title ?? "Loading", { step: "xl", align: "center", width: grow(), heading: true });
     const p = desc.progress;
     if (p === null || p === undefined) {
@@ -103,10 +103,10 @@ export function loadingScreen(id: string, desc: Api.LoadingDesc = {}): void {
       // A real value only: the bar never runs ahead of what loaded.
       kit.row("Bar", { width: grow(), gap: t.md, cross: "center" }, () => {
         kit.progress("Progress", p, { width: grow() });
-        kit.label("Percent", `${Math.floor(Math.max(0, Math.min(1, p)) * 100)}%`, { step: "meta", font: "mono", color: token("fgMuted"), nowrap: true });
+        kit.label("Percent", `${Math.floor(Math.max(0, Math.min(1, p)) * 100)}%`, { step: "meta", font: "mono", color: token("inkMuted"), nowrap: true });
       });
     }
-    if (tip) kit.label("Tip", tip, { step: "reading", color: token("fgMuted"), align: "center", width: grow() });
+    if (tip) kit.label("Tip", tip, { step: "reading", color: token("inkMuted"), align: "center", width: grow() });
   });
 }
 
@@ -118,7 +118,7 @@ function stars(id: string, earned: number, max: number, since: number, size: num
       const shown = kit.seconds() - since >= 0.3 * (k + 1);
       const on = k < earned;
       kit.transition(kit.idi("Star", k), shown, { kind: "scale", instant: false }, () => {
-        iconOr("Mark", "star", size, token(on ? "accent" : "fillStrong"));
+        iconOr("Mark", "star", size, token(on ? "primary" : "controlStrong"));
         if (on) kit.burst({ delayMs: 120 });
       });
       if (!shown) kit.spacer(kit.idi("Gap", k), px(size));
@@ -147,7 +147,7 @@ export function resultsScreen(id: string, desc: Api.ResultsDesc = {}): Api.MenuR
     const max = desc.maxStars ?? 3;
     if (max > 0) kit.row("StarRow", { width: grow(), align: "center" }, () => stars("Stars", desc.stars ?? 0, max, since, 44));
     kit.column("ScoreBlock", { width: grow(), cross: "center", gap: t.xxs }, () => {
-      if (desc.scoreLabel) kit.label("ScoreLabel", desc.scoreLabel, { step: "meta", color: token("fgMuted"), align: "center", width: grow(), nowrap: true });
+      if (desc.scoreLabel) kit.label("ScoreLabel", desc.scoreLabel, { step: "meta", color: token("inkMuted"), align: "center", width: grow(), nowrap: true });
       if (time) {
         // A time counts up as a clock (ease-out cubic over the same 0.9 s), the headline in m:ss.mmm.
         const k = open ? Math.min(1, Math.max(0, (kit.seconds() - since) / 0.9)) : 1;
@@ -158,8 +158,8 @@ export function resultsScreen(id: string, desc: Api.ResultsDesc = {}): Api.MenuR
       }
       if (!time || best > 0 || desc.newBest) {
         kit.row("BestRow", { gap: t.sm, cross: "center" }, () => {
-          if (!time || best > 0) kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", time ? lapTime(best) : fmt(best)), { step: "meta", color: token("fgMuted"), nowrap: true });
-          if (desc.newBest) kit.transition("Reveal", landed, { kind: "pop" }, () => kit.badge("NewBest", desc.newBestLabel ?? "New best", "accent"));
+          if (!time || best > 0) kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", time ? lapTime(best) : fmt(best)), { step: "meta", color: token("inkMuted"), nowrap: true });
+          if (desc.newBest) kit.transition("Reveal", landed, { kind: "pop" }, () => kit.badge("NewBest", desc.newBestLabel ?? "New best", "primary"));
         });
       }
     });

package/src/ui-kit/settings.ts

@@ -2,8 +2,11 @@
 // game's GameSettings. The game owns the values (a resource, a save); the
 // screen answers the new ones every tick and calls the hooks: onChange on
 // every change (apply it at once), onSave when it closes after changes.
+// A new graphics preset is applied to SettingsDesc.world by the screen
+// itself (og.render.applyQuality) before onChange.
 
 import type * as Api from "@origingame/engine";
+import { render } from "../runtime.ts";
 import { kit } from "./bind.ts";
 import { frame, grow, px, token } from "./util.ts";
 
@@ -40,7 +43,7 @@ function sliderRow(id: string, label: string, value: number, desc: Api.SliderDes
     kit.label("Label", label, { width: px(phone ? 96 : 140), nowrap: true });
     const r = kit.slider("Slider", value, desc) as Api.SliderResult;
     out = r.value;
-    kit.label("Value", shown, { width: px(48), align: "end", font: "mono", color: token("fgMuted"), nowrap: true });
+    kit.label("Value", shown, { width: px(48), align: "end", font: "mono", color: token("inkMuted"), nowrap: true });
   });
   return out;
 }
@@ -82,7 +85,7 @@ export function settingsScreen(id: string, desc: Api.SettingsDesc = {}): Api.Set
         }
         case "graphics": {
           const quality = desc.qualityLabel ?? "Quality";
-          kit.label("QualityLabel", quality, { step: "meta", color: token("fgMuted") });
+          kit.label("QualityLabel", quality, { step: "meta", color: token("inkMuted") });
           const levels = [desc.lowLabel ?? "Low", desc.mediumLabel ?? "Medium", desc.highLabel ?? "High"];
           const q = kit.radio("Quality", levels, QUALITIES.indexOf(s.quality), { horizontal: !phone, label: quality });
           s.quality = QUALITIES[q.selected] ?? "medium";
@@ -119,6 +122,12 @@ export function settingsScreen(id: string, desc: Api.SettingsDesc = {}): Api.Set
   const changed = JSON.stringify(s) !== JSON.stringify(before);
   if (changed) {
     dirty = true;
+    // The preset is RenderSettings' quality fields (og.render.applyQuality):
+    // the next frame draws it, and the probe reads what is drawn.
+    if (s.quality !== before.quality && desc.world) {
+      const r = render.applyQuality(desc.world as unknown as Parameters<typeof render.applyQuality>[0], s.quality) as Api.Result<void>;
+      if (!r.ok) throw new Error(`og.ui.settingsScreen: ${r.reason}`);
+    }
     desc.onChange?.(s);
   }
   if (closed && dirty) {