Skip to main content

glass_dev/
browser.rs

1//! Resident browser and workflow ownership for the Glass development workspace.
2
3use crate::development::{DevelopmentError, DevelopmentResult};
4use crate::development::{RemoteFrame, RemoteInput, RemoteView};
5use glass_browser::browser::policy::{BrowserPolicy, PolicyPreset};
6use glass_browser::browser::session::{
7    BrowserSession, SemanticObservationLevel, SessionOptions, WorkflowCheckpoint,
8    WorkflowDefinition, WorkflowRunResult,
9};
10use glass_browser::extraction::ExtractionRequest;
11use glass_browser::protocol::WebIrInspectionResult;
12use serde::{Deserialize, Serialize};
13use serde_json::Value;
14use std::collections::BTreeMap;
15use std::path::{Path, PathBuf};
16use std::sync::mpsc::{self, SyncSender};
17use std::time::Duration;
18
19const COMMAND_QUEUE: usize = 32;
20const COMMAND_TIMEOUT: Duration = Duration::from_secs(180);
21
22/// Options used to create or attach the resident development browser session.
23#[derive(Debug, Clone, Serialize, Deserialize)]
24#[serde(default, rename_all = "camelCase")]
25pub struct BrowserStartConfig {
26    /// Chrome DevTools port.
27    pub port: u16,
28    /// Attach to an existing browser rather than launching one.
29    pub attach: bool,
30    /// Use an isolated incognito context.
31    pub incognito: bool,
32    /// Show the browser window.
33    pub headed: bool,
34    /// Named profile passed to the browser session.
35    pub profile: String,
36    /// Optional explicit Chrome executable path.
37    pub chrome_path: Option<PathBuf>,
38}
39
40impl Default for BrowserStartConfig {
41    fn default() -> Self {
42        Self {
43            port: default_port(),
44            attach: false,
45            incognito: true,
46            headed: false,
47            profile: default_profile(),
48            chrome_path: None,
49        }
50    }
51}
52
53fn default_port() -> u16 {
54    9222
55}
56
57fn default_profile() -> String {
58    "default".into()
59}
60
61/// Serializable state of the resident browser worker.
62#[derive(Debug, Clone, Serialize)]
63#[serde(rename_all = "camelCase")]
64pub struct BrowserRuntimeState {
65    /// Policy preset governing browser capabilities and host access.
66    pub policy_preset: PolicyPreset,
67    /// Whether a browser session is connected.
68    pub connected: bool,
69    /// PID when this service owns the browser process.
70    pub browser_process_id: Option<u32>,
71    /// Latest observation revision known to the worker.
72    pub browser_revision: Option<u64>,
73    /// Current workflow lifecycle state.
74    pub workflow_state: String,
75    /// Identifier of the active workflow, if any.
76    pub active_workflow: Option<String>,
77}
78
79enum BrowserCommand {
80    Start(BrowserStartConfig),
81    Reconnect,
82    Stop,
83    State,
84    Observe,
85    Snapshot,
86    Semantic(SemanticObservationLevel),
87    WebIr,
88    Diff,
89    Targets,
90    SelectTarget(String),
91    Navigate {
92        url: String,
93        expected_revision: u64,
94        timeout: Duration,
95    },
96    Back(u64),
97    Forward(u64),
98    Reload(u64),
99    StopLoading(u64),
100    Highlight {
101        target: String,
102        expected_revision: u64,
103    },
104    Click {
105        target: String,
106        expected_revision: u64,
107    },
108    Type {
109        text: String,
110        target: Option<String>,
111        expected_revision: u64,
112    },
113    Scroll {
114        dx: f64,
115        dy: f64,
116        expected_revision: u64,
117    },
118    Screenshot,
119    RunWorkflow {
120        definition: Value,
121        inputs: BTreeMap<String, Value>,
122    },
123    PauseWorkflow,
124    ResumeWorkflow {
125        definition: Value,
126        inputs: BTreeMap<String, Value>,
127        checkpoint: Value,
128    },
129    ListWorkflows,
130    CancelWorkflow,
131    VerifyWorkflow,
132    RemoteViewOpen,
133    RemoteViewStatus,
134    RemoteViewRevoke,
135}
136
137type Reply = SyncSender<DevelopmentResult<Value>>;
138
139/// Cloneable command handle for the one authoritative browser worker.
140#[derive(Clone)]
141pub struct BrowserService {
142    commands: SyncSender<(BrowserCommand, Reply)>,
143}
144
145impl BrowserService {
146    /// Create a resident browser worker with the development policy.
147    pub fn new(root: impl AsRef<Path>) -> DevelopmentResult<Self> {
148        Self::new_with_policy(root, PolicyPreset::Development)
149    }
150
151    /// Create a resident browser worker with an explicit authorization preset.
152    pub fn new_with_policy(
153        root: impl AsRef<Path>,
154        policy_preset: PolicyPreset,
155    ) -> DevelopmentResult<Self> {
156        let root = root.as_ref().to_path_buf();
157        let (commands, receiver) = mpsc::sync_channel::<(BrowserCommand, Reply)>(COMMAND_QUEUE);
158        std::thread::Builder::new()
159            .name("glass-browser-workspace".into())
160            .spawn(move || {
161                let runtime = tokio::runtime::Builder::new_current_thread()
162                    .enable_all()
163                    .build();
164                let Ok(runtime) = runtime else {
165                    return;
166                };
167                let mut worker = BrowserWorker::new(root, policy_preset);
168                while let Ok((command, reply)) = receiver.recv() {
169                    let result = runtime.block_on(worker.execute(command));
170                    let _ = reply.send(result);
171                }
172                runtime.block_on(worker.shutdown());
173            })
174            .map_err(|error| DevelopmentError::Process(error.to_string()))?;
175        Ok(Self { commands })
176    }
177
178    fn call(&self, command: BrowserCommand) -> DevelopmentResult<Value> {
179        let (reply, receiver) = mpsc::sync_channel(1);
180        self.commands
181            .send((command, reply))
182            .map_err(|_| DevelopmentError::Process("resident browser worker stopped".into()))?;
183        receiver.recv_timeout(COMMAND_TIMEOUT).map_err(|error| {
184            DevelopmentError::Process(format!("resident browser command timed out: {error}"))
185        })?
186    }
187
188    /// Start a browser session; fails if one is already connected.
189    pub fn start(&self, config: BrowserStartConfig) -> DevelopmentResult<Value> {
190        self.call(BrowserCommand::Start(config))
191    }
192
193    /// Stop the session and revoke any remote view.
194    pub fn stop(&self) -> DevelopmentResult<Value> {
195        self.call(BrowserCommand::Stop)
196    }
197
198    /// Restart using the most recent start configuration.
199    pub fn reconnect(&self) -> DevelopmentResult<Value> {
200        self.call(BrowserCommand::Reconnect)
201    }
202
203    /// Return connection, workflow, and latest revision state.
204    pub fn state(&self) -> DevelopmentResult<Value> {
205        self.call(BrowserCommand::State)
206    }
207
208    /// Capture a fresh observation and advance the worker's known revision.
209    pub fn observe(&self) -> DevelopmentResult<Value> {
210        self.call(BrowserCommand::Observe)
211    }
212
213    /// Capture the session's current snapshot without forcing a fresh observe.
214    pub fn snapshot(&self) -> DevelopmentResult<Value> {
215        self.call(BrowserCommand::Snapshot)
216    }
217
218    /// Capture semantic observations at the requested level.
219    pub fn semantic(&self, level: SemanticObservationLevel) -> DevelopmentResult<Value> {
220        self.call(BrowserCommand::Semantic(level))
221    }
222
223    /// Extract the current page into a bounded Web IR inspection summary.
224    pub fn web_ir(&self) -> DevelopmentResult<Value> {
225        self.call(BrowserCommand::WebIr)
226    }
227
228    /// Return the observation delta since the session's previous revision.
229    pub fn diff(&self) -> DevelopmentResult<Value> {
230        self.call(BrowserCommand::Diff)
231    }
232
233    /// List browser targets.
234    pub fn targets(&self) -> DevelopmentResult<Value> {
235        self.call(BrowserCommand::Targets)
236    }
237
238    /// Select a target and return a fresh observation for it.
239    pub fn select_target(&self, target: String) -> DevelopmentResult<Value> {
240        self.call(BrowserCommand::SelectTarget(target))
241    }
242
243    /// Navigate if `expected_revision` still matches; `timeout` bounds navigation.
244    pub fn navigate(
245        &self,
246        url: String,
247        expected_revision: u64,
248        timeout: Duration,
249    ) -> DevelopmentResult<Value> {
250        self.call(BrowserCommand::Navigate {
251            url,
252            expected_revision,
253            timeout,
254        })
255    }
256    /// Go back if the supplied observation revision is current.
257    pub fn back(&self, expected_revision: u64) -> DevelopmentResult<Value> {
258        self.call(BrowserCommand::Back(expected_revision))
259    }
260    /// Go forward if the supplied observation revision is current.
261    pub fn forward(&self, expected_revision: u64) -> DevelopmentResult<Value> {
262        self.call(BrowserCommand::Forward(expected_revision))
263    }
264    /// Reload if the supplied observation revision is current.
265    pub fn reload(&self, expected_revision: u64) -> DevelopmentResult<Value> {
266        self.call(BrowserCommand::Reload(expected_revision))
267    }
268    /// Stop loading if the supplied observation revision is current.
269    pub fn stop_loading(&self, expected_revision: u64) -> DevelopmentResult<Value> {
270        self.call(BrowserCommand::StopLoading(expected_revision))
271    }
272    /// Highlight a target if the supplied observation revision is current.
273    pub fn highlight(&self, target: String, expected_revision: u64) -> DevelopmentResult<Value> {
274        self.call(BrowserCommand::Highlight {
275            target,
276            expected_revision,
277        })
278    }
279    /// Click a target if the supplied observation revision is current.
280    pub fn click(&self, target: String, expected_revision: u64) -> DevelopmentResult<Value> {
281        self.call(BrowserCommand::Click {
282            target,
283            expected_revision,
284        })
285    }
286    /// Type text into the selected or explicit target at the current revision.
287    pub fn type_text(
288        &self,
289        text: String,
290        target: Option<String>,
291        expected_revision: u64,
292    ) -> DevelopmentResult<Value> {
293        self.call(BrowserCommand::Type {
294            text,
295            target,
296            expected_revision,
297        })
298    }
299    /// Scroll by the requested delta at the current observation revision.
300    pub fn scroll(&self, dx: f64, dy: f64, expected_revision: u64) -> DevelopmentResult<Value> {
301        self.call(BrowserCommand::Scroll {
302            dx,
303            dy,
304            expected_revision,
305        })
306    }
307    /// Capture a screenshot of the connected browser.
308    pub fn screenshot(&self) -> DevelopmentResult<Value> {
309        self.call(BrowserCommand::Screenshot)
310    }
311
312    /// Start a workflow from its JSON definition and named inputs.
313    pub fn run_workflow(
314        &self,
315        definition: Value,
316        inputs: BTreeMap<String, Value>,
317    ) -> DevelopmentResult<Value> {
318        self.call(BrowserCommand::RunWorkflow { definition, inputs })
319    }
320
321    /// Pause the active workflow and retain its checkpoint.
322    pub fn pause_workflow(&self) -> DevelopmentResult<Value> {
323        self.call(BrowserCommand::PauseWorkflow)
324    }
325
326    /// Resume a workflow from a caller-provided checkpoint.
327    pub fn resume_workflow(
328        &self,
329        definition: Value,
330        inputs: BTreeMap<String, Value>,
331        checkpoint: Value,
332    ) -> DevelopmentResult<Value> {
333        self.call(BrowserCommand::ResumeWorkflow {
334            definition,
335            inputs,
336            checkpoint,
337        })
338    }
339
340    /// List workflow definitions known to the connected session.
341    pub fn list_workflows(&self) -> DevelopmentResult<Value> {
342        self.call(BrowserCommand::ListWorkflows)
343    }
344
345    /// Cancel the active workflow.
346    pub fn cancel_workflow(&self) -> DevelopmentResult<Value> {
347        self.call(BrowserCommand::CancelWorkflow)
348    }
349
350    /// Verify the active workflow's completion conditions.
351    pub fn verify_workflow(&self) -> DevelopmentResult<Value> {
352        self.call(BrowserCommand::VerifyWorkflow)
353    }
354
355    /// Open a remote-view capability for the connected browser.
356    pub fn open_remote_view(&self) -> DevelopmentResult<Value> {
357        self.call(BrowserCommand::RemoteViewOpen)
358    }
359
360    /// Return remote-view status and current capability state.
361    pub fn remote_view_status(&self) -> DevelopmentResult<Value> {
362        self.call(BrowserCommand::RemoteViewStatus)
363    }
364
365    /// Revoke the remote-view capability.
366    pub fn revoke_remote_view(&self) -> DevelopmentResult<Value> {
367        self.call(BrowserCommand::RemoteViewRevoke)
368    }
369}
370struct BrowserWorker {
371    root: PathBuf,
372    policy_preset: PolicyPreset,
373    session: Option<BrowserSession>,
374    revision: Option<u64>,
375    workflow_state: String,
376    active_workflow: Option<String>,
377    last_workflow: Option<(WorkflowDefinition, WorkflowRunResult)>,
378    last_config: Option<BrowserStartConfig>,
379    remote_view: Option<RemoteView>,
380}
381
382impl BrowserWorker {
383    fn new(root: PathBuf, policy_preset: PolicyPreset) -> Self {
384        Self {
385            root,
386            policy_preset,
387            session: None,
388            revision: None,
389            workflow_state: "idle".into(),
390            active_workflow: None,
391            last_workflow: None,
392            last_config: None,
393            remote_view: None,
394        }
395    }
396
397    fn state(&self) -> BrowserRuntimeState {
398        BrowserRuntimeState {
399            policy_preset: self.policy_preset,
400            connected: self.session.is_some(),
401            browser_process_id: self
402                .session
403                .as_ref()
404                .and_then(BrowserSession::owned_chrome_pid),
405            browser_revision: self.revision,
406            workflow_state: self.workflow_state.clone(),
407            active_workflow: self.active_workflow.clone(),
408        }
409    }
410
411    fn session(&self) -> DevelopmentResult<&BrowserSession> {
412        self.session.as_ref().ok_or_else(|| {
413            DevelopmentError::Conflict(
414                "browser is not connected; call glass.browser.start first".into(),
415            )
416        })
417    }
418
419    async fn shutdown(&mut self) {
420        if let Some(view) = self.remote_view.take() {
421            view.revoke().await;
422        }
423        if let Some(session) = self.session.take() {
424            let _ = session.close().await;
425        }
426        self.revision = None;
427        self.workflow_state = "idle".into();
428        self.active_workflow = None;
429        self.last_workflow = None;
430    }
431
432    async fn start_session(&mut self, config: BrowserStartConfig) -> DevelopmentResult<Value> {
433        if self.session.is_some() {
434            return Err(DevelopmentError::Conflict(
435                "browser workspace already has a connected session".into(),
436            ));
437        }
438        let policy = BrowserPolicy::from_preset(self.policy_preset, &self.root)
439            .map_err(|error| DevelopmentError::Process(error.to_string()))?;
440        let mut builder = SessionOptions::builder()
441            .port(config.port)
442            .attach(config.attach)
443            .incognito(config.incognito)
444            .headed(config.headed)
445            .profile(config.profile.clone())
446            .policy(policy);
447        if let Some(path) = config.chrome_path.clone() {
448            builder = builder.chrome_path(path);
449        }
450        let options = builder
451            .build()
452            .map_err(|error| DevelopmentError::InvalidInput(error.to_string()))?;
453        let session = BrowserSession::start(&options)
454            .await
455            .map_err(|error| DevelopmentError::Process(error.to_string()))?;
456        self.revision = Some(1);
457        self.session = Some(session);
458        self.last_config = Some(config);
459        serde_json::to_value(self.state()).map_err(Into::into)
460    }
461
462    async fn execute(&mut self, command: BrowserCommand) -> DevelopmentResult<Value> {
463        self.apply_remote_inputs().await?;
464        match command {
465            BrowserCommand::Start(config) => self.start_session(config).await,
466            BrowserCommand::Reconnect => {
467                let config = self.last_config.clone().ok_or_else(|| {
468                    DevelopmentError::Conflict(
469                        "browser has no prior connection configuration to reconnect".into(),
470                    )
471                })?;
472                self.shutdown().await;
473                self.start_session(config).await
474            }
475            BrowserCommand::Stop => {
476                self.shutdown().await;
477                serde_json::to_value(self.state()).map_err(Into::into)
478            }
479            BrowserCommand::State => serde_json::to_value(self.state()).map_err(Into::into),
480            BrowserCommand::Observe => {
481                let context = self
482                    .session()?
483                    .observe_fresh()
484                    .await
485                    .map_err(browser_error)?;
486                self.revision = Some(context.consistency.end_revision);
487                serde_json::to_value(context).map_err(Into::into)
488            }
489            BrowserCommand::Snapshot => {
490                let snapshot = self.session()?.snapshot().await.map_err(browser_error)?;
491                serde_json::to_value(snapshot).map_err(Into::into)
492            }
493            BrowserCommand::Semantic(level) => {
494                let observation = self
495                    .session()?
496                    .semantic_observe(level)
497                    .await
498                    .map_err(browser_error)?;
499                serde_json::to_value(observation).map_err(Into::into)
500            }
501            BrowserCommand::WebIr => {
502                let ir = self
503                    .session()?
504                    .extract_web_ir(&ExtractionRequest::default_document())
505                    .await
506                    .map_err(browser_error)?;
507                self.revision = Some(ir.revision);
508                serde_json::to_value(WebIrInspectionResult::from_ir(&ir)).map_err(Into::into)
509            }
510            BrowserCommand::Diff => {
511                let delta = self
512                    .session()?
513                    .observe_delta()
514                    .await
515                    .map_err(browser_error)?;
516                self.revision = Some(delta.to_revision);
517                serde_json::to_value(delta).map_err(Into::into)
518            }
519            BrowserCommand::Targets => {
520                let targets = self
521                    .session()?
522                    .list_targets()
523                    .await
524                    .map_err(browser_error)?;
525                serde_json::to_value(targets).map_err(Into::into)
526            }
527            BrowserCommand::SelectTarget(target) => {
528                let selected = self
529                    .session()?
530                    .select_target(&target)
531                    .await
532                    .map_err(browser_error)?;
533                let observation = self
534                    .session()?
535                    .observe_fresh()
536                    .await
537                    .map_err(browser_error)?;
538                self.revision = Some(observation.consistency.end_revision);
539                Ok(serde_json::json!({"target":selected,"observation":observation}))
540            }
541            BrowserCommand::Navigate {
542                url,
543                expected_revision,
544                timeout,
545            } => {
546                let outcome = self
547                    .session()?
548                    .navigate_with_revision(&url, timeout, expected_revision)
549                    .await
550                    .map_err(browser_error)?;
551                let value = serde_json::to_value(outcome)?;
552                self.revision = value.get("currentRevision").and_then(Value::as_u64);
553                Ok(value)
554            }
555            BrowserCommand::Back(expected_revision) => {
556                let outcome = self
557                    .session()?
558                    .go_back_with_revision(expected_revision)
559                    .await
560                    .map_err(browser_error)?;
561                self.revision = Some(outcome.current_revision);
562                serde_json::to_value(outcome).map_err(Into::into)
563            }
564            BrowserCommand::Forward(expected_revision) => {
565                let outcome = self
566                    .session()?
567                    .go_forward_with_revision(expected_revision)
568                    .await
569                    .map_err(browser_error)?;
570                self.revision = Some(outcome.current_revision);
571                serde_json::to_value(outcome).map_err(Into::into)
572            }
573            BrowserCommand::Reload(expected_revision) => {
574                let outcome = self
575                    .session()?
576                    .reload_with_revision(expected_revision)
577                    .await
578                    .map_err(browser_error)?;
579                self.revision = Some(outcome.current_revision);
580                serde_json::to_value(outcome).map_err(Into::into)
581            }
582            BrowserCommand::StopLoading(expected_revision) => {
583                let outcome = self
584                    .session()?
585                    .stop_loading_with_revision(expected_revision)
586                    .await
587                    .map_err(browser_error)?;
588                self.revision = Some(outcome.current_revision);
589                serde_json::to_value(outcome).map_err(Into::into)
590            }
591            BrowserCommand::Highlight {
592                target,
593                expected_revision,
594            } => {
595                self.session()?
596                    .highlight_target_with_revision(&target, expected_revision)
597                    .await
598                    .map_err(browser_error)?;
599                Ok(serde_json::json!({"highlighted":target,"browserRevision":expected_revision}))
600            }
601            BrowserCommand::Click {
602                target,
603                expected_revision,
604            } => {
605                let outcome = self
606                    .session()?
607                    .click_with_revision(&target, expected_revision)
608                    .await
609                    .map_err(browser_error)?;
610                self.revision = Some(outcome.current_revision);
611                serde_json::to_value(outcome).map_err(Into::into)
612            }
613            BrowserCommand::Type {
614                text,
615                target,
616                expected_revision,
617            } => {
618                let outcome = self
619                    .session()?
620                    .type_text_with_expected_revision(
621                        &text,
622                        target.as_deref(),
623                        Some(expected_revision),
624                    )
625                    .await
626                    .map_err(browser_error)?;
627                self.revision = Some(outcome.current_revision);
628                serde_json::to_value(outcome).map_err(Into::into)
629            }
630            BrowserCommand::Scroll {
631                dx,
632                dy,
633                expected_revision,
634            } => {
635                let outcome = self
636                    .session()?
637                    .scroll_with_revision(dx, dy, Some(expected_revision))
638                    .await
639                    .map_err(browser_error)?;
640                self.revision = Some(outcome.current_revision);
641                serde_json::to_value(outcome).map_err(Into::into)
642            }
643            BrowserCommand::Screenshot => {
644                let png = self
645                    .session()?
646                    .screenshot_png()
647                    .await
648                    .map_err(browser_error)?;
649                Ok(serde_json::json!({
650                    "mimeType":"image/png",
651                    "bytes":png.len(),
652                    "base64":base64::Engine::encode(&base64::engine::general_purpose::STANDARD, png)
653                }))
654            }
655            BrowserCommand::RunWorkflow { definition, inputs } => {
656                let workflow = WorkflowDefinition::from_value(definition)
657                    .map_err(|error| DevelopmentError::InvalidInput(error.to_string()))?;
658                self.workflow_state = "running".into();
659                self.active_workflow = Some(workflow.name.clone());
660                let result = self.session()?.run_workflow(&workflow, &inputs).await;
661                self.workflow_state = if result.is_ok() {
662                    "completed"
663                } else {
664                    "failed"
665                }
666                .into();
667                let result = result.map_err(browser_error)?;
668                self.revision = Some(result.final_revision);
669                self.last_workflow = Some((workflow, result.clone()));
670                serde_json::to_value(result).map_err(Into::into)
671            }
672            BrowserCommand::PauseWorkflow => {
673                let (workflow, result) = self.last_workflow.as_ref().ok_or_else(|| {
674                    DevelopmentError::Conflict(
675                        "no workflow result is available to checkpoint".into(),
676                    )
677                })?;
678                let checkpoint = self
679                    .session()?
680                    .export_workflow_checkpoint(workflow, result)
681                    .await
682                    .map_err(browser_error)?;
683                self.workflow_state = "paused".into();
684                serde_json::to_value(checkpoint).map_err(Into::into)
685            }
686            BrowserCommand::ResumeWorkflow {
687                definition,
688                inputs,
689                checkpoint,
690            } => {
691                let workflow = WorkflowDefinition::from_value(definition)
692                    .map_err(|error| DevelopmentError::InvalidInput(error.to_string()))?;
693                let checkpoint: WorkflowCheckpoint = serde_json::from_value(checkpoint)?;
694                self.workflow_state = "running".into();
695                self.active_workflow = Some(workflow.name.clone());
696                let result = self
697                    .session()?
698                    .resume_workflow(&workflow, &inputs, &checkpoint)
699                    .await;
700                self.workflow_state = if result.is_ok() {
701                    "completed"
702                } else {
703                    "failed"
704                }
705                .into();
706                let result = result.map_err(browser_error)?;
707                self.revision = Some(result.final_revision);
708                self.last_workflow = Some((workflow, result.clone()));
709                serde_json::to_value(result).map_err(Into::into)
710            }
711            BrowserCommand::ListWorkflows => Ok(serde_json::json!({
712                "state":self.workflow_state,
713                "active":self.active_workflow,
714                "last":self.last_workflow.as_ref().map(|(definition, result)| serde_json::json!({
715                    "name":definition.name,
716                    "version":definition.workflow_version,
717                    "result":result
718                }))
719            })),
720            BrowserCommand::CancelWorkflow => {
721                if self.workflow_state == "running" {
722                    return Err(DevelopmentError::Conflict(
723                        "workflow cancellation cannot preempt an in-flight synchronous browser command"
724                            .into(),
725                    ));
726                }
727                let previous = self.workflow_state.clone();
728                self.workflow_state = "cancelled".into();
729                self.active_workflow = None;
730                Ok(serde_json::json!({"cancelled":true,"previousState":previous}))
731            }
732            BrowserCommand::VerifyWorkflow => {
733                let (definition, result) = self.last_workflow.as_ref().ok_or_else(|| {
734                    DevelopmentError::Conflict("no workflow result is available to verify".into())
735                })?;
736                Ok(serde_json::json!({
737                    "verified":self.workflow_state == "completed",
738                    "name":definition.name,
739                    "version":definition.workflow_version,
740                    "finalRevision":result.final_revision,
741                    "result":result
742                }))
743            }
744            BrowserCommand::RemoteViewOpen => {
745                if self.remote_view.is_some() {
746                    return Err(DevelopmentError::Conflict("Remote View is already open".into()));
747                }
748                self.session()?;
749                let view = RemoteView::bind().await?;
750                let response = serde_json::json!({
751                    "active":true,
752                    "localUrl":view.local_url(),
753                    "sshForwardHint":view.ssh_forward_hint(),
754                    "loopbackOnly":true,
755                });
756                self.remote_view = Some(view);
757                self.publish_remote_frame().await?;
758                Ok(response)
759            }
760            BrowserCommand::RemoteViewStatus => Ok(self.remote_view.as_ref().map_or_else(
761                || serde_json::json!({"active":false,"loopbackOnly":true}),
762                |view| serde_json::json!({"active":true,"localUrl":view.local_url(),"sshForwardHint":view.ssh_forward_hint(),"loopbackOnly":true}),
763            )),
764            BrowserCommand::RemoteViewRevoke => {
765                if let Some(view) = self.remote_view.take() {
766                    view.revoke().await;
767                    Ok(serde_json::json!({"revoked":true}))
768                } else {
769                    Ok(serde_json::json!({"revoked":false}))
770                }
771            }
772        }
773    }
774
775    async fn publish_remote_frame(&self) -> DevelopmentResult<()> {
776        let (Some(view), Some(session), Some(revision)) = (
777            self.remote_view.as_ref(),
778            self.session.as_ref(),
779            self.revision,
780        ) else {
781            return Ok(());
782        };
783        let png = session.screenshot_png().await.map_err(browser_error)?;
784        let published = view.publish(RemoteFrame {
785            browser_revision: revision,
786            mime_type: "image/png".into(),
787            data: base64::Engine::encode(&base64::engine::general_purpose::STANDARD, png),
788        });
789        if !published {
790            return Err(DevelopmentError::Process(
791                "Remote View rejected the bounded frame".into(),
792            ));
793        }
794        Ok(())
795    }
796
797    async fn apply_remote_inputs(&mut self) -> DevelopmentResult<()> {
798        let mut inputs = Vec::new();
799        if let Some(view) = self.remote_view.as_mut() {
800            while let Ok(input) = view.try_recv_input() {
801                inputs.push(input);
802                if inputs.len() == 64 {
803                    break;
804                }
805            }
806        }
807        for input in inputs {
808            let session = self.session()?;
809            let revision = input.expected_revision();
810            let current_revision = match input {
811                RemoteInput::Click { x, y, .. } => {
812                    let (width, height) = session.viewport_size().await.map_err(browser_error)?;
813                    session
814                        .click_at_with_revision(x * width, y * height, Some(revision))
815                        .await
816                        .map_err(browser_error)?
817                        .revision
818                }
819                RemoteInput::Scroll { dx, dy, .. } => {
820                    session
821                        .scroll_with_revision(dx, dy, Some(revision))
822                        .await
823                        .map_err(browser_error)?
824                        .current_revision
825                }
826                RemoteInput::Key { key, .. } => {
827                    session
828                        .key_press_with_revision(&key, Some(revision))
829                        .await
830                        .map_err(browser_error)?
831                        .current_revision
832                }
833                RemoteInput::Text { text, .. } => {
834                    session
835                        .type_text_with_expected_revision(&text, None, Some(revision))
836                        .await
837                        .map_err(browser_error)?
838                        .current_revision
839                }
840            };
841            self.revision = Some(current_revision);
842        }
843        if self.remote_view.is_some() {
844            self.publish_remote_frame().await?;
845        }
846        Ok(())
847    }
848}
849
850fn browser_error(error: Box<dyn std::error::Error>) -> DevelopmentError {
851    DevelopmentError::Process(error.to_string())
852}
853
854#[cfg(test)]
855mod tests {
856    use super::*;
857    use std::io::{Read, Write};
858    use std::net::{TcpListener, TcpStream};
859    use std::sync::Arc;
860    use std::sync::atomic::{AtomicBool, Ordering};
861
862    #[test]
863    fn disconnected_service_reports_authoritative_state() {
864        let service = BrowserService::new(std::env::temp_dir()).unwrap();
865        let state = service.state().unwrap();
866        assert_eq!(state["connected"], false);
867        assert_eq!(state["workflowState"], "idle");
868        let error = service.observe().unwrap_err();
869        assert!(error.to_string().contains("glass.browser.start"));
870        assert_eq!(service.remote_view_status().unwrap()["active"], false);
871        let web_ir_error = service.web_ir().unwrap_err();
872        assert!(web_ir_error.to_string().contains("glass.browser.start"));
873        assert!(
874            service
875                .open_remote_view()
876                .unwrap_err()
877                .to_string()
878                .contains("browser")
879        );
880        assert_eq!(service.revoke_remote_view().unwrap()["revoked"], false);
881    }
882
883    #[test]
884    fn explicit_browser_policy_is_exposed_before_startup() {
885        let service =
886            BrowserService::new_with_policy(std::env::temp_dir(), PolicyPreset::Hardened).unwrap();
887        let state = service.state().unwrap();
888        assert_eq!(state["policyPreset"], "hardened");
889        assert_eq!(state["connected"], false);
890    }
891
892    #[test]
893    fn resident_browser_executes_revision_safe_fixture_flow() {
894        if std::env::var("GLASS_E2E").as_deref() != Ok("1") {
895            return;
896        }
897        let chrome_path =
898            std::env::var("GLASS_CHROME_PATH").expect("GLASS_E2E=1 requires GLASS_CHROME_PATH");
899        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
900        listener.set_nonblocking(true).unwrap();
901        let address = listener.local_addr().unwrap();
902        let running = Arc::new(AtomicBool::new(true));
903        let server_running = Arc::clone(&running);
904        let server = std::thread::spawn(move || {
905            let html = br#"<!doctype html><title>Resident Glass</title><label>Name<input id="name"></label><button id="save" onclick="document.querySelector('p').textContent='Saved '+document.querySelector('#name').value">Save</button><p></p>"#;
906            while server_running.load(Ordering::Relaxed) {
907                match listener.accept() {
908                    Ok((mut stream, _)) => {
909                        let mut request = [0; 4096];
910                        let _ = stream.read(&mut request);
911                        let header = format!(
912                            "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
913                            html.len()
914                        );
915                        let _ = stream.write_all(header.as_bytes());
916                        let _ = stream.write_all(html);
917                    }
918                    Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
919                        std::thread::sleep(Duration::from_millis(5));
920                    }
921                    Err(_) => break,
922                }
923            }
924        });
925        let port_probe = TcpListener::bind("127.0.0.1:0").unwrap();
926        let browser_port = port_probe.local_addr().unwrap().port();
927        drop(port_probe);
928
929        let service = BrowserService::new(std::env::temp_dir()).unwrap();
930        let started = service
931            .start(BrowserStartConfig {
932                port: browser_port,
933                chrome_path: Some(chrome_path.into()),
934                ..BrowserStartConfig::default()
935            })
936            .unwrap();
937        let browser_pid = started["browserProcessId"].as_u64().unwrap() as u32;
938        let initial = service.observe().unwrap();
939        let initial_revision = initial["consistency"]["end_revision"]
940            .as_u64()
941            .or_else(|| initial["consistency"]["endRevision"].as_u64())
942            .unwrap();
943        service
944            .navigate(
945                format!("http://{address}/fixture.html"),
946                initial_revision,
947                Duration::from_secs(30),
948            )
949            .unwrap();
950        assert!(
951            service
952                .navigate(
953                    format!("http://{address}/stale"),
954                    initial_revision,
955                    Duration::from_secs(30),
956                )
957                .unwrap_err()
958                .to_string()
959                .contains("revision")
960        );
961        let observed = service.observe().unwrap();
962        assert_eq!(observed["page"]["title"], "Resident Glass");
963        assert!(
964            service
965                .snapshot()
966                .unwrap()
967                .as_object()
968                .is_some_and(|snapshot| !snapshot.is_empty())
969        );
970        assert_eq!(
971            service
972                .semantic(SemanticObservationLevel::Structured)
973                .unwrap()["page"]["title"],
974            "Resident Glass"
975        );
976        let web_ir = service.web_ir().unwrap();
977        assert!(web_ir["revision"].as_u64().is_some());
978        assert!(web_ir["entityCount"].as_u64().unwrap_or_default() > 0);
979        assert!(web_ir["actionableEntities"].is_array());
980        assert!(service.diff().unwrap()["toRevision"].as_u64().is_some());
981        let revision = observed["consistency"]["end_revision"]
982            .as_u64()
983            .or_else(|| observed["consistency"]["endRevision"].as_u64())
984            .unwrap();
985        let typed = service
986            .type_text("Ada".into(), Some("Name".into()), revision)
987            .unwrap();
988        let revision = typed["currentRevision"].as_u64().unwrap();
989        service.click("Save".into(), revision).unwrap();
990        assert!(
991            service.observe().unwrap()["text"]
992                .as_str()
993                .unwrap()
994                .contains("Saved Ada")
995        );
996        let remote = service.open_remote_view().unwrap();
997        assert_eq!(remote["active"], true);
998        assert!(
999            remote["localUrl"]
1000                .as_str()
1001                .unwrap()
1002                .starts_with("http://127.0.0.1:")
1003        );
1004        assert_eq!(service.remote_view_status().unwrap()["active"], true);
1005        assert_eq!(service.revoke_remote_view().unwrap()["revoked"], true);
1006        let observed = service.observe().unwrap();
1007        let revision = observed["consistency"]["end_revision"]
1008            .as_u64()
1009            .or_else(|| observed["consistency"]["endRevision"].as_u64())
1010            .unwrap();
1011        assert_eq!(service.reload(revision).unwrap()["action"], "reload");
1012        service.stop().unwrap();
1013        #[cfg(unix)]
1014        assert!(unsafe { libc::kill(browser_pid as i32, 0) } == -1);
1015        let port_closed = (0..100).any(|_| {
1016            if TcpStream::connect(("127.0.0.1", browser_port)).is_err() {
1017                true
1018            } else {
1019                std::thread::sleep(Duration::from_millis(10));
1020                false
1021            }
1022        });
1023        assert!(port_closed, "owned browser endpoint survived resident stop");
1024        running.store(false, Ordering::Relaxed);
1025        server.join().unwrap();
1026    }
1027}