Merge branch 'v3-dev'

# Conflicts:
#	.github/workflows/update-ucm-catalog.yml
#	.gitignore
#	community_presets/catalog.json
#	ucm_presets/catalog.json

Author: FitzDegenhub

.gitattributes

@@ -0,0 +1,3 @@
+# Force LF line endings for preset files so SHA256 hashes match across platforms
+ucm_presets/*.ucmpreset text eol=lf
+ucm_presets/catalog.json text eol=lf

.github/workflows/update-ucm-catalog.yml

@@ -2,6 +2,7 @@ name: Update preset catalogs
 
 on:
   push:
+    branches: [main]
     paths:
       - 'ucm_presets/*.ucmpreset'
       - 'community_presets/*.ucmpreset'
@@ -93,17 +94,19 @@ jobs:
               print(f"{catalog_path}: {len(presets)} presets")
 
           # UCM presets (style definitions only)
-          generate_catalog("ucm_presets", "ucm_presets/catalog.json", kind_filter="style")
+          if os.path.isdir("ucm_presets"):
+              generate_catalog("ucm_presets", "ucm_presets/catalog.json", kind_filter="style")
 
           # Community presets (all presets)
-          generate_catalog("community_presets", "community_presets/catalog.json")
+          if os.path.isdir("community_presets"):
+              generate_catalog("community_presets", "community_presets/catalog.json")
           SCRIPT
 
       - name: Commit updated catalogs
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add ucm_presets/catalog.json community_presets/catalog.json
+          git add ucm_presets/catalog.json community_presets/catalog.json 2>/dev/null || true
           if git diff --cached --quiet; then
             echo "No changes to catalogs"
           else

.gitignore

@@ -13,19 +13,20 @@ release/
 *.suo
 *.csproj.user
 
-# Claude Code worktrees
+# Local-only worktree under src (do not commit)
 src/.claude/
 
 # Runtime data
 backups/
 custom_presets/
 advanced_presets/
 ucm_presets/
-# Re-include repo-level preset folders (official definitions + community presets for GitHub download)
+# Re-include the repo-level ucm_presets/ folder (official preset definitions for GitHub download)
 !/ucm_presets/
+my_presets/
 community_presets/
+# Re-include the repo-level community_presets/ folder (community presets for GitHub download)
 !/community_presets/
-my_presets/
 import_presets/
 imported_presets/
 presets/
@@ -34,6 +35,7 @@ advanced_overrides.json
 window_state.json
 u3_draft_slot.json
 crash.log
+tutorial_done.flag
 debug/
 *.marker
 

CHANGELOG.md

@@ -0,0 +1,191 @@
+# Changelog
+
+All notable changes to Ultimate Camera Mod are documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/). Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [v3.1] - 2026-04-05
+
+### Camera
+- **Lock-on auto-rotate toggle** - New checkbox in UCM Quick to disable camera snap-to-target when locking on. Prevents the camera from whipping around to face a target behind you. Discovered by [sillib1980](https://github.com/sillib1980). Sets `IsAutoRotate` and `IsTargetFixed` on lock-on camera sections.
+
+### God Mode
+- **Sacred God Mode overrides** - Values you edit in God Mode are now permanently protected from Quick/Fine Tune rebuilds. The camera rule engine skips any field you've explicitly touched. Your values stay exactly where you put them, no matter what happens in Quick or Fine Tune. Addresses issues #18, #20.
+- **Green sacred indicators** - Sacred values show in green in the God Mode grid (white = vanilla, gold = rules-modified, green = sacred/protected). Row count shows sacred count.
+- **"Sacred only" filter** - New filter option in God Mode dropdown to show only your protected values.
+- **Fine Tune slider locking** - Fine Tune sliders that control sacred God Mode values are greyed out with a green label and tooltip "Sacred -- controlled by God Mode".
+- **One-time sacred toast** - First God Mode edit on a managed preset shows a status message explaining the value is protected.
+
+### UI
+- **Version-aware upgrade overlay** - Existing users upgrading between versions (e.g. v3.0.2 to v3.1) now see a "What's new" overlay on first launch. Previously only triggered for users without tutorial_done.flag.
+
+### Bug Fixes
+- **Full Manual Control presets not installing edits** - Install was using the original vanilla XML from preset creation instead of rebuilding from current God Mode edits. God Mode changes on Full Manual Control presets now work correctly.
+- **God Mode overrides file polluted with CameraRules values** - `advanced_overrides.json` previously saved ALL values that differed from vanilla, including values set by CameraRules (not the user). Now only saves values the user explicitly edited.
+- **Fresh install showing upgrade overlay** - Startup created files (backups, preset dirs) before the fresh-install check ran, so it always detected "existing data". Detection now runs before any file creation.
+
+---
+
+## [v3.0.2] - 2026-04-04
+
+### UI
+- **In-app overlay dialogs** - All dialogs converted from Windows popups to themed in-app overlays (gold-bordered dark cards). X close button on all overlays (except fatal errors). No more Windows-style popups anywhere.
+- **Preset type selection** - New preset dialog with "Managed by UCM" and "Full Manual Control" cards. Feature tags show what's enabled (green ticks/red crosses). OR divider between options.
+- **Import type picker** - Cards with hover highlight instead of plain buttons.
+- **Import metadata dialog** - Textboxes enlarged (54px, 18px font, white text on dark background) for readability.
+- **Export dialog** - Removed redundant description under header. Auto-populates name, author, description, URL from active preset.
+- **Browse catalog cards** - Description/tags on left, Download/Nexus buttons on right.
+- **Game Default sidebar group** - Vanilla preset separated from UCM presets.
+- **Height slider** range extended to -1.6/1.5.
+- **Preset author text** enlarged in the active preset header.
+- **God Mode columns** - Fixed squished columns on first load with double-bind workaround.
+- **Camera preview** - Now updates immediately when switching presets.
+- **Error messages** - All major errors rewritten with clear, actionable guidance as overlay popups.
+- **First-run welcome overlay** - Verification prompt before tutorial. "No, close UCM" shuts down app.
+- **Game update warning** - Shows as overlay with Snooze/Dismiss instead of bottom strip.
+- **Fatal error overlay** - Unclosable overlay with "Close UCM" for critical errors (tainted backup, etc.).
+
+### Presets
+- **God Mode overrides persist across tabs** - Edits saved to `advanced_overrides.json` and re-applied when Quick/Fine Tune rebuilds. No more losing God Mode tweaks.
+- **Duplicate God Mode conversion** - When duplicating a God Mode preset, choose "Keep God Mode" or "Convert to UCM Managed" with warning about value changes.
+- **Raw XML import separation** - Imported XML/PAZ/mod manager presets are standalone with no UCM rules. Only God Mode editing available.
+- **Export writes `preset_mode`** - Exported .ucmpreset files preserve whether they're UCM managed or God Mode only.
+- **UCM presets can be deleted locally** - Re-download from catalog anytime. Rename still blocked.
+- **Community preset duplicates go to My Presets** - Instead of staying in the community_presets folder.
+
+### Catalog
+- **Community presets moved to main repo** - From separate `ucm-community-presets` repo to `community_presets/` folder. Single unified GitHub Actions workflow for both catalogs.
+- **New community presets** - Shoulder Camera (latranchedepain), Proper 3rd Person Camera (orangeees).
+- **All catalog URLs point to main branch** - Long-term stability.
+- **Workflow preserves existing SHAs** - Adding a new preset no longer changes SHAs of unchanged presets. No more false update icons.
+- **Raw byte downloads** - Both Browse and Update write raw bytes to preserve SHA hash for update detection.
+
+### Camera
+- **Game crash fix** - Removed Player_Interaction_LockOn and Interaction_LookAt from LockOnSections (modifying these NPC dialogue sections crashed the game).
+- **Game crash fix** - Removed unsafe byte-replacement fallback in ArchiveWriter that produced invalid XML.
+- **Vanilla validation relaxed** - June 2026 game patch added MaxZoomDistance=30 and XML comments to vanilla. Checks updated to only flag UCM-specific signatures.
+- **Auto-fix tainted backups** - Automatically deletes tainted backup AND 0.paz when validation fails. Steam verify alone doesn't restore modded files.
+- **God Mode attribute tooltips** - 54 attributes documented (up from 29). Covers interaction, blend, zoom, damping, and targeting.
+
+### Documentation
+- **Wiki** - 21 pages (11 user guide + 10 developer) published to GitHub Wiki tab with sidebar navigation.
+
+### Bug Fixes
+- **HShift slider staying gold on locked presets** - `ApplyCenteredLock` was re-enabling after lock.
+- **Community preset "View on Nexus" link not showing** - URL field past 4KB header. Fixed by ordering metadata before session_xml.
+- **Community preset update SHA mismatch** - Updates write raw bytes instead of re-serializing.
+- **False update icons after downloading** - Raw byte downloads preserve SHA hash.
+- **PAZ import from different game version** - Shows helpful overlay explaining PAMT version mismatch.
+- **Export missing `preset_mode`** - Exported files now include the correct mode tag.
+- **Vanilla validation false positive after game patch** - Relaxed checks for new vanilla values.
+
+---
+
+## [v3.0.1] - 2026-04-03
+
+### Added
+- **UCM preset catalog browser** - UCM style presets downloaded on demand via Browse button. Official presets hosted on v3-dev branch with auto-generated `catalog.json`.
+- **Preset update detection** - Background catalog check compares revision numbers. Outdated presets show update icon in sidebar. Update prompt offers to duplicate old version before downloading.
+- **Game Default sidebar group** - Vanilla preset separated into its own group.
+- **Community and UCM update detection** - SHA256 comparison against GitHub catalogs with pulsating update icons.
+- **Browse catalog redesign** - Cleaner card layout with description/tags on the left, Download and Nexus link buttons on the right.
+
+### Changed
+- **Style IDs renamed** - Old cryptic IDs (`western`, `cinematic`, `immersive`, `lowcam`, `vlowcam`, `ulowcam`, `re2`) replaced with self-documenting names (`heroic`, `panoramic`, `close-up`, `low-rider`, `knee-cam`, `dirt-cam`, `survival`).
+- **Definition-based UCM presets** - Presets stored as style definitions (style_id + settings), session XML baked locally from game files + current CameraRules.
+- **UCM Quick layout** - Custom Offsets and Global Settings side-by-side at top, camera previews side-by-side below.
+- **God Mode SECTION column** - Auto-stretches to fit window width.
+- **Live camera preview** - Shows selected preset name.
+- **Height slider** - Range extended to -1.6/1.5.
+
+### Fixed
+- **Game crash on load** - Removed `Player_Interaction_LockOn` and `Interaction_LookAt` from LockOnSections (modifying NPC dialogue camera sections caused crash).
+- **Game crash on load** - Removed unsafe byte-replacement fallback in ArchiveWriter that produced invalid XML.
+- **Session XML corruption** - Removed `JavaScriptEncoder.UnsafeRelaxedJsonEscaping` from preset serialization.
+- **Camera preview and FoV** - Now update immediately when switching presets.
+- **Community preset "View on Nexus" link** - No longer disappears after update.
+- **False update icons** - No longer show on all presets after download.
+- **Locked preset toast** - Now appears on Fine Tune and God Mode tabs.
+- **Steadycam tooltip** - Now shows on disabled sliders.
+
+---
+
+## [v3.0.0] - 2026-04-03
+
+### Added
+- **Export-first workflow** - Tune camera in-app, export as JSON patch for mod managers. Direct PAZ install still available as secondary option.
+- **Three-tier editor** - UCM Quick (fast sliders), Fine Tune (curated deep control), God Mode (full raw XML editor with vanilla comparison).
+- **`.ucmpreset` file format** - Dedicated shareable preset files.
+- **Sidebar preset manager** - Collapsible grouped sections: Game Default, UCM Presets, Community Presets, My Presets, Imported.
+- **Multi-format export** - JSON (Mod Manager), XML, 0.paz, .ucmpreset with metadata fields.
+- **Community preset catalog** - Browse and download presets from GitHub directly in-app.
+- **Preset lock system** - UCM presets permanently locked, user presets toggleable via padlock icon.
+- **True Vanilla preset** - Decoded directly from game backup with no modifications.
+- **Lock-on zoom slider** - Replaces combat camera dropdown (-60% to +60%).
+- **Steadycam expanded** - 30+ camera states smoothed, individually tunable in Fine Tune.
+- **Lock-on distance scaling** - ZoomDistance values scale dynamically with chosen camera distance.
+- **Live camera + FoV preview** - Distance-aware top-down view with FoV cone.
+- **Game patch awareness** - Tracks install metadata, warns when game may have updated.
+- **Auto-save** - Changes to unlocked presets write back to file automatically.
+- **Auto-migration** - Legacy `.json` presets migrated to `.ucmpreset` on first launch.
+
+### Changed
+- **Value-edits only** - Removed structural XML injection from v2 (extra zoom levels, horse first-person, horse camera overhaul). Modifies only existing values for safer sharing across game patches.
+
+---
+
+## [v2.5] - 2026-03-31
+
+### Fixed
+- **European locale camera values** - `InvariantCulture` forced for all number formatting so decimal separators are always periods regardless of Windows locale.
+
+---
+
+## [v2.4] - 2026-03-31
+
+Incremental improvements and tuning.
+
+---
+
+## [v2.3] - 2026-03-31
+
+Incremental improvements and tuning.
+
+---
+
+## [v2.2] - 2026-03-31
+
+### Added
+- Steadycam system
+- Extra zoom levels
+- Horse first person mode
+- Horizontal shift control
+- Universal FoV
+- Skill aiming consistency
+- Import XML support
+- Preset sharing
+- Update notifications
+
+---
+
+## [v2.1] - 2026-03-30
+
+### Added
+- Advanced editor with full XML parameter control
+- Export/import preset strings (`UCM:` and `UCM_ADV:` formats)
+
+---
+
+## [v2.0] - 2026-03-30
+
+### Changed
+- Complete rewrite from Python to C# WPF application
+- Single-file `.exe`, no installer required
+
+---
+
+## [v1.5] - 2026-03-30
+
+Initial public release (Python version).

CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing to Ultimate Camera Mod
+
+Thanks for wanting to help build `Ultimate Camera Mod` for `Crimson Desert`.
+
+This project is still evolving quickly, and outside contributors are very welcome. Camera behavior, XML coverage, UI polish, preset tuning, archive tooling, and regression testing all benefit from extra hands.
+
+## Ways To Help
+
+- Fix bugs in camera install, restore, preset handling, and XML editing.
+- Improve camera tuning for on-foot, horse, combat, aim, and special mounts.
+- Improve `UCM Quick`, `Fine Tune`, and `God Mode` UX.
+- Add missing parameter coverage where vanilla camera states are not yet exposed cleanly.
+- Improve export/import support for external mod workflows.
+- Improve docs, setup instructions, and troubleshooting.
+
+## Before You Start
+
+- Open an issue or discussion if you want to work on a larger change.
+- For small fixes, a PR is fine without prior discussion.
+- If your change affects live game file writes, camera state mapping, or preset compatibility, please describe the expected before/after behavior clearly.
+
+## Project Layout
+
+- `src/UltimateCameraMod/` - shared core logic, camera rules, archive tooling, legacy app
+- `src/UltimateCameraMod.V3/` - current V3 WPF app
+- `Additional Resources/` - reference files, mod manager docs, sample assets
+
+## Local Setup
+
+Requires:
+
+- Windows
+- .NET 6 SDK or later
+
+Build V3:
+
+```powershell
+dotnet build "src/UltimateCameraMod.V3/UltimateCameraMod.V3.csproj" -c Release
+```
+
+Run V3:
+
+```powershell
+dotnet run --project "src/UltimateCameraMod.V3/UltimateCameraMod.V3.csproj"
+```
+
+Build the legacy app:
+
+```powershell
+dotnet build "src/UltimateCameraMod/UltimateCameraMod.csproj" -c Release
+```
+
+Important on Windows: if `UltimateCameraMod.V3.exe` is already running, stop it before rebuilding or MSBuild may fail to replace the executable.
+
+```powershell
+Stop-Process -Name "UltimateCameraMod.V3" -Force -ErrorAction SilentlyContinue
+```
+
+## Development Guidelines
+
+- Keep behavior aligned with vanilla where the mod is meant to preserve original state coverage.
+- Avoid injecting non-vanilla camera states unless that is an intentional feature and clearly documented.
+- Prefer fixing shared logic in `src/UltimateCameraMod/` when V3 and the legacy app depend on the same code.
+- Be careful with generated/runtime files under `bin/Release/...`; they should not drive source-of-truth behavior.
+- Keep number formatting invariant for XML and patch output.
+- Avoid committing temporary diagnostics, extracted XML dumps, local traces, or personal test files.
+
+## Testing Expectations
+
+There is currently no deep automated test suite for the full camera pipeline, so manual verification matters.
+
+For changes that affect installs, presets, or XML generation, please verify as many of these as possible:
+
+- Build succeeds in `Release`
+- App launches successfully
+- Install to game works
+- Restore vanilla works
+- Presets save and reload correctly
+- Quick, Fine Tune, and God Mode stay in sync where expected
+- No extra non-vanilla zoom levels or camera states are unintentionally injected
+- Horse, combat, and aim behavior still feel correct in-game
+
+If you cannot test against the game directly, say so in the PR.
+
+## Pull Requests
+
+Please keep PRs focused.
+
+Good PRs usually include:
+
+- a short summary of the problem
+- what changed
+- any risk areas
+- a quick manual test plan
+
+If the change touches camera tuning, screenshots, XML snippets, or a short gameplay note are helpful.
+
+## Good First Contribution Areas
+
+- Fine Tune / God Mode parameter coverage
+- camera rule cleanup and parity fixes
+- preset generation and migration bugs
+- install/restore diagnostics and error handling
+- docs and onboarding improvements
+
+## Questions
+
+If you are unsure where to contribute, open an issue or discussion and describe:
+
+- what you want to improve
+- whether it is code, tuning, UI, or documentation
+- whether you can test in-game
+
+That is enough to get started.