Update sess/README.md and implement document_close on client

Author: randy3k

sess/README.md

@@ -40,23 +40,22 @@ The following methods are sent as notifications from R to the client:
 - **`plot_updated`**: Notifies that a new static plot is available. The client should request the `plot_latest` method via HTTP.
 - **`httpgd`**: Provides a URL for an `httpgd` live plot server (params: `url`).
 - **`help`**: Requests the client to display an R help page (params: `requestPath`).
-- **`browser`**: Requests the client to open a URL (params: `url`, `title`).
-- **`webview`**: Requests the client to open a local HTML file or URL in a webview (params: `file`, `title`).
+- **`browser`**: Requests the client to open a URL (params: `url`, `title`, `viewer`).
+- **`webview`**: Requests the client to open a local HTML file or URL in a webview (params: `file`, `title`, `viewer`).
 - **`restart_r`**: Requests the client to restart the R session (params: `command`, `clean`).
 - **`send_to_console`**: Sends code to the console for execution without blocking the R session (params: `code`, `execute`, `focus`, `animate`).
 
 #### 2. Synchronous Client Requests (`request_client`)
 
-The `request_client()` function allows R to call client-side functions synchronously by sending a **JSON-RPC Request** (with an `id`) over the WebSocket. This is primarily used to emulate the RStudio API:
+The `request_client()` function allows R to call client-side functions synchronously by sending a **JSON-RPC Request** (with an `id`) over the WebSocket. This is primarily used to emulate the RStudio API.
 
-1. R sends a request with `method` set to the action name (e.g., `"active_editor_context"`).
-2. R enters a `while` loop that calls `httpuv::service()`.
-3. The client processes the action and sends back a **JSON-RPC Response** (with the same id) via the WebSocket.
-4. R retrieves the `result` (or `error`) and returns it.
+**Coordinate Handling**: The `sess` protocol uses **1-indexed** coordinates for all rows (lines) and columns (characters) on the wire. This aligns with R's internal representation. The client (e.g., VS Code extension) is responsible for converting these to its internal 0-indexed representation if necessary.
 
-**Coordinate Handling**: The emulation layer automatically converts between R (1-indexed) and IPC (0-indexed) coordinates. Locations and ranges sent to the client are 0-indexed, while data received from the client (e.g., in `document_context`) is converted back to 1-indexed R objects.
+**Serialization Format**:
+- **Position**: A numeric array `[row, column]`.
+- **Range**: An object `{ "start": [row, column], "end": [row, column] }`.
 
-Below are all the JSON-RPC methods sent from R to the client to emulate RStudio API functionality:
+Below are the JSON-RPC methods sent from R to the client to emulate RStudio API functionality:
 
 - **`active_editor_context`**: Requests the current context of the active editor.
 - **`replace_text_in_current_selection`**: Replaces text in the current selection (params: `text`, `id`).
@@ -129,15 +128,21 @@ Returns the most recent static plot captured by the R session.
 
 ---
 
-## 3. Hook Registration
+## 3. Hook Registration & Options
 
 By default, the package does not inject hooks into the R session on load. Calling `sess::sess_app()` will start the server and automatically call `sess::register_hooks()` to enable features like automatic `View()` interception or plot redirection.
 
-If you need to manually register hooks without starting the full app environment (or re-register them if they were overridden), you can call:
-```r
-sess::register_hooks()
-```
-This rebinds internal functions (like `utils::View`) and sets `options()` for browsers, viewers, and devices to route through the IPC server.
+### Intercepted Functions
+- **`utils::View()`**: Redirects data to the client's data viewer. Supports `data.frame`, `matrix`, `list`, and `ArrowTabular` objects.
+- **`browser()`**, **`viewer()`**, **`page_viewer()`**: Redirects URLs and HTML files to the client's browser or webview.
+- **Help System**: Intercepts help topic printing to route HTML help to the client.
+
+### Global Options
+- **`sess.row_limit`**: Limits the number of rows sent to the data viewer (default: 100). Set to 0 for no limit.
+- **`sess.dataview`**: Target viewer column for data (default: `"Two"`).
+- **`sess.browser`**: Target viewer for browser (default: `"Active"`).
+- **`sess.webview`**: Target viewer for webview (default: `"Two"`).
+- **`sess.helpPanel`**: Target viewer for help (default: `"Two"`).
 
 ## 4. Comparison with Legacy IPC
 
@@ -153,37 +158,8 @@ The `sess` package replaces the legacy file-based IPC mechanism with a modern, i
 | **Transport Reliability**| OS-level File System Watchers | **WebSocket & HTTP streams** |
 | **Protocol Standard** | Ad-hoc JSON formats | **JSON-RPC 2.0** |
 
-### Detailed Mapping: Legacy to Modern
-
-**1. Command Dispatch (e.g., `View()`, `browser()`, `help()`)**
-- **Old Approach:** R intercepted commands and appended custom JSON structures to a `request.log` file, then updated the timestamp on a `request.lock` file. The client OS file watcher detected the `.lock` file change, read the `.log` file, and processed the pending commands.
-- **New Approach (`sess`):** R directly pushes an instantaneous **JSON-RPC Notification** (e.g., `method: "dataview"`, `method: "help"`) over the persistent WebSocket connection. The client receives and processes the payload instantly, bypassing disk I/O and file system watchers entirely.
-
-**2. Synchronous RStudio API Emulation**
-- **Old Approach:** R wrote a command to `request.log`, and then entered a blocking `while` loop aggressively polling for the creation of a `response.lock` file by the client.
-- **New Approach (`sess`):** R sends a **JSON-RPC Request** over the WebSocket with an `id`. It enters a `while` loop calling `httpuv::service()`, maintaining a responsive background state, and waits for a corresponding **JSON-RPC Response** with the matching `id` over the same WebSocket.
-
-**3. Workspace State (Global Environment)**
-- **Old Approach:** An R task callback ran after every top-level console execution, eagerly evaluating and serializing the entire Global Environment to a `workspace.json` file, followed by touching a `workspace.lock` file. The client watched for the lock file change to read the JSON file. This caused constant overhead and disk writes, even when the client's workspace pane was hidden.
-- **New Approach (`sess`):** Adopts a "Pull" architecture. The workspace is *only* evaluated and serialized when the client explicitly sends an **HTTP POST Request** to `/rpc` with `method: "workspace"`. This happens on-demand (e.g., when the UI pane is visible), saving significant R processing time and disk I/O.
-
-**4. Static Plots**
-- **Old Approach:** Plotting commands (via custom devices or hooks) generated a `plot.png` file on disk and updated a `plot.lock` file. The client watcher noticed the lock change, read the new PNG file from disk, and displayed it.
-- **New Approach (`sess`):** When a new plot is generated to a temporary file, R sends a lightweight **JSON-RPC Notification** (`method: "plot_updated"`) via the WebSocket. The client then pulls the actual image data by sending an **HTTP POST Request** to `/rpc` (`method: "plot_latest"`), which returns the base64-encoded image over the network stream.
-
-**5. Client Queries (Hover, Completion)**
-- **Old Approach:** R ran an internal `httpuv` server using custom JSON structures and ad-hoc request types (like `{ "type": "hover" }`).
-- **New Approach (`sess`):** Unified under the **JSON-RPC 2.0** standard. The client sends structured requests with strict `id` and `params` formatting to the single `/rpc` HTTP endpoint, receiving standardized JSON-RPC responses.
-
 ### Architectural Shifts
 
-1. **Elimination of File Watchers**: The legacy system relied heavily on OS-level file system watchers (`fs.watch`) monitoring lock files to trigger client updates. This approach could be unreliable or slow across different platforms, network drives, and remote container environments. `sess` replaces this entirely with persistent WebSocket connections for instantaneous, reliable event pushing.
-2. **On-Demand vs. Eager Evaluation**: Previously, R would eagerly evaluate and serialize the entire Global Environment to `workspace.json` frequently (e.g., via task callbacks), incurring significant continuous disk I/O and processing overhead. `sess` shifts this to a "Pull" model. The client requests the workspace state only when needed, significantly reducing R's background workload.
-3. **Unified Standard**: Instead of maintaining separate, disparate mechanisms for command logs, lock-file polling loops, JSON dumps, and custom HTTP query payloads, `sess` unifies all structured communication under the ubiquitous **JSON-RPC 2.0** standard across WebSocket and HTTP transports.
-
-### Responsiveness and the Event Loop
-
-Because R is fundamentally single-threaded, both IPC mechanisms are constrained by the R event loop, but they surface this limitation differently to the client:
-
-- **The "Busy" State**: If R is executing a long-running computation, the `httpuv` server running inside the session cannot process incoming HTTP requests (such as a request for `/rpc` `workspace` or `completion`). 
-- **Active vs. Passive Waiting**: In the legacy system, the client passively waited for `workspace.lock` to change, effectively ignoring the busy state until the operation completed. With the `sess` HTTP RPC model, the client actively requests data. Therefore, the client *must* implement short, aggressive timeouts (e.g., 500ms) for these HTTP requests. If a timeout occurs, the client gracefully interprets this as "R is busy" and can display a loading state without locking up the IDE's UI thread.
+1. **Elimination of File Watchers**: Replaces unreliable OS-level file system watchers with persistent WebSocket connections for instantaneous event pushing.
+2. **On-Demand Evaluation**: Evaluations of the Global Environment are now performed only when requested by the client ("Pull" model), reducing R's background workload.
+3. **Unified Standard**: Unifies all structured communication under the **JSON-RPC 2.0** standard across WebSocket and HTTP transports.

src/rstudioapi.ts

@@ -153,6 +153,21 @@ export async function documentSaveAll(): Promise<void> {
     await workspace.saveAll();
 }
 
+export async function documentClose(id: string, save: boolean): Promise<void> {
+    const target = findTargetUri(id);
+    const targetDocument = await workspace.openTextDocument(target);
+    if (save) {
+        await targetDocument.save();
+    }
+    // VS Code doesn't have a direct "close document" API that takes a Document.
+    // We have to show it and then execute the close editor command, 
+    // or use more complex workbench commands.
+    const editor = await window.showTextDocument(targetDocument, { preserveFocus: true, preview: true });
+    if (editor) {
+        await commands.executeCommand('workbench.action.closeActiveEditor');
+    }
+}
+
 // TODO: very similar to ./utils.getCurrentWorkspaceFolder()
 export function projectPath(): { path: string | undefined; } {
 

src/session.ts

@@ -936,6 +936,10 @@ async function handleRequest(message: Record<string, unknown>, ws: WebSocket) {
                     await rstudioapi.documentNew(String(params.text), String(params.type), params.position as number[]);
                     result = true;
                     break;
+                case 'document_close':
+                    await rstudioapi.documentClose(String(params.id), Boolean(params.save));
+                    result = true;
+                    break;
                 default:
                     throw new Error(`Unsupported method: ${method}`);
             }