mirror of
https://github.com/Azgaar/Fantasy-Map-Generator.git
synced 2026-04-03 22:17:24 +02:00
f928f9d101
- Added compatibility lookups for legacy single-SVG callers to ensure existing workflows function during migration to new architecture. - Implemented `getLayerSvg`, `getLayerSurface`, and `queryMap` functions as stable globals. - Migrated relevant code in `draw-state-labels.ts` to utilize the new `queryMap` function for scene-aware lookups. - Updated `layers.js` to manage layer visibility and registration more effectively. - Introduced `LayersModule` to handle layer registration, visibility, and ordering. - Created `WebGLSurfaceLayer` and `SvgLayer` classes to encapsulate layer behavior. - Refactored `TextureAtlasLayer` to utilize the new layer management system. - Updated HTML structure to accommodate new SVG and canvas elements. - Ensured all TypeScript checks pass with zero errors on modified files.
128 lines
7.6 KiB
Markdown
128 lines
7.6 KiB
Markdown
# Story 1.4: Add Layer Surface Lifecycle Ownership
|
|
|
|
Status: done
|
|
|
|
<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
|
|
|
|
## Story
|
|
|
|
As a map maintainer,
|
|
I want a Layer abstraction to own each surface lifecycle,
|
|
so that individual layers can be created, mounted, updated, and disposed without leaking renderer-specific details.
|
|
|
|
## Acceptance Criteria
|
|
|
|
1. Given the runtime needs one surface per logical layer, when a layer is instantiated, then the Layer abstraction owns creation, mount, update, and teardown for that surface, and caller code interacts with the layer through a stable contract rather than direct DOM assumptions.
|
|
2. Given both SVG and WebGL layers will exist, when a surface is registered with the Layer abstraction, then surface lifecycle handling works without exposing renderer-specific branching to feature modules, and layer modules remain responsible only for drawing their own surface.
|
|
|
|
## Tasks / Subtasks
|
|
|
|
- [x] Introduce the Layer lifecycle contract.
|
|
- [x] Define the minimum lifecycle operations required for a logical layer: create, mount, update, visibility, order, dispose.
|
|
- [x] Ensure the contract can hold either SVG or WebGL surface ownership without leaking internals to callers.
|
|
- [x] Integrate the lifecycle contract with the Layers registry.
|
|
- [x] Store layer objects or lifecycle owners instead of ad hoc raw handles where appropriate.
|
|
- [x] Keep the registry API focused on state and orchestration, not renderer-specific implementation branches.
|
|
- [x] Adapt current surfaces to the new ownership model.
|
|
- [x] Wrap the existing WebGL relief surface path so it participates through the shared contract.
|
|
- [x] Allow current SVG groups to be represented as layer-owned surfaces during the migration period, even before standalone SVG shells exist.
|
|
- [x] Preserve module boundaries.
|
|
- [x] Keep feature renderers responsible for drawing content only.
|
|
- [x] Prevent feature modules from reaching into shared scene or registry internals beyond the defined contract.
|
|
- [x] Perform manual smoke verification.
|
|
- [x] Relief rendering still mounts and clears correctly.
|
|
- [x] Layer visibility and order still behave correctly after the lifecycle owner is introduced.
|
|
|
|
## Dev Notes
|
|
|
|
### Context Summary
|
|
|
|
- `src/modules/webgl-layer.ts` already owns one shared Three.js scene and keeps a `Map<string, RegisteredLayer>` of WebGL groups. Reuse that work. Do not create a second parallel WebGL ownership model.
|
|
- `src/renderers/draw-relief-icons.ts` currently delegates to `TextureAtlasLayer`, which triggers `WebGLLayer.rerender()` directly. That is a concrete example of a feature module that should eventually talk only to its own surface owner.
|
|
- Current SVG layers are still raw D3 groups under `viewbox`. During Epic 1 the lifecycle abstraction can wrap those existing groups first; standalone SVG shells belong to Epic 2.
|
|
|
|
### Technical Requirements
|
|
|
|
- Keep the abstraction narrow and named after the architecture: `Layer` or similarly direct terminology.
|
|
- Avoid generic factories or strategy trees. One lifecycle owner with SVG and WebGL-capable implementations is enough for this phase.
|
|
- Do not force feature modules to pass renderer flags around. If two surface kinds need separate logic, isolate that inside the lifecycle owner.
|
|
- Preserve the current `WebGLLayer` canvas and shared context budget.
|
|
- Keep the API compact. Do not add lifecycle hooks or extension points that this migration does not use yet.
|
|
|
|
### Architecture Compliance
|
|
|
|
- This story implements the architecture requirement that each logical layer owns one surface lifecycle and that layer modules own only their own drawing surface.
|
|
- The abstraction must support incremental migration. Existing SVG groups can be wrapped now; split SVG shells come later.
|
|
|
|
### Previous Story Intelligence
|
|
|
|
- Story 1.3 should already establish the registry as the single ordering authority. Plug lifecycle ownership into that registry instead of storing a second map of surfaces.
|
|
- The existing `WebGLLayer` module already manages per-layer groups and a shared renderer. Extend that ownership model rather than replacing it.
|
|
- Story 1.2 should already own shared camera meaning. The lifecycle contract should consume Scene state, not recreate transform helpers.
|
|
|
|
### Project Structure Notes
|
|
|
|
- Expected touch points:
|
|
- `src/modules/layer.ts`
|
|
- `src/modules/layers.ts`
|
|
- `src/modules/webgl-layer.ts`
|
|
- `src/modules/texture-atlas-layer.ts`
|
|
- `src/renderers/draw-relief-icons.ts`
|
|
- `src/types/global.ts`
|
|
- Keep renderer-specific logic close to the existing modules rather than introducing extra indirection files.
|
|
- Avoid adding separate generic adapter directories or pattern-heavy wrappers for only one WebGL and one SVG path.
|
|
|
|
### Testing Notes
|
|
|
|
- Manual validation is sufficient.
|
|
- Focus on mount, redraw, hide/show, and cleanup behavior for relief because that is the current live mixed-render surface.
|
|
- Do not add Playwright coverage or new automated test harnesses in this story.
|
|
|
|
### Dependencies
|
|
|
|
- Story 1.3 should land first so the lifecycle owner plugs into the registry instead of inventing a second source of truth.
|
|
|
|
### References
|
|
|
|
- [Source: _bmad-output/planning-artifacts/epics.md, Epic 1, Story 1.4]
|
|
- [Source: _bmad-output/planning-artifacts/architecture-layered-map-dom-split.md, Decision 2, Decision 4, Clean Code Rules, Migration Plan]
|
|
- [Source: src/modules/webgl-layer.ts, shared renderer and per-layer group ownership]
|
|
- [Source: src/renderers/draw-relief-icons.ts, current feature-to-WebGL integration]
|
|
- [Source: src/modules/texture-atlas-layer.ts, current WebGL rerender trigger]
|
|
|
|
## Dev Agent Record
|
|
|
|
### Agent Model Used
|
|
|
|
Claude Sonnet 4.6
|
|
|
|
### Debug Log References
|
|
|
|
None.
|
|
|
|
### Completion Notes List
|
|
|
|
- Story context prepared on 2026-03-13.
|
|
- Implemented 2026-03-13 by Claude Sonnet 4.6.
|
|
- Created `src/modules/layer.ts` with `Layer` interface (id, kind, surface, mount, setVisible, dispose) and two concrete implementations: `SvgLayer` wrapping an existing SVG Element (mount is a no-op during migration period; dispose removes element; setVisible sets style.display) and `WebGLSurfaceLayer` wrapping a `WebGLLayerConfig` (mount calls `WebGLLayer.register()`; setVisible calls `WebGLLayer.setLayerVisible()`; dispose calls `WebGLLayer.unregister()`).
|
|
- Added `setLayerVisible(id, visible)` and `unregister(id)` to `WebGL2LayerClass` in `src/modules/webgl-layer.ts`. `setLayerVisible` sets `group.visible` and triggers a rerender frame. `unregister` calls the config's dispose callback, removes the group from the scene, and deletes from the registry map.
|
|
- Updated `src/modules/layers.ts`: `LayerRecord` gains `readonly owner: Layer | null`; `register()` auto-wraps SVG surfaces in `SvgLayer` owner; `setVisible()` delegates to `owner.setVisible()` in addition to updating the flag.
|
|
- Updated `src/modules/texture-atlas-layer.ts`: the constructor no longer calls `WebGLLayer.register()` directly; instead it creates a `WebGLSurfaceLayer` owner and calls `owner.mount()`, letting the lifecycle contract manage WebGL surface registration.
|
|
- All 62 unit tests pass; TypeScript and Biome checks clean.
|
|
|
|
### File List
|
|
|
|
- src/modules/layer.ts (new)
|
|
- src/modules/webgl-layer.ts (modified)
|
|
- src/modules/layers.ts (modified)
|
|
- src/modules/texture-atlas-layer.ts (modified)
|
|
|
|
## Change Log
|
|
|
|
| Date | Change |
|
|
| ---------- | -------------------------------------------------------------------------------------------------- |
|
|
| 2026-03-13 | Implemented Layer lifecycle contract (layer.ts, webgl-layer.ts, layers.ts, texture-atlas-layer.ts) |
|
|
|
|
- Story context prepared on 2026-03-13.
|
|
|
|
### File List
|