Zauberwald/.planning/phases/05-multi-wald-system-wald-pagination-und-navigation-zwischen-w-ldern/05-CONTEXT.md

Phase 5: Multi-Wald-System: Wald-Pagination und Navigation zwischen Wäldern - Context

Gathered: 2026-03-29 (assumptions mode) Status: Ready for planning

## Phase Boundary

Der Wald hat aktuell ein 4x3 Grid (12 Slots). Mit 16 Stufen und je einem Waldelement pro Einheit füllt sich ein einzelner Wald schnell. Diese Phase fügt Pagination hinzu: Mehrere "Waldseiten" mit Navigation dazwischen. Das Kind kann zwischen gefüllten Wäldern blättern und sieht neue Elemente immer auf der aktuellen Seite.

## Implementation Decisions

Pagination Data Model

• D-01: Wald-Seite wird aus dem Element-Index berechnet (Math.floor(index / 12)), kein neues Feld auf ForestElement, kein DB-Version-Bump. Elemente 1-12 = Wald 1, 13-24 = Wald 2, etc.
• D-02: getForestElements() gibt weiterhin alle Elemente zurück. Die Slicing-Logik liegt in renderForestScene.

Navigation UI

• D-03: Links/Rechts-Pfeiltasten neben der Waldszene + "Wald X von Y" Textanzeige. Keine Swipe-Gesten, keine Tab-Bar.
• D-04: Pfeiltasten sind kindgerecht gross (min 44px Touch-Target), Pastellfarben passend zum bestehenden Stil. Pfeil-Links deaktiviert auf Seite 1, Pfeil-Rechts deaktiviert auf letzter Seite.

Aktueller Wald in Progress

• D-05: Neues Feld currentForestPage: number im Progress-Singleton. Default 0. Wird bei Navigation aktualisiert und persistiert.
• D-06: Nach Lesson-Abschluss wird automatisch zur Seite navigiert, die das neue Element enthält (letzte Seite).

Rendering-Ansatz

• D-07: renderForestScene bekommt Page-Index-Parameter, slice-t Elements (page * 12 bis (page + 1) * 12). Bestehendes tear-down-and-rebuild Pattern bleibt erhalten.
• D-08: Object-URL-Management bleibt wie bisher — nur die aktuelle Seite hat aktive Object URLs.

Claude's Discretion

• Exakte Pfeil-Button-Positionierung (über, neben, unter dem Grid)
• Animation beim Seitenwechsel (Slide, Fade, oder sofort)
• "Wald X von Y" Typography und Platzierung
• Ob bei nur einem Wald die Navigation ausgeblendet wird

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Forest System

• src/forest/scene.ts — Aktuelles Forest-Rendering, 12-Slot-Limit, renderForestScene, initForestScreen, renderLevelMap
• src/forest/reward.ts — Reward-Flow der neue Elemente speichert, slotIndex = existing.length % 12
• src/types.ts — ForestElement Interface, Progress Interface (Singleton)
• src/storage/db.ts — getForestElements(), saveForestElement(), DB-Schema

UI & Styling

• src/styles/main.css — Forest-Grid-Styling (.forest__scene, .forest__element)
• index.html — Forest-Screen DOM-Struktur (screen-forest)
• src/ui/screens.ts — Screen-Management

App Flow

• src/app.ts — initForestScreen Aufruf nach Reward, Navigation zwischen Screens </canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• renderForestScene(db, newElementId?) — Kernfunktion, muss um Page-Parameter erweitert werden
• initForestScreen(db, onStartLesson) — Init-Punkt für Navigation-UI-Setup
• getForestElements(db) — Gibt alle Elemente zurück, bereits für Slicing geeignet
• Object-URL-Management in activeObjectUrls — Verhindert Memory Leaks

Established Patterns

• Tear-down-and-rebuild: grid.innerHTML = "" + Neuaufbau bei jedem Render
• Singleton Progress mit getProgress/saveProgress für Zustandspersistenz
• CSS-Klassen mit BEM-Notation (.forest__element, .forest__element--new)
• Button-Patterns: continueBtn in Forest, Level-Cards als Buttons

Integration Points

• renderForestScene wird von initForestScreen und nach Reward aufgerufen
• reward.ts berechnet slotIndex — muss Pagination berücksichtigen
• app.ts steuert den Flow zwischen Screens — Forest-Init muss korrekte Seite laden
• Progress wird bei jedem Forest-Init gelesen — neues Feld wird automatisch mitgeladen </code_context>

## Specific Ideas

No specific requirements — open to standard approaches

## Deferred Ideas

None — analysis stayed within phase scope

---

Phase: 05-multi-wald-system-wald-pagination-und-navigation-zwischen-w-ldern Context gathered: 2026-03-29 via assumptions mode