Add startApp() for non-blocking app execution (#4349)

* Non-blocking concept

* Update unrelated tabPanel test snapshot

* Review user interface

* Review internal methods

* Tighten later loop for performance

* Silence tests

* Cleanup pass

* Rename internal function

* Use combined error message

* Consolidate two on.exit() clauses

* Fix cleanup step and add regression test

* Add documentation about running the later loop

* Default to non-blocking for LLMs

* Auto-stop upon new `runApp()`

* Update news and docs

* Refactor pass

* Make `handle$stop()` idempotent

* Simplify `serviceAsync()`

* Minimize changes to `on.exit()` handlers

* Move cleanup func creation

* Consistent cleanup order

* Apply review changes from @cpsievert and @schloerke

* Make non-default for LLMs

* `devtools::document()` (GitHub Actions)

* Update news

* Use generation invalidation for loops

* Move generation increment before the blocking/non-blocking branch

* Have `handle$stop()` method handle setting of `stopped` flag

* Amend currently running message

* Apply suggestions from code review

Co-authored-by: Carson Sievert <cpsievert1@gmail.com>

* Separate out non-blocking into `startApp()`

* Amend `stopApp()` docs

* Add `startApp()` to pkgdown.yml

* Fix stale variable name in test comment

* Move option resolution into `.setupShinyApp()`

Aligns `startApp()` with `runApp()` by setting `options(warn,
pool.scheduler)` before `as.shiny.appobj()` and passing `ops` through.
Folds the `findVal` precedence block into `.setupShinyApp()`; missingness
is checked in the caller's frame via a `caller = parent.frame()` default
arg, since `runApp()`/`startApp()` formals carry defaults.

* Scope OTEL promise domain to `startApp()` setup and service loop

`local_otel_promise_domain()` binds the domain to the caller's frame,
which in `startApp()` exits before any request is served. A persistent
global install would leak into unrelated user promises between ticks.

Wrap the synchronous setup phase and each service iteration in
`with_otel_promise_domain()`. Callbacks are wrapped at registration
time, so promises created during `onStart`, handlers, and observers
stay instrumented when they fire. The domain is dormant between ticks,
so it stays out of user promises at the console.

* fix(startApp): preserve stopApp() called during setup

* docs(startApp): clarify relationship to stopApp()

* `devtools::document()` (GitHub Actions)

* perf(startApp): replace 1ms polling with adaptive serviceApp(NA) scheduling

* `usethis::use_tidy_description()` (GitHub Actions)

* fix(startApp): error on nested launch from app code

* Add comment about finalizer reachability

* Add note in docs about auto-replacement

* Update news

---------

Co-authored-by: shikokuchuo <shikokuchuo@users.noreply.github.com>
Co-authored-by: Carson Sievert <cpsievert1@gmail.com>

Author: shikokuchuo

DESCRIPTION

@@ -127,6 +127,7 @@ Config/testthat/edition: 3
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 Collate:
+    'app-handle.R'
     'globals.R'
     'app-state.R'
     'app_template.R'

NAMESPACE

@@ -276,6 +276,7 @@ export(snapshotPreprocessInput)
 export(snapshotPreprocessOutput)
 export(span)
 export(splitLayout)
+export(startApp)
 export(stopApp)
 export(strong)
 export(submitButton)

NEWS.md

@@ -2,6 +2,11 @@
 
 ## New features
 
+* New `startApp()` runs a Shiny app in non-blocking mode, returning a
+  `ShinyAppHandle` object with `stop()`, `status()`, `url()`, and `result()`
+  methods. When a new app is started, any previously running non-blocking app
+  is automatically stopped. (#4349)
+
 * `downloadButton()` and `downloadLink()` gain a new `enabled` parameter. The default value, `"auto"`, automatically enables the button/link when the download is ready. To opt-into manual state management (e.g., `shinyjs::enable()`), set `enabled` to `FALSE` (or `TRUE`). (#4119)
 
 ## Improvements

R/app-handle.R

@@ -0,0 +1,76 @@
+# Handle returned by startApp()
+ShinyAppHandle <- R6::R6Class("ShinyAppHandle",
+  cloneable = FALSE,
+
+  public = list(
+    initialize = function(appUrl, cleanupFn) {
+      private$appUrl <- appUrl
+      private$cleanupFn <- cleanupFn
+
+      # Does NOT fire while the app is running: internal refs
+      # (.globals$runningHandle and the serviceLoop closure) keep the
+      # handle alive.
+      reg.finalizer(self, function(e) {
+        tryCatch(e$stop(), error = function(cnd) NULL)
+      }, onexit = TRUE)
+    },
+
+    stop = function() {
+      if (self$status() != "running") {
+        return(invisible(self))
+      }
+      private$stopped <- TRUE
+      private$captureResult()
+      private$cleanupFn()
+      private$cleanupFn <- NULL
+      invisible(self)
+    },
+
+    url = function() private$appUrl,
+
+    status = function() {
+      if (!private$stopped) {
+        "running"
+      } else if (!is.null(private$resultError)) {
+        "error"
+      } else {
+        "success"
+      }
+    },
+
+    result = function() {
+      if (self$status() == "running") {
+        stop("App is still running. Use status() to check if the app has stopped.")
+      }
+      if (!is.null(private$resultError)) {
+        stop(private$resultError)
+      }
+      private$resultValue
+    },
+
+    print = function(...) {
+      cat("Shiny app handle\n")
+      cat("  URL:   ", private$appUrl, "\n", sep = "")
+      cat("  Status:", self$status(), "\n")
+      invisible(self)
+    }
+  ),
+
+  private = list(
+    appUrl = NULL,
+    cleanupFn = NULL,
+    # Whether this handle has been stopped. Distinct from .globals$stopped
+    # which tracks whether a stop was requested (set by stopApp() or stop()).
+    stopped = FALSE,
+    resultValue = NULL,
+    resultError = NULL,
+
+    captureResult = function() {
+      if (isTRUE(.globals$reterror)) {
+        private$resultError <- .globals$retval
+      } else if (!is.null(.globals$retval)) {
+        private$resultValue <- .globals$retval$value
+      }
+    }
+  )
+)