1.0 → 2.0 Scroll State Migration

This article documents the 1.0 → 2.0 Scroll State Migration feature, released in Tiled v58.0.0. With the Scroll States MVP now available in Builder 2.0, existing microapps that were built in Builder 1.0 and contain scroll states or scroll tiles can be migrated through an assisted migration flow that maps 1.0 scroll configurations to their Builder 2.0 equivalents.

Scope: Tiled Library Administrators and Editors managing existing 1.0 microapps that use scroll states or scroll tiles. The migration is available when converting a 1.0 microapp to Builder 2.0.

2. Control Objective

The control objective is to ensure that scroll state configurations defined in Builder 1.0 are faithfully translated to their Builder 2.0 equivalents during conversion, preserving content structure, scroll offsets, and navigation behavior without requiring manual recreation.

3. What the Migration Does

When a Builder 1.0 microapp containing scroll states is converted to Builder 2.0, the assisted migration flow performs the following:

4. Pre-Migration Requirements

Before initiating migration, complete the following to establish a safe rollback baseline:

15. Identify all scroll states in the 1.0 microapp — record their names and approximate offsets.

16. Note all click events that target scroll states — source tile and target state name.

17. Capture screenshots of the microapp in Preview and Viewer as a visual reference.

18. Duplicate the original 1.0 microapp before converting — retain it as a rollback copy.

5. Migration Procedure

19. Open the 1.0 microapp in the Tiled Library.

20. Select Convert to Builder 2.0 from the microapp actions menu.

21. Confirm the conversion. The migration flow will run automatically.

22. Review the migration summary presented after conversion — note any states flagged for manual review.

23. Open the converted microapp in Builder 2.0 and open the Scroll States panel.

24. Verify all expected scroll states are listed with the correct names and offsets.

25. Check all click events that previously targeted scroll states — confirm retargeting is correct.

6. Post-Migration Validation

6.1 Structure Validation

26. Confirm all pages are present in the converted microapp.

27. Confirm all scroll states are present in the Scroll States panel with correct names and offsets.

28. Confirm all scroll containers (formerly scroll tiles) are present with correct content and scroll direction.

29. Confirm all click events targeting scroll states reference the correct 2.0 state names.

6.2 Behavior Validation

30. Preview the converted microapp. Scroll through all pages with scroll states and verify activation at expected positions.

31. Trigger all click events that navigate to scroll states. Verify navigation lands at the correct state.

32. Open in the Viewer and repeat behavior validation.

33. Share via Share Link and repeat behavior validation in the shared view.

34. Compare screenshots against pre-migration captures — flag any visual regressions.

7. Handling Migration Gaps

If the migration summary flags states requiring manual review, or if post-migration validation reveals missing or incorrect states:

35. Document the gap: which state, what the expected vs. actual behavior is.

36. Manually create or adjust the scroll state in Builder 2.0 to match the intended behavior.

37. If the gap is significant or reproducible, file a Jira ticket for the engineering team.

38. Do not delete the 1.0 duplicate until all gaps are resolved and the converted microapp is validated.

• The 1.0 duplicate retained before migration is a data integrity control artifact confirming a rollback path existed throughout the conversion.

• The migration summary report constitutes a change record for SOC 2 CC8.1 (Change Management) — documenting what scroll states were migrated and what (if any) required manual intervention.