mirror of
https://github.com/Azgaar/Fantasy-Map-Generator.git
synced 2026-04-06 23:47:24 +02:00
feat: Implement Story 1.6 - Move Shared Defs Resources to the Dedicated Host
- Added documentation for Story 1.6 outlining the requirements and acceptance criteria for migrating shared defs-backed resources to a dedicated host. - Updated sprint status to reflect the readiness of Story 1.6 for development. - Created epics document detailing the breakdown of the Fantasy-Map-Generator project, including functional and non-functional requirements. - Added implementation readiness report assessing the current state of documentation and readiness for the project. - Introduced end-to-end tests for scene bootstrap to ensure runtime hosts are created and reused correctly.
This commit is contained in:
Azgaar
parent
df18f69516
commit
125403b82f
10 changed files with 1522 additions and 0 deletions
480
_bmad-output/planning-artifacts/epics.md
Normal file
480
_bmad-output/planning-artifacts/epics.md
Normal file
|
|
@ -0,0 +1,480 @@
|
|||
---
|
||||
stepsCompleted:
|
||||
- step-01-validate-prerequisites
|
||||
- step-02-design-epics
|
||||
- step-03-create-stories
|
||||
- step-04-final-validation
|
||||
inputDocuments:
|
||||
- _bmad-output/planning-artifacts/prd-layered-map-dom-split.md
|
||||
- _bmad-output/planning-artifacts/architecture-layered-map-dom-split.md
|
||||
---
|
||||
|
||||
# Fantasy-Map-Generator - Epic Breakdown
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides the complete epic and story breakdown for Fantasy-Map-Generator, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.
|
||||
|
||||
## Requirements Inventory
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
FR1: Users can reorder layers in any sequence supported today, regardless of whether the layer is implemented in SVG or WebGL.
|
||||
FR2: Visibility toggles behave exactly as they do now.
|
||||
FR3: Editing and pointer interaction remain correct after layer splitting.
|
||||
FR4: Shared styles, filters, masks, and text path resources remain available where needed.
|
||||
FR5: Existing layer-based workflows continue to function without exposing rendering implementation details.
|
||||
FR6: Export produces equivalent output to the current behavior for supported layers.
|
||||
FR7: Legacy code paths that depend on svg, viewbox, or one selector scope have a compatibility path during migration.
|
||||
|
||||
### NonFunctional Requirements
|
||||
|
||||
NFR1: The architecture must support incremental migration rather than a flag-day rewrite.
|
||||
NFR2: Test design and execution are out of scope for this implementation tranche and will be handled in a separate follow-up activity.
|
||||
NFR3: Layer order changes must update all runtime surfaces atomically.
|
||||
NFR4: Performance must not regress for existing SVG-only layers.
|
||||
NFR5: The architecture must remain compatible with the existing global-variable runtime model.
|
||||
|
||||
### Additional Requirements
|
||||
|
||||
- The layer registry is the single source of truth and each layer must register id, kind, order, visible state, and surface.
|
||||
- The runtime scene must use one independent surface per logical layer, including dedicated SVG shells for SVG layers and registered canvas surfaces for WebGL layers.
|
||||
- Shared transform ownership moves from the old viewbox DOM element to scene state, while scale, viewX, viewY, graphWidth, and graphHeight remain authoritative globals.
|
||||
- svg and viewbox must stop being architectural source-of-truth globals and instead be supported only through a temporary compatibility layer during migration.
|
||||
- The compatibility layer must provide getLayerSvg(id), getLayerSurface(id), and queryMap(selector).
|
||||
- Runtime shared defs resources must live in a dedicated defs host separate from layer surfaces.
|
||||
- Filters, patterns, masks, symbols, markers, and text paths must use stable IDs and remain available across split surfaces.
|
||||
- Export must use a separate assembly pipeline that rebuilds a unified SVG from registry order, layer outputs, and only the required defs resources.
|
||||
- Runtime structure must allow arbitrary ordering of SVG and WebGL layers without grouped SVG buckets.
|
||||
- Layer modules should own only their own drawing surface; scene owns shared runtime state; defs owns shared SVG resources.
|
||||
- The migration should proceed in phases: foundation, initial split layers, mixed rendering, then export hardening.
|
||||
- No starter template requirement was identified in the architecture document.
|
||||
- No UX document was provided, so no UX-specific requirements were added in this step.
|
||||
|
||||
### FR Coverage Map
|
||||
|
||||
FR1: Epic 2 and Epic 3 - Reordering remains correct first for split SVG layers and then for mixed SVG and WebGL layers.
|
||||
FR2: Epic 2 and Epic 3 - Visibility behavior remains unchanged for split layers and mixed rendering.
|
||||
FR3: Epic 2 and Epic 3 - Pointer and editing workflows remain correct through the split-layer and mixed-render transitions.
|
||||
FR4: Epic 1 and Epic 4 - Shared defs-backed resources are preserved in runtime and in unified export output.
|
||||
FR5: Epic 1, Epic 2, and Epic 3 - Existing workflows continue to work while the runtime architecture changes underneath them.
|
||||
FR6: Epic 4 - Export output remains equivalent for supported layers after the runtime moves to split surfaces.
|
||||
FR7: Epic 1 - Legacy single-SVG callers keep a compatibility path during migration.
|
||||
|
||||
## Epic List
|
||||
|
||||
### Epic 1: Foundation for Layered Runtime
|
||||
|
||||
Establish the shared scene, defs, layer registry, layer lifecycle, and compatibility contracts so the runtime can migrate away from one canonical SVG root without breaking existing map behavior.
|
||||
**FRs covered:** FR4, FR5, FR7
|
||||
|
||||
### Epic 2: First Split SVG Layers
|
||||
|
||||
Move approved low-risk SVG layers into standalone SVG shells while preserving visual behavior, layer controls, and editing interactions.
|
||||
**FRs covered:** FR1, FR2, FR3, FR5
|
||||
|
||||
### Epic 3: Mixed SVG and WebGL Ordering
|
||||
|
||||
Register WebGL surfaces under the same ordering and visibility model so users can interleave SVG and WebGL layers through one control path.
|
||||
**FRs covered:** FR1, FR2, FR3, FR5
|
||||
|
||||
### Epic 4: Unified Export Assembly
|
||||
|
||||
Assemble a unified SVG export from registry state and shared defs resources so supported layered maps export with equivalent output quality.
|
||||
**FRs covered:** FR4, FR6
|
||||
|
||||
## Epic 1: Foundation for Layered Runtime
|
||||
|
||||
Establish the shared scene, defs, layer registry, layer lifecycle, and compatibility contracts so the runtime can migrate away from one canonical SVG root without breaking existing map behavior.
|
||||
|
||||
### Story 1.1: Bootstrap Scene Container and Defs Host
|
||||
|
||||
As a map maintainer,
|
||||
I want runtime initialization to create a dedicated scene container and defs host,
|
||||
So that split layer surfaces can share resources without depending on one map SVG root.
|
||||
|
||||
**Implements:** FR4, FR5; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the current runtime starts from one canonical map host
|
||||
**When** the layered runtime bootstrap runs
|
||||
**Then** it creates or reuses a dedicated scene container for layer surfaces and a dedicated defs host outside individual layer surfaces
|
||||
**And** the visible map loads without user-facing regressions at startup.
|
||||
|
||||
**Given** existing code expects the map to initialize once
|
||||
**When** the new bootstrap path is enabled
|
||||
**Then** the scene container and defs host are available through stable runtime references
|
||||
**And** initialization does not require changing user-facing layer controls.
|
||||
|
||||
### Story 1.2: Add Scene Module for Shared Camera State
|
||||
|
||||
As a map maintainer,
|
||||
I want a Scene module to own shared camera and viewport state,
|
||||
So that all layer surfaces consume one authoritative transform contract.
|
||||
|
||||
**Implements:** FR5; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** shared globals such as scale, viewX, viewY, graphWidth, and graphHeight already exist
|
||||
**When** the Scene module is introduced
|
||||
**Then** it exposes a single runtime contract for camera and viewport state
|
||||
**And** existing global values remain authoritative and usable during migration.
|
||||
|
||||
**Given** multiple surfaces will render the same map
|
||||
**When** camera state changes
|
||||
**Then** the Scene module provides one consistent state source for all registered surfaces
|
||||
**And** no feature code needs to read transforms from DOM structure directly.
|
||||
|
||||
### Story 1.3: Add Layers Registry as the Ordering Source of Truth
|
||||
|
||||
As a map maintainer,
|
||||
I want a centralized Layers registry,
|
||||
So that visibility, order, and surface ownership are managed consistently instead of inferred from DOM position.
|
||||
|
||||
**Implements:** FR5; NFR1, NFR3, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** logical map layers currently rely on DOM placement and ad hoc lookups
|
||||
**When** a layer is registered
|
||||
**Then** the registry stores its id, kind, order, visible state, and surface handle
|
||||
**And** callers can query layer state without inferring it from DOM order.
|
||||
|
||||
**Given** runtime layer order changes
|
||||
**When** reorder operations are applied through the registry
|
||||
**Then** all registered layer surfaces receive the updated ordering atomically
|
||||
**And** the registry remains the single source of truth for visibility and order.
|
||||
|
||||
### Story 1.4: Add Layer Surface Lifecycle Ownership
|
||||
|
||||
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.
|
||||
|
||||
**Implements:** FR5; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
### Story 1.5: Add Compatibility Lookups for Legacy Single-SVG Callers
|
||||
|
||||
As a map maintainer,
|
||||
I want compatibility helpers for legacy single-SVG access patterns,
|
||||
So that existing workflows keep working while code migrates to the new scene and layer contracts.
|
||||
|
||||
**Implements:** FR5, FR7; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** legacy code still expects svg, viewbox, or one shared selector scope
|
||||
**When** compatibility helpers are introduced
|
||||
**Then** the runtime provides getLayerSvg(id), getLayerSurface(id), and queryMap(selector)
|
||||
**And** callers can continue to function during migration without depending on one canonical map SVG.
|
||||
|
||||
**Given** new code is added after the compatibility layer exists
|
||||
**When** it needs layer or scene access
|
||||
**Then** it can use the new layer and scene contracts directly
|
||||
**And** the compatibility layer remains a migration bridge rather than the new source of truth.
|
||||
|
||||
### Story 1.6: Move Shared Defs Resources to the Dedicated Host
|
||||
|
||||
As a map maintainer,
|
||||
I want shared defs-backed resources to be registered in one dedicated host,
|
||||
So that split surfaces can keep using stable IDs for filters, masks, symbols, markers, patterns, and text paths.
|
||||
|
||||
**Implements:** FR4, FR5; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** runtime resources currently live under one shared SVG structure
|
||||
**When** defs registration is migrated
|
||||
**Then** shared resources are created under the dedicated defs host with stable identifiers
|
||||
**And** layer surfaces can reference those resources without duplicating them per layer.
|
||||
|
||||
**Given** a split surface uses a filter, mask, symbol, marker, pattern, or text path
|
||||
**When** the layer renders
|
||||
**Then** the resource reference resolves from the dedicated defs host
|
||||
**And** existing visual behavior remains unchanged for supported runtime features.
|
||||
|
||||
## Epic 2: First Split SVG Layers
|
||||
|
||||
Move approved low-risk SVG layers into standalone SVG shells while preserving visual behavior, layer controls, and editing interactions.
|
||||
|
||||
### Story 2.1: Create Reusable Standalone SVG Shell Mounting
|
||||
|
||||
As a map maintainer,
|
||||
I want low-risk SVG layers to mount into dedicated SVG shells,
|
||||
So that selected layers can leave the single-root SVG without changing their visible behavior.
|
||||
|
||||
**Implements:** FR5; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** a low-risk SVG layer is selected for migration
|
||||
**When** its surface is created through the layered runtime
|
||||
**Then** the layer mounts into its own dedicated SVG shell inside the scene container
|
||||
**And** the shell can participate in registry-controlled ordering and visibility.
|
||||
|
||||
**Given** the shell mounting path is in place
|
||||
**When** another approved low-risk SVG layer is migrated
|
||||
**Then** the same mounting mechanism can be reused without introducing layer-specific bootstrap hacks
|
||||
**And** the migration remains incremental.
|
||||
|
||||
### Story 2.2: Migrate a Representative Low-Risk SVG Layer to a Dedicated Shell
|
||||
|
||||
As a map maintainer,
|
||||
I want one representative low-risk SVG layer migrated first,
|
||||
So that the split-surface path is proven on a contained layer before broader rollout.
|
||||
|
||||
**Implements:** FR3, FR5; NFR1, NFR4.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the standalone shell path exists
|
||||
**When** the first approved low-risk SVG layer is migrated
|
||||
**Then** it renders from its dedicated shell with unchanged visual output for supported behavior
|
||||
**And** its feature workflow continues to operate through the new scene and layer contracts.
|
||||
|
||||
**Given** the representative layer is split out
|
||||
**When** users interact with that layer through existing tools
|
||||
**Then** pointer targeting and editing behavior remain correct
|
||||
**And** the migration does not require unrelated layers to move at the same time.
|
||||
|
||||
### Story 2.3: Migrate Remaining Approved Low-Risk SVG Layers
|
||||
|
||||
As a map maintainer,
|
||||
I want the remaining approved low-risk SVG layers moved through the same split-layer path,
|
||||
So that the runtime can prove multi-layer SVG splitting before mixed rendering begins.
|
||||
|
||||
**Implements:** FR3, FR5; NFR1, NFR4.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the representative migration pattern has been established
|
||||
**When** additional approved low-risk SVG layers are migrated
|
||||
**Then** each layer renders from its own SVG shell using the shared scene, layer, and defs contracts
|
||||
**And** each migrated layer preserves its existing visible behavior for supported workflows.
|
||||
|
||||
**Given** more than one low-risk SVG layer has been split
|
||||
**When** they coexist in the runtime
|
||||
**Then** they can render independently without grouped SVG buckets
|
||||
**And** layer modules remain responsible only for their own surfaces.
|
||||
|
||||
### Story 2.4: Drive Reorder and Visibility for Split SVG Layers from the Registry
|
||||
|
||||
As a map user,
|
||||
I want reordered and toggled split SVG layers to behave exactly as before,
|
||||
So that layer management remains familiar while the runtime architecture changes.
|
||||
|
||||
**Implements:** FR1, FR2, FR5; NFR3, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** one or more low-risk SVG layers have been split into standalone shells
|
||||
**When** a user reorders those layers through existing controls
|
||||
**Then** the registry updates the shell ordering atomically
|
||||
**And** the visible stacking order matches the updated control order.
|
||||
|
||||
**Given** a user toggles visibility for a split SVG layer
|
||||
**When** the layer state changes
|
||||
**Then** the registry applies the visible state to the correct shell
|
||||
**And** toggle behavior matches existing user expectations.
|
||||
|
||||
### Story 2.5: Preserve Pointer and Editing Workflows for Split SVG Layers
|
||||
|
||||
As a map user,
|
||||
I want editing and pointer interactions to remain correct on split SVG layers,
|
||||
So that the architectural migration does not break existing map workflows.
|
||||
|
||||
**Implements:** FR3, FR5; NFR4, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** a split SVG layer supports pointer or editing workflows today
|
||||
**When** a user clicks, hovers, drags, or edits through the existing UI
|
||||
**Then** events reach the correct standalone layer surface
|
||||
**And** the workflow behaves the same way it did before the split.
|
||||
|
||||
**Given** multiple split SVG layers can overlap in the scene
|
||||
**When** the active tool resolves pointer targets
|
||||
**Then** targeting respects the registry-driven order and layer visibility state
|
||||
**And** no workflow depends on a future mixed-render story to function.
|
||||
|
||||
## Epic 3: Mixed SVG and WebGL Ordering
|
||||
|
||||
Register WebGL surfaces under the same ordering and visibility model so users can interleave SVG and WebGL layers through one control path.
|
||||
|
||||
### Story 3.1: Register WebGL Surfaces in the Shared Layer Model
|
||||
|
||||
As a map maintainer,
|
||||
I want WebGL surfaces registered in the same Layers model as SVG layers,
|
||||
So that render technology no longer determines whether a layer can participate in the ordered scene.
|
||||
|
||||
**Implements:** FR1, FR5; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the Layers registry already manages SVG layer surfaces
|
||||
**When** a WebGL layer is registered
|
||||
**Then** it receives the same core metadata contract of id, kind, order, visible state, and surface handle
|
||||
**And** the registry can treat SVG and WebGL layers as peers in the same scene.
|
||||
|
||||
**Given** existing WebGL behavior already depends on shared scene context
|
||||
**When** registration is moved into the shared layer model
|
||||
**Then** WebGL layers keep access to the required scene and camera state
|
||||
**And** they no longer rely on special ordering paths outside the registry.
|
||||
|
||||
### Story 3.2: Unify Mixed-Layer Ordering and Visibility Controls
|
||||
|
||||
As a map user,
|
||||
I want one layer control path to reorder and toggle both SVG and WebGL layers,
|
||||
So that I can manage the full layer stack without caring how any layer is rendered.
|
||||
|
||||
**Implements:** FR1, FR2, FR5; NFR3, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** both SVG and WebGL layers are registered in the scene
|
||||
**When** a user changes layer order through the existing controls
|
||||
**Then** the registry applies the new order across both render technologies atomically
|
||||
**And** the visible stack matches the requested mixed order.
|
||||
|
||||
**Given** a user toggles visibility for an SVG or WebGL layer
|
||||
**When** the control state changes
|
||||
**Then** the runtime updates the correct surface regardless of renderer type
|
||||
**And** visibility behavior remains consistent across the mixed stack.
|
||||
|
||||
### Story 3.3: Keep Scene Transforms and Interaction Correct in Mixed Rendering
|
||||
|
||||
As a map user,
|
||||
I want zoom, pan, and interactions to stay aligned across SVG and WebGL layers,
|
||||
So that the map behaves as one coherent scene after mixed rendering is enabled.
|
||||
|
||||
**Implements:** FR3, FR5; NFR4, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the scene contains both SVG and WebGL surfaces
|
||||
**When** camera state changes through zoom or pan
|
||||
**Then** all registered surfaces consume the same scene transform state
|
||||
**And** the map remains visually aligned across renderer boundaries.
|
||||
|
||||
**Given** a user interacts with mixed-render content through existing tools
|
||||
**When** the runtime resolves those interactions
|
||||
**Then** the correct layer surface handles the interaction in scene order
|
||||
**And** mixed rendering does not degrade the expected behavior of existing workflows.
|
||||
|
||||
### Story 3.4: Preserve Atomic Updates and No-Regressions Guardrails in Mixed Mode
|
||||
|
||||
As a map maintainer,
|
||||
I want mixed-layer updates applied through one controlled pipeline,
|
||||
So that the runtime preserves atomic layer changes and avoids regressions for existing SVG-heavy maps.
|
||||
|
||||
**Implements:** FR1, FR2, FR5; NFR3, NFR4.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** layer order or visibility changes affect both SVG and WebGL surfaces
|
||||
**When** the runtime applies an update
|
||||
**Then** all affected surfaces transition through one coordinated update path
|
||||
**And** partial mixed-stack states are not exposed to the user.
|
||||
|
||||
**Given** an existing SVG-heavy map uses no new mixed-render features
|
||||
**When** it runs on the layered runtime
|
||||
**Then** the runtime preserves current behavior for supported workflows
|
||||
**And** the migration does not introduce avoidable performance regressions for SVG-only scenarios.
|
||||
|
||||
## Epic 4: Unified Export Assembly
|
||||
|
||||
Assemble a unified SVG export from registry state and shared defs resources so supported layered maps export with equivalent output quality.
|
||||
|
||||
### Story 4.1: Add Export Participation Metadata to the Layer Registry
|
||||
|
||||
As a map maintainer,
|
||||
I want each registered layer to declare how it participates in export,
|
||||
So that unified SVG assembly can rebuild export output from registry state instead of the live runtime DOM.
|
||||
|
||||
**Implements:** FR6; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the export pipeline can no longer assume the runtime DOM is the final SVG document
|
||||
**When** a layer is registered for export
|
||||
**Then** the registry stores the metadata needed to include, order, or skip that layer during export assembly
|
||||
**And** export logic reads registry state rather than scraping one runtime SVG root.
|
||||
|
||||
**Given** supported layers have different render technologies
|
||||
**When** export participation metadata is evaluated
|
||||
**Then** the assembler can determine which layers contribute to the final SVG output
|
||||
**And** unsupported layers can be excluded intentionally rather than failing implicitly.
|
||||
|
||||
### Story 4.2: Assemble Unified SVG Export from Registry Order
|
||||
|
||||
As a map user,
|
||||
I want export output assembled from the layered runtime state,
|
||||
So that my exported map preserves supported layer order after the DOM is split into separate surfaces.
|
||||
|
||||
**Implements:** FR6; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the runtime scene is composed of multiple registered surfaces
|
||||
**When** a user exports the map
|
||||
**Then** the export pipeline assembles one unified SVG document using registry order
|
||||
**And** the supported exported layer stack matches the user-visible order.
|
||||
|
||||
**Given** the runtime no longer uses one canonical map SVG as its model
|
||||
**When** export runs
|
||||
**Then** the export pipeline treats the live DOM as an implementation detail rather than the export source of truth
|
||||
**And** supported layers still produce equivalent SVG output.
|
||||
|
||||
### Story 4.3: Clone Only Required Defs Resources into Export
|
||||
|
||||
As a map user,
|
||||
I want exported SVG files to include only the defs resources they actually use,
|
||||
So that exported maps remain correct without dragging along unrelated runtime resources.
|
||||
|
||||
**Implements:** FR4, FR6; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the runtime defs host may contain resources for many layers
|
||||
**When** export assembly runs
|
||||
**Then** the pipeline includes only defs resources referenced by the exported layers
|
||||
**And** exported resources preserve the stable IDs required by those layers.
|
||||
|
||||
**Given** an exported layer references shared defs-backed assets
|
||||
**When** the export document is opened independently of the runtime
|
||||
**Then** those references resolve correctly within the assembled SVG
|
||||
**And** unrelated defs content is not copied by default.
|
||||
|
||||
### Story 4.4: Preserve Text Paths, Masks, and Filtered Layers in Export
|
||||
|
||||
As a map user,
|
||||
I want exported maps to preserve supported advanced SVG features,
|
||||
So that split-surface runtime changes do not degrade final output quality.
|
||||
|
||||
**Implements:** FR4, FR6; NFR1, NFR5.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** supported exported layers use text paths, masks, filters, symbols, markers, or patterns
|
||||
**When** export assembly completes
|
||||
**Then** the unified SVG preserves those features with correct references and ordering
|
||||
**And** output remains equivalent for supported layers.
|
||||
|
||||
**Given** advanced defs-backed features participate in export
|
||||
**When** the assembler processes them
|
||||
**Then** it clones the required resources and wiring needed for those features to render correctly outside the runtime
|
||||
**And** export hardening remains isolated from runtime ordering logic.
|
||||
|
|
@ -0,0 +1,236 @@
|
|||
---
|
||||
stepsCompleted:
|
||||
- step-01-document-discovery
|
||||
inputDocuments:
|
||||
- _bmad-output/planning-artifacts/prd-layered-map-dom-split.md
|
||||
- _bmad-output/planning-artifacts/architecture-layered-map-dom-split.md
|
||||
- _bmad-output/planning-artifacts/epics.md
|
||||
excludedDocuments:
|
||||
- _bmad-output/planning-artifacts/prd.md
|
||||
- _bmad-output/planning-artifacts/architecture.md
|
||||
missingDocuments:
|
||||
- UX design document
|
||||
---
|
||||
|
||||
# Implementation Readiness Assessment Report
|
||||
|
||||
**Date:** 2026-03-12
|
||||
**Project:** Fantasy-Map-Generator
|
||||
|
||||
## Document Discovery
|
||||
|
||||
### PRD Files Found
|
||||
|
||||
**Whole Documents:**
|
||||
|
||||
- \_bmad-output/planning-artifacts/prd-layered-map-dom-split.md (8695 bytes, modified Mar 12 23:06:55 2026) [selected]
|
||||
- \_bmad-output/planning-artifacts/prd.md (31818 bytes, modified Mar 12 03:42:10 2026) [excluded]
|
||||
|
||||
### Architecture Files Found
|
||||
|
||||
**Whole Documents:**
|
||||
|
||||
- \_bmad-output/planning-artifacts/architecture-layered-map-dom-split.md (7274 bytes, modified Mar 12 23:22:49 2026) [selected]
|
||||
- \_bmad-output/planning-artifacts/architecture.md (50648 bytes, modified Mar 12 19:00:05 2026) [excluded]
|
||||
|
||||
### Epics and Stories Files Found
|
||||
|
||||
**Whole Documents:**
|
||||
|
||||
- \_bmad-output/planning-artifacts/epics.md (22401 bytes, modified Mar 12 23:55:41 2026) [selected]
|
||||
|
||||
### UX Files Found
|
||||
|
||||
- None found
|
||||
|
||||
## Discovery Issues
|
||||
|
||||
- Duplicate document families exist for PRD and Architecture. This assessment uses the layered-map documents explicitly requested by the user and excludes the baseline documents from scope.
|
||||
- No UX design artifact was found. Readiness assessment will proceed without UX-specific validation.
|
||||
|
||||
## Assessment Scope
|
||||
|
||||
This readiness assessment is scoped to:
|
||||
|
||||
- \_bmad-output/planning-artifacts/prd-layered-map-dom-split.md
|
||||
- \_bmad-output/planning-artifacts/architecture-layered-map-dom-split.md
|
||||
- \_bmad-output/planning-artifacts/epics.md
|
||||
|
||||
## PRD Analysis
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
FR1: Users can reorder layers in any sequence supported today, regardless of whether the layer is implemented in SVG or WebGL.
|
||||
FR2: Visibility toggles behave exactly as they do now.
|
||||
FR3: Editing and pointer interaction remain correct after layer splitting.
|
||||
FR4: Shared styles, filters, masks, and text path resources remain available where needed.
|
||||
FR5: Existing layer-based workflows continue to function without exposing rendering implementation details.
|
||||
FR6: Export produces equivalent output to the current behavior for supported layers.
|
||||
FR7: Legacy code paths that depend on svg, viewbox, or one selector scope have a compatibility path during migration.
|
||||
|
||||
Total FRs: 7
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
NFR1: The architecture must support incremental migration rather than a flag-day rewrite.
|
||||
NFR2: Test design and execution are out of scope for this implementation tranche and will be handled in a separate follow-up activity.
|
||||
NFR3: Layer order changes must update all runtime surfaces atomically.
|
||||
NFR4: Performance must not regress for existing SVG-only layers.
|
||||
NFR5: The architecture must remain compatible with the existing global-variable runtime model.
|
||||
|
||||
Total NFRs: 5
|
||||
|
||||
### Additional Requirements
|
||||
|
||||
- The initiative is explicitly constrained to preserve current user-visible layer controls, visibility behavior, edit workflows, and output quality while the runtime architecture changes underneath.
|
||||
- Shared map state remains globally accessible, but globals tied to one concrete SVG root may be narrowed, redefined, or placed behind compatibility adapters.
|
||||
- Shared defs, masks, filters, symbols, and text paths are first-class requirements rather than deferred cleanup.
|
||||
- The codebase needs an inventory and migration plan for hotspots that assume one map SVG or one shared selector scope.
|
||||
- Automated and manual testing are out of scope for this implementation tranche and deferred until the new layer model stabilizes.
|
||||
- The current PRD leaves several architecture-shaping questions open, including which layers are low-risk for splitting first and how export assembly should be sourced.
|
||||
|
||||
### PRD Completeness Assessment
|
||||
|
||||
The PRD is sufficient to define the product goal, scope boundaries, functional requirements, non-functional requirements, and acceptance themes for the layered-runtime initiative. It is intentionally incomplete on implementation specifics and leaves several open questions for architecture and execution planning, which is acceptable because those details are partially answered by the selected architecture document. The main residual gap at the PRD layer is that it does not name the initial low-risk split candidates or define a UX artifact, so implementation readiness depends on the architecture and epics compensating for that missing specificity.
|
||||
|
||||
## Epic Coverage Validation
|
||||
|
||||
### Epic FR Coverage Extracted
|
||||
|
||||
FR1: Covered in Epic 2 and Epic 3
|
||||
FR2: Covered in Epic 2 and Epic 3
|
||||
FR3: Covered in Epic 2 and Epic 3
|
||||
FR4: Covered in Epic 1 and Epic 4
|
||||
FR5: Covered in Epic 1, Epic 2, and Epic 3
|
||||
FR6: Covered in Epic 4
|
||||
FR7: Covered in Epic 1
|
||||
|
||||
Total FRs in epics: 7
|
||||
|
||||
### Coverage Matrix
|
||||
|
||||
| FR Number | PRD Requirement | Epic Coverage | Status |
|
||||
| --------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------- |
|
||||
| FR1 | Users can reorder layers in any sequence supported today, regardless of whether the layer is implemented in SVG or WebGL. | Epic 2 Story 2.4; Epic 3 Stories 3.1, 3.2, 3.4 | Covered |
|
||||
| FR2 | Visibility toggles behave exactly as they do now. | Epic 2 Story 2.4; Epic 3 Stories 3.2, 3.4 | Covered |
|
||||
| FR3 | Editing and pointer interaction remain correct after layer splitting. | Epic 2 Stories 2.2, 2.3, 2.5; Epic 3 Story 3.3 | Covered |
|
||||
| FR4 | Shared styles, filters, masks, and text path resources remain available where needed. | Epic 1 Stories 1.1, 1.6; Epic 4 Stories 4.3, 4.4 | Covered |
|
||||
| FR5 | Existing layer-based workflows continue to function without exposing rendering implementation details. | Epic 1 Stories 1.1 to 1.6; Epic 2 Stories 2.1 to 2.5; Epic 3 Stories 3.1 to 3.4 | Covered |
|
||||
| FR6 | Export produces equivalent output to the current behavior for supported layers. | Epic 4 Stories 4.1 to 4.4 | Covered |
|
||||
| FR7 | Legacy code paths that depend on svg, viewbox, or one selector scope have a compatibility path during migration. | Epic 1 Story 1.5 | Covered |
|
||||
|
||||
### Missing Requirements
|
||||
|
||||
No PRD functional requirements are missing from the current epics and stories document.
|
||||
|
||||
Residual traceability note:
|
||||
|
||||
- FR3 and FR5 are covered broadly, but validation depends on maintaining story acceptance criteria discipline during implementation because these requirements span many modules and workflows.
|
||||
- FR4 and FR6 coverage is present, but export fidelity remains low priority and therefore carries sequencing risk rather than outright coverage risk.
|
||||
|
||||
### Coverage Statistics
|
||||
|
||||
- Total PRD FRs: 7
|
||||
- FRs covered in epics: 7
|
||||
- Coverage percentage: 100%
|
||||
|
||||
## UX Alignment Assessment
|
||||
|
||||
### UX Document Status
|
||||
|
||||
Not Found.
|
||||
|
||||
### Alignment Issues
|
||||
|
||||
- No dedicated UX planning artifact exists for this initiative, so there is no separately reviewed source for interaction flows, affordances, edge-case behavior, or acceptance-level user experience constraints.
|
||||
- The PRD clearly implies a user-facing application because it requires stable layer controls, visibility behavior, edit workflows, and output quality, but those expectations are not decomposed into a dedicated UX document.
|
||||
- The architecture preserves current user-visible behavior and interaction correctness, which partially compensates for missing UX documentation, but it does not replace explicit UX decisions for complex editing workflows.
|
||||
|
||||
### Warnings
|
||||
|
||||
- UX is implied by the problem and requirements, but no UX artifact was provided for readiness validation.
|
||||
- Implementation can proceed for this architecture tranche because the stated goal is behavioral parity rather than new interaction design, but QA and acceptance review later will carry extra ambiguity around interaction regressions.
|
||||
- If future stories introduce changed controls, changed affordances, or non-parity interaction behavior, a UX artifact should be created before implementation continues.
|
||||
|
||||
## Epic Quality Review
|
||||
|
||||
### Best Practices Compliance Summary
|
||||
|
||||
- Epic independence is mostly preserved in sequence: Epic 2 can build on Epic 1, Epic 3 can build on Epics 1 and 2, and Epic 4 can remain low-priority and isolated to export.
|
||||
- Within-epic forward dependencies are mostly controlled. The story order generally builds from infrastructure to usage without explicit dependence on future stories.
|
||||
- Traceability is present because every story includes an Implements line and the document includes a coverage map.
|
||||
|
||||
### 🔴 Critical Violations
|
||||
|
||||
1. The epic structure is phase-driven technical delivery, not user-value-driven delivery.
|
||||
|
||||
- Epic 1 is explicitly foundation work: scene, defs, registry, layer lifecycle, compatibility contracts.
|
||||
- Epic 2 and Epic 3 are migration phases keyed to renderer architecture.
|
||||
- Epic 4 is an export pipeline phase.
|
||||
- This directly conflicts with the workflow standard that epics should organize around user value rather than technical layers or infrastructure milestones.
|
||||
- Recommendation: accept these as implementation phases if that is the deliberate exception, but mark the document as not fully compliant with BMAD epic-quality rules.
|
||||
|
||||
2. Several stories are technical maintenance stories rather than meaningful user capabilities.
|
||||
|
||||
- Examples: Story 1.2 Add Scene Module for Shared Camera State, Story 1.3 Add Layers Registry as the Ordering Source of Truth, Story 1.4 Add Layer Surface Lifecycle Ownership, Story 3.1 Register WebGL Surfaces in the Shared Layer Model, Story 4.1 Add Export Participation Metadata to the Layer Registry.
|
||||
- These may be valid implementation work items, but they are not strong user stories under the workflow’s own standard.
|
||||
- Recommendation: either convert them into engineering tasks under broader user-facing stories, or explicitly classify this artifact as an architecture-delivery plan rather than pure user-story decomposition.
|
||||
|
||||
### 🟠 Major Issues
|
||||
|
||||
1. Acceptance criteria are testable but often too abstract for direct implementation handoff.
|
||||
|
||||
- Many ACs assert outcomes like "existing visual behavior remains unchanged" or "workflow behaves the same way it did before" without naming concrete layers, tools, or observables.
|
||||
- This makes implementation review and later QA interpretation more subjective than it should be.
|
||||
- Recommendation: add concrete examples or named validation targets per story, especially for split-layer migrations and export fidelity.
|
||||
|
||||
2. Low-risk SVG migration scope is still undefined at story level.
|
||||
|
||||
- Epic 2 depends on "approved low-risk SVG layers," but the selected documents never identify which layers those are.
|
||||
- Story 2.2 and Story 2.3 are therefore not fully actionable without another planning decision.
|
||||
- Recommendation: add a shortlist of candidate layers or a prerequisite decision artifact before implementation begins.
|
||||
|
||||
3. Story sizing is uneven in a few places.
|
||||
|
||||
- Story 2.3, Story 3.2, Story 3.3, and Story 4.2 through 4.4 may each span multiple modules, cross-layer behaviors, and regression-sensitive flows.
|
||||
- They may be larger than a single clean dev-agent session depending on the current codebase reality.
|
||||
- Recommendation: consider splitting the highest-risk stories by concrete layer set, runtime behavior, or export feature class.
|
||||
|
||||
### 🟡 Minor Concerns
|
||||
|
||||
1. Missing UX artifact increases ambiguity around interaction-parity acceptance.
|
||||
2. The document is consistent, but several stories are written from the perspective of a "map maintainer" rather than a direct end user, which weakens the user-story framing.
|
||||
3. Export remains intentionally low priority, which is fine strategically, but it means FR6 readiness is later than the rest of the plan and should be tracked as a sequencing risk.
|
||||
|
||||
### Dependency Review
|
||||
|
||||
- No explicit within-epic forward dependency violations were found.
|
||||
- No starter-template requirement exists in the architecture, so there is no missing greenfield bootstrap story.
|
||||
- The brownfield migration shape is reflected appropriately through compatibility and incremental split stories.
|
||||
- Database/entity timing rules are not relevant to this initiative and no analogous upfront persistence anti-pattern was found.
|
||||
|
||||
### Quality Review Verdict
|
||||
|
||||
The current epics and stories are workable as an implementation roadmap for an architectural migration, but they do not fully satisfy the workflow's own best-practice standard for user-value-first epics and user-facing stories. This is the main readiness defect, and it should be treated as a conscious tradeoff rather than ignored.
|
||||
|
||||
## Summary and Recommendations
|
||||
|
||||
### Overall Readiness Status
|
||||
|
||||
READY
|
||||
|
||||
### Critical Issues Requiring Immediate Action
|
||||
|
||||
1. No blocking issues remain because the user explicitly accepted the phase-based migration roadmap as a deliberate exception to the workflow's default epic-design standard.
|
||||
2. The previously identified epic/story framing issues remain documented as accepted planning debt and should be monitored during implementation.
|
||||
|
||||
### Recommended Next Steps
|
||||
|
||||
1. Proceed into sprint planning and story execution using the current phase-based roadmap.
|
||||
2. Tighten acceptance criteria opportunistically during story preparation, especially where parity or export behavior is still abstract.
|
||||
3. Identify the first low-risk SVG layer candidates before Epic 2 implementation work starts.
|
||||
4. Add a lightweight UX parity note if future implementation changes interaction behavior instead of preserving parity.
|
||||
|
||||
### Final Note
|
||||
|
||||
This assessment identified 8 issues across 3 severity categories, plus 1 scope warning about missing UX documentation. None of the PRD functional requirements are missing from the plan, and the architecture-to-epics traceability is coherent. On 2026-03-13, the user explicitly accepted the phase-driven engineering roadmap as a conscious exception to the workflow's default user-value-first epic standard. With that exception accepted, the planning set is cleared for implementation and the readiness status is marked READY.
|
||||
Loading…
Add table
Add a link
Reference in a new issue