@orakl/shared 0.1.0

package/dist/badges.js

@@ -0,0 +1,667 @@
+// Achievement badges. A badge is an honour earned for *how* a run was played
+// (not just the score) — a clean sweep, precision, a hot streak, speed, focus,
+// survival, a podium finish. One canonical registry serves every mode: each
+// badge is tagged with the modes that can award it (cross-mode, solo-only or
+// multiplayer-only — ADR 0018). Earned badges are surfaced on the results
+// screen and tallied across runs on the player's trials page ("No hesitation
+// ×3"). Computation is a pure function so it stays testable and is the single
+// source of truth for server (authoritative award + persistence) and client
+// (display).
+//
+// Rarity is hybrid: each badge has a base tier, then the run's conditions (more
+// questions, shorter/longer timer, harder difficulty, a bigger field of heroes)
+// bump it up — a Flawless on 30 questions at a 5s clock is rarer than one on
+// the default 10 at 60s. Rarity is fully derivable from the run's parameters,
+// so it's recomputed wherever a badge renders rather than stored.
+import { percent } from "./math.js";
+const CROSS_MODE = ["solo", "multiplayer"];
+const SOLO_ONLY = ["solo"];
+const MULTIPLAYER_ONLY = ["multiplayer"];
+/** Display order, most prestigious first. */
+export const BADGE_ORDER = [
+    "victor",
+    "flawless",
+    "unstoppable",
+    "on-a-roll",
+    "survivor",
+    "giant-slayer",
+    "sharpshooter",
+    "podium",
+    "pantheon",
+    "specialist",
+    "polymath",
+    "phoenix",
+    "strong-finish",
+    "master-of-none",
+    "faster-than-most",
+    "clutch",
+    "quick-draw",
+    "decisive",
+    "sure-handed",
+    "unbroken-focus",
+    "devotee",
+];
+export const BADGES = {
+    victor: {
+        id: "victor",
+        label: "Victor",
+        description: "Topped the field in a multiplayer quiz.",
+        icon: "banner",
+        modes: MULTIPLAYER_ONLY,
+    },
+    podium: {
+        id: "podium",
+        label: "Podium",
+        description: "Finished among the top three in a multiplayer quiz.",
+        icon: "steps",
+        modes: MULTIPLAYER_ONLY,
+    },
+    flawless: {
+        id: "flawless",
+        label: "Flawless",
+        description: "Cleared a trial without a single miss.",
+        icon: "wreath",
+        modes: CROSS_MODE,
+    },
+    unstoppable: {
+        id: "unstoppable",
+        label: "Unstoppable",
+        description: "Strung together a streak of ten or more.",
+        icon: "stars",
+        modes: CROSS_MODE,
+    },
+    "on-a-roll": {
+        id: "on-a-roll",
+        label: "On a roll",
+        description: "Strung together a streak of six or more.",
+        icon: "flame",
+        modes: CROSS_MODE,
+    },
+    survivor: {
+        id: "survivor",
+        label: "Survivor",
+        description: "Endured twenty or more questions in an endless run.",
+        icon: "shield",
+        modes: SOLO_ONLY,
+    },
+    "giant-slayer": {
+        id: "giant-slayer",
+        label: "Giant slayer",
+        description: "Cleared a hard-difficulty trial with commanding accuracy.",
+        icon: "empty-skull",
+        modes: CROSS_MODE,
+    },
+    pantheon: {
+        id: "pantheon",
+        label: "Pantheon",
+        description: "Aced two or more categories in a single trial.",
+        icon: "olympus",
+        modes: CROSS_MODE,
+    },
+    phoenix: {
+        id: "phoenix",
+        label: "Phoenix",
+        description: "Rallied to a long streak after an early stumble.",
+        icon: "flower-1",
+        modes: CROSS_MODE,
+    },
+    clutch: {
+        id: "clutch",
+        label: "Clutch",
+        description: "Landed answers in the dying moments of the clock.",
+        icon: "clock",
+        modes: CROSS_MODE,
+    },
+    sharpshooter: {
+        id: "sharpshooter",
+        label: "Sharpshooter",
+        description: "Finished a trial with near-perfect accuracy.",
+        icon: "rhombus",
+        modes: CROSS_MODE,
+    },
+    specialist: {
+        id: "specialist",
+        label: "Specialist",
+        description: "Aced every question in a category.",
+        icon: "owl",
+        modes: CROSS_MODE,
+    },
+    polymath: {
+        id: "polymath",
+        label: "Polymath",
+        description: "Answered well across easy, medium and hard in one trial.",
+        icon: "scroll",
+        modes: CROSS_MODE,
+    },
+    "strong-finish": {
+        id: "strong-finish",
+        label: "Strong finish",
+        description: "Closed out a trial on a long unbroken streak.",
+        icon: "flags",
+        modes: CROSS_MODE,
+    },
+    "sure-handed": {
+        id: "sure-handed",
+        label: "Sure-handed",
+        description: "Committed every answer without second-guessing.",
+        icon: "check",
+        modes: SOLO_ONLY,
+    },
+    devotee: {
+        id: "devotee",
+        label: "Devotee",
+        description: "Returned to the oracle on consecutive days.",
+        icon: "church",
+        modes: SOLO_ONLY,
+    },
+    "master-of-none": {
+        id: "master-of-none",
+        label: "Master of none",
+        description: "Earned a spread of honours across many categories at once.",
+        icon: "dice",
+        modes: CROSS_MODE,
+    },
+    "faster-than-most": {
+        id: "faster-than-most",
+        label: "Faster than most",
+        description: "Beat most other players' time on a question.",
+        icon: "top-right",
+        modes: SOLO_ONLY,
+    },
+    "quick-draw": {
+        id: "quick-draw",
+        label: "Quick draw",
+        description: "Answered with a lightning-fast average time.",
+        icon: "hourglass",
+        modes: CROSS_MODE,
+    },
+    decisive: {
+        id: "decisive",
+        label: "No hesitation",
+        description: "Committed most answers before the clock's halfway mark.",
+        icon: "star",
+        modes: CROSS_MODE,
+    },
+    "unbroken-focus": {
+        id: "unbroken-focus",
+        label: "Unbroken focus",
+        description: "Never left the trial.",
+        icon: "eye-1",
+        modes: SOLO_ONLY,
+    },
+};
+// ── Thresholds ────────────────────────────────────────────────────────────────
+// Tuned so a typical run earns ~1–2 badges, not a handful — the easy-to-stack
+// ones (decisive, quick-draw, focus) carry the higher bars.
+/** Share of answers (0–1) before halfway needed to read as decisive. */
+const DECISIVE_THRESHOLD = 0.7;
+/** Peak streak that earns "on a roll". */
+const ON_A_ROLL_STREAK = 6;
+/** Peak streak that earns the higher-tier "unstoppable" (suppresses on-a-roll). */
+const UNSTOPPABLE_STREAK = 10;
+/** Accuracy (0–1) for sharpshooter — near-perfect but short of flawless. */
+const SHARPSHOOTER_ACCURACY = 0.95;
+/** Minimum answers before sharpshooter is meaningful. */
+const SHARPSHOOTER_MIN_ANSWERED = 6;
+/** Answers floor for the rate badges (quick-draw, decisive) — below this a timing average or halfway share isn't a claim. */
+const RATE_BADGE_MIN_ANSWERED = 6;
+/** Mean time-to-answer (ms) under which a run is a quick draw. */
+const QUICK_DRAW_AVG_MS = 3000;
+/** Minimum answers before "unbroken focus" is an achievement, not a freebie. */
+const UNBROKEN_FOCUS_MIN_ANSWERED = 10;
+/** Per-category correct count needed to claim specialist (must be 100%). */
+const SPECIALIST_MIN_IN_CATEGORY = 4;
+/** A single answer beating more than this % of prior solvers earns faster-than-most. */
+const FASTER_THAN_MOST_PERCENT = 75;
+/** Questions answered in an endless run that earns survivor. */
+const SURVIVOR_QUESTIONS = 20;
+/** Distinct categories a run must span for the "master of none" meta-badge. */
+const MASTER_OF_NONE_MIN_CATEGORIES = 3;
+/** Other badges that must be earned alongside the breadth for "master of none". */
+const MASTER_OF_NONE_MIN_BADGES = 3;
+/** Accuracy (0–1) on a hard run that earns giant-slayer. */
+const GIANT_SLAYER_ACCURACY = 0.9;
+/** Minimum answers before giant-slayer is meaningful. */
+const GIANT_SLAYER_MIN_ANSWERED = 6;
+/** Aced categories needed for the higher-tier "pantheon" (suppresses specialist). */
+const PANTHEON_MIN_CATEGORIES = 2;
+/** Length of a post-stumble recovery streak that earns phoenix. */
+const PHOENIX_STREAK = 5;
+/** Share of the clock (0–1) left when an answer counts as a clutch finish. */
+const CLUTCH_REMAINING_FRACTION = 0.1;
+/** Clutch finishes needed across the run to earn the badge. */
+const CLUTCH_MIN = 3;
+/** Min answers before "sure-handed" (never changed an answer) is an achievement. */
+const SURE_HANDED_MIN_ANSWERED = 8;
+/** Trailing consecutive-correct answers a run must end on for "strong finish". */
+const STRONG_FINISH_STREAK = 5;
+/** Per-band accuracy (0–1) each difficulty must clear for "polymath". */
+const POLYMATH_BAND_ACCURACY = 0.6;
+/** Min questions in a band before it counts toward "polymath". */
+const POLYMATH_MIN_PER_BAND = 2;
+/** Consecutive days played that earns "devotee". */
+const DEVOTEE_DAYS = 3;
+/** Heroes a multiplayer field needs before winning it means anything. */
+const VICTOR_MIN_HEROES = 2;
+/** Highest rank that still counts as a podium finish. */
+const PODIUM_MAX_RANK = 3;
+/** Heroes needed before a podium finish is an achievement (someone missed it). */
+const PODIUM_MIN_HEROES = 4;
+/** Served-questions floor for the rank badges (victor, podium) and lifetime best-rank — below this a rank isn't a claim. */
+export const RANK_BADGE_MIN_QUESTIONS = 6;
+function humanize(categoryId) {
+    return categoryId.replace(/-/g, " ");
+}
+/**
+ * Raw share (0–1) of answers committed before the clock's halfway mark — quick
+ * answers read as decisive (implicit confidence from timing). Null when not
+ * measurable. This is the value the badge gates on (the rounded percent below
+ * is display-only, and rounding up could award the badge under the threshold).
+ */
+export function decisiveShare(input) {
+    if (input.results.length === 0 || input.timerDurationMs <= 0)
+        return null;
+    const half = input.timerDurationMs / 2;
+    const decisive = input.results.filter((r) => r.timeToAnswerMs <= half).length;
+    return decisive / input.results.length;
+}
+/** Rounded percentage form of {@link decisiveShare}, for display. */
+export function decisivenessPercent(input) {
+    const share = decisiveShare(input);
+    return share === null ? null : percent(share);
+}
+/** Categories aced this run (100% correct over the specialist floor). */
+function acedCategories(input) {
+    const tally = new Map();
+    for (const r of input.results) {
+        const e = tally.get(r.categoryId) ?? { correct: 0, total: 0 };
+        e.total++;
+        if (r.isCorrect)
+            e.correct++;
+        tally.set(r.categoryId, e);
+    }
+    const aced = [];
+    for (const [id, v] of tally) {
+        if (v.total >= SPECIALIST_MIN_IN_CATEGORY && v.correct === v.total) {
+            aced.push(id);
+        }
+    }
+    return aced;
+}
+/** Longest run of consecutive correct answers that began after an earlier miss. */
+function comebackStreak(input) {
+    let sawMiss = false;
+    let run = 0;
+    let best = 0;
+    for (const r of input.results) {
+        if (!r.isCorrect) {
+            sawMiss = true;
+            run = 0;
+        }
+        else {
+            run++;
+            if (sawMiss)
+                best = Math.max(best, run);
+        }
+    }
+    return best;
+}
+/** Correct answers committed in the final slice of the clock (clutch finishes). */
+function clutchFinishes(input) {
+    if (input.timerDurationMs <= 0)
+        return 0;
+    const cutoff = input.timerDurationMs * (1 - CLUTCH_REMAINING_FRACTION);
+    return input.results.filter((r) => r.isCorrect && r.timeToAnswerMs >= cutoff)
+        .length;
+}
+/** Length of the unbroken correct streak the run *ended* on (strong finish). */
+function trailingStreak(input) {
+    let run = 0;
+    for (let i = input.results.length - 1; i >= 0; i--) {
+        if (input.results[i].isCorrect)
+            run++;
+        else
+            break;
+    }
+    return run;
+}
+/**
+ * True when the run spanned all three difficulty bands (each over its floor) and
+ * cleared the accuracy bar in every one — a polymath. Needs per-result
+ * difficulty; a single-band or `all`-without-tags run can't qualify.
+ */
+function isPolymath(input) {
+    const bands = new Map();
+    for (const r of input.results) {
+        if (!r.difficulty)
+            continue;
+        const e = bands.get(r.difficulty) ?? { correct: 0, total: 0 };
+        e.total++;
+        if (r.isCorrect)
+            e.correct++;
+        bands.set(r.difficulty, e);
+    }
+    if (bands.size < 3)
+        return false;
+    for (const band of ["easy", "medium", "hard"]) {
+        const e = bands.get(band);
+        if (!e || e.total < POLYMATH_MIN_PER_BAND)
+            return false;
+        if (e.correct / e.total < POLYMATH_BAND_ACCURACY)
+            return false;
+    }
+    return true;
+}
+/** Badges earned by a completed run (solo or multiplayer), in display order. */
+export function computeBadges(input) {
+    const { context } = input;
+    const awards = [];
+    const accuracy = input.totalAnswered > 0 ? input.correctCount / input.totalAnswered : 0;
+    // Victor vs Podium — mutually exclusive (rank already says who won).
+    if (context.kind === "multiplayer") {
+        if (context.rank === 1 &&
+            context.score > 0 &&
+            context.heroCount >= VICTOR_MIN_HEROES &&
+            context.questionsServed >= RANK_BADGE_MIN_QUESTIONS) {
+            awards.push({
+                id: "victor",
+                detail: `first among ${context.heroCount}`,
+            });
+        }
+        else if (context.rank <= PODIUM_MAX_RANK &&
+            context.score > 0 &&
+            context.heroCount >= PODIUM_MIN_HEROES &&
+            context.questionsServed >= RANK_BADGE_MIN_QUESTIONS) {
+            awards.push({ id: "podium", detail: `finished #${context.rank}` });
+        }
+    }
+    // Flawless vs Sharpshooter — mutually exclusive (sharpshooter is "almost").
+    // Multiplayer holds a higher bar: acing every question of the *game* (present
+    // the whole way), not just every question in your own log — a late joiner
+    // going 3/3 in a 10-question game isn't flawless.
+    const flawlessTarget = context.kind === "multiplayer"
+        ? context.totalQuestions
+        : input.totalAnswered;
+    if (input.totalAnswered > 0 &&
+        input.correctCount === input.totalAnswered &&
+        input.correctCount === flawlessTarget) {
+        awards.push({ id: "flawless", detail: "every answer correct" });
+    }
+    else if (input.totalAnswered >= SHARPSHOOTER_MIN_ANSWERED &&
+        accuracy >= SHARPSHOOTER_ACCURACY) {
+        awards.push({
+            id: "sharpshooter",
+            detail: `${percent(accuracy)}% accuracy`,
+        });
+    }
+    // Streak — only the highest tier earned.
+    if (input.maxStreak >= UNSTOPPABLE_STREAK) {
+        awards.push({ id: "unstoppable", detail: `${input.maxStreak} in a row` });
+    }
+    else if (input.maxStreak >= ON_A_ROLL_STREAK) {
+        awards.push({ id: "on-a-roll", detail: `${input.maxStreak} in a row` });
+    }
+    if (context.kind === "solo" &&
+        context.mode === "endless" &&
+        input.totalAnswered >= SURVIVOR_QUESTIONS) {
+        awards.push({
+            id: "survivor",
+            detail: `${input.totalAnswered} answered, ${input.correctCount} correct`,
+        });
+    }
+    // Giant slayer: a strong showing on the hard setting specifically.
+    if (input.difficulty === "hard" &&
+        input.totalAnswered >= GIANT_SLAYER_MIN_ANSWERED &&
+        accuracy >= GIANT_SLAYER_ACCURACY) {
+        awards.push({
+            id: "giant-slayer",
+            detail: `${percent(accuracy)}% on hard`,
+        });
+    }
+    // Pantheon supersedes Specialist — only the higher tier shows.
+    const aced = acedCategories(input);
+    if (aced.length >= PANTHEON_MIN_CATEGORIES) {
+        awards.push({ id: "pantheon", detail: `${aced.length} categories aced` });
+    }
+    else if (aced.length === 1) {
+        awards.push({ id: "specialist", detail: `aced ${humanize(aced[0])}` });
+    }
+    // Polymath: strong across every difficulty band in one trial (STATS-8).
+    if (isPolymath(input)) {
+        awards.push({ id: "polymath", detail: "strong across all difficulties" });
+    }
+    // Phoenix: rallied to a long streak after an earlier miss.
+    const comeback = comebackStreak(input);
+    if (comeback >= PHOENIX_STREAK) {
+        awards.push({ id: "phoenix", detail: `rallied to ${comeback} in a row` });
+    }
+    // Strong finish: closed the trial on a long unbroken streak (STATS-10).
+    const finish = trailingStreak(input);
+    if (finish >= STRONG_FINISH_STREAK) {
+        awards.push({ id: "strong-finish", detail: `${finish} to close it out` });
+    }
+    if (input.fasterThanMaxPercent !== null &&
+        input.fasterThanMaxPercent > FASTER_THAN_MOST_PERCENT) {
+        awards.push({
+            id: "faster-than-most",
+            detail: `beat ${input.fasterThanMaxPercent}% of solvers`,
+        });
+    }
+    // Clutch: repeatedly landed answers in the final slice of the clock.
+    const clutch = clutchFinishes(input);
+    if (clutch >= CLUTCH_MIN) {
+        awards.push({ id: "clutch", detail: `${clutch} down to the wire` });
+    }
+    if (input.totalAnswered >= RATE_BADGE_MIN_ANSWERED &&
+        input.timeToAnswerAvgMs < QUICK_DRAW_AVG_MS) {
+        awards.push({
+            id: "quick-draw",
+            detail: `${(input.timeToAnswerAvgMs / 1000).toFixed(1)}s average`,
+        });
+    }
+    const share = decisiveShare(input);
+    if (share !== null &&
+        share >= DECISIVE_THRESHOLD &&
+        input.totalAnswered >= RATE_BADGE_MIN_ANSWERED) {
+        const pct = percent(share);
+        awards.push({ id: "decisive", detail: `${pct}% before halfway` });
+    }
+    // Sure-handed: committed every answer first-try, no second-guessing (STATS-7).
+    if (input.answerChanges === 0 &&
+        input.totalAnswered >= SURE_HANDED_MIN_ANSWERED) {
+        awards.push({ id: "sure-handed", detail: "no answer ever changed" });
+    }
+    if (input.totalAnswered >= UNBROKEN_FOCUS_MIN_ANSWERED &&
+        input.tabAwayCount === 0) {
+        awards.push({ id: "unbroken-focus", detail: "never left the trial" });
+    }
+    // Mode tags (ADR 0018): only badges awardable in this mode survive. Applied
+    // before the meta-badge so master-of-none never counts a filtered honour.
+    const eligible = awards.filter((a) => BADGES[a.id].modes.includes(context.kind));
+    // Master of none (meta): broad play that still racked up honours — jack of
+    // all trades. Counts the badges earned *above*, so it never counts itself.
+    const distinctCategories = new Set(input.results.map((r) => r.categoryId))
+        .size;
+    if (distinctCategories > MASTER_OF_NONE_MIN_CATEGORIES &&
+        eligible.length > MASTER_OF_NONE_MIN_BADGES) {
+        eligible.push({
+            id: "master-of-none",
+            detail: `${distinctCategories} categories spanned`,
+        });
+    }
+    // Devotee: a consistency honour for returning on consecutive days (STATS-9).
+    // Cross-run, so it's gated on the player's day streak (signed-in only) rather
+    // than this run's play. Added after the meta so it never counts toward it.
+    if (context.kind === "solo" &&
+        input.consecutiveDays !== undefined &&
+        input.consecutiveDays >= DEVOTEE_DAYS) {
+        eligible.push({
+            id: "devotee",
+            detail: `${input.consecutiveDays} days running`,
+        });
+    }
+    const rank = new Map(BADGE_ORDER.map((id, i) => [id, i]));
+    return (eligible
+        // The mode tags are the authoritative gate (ADR 0018): a final pass so
+        // badges appended after the meta-count filter can never bypass them.
+        .filter((a) => BADGES[a.id].modes.includes(context.kind))
+        .sort((a, b) => (rank.get(a.id) ?? 0) - (rank.get(b.id) ?? 0)));
+}
+export const RARITY_ORDER = ["common", "rare", "legendary", "exotic"];
+export const RARITY_LABELS = {
+    common: "Common",
+    rare: "Rare",
+    legendary: "Legendary",
+    exotic: "Exotic",
+};
+/**
+ * Canonical tier colours, shared by every surface that renders the rarity
+ * scale (badge chips, legends) so the key always matches the badges it
+ * explains.
+ */
+export const RARITY_CHIP_CLASSES = {
+    common: "border-zinc-500/40 bg-zinc-500/10 text-zinc-200",
+    rare: "border-blue-500/40 bg-blue-500/10 text-blue-200",
+    legendary: "border-violet-500/50 bg-violet-500/10 text-violet-200",
+    exotic: "border-gold bg-gold/20 text-gold-lighter shadow-[0_0_12px_-2px] shadow-gold/40",
+};
+const RARITY_RULES = {
+    victor: { base: 1, heroes: true, difficulty: true },
+    podium: { base: 0, heroes: true, difficulty: true },
+    flawless: { base: 1, questions: true, timer: "shorter", difficulty: true },
+    sharpshooter: {
+        base: 1,
+        questions: true,
+        timer: "shorter",
+        difficulty: true,
+    },
+    unstoppable: { base: 2, timer: "shorter", difficulty: true },
+    "on-a-roll": { base: 0, timer: "shorter", difficulty: true },
+    survivor: { base: 1, questions: true, difficulty: true },
+    "giant-slayer": {
+        base: 1,
+        questions: true,
+        timer: "shorter",
+        difficulty: true,
+    },
+    pantheon: { base: 2, questions: true, difficulty: true },
+    specialist: { base: 1, questions: true, difficulty: true },
+    polymath: { base: 2, questions: true, timer: "shorter" },
+    "strong-finish": {
+        base: 1,
+        questions: true,
+        timer: "shorter",
+        difficulty: true,
+    },
+    "sure-handed": { base: 1, questions: true, difficulty: true },
+    devotee: { base: 1 },
+    phoenix: { base: 1, difficulty: true },
+    "master-of-none": { base: 2, difficulty: true },
+    clutch: { base: 1, questions: true, difficulty: true },
+    "faster-than-most": { base: 1, timer: "shorter", difficulty: true },
+    "quick-draw": { base: 1, questions: true, timer: "longer", difficulty: true },
+    decisive: { base: 0, questions: true, timer: "shorter", difficulty: true },
+    "unbroken-focus": { base: 0, questions: true, difficulty: true },
+};
+/** More questions than the default 10 → harder to sustain (0–2). */
+function questionLevel(count) {
+    if (count > 20)
+        return 2;
+    if (count > 10)
+        return 1;
+    return 0;
+}
+/** Shorter than the 30s baseline → harder (0–2). */
+function shortTimerLevel(sec) {
+    if (sec <= 15)
+        return 2;
+    if (sec < 30)
+        return 1;
+    return 0;
+}
+/**
+ * Longer than baseline → a fast average is more impressive, but it's a soft
+ * signal (a generous clock is a common casual setting), so it's capped at +1.
+ * Reaching Exotic on Quick draw therefore needs a long clock *and* a harder run.
+ */
+function longTimerLevel(sec) {
+    return sec > 40 ? 1 : 0;
+}
+/** Harder difficulty settings raise rarity ("all" is the neutral default). */
+function difficultyLevel(difficulty) {
+    if (difficulty === "hard")
+        return 2;
+    if (difficulty === "medium")
+        return 1;
+    return 0;
+}
+/** A bigger field is harder to top: 8+ heroes bumps once, 12+ twice. */
+function heroLevel(count) {
+    if (count === undefined)
+        return 0;
+    if (count >= 12)
+        return 2;
+    if (count >= 8)
+        return 1;
+    return 0;
+}
+/** The rarity tier a badge reaches when earned under the given run conditions. */
+export function computeBadgeRarity(id, run) {
+    const rule = RARITY_RULES[id];
+    let bump = 0;
+    if (rule.questions)
+        bump += questionLevel(run.questionCount);
+    if (rule.timer === "shorter")
+        bump += shortTimerLevel(run.timerSec);
+    if (rule.timer === "longer")
+        bump += longTimerLevel(run.timerSec);
+    if (rule.difficulty)
+        bump += difficultyLevel(run.difficulty);
+    if (rule.heroes)
+        bump += heroLevel(run.heroCount);
+    bump = Math.min(bump, 2);
+    const tier = Math.min(rule.base + bump, RARITY_ORDER.length - 1);
+    return RARITY_ORDER[tier];
+}
+/** Parse a stored badge-id JSON array; malformed/missing/unknown ids read as none. */
+export function parseBadgeIds(json) {
+    try {
+        const parsed = JSON.parse(json ?? "[]");
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((id) => typeof id === "string" && id in BADGES);
+    }
+    catch {
+        return [];
+    }
+}
+/** The higher of two rarity tiers. */
+function betterRarity(a, b) {
+    return RARITY_ORDER.indexOf(a) > RARITY_ORDER.indexOf(b) ? a : b;
+}
+/** Fold one earned badge into a tally (count + best rarity). Mutates `tally`. */
+export function addToBadgeTally(tally, id, rarity) {
+    const existing = tally[id];
+    if (!existing) {
+        tally[id] = { count: 1, bestRarity: rarity };
+        return;
+    }
+    existing.count++;
+    existing.bestRarity = betterRarity(rarity, existing.bestRarity);
+}
+/** Merge tallies from different sources (e.g. solo + multiplayer) into one. */
+export function mergeBadgeTallies(...tallies) {
+    const merged = {};
+    for (const tally of tallies) {
+        for (const [id, entry] of Object.entries(tally)) {
+            const existing = merged[id];
+            if (!existing) {
+                merged[id] = { ...entry };
+                continue;
+            }
+            existing.count += entry.count;
+            existing.bestRarity = betterRarity(entry.bestRarity, existing.bestRarity);
+        }
+    }
+    return merged;
+}

package/dist/constants/auth.constants.d.ts

@@ -0,0 +1,26 @@
+import type { AuthUser, UserPower, UserRole } from "../types/auth.ts";
+/**
+ * What a Power is, not merely that it exists.
+ *
+ * - `gate` — stands between a request and a surface or its data. Granting one
+ *   widens what the holder may do.
+ * - `display` — read only by the UI to decide what to render. Granting one
+ *   widens nothing; revoking it refuses nobody.
+ */
+export type PowerShape = "gate" | "display";
+/**
+ * The runtime list of `UserPower`, which is what `/admin/users` offers and what
+ * the request schema accepts. Derived from `POWERS`, so it cannot drift from
+ * the union. See `UserPower` for what each one reaches.
+ */
+export declare const ALL_POWERS: UserPower[];
+export declare const powerShape: (power: UserPower) => PowerShape;
+/** One line for `/admin/users` to print under the toggle. */
+export declare const powerDescription: (power: UserPower) => string;
+/**
+ * Rank per role, for `hasRole`. `anonymous` and `display` share rank 0 —
+ * neither is an account, so every "is this signed in" gate compares against
+ * `member` rather than naming a role.
+ */
+export declare const ROLE_HIERARCHY: Record<UserRole, number>;
+export declare const ANON_USER: AuthUser;