FieldwrightModSystem.cs

using System;
using System.Collections.Generic;
using Vintagestory.API.Client;
using Vintagestory.API.Common;
using Vintagestory.API.Common.CommandAbbr;
using Vintagestory.API.MathTools;
using Vintagestory.API.Util;

[assembly: ModInfo("Fieldwright", "fieldwright",
    Authors = new string[] { "Venah" },
    Description = "A surveyor's pocket aid for builders. Client-side personal blueprint mod with anchor-snap paste.",
    Version = "0.1.5")]

namespace Fieldwright;

public class FieldwrightModSystem : ModSystem
{
    private const string Component = "mod-system";
    private const string HotkeyCorner1 = "fieldwright-corner1";
    private const string HotkeyCorner2 = "fieldwright-corner2";
    private const string HotkeyPlace = "fieldwright-place";
    private const string HotkeyMirror = "fieldwright-mirror";
    private const string HotkeyLayerUp = "fieldwright-layer-up";
    private const string HotkeyLayerDown = "fieldwright-layer-down";
    private const string HotkeyLibrary = "fieldwright-library";
    private const string HotkeyCancel = "fieldwright-cancel";

    // HighlightBlocks slot IDs. Arbitrary but must be stable per mod so we can clear them.
    private const int HighlightSlotBox = 8501;
    private const int HighlightSlotAnchor = 8502;

    private SelectionState selection = new SelectionState();
    private ICoreClientAPI? capi;
    private FieldwrightConfig config = new FieldwrightConfig();

    // Active paste state, null when nothing is being pasted.
    private GhostMesh? activeGhostMesh;
    private GhostRenderer? activeGhostRenderer;
    private string? activeGhostName;
    private BlockSchematic? activeSchematic;
    private Vec3i activeAnchorOffset = new Vec3i(0, 0, 0);

    /// <summary>
    /// Matching mode chosen at .fw paste time. Defaults to config.DefaultMatchingMode; the
    /// paste command can override per-blueprint. Used by SpinUpTracking when constructing
    /// the tracker (which captures the mode for the lifetime of that ghost).
    /// </summary>
    private MatchingMode activeMatchingMode = MatchingMode.Loose;

    // Phase 3a: match tracker + checklist views created on .fw place, disposed on
    // cancel / unlock. Two view surfaces: the always-on HUD (transparent overlay, no
    // cursor grab) and the modal dialog (movable, scrollable, copyable). Ctrl+Shift+L
    // cycles: HUD -> Modal -> Hidden -> HUD.
    private GhostMatchTracker? activeMatchTracker;
    private GhostChecklistHud? activeChecklistHud;
    private GhostChecklistDialog? activeChecklistDialog;
    private enum ChecklistView { Hud = 0, Modal = 1, Hidden = 2 }
    private ChecklistView checklistView = ChecklistView.Hud;

    // Auto-dismiss timer: ghost + HUD auto-clear N ms after the structure first
    // becomes fully matched. Re-arms if the player breaks a block (uncompleting it).
    // Phase 4 will swap this for a chisel-pass toggle so users can keep the base
    // ghost visible while annotating chisel positions.
    private long completionTickListenerId = -1;
    private long completionDetectedAtMs = 0;
    private bool completionDismissNotified = false;

    public override bool ShouldLoad(EnumAppSide side) => side == EnumAppSide.Client;

    public override void StartClientSide(ICoreClientAPI api)
    {
        capi = api;
        FieldwrightLogger.Info(api, Component, "loading Fieldwright v0.1.5");

        config = FieldwrightConfig.Load(api);
        activeMatchingMode = config.DefaultMatchingMode;

        RegisterHotkeys(api);
        RegisterCommands(api);

        FieldwrightLogger.Info(api, Component,
            $"ready, blueprints directory: {BlueprintStore.GetBlueprintsDirectory(api)}");
    }

    private void RegisterHotkeys(ICoreClientAPI api)
    {
        api.Input.RegisterHotKey(HotkeyCorner1, FieldwrightLang.Get("hotkey.corner1"),
            GlKeys.B, HotkeyType.CharacterControls, ctrlPressed: true, shiftPressed: true);
        api.Input.SetHotKeyHandler(HotkeyCorner1, _ => HandleCornerHotkey(corner: 1));

        api.Input.RegisterHotKey(HotkeyCorner2, FieldwrightLang.Get("hotkey.corner2"),
            GlKeys.N, HotkeyType.CharacterControls, ctrlPressed: true, shiftPressed: true);
        api.Input.SetHotKeyHandler(HotkeyCorner2, _ => HandleCornerHotkey(corner: 2));

        api.Input.RegisterHotKey(HotkeyPlace, FieldwrightLang.Get("hotkey.place"),
            GlKeys.P, HotkeyType.CharacterControls, ctrlPressed: true, shiftPressed: true);
        api.Input.SetHotKeyHandler(HotkeyPlace, _ => { ToggleGhostPlacement(); return true; });

        api.Input.RegisterHotKey(HotkeyMirror, FieldwrightLang.Get("hotkey.mirror"),
            GlKeys.M, HotkeyType.CharacterControls, ctrlPressed: true, shiftPressed: true);
        api.Input.SetHotKeyHandler(HotkeyMirror, _ => { CycleGhostMirror(); return true; });

        // Layer-by-layer view. PgDn peels the top layer off the ghost, PgUp adds it back.
        // No modifiers, pure PgDn / PgUp because nothing else in Fieldwright uses them.
        api.Input.RegisterHotKey(HotkeyLayerDown, FieldwrightLang.Get("hotkey.layer-down"),
            GlKeys.PageDown, HotkeyType.CharacterControls);
        api.Input.SetHotKeyHandler(HotkeyLayerDown, _ => { AdjustGhostLayer(decrease: true); return true; });

        api.Input.RegisterHotKey(HotkeyLayerUp, FieldwrightLang.Get("hotkey.layer-up"),
            GlKeys.PageUp, HotkeyType.CharacterControls);
        api.Input.SetHotKeyHandler(HotkeyLayerUp, _ => { AdjustGhostLayer(decrease: false); return true; });

        api.Input.RegisterHotKey(HotkeyLibrary, FieldwrightLang.Get("hotkey.library"),
            GlKeys.K, HotkeyType.CharacterControls, ctrlPressed: true, shiftPressed: true);
        api.Input.SetHotKeyHandler(HotkeyLibrary, _ => { ToggleLibraryDialog(); return true; });

        api.Input.RegisterHotKey(HotkeyCancel, FieldwrightLang.Get("hotkey.cancel"),
            GlKeys.X, HotkeyType.CharacterControls, ctrlPressed: true, shiftPressed: true);
        api.Input.SetHotKeyHandler(HotkeyCancel, _ =>
        {
            var (msg, _) = CancelAll();
            capi?.ShowChatMessage(msg);
            return true;
        });

        // Checklist view cycle: HUD -> Modal -> Hidden -> HUD. The HUD doesn't grab
        // the cursor (transparent always-on); the modal does (movable / scrollable /
        // copyable). Hidden leaves nothing on screen.
        api.Input.RegisterHotKey("fieldwright-checklist-toggle", FieldwrightLang.Get("hotkey.checklist-toggle"),
            GlKeys.L, HotkeyType.CharacterControls, ctrlPressed: true, shiftPressed: true);
        api.Input.SetHotKeyHandler("fieldwright-checklist-toggle", _ => { CycleChecklistView(); return true; });

        FieldwrightLogger.Info(api, Component,
            "registered hotkeys Ctrl+Shift+B (corner1+anchor), Ctrl+Shift+N (corner2), Ctrl+Shift+P (place), " +
            "Ctrl+Shift+M (mirror), Ctrl+Shift+X (cancel), PgUp/PgDn (ghost layer view), Ctrl+Shift+K (library)");
    }

    private bool HandleCornerHotkey(int corner)
    {
        if (capi == null) return false;

        var sel = capi.World.Player?.CurrentBlockSelection;
        if (sel?.Position == null)
        {
            capi.ShowChatMessage(FieldwrightLang.Chat("chat.no-block-under-crosshair", corner));
            return true;
        }

        SetCorner(corner, sel.Position, sel.Face);
        return true;
    }

    private void SetCorner(int corner, BlockPos pos, BlockFacing? face)
    {
        if (capi == null) return;

        if (corner == 1)
        {
            selection.SetCorner1(pos, face);
            var faceNote = face == null
                ? string.Empty
                : (face.IsHorizontal
                    ? FieldwrightLang.Get("chat.corner1-face-note-horizontal", FieldwrightLang.Facing(face.Code))
                    : FieldwrightLang.Get("chat.corner1-face-note-vertical", FieldwrightLang.Facing(face.Code)));
            capi.ShowChatMessage(FieldwrightLang.Chat("chat.corner1-set", FormatPos(pos), faceNote));
        }
        else
        {
            selection.SetCorner2(pos);
            capi.ShowChatMessage(FieldwrightLang.Chat("chat.corner2-set", FormatPos(pos)));
        }

        UpdateHighlight();
        EchoSelectionSize();

        FieldwrightLogger.Debug(capi, Component, $"corner{corner} = {FormatPos(pos)}, face={face?.Code ?? "none"}");
    }

    private void EchoSelectionSize()
    {
        if (capi == null || !selection.HasSelection) return;

        var (dx, dy, dz) = selection.GetDimensions();
        var heightHint = dy == 1
            ? FieldwrightLang.Get("chat.selection-height-hint")
            : string.Empty;
        capi.ShowChatMessage(
            FieldwrightLang.Chat("chat.selection-size", dx, dy, dz, dx * dy * dz, FormatPos(selection.Anchor!), heightHint));
    }

    private const int MaxHighlightCells = 65536;

    private void UpdateHighlight()
    {
        if (capi == null) return;

        if (!selection.HasSelection)
        {
            ClearHighlight();
            return;
        }

        var min = selection.Min!;
        var max = selection.Max!;
        var anchor = selection.Anchor!;

        int width = max.X - min.X + 1;
        int height = max.Y - min.Y + 1;
        int depth = max.Z - min.Z + 1;
        long total = (long)width * height * depth;

        if (total > MaxHighlightCells)
        {
            // Too many cells to paint individually without lagging the engine.
            // Fall back to face-only highlight: only the 6 outer faces of the cuboid.
            HighlightFacesOnly(min, max, anchor);
            FieldwrightLogger.Debug(capi, Component,
                $"selection {width}×{height}×{depth}={total} > {MaxHighlightCells}, using face-only highlight");
            return;
        }

        // Paint every cell in the cuboid translucent green. Anchor block gets a brighter
        // tint so the placement reference stays visible. One slot for everything so
        // the engine only re-uploads one mesh per change.
        var positions = new List<BlockPos>((int)total);
        var colors = new List<int>((int)total);
        int boxColor = ColorUtil.ColorFromRgba(80, 200, 100, 60);     // R, G, B, A
        int anchorColor = ColorUtil.ColorFromRgba(50, 255, 220, 200); // anchor accent

        for (int x = min.X; x <= max.X; x++)
        {
            for (int y = min.Y; y <= max.Y; y++)
            {
                for (int z = min.Z; z <= max.Z; z++)
                {
                    var p = new BlockPos(x, y, z, min.dimension);
                    positions.Add(p);
                    colors.Add(p.X == anchor.X && p.Y == anchor.Y && p.Z == anchor.Z ? anchorColor : boxColor);
                }
            }
        }

        capi.World.HighlightBlocks(
            capi.World.Player, HighlightSlotBox,
            positions, colors,
            EnumHighlightBlocksMode.Absolute, EnumHighlightShape.Arbitrary);

        // HighlightSlotAnchor unused in fill mode; clear in case it was set previously.
        capi.World.HighlightBlocks(capi.World.Player, HighlightSlotAnchor,
            new List<BlockPos>(),
            EnumHighlightBlocksMode.Absolute, EnumHighlightShape.Arbitrary);
    }

    private void HighlightFacesOnly(BlockPos min, BlockPos max, BlockPos anchor)
    {
        if (capi == null) return;

        var positions = new List<BlockPos>();
        var colors = new List<int>();
        int boxColor = ColorUtil.ColorFromRgba(80, 200, 100, 90);
        int anchorColor = ColorUtil.ColorFromRgba(50, 255, 220, 200);

        // Add every cell on the 6 outer faces of the cuboid (with edge dedup).
        for (int x = min.X; x <= max.X; x++)
        {
            for (int y = min.Y; y <= max.Y; y++)
            {
                for (int z = min.Z; z <= max.Z; z++)
                {
                    bool onFace =
                        x == min.X || x == max.X ||
                        y == min.Y || y == max.Y ||
                        z == min.Z || z == max.Z;
                    if (!onFace) continue;

                    var p = new BlockPos(x, y, z, min.dimension);
                    positions.Add(p);
                    colors.Add(p.X == anchor.X && p.Y == anchor.Y && p.Z == anchor.Z ? anchorColor : boxColor);
                }
            }
        }

        capi.World.HighlightBlocks(
            capi.World.Player, HighlightSlotBox,
            positions, colors,
            EnumHighlightBlocksMode.Absolute, EnumHighlightShape.Arbitrary);

        capi.World.HighlightBlocks(capi.World.Player, HighlightSlotAnchor,
            new List<BlockPos>(),
            EnumHighlightBlocksMode.Absolute, EnumHighlightShape.Arbitrary);
    }

    private void ClearHighlight()
    {
        if (capi == null) return;
        var empty = new List<BlockPos>();
        capi.World.HighlightBlocks(capi.World.Player, HighlightSlotBox, empty,
            EnumHighlightBlocksMode.Absolute, EnumHighlightShape.Arbitrary);
        capi.World.HighlightBlocks(capi.World.Player, HighlightSlotAnchor, empty,
            EnumHighlightBlocksMode.Absolute, EnumHighlightShape.Arbitrary);
    }

    private void RegisterCommands(ICoreClientAPI api)
    {
        var parsers = api.ChatCommands.Parsers;

        var root = api.ChatCommands.Create("fw")
            .WithDesc(FieldwrightLang.Get("command.root.desc"));

        root.BeginSub("corner1")
            .WithDesc(FieldwrightLang.Get("command.corner1.desc"))
            .HandleWith(_ => { HandleCornerHotkey(corner: 1); return TextCommandResult.Success(); })
            .EndSub();

        root.BeginSub("corner2")
            .WithDesc(FieldwrightLang.Get("command.corner2.desc"))
            .HandleWith(_ => { HandleCornerHotkey(corner: 2); return TextCommandResult.Success(); })
            .EndSub();

        root.BeginSub("grow")
            .WithDesc(FieldwrightLang.Get("command.grow.desc", FieldwrightLang.DirectionCodes))
            .WithArgs(parsers.Word("direction"), parsers.OptionalInt("amount", 1))
            .HandleWith(args => OnCmdGrowOrShrink(args, grow: true))
            .EndSub();

        root.BeginSub("shrink")
            .WithDesc(FieldwrightLang.Get("command.shrink.desc", FieldwrightLang.DirectionCodes))
            .WithArgs(parsers.Word("direction"), parsers.OptionalInt("amount", 1))
            .HandleWith(args => OnCmdGrowOrShrink(args, grow: false))
            .EndSub();

        root.BeginSub("status")
            .WithDesc(FieldwrightLang.Get("command.status.desc"))
            .HandleWith(OnCmdStatus)
            .EndSub();

        root.BeginSub("clear")
            .WithDesc(FieldwrightLang.Get("command.clear.desc"))
            .HandleWith(OnCmdClear)
            .EndSub();

        root.BeginSub("save")
            .WithDesc(FieldwrightLang.Get("command.save.desc"))
            .WithArgs(parsers.Word("name"), parsers.OptionalWord("overwrite"))
            .HandleWith(OnCmdSave)
            .EndSub();

        root.BeginSub("paste")
            .WithDesc(FieldwrightLang.Get("command.paste.desc", FieldwrightLang.MatchingModeCodes))
            .WithArgs(parsers.Word("name"), parsers.OptionalWord("matching"))
            .HandleWith(OnCmdPaste)
            .EndSub();

        root.BeginSub("place")
            .WithDesc(FieldwrightLang.Get("command.place.desc"))
            .HandleWith(_ => { ToggleGhostPlacement(); return TextCommandResult.Success(); })
            .EndSub();

        root.BeginSub("cancel")
            .WithDesc(FieldwrightLang.Get("command.cancel.desc"))
            .HandleWith(OnCmdCancel)
            .EndSub();

        root.BeginSub("list")
            .WithDesc(FieldwrightLang.Get("command.list.desc"))
            .HandleWith(OnCmdList)
            .EndSub();

        root.BeginSub("restore")
            .WithDesc(FieldwrightLang.Get("command.restore.desc"))
            .WithArgs(parsers.Word("name"))
            .HandleWith(OnCmdRestore)
            .EndSub();

        root.BeginSub("mirror")
            .WithDesc(FieldwrightLang.Get("command.mirror.desc"))
            .HandleWith(_ => { CycleGhostMirror(); return TextCommandResult.Success(); })
            .EndSub();

        root.BeginSub("library")
            .WithDesc(FieldwrightLang.Get("command.library.desc"))
            .HandleWith(_ => { ToggleLibraryDialog(); return TextCommandResult.Success(); })
            .EndSub();

        FieldwrightLogger.Info(api, Component,
            "registered .fw commands: corner1, corner2, grow, shrink, status, clear, save, paste, place, cancel, list, restore, mirror, library");
    }

    private TextCommandResult OnCmdRestore(TextCommandCallingArgs args)
    {
        if (capi == null) return TextCommandResult.Error(FieldwrightLang.Get("chat.client-api-unavailable"));

        var name = (string)args[0];
        var result = BlueprintStore.Restore(capi, name);

        return result switch
        {
            BlueprintStore.RestoreResult.NoBackup => TextCommandResult.Error(
                FieldwrightLang.Chat("chat.restore.no-backup", name)),
            BlueprintStore.RestoreResult.PromotedFromBackup => TextCommandResult.Success(
                FieldwrightLang.Chat("chat.restore.promoted", name)),
            BlueprintStore.RestoreResult.Swapped => TextCommandResult.Success(
                FieldwrightLang.Chat("chat.restore.swapped", name)),
            _ => TextCommandResult.Error(FieldwrightLang.Chat("chat.restore.unknown-result")),
        };
    }

    private TextCommandResult OnCmdGrowOrShrink(TextCommandCallingArgs args, bool grow)
    {
        if (capi == null) return TextCommandResult.Error(FieldwrightLang.Get("chat.client-api-unavailable"));

        if (!selection.HasSelection)
        {
            return TextCommandResult.Error(FieldwrightLang.Chat("chat.no-selection-set-corner1-first"));
        }

        var dirString = ((string)args[0]).ToLowerInvariant();
        var face = BlockFacing.FromCode(dirString);
        if (face == null)
        {
            return TextCommandResult.Error(FieldwrightLang.Chat("chat.unknown-direction", dirString, FieldwrightLang.DirectionCodes));
        }

        int amount = (int)args[1];
        if (amount <= 0)
        {
            return TextCommandResult.Error(FieldwrightLang.Chat("chat.amount-must-be-positive"));
        }

        if (grow) selection.Grow(face, amount);
        else selection.Shrink(face, amount);

        UpdateHighlight();

        var (dx, dy, dz) = selection.GetDimensions();
        return TextCommandResult.Success(
            FieldwrightLang.Chat(
                grow ? "chat.selection-grew" : "chat.selection-shrank",
                FieldwrightLang.Facing(dirString), amount, dx, dy, dz, dx * dy * dz));
    }

    private TextCommandResult OnCmdStatus(TextCommandCallingArgs args)
    {
        if (!selection.HasSelection)
        {
            return TextCommandResult.Success(FieldwrightLang.Chat("chat.no-active-selection"));
        }

        var (dx, dy, dz) = selection.GetDimensions();
        return TextCommandResult.Success(
            FieldwrightLang.Chat(
                "chat.selection-status",
                dx, dy, dz, dx * dy * dz,
                FormatPos(selection.Anchor!),
                FormatPos(selection.Min!),
                FormatPos(selection.Max!)));
    }

    private TextCommandResult OnCmdClear(TextCommandCallingArgs args)
    {
        selection.Clear();
        ClearHighlight();
        return TextCommandResult.Success(FieldwrightLang.Chat("chat.selection-cleared"));
    }

    private TextCommandResult OnCmdSave(TextCommandCallingArgs args)
    {
        if (capi == null) return TextCommandResult.Error(FieldwrightLang.Get("chat.client-api-unavailable"));

        if (!selection.HasSelection)
        {
            return TextCommandResult.Error(FieldwrightLang.Chat("chat.set-corner1-first-shortcut"));
        }

        var name = (string)args[0];
        var overwriteArg = (args[1] as string)?.Trim().ToLowerInvariant();
        bool overwriteRequested = overwriteArg == "overwrite";

        bool willOverwrite = BlueprintStore.Exists(capi, name);
        if (willOverwrite && !overwriteRequested)
        {
            return TextCommandResult.Error(
                FieldwrightLang.Chat("chat.blueprint-exists", name));
        }

        try
        {
            var min = selection.Min!;
            var max = selection.Max!;
            var anchorOffset = selection.GetAnchorOffsetFromMin();

            // BlockSchematic.AddArea has a strict-less-than loop on the end coord,
            // so we pass max + (1,1,1) to capture the user's chosen max block inclusively.
            var endExclusive = new BlockPos(max.X + 1, max.Y + 1, max.Z + 1, max.dimension);

            // Try the vanilla AddArea path first. It captures full block-entity state
            // (chest contents, chisel voxel data, askew chest meshAngle, sign text) which
            // the ghost render depends on for proper visuals. AddArea can NRE inside
            // Entity.OnStoreCollectibleMappings if a world entity (mob, dropped item) has
            // a null collectible reference. When that happens, fall back to a block-only
            // capture that bypasses the entity path entirely.
            BlockSchematic schematic;
            bool fellBack = false;
            try
            {
                schematic = new BlockSchematic();
                schematic.AddArea(capi.World, min, endExclusive);
                schematic.Pack(capi.World, min);
            }
            catch (System.NullReferenceException)
            {
                FieldwrightLogger.Warn(capi, Component,
                    "AddArea NRE (likely an entity with null collectible refs in the region); falling back to block-only capture");
                schematic = BlueprintStore.CaptureBlocksOnly(capi.World, min, endExclusive);
                fellBack = true;
            }

            // Auto-backup the existing file before overwrite, single rolling backup
            // at {name}.bak.json so one accidental overwrite is recoverable.
            string? backupPath = null;
            if (willOverwrite)
            {
                backupPath = BlueprintStore.BackupExisting(capi, name);
            }

            var blueprint = BlueprintFile.Wrap(schematic, anchorOffset, selection.AnchorFace);
            BlueprintStore.Save(capi, name, blueprint);

            var (dx, dy, dz) = selection.GetDimensions();
            int totalBlocks = schematic.Indices?.Count ?? 0;

            // Auto-clear selection + highlight after a successful save so the
            // green overlay doesn't linger over the source structure.
            selection.Clear();
            ClearHighlight();

            var overwriteNote = backupPath != null
                ? FieldwrightLang.Get("chat.save-overwrite-note", System.IO.Path.GetFileName(backupPath))
                : string.Empty;
            var fallbackNote = fellBack
                ? FieldwrightLang.Get("chat.save-fallback-note")
                : string.Empty;
            return TextCommandResult.Success(
                FieldwrightLang.Chat(
                    "chat.saved-blueprint",
                    name, dx, dy, dz, totalBlocks,
                    anchorOffset.X, anchorOffset.Y, anchorOffset.Z,
                    overwriteNote, fallbackNote));
        }
        catch (System.Exception ex)
        {
            FieldwrightLogger.Error(capi, Component, $"save failed: {ex}");
            return TextCommandResult.Error(FieldwrightLang.Chat("chat.save-failed", ex.Message));
        }
    }

    private TextCommandResult OnCmdPaste(TextCommandCallingArgs args)
    {
        if (capi == null) return TextCommandResult.Error(FieldwrightLang.Get("chat.client-api-unavailable"));

        var name = (string)args[0];
        var matchingArg = args[1] as string;
        var requestedMode = FieldwrightConfig.ParseMatchingMode(matchingArg);
        if (matchingArg != null && requestedMode == null)
        {
            return TextCommandResult.Error(
                FieldwrightLang.Chat("chat.unknown-matching-mode", matchingArg, FieldwrightLang.MatchingModeCodes));
        }
        activeMatchingMode = requestedMode ?? config.DefaultMatchingMode;

        var (ok, message) = DoPaste(name);
        return ok ? TextCommandResult.Success(message) : TextCommandResult.Error(message);
    }

    /// <summary>
    /// Core paste implementation. Sets up activeGhostMesh, activeGhostRenderer, schematic,
    /// and anchor offset. Caller is responsible for setting activeMatchingMode beforehand
    /// since the tracker doesn't spin up until .fw place / Ctrl+Shift+P. Returns (success,
    /// message) so both the chat command handler and the library dialog can route the
    /// result back to the user.
    /// </summary>
    private (bool ok, string message) DoPaste(string name)
    {
        if (capi == null) return (false, FieldwrightLang.Get("chat.client-api-unavailable"));

        try
        {
            var blueprint = BlueprintStore.Load(capi, name);
            var schematic = blueprint.ToBlockSchematic();

            schematic.Init(capi.World.BlockAccessor);
            schematic.LoadMetaInformationAndValidate(capi.World.BlockAccessor, capi.World, name);

            var anchorOffset = blueprint.AnchorOffsetAsVec3i();
            var savedFace = blueprint.AnchorFacingResolved();

            ClearActiveGhost();

            var ghostMesh = new GhostMesh(capi, schematic, anchorOffset, config.GhostAlpha);
            if (!ghostMesh.HasMesh)
            {
                ghostMesh.Dispose();
                return (false, FieldwrightLang.Chat("chat.ghost-empty-mesh", name, ghostMesh.SkippedCount));
            }

            var initialOrigin = capi.World.Player?.CurrentBlockSelection?.Position?.Copy()
                ?? capi.World.Player!.Entity.Pos.AsBlockPos;

            activeGhostMesh = ghostMesh;
            activeGhostRenderer = new GhostRenderer(
                capi, ghostMesh, initialOrigin, anchorOffset, savedFace, startFloating: true,
                renderRange: config.RenderDistanceBlocks);
            activeGhostName = name;
            activeSchematic = schematic;
            activeAnchorOffset = anchorOffset;

            FieldwrightLogger.Info(capi, Component,
                $"pasting '{name}': size={schematic.SizeX}x{schematic.SizeY}x{schematic.SizeZ}, " +
                $"meshed={ghostMesh.BlockCount}, skipped={ghostMesh.SkippedCount}, " +
                $"initialOrigin=({initialOrigin.X},{initialOrigin.Y},{initialOrigin.Z}), " +
                $"savedFace={savedFace?.Code ?? "none"}, mode={activeMatchingMode}");

            var rotateNote = savedFace != null
                ? FieldwrightLang.Get("chat.ghost-rotate-note")
                : FieldwrightLang.Get("chat.ghost-no-rotate-note");
            return (true,
                FieldwrightLang.Chat(
                    "chat.ghost-active",
                    name, schematic.SizeX, schematic.SizeY, schematic.SizeZ,
                    ghostMesh.BlockCount, FieldwrightLang.MatchingModeLabel(activeMatchingMode), rotateNote));
        }
        catch (System.IO.FileNotFoundException)
        {
            return (false, FieldwrightLang.Chat("chat.no-blueprint-named", name));
        }
        catch (System.Exception ex)
        {
            FieldwrightLogger.Error(capi, Component, $"paste failed: {ex}");
            return (false, FieldwrightLang.Chat("chat.load-failed", ex.Message));
        }
    }

    private TextCommandResult OnCmdCancel(TextCommandCallingArgs args)
    {
        var (msg, _) = CancelAll();
        return TextCommandResult.Success(msg);
    }

    /// <summary>
    /// "Stop everything", dismiss any active ghost AND clear the current selection box.
    /// Combined intentionally: from a player's perspective both are "I'm done with this
    /// Fieldwright operation". `.fw clear` stays as the selection-only escape hatch for
    /// users who want granularity.
    /// </summary>
    private (string message, bool didAnything) CancelAll()
    {
        bool clearedGhost = activeGhostName != null;
        string prevName = activeGhostName ?? string.Empty;
        if (clearedGhost) ClearActiveGhost();

        bool clearedSelection = selection.HasSelection;
        if (clearedSelection)
        {
            selection.Clear();
            ClearHighlight();
        }

        if (clearedGhost && clearedSelection)
            return (FieldwrightLang.Chat("chat.cancel-both", prevName), true);
        if (clearedGhost)
            return (FieldwrightLang.Chat("chat.cancel-ghost", prevName), true);
        if (clearedSelection)
            return (FieldwrightLang.Chat("chat.selection-cleared"), true);
        return (FieldwrightLang.Chat("chat.cancel-nothing"), false);
    }

    private void ClearActiveGhost()
    {
        TearDownTracking();

        if (activeGhostRenderer != null)
        {
            activeGhostRenderer.Dispose();
            activeGhostRenderer = null;
        }
        if (activeGhostMesh != null)
        {
            activeGhostMesh.Dispose();
            activeGhostMesh = null;
        }
        activeGhostName = null;
        activeSchematic = null;
        activeAnchorOffset = new Vec3i(0, 0, 0);
    }

    private void TearDownTracking()
    {
        if (capi != null && completionTickListenerId != -1)
        {
            capi.Event.UnregisterGameTickListener(completionTickListenerId);
            completionTickListenerId = -1;
        }
        completionDetectedAtMs = 0;
        completionDismissNotified = false;

        if (activeChecklistHud != null)
        {
            if (activeChecklistHud.IsOpened()) activeChecklistHud.TryClose();
            activeChecklistHud.Dispose();
            activeChecklistHud = null;
        }
        if (activeChecklistDialog != null)
        {
            if (activeChecklistDialog.IsOpened()) activeChecklistDialog.TryClose();
            activeChecklistDialog.Dispose();
            activeChecklistDialog = null;
        }
        if (activeMatchTracker != null)
        {
            activeMatchTracker.Dispose();
            activeMatchTracker = null;
        }
        checklistView = ChecklistView.Hud;
    }

    /// <summary>
    /// Toggle: floating ghost → placed (locks position/rotation + spins up match
    /// tracking + opens HUD), or placed ghost → floating (tears down tracking).
    /// No-op when no ghost is active.
    /// </summary>
    private void ToggleGhostPlacement()
    {
        if (capi == null) return;

        if (activeGhostRenderer == null)
        {
            capi.ShowChatMessage(FieldwrightLang.Chat("chat.no-active-ghost"));
            return;
        }

        if (activeGhostRenderer.IsFloating)
        {
            activeGhostRenderer.Place();
            SpinUpTracking();

            var o = activeGhostRenderer.Origin;
            capi.ShowChatMessage(
                FieldwrightLang.Chat("chat.ghost-placed", activeGhostName!, o.X, o.Y, o.Z));
        }
        else
        {
            activeGhostRenderer.Unplace();
            TearDownTracking();
            capi.ShowChatMessage(
                FieldwrightLang.Chat("chat.ghost-unlocked", activeGhostName!));
        }
    }

    /// <summary>
    /// Cycle the active ghost's mirror axis (None → X → Y → Z → None). If the ghost
    /// is already placed, the tracker is rebuilt so expected positions follow the new
    /// mirror, pre-existing matches are recomputed via the tracker's InitialScan.
    /// </summary>
    private void CycleGhostMirror()
    {
        if (capi == null) return;

        if (activeGhostRenderer == null)
        {
            capi.ShowChatMessage(FieldwrightLang.Chat("chat.no-active-ghost-load-first"));
            return;
        }

        activeGhostRenderer.CycleMirror();
        var state = activeGhostRenderer.CurrentMirror;

        if (!activeGhostRenderer.IsFloating && activeSchematic != null)
        {
            // Ghost is locked. Rebuild tracking so expected positions follow the
            // new mirror state. The HUD will re-open via SpinUpTracking.
            TearDownTracking();
            SpinUpTracking();
        }

        capi.ShowChatMessage(FieldwrightLang.Chat("chat.mirror-state", FieldwrightLang.MirrorState(state)));
    }

    /// <summary>
    /// PgDn / PgUp adjust how many layers of the ghost render from the top down.
    /// Only meaningful when a ghost is active; silent no-op otherwise so the keys
    /// remain usable for whatever else the game does with them.
    /// </summary>
    private void AdjustGhostLayer(bool decrease)
    {
        if (activeGhostRenderer == null) return;

        if (decrease) activeGhostRenderer.DecreaseVisibleLayers();
        else activeGhostRenderer.IncreaseVisibleLayers();
    }

    private SchematicLibraryDialog? activeLibraryDialog;

    /// <summary>
    /// Ctrl+Shift+K: open the library when nothing is showing, close everything
    /// Fieldwright (library + hotkey help modal) when at least one is open. The
    /// hotkey help modal is owned by the library dialog, so we delegate the
    /// "close everything" path to the library's CloseAll().
    /// </summary>
    private void ToggleLibraryDialog()
    {
        if (capi == null) return;

        if (activeLibraryDialog != null && activeLibraryDialog.IsAnythingOpen())
        {
            activeLibraryDialog.CloseAll();
            return;
        }

        activeLibraryDialog ??= new SchematicLibraryDialog(capi, this);
        activeLibraryDialog.Refresh();
        activeLibraryDialog.TryOpen();
    }

    /// <summary>
    /// Library-dialog callback: paste a blueprint by name with the chosen matching mode.
    /// Calls the same code path as the .fw paste chat command (capi.SendChatMessage on
    /// client-side commands fired from a GUI button doesn't always route through the
    /// command system, so we invoke directly).
    /// </summary>
    public void PasteFromLibrary(string name, MatchingMode mode)
    {
        if (capi == null) return;

        activeMatchingMode = mode;
        var (ok, message) = DoPaste(name);
        capi.ShowChatMessage(message);
        if (!ok)
        {
            FieldwrightLogger.Warn(capi, Component, $"library paste failed for '{name}': {message}");
        }
    }

    /// <summary>Library-dialog callback: delete a saved blueprint.</summary>
    public bool DeleteFromLibrary(string name)
    {
        if (capi == null) return false;
        try
        {
            BlueprintStore.Delete(capi, name);
            capi.ShowChatMessage(FieldwrightLang.Chat("chat.deleted-blueprint", name));
            return true;
        }
        catch (Exception ex)
        {
            capi.ShowChatMessage(FieldwrightLang.Chat("chat.delete-failed", name, ex.Message));
            return false;
        }
    }

    public MatchingMode GetDefaultMatchingMode() => config.DefaultMatchingMode;

    /// <summary>
    /// Persist a new default matching mode to ModConfig/Fieldwright.json so it survives
    /// across sessions. Called by the library dialog when the user picks a mode from the
    /// dropdown, the in-memory config also updates so subsequent .fw paste calls without
    /// an explicit mode use the new default.
    /// </summary>
    public void SetDefaultMatchingMode(MatchingMode mode)
    {
        if (capi == null) return;
        if (config.DefaultMatchingMode == mode) return;
        config.DefaultMatchingMode = mode;
        try
        {
            capi.StoreModConfig(config, "Fieldwright.json");
            FieldwrightLogger.Info(capi, "config", $"default matching mode saved: {mode}");
        }
        catch (Exception ex)
        {
            FieldwrightLogger.Warn(capi, "config", $"failed to save config: {ex.Message}");
        }
    }

    private void SpinUpTracking()
    {
        if (capi == null || activeGhostRenderer == null || activeSchematic == null || activeGhostName == null) return;

        // Compute the rotation increment (0/1/2/3 = 0°/90°/180°/270°) from the renderer's RotationY.
        float quarterTurn = MathF.PI / 2f;
        int rot = (int)MathF.Round(activeGhostRenderer.RotationY / quarterTurn);
        rot = ((rot % 4) + 4) % 4;

        activeMatchTracker = new GhostMatchTracker(
            capi, activeSchematic, activeAnchorOffset, activeGhostRenderer.Origin, rot,
            activeGhostRenderer.CurrentMirror, activeMatchingMode);

        // Build both views up-front so Ctrl+Shift+L can flip between them without
        // a new construction cost mid-build. HUD opens by default; modal stays closed
        // until the player asks for it.
        activeChecklistHud = new GhostChecklistHud(capi, activeMatchTracker, activeGhostName,
            config.HudOffsetX, config.HudOffsetY);
        activeChecklistDialog = new GhostChecklistDialog(capi, activeMatchTracker, activeGhostName,
            config.HudOffsetX, config.HudOffsetY);
        checklistView = ChecklistView.Hud;
        activeChecklistHud.TryOpen();

        // Poll every 250ms for completion → start the dismiss timer.
        completionTickListenerId = capi.Event.RegisterGameTickListener(CheckCompletion, 250);
        completionDetectedAtMs = 0;
        completionDismissNotified = false;

        FieldwrightLogger.Info(capi, Component,
            $"spun up match tracking: rot={rot * 90}°, expected={activeMatchTracker.TotalBlockCells}, " +
            $"air-cells={activeMatchTracker.TotalAirCells}");
    }

    private void CheckCompletion(float dt)
    {
        if (capi == null || activeMatchTracker == null) return;

        if (!activeMatchTracker.IsComplete)
        {
            // Build came uncompleted (player broke a matched block). Re-arm.
            completionDetectedAtMs = 0;
            completionDismissNotified = false;
            return;
        }

        long now = capi.World.ElapsedMilliseconds;

        if (completionDetectedAtMs == 0)
        {
            completionDetectedAtMs = now;
            if (!completionDismissNotified)
            {
                capi.ShowChatMessage(
                    FieldwrightLang.Chat("chat.structure-complete-dismiss", config.AutoDismissMs / 1000));
                completionDismissNotified = true;
            }
            return;
        }

        if (now - completionDetectedAtMs >= config.AutoDismissMs)
        {
            capi.ShowChatMessage(FieldwrightLang.Chat("chat.build-complete-dismissed", activeGhostName!));
            ClearActiveGhost();
        }
    }

    /// <summary>
    /// Cycle through the three checklist view states: HUD -> Modal -> Hidden -> HUD.
    /// HUD is the transparent overlay that opens by default on .fw place (no cursor
    /// grab). Modal is the draggable / scrollable / copyable dialog. Hidden leaves
    /// nothing on screen.
    /// </summary>
    private void CycleChecklistView()
    {
        if (capi == null || activeChecklistHud == null || activeChecklistDialog == null)
        {
            capi?.ShowChatMessage(FieldwrightLang.Chat("chat.no-active-checklist"));
            return;
        }

        // Advance to the next state.
        checklistView = (ChecklistView)(((int)checklistView + 1) % 3);

        // Close anything that shouldn't be showing, then open what should. Order matters
        // so that flipping HUD -> Modal doesn't briefly show both, which causes the modal
        // to grab the cursor while the HUD's render layer is still active.
        switch (checklistView)
        {
            case ChecklistView.Hud:
                if (activeChecklistDialog.IsOpened()) activeChecklistDialog.TryClose();
                if (!activeChecklistHud.IsOpened()) activeChecklistHud.TryOpen();
                break;
            case ChecklistView.Modal:
                if (activeChecklistHud.IsOpened()) activeChecklistHud.TryClose();
                if (!activeChecklistDialog.IsOpened()) activeChecklistDialog.TryOpen();
                break;
            case ChecklistView.Hidden:
                if (activeChecklistHud.IsOpened()) activeChecklistHud.TryClose();
                if (activeChecklistDialog.IsOpened()) activeChecklistDialog.TryClose();
                break;
        }
    }

    private TextCommandResult OnCmdList(TextCommandCallingArgs args)
    {
        if (capi == null) return TextCommandResult.Error(FieldwrightLang.Get("chat.client-api-unavailable"));

        var names = BlueprintStore.List(capi);
        if (names.Count == 0)
        {
            return TextCommandResult.Success(
                FieldwrightLang.Chat("chat.no-blueprints-saved-directory", BlueprintStore.GetBlueprintsDirectory(capi)));
        }

        return TextCommandResult.Success(FieldwrightLang.Chat("chat.blueprint-list", names.Count, string.Join(", ", names)));
    }

    private static string FormatPos(BlockPos pos) => $"({pos.X}, {pos.Y}, {pos.Z})";

    public override void Dispose()
    {
        ClearActiveGhost();
        base.Dispose();
    }
}