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/components/action-bar.tsx

@@ -1,18 +1,15 @@
-import type { Creature } from "@initiative/domain";
 import { Search } from "lucide-react";
 import { type FormEvent, useState } from "react";
+import type { SearchResult } from "../hooks/use-bestiary.js";
 import { BestiarySearch } from "./bestiary-search.js";
 import { Button } from "./ui/button.js";
 import { Input } from "./ui/input.js";
 
 interface ActionBarProps {
 	onAddCombatant: (name: string) => void;
-	onAddFromBestiary: (creature: Creature) => void;
-	bestiarySearch: (query: string) => Creature[];
+	onAddFromBestiary: (result: SearchResult) => void;
+	bestiarySearch: (query: string) => SearchResult[];
 	bestiaryLoaded: boolean;
-	suggestions: Creature[];
-	onSearchChange: (query: string) => void;
-	onShowStatBlock?: (creature: Creature) => void;
 }
 
 export function ActionBar({
@@ -20,12 +17,10 @@ export function ActionBar({
 	onAddFromBestiary,
 	bestiarySearch,
 	bestiaryLoaded,
-	suggestions,
-	onSearchChange,
-	onShowStatBlock,
 }: ActionBarProps) {
 	const [nameInput, setNameInput] = useState("");
 	const [searchOpen, setSearchOpen] = useState(false);
+	const [suggestions, setSuggestions] = useState<SearchResult[]>([]);
 	const [suggestionIndex, setSuggestionIndex] = useState(-1);
 
 	const handleAdd = (e: FormEvent) => {
@@ -33,28 +28,30 @@ export function ActionBar({
 		if (nameInput.trim() === "") return;
 		onAddCombatant(nameInput);
 		setNameInput("");
-		onSearchChange("");
+		setSuggestions([]);
 	};
 
 	const handleNameChange = (value: string) => {
 		setNameInput(value);
 		setSuggestionIndex(-1);
-		onSearchChange(value);
+		if (value.length >= 2) {
+			setSuggestions(bestiarySearch(value));
+		} else {
+			setSuggestions([]);
+		}
 	};
 
-	const handleSelectCreature = (creature: Creature) => {
-		onAddFromBestiary(creature);
+	const handleSelectCreature = (result: SearchResult) => {
+		onAddFromBestiary(result);
 		setSearchOpen(false);
 		setNameInput("");
-		onSearchChange("");
-		onShowStatBlock?.(creature);
+		setSuggestions([]);
 	};
 
-	const handleSelectSuggestion = (creature: Creature) => {
-		onAddFromBestiary(creature);
+	const handleSelectSuggestion = (result: SearchResult) => {
+		onAddFromBestiary(result);
 		setNameInput("");
-		onSearchChange("");
-		onShowStatBlock?.(creature);
+		setSuggestions([]);
 	};
 
 	const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -71,7 +68,7 @@ export function ActionBar({
 			handleSelectSuggestion(suggestions[suggestionIndex]);
 		} else if (e.key === "Escape") {
 			setSuggestionIndex(-1);
-			onSearchChange("");
+			setSuggestions([]);
 		}
 	};
 
@@ -100,8 +97,8 @@ export function ActionBar({
 						{suggestions.length > 0 && (
 							<div className="absolute bottom-full z-50 mb-1 w-full max-w-xs rounded-md border border-border bg-card shadow-lg">
 								<ul className="max-h-48 overflow-y-auto py-1">
-									{suggestions.map((creature, i) => (
-										<li key={creature.id}>
+									{suggestions.map((result, i) => (
+										<li key={`${result.source}:${result.name}`}>
 											<button
 												type="button"
 												className={`flex w-full items-center justify-between px-3 py-1.5 text-left text-sm ${
@@ -109,12 +106,12 @@ export function ActionBar({
 														? "bg-accent/20 text-foreground"
 														: "text-foreground hover:bg-hover-neutral-bg"
 												}`}
-												onClick={() => handleSelectSuggestion(creature)}
+												onClick={() => handleSelectSuggestion(result)}
 												onMouseEnter={() => setSuggestionIndex(i)}
 											>
-												<span>{creature.name}</span>
+												<span>{result.name}</span>
 												<span className="text-xs text-muted-foreground">
-													{creature.sourceDisplayName}
+													{result.sourceDisplayName}
 												</span>
 											</button>
 										</li>

apps/web/src/components/bestiary-search.tsx

@@ -1,4 +1,3 @@
-import type { Creature } from "@initiative/domain";
 import { Search, X } from "lucide-react";
 import {
 	type KeyboardEvent,
@@ -7,12 +6,13 @@ import {
 	useRef,
 	useState,
 } from "react";
+import type { SearchResult } from "../hooks/use-bestiary.js";
 import { Input } from "./ui/input.js";
 
 interface BestiarySearchProps {
-	onSelectCreature: (creature: Creature) => void;
+	onSelectCreature: (result: SearchResult) => void;
 	onClose: () => void;
-	searchFn: (query: string) => Creature[];
+	searchFn: (query: string) => SearchResult[];
 }
 
 export function BestiarySearch({
@@ -101,8 +101,8 @@ export function BestiarySearch({
 						</div>
 					) : (
 						<ul className="max-h-60 overflow-y-auto py-1">
-							{results.map((creature, i) => (
-								<li key={creature.id}>
+							{results.map((result, i) => (
+								<li key={`${result.source}:${result.name}`}>
 									<button
 										type="button"
 										className={`flex w-full items-center justify-between px-3 py-1.5 text-left text-sm ${
@@ -110,12 +110,12 @@ export function BestiarySearch({
 												? "bg-accent/20 text-foreground"
 												: "text-foreground hover:bg-hover-neutral-bg"
 										}`}
-										onClick={() => onSelectCreature(creature)}
+										onClick={() => onSelectCreature(result)}
 										onMouseEnter={() => setHighlightIndex(i)}
 									>
-										<span>{creature.name}</span>
+										<span>{result.name}</span>
 										<span className="text-xs text-muted-foreground">
-											{creature.sourceDisplayName}
+											{result.sourceDisplayName}
 										</span>
 									</button>
 								</li>

apps/web/src/components/source-fetch-prompt.tsx

@@ -0,0 +1,131 @@
+import { Download, Loader2, Upload } from "lucide-react";
+import { useRef, useState } from "react";
+import { getDefaultFetchUrl } from "../adapters/bestiary-index-adapter.js";
+import { Button } from "./ui/button.js";
+import { Input } from "./ui/input.js";
+
+interface SourceFetchPromptProps {
+	sourceCode: string;
+	sourceDisplayName: string;
+	fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>;
+	onSourceLoaded: () => void;
+	onUploadSource: (sourceCode: string, jsonData: unknown) => Promise<void>;
+}
+
+export function SourceFetchPrompt({
+	sourceCode,
+	sourceDisplayName,
+	fetchAndCacheSource,
+	onSourceLoaded,
+	onUploadSource,
+}: SourceFetchPromptProps) {
+	const [url, setUrl] = useState(() => getDefaultFetchUrl(sourceCode));
+	const [status, setStatus] = useState<"idle" | "fetching" | "error">("idle");
+	const [error, setError] = useState<string>("");
+	const fileInputRef = useRef<HTMLInputElement>(null);
+
+	const handleFetch = async () => {
+		setStatus("fetching");
+		setError("");
+		try {
+			await fetchAndCacheSource(sourceCode, url);
+			onSourceLoaded();
+		} catch (e) {
+			setStatus("error");
+			setError(e instanceof Error ? e.message : "Failed to fetch source data");
+		}
+	};
+
+	const handleFileUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+		const file = e.target.files?.[0];
+		if (!file) return;
+
+		setStatus("fetching");
+		setError("");
+
+		try {
+			const text = await file.text();
+			const json = JSON.parse(text);
+			await onUploadSource(sourceCode, json);
+			onSourceLoaded();
+		} catch (err) {
+			setStatus("error");
+			setError(
+				err instanceof Error ? err.message : "Failed to process uploaded file",
+			);
+		}
+
+		// Reset file input
+		if (fileInputRef.current) {
+			fileInputRef.current.value = "";
+		}
+	};
+
+	return (
+		<div className="flex flex-col gap-4">
+			<div>
+				<h3 className="text-sm font-semibold text-foreground">
+					Load {sourceDisplayName}
+				</h3>
+				<p className="mt-1 text-xs text-muted-foreground">
+					Stat block data for this source needs to be loaded. Enter a URL or
+					upload a JSON file.
+				</p>
+			</div>
+
+			<div className="flex flex-col gap-2">
+				<label htmlFor="source-url" className="text-xs text-muted-foreground">
+					Source URL
+				</label>
+				<Input
+					id="source-url"
+					type="url"
+					value={url}
+					onChange={(e) => setUrl(e.target.value)}
+					disabled={status === "fetching"}
+					className="text-xs"
+				/>
+			</div>
+
+			<div className="flex items-center gap-2">
+				<Button
+					size="sm"
+					onClick={handleFetch}
+					disabled={status === "fetching" || !url}
+				>
+					{status === "fetching" ? (
+						<Loader2 className="mr-1 h-3 w-3 animate-spin" />
+					) : (
+						<Download className="mr-1 h-3 w-3" />
+					)}
+					{status === "fetching" ? "Loading..." : "Load"}
+				</Button>
+
+				<span className="text-xs text-muted-foreground">or</span>
+
+				<Button
+					size="sm"
+					variant="outline"
+					onClick={() => fileInputRef.current?.click()}
+					disabled={status === "fetching"}
+				>
+					<Upload className="mr-1 h-3 w-3" />
+					Upload file
+				</Button>
+				<input
+					ref={fileInputRef}
+					type="file"
+					accept=".json"
+					className="hidden"
+					onChange={handleFileUpload}
+				/>
+			</div>
+
+			{status === "error" && (
+				<div className="rounded-md border border-destructive/50 bg-destructive/10 px-3 py-2 text-xs text-destructive">
+					{error}
+				</div>
+			)}
+		</div>
+	);
+}

apps/web/src/components/source-manager.tsx

@@ -0,0 +1,81 @@
+import { Database, Trash2 } from "lucide-react";
+import { useCallback, useEffect, useState } from "react";
+import type { CachedSourceInfo } from "../adapters/bestiary-cache.js";
+import * as bestiaryCache from "../adapters/bestiary-cache.js";
+import { Button } from "./ui/button.js";
+
+interface SourceManagerProps {
+	onCacheCleared: () => void;
+}
+
+export function SourceManager({ onCacheCleared }: SourceManagerProps) {
+	const [sources, setSources] = useState<CachedSourceInfo[]>([]);
+
+	const loadSources = useCallback(async () => {
+		const cached = await bestiaryCache.getCachedSources();
+		setSources(cached);
+	}, []);
+
+	useEffect(() => {
+		loadSources();
+	}, [loadSources]);
+
+	const handleClearSource = async (sourceCode: string) => {
+		await bestiaryCache.clearSource(sourceCode);
+		await loadSources();
+		onCacheCleared();
+	};
+
+	const handleClearAll = async () => {
+		await bestiaryCache.clearAll();
+		await loadSources();
+		onCacheCleared();
+	};
+
+	if (sources.length === 0) {
+		return (
+			<div className="flex flex-col items-center gap-2 py-8 text-center">
+				<Database className="h-8 w-8 text-muted-foreground" />
+				<p className="text-sm text-muted-foreground">No cached sources</p>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex flex-col gap-3">
+			<div className="flex items-center justify-between">
+				<span className="text-sm font-semibold text-foreground">
+					Cached Sources
+				</span>
+				<Button size="sm" variant="outline" onClick={handleClearAll}>
+					<Trash2 className="mr-1 h-3 w-3" />
+					Clear All
+				</Button>
+			</div>
+			<ul className="flex flex-col gap-1">
+				{sources.map((source) => (
+					<li
+						key={source.sourceCode}
+						className="flex items-center justify-between rounded-md border border-border px-3 py-2"
+					>
+						<div>
+							<span className="text-sm text-foreground">
+								{source.displayName}
+							</span>
+							<span className="ml-2 text-xs text-muted-foreground">
+								{source.creatureCount} creatures
+							</span>
+						</div>
+						<button
+							type="button"
+							onClick={() => handleClearSource(source.sourceCode)}
+							className="text-muted-foreground hover:text-hover-danger"
+						>
+							<Trash2 className="h-3.5 w-3.5" />
+						</button>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}

apps/web/src/components/stat-block-panel.tsx

@@ -1,17 +1,43 @@
-import type { Creature } from "@initiative/domain";
+import type { Creature, CreatureId } from "@initiative/domain";
 import { X } from "lucide-react";
 import { useEffect, useState } from "react";
+import { getSourceDisplayName } from "../adapters/bestiary-index-adapter.js";
+import { SourceFetchPrompt } from "./source-fetch-prompt.js";
 import { StatBlock } from "./stat-block.js";
 
 interface StatBlockPanelProps {
+	creatureId: CreatureId | null;
 	creature: Creature | null;
+	isSourceCached: (sourceCode: string) => Promise<boolean>;
+	fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>;
+	uploadAndCacheSource: (
+		sourceCode: string,
+		jsonData: unknown,
+	) => Promise<void>;
+	refreshCache: () => Promise<void>;
 	onClose: () => void;
 }
 
-export function StatBlockPanel({ creature, onClose }: StatBlockPanelProps) {
+function extractSourceCode(cId: CreatureId): string {
+	const colonIndex = cId.indexOf(":");
+	if (colonIndex === -1) return "";
+	return cId.slice(0, colonIndex).toUpperCase();
+}
+
+export function StatBlockPanel({
+	creatureId,
+	creature,
+	isSourceCached,
+	fetchAndCacheSource,
+	uploadAndCacheSource,
+	refreshCache,
+	onClose,
+}: StatBlockPanelProps) {
 	const [isDesktop, setIsDesktop] = useState(
 		() => window.matchMedia("(min-width: 1024px)").matches,
 	);
+	const [needsFetch, setNeedsFetch] = useState(false);
+	const [checkingCache, setCheckingCache] = useState(false);
 
 	useEffect(() => {
 		const mq = window.matchMedia("(min-width: 1024px)");
@@ -20,7 +46,66 @@ export function StatBlockPanel({ creature, onClose }: StatBlockPanelProps) {
 		return () => mq.removeEventListener("change", handler);
 	}, []);
 
-	if (!creature) return null;
+	// When creatureId changes, check if we need to show the fetch prompt
+	useEffect(() => {
+		if (!creatureId || creature) {
+			setNeedsFetch(false);
+			return;
+		}
+
+		const sourceCode = extractSourceCode(creatureId);
+		if (!sourceCode) {
+			setNeedsFetch(false);
+			return;
+		}
+
+		setCheckingCache(true);
+		isSourceCached(sourceCode).then((cached) => {
+			// If source is cached but creature not found, it's an edge case
+			// If source is not cached, show fetch prompt
+			setNeedsFetch(!cached);
+			setCheckingCache(false);
+		});
+	}, [creatureId, creature, isSourceCached]);
+
+	if (!creatureId) return null;
+
+	const sourceCode = extractSourceCode(creatureId);
+
+	const handleSourceLoaded = async () => {
+		await refreshCache();
+		setNeedsFetch(false);
+	};
+
+	const renderContent = () => {
+		if (checkingCache) {
+			return (
+				<div className="p-4 text-sm text-muted-foreground">Loading...</div>
+			);
+		}
+
+		if (creature) {
+			return <StatBlock creature={creature} />;
+		}
+
+		if (needsFetch && sourceCode) {
+			return (
+				<SourceFetchPrompt
+					sourceCode={sourceCode}
+					sourceDisplayName={getSourceDisplayName(sourceCode)}
+					fetchAndCacheSource={fetchAndCacheSource}
+					onSourceLoaded={handleSourceLoaded}
+					onUploadSource={uploadAndCacheSource}
+				/>
+			);
+		}
+
+		return (
+			<div className="p-4 text-sm text-muted-foreground">
+				No stat block available
+			</div>
+		);
+	};
 
 	if (isDesktop) {
 		return (
@@ -37,9 +122,7 @@ export function StatBlockPanel({ creature, onClose }: StatBlockPanelProps) {
 						<X className="h-4 w-4" />
 					</button>
 				</div>
-				<div className="flex-1 overflow-y-auto p-4">
-					<StatBlock creature={creature} />
-				</div>
+				<div className="flex-1 overflow-y-auto p-4">{renderContent()}</div>
 			</div>
 		);
 	}
@@ -69,7 +152,7 @@ export function StatBlockPanel({ creature, onClose }: StatBlockPanelProps) {
 					</button>
 				</div>
 				<div className="h-[calc(100%-41px)] overflow-y-auto p-4">
-					<StatBlock creature={creature} />
+					{renderContent()}
 				</div>
 			</div>
 		</div>

apps/web/src/components/turn-navigation.tsx

@@ -1,5 +1,5 @@
 import type { Encounter } from "@initiative/domain";
-import { StepBack, StepForward, Trash2 } from "lucide-react";
+import { Settings, StepBack, StepForward, Trash2 } from "lucide-react";
 import { D20Icon } from "./d20-icon";
 import { Button } from "./ui/button";
 
@@ -9,6 +9,7 @@ interface TurnNavigationProps {
 	onRetreatTurn: () => void;
 	onClearEncounter: () => void;
 	onRollAllInitiative: () => void;
+	onOpenSourceManager: () => void;
 }
 
 export function TurnNavigation({
@@ -17,6 +18,7 @@ export function TurnNavigation({
 	onRetreatTurn,
 	onClearEncounter,
 	onRollAllInitiative,
+	onOpenSourceManager,
 }: TurnNavigationProps) {
 	const hasCombatants = encounter.combatants.length > 0;
 	const isAtStart = encounter.roundNumber === 1 && encounter.activeIndex === 0;
@@ -62,6 +64,16 @@ export function TurnNavigation({
 					>
 						<D20Icon className="h-6 w-6" />
 					</Button>
+					<Button
+						variant="ghost"
+						size="icon"
+						className="h-8 w-8 text-muted-foreground hover:text-hover-neutral"
+						onClick={onOpenSourceManager}
+						title="Manage cached sources"
+						aria-label="Manage cached sources"
+					>
+						<Settings className="h-5 w-5" />
+					</Button>
 					<Button
 						variant="ghost"
 						size="icon"