Update the README with new features

Author: coatless

README.Rmd

@@ -126,20 +126,57 @@ package documentation more engaging and allows users to experiment with examples
 without installing R locally.
 
 For this to work with developmental versions of your package, you will need to
+either have an account with [r-universe.dev](https://r-universe.dev/) or
 use the following `pkgdown` + `rwasm` build action:
 
 <https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml>
 
 For a fast setup, please use:
 
 ```r
-usethis::use_github_action("https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml")
+usethis::use_github_action(repos = "https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml")
 ```
 
 > [!IMPORTANT]
 >
 > Please make sure to delete your old `pkgdown.yml` file.
 
+## Requirements
+
+For `@examplesWebR` functionality, your package's `DESCRIPTION` file must
+have:
+
+```
+Suggests:
+  rocleteer
+Remotes: coatless-rpkg/rocleteer
+
+Roxygen: list(..., packages = c("rocleteer"))
+
+Config/rocleteer/webr-repo: https://user.github.io/pkgname/
+```
+
+For the package to be usable in webR examples, you must 
+specify a webR-compatible repository in your `DESCRIPTION` file. This
+repository can be generated by [`r-universe`](https://r-universe.dev/) or
+by using the above GitHub Action to build and serve a webR R binary alongside
+your pkgdown site.
+
+By default, the `@examplesWebR` tag will look for the following: 
+
+- `Config/rocleteer/webr-repo: https://user.r-universe.dev/` (recommended)
+- `Config/rocleteer/webr-repo: https://user.github.io/pkgname/`
+- `URL` field containing GitHub Pages or R-universe patterns (shown above)
+
+If none of these are found, the tag will produce a warning during processing
+and will not generate the webR section in the Rd file.
+
+#### WebR Version Support
+
+Only webR versions v0.5.4 and higher are supported. 
+The tag will validate the version parameter and produce an error if an 
+unsupported version is specified.
+
 #### Generated Structure
 
 When you use `@examplesWebR`, it generates:
@@ -165,7 +202,8 @@ it generates:
 \section{WebR}{
  \ifelse{html}{
    \out{
-     <a href="webR_URL">\U0001F310 View in webR REPL</a>
+     <button>\U0001F310 Try it in your browser!</button>
+     <iframe href="webR_URL"></iframe>
    }
  }{
    \ifelse{latex}{
@@ -188,22 +226,23 @@ plot(x, y, type = "b", main = "Interactive Example")
 This creates:
 
 - Regular examples with your R code
-- A "WebR" section with a "View in webR REPL" button in HTML documentation
-  or a URL in LaTeX documentation.
-- The button opens the code in an interactive webR session
+- A "WebR" section with a "Try it in your browser" and "Open in Tab" buttons
+  in HTML documentation or a URL in LaTeX documentation.
+- The button opens either an embedded webR session or 
+  a new tab with the code in an interactive webR REPL.
 
 > [!NOTE]
 >
 > The `@examplesWebR` tag uses a simplified encoding scheme compatible with webR.
 
-#### Embedded Mode
+#### Standalone Mode
 
-For a more integrated experience, embed the webR REPL directly into the Rd
-file with:
+To avoid embedding the webR REPL, you can use the `@examplesWebR embed=false` tag.
+This will generate a link to the webR REPL without embedding it directly in the documentation.
 
 ```r
 #' @examplesWebR embed
-#' # This code will be available in an embedded webR session
+#' # This code will be available in a new web browser tab with the webR REPL
 #' library(ggplot2)
 #' ggplot(mtcars, aes(mpg, wt)) + 
 #'   geom_point() + 
@@ -214,15 +253,18 @@ file with:
 
 You can customize the `@examplesWebR` tag with additional options:
 
-- `embed`: Embed an iframe instead of showing a link
-- `height=N`: Set iframe height in pixels (default: `300`)
+- `autorun`: Embed an iframe instead of showing a link  (default: `"false"`)
+- `embed`: Embed an iframe instead of showing a link  (default: `"true"`)
+- `height=N`: Set iframe height in pixels (default: `400`)
 - `version=X`: Specify webR version (default: `"latest"`)
+- `mode=X-Y`: Configure embedded webR interface (editor, plot, terminal, files) (default: `"editor-plot-terminal"`)
+- `channel=X`: Set webR communication channel (default: `"Automatic`)
 
 For example, to embed with a specific height and version:
 
 ```r
-#' @examplesWebR embed height=500 version=v0.3.3
-#' # Custom height iframe with specific webR version
+#' @examplesWebR autorun height=500 version=v0.5.4
+#' # Custom height iframe with specific webR version that autoruns code
 #' summary(cars)
 #' plot(cars)
 ```

README.md

@@ -119,20 +119,58 @@ documentation more engaging and allows users to experiment with examples
 without installing R locally.
 
 For this to work with developmental versions of your package, you will
-need to use the following `pkgdown` + `rwasm` build action:
+need to either have an account with
+[r-universe.dev](https://r-universe.dev/) or use the following
+`pkgdown` + `rwasm` build action:
 
 <https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml>
 
 For a fast setup, please use:
 
 ``` r
-usethis::use_github_action("https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml")
+usethis::use_github_action(repos = "https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml")
 ```
 
 > \[!IMPORTANT\]
 >
 > Please make sure to delete your old `pkgdown.yml` file.
 
+## Requirements
+
+For `@examplesWebR` functionality, your package’s `DESCRIPTION` file
+must have:
+
+    Suggests:
+      rocleteer
+    Remotes: coatless-rpkg/rocleteer
+
+    Roxygen: list(..., packages = c("rocleteer"))
+
+    Config/rocleteer/webr-repo: https://user.github.io/pkgname/
+
+For the package to be usable in webR examples, you must specify a
+webR-compatible repository in your `DESCRIPTION` file. This repository
+can be generated by [`r-universe`](https://r-universe.dev/) or by using
+the above GitHub Action to build and serve a webR R binary alongside
+your pkgdown site.
+
+By default, the `@examplesWebR` tag will look for the following:
+
+- `Config/rocleteer/webr-repo: https://user.r-universe.dev/`
+  (recommended)
+- `Config/rocleteer/webr-repo: https://user.github.io/pkgname/`
+- `URL` field containing GitHub Pages or R-universe patterns (shown
+  above)
+
+If none of these are found, the tag will produce a warning during
+processing and will not generate the webR section in the Rd file.
+
+#### WebR Version Support
+
+Only webR versions v0.5.4 and higher are supported. The tag will
+validate the version parameter and produce an error if an unsupported
+version is specified.
+
 #### Generated Structure
 
 When you use `@examplesWebR`, it generates:
@@ -158,7 +196,8 @@ it generates:
 \section{WebR}{
  \ifelse{html}{
    \out{
-     <a href="webR_URL">\U0001F310 View in webR REPL</a>
+     <button>\U0001F310 Try it in your browser!</button>
+     <iframe href="webR_URL"></iframe>
    }
  }{
    \ifelse{latex}{
@@ -181,23 +220,25 @@ plot(x, y, type = "b", main = "Interactive Example")
 This creates:
 
 - Regular examples with your R code
-- A “WebR” section with a “View in webR REPL” button in HTML
-  documentation or a URL in LaTeX documentation.
-- The button opens the code in an interactive webR session
+- A “WebR” section with a “Try it in your browser” and “Open in Tab”
+  buttons in HTML documentation or a URL in LaTeX documentation.
+- The button opens either an embedded webR session or a new tab with the
+  code in an interactive webR REPL.
 
 > \[!NOTE\]
 >
 > The `@examplesWebR` tag uses a simplified encoding scheme compatible
 > with webR.
 
-#### Embedded Mode
+#### Standalone Mode
 
-For a more integrated experience, embed the webR REPL directly into the
-Rd file with:
+To avoid embedding the webR REPL, you can use the
+`@examplesWebR embed=false` tag. This will generate a link to the webR
+REPL without embedding it directly in the documentation.
 
 ``` r
 #' @examplesWebR embed
-#' # This code will be available in an embedded webR session
+#' # This code will be available in a new web browser tab with the webR REPL
 #' library(ggplot2)
 #' ggplot(mtcars, aes(mpg, wt)) + 
 #'   geom_point() + 
@@ -208,15 +249,20 @@ Rd file with:
 
 You can customize the `@examplesWebR` tag with additional options:
 
-- `embed`: Embed an iframe instead of showing a link
-- `height=N`: Set iframe height in pixels (default: `300`)
+- `autorun`: Embed an iframe instead of showing a link (default:
+  `"false"`)
+- `embed`: Embed an iframe instead of showing a link (default: `"true"`)
+- `height=N`: Set iframe height in pixels (default: `400`)
 - `version=X`: Specify webR version (default: `"latest"`)
+- `mode=X-Y`: Configure embedded webR interface (editor, plot, terminal,
+  files) (default: `"editor-plot-terminal"`)
+- `channel=X`: Set webR communication channel (default: `"Automatic`)
 
 For example, to embed with a specific height and version:
 
 ``` r
-#' @examplesWebR embed height=500 version=v0.3.3
-#' # Custom height iframe with specific webR version
+#' @examplesWebR autorun height=500 version=v0.5.4
+#' # Custom height iframe with specific webR version that autoruns code
 #' summary(cars)
 #' plot(cars)
 ```