adding 'TabStack.sublime-settings' and "preview_file" setting

AGENTS.md

@@ -17,6 +17,8 @@
 - Ctrl-release detection lives in `plugin/ctrl_release/`.
 - Uner Linux, Ctrl-release polling uses the X11 key state API, so Sublime must run under X11 or XWayland; a native Wayland session has no pollable global key state and Sublime exposes no key-release API.
 - `tab_stack_open` arms a pending session, starts a Ctrl-release poller, and opens the quick panel after a short delay unless Ctrl is released first.
+- Package defaults live in `TabStack.sublime-settings` and are read through `sublime.load_settings` in `plugin/settings.py`.
+- `preview_file` controls whether the highlighted entry is shown while the list is open. When it is false, the file changes only when the list closes.
 - Wrap-around cycling is implemented by intentionally closing and reopening the quick panel at the opposite boundary.
   That handoff keeps the session active and reuses the existing Ctrl-release poller.
 - `tab_stack.session_active` is the quick-panel session context key.

Main.sublime-menu

@@ -0,0 +1,34 @@
+[
+    {
+        "caption": "Preferences",
+        "mnemonic": "n",
+        "id": "preferences",
+        "children":
+        [
+            {
+                "caption": "Package Settings",
+                "mnemonic": "P",
+                "id": "package-settings",
+                "children":
+                [
+                    {
+                        "caption": "TabStack",
+                        "children":
+                        [
+                            {
+                                "command": "open_file",
+                                "args": {"file": "${packages}/TabStack/TabStack.sublime-settings"},
+                                "caption": "Settings – Default"
+                            },
+                            {
+                                "command": "open_file",
+                                "args": {"file": "${packages}/User/TabStack.sublime-settings"},
+                                "caption": "Settings – User"
+                            }
+                        ]
+                    }
+                ]
+            }
+        ]
+    }
+]

TabStack.sublime-settings

@@ -0,0 +1,5 @@
+{
+  // Show the highlighted file while the list is open.
+  // When false, the file changes only after the list closes.
+  "preview_file": true
+}

plugin/session.py

@@ -4,6 +4,7 @@
 
 from .constants import KIND_MODIFIED
 from .ctrl_release import CtrlReleasePoller
+from .settings import preview_file
 from .sheets import apply_group_selection
 from .state import TabStackWindowState
 
@@ -50,7 +51,8 @@ def on_highlight(index: int) -> None:
         if index < 0 or index >= len(entries):
             return
         state.session_selected_index = index
-        preview_entry(window, state)
+        if preview_file():
+            preview_entry(window, state)
 
     window.show_quick_panel(
         items,
@@ -101,7 +103,7 @@ def _commit_pending_session(window: sublime.Window, state: TabStackWindowState)
 
 
 def _commit_session(window: sublime.Window, state: TabStackWindowState) -> None:
-    if not state.session_active:
+    if not state.session_active or state.session_committing:
         return
 
     entries = state.session_entries
@@ -115,6 +117,26 @@ def _commit_session(window: sublime.Window, state: TabStackWindowState) -> None:
         cancel_session(window, state)
         return
 
+    # Preview already focused this sheet while the list was open, so closing
+    # now does not postpone a file change.
+    if preview_file():
+        window.run_command("hide_overlay", {"cancel": True})
+        state.clear_session()
+        return
+
+    # Focusing and hiding in this same turn does not show the new sheet until
+    # the list has finished closing. Yield once so the focus lands first.
+    token = state.session_pending_token
+    sublime.set_timeout(lambda: _hide_committed_panel(window, state, token), 0)
+
+
+def _hide_committed_panel(window: sublime.Window, state: TabStackWindowState, token: int | None) -> None:
+    if not state.session_active:
+        return
+    if token is not None and state.session_pending_token != token:
+        return
+
+    state.session_committing = True
     window.run_command("hide_overlay", {"cancel": True})
     state.clear_session()
 
@@ -156,4 +178,9 @@ def handle_panel_closed(window: sublime.Window, state: TabStackWindowState) -> N
         state.session_panel_reopening = False
         return
 
+    # Commit already focused the chosen sheet. This close is that commit
+    # finishing, not an abort, so the original sheet must stay put.
+    if state.session_committing:
+        return
+
     cancel_session(window, state)

plugin/settings.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import sublime
+
+SETTINGS_FILE = "TabStack.sublime-settings"
+_settings = sublime.load_settings(SETTINGS_FILE)
+
+
+def save_settings() -> None:
+    sublime.save_settings(SETTINGS_FILE)
+
+
+def preview_file() -> bool:
+    """Whether the highlighted list entry is shown before the list closes."""
+    return _bool_setting("preview_file", default=True)
+
+
+def _bool_setting(key: str, *, default: bool) -> bool:
+    value = _settings.get(key, default)
+    return value if isinstance(value, bool) else default

plugin/state.py

@@ -29,6 +29,12 @@ class TabStackWindowState:
     session_group: int = 0
     session_entries: Optional[list[Entry]] = None
     session_panel_reopening: bool = False
+    session_committing: bool = False
+    """A commit has focused its sheet and is closing the list.
+
+    The overlay's close callback must not treat that close as a cancel,
+    or it puts the original sheet back.
+    """
     selection_poller: Optional[Poller] = None
     ctrl_release_poller: Optional[CtrlPoller] = None
     overlay_views: set[int] = field(default_factory=set)
@@ -53,6 +59,7 @@ def clear_session(self) -> None:
         self.session_group = 0
         self.session_entries = None
         self.session_panel_reopening = False
+        self.session_committing = False
         self.session_pending_token += 1
         if self.ctrl_release_poller is not None:
             self.ctrl_release_poller.stop()