---
title: "Optional XGeoRTR Bridge"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Optional XGeoRTR Bridge}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
if (file.exists("../DESCRIPTION") && requireNamespace("pkgload", quietly = TRUE)) {
  pkgload::load_all("..", export_all = FALSE, helpers = FALSE, quiet = TRUE)
} else {
  library(ggWebGL)
}
build_optional_bridges <- identical(
  tolower(Sys.getenv("GGWEBGL_BUILD_OPTIONAL_BRIDGES", "false")),
  "true"
)
bridge_candidates <- c(
  "inst/examples/htmlwidget/xgeortr-bridge-gallery.R",
  file.path("..", "inst", "examples", "htmlwidget", "xgeortr-bridge-gallery.R"),
  system.file("examples", "htmlwidget", "xgeortr-bridge-gallery.R", package = "ggWebGL")
)
bridge_candidates <- bridge_candidates[nzchar(bridge_candidates) & file.exists(bridge_candidates)]

bridge_env <- new.env(parent = globalenv())
bridge_path <- if (length(bridge_candidates)) bridge_candidates[[1L]] else NA_character_
if (build_optional_bridges && !is.na(bridge_path)) {
  sys.source(bridge_path, envir = bridge_env)
}

bridge_available <- build_optional_bridges &&
  !is.na(bridge_path) &&
  exists("xgeortr_bridge_available", envir = bridge_env, inherits = FALSE) &&
  isTRUE(bridge_env$xgeortr_bridge_available())

bridge_widgets <- if (bridge_available) {
  bridge_env$ggwebgl_xgeortr_bridge_widgets(height = 520)
} else {
  NULL
}
```

# Boundary

This vignette demonstrates an optional downstream bridge from `XGeoRTR` into
`ggWebGL`.

The ownership split stays fixed:

- `XGeoRTR` owns `xgeo_state`, embeddings, and explainable-geometry semantics
- the bridge example resolves that backend state into renderer-ready payloads
- `ggWebGL` owns widget construction, shaders, panel layout, hover, pan, and zoom

No `XGeoRTR` code is modified here. The bridge lives entirely inside the
`ggWebGL` example layer.

The representative and multiscale scenes show how optional XGeoRTR-style
renderer inputs can combine coloured explanation-state points with sparse
contribution-direction arrows. Those arrows are true
`ggwebgl_layer_vectors()` primitives rather than line segments plus decorative
anchors, so the vignette exercises the same renderer-owned vector path that
downstream packages can target.

# Optional Dependency

`XGeoRTR` is an optional development ecosystem package for `ggWebGL`, not a
CRAN dependency. Live bridge widgets are disabled during standard vignette
builds and can be enabled in development by setting
`GGWEBGL_BUILD_OPTIONAL_BRIDGES=true` before rendering this article. When the
bridge is disabled or `XGeoRTR` is unavailable, the package still builds and
this vignette degrades to documentation-only mode.

```{r}
if (!build_optional_bridges) {
  cat("Optional XGeoRTR live bridge widgets are disabled for this vignette build.\n")
} else if (!bridge_available) {
  cat("XGeoRTR is unavailable, so the live bridge widgets are skipped in this vignette.\n")
} else {
  cat("XGeoRTR bridge widgets are available.\n")
}
```

# Representative Scene

This scene demonstrates class-coloured explanation points with sparse vector
arrows summarising local contribution direction.

```{r}
if (!bridge_available) {
  cat("Representative widget skipped.\n")
} else {
  bridge_widgets$representative
}
```

# Multiscale Scene

This two-panel view keeps the same vector grammar while contrasting the global
embedding with a local explanation panel whose viewport is the exact
data-coordinate zoom of the rectangle marked in the global panel.

```{r}
if (!bridge_available) {
  cat("Multiscale widget skipped.\n")
} else {
  bridge_widgets$multiscale
}
```

# Attribution Scene

```{r}
if (!bridge_available) {
  cat("Attribution widget skipped.\n")
} else {
  bridge_widgets$attribution
}
```

# Structure Scene

```{r}
if (!bridge_available) {
  cat("Structure widget skipped.\n")
} else {
  bridge_widgets$structure
}
```

# Regeneration

The example source for these widgets lives at:

```{r eval = FALSE}
source(system.file("examples", "htmlwidget", "xgeortr-bridge-gallery.R", package = "ggWebGL"))
```