pub struct ShadowDom<D: Desktop> { /* private fields */ }Expand description
A cached registry of named live element handles. Does not own the desktop;
callers pass &D to the methods that need to re-query the UIA tree.
Implementations§
Source§impl<D: Desktop> ShadowDom<D>
impl<D: Desktop> ShadowDom<D>
pub fn new() -> Self
Sourcepub fn set_depth(&mut self, depth: usize)
pub fn set_depth(&mut self, depth: usize)
Set the current subflow depth. At depth 0, all anchors use their raw name.
At depth N, Stable/Ephemeral anchors are stored under ":".repeat(N) + name.
Sourcepub fn set_launch_context(&mut self, ctx: LaunchContext)
pub fn set_launch_context(&mut self, ctx: LaunchContext)
Store the launch context so root-anchor first-resolutions use it for filtering.
Sourcepub fn mount(
&mut self,
anchors: Vec<AnchorDef>,
desktop: &D,
) -> Result<(), AutomataError>
pub fn mount( &mut self, anchors: Vec<AnchorDef>, desktop: &D, ) -> Result<(), AutomataError>
Register anchor definitions and immediately resolve Root-tier anchors.
Sourcepub fn insert(&mut self, name: impl Into<String>, element: D::Elem)
pub fn insert(&mut self, name: impl Into<String>, element: D::Elem)
Insert an element directly into the cache (used for Ephemeral captures).
Sourcepub fn get(
&mut self,
name: &str,
desktop: &D,
) -> Result<&D::Elem, AutomataError>
pub fn get( &mut self, name: &str, desktop: &D, ) -> Result<&D::Elem, AutomataError>
Retrieve a live handle by name. Re-queries if the cached handle is stale.
Returns Err if the anchor cannot be resolved (root gone, selector
not found after walk-up, or name not registered).
Sourcepub fn invalidate_session(&mut self, session_name: &str)
pub fn invalidate_session(&mut self, session_name: &str)
Remove a session anchor and all stable anchors that depend on it.
Sourcepub fn unmount(&mut self, names: &[&str], desktop: &D)
pub fn unmount(&mut self, names: &[&str], desktop: &D)
Unmount anchors by name, removing their definition, cached handle, and
snapshot. The symmetric inverse of mount: after this
call the names are completely unknown to the registry.
Root and Session anchors are globally shared and cannot be unmounted this way; a warning is logged and the name is skipped.
Any Tab anchor whose tab was opened by the workflow (created=true) is
closed via desktop.browser().close_tab() before its handle is removed.
Sourcepub fn is_live(&self, name: &str) -> bool
pub fn is_live(&self, name: &str) -> bool
Check whether a handle is currently cached and live (no re-query).
Sourcepub fn find_descendant(
&mut self,
scope: &str,
selector: &SelectorPath,
desktop: &D,
) -> Result<Option<D::Elem>, AutomataError>
pub fn find_descendant( &mut self, scope: &str, selector: &SelectorPath, desktop: &D, ) -> Result<Option<D::Elem>, AutomataError>
Find a descendant element matching selector within scope, using a
stale-first strategy with partial-tree re-resolution:
- Cache hit, live → return immediately (1 COM call, no DFS).
- Cache hit, stale, step-parent live → re-run the selector’s last step from the cached step-parent (narrow search — O(subtree) not O(whole tree)). Update the cache on success; fall through on failure.
- Cache hit, stale, step-parent also stale → clear cache entry, fall through to full DFS.
- Cache miss → full
find_onetraversal from the anchor root; cache both the result and its step-parent for next time.
The cache is cleared whenever the scope anchor is re-resolved or unmounted.
Sourcepub fn sync_changes(&mut self, name: &str, desktop: &D) -> Vec<String>
pub fn sync_changes(&mut self, name: &str, desktop: &D) -> Vec<String>
Snapshot the live subtree of name, diff against the previous snapshot,
emit each change to the tracer, and return the change lines.
The returned Vec is empty when nothing changed. Each line has the form:
dom: <scope>: ADDED [role "name"]
dom: <scope> > [role "name"]: REMOVED [child-role "child"]
dom: <scope>: name "old" → "new"Primarily used by the executor’s poll loop, but also directly testable.
Sourcepub fn sync(&mut self, name: &str, desktop: &D)
pub fn sync(&mut self, name: &str, desktop: &D)
Like [sync_changes] but discards the return value.
Convenience for the executor’s poll loop.
Sourcepub fn anchor_pid(&self, name: &str) -> Option<u32>
pub fn anchor_pid(&self, name: &str) -> Option<u32>
Returns the effective PID for a registered anchor. Prefers the locked PID (captured on first resolution) over the statically declared PID, since the locked value is always the more specific one.
Sourcepub fn anchor_hwnd(&self, name: &str) -> Option<u64>
pub fn anchor_hwnd(&self, name: &str) -> Option<u64>
Returns the locked HWND for a registered anchor, if one was captured on first resolution.
Sourcepub fn tab_handle(&self, name: &str) -> Option<&TabHandle>
pub fn tab_handle(&self, name: &str) -> Option<&TabHandle>
Return a reference to the tab handle for name, if present.
Sourcepub fn cleanup_depth(&mut self, depth: usize, desktop: &D)
pub fn cleanup_depth(&mut self, depth: usize, desktop: &D)
Remove all anchors stored at exactly depth (keys prefixed with exactly
":".repeat(depth) followed by a non-colon character).
Acts as a safety net for anything not explicitly unmounted by the subflow.
Any created Tab anchors at this depth are closed via desktop.browser().close_tab().