scarab_plugin_api/object_model/mod.rs
1//! Object Model for exposing terminal state to Fusabi scripts
2//!
3//! This module provides handle-based proxies that allow Fusabi scripts
4//! to interact with Window, Pane, and Tab objects.
5//!
6//! # Architecture
7//!
8//! The object model uses a handle-based approach similar to WezTerm's Lua API:
9//!
10//! 1. **Handles**: Lightweight, copyable references to objects
11//! 2. **Registry**: Centralized storage for objects with lifecycle management
12//! 3. **Generation Counters**: Detect stale handles after object deletion
13//!
14//! # Example
15//!
16//! ```
17//! use scarab_plugin_api::object_model::{ObjectHandle, ObjectType, WindowProxy};
18//!
19//! // Create a handle
20//! let handle = ObjectHandle::new(ObjectType::Window, 1, 0);
21//!
22//! // Create a proxy from the handle
23//! let window = WindowProxy::new(handle).unwrap();
24//!
25//! // Check validity
26//! assert!(handle.is_valid(0));
27//! assert!(!handle.is_valid(1));
28//! ```
29//!
30//! # Handle-Based Design
31//!
32//! Instead of passing raw object references to scripts, we use handles:
33//!
34//! - **Safety**: Scripts can't hold dangling references
35//! - **Serialization**: Handles can cross process boundaries
36//! - **Invalidation**: Generation counters detect deleted objects
37//! - **Type Safety**: ObjectType enum prevents type confusion
38//!
39//! # Lifecycle Management
40//!
41//! Objects follow this lifecycle:
42//!
43//! 1. **Registration**: Object is stored, handle is returned
44//! 2. **Access**: Handle is used to retrieve object from registry
45//! 3. **Unregistration**: Object is removed, generation is incremented
46//! 4. **Invalidation**: Old handles fail validation checks
47//!
48//! # Thread Safety
49//!
50//! All types in this module are designed to be `Send + Sync`:
51//!
52//! - Handles contain only primitive types
53//! - Registry trait can be implemented with appropriate locking
54//! - Errors are cloneable for propagation across threads
55
56mod error;
57mod handle;
58mod pane;
59mod registry;
60mod tab;
61mod window;
62
63pub use error::{ObjectError, Result};
64pub use handle::{ObjectHandle, ObjectType};
65pub use pane::PaneProxy;
66pub use registry::{ObjectRegistry, RegistryEntry};
67pub use tab::TabProxy;
68pub use window::WindowProxy;