diff --git a/shared/lib/rarity.test.ts b/shared/lib/rarity.test.ts
index b0c46be..a4173d8 100644
--- a/shared/lib/rarity.test.ts
+++ b/shared/lib/rarity.test.ts
@@ -18,6 +18,11 @@ describe("getRarityConfig", () => {
     const result = getRarityConfig("LEGENDARY");
     expect(result).toEqual(RARITY_CONFIG["C"]);
   });
+
+  it("falls back to Common for null/undefined input", () => {
+    expect(getRarityConfig(null as any)).toEqual(RARITY_CONFIG["C"]);
+    expect(getRarityConfig(undefined as any)).toEqual(RARITY_CONFIG["C"]);
+  });
 });
 
 describe("defaultName", () => {
diff --git a/shared/lib/rarity.ts b/shared/lib/rarity.ts
index 0a5181f..41375dd 100644
--- a/shared/lib/rarity.ts
+++ b/shared/lib/rarity.ts
@@ -1,3 +1,8 @@
+/**
+ * Shared Rarity Configuration
+ * Provides the canonical rarity display config (colors, emoji, labels)
+ * used by lootbox pull results and shop loot table views.
+ */
 export const RARITY_CONFIG: Record<string, { color: number; emoji: string; label: string }> = {
   C:        { color: 0x95A5A6, emoji: "📦", label: "Common" },
   R:        { color: 0x3498DB, emoji: "📦", label: "Rare" },