refactor(preview): fire after_file_open on escalation; single source of truth

Two related changes to the preview/after_file_open machinery.

1. Escalation now fires the deferred hook. Previewing a file defers
   `after_file_open`; previously, escalating that preview to a permanent
   buffer (editing it, Enter, focusing away) never fired it at all — so a
   file you preview-then-commit diverged from one you open directly, and
   plugin side effects keyed on the hook (csharp `dotnet restore`, the
   asm-lsp config offer, git_explorer refresh) silently never ran. The
   `promote_*` methods now fire the deferred hook at the moment of
   commitment, so the hook fires exactly once per buffer whether it was
   opened directly or escalated from a preview.

2. Fewer, non-redundant states. Preview was tracked in three places that
   could drift: `Window.preview` (the anchored (split, buffer)), a
   per-buffer `BufferMetadata.is_preview` bool, and the `opening_as_preview`
   open-time flag. Collapsed to one source of truth:
   - `Window.preview: Option<(LeafId, BufferId)>` is now the only preview
     state. "Two previews", "orphan preview flag", and "flag disagrees with
     the anchored preview" are no longer representable. `is_buffer_preview`
     and the tab renderer derive from it (the renderer takes a
     `preview_buffer` argument threaded from `window.preview`).
   - `opening_as_preview` (ambient mutable flag) is replaced by an explicit
     `OpenKind::{Commit, Preview}` value threaded through the open path, so
     the hook-deferral intent travels as an argument rather than window
     state read out of band.

Because the single `after_file_open` fire site keys deferral off `OpenKind`
and re-fires off `Window.preview` at promotion, exactly-once holds
structurally with no "hook already fired" bookkeeping: a directly-opened
buffer is never the preview, and a promoted buffer is cleared from
`Window.preview`, so a later promote is a no-op.

The e2e suite adds the escalation case (preview → edit → hook fires) next to
the existing preview-suppression case; it times out without the fire-on-
promote change and passes with it.

https://claude.ai/code/session_01KdY8xi7GwhBTJueszhwGXB

Author: claude

crates/fresh-editor/src/app/buffer_management.rs

@@ -137,16 +137,15 @@ impl Editor {
         // (LSP, language detection, split targeting, status message, plugin
         // hooks) consistent with a normal open.
         //
-        // `opening_as_preview` additionally tells the inner open path that
-        // this is a browse, not a deliberate open, so the `after_file_open`
-        // plugin hook is skipped — otherwise plugins raise intrusive UI
-        // (e.g. the asm-lsp `.asm-lsp.toml` config-offer popup) over each
-        // file the user arrows past. Set and cleared around the call so a
-        // failed open can't leave the flag stuck.
+        // `OpenKind::Preview` additionally tells the open path that this is a
+        // browse, not a deliberate open, so the `after_file_open` plugin hook
+        // is deferred — otherwise plugins raise intrusive UI (e.g. the
+        // asm-lsp `.asm-lsp.toml` config-offer popup) over each file the user
+        // arrows past. The hook fires later if/when this preview is escalated
+        // to a permanent tab.
         self.active_window_mut().suppress_position_history_once = true;
-        self.active_window_mut().opening_as_preview = true;
-        let open_result = self.open_file(path);
-        self.active_window_mut().opening_as_preview = false;
+        let open_result =
+            self.open_file_with_kind(path, super::file_open_orchestrators::OpenKind::Preview);
         self.active_window_mut().suppress_position_history_once = false;
         let buffer_id = open_result?;
         let is_new = !previously_file_backed.contains(&buffer_id);
@@ -159,40 +158,37 @@ impl Editor {
         }
 
         // New buffer. Resolve the existing preview (if any) relative to the
-        // target split.
+        // target split. `preview.take()` clears the single source of truth;
+        // each arm below decides whether the displaced buffer was *committed*
+        // (escalated → fire its deferred `after_file_open`) or merely
+        // *discarded* (closed → no hook).
         match self.active_window_mut().preview.take() {
             Some((prev_split, old_id)) if prev_split == target_split => {
                 // Same split: close the old preview so the new one takes its
-                // place. If close fails (modified buffer — shouldn't happen
-                // because edits promote, but defend in depth), demote the
-                // orphan to a permanent tab rather than leaving behind an
-                // italic "(preview)" tab that will never be replaced.
+                // place. Replacement is not a commitment, so no hook. If close
+                // fails (modified buffer — shouldn't happen because edits
+                // promote, but defend in depth), the buffer stays open as a
+                // permanent tab, which *is* a commitment → fire its deferred
+                // hook.
                 if let Err(e) = self.close_buffer(old_id) {
                     tracing::warn!(
                         "preview: could not replace stale preview buffer {:?}, demoting to permanent: {}",
                         old_id,
                         e
                     );
-                    if let Some(m) = self.active_window_mut().buffer_metadata.get_mut(&old_id) {
-                        m.is_preview = false;
-                    }
+                    self.active_window().fire_deferred_after_file_open(old_id);
                 }
             }
             Some((_other_split, old_id)) => {
                 // Different split: user walked away from the old preview
-                // before this click. Promote it to permanent — their focus
-                // moving to another split was the commitment signal.
-                if let Some(m) = self.active_window_mut().buffer_metadata.get_mut(&old_id) {
-                    m.is_preview = false;
-                }
+                // before this click. Their focus moving to another split was
+                // the commitment signal → escalate it and fire the hook.
+                self.active_window().fire_deferred_after_file_open(old_id);
             }
             None => {}
         }
 
-        // Mark the new buffer as the preview, anchored to its split.
-        if let Some(meta) = self.active_window_mut().buffer_metadata.get_mut(&buffer_id) {
-            meta.is_preview = true;
-        }
+        // Anchor the new buffer as the preview — the single source of truth.
         self.active_window_mut().preview = Some((target_split, buffer_id));
 
         Ok(buffer_id)

crates/fresh-editor/src/app/file_open_orchestrators.rs

@@ -21,6 +21,24 @@ use crate::state::EditorState;
 
 use super::Editor;
 
+/// How a file open treats the resulting buffer.
+///
+/// Threaded through the open path so the single `after_file_open` fire site
+/// in [`open_file_no_focus_inner`] can defer the hook for previews. A
+/// `Preview` open is "just looking" (file-explorer browse, live-grep
+/// overlay): the hook is withheld until the preview is escalated to a
+/// permanent buffer (see the `promote_*` methods on `Window`). `Commit` is
+/// every deliberate open and fires the hook immediately. This replaces an
+/// earlier ambient `opening_as_preview` flag — the intent now travels as a
+/// value rather than mutable window state that could be read out of band.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum OpenKind {
+    /// Deliberate open — fire `after_file_open` now.
+    Commit,
+    /// Ephemeral preview — defer `after_file_open` until escalation.
+    Preview,
+}
+
 impl Editor {
     /// Helper to jump to a line/column position in the active buffer.
     ///
@@ -98,6 +116,18 @@ impl Editor {
     /// If the file doesn't exist, creates an unsaved buffer with that filename.
     /// Saving the buffer will create the file.
     pub fn open_file(&mut self, path: &Path) -> anyhow::Result<BufferId> {
+        self.open_file_with_kind(path, OpenKind::Commit)
+    }
+
+    /// `open_file` with explicit [`OpenKind`]. `open_file_preview` uses
+    /// `OpenKind::Preview` to route through all of `open_file`'s
+    /// cross-cutting concerns (focus, language detection, status, the
+    /// `buffer_activated` hook) while deferring only `after_file_open`.
+    pub(crate) fn open_file_with_kind(
+        &mut self,
+        path: &Path,
+        kind: OpenKind,
+    ) -> anyhow::Result<BufferId> {
         // If the active leaf is a utility-dock pane (Search/Replace,
         // Quickfix, terminal-in-dock), the user almost never wants the
         // newly-opened file to land there — the dock hosts panel-style
@@ -119,7 +149,9 @@ impl Editor {
             .and_then(|s| s.buffer.file_path())
             .is_some();
 
-        let buffer_id = self.active_window_mut().open_file_no_focus(path)?;
+        let buffer_id = self
+            .active_window_mut()
+            .open_file_no_focus_with_kind(path, kind)?;
 
         // Check if this was an already-open buffer or a new one
         // For already-open buffers, just switch to them
@@ -817,7 +849,18 @@ impl crate::app::window::Window {
     /// flip. If the file doesn't exist, creates an unsaved buffer with
     /// that filename.
     pub fn open_file_no_focus(&mut self, path: &Path) -> anyhow::Result<BufferId> {
-        self.open_file_no_focus_inner(path, true)
+        self.open_file_no_focus_inner(path, true, OpenKind::Commit)
+    }
+
+    /// `open_file_no_focus` with an explicit [`OpenKind`], so the Editor-side
+    /// `open_file_with_kind` can route a preview open through the same core
+    /// while deferring `after_file_open`.
+    pub(crate) fn open_file_no_focus_with_kind(
+        &mut self,
+        path: &Path,
+        kind: OpenKind,
+    ) -> anyhow::Result<BufferId> {
+        self.open_file_no_focus_inner(path, true, kind)
     }
 
     /// Open a file without switching focus AND without ever
@@ -832,14 +875,10 @@ impl crate::app::window::Window {
     /// results. This variant always allocates a fresh BufferId so the
     /// background buffer never gets repurposed.
     pub(crate) fn open_file_for_preview(&mut self, path: &Path) -> anyhow::Result<BufferId> {
-        // Live-grep preview is a browse, not a deliberate open: suppress the
-        // `after_file_open` plugin hook so plugins don't pop UI / run side
-        // effects over each result the user cycles through. Cleared
-        // unconditionally so an error can't leave the flag stuck.
-        self.opening_as_preview = true;
-        let result = self.open_file_no_focus_inner(path, false);
-        self.opening_as_preview = false;
-        result
+        // Live-grep preview is a browse, not a deliberate open: defer the
+        // `after_file_open` hook so plugins don't pop UI / run side effects
+        // over each result the user cycles through.
+        self.open_file_no_focus_inner(path, false, OpenKind::Preview)
     }
 
     /// True if `path` is an internal app artifact (terminal scrollback,
@@ -866,6 +905,7 @@ impl crate::app::window::Window {
         &mut self,
         path: &Path,
         allow_replace_empty: bool,
+        kind: OpenKind,
     ) -> anyhow::Result<BufferId> {
         // Fail fast if the remote connection is down — don't attempt I/O that
         // would either timeout or return confusing errors.
@@ -1172,20 +1212,40 @@ impl crate::app::window::Window {
         // looking": firing this hook lets plugins raise intrusive UI (e.g.
         // the asm-lsp config-offer popup) or run side effects (csharp
         // `dotnet restore`) over a file the user is merely glancing at as
-        // previews replace each other. Deliberate opens (Ctrl+P, double-
-        // click, Enter) go through the non-preview path and still fire it.
-        // Plugins that need to react when a preview becomes visible use
-        // `buffer_activated`, which still fires on every preview switch.
-        if !self.opening_as_preview {
-            self.resources.plugin_manager.read().unwrap().run_hook(
-                "after_file_open",
-                crate::services::plugins::hooks::HookArgs::AfterFileOpen {
-                    buffer_id,
-                    path: path.to_path_buf(),
-                },
-            );
+        // previews replace each other. For a preview the hook is deferred —
+        // it fires once the buffer is escalated to a permanent tab (see
+        // `Window::promote_*`). Plugins that need to react when a preview
+        // becomes visible use `buffer_activated`, which still fires on every
+        // preview switch.
+        if kind == OpenKind::Commit {
+            self.run_after_file_open_hook(buffer_id, path.to_path_buf());
         }
 
         Ok(buffer_id)
     }
+
+    /// Fire the `after_file_open` plugin hook for `buffer_id`. Single site so
+    /// both the commit-time open path and the escalation (promote) path raise
+    /// it identically.
+    pub(crate) fn run_after_file_open_hook(&self, buffer_id: BufferId, path: std::path::PathBuf) {
+        self.resources.plugin_manager.read().unwrap().run_hook(
+            "after_file_open",
+            crate::services::plugins::hooks::HookArgs::AfterFileOpen { buffer_id, path },
+        );
+    }
+
+    /// Fire the deferred `after_file_open` hook for a buffer that was opened
+    /// as a preview and is now being escalated to a permanent tab. Looks up
+    /// the buffer's own file path; a no-op for buffers without one.
+    pub(crate) fn fire_deferred_after_file_open(&self, buffer_id: BufferId) {
+        if let Some(path) = self
+            .buffers
+            .get(&buffer_id)
+            .and_then(|s| s.buffer.file_path())
+            .filter(|p| !p.as_os_str().is_empty())
+            .map(|p| p.to_path_buf())
+        {
+            self.run_after_file_open_hook(buffer_id, path);
+        }
+    }
 }

crates/fresh-editor/src/app/macro_actions.rs

@@ -245,7 +245,6 @@ impl Editor {
             hidden_from_tabs: false,
             auto_revert_enabled: true,
             synthetic_placeholder: false,
-            is_preview: false,
             recovery_id: None,
         };
         self.active_window_mut()
@@ -331,7 +330,6 @@ impl Editor {
             hidden_from_tabs: false,
             auto_revert_enabled: true,
             synthetic_placeholder: false,
-            is_preview: false,
             recovery_id: None,
         };
         self.active_window_mut()

crates/fresh-editor/src/app/plugin_dispatch.rs

@@ -5115,11 +5115,7 @@ impl Window {
                     .map(|bs| matches!(bs.view_mode, crate::state::ViewMode::PageView))
                     .unwrap_or(false)
             });
-            let is_preview = self
-                .buffer_metadata
-                .get(buffer_id)
-                .map(|m| m.is_preview)
-                .unwrap_or(false);
+            let is_preview = self.is_buffer_preview(*buffer_id);
             // Which splits currently hold this buffer — lets plugins
             // implement "focus existing if visible, else open new"
             // without tracking split ids across editor restarts

crates/fresh-editor/src/app/render.rs

@@ -672,6 +672,10 @@ impl Editor {
             .get_mut(&active_window_id)
             .expect("active window must exist");
         let __metadata_ref = &__win.buffer_metadata;
+        // Copy out the preview buffer id (the single source of truth) so the
+        // tab renderer can style the "(preview)" tab without holding a borrow
+        // of `__win` across the `with_all_mut` closure below.
+        let __preview_buffer = __win.preview.map(|(_, b)| b);
         let __event_logs_mut = &mut __win.event_logs;
         let __grouped_ref = &__win.grouped_subtrees;
         let __composite_buffers_mut = &mut __win.composite_buffers;
@@ -695,6 +699,7 @@ impl Editor {
                     &*__mgr,
                     __buffers_mut,
                     __metadata_ref,
+                    __preview_buffer,
                     __event_logs_mut,
                     __composite_buffers_mut,
                     __composite_view_states_mut,
@@ -2250,6 +2255,7 @@ impl Editor {
             return;
         };
         let __preview_metadata = &__win_for_preview.buffer_metadata;
+        let __preview_buffer_id = __win_for_preview.preview.map(|(_, b)| b);
         let __preview_event_logs = &mut __win_for_preview.event_logs;
         let __preview_composite_buffers = &mut __win_for_preview.composite_buffers;
         let __preview_composite_view_states = &mut __win_for_preview.composite_view_states;
@@ -2287,6 +2293,7 @@ impl Editor {
                     &*mgr,
                     preview_buffers,
                     __preview_metadata,
+                    __preview_buffer_id,
                     __preview_event_logs,
                     __preview_composite_buffers,
                     __preview_composite_view_states,

crates/fresh-editor/src/app/scroll_sync.rs

@@ -40,6 +40,7 @@ impl crate::app::window::Window {
             .collect();
         let metadata = &self.buffer_metadata;
         let composites = &self.composite_buffers;
+        let preview_buffer = self.preview.map(|(_, b)| b);
 
         self.buffers.with_all_mut(|buffer_map, _mgr, vs_map| {
             let Some(view_state) = vs_map.get_mut(&split_id) else {
@@ -52,6 +53,7 @@ impl crate::app::window::Window {
                 metadata,
                 composites,
                 &group_names,
+                preview_buffer,
             );
 
             let total_tabs_width: usize = tab_widths.iter().sum();

crates/fresh-editor/src/app/types/buffer_meta.rs

@@ -71,19 +71,6 @@ pub struct BufferMetadata {
     /// user a truly empty workspace.
     pub synthetic_placeholder: bool,
 
-    /// Whether this buffer is opened in "preview" mode (ephemeral).
-    /// A preview buffer is one opened by a single-click in the file explorer
-    /// (or a similar soft-open gesture). Its tab is rendered in italic and
-    /// it is replaced the next time another file is opened the same way.
-    /// The flag is cleared ("promoted") when the user edits the buffer,
-    /// double-clicks the file, or otherwise signals commitment to the file.
-    ///
-    /// Intentionally ephemeral — never serialized into workspace or
-    /// recovery state. Restarting the editor always brings buffers back
-    /// as permanent tabs; preview status belongs to the current session's
-    /// exploration flow only.
-    pub is_preview: bool,
-
     /// Stable recovery ID for unnamed buffers.
     /// For file-backed buffers, recovery ID is computed from the path hash.
     /// For unnamed buffers, this is generated once and reused across auto-saves.
@@ -150,7 +137,6 @@ impl BufferMetadata {
             hidden_from_tabs: false,
             auto_revert_enabled: true,
             synthetic_placeholder: false,
-            is_preview: false,
             recovery_id: None,
         }
     }
@@ -172,7 +158,6 @@ impl BufferMetadata {
             auto_revert_enabled: true,
             hidden_from_tabs: false,
             synthetic_placeholder: false,
-            is_preview: false,
             recovery_id: None,
         }
     }
@@ -233,7 +218,6 @@ impl BufferMetadata {
             lsp_opened_with: HashSet::new(),
             hidden_from_tabs: false,
             synthetic_placeholder: false,
-            is_preview: false,
             recovery_id: None,
         }
     }
@@ -273,7 +257,6 @@ impl BufferMetadata {
             lsp_opened_with: HashSet::new(),
             hidden_from_tabs: false,
             synthetic_placeholder: false,
-            is_preview: false,
             recovery_id: None,
         }
     }
@@ -372,7 +355,6 @@ impl BufferMetadata {
             lsp_opened_with: HashSet::new(),
             hidden_from_tabs: false,
             synthetic_placeholder: false,
-            is_preview: false,
             recovery_id: None,
         }
     }
@@ -392,7 +374,6 @@ impl BufferMetadata {
             lsp_opened_with: HashSet::new(),
             hidden_from_tabs: true,
             synthetic_placeholder: false,
-            is_preview: false,
             recovery_id: None,
         }
     }