feat: Add support for action modifier keys like ctrl,shift,alt.

Cargo.toml

@@ -3,6 +3,7 @@ resolver = "3"
 members = [
     "crates/pikl-core",
     "crates/pikl-tui",
+    "crates/pikl-gui",
     "crates/pikl",
     "crates/pikl-test-macros",
 ]

crates/pikl-core/src/model/event.rs

@@ -9,6 +9,8 @@
 
 use std::sync::Arc;
 
+use serde::ser::SerializeSeq;
+use serde::Serialize;
 use serde_json::Value;
 
 use crate::hook::HookResponse;
@@ -53,6 +55,65 @@ pub enum Action {
     RemoveItems(Vec<usize>),
     ProcessHookResponse(HookResponse),
     CloseMenu,
+    StreamingDone,
+}
+
+/// Modifier keys held during an action. Serializes as an
+/// array of strings (e.g. `["shift", "ctrl"]`). Empty
+/// modifiers serialize as `[]`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct Modifiers {
+    pub shift: bool,
+    pub ctrl: bool,
+    pub alt: bool,
+}
+
+impl Modifiers {
+    /// True when no modifiers are held.
+    pub fn is_empty(&self) -> bool {
+        !self.shift && !self.ctrl && !self.alt
+    }
+}
+
+impl Serialize for Modifiers {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let count = self.shift as usize + self.ctrl as usize + self.alt as usize;
+        let mut seq = serializer.serialize_seq(Some(count))?;
+        if self.shift {
+            seq.serialize_element("shift")?;
+        }
+        if self.ctrl {
+            seq.serialize_element("ctrl")?;
+        }
+        if self.alt {
+            seq.serialize_element("alt")?;
+        }
+        seq.end()
+    }
+}
+
+/// An [`Action`] paired with the modifier keys that were
+/// held when it was triggered. Frontends produce these,
+/// the menu engine consumes them.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ModifiedAction {
+    pub action: Action,
+    pub modifiers: Modifiers,
+}
+
+impl ModifiedAction {
+    /// Wrap an action with default (empty) modifiers.
+    pub fn new(action: Action) -> Self {
+        Self {
+            action,
+            modifiers: Modifiers::default(),
+        }
+    }
+
+    /// Wrap an action with specific modifiers.
+    pub fn with_modifiers(action: Action, modifiers: Modifiers) -> Self {
+        Self { action, modifiers }
+    }
 }
 
 /// Broadcast from the menu loop to all subscribers
@@ -81,6 +142,8 @@ pub struct ViewState {
     pub mode: Mode,
     pub selection_count: usize,
     pub multi_enabled: bool,
+    /// True while stdin is still streaming items in.
+    pub streaming: bool,
     /// Column headers for table mode. None when not in
     /// table mode.
     pub columns: Option<Vec<ColumnHeader>>,
@@ -122,10 +185,89 @@ pub enum MenuResult {
     Selected {
         items: Vec<(Value, usize)>,
         filter_text: String,
+        modifiers: Modifiers,
     },
     Quicklist {
         items: Vec<(Value, usize)>,
         filter_text: String,
+        modifiers: Modifiers,
+    },
+    Cancelled {
+        modifiers: Modifiers,
     },
-    Cancelled,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn modifiers_empty_serializes_as_empty_array() {
+        let mods = Modifiers::default();
+        let json = serde_json::to_value(&mods).unwrap_or_default();
+        assert_eq!(json, json!([]));
+    }
+
+    #[test]
+    fn modifiers_single_serializes() {
+        let mods = Modifiers {
+            shift: true,
+            ctrl: false,
+            alt: false,
+        };
+        let json = serde_json::to_value(&mods).unwrap_or_default();
+        assert_eq!(json, json!(["shift"]));
+    }
+
+    #[test]
+    fn modifiers_multiple_serializes() {
+        let mods = Modifiers {
+            shift: true,
+            ctrl: true,
+            alt: false,
+        };
+        let json = serde_json::to_value(&mods).unwrap_or_default();
+        assert_eq!(json, json!(["shift", "ctrl"]));
+    }
+
+    #[test]
+    fn modifiers_all_serializes() {
+        let mods = Modifiers {
+            shift: true,
+            ctrl: true,
+            alt: true,
+        };
+        let json = serde_json::to_value(&mods).unwrap_or_default();
+        assert_eq!(json, json!(["shift", "ctrl", "alt"]));
+    }
+
+    #[test]
+    fn modifiers_is_empty() {
+        assert!(Modifiers::default().is_empty());
+        assert!(!Modifiers {
+            shift: true,
+            ctrl: false,
+            alt: false
+        }
+        .is_empty());
+    }
+
+    #[test]
+    fn modified_action_new_has_empty_modifiers() {
+        let ma = ModifiedAction::new(Action::Confirm);
+        assert!(ma.modifiers.is_empty());
+    }
+
+    #[test]
+    fn modified_action_with_modifiers() {
+        let mods = Modifiers {
+            shift: true,
+            ctrl: false,
+            alt: false,
+        };
+        let ma = ModifiedAction::with_modifiers(Action::Confirm, mods);
+        assert!(ma.modifiers.shift);
+        assert!(!ma.modifiers.ctrl);
+    }
 }

crates/pikl-core/src/model/output.rs

@@ -6,6 +6,8 @@ use serde::Serialize;
 use serde::ser::SerializeMap;
 use serde_json::Value;
 
+use crate::event::Modifiers;
+
 /// What the user did to produce this output.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "snake_case")]
@@ -25,27 +27,35 @@ pub struct OutputItem {
     pub value: Value,
     pub action: OutputAction,
     pub index: usize,
+    pub modifiers: Modifiers,
 }
 
 impl Serialize for OutputItem {
     fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let has_mods = !self.modifiers.is_empty();
         match &self.value {
             Value::Object(map) => {
                 // Flatten: merge object fields with action/index
-                let mut s = serializer.serialize_map(Some(map.len() + 2))?;
+                let mut s = serializer.serialize_map(None)?;
                 for (k, v) in map {
                     s.serialize_entry(k, v)?;
                 }
                 s.serialize_entry("action", &self.action)?;
                 s.serialize_entry("index", &self.index)?;
+                if has_mods {
+                    s.serialize_entry("modifiers", &self.modifiers)?;
+                }
                 s.end()
             }
             _ => {
                 // Non-object: put value in a "value" field
-                let mut s = serializer.serialize_map(Some(3))?;
+                let mut s = serializer.serialize_map(None)?;
                 s.serialize_entry("value", &self.value)?;
                 s.serialize_entry("action", &self.action)?;
                 s.serialize_entry("index", &self.index)?;
+                if has_mods {
+                    s.serialize_entry("modifiers", &self.modifiers)?;
+                }
                 s.end()
             }
         }
@@ -63,6 +73,7 @@ mod tests {
             value: json!({"label": "Firefox", "url": "https://firefox.com"}),
             action: OutputAction::Select,
             index: 3,
+            modifiers: Modifiers::default(),
         };
         let json = serde_json::to_value(&item).unwrap_or_default();
         assert_eq!(json["label"], "Firefox");
@@ -77,6 +88,7 @@ mod tests {
             value: json!("hello"),
             action: OutputAction::Select,
             index: 0,
+            modifiers: Modifiers::default(),
         };
         let json = serde_json::to_value(&item).unwrap_or_default();
         assert_eq!(json["value"], "hello");
@@ -90,6 +102,7 @@ mod tests {
             value: json!(null),
             action: OutputAction::Cancel,
             index: 0,
+            modifiers: Modifiers::default(),
         };
         let json = serde_json::to_value(&item).unwrap_or_default();
         assert_eq!(json["action"], "cancel");
@@ -101,6 +114,7 @@ mod tests {
             value: json!("test"),
             action: OutputAction::Quicklist,
             index: 2,
+            modifiers: Modifiers::default(),
         };
         let json = serde_json::to_value(&item).unwrap_or_default();
         assert_eq!(json["action"], "quicklist");
@@ -113,6 +127,7 @@ mod tests {
             value: json!("alpha"),
             action: OutputAction::Select,
             index: 0,
+            modifiers: Modifiers::default(),
         };
         let serialized = serde_json::to_string(&item).unwrap_or_default();
         assert!(
@@ -120,4 +135,61 @@ mod tests {
             "output should contain the value text: {serialized}"
         );
     }
+
+    #[test]
+    fn output_item_omits_empty_modifiers() {
+        let item = OutputItem {
+            value: json!("test"),
+            action: OutputAction::Select,
+            index: 0,
+            modifiers: Modifiers::default(),
+        };
+        let json = serde_json::to_value(&item).unwrap_or_default();
+        assert!(json.get("modifiers").is_none(), "empty modifiers should be omitted");
+    }
+
+    #[test]
+    fn output_item_includes_modifiers_when_present() {
+        let item = OutputItem {
+            value: json!("test"),
+            action: OutputAction::Select,
+            index: 0,
+            modifiers: Modifiers {
+                shift: true,
+                ctrl: false,
+                alt: false,
+            },
+        };
+        let json = serde_json::to_value(&item).unwrap_or_default();
+        assert_eq!(json["modifiers"], json!(["shift"]));
+    }
+
+    #[test]
+    fn output_item_object_with_modifiers() {
+        let item = OutputItem {
+            value: json!({"label": "Firefox"}),
+            action: OutputAction::Select,
+            index: 0,
+            modifiers: Modifiers {
+                shift: true,
+                ctrl: true,
+                alt: false,
+            },
+        };
+        let json = serde_json::to_value(&item).unwrap_or_default();
+        assert_eq!(json["label"], "Firefox");
+        assert_eq!(json["modifiers"], json!(["shift", "ctrl"]));
+    }
+
+    #[test]
+    fn output_item_object_omits_empty_modifiers() {
+        let item = OutputItem {
+            value: json!({"label": "Firefox"}),
+            action: OutputAction::Select,
+            index: 0,
+            modifiers: Modifiers::default(),
+        };
+        let json = serde_json::to_value(&item).unwrap_or_default();
+        assert!(json.get("modifiers").is_none());
+    }
 }

crates/pikl-core/src/runtime/debounce.rs

@@ -10,7 +10,7 @@ use tokio::sync::mpsc;
 use tokio::task::JoinHandle;
 use tracing::Instrument;
 
-use crate::event::Action;
+use crate::event::{Action, ModifiedAction};
 use crate::hook::{HookEvent, HookEventKind, HookHandler, HookResponse};
 
 /// Debounce mode for a hook event kind.
@@ -30,13 +30,13 @@ pub enum DebounceMode {
 /// behavior. Each event kind can have its own mode.
 pub struct DebouncedDispatcher {
     handler: Arc<dyn HookHandler>,
-    _action_tx: mpsc::Sender<Action>,
+    _action_tx: mpsc::Sender<ModifiedAction>,
     modes: HashMap<HookEventKind, DebounceMode>,
     in_flight: HashMap<HookEventKind, JoinHandle<()>>,
 }
 
 impl DebouncedDispatcher {
-    pub fn new(handler: Arc<dyn HookHandler>, action_tx: mpsc::Sender<Action>) -> Self {
+    pub fn new(handler: Arc<dyn HookHandler>, action_tx: mpsc::Sender<ModifiedAction>) -> Self {
         Self {
             handler,
             _action_tx: action_tx,
@@ -149,6 +149,7 @@ pub fn hook_response_to_action(resp: HookResponse) -> Action {
 mod tests {
     use super::*;
     use crate::error::PiklError;
+    use crate::event::Modifiers;
     use serde_json::json;
     use std::sync::Mutex;
 
@@ -217,12 +218,15 @@ mod tests {
         // Rapid-fire filter events
         dispatcher.dispatch(HookEvent::Filter {
             text: "a".to_string(),
+            modifiers: Modifiers::default(),
         });
         dispatcher.dispatch(HookEvent::Filter {
             text: "ab".to_string(),
+            modifiers: Modifiers::default(),
         });
         dispatcher.dispatch(HookEvent::Filter {
             text: "abc".to_string(),
+            modifiers: Modifiers::default(),
         });
 
         // Advance past debounce window. sleep(0) processes
@@ -251,12 +255,14 @@ mod tests {
         dispatcher.dispatch(HookEvent::Hover {
             item: json!("a"),
             index: 0,
+            modifiers: Modifiers::default(),
         });
         // Wait a bit, then send second hover which cancels first
         tokio::time::sleep(Duration::from_millis(50)).await;
         dispatcher.dispatch(HookEvent::Hover {
             item: json!("b"),
             index: 1,
+            modifiers: Modifiers::default(),
         });
 
         // Advance past debounce for the second event

crates/pikl-core/src/runtime/hook.rs

@@ -7,6 +7,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
 use crate::error::PiklError;
+use crate::event::Modifiers;
 
 /// A lifecycle event emitted by the menu engine. Handler
 /// hooks receive these as JSON lines on stdin. The `event`
@@ -16,11 +17,33 @@ use crate::error::PiklError;
 pub enum HookEvent {
     Open,
     Close,
-    Hover { item: Value, index: usize },
-    Select { item: Value, index: usize },
-    Cancel,
-    Filter { text: String },
-    Quicklist { items: Vec<Value>, count: usize },
+    Hover {
+        item: Value,
+        index: usize,
+        #[serde(skip_serializing_if = "Modifiers::is_empty")]
+        modifiers: Modifiers,
+    },
+    Select {
+        item: Value,
+        index: usize,
+        #[serde(skip_serializing_if = "Modifiers::is_empty")]
+        modifiers: Modifiers,
+    },
+    Cancel {
+        #[serde(skip_serializing_if = "Modifiers::is_empty")]
+        modifiers: Modifiers,
+    },
+    Filter {
+        text: String,
+        #[serde(skip_serializing_if = "Modifiers::is_empty")]
+        modifiers: Modifiers,
+    },
+    Quicklist {
+        items: Vec<Value>,
+        count: usize,
+        #[serde(skip_serializing_if = "Modifiers::is_empty")]
+        modifiers: Modifiers,
+    },
 }
 
 /// Discriminant for [`HookEvent`], used as a key for
@@ -44,7 +67,7 @@ impl HookEvent {
             HookEvent::Close => HookEventKind::Close,
             HookEvent::Hover { .. } => HookEventKind::Hover,
             HookEvent::Select { .. } => HookEventKind::Select,
-            HookEvent::Cancel => HookEventKind::Cancel,
+            HookEvent::Cancel { .. } => HookEventKind::Cancel,
             HookEvent::Filter { .. } => HookEventKind::Filter,
             HookEvent::Quicklist { .. } => HookEventKind::Quicklist,
         }
@@ -116,11 +139,14 @@ mod tests {
         let event = HookEvent::Hover {
             item: json!({"label": "test"}),
             index: 5,
+            modifiers: Modifiers::default(),
         };
         let json = serde_json::to_value(&event).unwrap_or_default();
         assert_eq!(json["event"], "hover");
         assert_eq!(json["item"]["label"], "test");
         assert_eq!(json["index"], 5);
+        // Empty modifiers should be omitted
+        assert!(json.get("modifiers").is_none());
     }
 
     #[test]
@@ -128,6 +154,7 @@ mod tests {
         let event = HookEvent::Select {
             item: json!("hello"),
             index: 0,
+            modifiers: Modifiers::default(),
         };
         let json = serde_json::to_value(&event).unwrap_or_default();
         assert_eq!(json["event"], "select");
@@ -137,14 +164,19 @@ mod tests {
 
     #[test]
     fn event_cancel_serializes() {
-        let json = serde_json::to_value(&HookEvent::Cancel).unwrap_or_default();
+        let json = serde_json::to_value(&HookEvent::Cancel {
+            modifiers: Modifiers::default(),
+        })
+        .unwrap_or_default();
         assert_eq!(json["event"], "cancel");
+        assert!(json.get("modifiers").is_none());
     }
 
     #[test]
     fn event_filter_serializes() {
         let event = HookEvent::Filter {
             text: "foo".to_string(),
+            modifiers: Modifiers::default(),
         };
         let json = serde_json::to_value(&event).unwrap_or_default();
         assert_eq!(json["event"], "filter");
@@ -160,7 +192,8 @@ mod tests {
         assert_eq!(
             HookEvent::Hover {
                 item: json!(null),
-                index: 0
+                index: 0,
+                modifiers: Modifiers::default(),
             }
             .kind(),
             HookEventKind::Hover
@@ -168,15 +201,23 @@ mod tests {
         assert_eq!(
             HookEvent::Select {
                 item: json!(null),
-                index: 0
+                index: 0,
+                modifiers: Modifiers::default(),
             }
             .kind(),
             HookEventKind::Select
         );
-        assert_eq!(HookEvent::Cancel.kind(), HookEventKind::Cancel);
+        assert_eq!(
+            HookEvent::Cancel {
+                modifiers: Modifiers::default()
+            }
+            .kind(),
+            HookEventKind::Cancel
+        );
         assert_eq!(
             HookEvent::Filter {
-                text: String::new()
+                text: String::new(),
+                modifiers: Modifiers::default(),
             }
             .kind(),
             HookEventKind::Filter
@@ -291,6 +332,7 @@ mod tests {
         let event = HookEvent::Quicklist {
             items: vec![json!("alpha"), json!("beta")],
             count: 2,
+            modifiers: Modifiers::default(),
         };
         let json = serde_json::to_value(&event).unwrap_or_default();
         assert_eq!(json["event"], "quicklist");
@@ -303,6 +345,7 @@ mod tests {
         let event = HookEvent::Quicklist {
             items: vec![],
             count: 0,
+            modifiers: Modifiers::default(),
         };
         assert_eq!(event.kind(), HookEventKind::Quicklist);
     }
@@ -314,6 +357,7 @@ mod tests {
         let event = HookEvent::Hover {
             item: json!({"label": "Firefox", "url": "https://firefox.com"}),
             index: 2,
+            modifiers: Modifiers::default(),
         };
         let serialized = serde_json::to_string(&event).unwrap_or_default();
         let parsed: Value = serde_json::from_str(&serialized).unwrap_or_default();
@@ -321,4 +365,35 @@ mod tests {
         assert_eq!(parsed["item"]["label"], "Firefox");
         assert_eq!(parsed["index"], 2);
     }
+
+    // -- Modifier serialization in hook events --
+
+    #[test]
+    fn event_select_with_modifiers() {
+        let event = HookEvent::Select {
+            item: json!("test"),
+            index: 0,
+            modifiers: Modifiers {
+                shift: true,
+                ctrl: false,
+                alt: false,
+            },
+        };
+        let json = serde_json::to_value(&event).unwrap_or_default();
+        assert_eq!(json["modifiers"], json!(["shift"]));
+    }
+
+    #[test]
+    fn event_cancel_with_modifiers() {
+        let event = HookEvent::Cancel {
+            modifiers: Modifiers {
+                shift: true,
+                ctrl: true,
+                alt: false,
+            },
+        };
+        let json = serde_json::to_value(&event).unwrap_or_default();
+        assert_eq!(json["event"], "cancel");
+        assert_eq!(json["modifiers"], json!(["shift", "ctrl"]));
+    }
 }

crates/pikl-core/src/runtime/input.rs

@@ -8,6 +8,15 @@ use tokio::io::AsyncBufReadExt;
 use crate::error::PiklError;
 use crate::item::Item;
 
+/// Parse a single line into a JSON Value. Tries JSON first,
+/// falls back to wrapping as a string. Used by the streaming
+/// stdin reader in the CLI binary, which sends raw Values
+/// via `Action::AddItems`.
+pub fn parse_line_to_value(line: &str) -> serde_json::Value {
+    serde_json::from_str::<serde_json::Value>(line)
+        .unwrap_or_else(|_| serde_json::Value::String(line.to_string()))
+}
+
 /// Try to parse a line as JSON. Falls back to wrapping
 /// it as a plain-text string. The `label_key` controls
 /// which JSON key is used as the display label for object
@@ -116,4 +125,39 @@ mod tests {
         assert_eq!(items.len(), 1);
         assert_eq!(items[0].label(), "quoted string");
     }
+
+    #[test]
+    fn parse_line_to_value_plain_text() {
+        let v = parse_line_to_value("hello world");
+        assert_eq!(v, serde_json::Value::String("hello world".to_string()));
+    }
+
+    #[test]
+    fn parse_line_to_value_json_object() {
+        let v = parse_line_to_value(r#"{"label": "foo", "count": 42}"#);
+        assert!(v.is_object());
+        assert_eq!(v["label"], "foo");
+        assert_eq!(v["count"], 42);
+    }
+
+    #[test]
+    fn parse_line_to_value_invalid_json() {
+        let v = parse_line_to_value("{not valid json}");
+        assert_eq!(
+            v,
+            serde_json::Value::String("{not valid json}".to_string())
+        );
+    }
+
+    #[test]
+    fn parse_line_to_value_json_string() {
+        let v = parse_line_to_value(r#""quoted""#);
+        assert_eq!(v, serde_json::Value::String("quoted".to_string()));
+    }
+
+    #[test]
+    fn parse_line_to_value_json_number() {
+        let v = parse_line_to_value("42");
+        assert_eq!(v, serde_json::json!(42));
+    }
 }

crates/pikl-core/src/runtime/menu.rs

@@ -11,7 +11,10 @@ use tracing::{debug, info, trace};
 
 use crate::debounce::{DebouncedDispatcher, hook_response_to_action};
 use crate::error::PiklError;
-use crate::event::{Action, ColumnHeader, MenuEvent, MenuResult, Mode, ViewState, VisibleItem};
+use crate::event::{
+    Action, ColumnHeader, MenuEvent, MenuResult, ModifiedAction, Modifiers, Mode, ViewState,
+    VisibleItem,
+};
 use crate::hook::{HookEvent, HookHandler};
 use crate::model::traits::MutableMenu;
 use crate::navigation::Viewport;
@@ -147,13 +150,15 @@ pub struct MenuRunner<M: MutableMenu> {
     viewport: Viewport,
     filter_text: Arc<str>,
     mode: Mode,
-    action_rx: mpsc::Receiver<Action>,
+    action_rx: mpsc::Receiver<ModifiedAction>,
     event_tx: broadcast::Sender<MenuEvent>,
     dispatcher: Option<DebouncedDispatcher>,
     previous_cursor: Option<usize>,
     generation: u64,
     selection: SelectionState,
     visual_anchor: Option<usize>,
+    streaming: bool,
+    last_modifiers: Modifiers,
 }
 
 impl<M: MutableMenu> MenuRunner<M> {
@@ -161,7 +166,7 @@ impl<M: MutableMenu> MenuRunner<M> {
     /// Returns the runner and an action sender. Call
     /// [`subscribe`](Self::subscribe) to get an event handle,
     /// then [`run`](Self::run) to start the event loop.
-    pub fn new(menu: M) -> (Self, mpsc::Sender<Action>) {
+    pub fn new(menu: M) -> (Self, mpsc::Sender<ModifiedAction>) {
         let (action_tx, action_rx) = mpsc::channel(256);
         // 1024 slots: large enough that a burst of rapid state changes
         // (e.g. streaming AddItems + filter updates) won't cause lag for
@@ -180,6 +185,8 @@ impl<M: MutableMenu> MenuRunner<M> {
             generation: 0,
             selection: SelectionState::new(),
             visual_anchor: None,
+            streaming: false,
+            last_modifiers: Modifiers::default(),
         };
         (runner, action_tx)
     }
@@ -202,7 +209,7 @@ impl<M: MutableMenu> MenuRunner<M> {
     pub fn set_hook_handler(
         &mut self,
         handler: Arc<dyn HookHandler>,
-        action_tx: mpsc::Sender<Action>,
+        action_tx: mpsc::Sender<ModifiedAction>,
     ) {
         let dispatcher = DebouncedDispatcher::new(handler, action_tx);
         self.dispatcher = Some(dispatcher);
@@ -312,6 +319,7 @@ impl<M: MutableMenu> MenuRunner<M> {
             mode: self.mode,
             selection_count: self.selection.count(),
             multi_enabled: self.selection.multi_enabled,
+            streaming: self.streaming,
             columns,
             generation: self.generation,
         }
@@ -354,6 +362,7 @@ impl<M: MutableMenu> MenuRunner<M> {
                 self.emit_hook(HookEvent::Hover {
                     item: value,
                     index: orig_idx,
+                    modifiers: self.last_modifiers,
                 });
             }
         }
@@ -557,6 +566,11 @@ impl<M: MutableMenu> MenuRunner<M> {
                 self.apply_action(action)
             }
             Action::CloseMenu => ActionOutcome::Closed,
+            Action::StreamingDone => {
+                debug!("streaming done");
+                self.streaming = false;
+                ActionOutcome::Broadcast
+            }
         }
     }
 
@@ -566,6 +580,11 @@ impl<M: MutableMenu> MenuRunner<M> {
         self.mode = mode;
     }
 
+    /// Mark the menu as actively streaming items from stdin.
+    pub fn set_streaming(&mut self, v: bool) {
+        self.streaming = v;
+    }
+
     /// Run the menu event loop. Consumes actions and
     /// broadcasts events.
     ///
@@ -591,7 +610,9 @@ impl<M: MutableMenu> MenuRunner<M> {
         // Emit Open event
         self.emit_hook(HookEvent::Open);
 
-        while let Some(action) = self.action_rx.recv().await {
+        while let Some(modified) = self.action_rx.recv().await {
+            let ModifiedAction { action, modifiers } = modified;
+            self.last_modifiers = modifiers;
             let is_filter_update = matches!(&action, Action::UpdateFilter(_));
 
             match self.apply_action(action) {
@@ -601,7 +622,10 @@ impl<M: MutableMenu> MenuRunner<M> {
                     // Emit Filter event if the filter changed
                     if is_filter_update {
                         let text = self.filter_text.to_string();
-                        self.emit_hook(HookEvent::Filter { text });
+                        self.emit_hook(HookEvent::Filter {
+                            text,
+                            modifiers: self.last_modifiers,
+                        });
                     }
 
                     // Check for cursor movement -> Hover
@@ -615,6 +639,7 @@ impl<M: MutableMenu> MenuRunner<M> {
                         self.emit_hook(HookEvent::Select {
                             item: value.clone(),
                             index: *index,
+                            modifiers: self.last_modifiers,
                         });
                     }
                     // Emit Close event
@@ -624,6 +649,7 @@ impl<M: MutableMenu> MenuRunner<M> {
                     return Ok(MenuResult::Selected {
                         items,
                         filter_text: self.filter_text.to_string(),
+                        modifiers: self.last_modifiers,
                     });
                 }
                 ActionOutcome::Quicklist { items } => {
@@ -633,6 +659,7 @@ impl<M: MutableMenu> MenuRunner<M> {
                     self.emit_hook(HookEvent::Quicklist {
                         items: values.clone(),
                         count,
+                        modifiers: self.last_modifiers,
                     });
                     self.emit_hook(HookEvent::Close);
 
@@ -640,22 +667,29 @@ impl<M: MutableMenu> MenuRunner<M> {
                     return Ok(MenuResult::Quicklist {
                         items,
                         filter_text: self.filter_text.to_string(),
+                        modifiers: self.last_modifiers,
                     });
                 }
                 ActionOutcome::Cancelled => {
                     info!("menu cancelled");
-                    self.emit_hook(HookEvent::Cancel);
+                    self.emit_hook(HookEvent::Cancel {
+                        modifiers: self.last_modifiers,
+                    });
                     self.emit_hook(HookEvent::Close);
 
                     let _ = self.event_tx.send(MenuEvent::Cancelled);
-                    return Ok(MenuResult::Cancelled);
+                    return Ok(MenuResult::Cancelled {
+                        modifiers: self.last_modifiers,
+                    });
                 }
                 ActionOutcome::Closed => {
                     info!("menu closed by hook");
                     self.emit_hook(HookEvent::Close);
 
                     let _ = self.event_tx.send(MenuEvent::Cancelled);
-                    return Ok(MenuResult::Cancelled);
+                    return Ok(MenuResult::Cancelled {
+                        modifiers: Modifiers::default(),
+                    });
                 }
                 ActionOutcome::NoOp => {}
             }
@@ -663,7 +697,9 @@ impl<M: MutableMenu> MenuRunner<M> {
 
         // Sender dropped
         self.emit_hook(HookEvent::Close);
-        Ok(MenuResult::Cancelled)
+        Ok(MenuResult::Cancelled {
+            modifiers: Modifiers::default(),
+        })
     }
 }
 
@@ -675,7 +711,7 @@ mod tests {
     use crate::model::traits::Menu;
     use crate::runtime::json_menu::JsonMenu;
 
-    fn test_menu() -> (MenuRunner<JsonMenu>, mpsc::Sender<Action>) {
+    fn test_menu() -> (MenuRunner<JsonMenu>, mpsc::Sender<ModifiedAction>) {
         let items = vec![
             Item::from_plain_text("alpha"),
             Item::from_plain_text("beta"),
@@ -805,9 +841,9 @@ mod tests {
         }
 
         // Cancel to exit
-        let _ = tx.send(Action::Cancel).await;
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
-        assert!(matches!(result, Ok(MenuResult::Cancelled)));
+        let _ = tx.send(ModifiedAction::new(Action::Cancel)).await;
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
+        assert!(matches!(result, Ok(MenuResult::Cancelled { .. })));
     }
 
     #[tokio::test]
@@ -821,7 +857,7 @@ mod tests {
         let _ = rx.recv().await;
 
         // Filter to "al"
-        let _ = tx.send(Action::UpdateFilter("al".to_string())).await;
+        let _ = tx.send(ModifiedAction::new(Action::UpdateFilter("al".to_string()))).await;
         if let Ok(MenuEvent::StateChanged(vs)) = rx.recv().await {
             assert_eq!(vs.total_items, 4);
             // alpha should match "al"
@@ -829,7 +865,7 @@ mod tests {
             assert_eq!(&*vs.filter_text, "al");
         }
 
-        let _ = tx.send(Action::Cancel).await;
+        let _ = tx.send(ModifiedAction::new(Action::Cancel)).await;
         let _ = handle.await;
     }
 
@@ -844,20 +880,20 @@ mod tests {
         let _ = rx.recv().await;
 
         // Need to send resize first so viewport has height
-        let _ = tx.send(Action::Resize { height: 10 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 10 })).await;
         let _ = rx.recv().await;
 
         // Move down and confirm
-        let _ = tx.send(Action::MoveDown(1)).await;
+        let _ = tx.send(ModifiedAction::new(Action::MoveDown(1))).await;
         let _ = rx.recv().await;
-        let _ = tx.send(Action::Confirm).await;
+        let _ = tx.send(ModifiedAction::new(Action::Confirm)).await;
 
         // Should get Selected event
         if let Ok(MenuEvent::Selected(items)) = rx.recv().await {
             assert_eq!(items[0].0.as_str(), Some("beta"));
         }
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         assert!(matches!(result, Ok(MenuResult::Selected { .. })));
     }
 
@@ -871,18 +907,18 @@ mod tests {
         let _ = rx.recv().await; // initial
 
         // Filter to something that matches nothing
-        let _ = tx.send(Action::UpdateFilter("zzzzz".to_string())).await;
+        let _ = tx.send(ModifiedAction::new(Action::UpdateFilter("zzzzz".to_string()))).await;
         if let Ok(MenuEvent::StateChanged(vs)) = rx.recv().await {
             assert_eq!(vs.total_filtered, 0);
         }
 
         // Confirm should be no-op
-        let _ = tx.send(Action::Confirm).await;
+        let _ = tx.send(ModifiedAction::new(Action::Confirm)).await;
 
         // Cancel to exit (should still work)
-        let _ = tx.send(Action::Cancel).await;
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
-        assert!(matches!(result, Ok(MenuResult::Cancelled)));
+        let _ = tx.send(ModifiedAction::new(Action::Cancel)).await;
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
+        assert!(matches!(result, Ok(MenuResult::Cancelled { .. })));
     }
 
     #[tokio::test]
@@ -895,8 +931,8 @@ mod tests {
         // Drop the only sender.
         drop(tx);
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
-        assert!(matches!(result, Ok(MenuResult::Cancelled)));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
+        assert!(matches!(result, Ok(MenuResult::Cancelled { .. })));
     }
 
     // -- End-to-end output correctness --
@@ -909,18 +945,18 @@ mod tests {
         let handle = tokio::spawn(async move { menu.run().await });
 
         let _ = rx.recv().await; // initial state
-        let _ = tx.send(Action::Resize { height: 10 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 10 })).await;
         let _ = rx.recv().await;
 
         // Confirm at cursor 0, should get "alpha"
-        let _ = tx.send(Action::Confirm).await;
+        let _ = tx.send(ModifiedAction::new(Action::Confirm)).await;
 
         let event = rx.recv().await;
         assert!(
             matches!(&event, Ok(MenuEvent::Selected(items)) if items[0].0.as_str() == Some("alpha"))
         );
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         assert!(
             matches!(result, Ok(MenuResult::Selected { ref items, .. }) if items[0].0.as_str() == Some("alpha"))
         );
@@ -934,17 +970,17 @@ mod tests {
         let handle = tokio::spawn(async move { menu.run().await });
 
         let _ = rx.recv().await; // initial
-        let _ = tx.send(Action::Resize { height: 10 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 10 })).await;
         let _ = rx.recv().await;
 
         // Move down twice -> cursor at index 2 -> "gamma"
-        let _ = tx.send(Action::MoveDown(1)).await;
+        let _ = tx.send(ModifiedAction::new(Action::MoveDown(1))).await;
         let _ = rx.recv().await;
-        let _ = tx.send(Action::MoveDown(1)).await;
+        let _ = tx.send(ModifiedAction::new(Action::MoveDown(1))).await;
         let _ = rx.recv().await;
-        let _ = tx.send(Action::Confirm).await;
+        let _ = tx.send(ModifiedAction::new(Action::Confirm)).await;
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         assert!(
             matches!(result, Ok(MenuResult::Selected { ref items, .. }) if items[0].0.as_str() == Some("gamma"))
         );
@@ -958,20 +994,20 @@ mod tests {
         let handle = tokio::spawn(async move { menu.run().await });
 
         let _ = rx.recv().await; // initial
-        let _ = tx.send(Action::Resize { height: 10 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 10 })).await;
         let _ = rx.recv().await;
 
         // Filter to "del", should match "delta"
-        let _ = tx.send(Action::UpdateFilter("del".to_string())).await;
+        let _ = tx.send(ModifiedAction::new(Action::UpdateFilter("del".to_string()))).await;
         if let Ok(MenuEvent::StateChanged(vs)) = rx.recv().await {
             assert!(vs.total_filtered >= 1);
             assert_eq!(vs.visible_items[0].label, "delta");
         }
 
         // Confirm, should select "delta"
-        let _ = tx.send(Action::Confirm).await;
+        let _ = tx.send(ModifiedAction::new(Action::Confirm)).await;
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         assert!(
             matches!(result, Ok(MenuResult::Selected { ref items, .. }) if items[0].0.as_str() == Some("delta"))
         );
@@ -985,14 +1021,14 @@ mod tests {
         let handle = tokio::spawn(async move { menu.run().await });
 
         let _ = rx.recv().await; // initial
-        let _ = tx.send(Action::Resize { height: 10 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 10 })).await;
         let _ = rx.recv().await;
 
         // Add a new item
         let _ = tx
-            .send(Action::AddItems(vec![serde_json::Value::String(
-                "epsilon".to_string(),
-            )]))
+            .send(ModifiedAction::new(Action::AddItems(vec![
+                serde_json::Value::String("epsilon".to_string()),
+            ])))
             .await;
         if let Ok(MenuEvent::StateChanged(vs)) = rx.recv().await {
             assert_eq!(vs.total_items, 5);
@@ -1000,15 +1036,15 @@ mod tests {
         }
 
         // Filter to "eps", only epsilon should match
-        let _ = tx.send(Action::UpdateFilter("eps".to_string())).await;
+        let _ = tx.send(ModifiedAction::new(Action::UpdateFilter("eps".to_string()))).await;
         if let Ok(MenuEvent::StateChanged(vs)) = rx.recv().await {
             assert!(vs.total_filtered >= 1);
             assert_eq!(vs.visible_items[0].label, "epsilon");
         }
 
-        let _ = tx.send(Action::Confirm).await;
+        let _ = tx.send(ModifiedAction::new(Action::Confirm)).await;
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         assert!(
             matches!(result, Ok(MenuResult::Selected { ref items, .. }) if items[0].0.as_str() == Some("epsilon"))
         );
@@ -1023,13 +1059,13 @@ mod tests {
 
         let _ = rx.recv().await; // initial
 
-        let _ = tx.send(Action::Cancel).await;
+        let _ = tx.send(ModifiedAction::new(Action::Cancel)).await;
 
         // Should get Cancelled event
         assert!(matches!(rx.recv().await, Ok(MenuEvent::Cancelled)));
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
-        assert!(matches!(result, Ok(MenuResult::Cancelled)));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
+        assert!(matches!(result, Ok(MenuResult::Cancelled { .. })));
     }
 
     // -- Ordering invariant tests --
@@ -1052,14 +1088,14 @@ mod tests {
         let handle = tokio::spawn(async move { menu.run().await });
 
         let _ = rx.recv().await; // initial
-        let _ = tx.send(Action::Resize { height: 50 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 50 })).await;
         let _ = rx.recv().await;
 
         // Back-to-back, no waiting between these
-        let _ = tx.send(Action::UpdateFilter("ban".to_string())).await;
-        let _ = tx.send(Action::Confirm).await;
+        let _ = tx.send(ModifiedAction::new(Action::UpdateFilter("ban".to_string()))).await;
+        let _ = tx.send(ModifiedAction::new(Action::Confirm)).await;
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         // Must get "banana". Filter was applied before confirm ran.
         assert!(matches!(
             result,
@@ -1076,16 +1112,16 @@ mod tests {
         let handle = tokio::spawn(async move { menu.run().await });
 
         let _ = rx.recv().await; // initial
-        let _ = tx.send(Action::Resize { height: 50 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 50 })).await;
         let _ = rx.recv().await;
 
         // Three moves down back-to-back, then confirm
-        let _ = tx.send(Action::MoveDown(1)).await;
-        let _ = tx.send(Action::MoveDown(1)).await;
-        let _ = tx.send(Action::MoveDown(1)).await;
-        let _ = tx.send(Action::Confirm).await;
+        let _ = tx.send(ModifiedAction::new(Action::MoveDown(1))).await;
+        let _ = tx.send(ModifiedAction::new(Action::MoveDown(1))).await;
+        let _ = tx.send(ModifiedAction::new(Action::MoveDown(1))).await;
+        let _ = tx.send(ModifiedAction::new(Action::Confirm)).await;
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         // Cursor at index 3 -> "delta"
         assert!(matches!(
             result,
@@ -1169,19 +1205,19 @@ mod tests {
         let handle = tokio::spawn(async move { menu.run().await });
 
         let _ = rx.recv().await; // initial
-        let _ = tx.send(Action::Resize { height: 50 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 50 })).await;
         let _ = rx.recv().await;
 
         // All back-to-back
         let _ = tx
-            .send(Action::AddItems(vec![serde_json::Value::String(
-                "zephyr".to_string(),
-            )]))
+            .send(ModifiedAction::new(Action::AddItems(vec![
+                serde_json::Value::String("zephyr".to_string()),
+            ])))
             .await;
-        let _ = tx.send(Action::UpdateFilter("zep".to_string())).await;
-        let _ = tx.send(Action::Confirm).await;
+        let _ = tx.send(ModifiedAction::new(Action::UpdateFilter("zep".to_string()))).await;
+        let _ = tx.send(ModifiedAction::new(Action::Confirm)).await;
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         // Must find "zephyr". It was added before the filter ran.
         assert!(matches!(
             result,
@@ -1340,10 +1376,10 @@ mod tests {
 
         // Skip initial state
         let _ = rx.recv().await;
-        let _ = tx.send(Action::Resize { height: 10 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 10 })).await;
         let _ = rx.recv().await;
 
-        let _ = tx.send(Action::Quicklist).await;
+        let _ = tx.send(ModifiedAction::new(Action::Quicklist)).await;
 
         if let Ok(MenuEvent::Quicklist(values)) = rx.recv().await {
             assert_eq!(values.len(), 4);
@@ -1351,7 +1387,7 @@ mod tests {
             panic!("expected Quicklist event");
         }
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         assert!(matches!(result, Ok(MenuResult::Quicklist { .. })));
     }
 
@@ -1363,14 +1399,14 @@ mod tests {
         let handle = tokio::spawn(async move { menu.run().await });
 
         let _ = rx.recv().await; // initial
-        let _ = tx.send(Action::Resize { height: 10 }).await;
+        let _ = tx.send(ModifiedAction::new(Action::Resize { height: 10 })).await;
         let _ = rx.recv().await;
 
         // Filter then quicklist back-to-back
-        let _ = tx.send(Action::UpdateFilter("al".to_string())).await;
-        let _ = tx.send(Action::Quicklist).await;
+        let _ = tx.send(ModifiedAction::new(Action::UpdateFilter("al".to_string()))).await;
+        let _ = tx.send(ModifiedAction::new(Action::Quicklist)).await;
 
-        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+        let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: Modifiers::default() }));
         match result {
             Ok(MenuResult::Quicklist { items, .. }) => {
                 // "alpha" matches "al"
@@ -1416,6 +1452,7 @@ mod tests {
         m.apply_action(Action::UpdateFilter("al".to_string()));
         m.emit_hook(HookEvent::Filter {
             text: "al".to_string(),
+            modifiers: Modifiers::default(),
         });
         m.apply_action(Action::MoveDown(1));
         m.check_cursor_hover();
@@ -1824,4 +1861,54 @@ mod tests {
         // City "toronto" (7) vs header "City" (4): width = 7
         assert_eq!(cols[2].width, 7);
     }
+
+    // -- Streaming tests --
+
+    #[test]
+    fn streaming_done_sets_streaming_false() {
+        let (mut m, _tx) = test_menu();
+        m.set_streaming(true);
+        m.run_filter();
+        assert!(m.build_view_state().streaming);
+        let outcome = m.apply_action(Action::StreamingDone);
+        assert!(matches!(outcome, ActionOutcome::Broadcast));
+        assert!(!m.build_view_state().streaming);
+    }
+
+    #[test]
+    fn add_items_on_empty_streaming_menu() {
+        let (mut m, _tx) = MenuRunner::new(JsonMenu::new(vec![], "label".to_string()));
+        m.set_streaming(true);
+        m.run_filter();
+        m.apply_action(Action::Resize { height: 20 });
+
+        assert_eq!(m.menu.total(), 0);
+        assert!(m.build_view_state().streaming);
+
+        m.apply_action(Action::AddItems(vec![
+            Value::String("one".into()),
+            Value::String("two".into()),
+        ]));
+        assert_eq!(m.menu.total(), 2);
+        assert_eq!(m.menu.filtered_count(), 2);
+
+        // Confirm on non-empty streaming menu works
+        let outcome = m.apply_action(Action::Confirm);
+        assert!(matches!(outcome, ActionOutcome::Selected { .. }));
+    }
+
+    #[test]
+    fn confirm_on_empty_streaming_menu_is_noop() {
+        let (mut m, _tx) = MenuRunner::new(JsonMenu::new(vec![], "label".to_string()));
+        m.set_streaming(true);
+        m.run_filter();
+        let outcome = m.apply_action(Action::Confirm);
+        assert!(matches!(outcome, ActionOutcome::NoOp));
+    }
+
+    #[test]
+    fn view_state_streaming_defaults_false() {
+        let mut m = ready_menu();
+        assert!(!m.build_view_state().streaming);
+    }
 }

crates/pikl-core/src/script/action_fd/mod.rs

@@ -14,7 +14,7 @@ pub mod parse;
 use tokio::sync::mpsc;
 
 use crate::error::PiklError;
-use crate::event::Action;
+use crate::event::{Action, ModifiedAction, Modifiers};
 
 pub use error::{ScriptError, ScriptErrorKind};
 pub use parse::{load_script, parse_action};
@@ -22,7 +22,7 @@ pub use parse::{load_script, parse_action};
 /// A parsed action from an action-fd script.
 #[derive(Debug, Clone, PartialEq)]
 pub enum ScriptAction {
-    Core(Action),
+    Core(Action, Modifiers),
     ShowUi,
     ShowTui,
     ShowGui,
@@ -41,14 +41,14 @@ pub enum ShowAction {
 /// Returns the Show* variant if the script ends with one, or None.
 pub async fn run_script(
     script: Vec<ScriptAction>,
-    tx: &mpsc::Sender<Action>,
+    tx: &mpsc::Sender<ModifiedAction>,
 ) -> Result<Option<ShowAction>, PiklError> {
     let mut show = None;
 
     for action in script {
         match action {
-            ScriptAction::Core(action) => {
-                tx.send(action)
+            ScriptAction::Core(action, modifiers) => {
+                tx.send(ModifiedAction { action, modifiers })
                     .await
                     .map_err(|_| PiklError::ChannelClosed)?;
             }
@@ -69,9 +69,9 @@ mod tests {
     #[tokio::test]
     async fn run_script_sends_actions_in_order() {
         let script = vec![
-            ScriptAction::Core(Action::UpdateFilter("hello".to_string())),
-            ScriptAction::Core(Action::MoveDown(1)),
-            ScriptAction::Core(Action::Confirm),
+            ScriptAction::Core(Action::UpdateFilter("hello".to_string()), Modifiers::default()),
+            ScriptAction::Core(Action::MoveDown(1), Modifiers::default()),
+            ScriptAction::Core(Action::Confirm, Modifiers::default()),
         ];
         let (tx, mut rx) = mpsc::channel(16);
         let result = run_script(script, &tx).await;
@@ -79,14 +79,14 @@ mod tests {
         assert_eq!(result.unwrap_or(Some(ShowAction::Ui)), None);
 
         // Verify order
-        assert!(matches!(rx.recv().await, Some(Action::UpdateFilter(s)) if s == "hello"));
-        assert!(matches!(rx.recv().await, Some(Action::MoveDown(1))));
-        assert!(matches!(rx.recv().await, Some(Action::Confirm)));
+        assert!(matches!(rx.recv().await, Some(ModifiedAction { action: Action::UpdateFilter(s), .. }) if s == "hello"));
+        assert!(matches!(rx.recv().await, Some(ModifiedAction { action: Action::MoveDown(1), .. })));
+        assert!(matches!(rx.recv().await, Some(ModifiedAction { action: Action::Confirm, .. })));
     }
 
     #[tokio::test]
     async fn run_script_returns_none_without_show() {
-        let script = vec![ScriptAction::Core(Action::Confirm)];
+        let script = vec![ScriptAction::Core(Action::Confirm, Modifiers::default())];
         let (tx, _rx) = mpsc::channel(16);
         let result = run_script(script, &tx).await;
         assert!(result.is_ok());
@@ -96,7 +96,7 @@ mod tests {
     #[tokio::test]
     async fn run_script_returns_show_action() {
         let script = vec![
-            ScriptAction::Core(Action::UpdateFilter("test".to_string())),
+            ScriptAction::Core(Action::UpdateFilter("test".to_string()), Modifiers::default()),
             ScriptAction::ShowUi,
         ];
         let (tx, _rx) = mpsc::channel(16);

crates/pikl-core/src/script/action_fd/parse.rs

@@ -4,7 +4,7 @@
 
 use std::io::BufRead;
 
-use crate::event::{Action, Mode};
+use crate::event::{Action, Mode, Modifiers};
 
 use super::ScriptAction;
 use super::error::{ScriptError, ScriptErrorKind};
@@ -82,6 +82,30 @@ fn parse_positive_u16(
     }
 }
 
+/// Parse modifier prefixes from the start of a trimmed line.
+/// Returns (modifiers, remaining_line).
+fn parse_modifier_prefix(line: &str) -> Result<(Modifiers, &str), Option<String>> {
+    let mut mods = Modifiers::default();
+    let mut rest = line;
+
+    while let Some(stripped) = rest.strip_prefix('+') {
+        // Find the end of this modifier token (next space or '+')
+        let end = stripped
+            .find([' ', '+'])
+            .unwrap_or(stripped.len());
+        let token = &stripped[..end];
+        match token {
+            "shift" => mods.shift = true,
+            "ctrl" => mods.ctrl = true,
+            "alt" => mods.alt = true,
+            other => return Err(Some(format!("unknown modifier '+{other}'"))),
+        }
+        rest = stripped[end..].trim_start();
+    }
+
+    Ok((mods, rest))
+}
+
 /// Parse a single line into a ScriptAction.
 pub fn parse_action(line_number: usize, line: &str) -> Result<ScriptAction, ScriptError> {
     let trimmed = line.trim();
@@ -90,41 +114,66 @@ pub fn parse_action(line_number: usize, line: &str) -> Result<ScriptAction, Scri
         return Ok(ScriptAction::Comment);
     }
 
-    let (cmd, arg) = match trimmed.split_once(' ') {
+    // Parse optional modifier prefixes (+shift, +ctrl, +alt)
+    let (modifiers, rest) = parse_modifier_prefix(trimmed).map_err(|msg| ScriptError {
+        line: line_number,
+        source_line: line.to_string(),
+        kind: ScriptErrorKind::InvalidArgument {
+            action: String::new(),
+            message: msg.unwrap_or_default(),
+        },
+    })?;
+
+    if rest.is_empty() {
+        return Err(ScriptError {
+            line: line_number,
+            source_line: line.to_string(),
+            kind: ScriptErrorKind::InvalidArgument {
+                action: String::new(),
+                message: "modifier prefix without an action".to_string(),
+            },
+        });
+    }
+
+    let (cmd, arg) = match rest.split_once(' ') {
         Some((c, a)) => (c, Some(a)),
-        None => (trimmed, None),
+        None => (rest, None),
+    };
+
+    let core = |action: Action| -> Result<ScriptAction, ScriptError> {
+        Ok(ScriptAction::Core(action, modifiers))
     };
 
     match cmd {
         "filter" => {
             let text = arg.unwrap_or("");
-            Ok(ScriptAction::Core(Action::UpdateFilter(text.to_string())))
+            core(Action::UpdateFilter(text.to_string()))
         }
         "move-up" => {
             let n = parse_count(line_number, line, "move-up", arg)?;
-            Ok(ScriptAction::Core(Action::MoveUp(n)))
+            core(Action::MoveUp(n))
         }
         "move-down" => {
             let n = parse_count(line_number, line, "move-down", arg)?;
-            Ok(ScriptAction::Core(Action::MoveDown(n)))
+            core(Action::MoveDown(n))
         }
-        "move-to-top" => Ok(ScriptAction::Core(Action::MoveToTop)),
-        "move-to-bottom" => Ok(ScriptAction::Core(Action::MoveToBottom)),
+        "move-to-top" => core(Action::MoveToTop),
+        "move-to-bottom" => core(Action::MoveToBottom),
         "page-up" => {
             let n = parse_count(line_number, line, "page-up", arg)?;
-            Ok(ScriptAction::Core(Action::PageUp(n)))
+            core(Action::PageUp(n))
         }
         "page-down" => {
             let n = parse_count(line_number, line, "page-down", arg)?;
-            Ok(ScriptAction::Core(Action::PageDown(n)))
+            core(Action::PageDown(n))
         }
         "half-page-up" => {
             let n = parse_count(line_number, line, "half-page-up", arg)?;
-            Ok(ScriptAction::Core(Action::HalfPageUp(n)))
+            core(Action::HalfPageUp(n))
         }
         "half-page-down" => {
             let n = parse_count(line_number, line, "half-page-down", arg)?;
-            Ok(ScriptAction::Core(Action::HalfPageDown(n)))
+            core(Action::HalfPageDown(n))
         }
         "set-mode" => {
             let Some(mode_str) = arg else {
@@ -136,9 +185,9 @@ pub fn parse_action(line_number: usize, line: &str) -> Result<ScriptAction, Scri
                 ));
             };
             match mode_str.trim() {
-                "insert" => Ok(ScriptAction::Core(Action::SetMode(Mode::Insert))),
-                "normal" => Ok(ScriptAction::Core(Action::SetMode(Mode::Normal))),
-                "visual" => Ok(ScriptAction::Core(Action::SetMode(Mode::Visual))),
+                "insert" => core(Action::SetMode(Mode::Insert)),
+                "normal" => core(Action::SetMode(Mode::Normal)),
+                "visual" => core(Action::SetMode(Mode::Visual)),
                 other => Err(invalid_arg(
                     line_number,
                     line,
@@ -147,20 +196,21 @@ pub fn parse_action(line_number: usize, line: &str) -> Result<ScriptAction, Scri
                 )),
             }
         }
-        "toggle-select" => Ok(ScriptAction::Core(Action::ToggleSelect)),
-        "select-all" => Ok(ScriptAction::Core(Action::SelectAll)),
-        "deselect-all" => Ok(ScriptAction::Core(Action::ClearSelections)),
-        "undo-selection" => Ok(ScriptAction::Core(Action::UndoSelection)),
-        "redo-selection" => Ok(ScriptAction::Core(Action::RedoSelection)),
-        "confirm" => Ok(ScriptAction::Core(Action::Confirm)),
-        "cancel" => Ok(ScriptAction::Core(Action::Cancel)),
+        "toggle-select" => core(Action::ToggleSelect),
+        "select-all" => core(Action::SelectAll),
+        "deselect-all" => core(Action::ClearSelections),
+        "undo-selection" => core(Action::UndoSelection),
+        "redo-selection" => core(Action::RedoSelection),
+        "confirm" => core(Action::Confirm),
+        "cancel" => core(Action::Cancel),
         "resize" => {
             let height = parse_positive_u16(line_number, line, "resize", arg)?;
-            Ok(ScriptAction::Core(Action::Resize { height }))
+            core(Action::Resize { height })
         }
         "show-ui" => Ok(ScriptAction::ShowUi),
         "show-tui" => Ok(ScriptAction::ShowTui),
         "show-gui" => Ok(ScriptAction::ShowGui),
+        "streaming-done" => core(Action::StreamingDone),
         _ => Err(ScriptError {
             line: line_number,
             source_line: line.to_string(),
@@ -243,7 +293,7 @@ mod tests {
         assert!(result.is_ok());
         assert_eq!(
             result.unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::UpdateFilter("hello world".to_string()))
+            ScriptAction::Core(Action::UpdateFilter("hello world".to_string()), Modifiers::default())
         );
     }
 
@@ -253,7 +303,7 @@ mod tests {
         assert!(result.is_ok());
         assert_eq!(
             result.unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::UpdateFilter(String::new()))
+            ScriptAction::Core(Action::UpdateFilter(String::new()), Modifiers::default())
         );
     }
 
@@ -261,27 +311,27 @@ mod tests {
     fn parse_movement_actions() {
         assert_eq!(
             parse_action(1, "move-up").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::MoveUp(1))
+            ScriptAction::Core(Action::MoveUp(1), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "move-down").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::MoveDown(1))
+            ScriptAction::Core(Action::MoveDown(1), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "move-to-top").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::MoveToTop)
+            ScriptAction::Core(Action::MoveToTop, Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "move-to-bottom").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::MoveToBottom)
+            ScriptAction::Core(Action::MoveToBottom, Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "page-up").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::PageUp(1))
+            ScriptAction::Core(Action::PageUp(1), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "page-down").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::PageDown(1))
+            ScriptAction::Core(Action::PageDown(1), Modifiers::default())
         );
     }
 
@@ -289,19 +339,19 @@ mod tests {
     fn parse_movement_with_count() {
         assert_eq!(
             parse_action(1, "move-up 5").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::MoveUp(5))
+            ScriptAction::Core(Action::MoveUp(5), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "move-down 3").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::MoveDown(3))
+            ScriptAction::Core(Action::MoveDown(3), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "page-up 2").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::PageUp(2))
+            ScriptAction::Core(Action::PageUp(2), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "page-down 10").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::PageDown(10))
+            ScriptAction::Core(Action::PageDown(10), Modifiers::default())
         );
     }
 
@@ -323,11 +373,11 @@ mod tests {
     fn parse_confirm_cancel() {
         assert_eq!(
             parse_action(1, "confirm").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::Confirm)
+            ScriptAction::Core(Action::Confirm, Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "cancel").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::Cancel)
+            ScriptAction::Core(Action::Cancel, Modifiers::default())
         );
     }
 
@@ -335,7 +385,7 @@ mod tests {
     fn parse_resize_valid() {
         assert_eq!(
             parse_action(1, "resize 25").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::Resize { height: 25 })
+            ScriptAction::Core(Action::Resize { height: 25 }, Modifiers::default())
         );
     }
 
@@ -404,19 +454,19 @@ mod tests {
     fn parse_half_page_actions() {
         assert_eq!(
             parse_action(1, "half-page-up").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::HalfPageUp(1))
+            ScriptAction::Core(Action::HalfPageUp(1), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "half-page-down").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::HalfPageDown(1))
+            ScriptAction::Core(Action::HalfPageDown(1), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "half-page-up 3").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::HalfPageUp(3))
+            ScriptAction::Core(Action::HalfPageUp(3), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "half-page-down 2").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::HalfPageDown(2))
+            ScriptAction::Core(Action::HalfPageDown(2), Modifiers::default())
         );
     }
 
@@ -430,11 +480,11 @@ mod tests {
     fn parse_set_mode() {
         assert_eq!(
             parse_action(1, "set-mode insert").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::SetMode(Mode::Insert))
+            ScriptAction::Core(Action::SetMode(Mode::Insert), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "set-mode normal").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::SetMode(Mode::Normal))
+            ScriptAction::Core(Action::SetMode(Mode::Normal), Modifiers::default())
         );
     }
 
@@ -447,7 +497,7 @@ mod tests {
     fn parse_set_mode_invalid() {
         assert_eq!(
             parse_action(1, "set-mode visual").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::SetMode(Mode::Visual))
+            ScriptAction::Core(Action::SetMode(Mode::Visual), Modifiers::default())
         );
     }
 
@@ -518,7 +568,7 @@ mod tests {
             ParsedLine {
                 line_number: 1,
                 source: "filter test".into(),
-                action: ScriptAction::Core(Action::UpdateFilter("test".into())),
+                action: ScriptAction::Core(Action::UpdateFilter("test".into()), Modifiers::default()),
             },
             ParsedLine {
                 line_number: 2,
@@ -540,7 +590,7 @@ mod tests {
             ParsedLine {
                 line_number: 2,
                 source: "confirm".into(),
-                action: ScriptAction::Core(Action::Confirm),
+                action: ScriptAction::Core(Action::Confirm, Modifiers::default()),
             },
         ];
         let err = validate_show_last(&actions).unwrap_err();
@@ -554,7 +604,7 @@ mod tests {
             ParsedLine {
                 line_number: 1,
                 source: "filter x".into(),
-                action: ScriptAction::Core(Action::UpdateFilter("x".into())),
+                action: ScriptAction::Core(Action::UpdateFilter("x".into()), Modifiers::default()),
             },
             ParsedLine {
                 line_number: 2,
@@ -564,7 +614,7 @@ mod tests {
             ParsedLine {
                 line_number: 3,
                 source: "confirm".into(),
-                action: ScriptAction::Core(Action::Confirm),
+                action: ScriptAction::Core(Action::Confirm, Modifiers::default()),
             },
         ];
         let err = validate_show_last(&actions).unwrap_err();
@@ -588,12 +638,12 @@ mod tests {
             ParsedLine {
                 line_number: 1,
                 source: "filter x".into(),
-                action: ScriptAction::Core(Action::UpdateFilter("x".into())),
+                action: ScriptAction::Core(Action::UpdateFilter("x".into()), Modifiers::default()),
             },
             ParsedLine {
                 line_number: 2,
                 source: "confirm".into(),
-                action: ScriptAction::Core(Action::Confirm),
+                action: ScriptAction::Core(Action::Confirm, Modifiers::default()),
             },
         ];
         assert!(validate_show_last(&actions).is_ok());
@@ -658,23 +708,31 @@ mod tests {
     fn parse_selection_actions() {
         assert_eq!(
             parse_action(1, "toggle-select").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::ToggleSelect)
+            ScriptAction::Core(Action::ToggleSelect, Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "select-all").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::SelectAll)
+            ScriptAction::Core(Action::SelectAll, Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "deselect-all").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::ClearSelections)
+            ScriptAction::Core(Action::ClearSelections, Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "undo-selection").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::UndoSelection)
+            ScriptAction::Core(Action::UndoSelection, Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "redo-selection").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::RedoSelection)
+            ScriptAction::Core(Action::RedoSelection, Modifiers::default())
+        );
+    }
+
+    #[test]
+    fn parse_streaming_done() {
+        assert_eq!(
+            parse_action(1, "streaming-done").unwrap_or(ScriptAction::Comment),
+            ScriptAction::Core(Action::StreamingDone, Modifiers::default())
         );
     }
 
@@ -690,11 +748,11 @@ mod tests {
         // Extra whitespace around the mode value should be trimmed
         assert_eq!(
             parse_action(1, "set-mode  insert ").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::SetMode(Mode::Insert))
+            ScriptAction::Core(Action::SetMode(Mode::Insert), Modifiers::default())
         );
         assert_eq!(
             parse_action(1, "set-mode  normal ").unwrap_or(ScriptAction::Comment),
-            ScriptAction::Core(Action::SetMode(Mode::Normal))
+            ScriptAction::Core(Action::SetMode(Mode::Normal), Modifiers::default())
         );
     }
 
@@ -705,16 +763,96 @@ mod tests {
         assert!(result.is_ok());
         let actions = result.unwrap_or_default();
         assert_eq!(actions.len(), 5);
-        assert_eq!(actions[0], ScriptAction::Core(Action::HalfPageUp(2)));
+        assert_eq!(actions[0], ScriptAction::Core(Action::HalfPageUp(2), Modifiers::default()));
         assert_eq!(
             actions[1],
-            ScriptAction::Core(Action::SetMode(Mode::Normal))
+            ScriptAction::Core(Action::SetMode(Mode::Normal), Modifiers::default())
         );
         assert_eq!(
             actions[2],
-            ScriptAction::Core(Action::SetMode(Mode::Insert))
+            ScriptAction::Core(Action::SetMode(Mode::Insert), Modifiers::default())
         );
-        assert_eq!(actions[3], ScriptAction::Core(Action::HalfPageDown(1)));
-        assert_eq!(actions[4], ScriptAction::Core(Action::Confirm));
+        assert_eq!(actions[3], ScriptAction::Core(Action::HalfPageDown(1), Modifiers::default()));
+        assert_eq!(actions[4], ScriptAction::Core(Action::Confirm, Modifiers::default()));
+    }
+
+    // -- Modifier prefix tests --
+
+    #[test]
+    fn parse_shift_prefix() {
+        let result = parse_action(1, "+shift confirm");
+        assert!(result.is_ok());
+        let expected_mods = Modifiers {
+            shift: true,
+            ctrl: false,
+            alt: false,
+        };
+        assert_eq!(
+            result.unwrap_or(ScriptAction::Comment),
+            ScriptAction::Core(Action::Confirm, expected_mods)
+        );
+    }
+
+    #[test]
+    fn parse_multiple_modifier_prefixes() {
+        let result = parse_action(1, "+ctrl+alt move-down 3");
+        assert!(result.is_ok());
+        let expected_mods = Modifiers {
+            shift: false,
+            ctrl: true,
+            alt: true,
+        };
+        assert_eq!(
+            result.unwrap_or(ScriptAction::Comment),
+            ScriptAction::Core(Action::MoveDown(3), expected_mods)
+        );
+    }
+
+    #[test]
+    fn parse_all_modifier_prefixes() {
+        let result = parse_action(1, "+shift+ctrl+alt cancel");
+        assert!(result.is_ok());
+        let expected_mods = Modifiers {
+            shift: true,
+            ctrl: true,
+            alt: true,
+        };
+        assert_eq!(
+            result.unwrap_or(ScriptAction::Comment),
+            ScriptAction::Core(Action::Cancel, expected_mods)
+        );
+    }
+
+    #[test]
+    fn parse_unknown_modifier_is_error() {
+        let result = parse_action(1, "+super confirm");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn parse_modifier_without_action_is_error() {
+        let result = parse_action(1, "+shift");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn parse_no_modifier_prefix_has_empty_modifiers() {
+        let result = parse_action(1, "confirm");
+        assert!(result.is_ok());
+        assert_eq!(
+            result.unwrap_or(ScriptAction::Comment),
+            ScriptAction::Core(Action::Confirm, Modifiers::default())
+        );
+    }
+
+    #[test]
+    fn parse_modifier_with_space_separated() {
+        // "+shift confirm" should work
+        let result = parse_action(1, "+shift confirm");
+        assert!(result.is_ok());
+        if let Ok(ScriptAction::Core(_, mods)) = result {
+            assert!(mods.shift);
+            assert!(!mods.ctrl);
+        }
     }
 }

crates/pikl-gui/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "pikl-gui"
+description = "GUI frontend for pikl-menu (iced + Wayland layer-shell)."
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+pikl-core = { path = "../pikl-core" }
+iced = { version = "0.14", features = ["tokio"] }
+iced_layershell = "0.15"
+tokio = { version = "1", features = ["sync", "macros", "rt"] }
+tracing = "0.1"

crates/pikl-gui/src/lib.rs

@@ -0,0 +1,634 @@
+//! GUI frontend for pikl-menu. Renders a Wayland
+//! layer-shell overlay using iced. Same channel pattern as
+//! the TUI: receives [`ViewState`] snapshots, sends
+//! [`Action`]s into the core engine.
+
+use std::sync::{Mutex, OnceLock};
+
+use iced::keyboard::key::Named;
+use iced::keyboard::{Key, Modifiers};
+use iced::widget::{column, container, row, scrollable, text, text_input, Column};
+use iced::{Color, Element, Font, Length, Subscription, Task, Theme};
+use iced_layershell::build_pattern::application as layer_application;
+use iced_layershell::reexport::{Anchor, KeyboardInteractivity, Layer};
+use iced_layershell::settings::{LayerShellSettings, Settings};
+use iced_layershell::to_layer_message;
+use tokio::sync::{broadcast, mpsc};
+
+use pikl_core::event::{
+    Action, MenuEvent, ModifiedAction, Modifiers as PiklModifiers, Mode, ViewState, VisibleItem,
+};
+
+/// Number of visible items in the list viewport.
+const VIEWPORT_HEIGHT: u16 = 20;
+
+/// Pending key state for multi-key sequences (e.g. `gg`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum PendingKey {
+    None,
+    G,
+}
+
+/// Messages for the iced application. The `#[to_layer_message]`
+/// macro generates the `TryInto<LayershellCustomActionWithId>`
+/// impl that iced_layershell requires.
+#[to_layer_message]
+#[derive(Debug, Clone)]
+enum Message {
+    /// A state snapshot arrived from the core engine.
+    StateChanged(ViewState),
+    /// The core signalled that the menu is done.
+    Done,
+    /// Text input changed (insert mode filter).
+    FilterChanged(String),
+    /// A keyboard event from iced.
+    KeyPressed(Key, Modifiers),
+    /// Fire-and-forget action sent, nothing to do.
+    Sent,
+}
+
+/// Global slot for the bridge receiver. Used by the
+/// subscription fn pointer since `Subscription::run`
+/// doesn't accept closures.
+static BRIDGE_RX: OnceLock<Mutex<Option<mpsc::Receiver<Message>>>> = OnceLock::new();
+
+/// Global slot for the action sender. Moved into the Pikl
+/// struct during boot (called exactly once by iced).
+static ACTION_TX: OnceLock<Mutex<Option<mpsc::Sender<ModifiedAction>>>> = OnceLock::new();
+
+/// Top-level GUI state.
+struct Pikl {
+    /// Channel to send actions into the core engine.
+    action_tx: mpsc::Sender<ModifiedAction>,
+    /// Current view snapshot from core.
+    view_state: Option<ViewState>,
+    /// Local copy of filter text for the text input widget.
+    filter_text: String,
+    /// Current input mode (synced from core).
+    mode: Mode,
+    /// Pending key for multi-key sequences.
+    pending: PendingKey,
+    /// Whether multi-select is enabled (synced from core).
+    multi_enabled: bool,
+    /// Visual mode anchor index.
+    visual_anchor: Option<usize>,
+    /// Last generation seen, to skip duplicate broadcasts.
+    last_generation: u64,
+    /// Whether we've focused the input after the first render.
+    initial_focus_done: bool,
+    /// ID for the filter text input widget.
+    filter_input_id: iced::widget::Id,
+}
+
+/// Start the GUI. Creates a Wayland layer-shell overlay,
+/// runs the iced event loop, and exits when the user
+/// confirms or cancels.
+pub fn run(
+    action_tx: mpsc::Sender<ModifiedAction>,
+    event_rx: broadcast::Receiver<MenuEvent>,
+) -> Result<(), iced_layershell::Error> {
+    // Send initial resize to core so it knows our viewport.
+    let _ = action_tx.blocking_send(ModifiedAction::new(Action::Resize {
+        height: VIEWPORT_HEIGHT,
+    }));
+
+    // Bridge: spawn a thread that reads core events and
+    // forwards them as Messages through an mpsc channel.
+    let (bridge_tx, bridge_rx) = mpsc::channel::<Message>(64);
+    std::thread::spawn(move || {
+        bridge_core_events(event_rx, bridge_tx);
+    });
+
+    // Stash channels in global slots so the boot fn pointer
+    // and subscription fn pointer can access them.
+    let _ = BRIDGE_RX.set(Mutex::new(Some(bridge_rx)));
+    let _ = ACTION_TX.set(Mutex::new(Some(action_tx)));
+
+    layer_application(
+        || {
+            let input_id = iced::widget::Id::unique();
+            let atx = ACTION_TX
+                .get()
+                .and_then(|m| m.lock().unwrap_or_else(|e| e.into_inner()).take())
+                .unwrap_or_else(|| {
+                    let (tx, _) = mpsc::channel::<ModifiedAction>(1);
+                    tx
+                });
+            let pikl = Pikl {
+                action_tx: atx,
+                view_state: None,
+                filter_text: String::new(),
+                mode: Mode::Insert,
+                pending: PendingKey::None,
+                multi_enabled: false,
+                visual_anchor: None,
+                last_generation: 0,
+                initial_focus_done: false,
+                filter_input_id: input_id.clone(),
+            };
+            (pikl, iced::widget::operation::focus(input_id))
+        },
+        "pikl",
+        update,
+        view,
+    )
+    .settings(Settings {
+        layer_settings: LayerShellSettings {
+            layer: Layer::Overlay,
+            anchor: Anchor::Top | Anchor::Left | Anchor::Right,
+            size: Some((0, 600)),
+            keyboard_interactivity: KeyboardInteractivity::Exclusive,
+            exclusive_zone: -1,
+            margin: (200, 400, 0, 400),
+            ..Default::default()
+        },
+        ..Default::default()
+    })
+    .subscription(subscription)
+    .theme(theme)
+    .run()
+}
+
+/// Read core events from the broadcast channel and forward
+/// them as Messages. Runs on a dedicated thread with its
+/// own tokio runtime so it works regardless of whether the
+/// caller's runtime is still alive.
+fn bridge_core_events(
+    mut event_rx: broadcast::Receiver<MenuEvent>,
+    bridge_tx: mpsc::Sender<Message>,
+) {
+    let rt = match tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+    {
+        Ok(rt) => rt,
+        Err(_) => return,
+    };
+    rt.block_on(async {
+        loop {
+            match event_rx.recv().await {
+                Ok(MenuEvent::StateChanged(vs)) => {
+                    if bridge_tx.send(Message::StateChanged(vs)).await.is_err() {
+                        break;
+                    }
+                }
+                Ok(
+                    MenuEvent::Selected(_)
+                    | MenuEvent::Quicklist(_)
+                    | MenuEvent::Cancelled,
+                ) => {
+                    let _ = bridge_tx.send(Message::Done).await;
+                    break;
+                }
+                Err(broadcast::error::RecvError::Lagged(n)) => {
+                    tracing::warn!(skipped = n, "GUI fell behind on state broadcasts");
+                }
+                Err(broadcast::error::RecvError::Closed) => {
+                    let _ = bridge_tx.send(Message::Done).await;
+                    break;
+                }
+            }
+        }
+    });
+}
+
+fn update(state: &mut Pikl, message: Message) -> Task<Message> {
+    match message {
+        Message::StateChanged(vs) => {
+            if vs.generation == state.last_generation {
+                return Task::none();
+            }
+            state.last_generation = vs.generation;
+
+            if &*vs.filter_text != state.filter_text.as_str() {
+                state.filter_text = vs.filter_text.to_string();
+            }
+            if vs.mode != state.mode {
+                state.mode = vs.mode;
+                state.pending = PendingKey::None;
+            }
+            state.multi_enabled = vs.multi_enabled;
+            state.view_state = Some(vs);
+
+            // Re-focus the input on the first state update.
+            // The boot focus task can fire before the widget
+            // tree exists, so this catches the Hyprland case
+            // where the input starts unfocused.
+            if !state.initial_focus_done {
+                state.initial_focus_done = true;
+                iced::widget::operation::focus(state.filter_input_id.clone())
+            } else {
+                Task::none()
+            }
+        }
+        Message::Done => iced::exit(),
+        Message::FilterChanged(new_text) => {
+            if state.mode != Mode::Insert {
+                return Task::none();
+            }
+            state.filter_text = new_text.clone();
+            let tx = state.action_tx.clone();
+            Task::perform(
+                async move {
+                    let _ = tx.send(ModifiedAction::new(Action::UpdateFilter(new_text))).await;
+                },
+                |_| Message::Sent,
+            )
+        }
+        Message::KeyPressed(key, modifiers) => handle_key(state, key, modifiers),
+        Message::Sent => Task::none(),
+        _ => Task::none(),
+    }
+}
+
+fn view(state: &Pikl) -> Element<'_, Message> {
+    let filter_input = text_input("filter...", &state.filter_text)
+        .id(state.filter_input_id.clone())
+        .on_input(Message::FilterChanged)
+        .padding(8)
+        .size(16)
+        .font(Font::MONOSPACE);
+
+    let mode_indicator = match state.mode {
+        Mode::Insert => "[I]",
+        Mode::Normal => "[N]",
+        Mode::Visual => "[V]",
+    };
+
+    let counts = if let Some(vs) = &state.view_state {
+        let streaming = if vs.streaming { "..." } else { "" };
+        let sel = if vs.selection_count > 0 {
+            format!("  [{}]", vs.selection_count)
+        } else {
+            String::new()
+        };
+        format!(
+            "{}/{}{streaming}{sel}",
+            vs.total_filtered, vs.total_items
+        )
+    } else {
+        String::from("0/0")
+    };
+
+    let prompt_row = row![
+        text(mode_indicator)
+            .font(Font::MONOSPACE)
+            .size(16)
+            .color(Color::from_rgb(0.4, 0.8, 1.0)),
+        filter_input,
+        text(counts)
+            .font(Font::MONOSPACE)
+            .size(14)
+            .color(Color::from_rgb(0.5, 0.5, 0.5)),
+    ]
+    .spacing(8)
+    .align_y(iced::Alignment::Center)
+    .padding(4);
+
+    let items_list: Element<Message> = if let Some(vs) = &state.view_state {
+        let items: Vec<Element<Message>> = vs
+            .visible_items
+            .iter()
+            .enumerate()
+            .map(|(i, vi)| render_item(state, i, vi, vs))
+            .collect();
+
+        scrollable(
+            Column::with_children(items)
+                .spacing(0)
+                .width(Length::Fill),
+        )
+        .height(Length::Fill)
+        .into()
+    } else {
+        text("loading...").font(Font::MONOSPACE).size(14).into()
+    };
+
+    container(
+        column![prompt_row, items_list]
+            .spacing(0)
+            .width(Length::Fill),
+    )
+    .style(|_theme| container::Style {
+        background: Some(iced::Background::Color(Color::from_rgb(
+            0.12, 0.12, 0.15,
+        ))),
+        ..Default::default()
+    })
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .into()
+}
+
+fn theme(_state: &Pikl) -> Theme {
+    Theme::Dark
+}
+
+fn render_item<'a>(
+    state: &Pikl,
+    index: usize,
+    vi: &VisibleItem,
+    vs: &ViewState,
+) -> Element<'a, Message> {
+    let is_cursor = index == vs.cursor;
+    let in_visual = if vs.mode == Mode::Visual {
+        state.visual_anchor.is_some_and(|anchor| {
+            let min = anchor.min(vs.cursor);
+            let max = anchor.max(vs.cursor);
+            (min..=max).contains(&index)
+        })
+    } else {
+        false
+    };
+
+    let display_text = vi.formatted_text.as_deref().unwrap_or(vi.label.as_str());
+
+    let label = if state.multi_enabled {
+        let marker = if vi.selected { "* " } else { "  " };
+        format!("{marker}{display_text}")
+    } else {
+        display_text.to_string()
+    };
+
+    let text_color = if vi.selected {
+        Color::from_rgb(0.4, 0.9, 0.4)
+    } else if is_cursor || in_visual {
+        Color::from_rgb(0.95, 0.95, 0.95)
+    } else {
+        Color::from_rgb(0.8, 0.8, 0.8)
+    };
+
+    let bg_color = if is_cursor {
+        Color::from_rgb(0.25, 0.25, 0.35)
+    } else if in_visual {
+        Color::from_rgb(0.15, 0.2, 0.35)
+    } else {
+        Color::TRANSPARENT
+    };
+
+    container(
+        text(label)
+            .font(Font::MONOSPACE)
+            .size(15)
+            .color(text_color),
+    )
+    .style(move |_theme| container::Style {
+        background: Some(iced::Background::Color(bg_color)),
+        ..Default::default()
+    })
+    .padding([4, 10])
+    .width(Length::Fill)
+    .into()
+}
+
+fn subscription(_state: &Pikl) -> Subscription<Message> {
+    let keyboard_sub = iced::event::listen_with(|event, _status, _id| match event {
+        iced::Event::Keyboard(iced::keyboard::Event::KeyPressed {
+            key,
+            modifiers,
+            ..
+        }) => Some(Message::KeyPressed(key, modifiers)),
+        _ => None,
+    });
+
+    let core_sub = Subscription::run(core_event_stream);
+
+    Subscription::batch([keyboard_sub, core_sub])
+}
+
+/// Stream factory for the core event subscription. Takes the
+/// bridge receiver from the global slot and yields Messages
+/// until the channel closes.
+fn core_event_stream() -> impl iced::futures::Stream<Item = Message> {
+    // Take the receiver from the global slot. Only the first
+    // subscription instantiation will get Some.
+    let rx = BRIDGE_RX
+        .get()
+        .and_then(|m| m.lock().unwrap_or_else(|e| e.into_inner()).take());
+
+    // unfold with the receiver as state. Each step awaits one
+    // message and yields it.
+    iced::futures::stream::unfold(rx, |state| async move {
+        let mut rx = state?;
+        match rx.recv().await {
+            Some(msg) => Some((msg, Some(rx))),
+            None => Some((Message::Done, None)),
+        }
+    })
+}
+
+/// Convert iced keyboard modifiers to pikl Modifiers.
+fn iced_modifiers(m: &iced::keyboard::Modifiers) -> PiklModifiers {
+    PiklModifiers {
+        shift: m.shift(),
+        ctrl: m.control(),
+        alt: m.alt(),
+    }
+}
+
+/// Handle a keyboard event and return the appropriate task.
+fn handle_key(state: &mut Pikl, key: Key, modifiers: Modifiers) -> Task<Message> {
+    let action = match state.mode {
+        Mode::Insert => map_insert_key(state, &key, &modifiers),
+        Mode::Normal => map_normal_key(state, &key, &modifiers),
+        Mode::Visual => map_visual_key(state, &key, &modifiers),
+    };
+
+    if let Some(action) = action {
+        if let Action::SetMode(m) = &action {
+            if *m == Mode::Visual {
+                if let Some(vs) = &state.view_state {
+                    state.visual_anchor = Some(vs.cursor);
+                }
+            } else if state.mode == Mode::Visual {
+                state.visual_anchor = None;
+            }
+            state.mode = *m;
+            state.pending = PendingKey::None;
+        }
+
+        let focus_task = if matches!(action, Action::SetMode(Mode::Insert)) {
+            iced::widget::operation::focus(state.filter_input_id.clone())
+        } else {
+            Task::none()
+        };
+
+        let tx = state.action_tx.clone();
+        let mods = iced_modifiers(&modifiers);
+        let send_task = Task::perform(
+            async move {
+                let _ = tx.send(ModifiedAction::with_modifiers(action, mods)).await;
+            },
+            |_| Message::Sent,
+        );
+
+        Task::batch([send_task, focus_task])
+    } else {
+        Task::none()
+    }
+}
+
+/// Map keys in insert mode. Returns None for keys that the
+/// text_input widget handles (regular characters, backspace).
+fn map_insert_key(state: &mut Pikl, key: &Key, modifiers: &Modifiers) -> Option<Action> {
+    let ctrl = modifiers.control();
+
+    match key {
+        Key::Named(Named::Escape) => Some(Action::Cancel),
+        Key::Named(Named::Enter) => Some(Action::Confirm),
+        Key::Named(Named::ArrowUp) => Some(Action::MoveUp(1)),
+        Key::Named(Named::ArrowDown) => Some(Action::MoveDown(1)),
+        Key::Named(Named::PageUp) => Some(Action::PageUp(1)),
+        Key::Named(Named::PageDown) => Some(Action::PageDown(1)),
+        Key::Named(Named::Tab) if state.multi_enabled => {
+            let tx = state.action_tx.clone();
+            let mods = iced_modifiers(modifiers);
+            tokio::spawn(async move {
+                let _ = tx.send(ModifiedAction::with_modifiers(Action::ToggleSelect, mods)).await;
+                let _ = tx.send(ModifiedAction::with_modifiers(Action::MoveDown(1), mods)).await;
+            });
+            None
+        }
+        Key::Character(c) if ctrl && c.as_str() == "p" => Some(Action::MoveUp(1)),
+        Key::Character(c) if ctrl && c.as_str() == "n" => {
+            Some(Action::SetMode(Mode::Normal))
+        }
+        Key::Character(c) if ctrl && c.as_str() == "q" => Some(Action::Quicklist),
+        _ => None,
+    }
+}
+
+/// Map keys in normal mode.
+fn map_normal_key(state: &mut Pikl, key: &Key, modifiers: &Modifiers) -> Option<Action> {
+    let ctrl = modifiers.control();
+
+    if state.pending == PendingKey::G {
+        state.pending = PendingKey::None;
+        if let Key::Character(c) = key
+            && c.as_str() == "g"
+            && !ctrl
+        {
+            return Some(Action::MoveToTop);
+        }
+    }
+
+    match key {
+        Key::Character(c) if !ctrl => match c.as_str() {
+            "j" => Some(Action::MoveDown(1)),
+            "k" => Some(Action::MoveUp(1)),
+            "G" => Some(Action::MoveToBottom),
+            "g" => {
+                state.pending = PendingKey::G;
+                None
+            }
+            "/" => Some(Action::SetMode(Mode::Insert)),
+            "q" => Some(Action::Cancel),
+            "V" => Some(Action::SetMode(Mode::Visual)),
+            "U" => Some(Action::ClearSelections),
+            "u" => Some(Action::UndoSelection),
+            " " if state.multi_enabled => {
+                let tx = state.action_tx.clone();
+                let mods = iced_modifiers(modifiers);
+                tokio::spawn(async move {
+                    let _ = tx.send(ModifiedAction::with_modifiers(Action::ToggleSelect, mods)).await;
+                    let _ = tx.send(ModifiedAction::with_modifiers(Action::MoveDown(1), mods)).await;
+                });
+                None
+            }
+            _ => None,
+        },
+        Key::Character(c) if ctrl => match c.as_str() {
+            "d" => Some(Action::HalfPageDown(1)),
+            "u" => Some(Action::HalfPageUp(1)),
+            "f" => Some(Action::PageDown(1)),
+            "b" => Some(Action::PageUp(1)),
+            "e" => Some(Action::SetMode(Mode::Insert)),
+            "q" => Some(Action::Quicklist),
+            "r" => Some(Action::RedoSelection),
+            _ => None,
+        },
+        Key::Named(Named::Enter) => Some(Action::Confirm),
+        Key::Named(Named::Escape) => Some(Action::Cancel),
+        Key::Named(Named::ArrowUp) => Some(Action::MoveUp(1)),
+        Key::Named(Named::ArrowDown) => Some(Action::MoveDown(1)),
+        Key::Named(Named::Tab) if state.multi_enabled => {
+            let tx = state.action_tx.clone();
+            let mods = iced_modifiers(modifiers);
+            tokio::spawn(async move {
+                let _ = tx.send(ModifiedAction::with_modifiers(Action::ToggleSelect, mods)).await;
+                let _ = tx.send(ModifiedAction::with_modifiers(Action::MoveDown(1), mods)).await;
+            });
+            None
+        }
+        _ => None,
+    }
+}
+
+/// Map keys in visual mode.
+fn map_visual_key(state: &mut Pikl, key: &Key, modifiers: &Modifiers) -> Option<Action> {
+    let ctrl = modifiers.control();
+
+    if state.pending == PendingKey::G {
+        state.pending = PendingKey::None;
+        if let Key::Character(c) = key
+            && c.as_str() == "g"
+            && !ctrl
+        {
+            return Some(Action::MoveToTop);
+        }
+    }
+
+    match key {
+        Key::Character(c) if !ctrl => match c.as_str() {
+            "j" => Some(Action::MoveDown(1)),
+            "k" => Some(Action::MoveUp(1)),
+            "G" => Some(Action::MoveToBottom),
+            "g" => {
+                state.pending = PendingKey::G;
+                None
+            }
+            "V" => Some(Action::SetMode(Mode::Normal)),
+            " " => {
+                if let (Some(anchor), Some(vs)) =
+                    (state.visual_anchor, &state.view_state)
+                {
+                    let tx = state.action_tx.clone();
+                    let start = anchor;
+                    let end = vs.cursor;
+                    let mods = iced_modifiers(modifiers);
+                    tokio::spawn(async move {
+                        let _ = tx
+                            .send(ModifiedAction::with_modifiers(Action::SelectRange { start, end }, mods))
+                            .await;
+                        let _ = tx.send(ModifiedAction::with_modifiers(Action::SetMode(Mode::Normal), mods)).await;
+                    });
+                }
+                state.visual_anchor = None;
+                None
+            }
+            _ => None,
+        },
+        Key::Named(Named::Enter) => {
+            if let (Some(anchor), Some(vs)) =
+                (state.visual_anchor, &state.view_state)
+            {
+                let tx = state.action_tx.clone();
+                let start = anchor;
+                let end = vs.cursor;
+                let mods = iced_modifiers(modifiers);
+                tokio::spawn(async move {
+                    let _ = tx
+                        .send(ModifiedAction::with_modifiers(Action::SelectRange { start, end }, mods))
+                        .await;
+                    let _ = tx.send(ModifiedAction::with_modifiers(Action::SetMode(Mode::Normal), mods)).await;
+                });
+            }
+            state.visual_anchor = None;
+            None
+        }
+        Key::Named(Named::ArrowDown) => Some(Action::MoveDown(1)),
+        Key::Named(Named::ArrowUp) => Some(Action::MoveUp(1)),
+        Key::Named(Named::Escape) => Some(Action::Cancel),
+        _ => None,
+    }
+}

crates/pikl-test-macros/src/codegen.rs

@@ -59,7 +59,7 @@ fn gen_imports(kind: TestKind) -> TokenStream {
         TestKind::Menu => {
             quote! {
                 use pikl_core::item::Item;
-                use pikl_core::event::{Action, MenuEvent, MenuResult};
+                use pikl_core::event::{Action, MenuEvent, MenuResult, ModifiedAction};
                 use pikl_core::menu::MenuRunner;
                 use pikl_core::json_menu::JsonMenu;
             }
@@ -67,7 +67,7 @@ fn gen_imports(kind: TestKind) -> TokenStream {
         TestKind::Ipc => {
             quote! {
                 use pikl_core::item::Item;
-                use pikl_core::event::{Action, MenuEvent, MenuResult};
+                use pikl_core::event::{Action, MenuEvent, MenuResult, ModifiedAction};
                 use pikl_core::menu::MenuRunner;
                 use pikl_core::json_menu::JsonMenu;
                 use crate::ipc::server::IpcServer;
@@ -326,14 +326,14 @@ fn gen_menu(case: &TestCase, fixtures: &Fixtures) -> syn::Result<TokenStream> {
             let handle = tokio::spawn(async move { menu.run().await });
 
             let _ = rx.recv().await;
-            let _ = tx.send(Action::Resize { height: 50 }).await;
+            let _ = tx.send(ModifiedAction::new(Action::Resize { height: 50 })).await;
             let _ = rx.recv().await;
 
             #(#action_sends)*
 
             drop(tx);
 
-            let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+            let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: pikl_core::event::Modifiers::default() }));
             #result_assert
         }
     })
@@ -345,17 +345,17 @@ fn gen_menu_actions(actions: &[ActionExpr]) -> syn::Result<Vec<TokenStream>> {
         let expr = match action {
             ActionExpr::Simple(name) => {
                 let variant = menu_action_variant(name)?;
-                quote! { let _ = tx.send(#variant).await; }
+                quote! { let _ = tx.send(ModifiedAction::new(#variant)).await; }
             }
             ActionExpr::Filter(query) => {
-                quote! { let _ = tx.send(Action::UpdateFilter(#query.to_string())).await; }
+                quote! { let _ = tx.send(ModifiedAction::new(Action::UpdateFilter(#query.to_string()))).await; }
             }
             ActionExpr::AddItems(items) => {
                 let item_exprs: Vec<TokenStream> = items
                     .iter()
                     .map(|s| quote! { serde_json::Value::String(#s.to_string()) })
                     .collect();
-                quote! { let _ = tx.send(Action::AddItems(vec![#(#item_exprs),*])).await; }
+                quote! { let _ = tx.send(ModifiedAction::new(Action::AddItems(vec![#(#item_exprs),*]))).await; }
             }
             ActionExpr::Raw(_) => {
                 return Err(syn::Error::new(Span::call_site(), "raw actions are only supported in headless tests"));
@@ -450,7 +450,7 @@ fn gen_ipc(case: &TestCase, fixtures: &Fixtures) -> syn::Result<TokenStream> {
 
             let handle = tokio::spawn(async move { menu.run().await });
 
-            let _ = tx.send(Action::Resize { height: 50 }).await;
+            let _ = tx.send(ModifiedAction::new(Action::Resize { height: 50 })).await;
             tokio::time::sleep(Duration::from_millis(30)).await;
 
             // Start IPC server on a temp socket
@@ -484,7 +484,7 @@ fn gen_ipc(case: &TestCase, fixtures: &Fixtures) -> syn::Result<TokenStream> {
             drop(writer);
             drop(tx);
             drop(ipc_server);
-            let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled));
+            let result = handle.await.unwrap_or(Ok(MenuResult::Cancelled { modifiers: pikl_core::event::Modifiers::default() }));
             #result_assert
         }
     })
@@ -559,7 +559,7 @@ fn gen_result_assert(case: &TestCase, label_key: &str) -> syn::Result<TokenStrea
     if case.cancelled {
         Ok(quote! {
             assert!(
-                matches!(result, Ok(MenuResult::Cancelled)),
+                matches!(result, Ok(MenuResult::Cancelled { .. })),
                 "expected Cancelled, got: {:?}", result.as_ref().map(|r| format!("{:?}", r))
             );
         })

crates/pikl-tui/src/lib.rs

@@ -14,7 +14,7 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{List, ListItem, Paragraph};
 use tokio::sync::{broadcast, mpsc};
 
-use pikl_core::event::{Action, MenuEvent, Mode, ViewState};
+use pikl_core::event::{Action, MenuEvent, ModifiedAction, Modifiers, Mode, ViewState};
 
 /// Pending key state for multi-key sequences (e.g. `gg`).
 /// TUI-local, not part of core state.
@@ -32,12 +32,21 @@ pub fn restore_terminal() {
     let _ = crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen);
 }
 
+/// Convert crossterm key modifiers to pikl Modifiers.
+fn crossterm_modifiers(km: KeyModifiers) -> Modifiers {
+    Modifiers {
+        shift: km.contains(KeyModifiers::SHIFT),
+        ctrl: km.contains(KeyModifiers::CONTROL),
+        alt: km.contains(KeyModifiers::ALT),
+    }
+}
+
 /// Start the TUI. Enters the alternate screen, runs the
 /// event loop, and restores the terminal on exit. Translates
 /// crossterm key events into [`Action`]s and renders
 /// [`ViewState`] snapshots.
 pub async fn run(
-    action_tx: mpsc::Sender<Action>,
+    action_tx: mpsc::Sender<ModifiedAction>,
     mut event_rx: broadcast::Receiver<MenuEvent>,
     filter_history: Option<Vec<String>>,
 ) -> std::io::Result<()> {
@@ -65,7 +74,7 @@ pub async fn run(
 /// Inner event loop. Separated from [`run`] so terminal
 /// cleanup always happens even if this returns an error.
 async fn run_inner(
-    action_tx: &mpsc::Sender<Action>,
+    action_tx: &mpsc::Sender<ModifiedAction>,
     event_rx: &mut broadcast::Receiver<MenuEvent>,
     terminal: &mut Terminal<CrosstermBackend<std::io::Stderr>>,
     filter_history: Option<Vec<String>>,
@@ -74,9 +83,9 @@ async fn run_inner(
     let size = terminal.size()?;
     let list_height = size.height.saturating_sub(1);
     if action_tx
-        .send(Action::Resize {
+        .send(ModifiedAction::new(Action::Resize {
             height: list_height,
-        })
+        }))
         .await
         .is_err()
     {
@@ -135,7 +144,7 @@ async fn run_inner(
                                     history_cursor = Some(new_cursor);
                                     filter_text.clone_from(&history[new_cursor]);
                                     let _ = action_tx
-                                        .send(Action::UpdateFilter(filter_text.clone()))
+                                        .send(ModifiedAction::new(Action::UpdateFilter(filter_text.clone())))
                                         .await;
                                     true
                                 }
@@ -153,7 +162,7 @@ async fn run_inner(
                                             pre_history_text = None;
                                         }
                                         let _ = action_tx
-                                            .send(Action::UpdateFilter(filter_text.clone()))
+                                            .send(ModifiedAction::new(Action::UpdateFilter(filter_text.clone())))
                                             .await;
                                         true
                                     } else {
@@ -196,14 +205,14 @@ async fn run_inner(
                                 mode = *m;
                                 pending = PendingKey::None;
                             }
-                            if action_tx.send(action).await.is_err() {
+                            if action_tx.send(ModifiedAction::with_modifiers(action, crossterm_modifiers(key.modifiers))).await.is_err() {
                                 break; // core is gone
                             }
                         }
                     }
                     Event::Resize(_, h) => {
                         let list_height = h.saturating_sub(1);
-                        if action_tx.send(Action::Resize { height: list_height }).await.is_err() {
+                        if action_tx.send(ModifiedAction::new(Action::Resize { height: list_height })).await.is_err() {
                             break;
                         }
                     }
@@ -259,7 +268,7 @@ async fn handle_multi_action_key(
     multi_enabled: bool,
     visual_anchor: &mut Option<usize>,
     view_state: &Option<ViewState>,
-    action_tx: &mpsc::Sender<Action>,
+    action_tx: &mpsc::Sender<ModifiedAction>,
 ) -> bool {
     match mode {
         Mode::Insert => {
@@ -268,13 +277,15 @@ async fn handle_multi_action_key(
             }
             match key.code {
                 KeyCode::Tab => {
-                    let _ = action_tx.send(Action::ToggleSelect).await;
-                    let _ = action_tx.send(Action::MoveDown(1)).await;
+                    let mods = crossterm_modifiers(key.modifiers);
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::ToggleSelect, mods)).await;
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::MoveDown(1), mods)).await;
                     true
                 }
                 KeyCode::BackTab => {
-                    let _ = action_tx.send(Action::ToggleSelect).await;
-                    let _ = action_tx.send(Action::MoveUp(1)).await;
+                    let mods = crossterm_modifiers(key.modifiers);
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::ToggleSelect, mods)).await;
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::MoveUp(1), mods)).await;
                     true
                 }
                 _ => false,
@@ -288,18 +299,21 @@ async fn handle_multi_action_key(
                 (KeyCode::Char(' '), m)
                     if !m.intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
                 {
-                    let _ = action_tx.send(Action::ToggleSelect).await;
-                    let _ = action_tx.send(Action::MoveDown(1)).await;
+                    let mods = crossterm_modifiers(key.modifiers);
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::ToggleSelect, mods)).await;
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::MoveDown(1), mods)).await;
                     true
                 }
                 (KeyCode::Tab, _) => {
-                    let _ = action_tx.send(Action::ToggleSelect).await;
-                    let _ = action_tx.send(Action::MoveDown(1)).await;
+                    let mods = crossterm_modifiers(key.modifiers);
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::ToggleSelect, mods)).await;
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::MoveDown(1), mods)).await;
                     true
                 }
                 (KeyCode::BackTab, _) => {
-                    let _ = action_tx.send(Action::ToggleSelect).await;
-                    let _ = action_tx.send(Action::MoveUp(1)).await;
+                    let mods = crossterm_modifiers(key.modifiers);
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::ToggleSelect, mods)).await;
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::MoveUp(1), mods)).await;
                     true
                 }
                 _ => false,
@@ -310,18 +324,19 @@ async fn handle_multi_action_key(
                 (KeyCode::Char(' '), m) | (KeyCode::Enter, m)
                     if !m.intersects(KeyModifiers::ALT) =>
                 {
+                    let mods = crossterm_modifiers(key.modifiers);
                     // Apply visual selection
                     if let (Some(anchor), Some(vs)) = (*visual_anchor, view_state) {
                         let cursor = vs.cursor;
                         let _ = action_tx
-                            .send(Action::SelectRange {
+                            .send(ModifiedAction::with_modifiers(Action::SelectRange {
                                 start: anchor,
                                 end: cursor,
-                            })
+                            }, mods))
                             .await;
                     }
                     *visual_anchor = None;
-                    let _ = action_tx.send(Action::SetMode(Mode::Normal)).await;
+                    let _ = action_tx.send(ModifiedAction::with_modifiers(Action::SetMode(Mode::Normal), mods)).await;
                     true
                 }
                 _ => false,
@@ -374,7 +389,10 @@ fn render_menu(
         ),
         Span::raw(filter_text),
         Span::styled(
-            format!("  {filtered_count}/{total_count}"),
+            format!(
+                "  {filtered_count}/{total_count}{}",
+                if vs.streaming { "..." } else { "" }
+            ),
             Style::default().fg(Color::DarkGray),
         ),
     ];
@@ -691,6 +709,7 @@ mod tests {
             mode: Mode::Insert,
             selection_count: 0,
             multi_enabled: false,
+            streaming: false,
             columns: None,
             generation: 1,
         }
@@ -1166,6 +1185,7 @@ mod tests {
             mode: Mode::Insert,
             selection_count: 0,
             multi_enabled: false,
+            streaming: false,
             columns: None,
             generation: 1,
         };
@@ -1175,6 +1195,29 @@ mod tests {
         assert!(prompt.contains("0/0"));
     }
 
+    #[test]
+    fn streaming_indicator_shows_ellipsis() {
+        let mut vs = sample_view_state();
+        vs.streaming = true;
+        let backend = render_to_backend(40, 5, &vs, "");
+        let prompt = line_text(&backend, 0);
+        assert!(
+            prompt.contains("..."),
+            "streaming indicator should show '...': {prompt}"
+        );
+    }
+
+    #[test]
+    fn no_streaming_indicator_when_done() {
+        let vs = sample_view_state();
+        let backend = render_to_backend(40, 5, &vs, "");
+        let prompt = line_text(&backend, 0);
+        assert!(
+            !prompt.contains("..."),
+            "should not show '...' when not streaming: {prompt}"
+        );
+    }
+
     #[test]
     fn narrow_viewport_truncates() {
         let vs = sample_view_state();
@@ -1269,6 +1312,7 @@ mod tests {
             mode: Mode::Insert,
             selection_count: 0,
             multi_enabled: false,
+            streaming: false,
             columns: Some(vec![
                 ColumnHeader {
                     display_name: "name".into(),

crates/pikl/Cargo.toml

@@ -15,6 +15,7 @@ path = "src/main.rs"
 [dependencies]
 pikl-core = { path = "../pikl-core" }
 pikl-tui = { path = "../pikl-tui" }
+pikl-gui = { path = "../pikl-gui" }
 clap = { version = "4", features = ["derive"] }
 tokio = { version = "1", features = ["rt-multi-thread", "process", "signal", "io-util", "net"] }
 serde = { version = "1", features = ["derive"] }

crates/pikl/src/handler.rs

@@ -11,7 +11,7 @@ use tokio::process::Command;
 use tokio::sync::mpsc;
 
 use pikl_core::error::PiklError;
-use pikl_core::event::Action;
+use pikl_core::event::{Action, ModifiedAction};
 use pikl_core::hook::{HookEvent, HookEventKind, HookHandler, parse_hook_response};
 
 /// A persistent handler hook process. Spawns a child process,
@@ -25,7 +25,7 @@ pub struct ShellHandlerHook {
 
 impl ShellHandlerHook {
     /// Build from CLI flags. Returns None if no handler hooks are configured.
-    pub fn from_cli(cli: &crate::Cli, action_tx: mpsc::Sender<Action>) -> Option<Self> {
+    pub fn from_cli(cli: &crate::Cli, action_tx: mpsc::Sender<ModifiedAction>) -> Option<Self> {
         let mut handlers: Vec<(HookEventKind, &str)> = Vec::new();
 
         if let Some(ref cmd) = cli.on_open {
@@ -91,7 +91,7 @@ impl HookHandler for ShellHandlerHook {
 async fn run_handler_process(
     command: &str,
     mut event_rx: mpsc::Receiver<HookEvent>,
-    action_tx: mpsc::Sender<Action>,
+    action_tx: mpsc::Sender<ModifiedAction>,
 ) -> Result<(), PiklError> {
     let mut child = Command::new("sh")
         .arg("-c")
@@ -120,7 +120,7 @@ async fn run_handler_process(
         let mut lines = stdout_reader.lines();
         while let Ok(Some(line)) = lines.next_line().await {
             if let Some(resp) = parse_hook_response(&line) {
-                let action = Action::ProcessHookResponse(resp);
+                let action = ModifiedAction::new(Action::ProcessHookResponse(resp));
                 if reader_action_tx.send(action).await.is_err() {
                     break;
                 }

crates/pikl/src/ipc/server.rs

@@ -9,7 +9,7 @@ use tokio::net::UnixListener;
 use tokio::sync::{broadcast, mpsc, watch, RwLock};
 use tracing::{info, warn};
 
-use pikl_core::event::{Action, MenuEvent, ViewState};
+use pikl_core::event::{MenuEvent, ModifiedAction, ViewState};
 
 use super::protocol::{ipc_command_to_action, view_state_to_response, IpcCommand, IpcResponse};
 
@@ -19,7 +19,7 @@ use super::protocol::{ipc_command_to_action, view_state_to_response, IpcCommand,
 /// removes the socket file.
 pub struct IpcServer {
     socket_path: PathBuf,
-    action_tx: mpsc::Sender<Action>,
+    action_tx: mpsc::Sender<ModifiedAction>,
     state: Arc<RwLock<Option<ViewState>>>,
     event_tx: broadcast::Sender<MenuEvent>,
     /// Dropping the sender signals all tasks to shut down.
@@ -29,7 +29,7 @@ pub struct IpcServer {
 impl IpcServer {
     pub fn new(
         socket_path: PathBuf,
-        action_tx: mpsc::Sender<Action>,
+        action_tx: mpsc::Sender<ModifiedAction>,
         event_tx: broadcast::Sender<MenuEvent>,
     ) -> Self {
         Self {
@@ -143,7 +143,7 @@ impl Drop for IpcServer {
 /// dispatches actions, sends responses.
 async fn handle_connection(
     stream: tokio::net::UnixStream,
-    action_tx: mpsc::Sender<Action>,
+    action_tx: mpsc::Sender<ModifiedAction>,
     state: Arc<RwLock<Option<ViewState>>>,
     event_tx: broadcast::Sender<MenuEvent>,
 ) -> Result<(), std::io::Error> {
@@ -180,7 +180,7 @@ async fn handle_connection(
             // Write commands: convert to action, send, no response
             ref c if ipc_command_to_action(c).is_some() => {
                 if let Some(action) = ipc_command_to_action(&cmd) {
-                    let _ = action_tx.send(action).await;
+                    let _ = action_tx.send(ModifiedAction::new(action)).await;
                 }
             }
 

crates/pikl/src/main.rs

@@ -13,10 +13,10 @@ use pikl_core::column::ColumnConfig;
 use pikl_core::csv_input::{self, InputFormat};
 use pikl_core::debounce::{DebounceMode, DebouncedDispatcher};
 use pikl_core::error::PiklError;
-use pikl_core::event::{Action, MenuResult, Mode};
+use pikl_core::event::{Action, MenuResult, ModifiedAction, Mode};
 use pikl_core::format::FormatTemplate;
 use pikl_core::hook::{HookEventKind, HookHandler};
-use pikl_core::input::read_items_sync;
+use pikl_core::input::{parse_line_to_value, read_items_sync};
 use pikl_core::item::Item;
 use pikl_core::json_menu::JsonMenu;
 use pikl_core::menu::MenuRunner;
@@ -27,6 +27,30 @@ use serde_json::Value;
 use handler::ShellHandlerHook;
 use hook::ShellExecHandler;
 
+/// Which frontend to launch.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum FrontendMode {
+    Tui,
+    Gui,
+}
+
+/// Resolve `--mode` flag into a concrete frontend. "auto"
+/// picks GUI if `$WAYLAND_DISPLAY` is set, otherwise TUI.
+fn resolve_frontend_mode(mode_str: &str) -> Option<FrontendMode> {
+    match mode_str {
+        "tui" => Some(FrontendMode::Tui),
+        "gui" => Some(FrontendMode::Gui),
+        "auto" => {
+            if std::env::var_os("WAYLAND_DISPLAY").is_some() {
+                Some(FrontendMode::Gui)
+            } else {
+                Some(FrontendMode::Tui)
+            }
+        }
+        _ => None,
+    }
+}
+
 #[derive(Parser)]
 #[command(
     name = "pikl",
@@ -147,6 +171,10 @@ struct Cli {
     /// Session name (enables filter history, names the IPC socket)
     #[arg(long)]
     session: Option<String>,
+
+    /// Frontend mode: tui, gui, or auto (default: auto)
+    #[arg(long, value_name = "MODE", default_value = "auto")]
+    mode: String,
 }
 
 fn main() {
@@ -201,10 +229,6 @@ fn main() {
         std::process::exit(2);
     }
 
-    let timeout = cli
-        .stdin_timeout
-        .unwrap_or(if script.is_some() { 30 } else { 0 });
-
     let input_format = match InputFormat::from_str_opt(&cli.input_format) {
         Some(f) => f,
         None => {
@@ -217,22 +241,55 @@ fn main() {
         }
     };
 
-    let (items, csv_headers) = match read_stdin_with_timeout(timeout, &cli.label_key, input_format)
-    {
-        Ok(r) => r,
-        Err(e) => {
-            let _ = writeln!(std::io::stderr().lock(), "pikl: {e}");
+    // Detect streaming mode: piped stdin, no action-fd, not CSV/TSV.
+    let streaming = script.is_none()
+        && !std::io::stdin().is_terminal()
+        && !matches!(input_format, InputFormat::Csv | InputFormat::Tsv);
+
+    // Save the original stdin fd for the streaming reader before
+    // we dup2 /dev/tty onto fd 0.
+    #[cfg(unix)]
+    let saved_stdin_fd: Option<i32> = if streaming {
+        let fd = unsafe { libc::dup(libc::STDIN_FILENO) };
+        if fd < 0 {
+            let _ = writeln!(
+                std::io::stderr().lock(),
+                "pikl: failed to dup stdin: {}",
+                std::io::Error::last_os_error()
+            );
             std::process::exit(2);
         }
+        Some(fd)
+    } else {
+        None
     };
 
-    if items.is_empty() {
-        let _ = writeln!(
-            std::io::stderr().lock(),
-            "pikl: empty input. nothing to pick from"
-        );
-        std::process::exit(2);
-    }
+    let (items, csv_headers) = if streaming {
+        // Streaming mode: start with empty items, read in background later.
+        (Vec::new(), None)
+    } else {
+        let timeout = cli
+            .stdin_timeout
+            .unwrap_or(if script.is_some() { 30 } else { 0 });
+
+        let (items, csv_headers) =
+            match read_stdin_with_timeout(timeout, &cli.label_key, input_format) {
+                Ok(r) => r,
+                Err(e) => {
+                    let _ = writeln!(std::io::stderr().lock(), "pikl: {e}");
+                    std::process::exit(2);
+                }
+            };
+
+        if items.is_empty() {
+            let _ = writeln!(
+                std::io::stderr().lock(),
+                "pikl: empty input. nothing to pick from"
+            );
+            std::process::exit(2);
+        }
+        (items, csv_headers)
+    };
 
     // Resolve column config: explicit --columns, or auto-generate from CSV headers
     let column_config = if let Some(ref cols) = cli.columns {
@@ -250,8 +307,23 @@ fn main() {
         std::process::exit(2);
     });
 
+    // Resolve frontend mode
+    let frontend_mode = match resolve_frontend_mode(&cli.mode) {
+        Some(m) => m,
+        None => {
+            let _ = writeln!(
+                std::io::stderr().lock(),
+                "pikl: unknown --mode '{}', expected auto, tui, or gui",
+                cli.mode
+            );
+            std::process::exit(2);
+        }
+    };
+
     // Reopen stdin from /dev/tty before entering async context.
+    // Only needed for TUI mode (GUI doesn't read from the terminal).
     if script.is_none()
+        && frontend_mode == FrontendMode::Tui
         && let Err(e) = reopen_stdin_from_tty()
     {
         let _ = writeln!(std::io::stderr().lock(), "pikl: {e}");
@@ -288,12 +360,19 @@ fn main() {
         rt.block_on(run_headless(items, &cli, script, start_mode, column_config))
     } else {
         let history_entries = history.as_ref().map(|h| h.entries().to_vec());
+        #[cfg(unix)]
+        let saved_fd = saved_stdin_fd;
+        #[cfg(not(unix))]
+        let saved_fd: Option<i32> = None;
         rt.block_on(run_interactive(
             items,
             &cli,
             start_mode,
             column_config,
             history_entries,
+            streaming,
+            saved_fd,
+            frontend_mode,
         ))
     };
 
@@ -330,7 +409,7 @@ fn build_menu(items: Vec<Item>, cli: &Cli, column_config: Option<ColumnConfig>)
 /// Build the composite hook handler from CLI flags, if any hooks are specified.
 fn build_hook_handler(
     cli: &Cli,
-    action_tx: &tokio::sync::mpsc::Sender<Action>,
+    action_tx: &tokio::sync::mpsc::Sender<ModifiedAction>,
 ) -> Option<(Arc<dyn HookHandler>, DebouncedDispatcher)> {
     let exec_handler = ShellExecHandler::from_cli(cli);
     let handler_hook = ShellHandlerHook::from_cli(cli, action_tx.clone());
@@ -423,7 +502,9 @@ async fn run_headless(
     let event_rx = menu.subscribe();
 
     // Default headless viewport
-    let _ = action_tx.send(Action::Resize { height: 50 }).await;
+    let _ = action_tx
+        .send(ModifiedAction::new(Action::Resize { height: 50 }))
+        .await;
 
     let menu_handle = tokio::spawn(menu.run());
 
@@ -461,11 +542,15 @@ async fn run_interactive(
     start_mode: Mode,
     column_config: Option<ColumnConfig>,
     filter_history: Option<Vec<String>>,
+    streaming: bool,
+    saved_stdin_fd: Option<i32>,
+    frontend_mode: FrontendMode,
 ) -> Result<MenuResult, PiklError> {
     let (mut menu, action_tx) = MenuRunner::new(build_menu(items, cli, column_config));
     menu.set_initial_mode(start_mode);
     menu.set_multi(cli.multi);
     menu.set_selection_order(cli.selection_order);
+    menu.set_streaming(streaming);
 
     if let Some((_handler, dispatcher)) = build_hook_handler(cli, &action_tx) {
         menu.set_dispatcher(dispatcher);
@@ -492,6 +577,7 @@ async fn run_interactive(
 
     // Handle SIGINT/SIGTERM: restore terminal and exit cleanly.
     let signal_tx = action_tx.clone();
+    let signal_frontend = frontend_mode;
     tokio::spawn(async move {
         match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
             Ok(mut sigterm) => {
@@ -505,17 +591,92 @@ async fn run_interactive(
                 let _ = tokio::signal::ctrl_c().await;
             }
         }
-        pikl_tui::restore_terminal();
-        let _ = signal_tx.send(Action::Cancel).await;
+        if signal_frontend == FrontendMode::Tui {
+            pikl_tui::restore_terminal();
+        }
+        let _ = signal_tx.send(ModifiedAction::new(Action::Cancel)).await;
     });
 
-    let tui_handle =
-        tokio::spawn(async move { pikl_tui::run(action_tx, event_rx, filter_history).await });
+    // Spawn background stdin reader for streaming mode.
+    if let Some(fd) = saved_stdin_fd {
+        let stream_tx = action_tx.clone();
+        tokio::task::spawn_blocking(move || {
+            #[cfg(unix)]
+            {
+                use std::io::BufRead;
+                use std::os::unix::io::FromRawFd;
 
-    let result = menu.run().await;
+                let file = unsafe { std::fs::File::from_raw_fd(fd) };
+                let mut reader = std::io::BufReader::new(file);
+                let mut batch = Vec::with_capacity(100);
+                let mut line = String::new();
 
-    let _ = tui_handle.await;
-    result
+                loop {
+                    line.clear();
+                    match reader.read_line(&mut line) {
+                        Ok(0) => break,
+                        Ok(_) => {
+                            let trimmed = line.trim_end();
+                            if !trimmed.is_empty() {
+                                batch.push(parse_line_to_value(trimmed));
+                            }
+                            if (batch.len() >= 100 || reader.buffer().is_empty())
+                                && !batch.is_empty()
+                            {
+                                let _ = stream_tx.blocking_send(ModifiedAction::new(Action::AddItems(
+                                    std::mem::take(&mut batch),
+                                )));
+                            }
+                        }
+                        Err(e) => {
+                            tracing::warn!(%e, "stdin read error");
+                            break;
+                        }
+                    }
+                }
+                if !batch.is_empty() {
+                    let _ = stream_tx.blocking_send(ModifiedAction::new(Action::AddItems(batch)));
+                }
+                let _ = stream_tx.blocking_send(ModifiedAction::new(Action::StreamingDone));
+            }
+        });
+    }
+
+    match frontend_mode {
+        FrontendMode::Tui => {
+            let tui_handle = tokio::spawn(async move {
+                pikl_tui::run(action_tx, event_rx, filter_history).await
+            });
+
+            let result = menu.run().await;
+            let _ = tui_handle.await;
+            result
+        }
+        FrontendMode::Gui => {
+            // GUI runs on the main thread (Wayland requirement).
+            // Spawn the core event loop on a background task.
+            let menu_handle = tokio::spawn(menu.run());
+
+            // pikl_gui::run blocks until the user confirms/cancels.
+            // Run it on a blocking thread so we don't stall the
+            // tokio runtime.
+            let gui_handle = tokio::task::spawn_blocking(move || {
+                pikl_gui::run(action_tx, event_rx).map_err(|e| {
+                    PiklError::Io(std::io::Error::other(format!("GUI error: {e}")))
+                })
+            });
+
+            if let Err(e) = gui_handle.await {
+                return Err(PiklError::Io(std::io::Error::other(e.to_string())));
+            }
+
+            // Wait for core to finish.
+            match menu_handle.await {
+                Ok(result) => result,
+                Err(e) => Err(PiklError::Io(std::io::Error::other(e.to_string()))),
+            }
+        }
+    }
 }
 
 /// Process the menu result: print output to stdout and
@@ -523,13 +684,16 @@ async fn run_interactive(
 fn handle_result(result: Result<MenuResult, PiklError>, cli: &Cli) {
     let mut out = std::io::stdout().lock();
     match result {
-        Ok(MenuResult::Selected { items, .. }) => {
+        Ok(MenuResult::Selected {
+            items, modifiers, ..
+        }) => {
             if cli.structured {
                 for (value, index) in items {
                     let output = OutputItem {
                         value,
                         action: OutputAction::Select,
                         index,
+                        modifiers,
                     };
                     let _ = write_output_json(&mut out, &output);
                 }
@@ -539,13 +703,16 @@ fn handle_result(result: Result<MenuResult, PiklError>, cli: &Cli) {
                 }
             }
         }
-        Ok(MenuResult::Quicklist { items, .. }) => {
+        Ok(MenuResult::Quicklist {
+            items, modifiers, ..
+        }) => {
             if cli.structured {
                 for (value, index) in items {
                     let output = OutputItem {
                         value,
                         action: OutputAction::Quicklist,
                         index,
+                        modifiers,
                     };
                     let _ = write_output_json(&mut out, &output);
                 }
@@ -555,12 +722,13 @@ fn handle_result(result: Result<MenuResult, PiklError>, cli: &Cli) {
                 }
             }
         }
-        Ok(MenuResult::Cancelled) => {
+        Ok(MenuResult::Cancelled { modifiers }) => {
             if cli.structured {
                 let output = OutputItem {
                     value: Value::Null,
                     action: OutputAction::Cancel,
                     index: 0,
+                    modifiers,
                 };
                 let _ = write_output_json(&mut out, &output);
             }

docs/DESIGN.md

@@ -48,6 +48,43 @@ metadata that came in, plus selection context:
 {"label": "beach_sunset.jpg", "sublabel": "/home/maple/walls/nature/", "meta": {"size": "2.4MB"}, "action": "select", "index": 3}
 ```
 
+When `--structured` is used, the output JSON includes a
+`modifiers` field if any modifier keys (shift, ctrl, alt)
+were held during confirmation. The value is an array of
+strings:
+
+```jsonl
+{"label": "firefox", "action": "select", "index": 0, "modifiers": ["shift"]}
+{"label": "alacritty", "action": "select", "index": 2, "modifiers": ["ctrl", "alt"]}
+```
+
+When no modifiers are held, the field is omitted entirely.
+Plain text output is unchanged: modifiers only appear in
+structured JSON.
+
+### Working with Structured Output
+
+Check for shift modifier with jq:
+
+```sh
+pikl --structured | jq 'if (.modifiers // [] | contains(["shift"])) then "alternate" else "default" end'
+```
+
+Extract a field:
+
+```sh
+pikl --structured | jq -r '.label'
+```
+
+Branch on modifiers in a script:
+
+```sh
+result=$(echo -e "a\nb\nc" | pikl --structured)
+if echo "$result" | jq -e '.modifiers // [] | contains(["shift"])' > /dev/null 2>&1; then
+    echo "shift was held"
+fi
+```
+
 ### Streaming
 
 Input can arrive over time. The list populates progressively
@@ -96,6 +133,12 @@ There are two ways to respond to them: **exec hooks** and
 | `on-filter` | Filter text changes | Dynamic item reloading |
 | `on-toggle` | User toggles an item's selection | Visual feedback (deferred) |
 
+Hook event JSON includes a `modifiers` field on `select`,
+`cancel`, `filter`, `hover`, and `quicklist` events when
+modifier keys were held. Same format as structured output:
+an array of strings like `["shift"]` or `["ctrl", "alt"]`.
+Omitted when no modifiers are active.
+
 ### Exec Hooks (fire-and-forget)
 
 `--on-<event>-exec` spawns a subprocess for each event.
@@ -770,6 +813,18 @@ Available actions:
 | `show-tui` | (none) | Hand off to TUI specifically |
 | `show-gui` | (none) | Hand off to GUI specifically |
 
+Actions can include modifier key prefixes with `+`:
+
+```
++shift confirm
++ctrl+alt move-down 3
+```
+
+Valid modifiers: `shift`, `ctrl`, `alt`. Multiple modifiers
+chain with `+`. Lines without a `+` prefix work exactly as
+before. This lets scripts signal intent to hooks and
+structured output the same way a user holding Shift would.
+
 `show-ui` auto-detects the appropriate interactive frontend
 (Wayland: GUI, X11: GUI, otherwise: TUI). `show-tui` and
 `show-gui` are explicit overrides. All three must be the

docs/DEVPLAN.md

@@ -170,7 +170,7 @@ through hooks and structured I/O. A handler hook can
 receive hover events and emit commands to modify menu
 state.
 
-## Phase 4: Multi-Select
+## Phase 4: Multi-Select ✓
 
 Selection with undo/redo. No marks or registers: filtering
 already handles navigation, and selections surviving filter
@@ -275,21 +275,30 @@ pikl instance over the socket, push items, read state, and
 subscribe to events. A named session remembers filter
 history across invocations.
 
-## Phase 7: Streaming & Watched Sources
+## Phase 7: Streaming Stdin ✓
 
-Live, dynamic menus.
+Auto-detected streaming when stdin is a pipe (not action-fd,
+not CSV/TSV). The menu opens immediately with zero items and
+streams them in as they arrive.
+
+`--watch` was dropped from this phase. External tools like
+`inotifywait -m ~/walls | pikl` compose naturally with
+streaming stdin. No built-in file watcher needed.
 
 **Deliverables:**
-- Async/streaming stdin (items arrive over time, list
-  updates progressively)
-- Streaming output (on-hover events emitted to stdout)
-- `--watch path` for file/directory watching
-- `--watch-extensions` filter
-- notify crate integration (inotify on Linux, FSEvents
-  on macOS)
+- Auto-detected streaming stdin (items arrive over time,
+  list updates progressively)
+- `StreamingDone` action signals end of input
+- `streaming` flag on ViewState for frontend indicators
+- TUI shows `...` suffix on the count while streaming
+- Background reader with batched `AddItems` (up to 100
+  items per batch, flushes immediately for slow sources)
+- `streaming-done` action-fd command for test scripts
+- No new CLI flags: streaming is auto-detected
 
-**Done when:** `find / -name '*.log' | pikl` populates
-progressively. A watched directory updates the list live.
+**Done when:** `seq 1 10000 | pikl` opens immediately and
+items stream in. Slow sources show items appearing one at
+a time with a `...` indicator.
 
 ## Phase 8: GUI Frontend (Wayland + X11)
 
@@ -340,7 +349,14 @@ navigate directories without spawning new processes.
   pass `-la` to it. The output would include both the
   selected item and the user-supplied arguments.
 
-  Open questions:
+  **Partially resolved:** modifier key support has landed.
+  Structured output and hook events now carry a `modifiers`
+  field when shift/ctrl/alt are held during confirmation.
+  This covers the signaling side: scripts can detect
+  Shift+Enter and branch on it. The free-text argument
+  input (where does the user type `-la`?) is still open.
+
+  Remaining open questions:
   - UX flow: does the filter text become the args on
     Shift+Enter? Or does Shift+Enter open a second input
     field for args after selection? The filter-as-args
@@ -354,9 +370,6 @@ navigate directories without spawning new processes.
     matches exactly one item just confirm that item (current
     behaviour), or should it also treat any "extra" text
     as args? Probably not, too implicit.
-  - Keybind: Shift+Enter is natural, but some terminals
-    don't distinguish it from Enter. May need a fallback
-    like Ctrl+Enter or a normal-mode keybind.
 
   This is a core feature (new keybind, new output field),
   not just a launcher script concern. Fits naturally after
@@ -403,3 +416,4 @@ commitment, no order.
   to run per-keystroke" problem for the app launcher.
   Could be a `pikl index` subcommand or a standalone
   helper script.
+- Need vars in hooks like `--on-hover 'echo $out'`.

docs/use-cases/wallpaper-picker.md

@@ -126,7 +126,7 @@ bind = $mod, B, exec, wallpicker copy
 | Hook debouncing | 3 | Don't flood hyprctl |
 | Fuzzy filtering | 2 | Filter by filename |
 | Manifest files | 3 | Reusable config |
-| Watched sources | 7 | Live update on new files |
+| Streaming stdin | 7 | Progressive load from find |
 | Sessions | 6 | Remember last position |
 
 ## Open Questions