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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
//! Local, revision-safe browser intelligence for Chrome and Chromium.
//!
//! `glass-browser` provides an owned/attached browser [`BrowserSession`],
//! structured semantic observation, guarded actions, stable Web IR, Task
//! Protocol compilation/execution, workflows, advisory knowledge, policy,
//! MCP, daemon, TUI, backend, surface, presentation, and reliability contracts.
//!
//! Glass does not bundle a browser, host a browser service, or infer an
//! autonomous plan. Callers select operations; Glass validates current
//! evidence, policy, capabilities, revisions, unique targeting, and bounded
//! postconditions. CDP is the production backend. WebDriver BiDi remains an
//! experimental bounded adapter.
//!
//! # Choose an entry point
//!
//! | Goal | Entry point |
//! |---|---|
//! | Drive an owned or attached browser | [`BrowserSession`] and [`SessionOptions`] |
//! | Collect stable evidence | [`extraction`] and [`web_ir`] |
//! | Compile/execute semantic tasks | [`task_protocol`] and [`task_compiler`] |
//! | Run typed workflows | [`browser::session::WorkflowDefinition`] |
//! | Share standalone/embedded browser UI state | [`browser_workspace`] |
//! | Assess scoped historical knowledge | [`KnowledgeStore`] |
//! | Implement/select a backend | [`browser_backend`] and [`browser::BackendFactory`] |
//! | Expose MCP or canonical requests | [`mcp`] and [`protocol`] |
//! | Present terminal frames | [`presentation`] and [`terminal_graphics`] |
//!
//! # Browser lifecycle
//!
//! Start, navigate, observe, and explicitly close an owned session:
//!
//! ```rust,no_run
//! use glass_browser::{BrowserSession, SessionOptions};
//!
//! # async fn run() -> glass_browser::BrowserResult<()> {
//! let options = SessionOptions::builder().incognito(true).build()?;
//! let session = BrowserSession::start(&options).await?;
//! let page = session.navigate("https://example.com").await?;
//! let observation = session.observe().await?;
//! println!("{} revision={}", page.url, observation.accessibility.revision);
//! session.close().await?;
//! # Ok(())
//! # }
//! ```
//!
//! `close` sends `Browser.close` before process fallback so owned profile state
//! can flush. Attach mode does not own or close the external Chrome process.
//! [`SessionOptions::validate`] rejects incompatible attach/launch settings.
//!
//! # Structured observation and guarded action
//!
//! Compact observation is the default low-cost context. Semantic observation
//! exposes typed page, region, target, record, route, and revision state:
//!
//! ```rust,no_run
//! use glass_browser::browser::session::SemanticObservationLevel;
//! use glass_browser::{BrowserSession, SessionOptions};
//!
//! # async fn run() -> glass_browser::BrowserResult<()> {
//! let session = BrowserSession::start(&SessionOptions::builder().build()?).await?;
//! let semantic = session
//! .semantic_observe(SemanticObservationLevel::Interactive)
//! .await?;
//! println!("regions={}", semantic.regions.len());
//!
//! let current = session.observe().await?;
//! let outcome = session
//! .click_with_revision(
//! "role=button[name=Save]",
//! current.accessibility.revision,
//! )
//! .await?;
//! println!("status={:?}", outcome.status);
//! session.close().await
//! # }
//! ```
//!
//! Normal observation does not request a screenshot, full DOM, or form values.
//! Those evidence paths are explicit and policy-sensitive. A locator must
//! resolve exactly one actionable current target. A stale expected revision
//! fails before input.
//!
//! # Evidence, Web IR, and tasks
//!
//! [`ExtractionRequest`] selects source-labelled evidence and hard budgets.
//! [`BrowserSession::extract_web_ir`] reconciles it into stable
//! [`GlassWebIrV1`]. Offline callers can validate, diff, and classify
//! continuity without starting Chrome.
//!
//! [`GlassTask::from_json`] validates a strict authored semantic task.
//! [`compile_task`] compiles it against Web IR without browser access or side
//! effects. Plans and receipts contain input names but never authored input
//! values or live browser references. Live execution re-extracts evidence,
//! binds every semantic key to exactly one current revisioned target, applies
//! confirmation/lease rules, and verifies postconditions.
//! The offline JSON example uses the application's direct `serde_json`
//! dependency; typed session APIs do not require callers to serialize
//! intermediate contracts.
//!
//! ```rust,no_run
//! use glass_browser::{compile_task, GlassTask, GlassWebIrV1};
//!
//! fn compile(task_json: &str, ir_json: &str)
//! -> Result<String, Box<dyn std::error::Error>>
//! {
//! let task = GlassTask::from_json(task_json)?;
//! let ir: GlassWebIrV1 = serde_json::from_str(ir_json)?;
//! ir.validate()?;
//! Ok(compile_task(&task, &ir)?.to_canonical_json()?)
//! }
//! ```
//!
//! Historical knowledge is advisory. It may explain or rank current evidence,
//! but cannot supply an executable reference or authorize mutation.
//!
//! # Cargo features
//!
//! - `visual-compare` enables PNG comparison helpers for explicit screenshot
//! checks.
//! - `fuzzing` enables test-only fuzz hooks and is not for normal applications.
//!
//! docs.rs builds all features. The default library remains browser-focused.
//!
//! # Failure and privacy rules
//!
//! Unknown variants/fields, oversized input, stale revisions, ambiguous
//! targets, unsafe paths, unsupported capabilities, and incompatible backend
//! responses fail explicitly. An `indeterminate` mutation result means Chrome
//! may have accepted input; reconcile current state instead of retrying
//! blindly.
//!
//! Treat DOM, screenshots, PDFs, cookies, storage, evaluated values, profiles,
//! and diagnostics as sensitive. MCP stdout is protocol-only. Structured
//! audit and execution receipts omit typed values, raw selectors, raw CDP
//! errors, and browser handles.
//!
//! # Module map
//!
//! - [`browser`] — Chrome lifecycle, CDP client, DOM/accessibility parsing,
//! policy, profiles, actions, observations, workflows, and knowledge.
//! - [`browser_backend`] — semantic backend capabilities, requests, responses,
//! errors, and mandatory dispatcher.
//! - [`capabilities`] — versioned discovery and negotiation manifest.
//! - [`cli`] — Clap argument definitions and command dispatch.
//! - [`connection`] — independent layout, transport, graphics, shell,
//! multiplexer, presentation-policy, and observatory contracts.
//! - [`daemon`] — local Unix-socket lifecycle, isolated MCP children, leases,
//! logs, and interrupted-run recovery.
//! - [`extensions`] — bounded manifests, permissions, registry, sandbox, and
//! guarded action boundary.
//! - [`extraction`] — strict bounded evidence requests and source-labelled facts.
//! - [`mcp`] — JSON-RPC/MCP stdio server, prompts, resources, and tools.
//! - [`presentation`] — browser-neutral frame metadata, geometry, mailbox,
//! ownership, and metrics.
//! - [`protocol`] — canonical versioned request/response operations.
//! - [`reliability`] / [`reliability_runner`] — scenarios, replay evidence,
//! scorecards, gates, and bounded browser execution.
//! - [`results`] — agent-facing response projections and local diagnostic
//! artifacts.
//! - [`surfaces`] — nested surface evidence, coverage, provenance, and grants.
//! - [`task_protocol`] / [`task_compiler`] — strict authored tasks and
//! deterministic execution plans.
//! - [`terminal_graphics`] — Herdr, Kitty, ANSI, and semantic render adapters.
//! - [`tui`] — Ratatui reducer, browser worker, layouts, and remote live view.
//! - [`web_ir`] — stable reconciliation, validation, diff, and continuity.
//! - [`workspace`] — identity, ownership, lifecycle, attachments, and
//! persistence.
//!
//! # Guides and examples
//!
//! - [Rust SDK](https://github.com/wanazhar/glass/blob/main/docs/rust-sdk.md)
//! - [Runnable examples](https://github.com/wanazhar/glass/blob/main/docs/examples.md)
//! - [Complete feature reference](https://github.com/wanazhar/glass/blob/main/docs/features.md)
//! - [MCP tool catalog](https://github.com/wanazhar/glass/blob/main/docs/mcp-tools.md)
//! - [Security policy](https://github.com/wanazhar/glass/blob/main/SECURITY.md)
/// Browser control modules and the reusable [`browser::BrowserSession`] API.
/// Transport-neutral backend capability contract.
/// Canonical human-facing browser state, actions, focus, and recovery model.
/// Versioned Glass protocol and capability negotiation.
/// Command-line argument definitions and dispatch helpers.
/// Independent connection-environment and presentation-policy contracts.
/// Local Unix-socket daemon lifecycle and MCP bridge.
/// Validated extension metadata and permission boundaries.
/// Experimental bounded browser-evidence extraction contracts.
/// MCP stdio server, prompts, resources, and tool dispatch.
/// Browser-neutral terminal frame presentation contracts.
/// Transport-neutral versioned request and response envelopes.
/// Versioned browser-free reliability scenario contracts.
/// Bounded browser execution for reliability scenarios and replay evidence.
/// Bounded agent-facing response projections and local result artifacts.
/// Bounded, evidenced browser surface contracts.
/// Browser-free deterministic Task Protocol execution-plan compiler.
/// Strict, bounded authored Task Protocol v1 inputs.
/// Bounded terminal graphics adapters.
/// Ratatui terminal interface.
/// Stable Glass Web IR v1 reconciliation and validation.
/// Bounded workspace identity and lifecycle contracts.
// Keep the most common embedding types on the crate root. Lower-level and
// capability-specific APIs remain organized under `glass_browser::browser`.
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
/// Re-export the bounded extraction contract for embedding callers.
pub use ;
/// Re-export the stable Glass Web IR v1 contract for embedding callers.
pub use ;