feat(SwapTokenPositions): v2 modular rewrite + new FX pipelines

SwapTokenPositions/CHANGELOG.md

@@ -2,16 +2,44 @@
 
 All notable changes to the **SwapTokenPositions** script will be documented in this file.
 
+## [2.0.0] - 2026-04-24
+
+### Added
+
+- New staged FX pipeline with explicit origin, travel, and destination phases.
+- New FX flags: `--origin-fx`, `--travel-fx`, `--destination-fx`.
+- New timing flags: `--origin-time`, `--travel-time`, `--destination-time`, `--swap-delay`, `--destination-delay`.
+- New travel visibility flag: `--travel-mode` with values `normal` and `invisible`.
+- Preset system with `portal`, `lightning`, `shadow`, `fire`, `magic`, `transport`, and `none`.
+- `--instant` flag to force immediate swap.
+- Backward-compatibility parsing for legacy flags with deprecation warnings.
+- Modular multi-file source structure under `src/`.
+- Local build tooling (`rollup`) to generate single-file artifacts for Roll20.
+- Build banner metadata in generated output, including build timestamp.
+- Explicit same-page validation for selected tokens before swap.
+- Delayed pipeline safety checks that cancel gracefully if tokens disappear mid-sequence.
+
+### Changed
+
+- Refactored internal architecture from a monolithic file to source modules with a generated bundle.
+- Replaced the v1 mode-centric flow (`--mode` + repeated beam cycle) with a staged pipeline (`origin -> travel -> swap -> destination`) driven by stage FX and timing flags.
+
+### Deprecated
+
+- `--mode` (mapped for compatibility: `beams` -> `--preset lightning`, `transport` -> `--preset transport`)
+- `--duration` (replaced by `--swap-delay`)
+- `--beam-fx` (replaced by `--travel-fx`)
+- `--burst-fx` (replaced by `--destination-fx`)
+
 ## [1.0.0] - 2026-04-21
 
 ### Added
 
-- Complete modernization of the script architecture with a focus on maintainability.
 - Arcane-themed styled messaging for whispers and announcements.
 - Persistent state management for GM settings (saves between sessions).
 - One-time override support for duration, animation mode, and FX types.
 - New `--install-macro` command to automatically create a "SwapTokens" macro.
-- "Beams" animation mode (renamed from legacy "bounce") with customizable beam FX.
+- "Beams" and "transport" animation modes with customizable beam FX.
 - "Transport" animation mode for immediate magical relocation.
 - New `none` option for beam and burst FX to allow for silent, instantaneous swaps.
 - Strict selection validation with clear feedback on required token counts.

SwapTokenPositions/DEVELOPERS.md

@@ -0,0 +1,126 @@
+# SwapTokenPositions Developer Guide
+
+This guide is for contributors who want to edit source files and regenerate the bundled script used by Roll20.
+
+## What You Need
+
+- Node.js 20.x LTS (recommended)
+- npm (comes with Node.js)
+- Git
+- A code editor (VS Code recommended)
+
+Check your versions:
+
+```bash
+node -v
+npm -v
+git --version
+```
+
+If `node` is missing or old, install/update from the official Node.js website.
+
+## Project Layout (Important)
+
+- `src/` is the source of truth for script logic.
+- `SwapTokenPositions.js` is generated output.
+- `<version>/SwapTokenPositions.js` is also generated output for release/version tracking.
+- `script.json` controls script metadata and the versioned output folder name.
+
+Do not hand-edit generated bundle files.
+
+## First-Time Setup
+
+From the `SwapTokenPositions` directory:
+
+```bash
+npm install
+```
+
+This installs local dev dependencies (Rollup + Prettier) used by the build.
+
+## Build Commands
+
+### One-time build
+
+```bash
+npm run build
+```
+
+This bundles `src/index.js` and writes:
+
+- `SwapTokenPositions.js`
+- `<version>/SwapTokenPositions.js` (version taken from `script.json`)
+
+### Watch mode (recommended while coding)
+
+```bash
+npm run watch
+```
+
+Rebuilds automatically whenever files in `src/` change.
+
+## Typical Contributor Workflow
+
+1. Create a branch for your change.
+2. Edit code in `src/`.
+3. Run `npm run build`.
+4. Verify generated output is updated.
+5. Manually test in Roll20.
+6. Commit both source changes and generated artifacts.
+
+## Manual Roll20 Test Loop
+
+1. Run `npm run build`.
+2. Open `SwapTokenPositions.js`.
+3. Copy the full generated file.
+4. Paste into Roll20: Game Settings -> Mod (API) Scripts.
+5. Save and restart sandbox.
+6. Run smoke checks (`!swap-tokens`, `!swap-tokens --help`).
+7. Use the full checklist in `TESTING.md` for complete validation.
+
+## Updating Version Metadata
+
+If behavior changes in a release-worthy way:
+
+1. Update `script.json` version.
+2. Update `CHANGELOG.md`.
+3. Run `npm run build`.
+4. Confirm output appears in the new version folder.
+
+## Troubleshooting
+
+### `npm run build` fails
+
+- Run `npm install` again.
+- Remove `node_modules` and reinstall:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+On Windows PowerShell, use:
+
+```powershell
+Remove-Item -Recurse -Force node_modules
+Remove-Item package-lock.json
+npm install
+```
+
+### Build succeeds but Roll20 behavior is unchanged
+
+- Ensure the latest `SwapTokenPositions.js` content was pasted into Roll20.
+- Save and restart the Roll20 sandbox.
+- Confirm you are testing in the correct game.
+
+### Watch mode does not appear to rebuild
+
+- Make sure you started it from the `SwapTokenPositions` folder.
+- Save the file you edited in `src/`.
+- Stop and restart watch mode.
+
+## Notes for New Contributors
+
+- You do not need to understand Rollup internals to contribute.
+- Most changes only require editing files in `src/` and running `npm run build`.
+- If you are unsure what to test, start with `TESTING.md` baseline checks.

SwapTokenPositions/README.md

@@ -5,16 +5,39 @@
 ## Features
 
 - **Seamless Swapping**: Select exactly two tokens on the same page and run `!swap-tokens` to switch their positions.
-- **Animation Styles**:
-  - `beams`: Spawns arcane beams back and forth between the tokens before they swap.
-  - `transport`: Spawns vertical light columns and shimmer effects at both locations.
-- **Customizable FX**: Choose from a wide variety of beam and burst effects.
-- **Persistent Settings**: GMs can customize the global defaults (duration, mode, FX) and save them permanently.
+- **Staged Animation Pipeline**:
+  - `origin`: Point FX at starting positions.
+  - `travel`: Beam FX and optional travel visibility behavior.
+  - `destination`: Point FX after swap completes.
+- **Customizable FX**: Choose from a wide variety of point and beam effects.
+- **Persistent Settings**: GMs can customize staged defaults (FX, travel mode, timing/delays) and save them permanently.
 - **One-Time Overrides**: Players and GMs can use command flags to customize a single swap without changing global defaults.
 - **Styled Feedback**: Professional arcane-themed message boxes for success, errors, and settings.
 - **Macro Installation**: Automatically create a global "SwapTokens" macro for your game.
+- **Preset Support**: Includes `portal`, `lightning`, `shadow`, `fire`, `magic`, `transport`, and `none` presets.
+- **Legacy Compatibility**: Supports deprecated `--duration`, `--beam-fx`, and `--burst-fx` flags with warnings.
 
-## Commands
+## Contributor Docs
+
+This README focuses on Roll20 command usage. For contributor-oriented details, use these docs:
+
+- [DEVELOPERS.md](DEVELOPERS.md) for setup, build, watch mode, troubleshooting, and contributor workflow.
+- [TESTING.md](TESTING.md) for the manual Roll20 validation checklist.
+
+## v1 to v2 Migration Notes
+
+The v2 series keeps the same core command (`!swap-tokens`) but changes how animation is configured.
+
+- `--mode` (`beams|transport`) is still accepted as a deprecated legacy flag and maps to presets:
+  - `--mode beams` -> `--preset lightning`
+  - `--mode transport` -> `--preset transport`
+- New commands should use `--preset` and staged flags directly.
+- `--beam-fx` still works as a deprecated alias for `--travel-fx`.
+- `--burst-fx` still works as a deprecated alias for `--destination-fx`.
+- `--duration` still works as a deprecated alias for `--swap-delay`.
+- v2 explicitly rejects cross-page token pairs.
+
+## Roll20 VTT Commands
 
 ### Basic Usage
 
@@ -23,31 +46,48 @@ Swaps the two currently selected tokens using the default settings.
 
 ### Acceptable Parameters for Customization (Available to Everyone)
 
-- `--duration <1-10>`: Seconds to play the animation before swapping.
-- `--mode <value>`: The animation style to use.
-  - Values: `beams`, `transport`
-- `--beam-fx <value>`: The beam FX type.
-  - Values: `none`, `beam-magic`, `beam-acid`, `beam-charm`, `beam-fire`, `beam-frost`, `beam-holy`, `beam-death`
-- `--burst-fx <value>`: The burst FX type.
-  - Values: `none`, `burst-holy`, `burst-magic`, `burst-fire`, `burst-acid`, `burst-frost`, `burst-smoke`, `explode-fire`, `explode-holy`, `burn-fire`, `burn-holy`
+- `--help`: Displays the help menu.
+- `--instant`: Skips all FX and timing and swaps immediately.
+- `--preset <value>`: Applies a preset.
+  - Values: `portal`, `lightning`, `shadow`, `fire`, `magic`, `transport`, `none`
+- `--origin-fx <value>`: Point FX at both origin positions.
+- `--travel-fx <value>`: Beam FX between positions during travel stage.
+- `--destination-fx <value>`: Point FX at both destination positions.
+- `--travel-mode <value>`: Visibility behavior during travel stage.
+  - Values: `normal`, `invisible`
+- `--origin-time <0-10>`: Seconds to wait after origin FX.
+- `--travel-time <0-10>`: Duration in seconds for the travel animation stage.
+- `--destination-time <0-10>`: Additional wait before destination FX is shown.
+- `--swap-delay <0-10>`: Extra delay between origin and travel stages.
+- `--destination-delay <0-10>`: Extra delay before destination FX is shown.
 
 ### Examples of Customization
 
-- `!swap-tokens --mode transport` Shows the tokens swapping using a Roll20 version of the transport FX.
-- `!swap-tokens --mode beams` Shows the tokens swapping using the beams FX.
-- `!swap-tokens --duration 5 --beam-fx beam-fire --mode beams` Shows the tokens swapping using the beams FX for 5 seconds with fire beams.
-- `!swap-tokens --duration 2 --beam-fx beam-acid --mode beams` Shows the tokens swapping using the beams FX for 2 seconds with acid beams.
-- `!swap-tokens --duration 10 --burst-fx burst-magic --mode transport` Shows the tokens swapping using a Roll20 version of the transport FX for 10 seconds with magic burst FX.
-- `!swap-tokens --duration 3 --burst-fx explode-fire --mode transport` Shows the tokens swapping using a Roll20 version of the transport FX for 3 seconds with fire explode FX.
-- `!swap-tokens --beam-fx none --burst-fx none` Swaps the two currently selected tokens without using any animation effects.
+- `!swap-tokens --preset portal` Applies the portal preset for one swap.
+- `!swap-tokens --preset transport` Applies a Star Trek-style transporter shimmer preset with hidden travel.
+- `!swap-tokens --preset transport --travel-mode normal` Uses transport visuals but keeps tokens visible during travel.
+- `!swap-tokens --preset lightning --travel-time 1` Applies lightning preset with explicit travel timing override.
+- `!swap-tokens --origin-fx nova-magic --travel-fx beam-fire --destination-fx explode-fire` Uses custom FX for each stage.
+- `!swap-tokens --origin-time 1 --swap-delay 0.5 --destination-delay 1` Uses explicit stage timing.
+- `!swap-tokens --instant` Swaps immediately regardless of saved defaults.
+- `!swap-tokens --beam-fx beam-fire --duration 2` Uses deprecated flags (still supported) and shows deprecation notices.
 
 ### Global Configuration (GM Only)
 
-- `--save`: Commits any provided customization flags as the new global defaults. You must provide the customization flags you want to save, for example, just `--save --duration 5` will save the duration as the new default and keep the beam effect and swap mode as they are.
+- `--save`: Commits provided customization flags as the new global defaults.
 - `--show-settings`: Displays the current persistent defaults in chat.
+- `--check-settings`: Validates current persistent defaults and reports issues.
 - `--reset-settings`: Restores the script to its factory defaults.
 - `--install-macro`: Automatically creates a global "SwapTokens" macro in your campaign.
-- `--help`: Displays the help menu.
+
+### Deprecated Flags
+
+The following flags are still supported for backward compatibility but are deprecated:
+
+- `--mode` (use `--preset`; `beams` maps to `lightning`, `transport` maps to `transport`)
+- `--duration` (use `--swap-delay`)
+- `--beam-fx` (use `--travel-fx`)
+- `--burst-fx` (use `--destination-fx`)
 
 ## License