1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
// Copyright (c) 2025 R3BL LLC. Licensed under Apache License, Version 2.0.
//! OSC event types and definitions.
/// Represents parsed events from INCOMING OSC (Operating System Command) sequences.
///
/// These events are extracted when parsing OSC sequences received FROM applications
/// and represent the semantic meaning of those sequences. This is distinct from
/// `OscSequence` which is used to build OUTGOING OSC sequences to send TO the terminal.
///
/// ## Architecture Overview
///
/// The OSC processing pipeline has two distinct directions:
///
/// ### INCOMING (Application → Terminal Emulator)
/// 1. Application sends OSC sequences (e.g., `ESC]9;4;1;50ESC\\` for 50% progress)
/// 2. ANSI parser extracts these into `OscEvent` variants
/// 3. Terminal emulator acts on these events (updates progress bar, sets title, etc.)
///
/// ### OUTGOING (Terminal Emulator → Application)
/// 1. Terminal emulator needs to send OSC sequences
/// 2. Creates `OscSequence` instances
/// 3. Formats them using `FastStringify`/`Display` traits
/// 4. Sends formatted sequences to the application
///
/// ## Common OSC Events
///
/// - **Progress Tracking**: Build tools like cargo send progress updates
/// - **Window Management**: Applications can set terminal title/tab names
/// - **Hyperlinks**: Modern terminals support clickable links in output
///
/// ## Usage Example
///
/// ```rust
/// use r3bl_tui::OscEvent;
///
/// // Example of matching OSC events:
/// let event = OscEvent::ProgressUpdate(75);
/// match event {
/// OscEvent::ProgressUpdate(pct) => {
/// println!("Progress: {}%", pct);
/// },
/// OscEvent::SetTitleAndTab(title) => {
/// println!("Title set to: {}", title);
/// },
/// _ => {
/// println!("Other OSC event");
/// }
/// }
/// ```
///
/// ## Relationship to Other Types
///
/// - **`OscSequence`**: Builds OUTGOING OSC sequences for terminal output
/// - **`DsrRequestFromPty`**: Represents DSR requests FROM PTY requiring responses
/// - **`CsiSequence`**: Builds OUTGOING CSI sequences for cursor/formatting control