Merge pull request #1084 from joshunrau/docs

docs: document runtime execution context

Author: joshunrau

docs/en/4-concepts/4.3-runtime-execution-context.md

@@ -0,0 +1,71 @@
+---
+title: Runtime Execution Context
+slug: en/docs/concepts/runtime-execution-context
+sidebar:
+  order: 3
+---
+
+In JavaScript, the global object varies depending on the execution environment. In the browser, the global object is `window`, which includes properties like `document`. In Node.js, the global object is `global`. This object is specific to Node.js and is not available in browsers.
+
+For example, you cannot access `process.env` in a browser environment because it is specific to Node.js. Similarly, calling `document.createElement` on a server does not work, as it is intended for the client-side. Attempting either will result in a runtime error.
+
+In Open Data Capture, code runs on both the client and server. You should therefore not access browser-specific APIs, like `document` or `window` unless you are within functions named `render`, which execute exclusively on the client. For those familiar with Next.js, think of these functions as rendering a component with a "use client" directive within a React Server Component.
+
+## Example of Problematic Instrument
+
+```ts
+import { defineInstrument } from '/runtime/v1/@opendatacapture/runtime-core';
+import { z } from '/runtime/v1/[email protected]';
+
+const button = document.createElement('button');
+button.textContent = 'Submit Instrument';
+document.body.appendChild(button);
+
+export default defineInstrument({
+  // ...
+  kind: 'INTERACTIVE',
+  content: {
+    render(done) {
+      button.addEventListener('click', () => {
+        done({ message: 'Hello World' });
+      });
+    }
+  }
+  // ...
+});
+```
+
+## Fixing This Instrument
+
+To fix the instrument, there are two options:
+
+1. Move the browser-specific code directly within the render function
+2. Wrap the browser-specific code in a function. This function can be defined outside the render function but must only be called within it.
+
+**Example**
+
+```ts
+import { defineInstrument } from '/runtime/v1/@opendatacapture/runtime-core';
+import { z } from '/runtime/v1/[email protected]';
+
+function createButton() {
+  const button = document.createElement('button');
+  button.textContent = 'Submit Instrument';
+  document.body.appendChild(button);
+  return button;
+}
+
+export default defineInstrument({
+  // ...
+  kind: 'INTERACTIVE',
+  content: {
+    render(done) {
+      const button = createButton();
+      button.addEventListener('click', () => {
+        done({ message: 'Hello World' });
+      });
+    }
+  }
+  // ...
+});
+```