# Implementation Plan: Bulk Import All Sources

**Branch**: `030-bulk-import-sources` | **Date**: 2026-03-10 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/030-bulk-import-sources/spec.md`

## Summary

Add a "Bulk Import All Sources" button to the top bar that opens the stat block side panel with a bulk import prompt. The user confirms a base URL, and the app fetches all bestiary source files concurrently, normalizes each, and caches them in IndexedDB. Progress is shown via a counter and progress bar in the side panel; if the panel is closed mid-import, a lightweight toast notification takes over progress display.

## Technical Context

**Language/Version**: TypeScript 5.8 (strict mode, verbatimModuleSyntax)
**Primary Dependencies**: React 19, Vite 6, Tailwind CSS v4, Lucide React (icons), idb (IndexedDB wrapper)
**Storage**: IndexedDB for cached source data (existing via `bestiary-cache.ts`); localStorage for encounter persistence (existing, unchanged)
**Testing**: Vitest
**Target Platform**: Browser (desktop + mobile)
**Project Type**: Web application (React SPA)
**Performance Goals**: Non-blocking async import; UI remains responsive during ~12.5 MB download
**Constraints**: All fetches fire concurrently (browser connection pooling); no third-party toast library
**Scale/Scope**: All sources from bestiary index (currently ~102–104), ~12.5 MB total data

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Principle | Status | Notes |
|-----------|--------|-------|
| I. Deterministic Domain Core | PASS | No domain changes. All fetch/cache logic is in the adapter layer. |
| II. Layered Architecture | PASS | Bulk import logic lives entirely in the adapter/UI layer (hooks + components). No domain or application layer changes needed. |
| III. Agent Boundary | N/A | No agent layer involvement. |
| IV. Clarification-First | PASS | Feature description was comprehensive; no ambiguities remain. |
| V. Escalation Gates | PASS | All functionality is within spec scope. |
| VI. MVP Baseline Language | PASS | No permanent bans introduced. |
| VII. No Gameplay Rules | PASS | No gameplay mechanics involved. |

## Project Structure

### Documentation (this feature)

```text
specs/030-bulk-import-sources/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
└── tasks.md             # Phase 2 output (/speckit.tasks)
```

### Source Code (repository root)

```text
apps/web/src/
├── adapters/
│   ├── bestiary-cache.ts          # Existing — add isSourceCached batch check
│   └── bestiary-index-adapter.ts  # Existing — add getAllSourceCodes()
├── components/
│   ├── action-bar.tsx             # Existing — add Import button
│   ├── stat-block-panel.tsx       # Existing — add bulk import mode
│   ├── bulk-import-prompt.tsx     # NEW — bulk import UI (description + URL + progress)
│   └── toast.tsx                  # NEW — lightweight toast notification component
├── hooks/
│   ├── use-bestiary.ts            # Existing — add bulkImport method
│   └── use-bulk-import.ts         # NEW — bulk import state management hook
└── App.tsx                        # Existing — wire toast + bulk import panel mode
```

**Structure Decision**: Follows existing patterns. New components for bulk import prompt and toast. New hook for import state management. Minimal changes to existing files (button + wiring).