initiative/specs/030-bulk-import-sources/plan.md

Implementation Plan: Bulk Import All Sources

Branch: 030-bulk-import-sources | Date: 2026-03-10 | Spec: 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)

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)

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).