Implement the 029-on-demand-bestiary feature that replaces the bundled XMM bestiary JSON with a compact search index (~350KB) and on-demand source loading, where users explicitly provide a URL or upload a JSON file to fetch full stat block data per source, which is then normalized and cached in IndexedDB (with in-memory fallback) so creature stat blocks load instantly on subsequent visits while keeping the app bundle small and never auto-fetching copyrighted content

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

apps/web/src/adapters/__tests__/bestiary-adapter.test.ts

@@ -1,5 +1,12 @@
-import { describe, expect, it } from "vitest";
-import { normalizeBestiary } from "../bestiary-adapter.js";
+import { beforeAll, describe, expect, it } from "vitest";
+import {
+	normalizeBestiary,
+	setSourceDisplayNames,
+} from "../bestiary-adapter.js";
+
+beforeAll(() => {
+	setSourceDisplayNames({ XMM: "MM 2024" });
+});
 
 describe("normalizeBestiary", () => {
 	it("normalizes a simple creature", () => {

apps/web/src/adapters/__tests__/bestiary-full.test.ts

@@ -1,16 +0,0 @@
-import { expect, it } from "vitest";
-import rawData from "../../../../../data/bestiary/xmm.json";
-import { normalizeBestiary } from "../bestiary-adapter.js";
-
-it("normalizes all 503 monsters without error", () => {
-	const creatures = normalizeBestiary(
-		rawData as unknown as Parameters<typeof normalizeBestiary>[0],
-	);
-	expect(creatures.length).toBe(503);
-	for (const c of creatures) {
-		expect(c.name).toBeTruthy();
-		expect(c.id).toBeTruthy();
-		expect(c.ac).toBeGreaterThanOrEqual(0);
-		expect(c.hp.average).toBeGreaterThan(0);
-	}
-});

apps/web/src/adapters/bestiary-adapter.ts

@@ -81,9 +81,11 @@ interface RawSpellcasting {
 
 // --- Source mapping ---
 
-const SOURCE_DISPLAY_NAMES: Record<string, string> = {
-	XMM: "MM 2024",
-};
+let sourceDisplayNames: Record<string, string> = {};
+
+export function setSourceDisplayNames(names: Record<string, string>): void {
+	sourceDisplayNames = names;
+}
 
 // --- Size mapping ---
 
@@ -353,7 +355,13 @@ function makeCreatureId(source: string, name: string): CreatureId {
  * Normalizes raw 5etools bestiary JSON into domain Creature[].
  */
 export function normalizeBestiary(raw: { monster: RawMonster[] }): Creature[] {
-	return raw.monster.map((m) => {
+	// Filter out _copy entries — these reference another source's monster
+	// and lack their own stats (ac, hp, cr, etc.)
+	const monsters = raw.monster.filter(
+		// biome-ignore lint/suspicious/noExplicitAny: raw JSON may have _copy field
+		(m) => !(m as any)._copy,
+	);
+	return monsters.map((m) => {
 		const crStr = extractCr(m.cr);
 		const ac = extractAc(m.ac);
 
@@ -361,7 +369,7 @@ export function normalizeBestiary(raw: { monster: RawMonster[] }): Creature[] {
 			id: makeCreatureId(m.source, m.name),
 			name: m.name,
 			source: m.source,
-			sourceDisplayName: SOURCE_DISPLAY_NAMES[m.source] ?? m.source,
+			sourceDisplayName: sourceDisplayNames[m.source] ?? m.source,
 			size: formatSize(m.size),
 			type: formatType(m.type),
 			alignment: formatAlignment(m.alignment),

apps/web/src/adapters/bestiary-cache.ts

@@ -0,0 +1,139 @@
+import type { Creature, CreatureId } from "@initiative/domain";
+import { type IDBPDatabase, openDB } from "idb";
+
+const DB_NAME = "initiative-bestiary";
+const STORE_NAME = "sources";
+const DB_VERSION = 1;
+
+export interface CachedSourceInfo {
+	readonly sourceCode: string;
+	readonly displayName: string;
+	readonly creatureCount: number;
+	readonly cachedAt: number;
+}
+
+interface CachedSourceRecord {
+	sourceCode: string;
+	displayName: string;
+	creatures: Creature[];
+	cachedAt: number;
+	creatureCount: number;
+}
+
+let db: IDBPDatabase | null = null;
+let dbFailed = false;
+
+// In-memory fallback when IndexedDB is unavailable
+const memoryStore = new Map<string, CachedSourceRecord>();
+
+async function getDb(): Promise<IDBPDatabase | null> {
+	if (db) return db;
+	if (dbFailed) return null;
+
+	try {
+		db = await openDB(DB_NAME, DB_VERSION, {
+			upgrade(database) {
+				if (!database.objectStoreNames.contains(STORE_NAME)) {
+					database.createObjectStore(STORE_NAME, {
+						keyPath: "sourceCode",
+					});
+				}
+			},
+		});
+		return db;
+	} catch {
+		dbFailed = true;
+		console.warn(
+			"IndexedDB unavailable — bestiary cache will not persist across sessions.",
+		);
+		return null;
+	}
+}
+
+export async function cacheSource(
+	sourceCode: string,
+	displayName: string,
+	creatures: Creature[],
+): Promise<void> {
+	const record: CachedSourceRecord = {
+		sourceCode,
+		displayName,
+		creatures,
+		cachedAt: Date.now(),
+		creatureCount: creatures.length,
+	};
+
+	const database = await getDb();
+	if (database) {
+		await database.put(STORE_NAME, record);
+	} else {
+		memoryStore.set(sourceCode, record);
+	}
+}
+
+export async function isSourceCached(sourceCode: string): Promise<boolean> {
+	const database = await getDb();
+	if (database) {
+		const record = await database.get(STORE_NAME, sourceCode);
+		return record !== undefined;
+	}
+	return memoryStore.has(sourceCode);
+}
+
+export async function getCachedSources(): Promise<CachedSourceInfo[]> {
+	const database = await getDb();
+	if (database) {
+		const all: CachedSourceRecord[] = await database.getAll(STORE_NAME);
+		return all.map((r) => ({
+			sourceCode: r.sourceCode,
+			displayName: r.displayName,
+			creatureCount: r.creatureCount,
+			cachedAt: r.cachedAt,
+		}));
+	}
+	return [...memoryStore.values()].map((r) => ({
+		sourceCode: r.sourceCode,
+		displayName: r.displayName,
+		creatureCount: r.creatureCount,
+		cachedAt: r.cachedAt,
+	}));
+}
+
+export async function clearSource(sourceCode: string): Promise<void> {
+	const database = await getDb();
+	if (database) {
+		await database.delete(STORE_NAME, sourceCode);
+	} else {
+		memoryStore.delete(sourceCode);
+	}
+}
+
+export async function clearAll(): Promise<void> {
+	const database = await getDb();
+	if (database) {
+		await database.clear(STORE_NAME);
+	} else {
+		memoryStore.clear();
+	}
+}
+
+export async function loadAllCachedCreatures(): Promise<
+	Map<CreatureId, Creature>
+> {
+	const map = new Map<CreatureId, Creature>();
+	const database = await getDb();
+
+	let records: CachedSourceRecord[];
+	if (database) {
+		records = await database.getAll(STORE_NAME);
+	} else {
+		records = [...memoryStore.values()];
+	}
+
+	for (const record of records) {
+		for (const creature of record.creatures) {
+			map.set(creature.id, creature);
+		}
+	}
+	return map;
+}

apps/web/src/adapters/bestiary-index-adapter.ts

@@ -0,0 +1,56 @@
+import type { BestiaryIndex, BestiaryIndexEntry } from "@initiative/domain";
+
+import rawIndex from "../../../../data/bestiary/index.json";
+
+interface CompactCreature {
+	readonly n: string;
+	readonly s: string;
+	readonly ac: number;
+	readonly hp: number;
+	readonly dx: number;
+	readonly cr: string;
+	readonly ip: number;
+	readonly sz: string;
+	readonly tp: string;
+}
+
+interface CompactIndex {
+	readonly sources: Record<string, string>;
+	readonly creatures: readonly CompactCreature[];
+}
+
+function mapCreature(c: CompactCreature): BestiaryIndexEntry {
+	return {
+		name: c.n,
+		source: c.s,
+		ac: c.ac,
+		hp: c.hp,
+		dex: c.dx,
+		cr: c.cr,
+		initiativeProficiency: c.ip,
+		size: c.sz,
+		type: c.tp,
+	};
+}
+
+let cachedIndex: BestiaryIndex | undefined;
+
+export function loadBestiaryIndex(): BestiaryIndex {
+	if (cachedIndex) return cachedIndex;
+
+	const compact = rawIndex as unknown as CompactIndex;
+	cachedIndex = {
+		sources: compact.sources,
+		creatures: compact.creatures.map(mapCreature),
+	};
+	return cachedIndex;
+}
+
+export function getDefaultFetchUrl(sourceCode: string): string {
+	return `https://raw.githubusercontent.com/5etools-mirror-3/5etools-src/main/data/bestiary/bestiary-${sourceCode.toLowerCase()}.json`;
+}
+
+export function getSourceDisplayName(sourceCode: string): string {
+	const index = loadBestiaryIndex();
+	return index.sources[sourceCode] ?? sourceCode;
+}