@roku-sdk/ai 0.0.0-stage → 2.18.0

package/skills/fonts-and-glyphs/references/glyph-tables.md

@@ -0,0 +1,128 @@
+# Glyph tables
+
+45 constants, from `@roku-sdk/components/glyphs`. They are split into three tables here for the
+one reason that matters at runtime — **which font supplies the character** — because that, not the
+codepoint, decides whether a symbol survives a custom app typeface.
+
+| Group | Count | Under a system font | Under a custom app font |
+|---|---|---|---|
+| RokuFont01 private-use glyphs | 32 | renders | renders — firmware fallback applies |
+| Unicode characters RokuFont01 backs | 3 | renders | renders — same fallback |
+| RokuUI-Regular symbols | 10 | renders | **tofu**, unless the custom font supplies them |
+
+35 of the 45 are safe under a custom typeface. The ten that are not are the ones that look most
+ordinary, which is why this split is worth carrying.
+
+Verified on device twice, on different hardware and different firmware, by rendering the
+constants in a label with a custom TrueType font.
+
+- Roku Express 4K+, firmware 15.3.5: the private-use glyphs and the stars came through; `←` `↑`
+  `→` `↓` `✓` `✗` were empty boxes. `•` `…` `–` `—` rendered only because that particular font
+  happened to contain them — do not read that as a guarantee.
+- Roku Native (2910X), firmware 16.0.4, 1080p: same split. Under the system font every constant
+  rendered; under a custom TrueType the button glyphs and `★` `☆` rendered and `←` `→` `✓` were
+  boxes. The same run also showed a `Font` with a `uri` and no `size` drawing a speck, and
+  `fallbackGlyph` — as `u25CF` and as a literal `●` — leaving every box exactly as it was, both
+  for a RokuUI-only symbol and for a codepoint (`U+0E5B`, `U+A64B`) that no font on the device
+  has.
+
+The two runs agree, which is the point of having both: this split is a property of the firmware's
+font chain, not of one box.
+
+## 1. RokuFont01 — private-use glyphs (safe under a custom font)
+
+RokuFont01 is wired in as the system-wide fallback font in firmware, so these resolve wherever
+they appear.
+
+| Constant | Codepoint | Placeholder | Description |
+|---|---|---|---|
+| `OPTIONS_GLYPH` | `U+E000` | `{OPTIONS_GLYPH}` | Options / star (no border) |
+| `OK_BUTTON_GLYPH` | `U+E001` | `{OK_BUTTON_GLYPH}` | OK in circle |
+| `OPTIONS_BUTTON_GLYPH` | `U+E002` | `{OPTIONS_BUTTON_GLYPH}` | Options / star (with border) |
+| `MICROPHONE_GLYPH` | `U+E003` | `{MICROPHONE_GLYPH}` | Microphone (no border) |
+| `PLAY_PAUSE_BUTTON_GLYPH` | `U+E004` | `{PLAY_PAUSE_BUTTON_GLYPH}` | Play/pause (with border) |
+| `PLAY_PAUSE_GLYPH` | `U+E005` | `{PLAY_PAUSE_GLYPH}` | Play/pause (no border) |
+| `DOT_GLYPH` | `U+E006` | `{DOT_GLYPH}` | Baseline-aligned dot (icon-row form) |
+| `HOME_GLYPH` | `U+E007` | `{HOME_GLYPH}` | Home (no border) |
+| `SEARCH_GLYPH` | `U+E008` | `{SEARCH_GLYPH}` | Search / magnifying glass |
+| `REMOTE_GLYPH` | `U+E009` | `{REMOTE_GLYPH}` | Remote control |
+| `REPLAY_GLYPH` | `U+E010` | `{REPLAY_GLYPH}` | Instant replay |
+| `MICROPHONE_BUTTON_GLYPH` | `U+E011` | `{MICROPHONE_BUTTON_GLYPH}` | Microphone (with border) |
+| `SEARCH_BUTTON_GLYPH` | `U+E012` | `{SEARCH_BUTTON_GLYPH}` | Search (with border) |
+| `FAST_FORWARD_GLYPH` | `U+E013` | `{FAST_FORWARD_GLYPH}` | Fast forward |
+| `REWIND_GLYPH` | `U+E014` | `{REWIND_GLYPH}` | Rewind |
+| `SHORTCUT_ONE_BUTTON_GLYPH` | `U+E015` | `{SHORTCUT_ONE_BUTTON_GLYPH}` | Shortcut 1 |
+| `SHORTCUT_TWO_BUTTON_GLYPH` | `U+E016` | `{SHORTCUT_TWO_BUTTON_GLYPH}` | Shortcut 2 |
+| `CLOSED_CAPTIONS_GLYPH` | `U+E017` | `{CLOSED_CAPTIONS_GLYPH}` | Closed captions |
+| `LIVE_TV_GLYPH` | `U+E018` | `{LIVE_TV_GLYPH}` | Live TV |
+| `SLEEP_TIMER_GLYPH` | `U+E019` | `{SLEEP_TIMER_GLYPH}` | Sleep timer |
+| `GENERAL_APP_GLYPH` | `U+E020` | `{GENERAL_APP_GLYPH}` | General app icon |
+| `BACK_BUTTON_GLYPH` | `U+E021` | `{BACK_BUTTON_GLYPH}` | Back |
+| `HOME_BUTTON_GLYPH` | `U+E022` | `{HOME_BUTTON_GLYPH}` | Home button |
+| `QUICK_LAUNCH_BUTTON_GLYPH` | `U+E023` | `{QUICK_LAUNCH_BUTTON_GLYPH}` | Quick launch / rocket |
+| `DOWN_BUTTON_GLYPH` | `U+E024` | `{DOWN_BUTTON_GLYPH}` | Down |
+| `LEFT_BUTTON_GLYPH` | `U+E025` | `{LEFT_BUTTON_GLYPH}` | Left |
+| `RIGHT_BUTTON_GLYPH` | `U+E026` | `{RIGHT_BUTTON_GLYPH}` | Right |
+| `KIDS_PROFILE_GLYPH` | `U+E027` | `{KIDS_PROFILE_GLYPH}` | Kids profile |
+| `UP_BUTTON_GLYPH` | `U+E028` | `{UP_BUTTON_GLYPH}` | Up |
+| `POWER_BUTTON_GLYPH` | `U+E029` | `{POWER_BUTTON_GLYPH}` | Power |
+| `THUMBS_UP_GLYPH` | `U+E030` | `{THUMBS_UP_GLYPH}` | Thumbs up |
+| `THUMBS_DOWN_GLYPH` | `U+E031` | `{THUMBS_DOWN_GLYPH}` | Thumbs down |
+
+The numbering is decimal-style: the A–F slots in each decade (`U+E00A`–`U+E00F`, `U+E01A`–`U+E01F`,
+`U+E02A`–`U+E02F`) are unassigned. The font defines 32 private-use codepoints and the table lists
+all of them.
+
+`DOT_GLYPH` (`U+E006`) and `BLACK_CIRCLE` (`U+25CF`) are the same outline at two vertical
+positions — `DOT_GLYPH` sits on the baseline to line up with the other icon glyphs, `BLACK_CIRCLE`
+is raised to text centre for use inside a run of text. Both have full outline data; neither is
+reserved.
+
+## 2. Unicode characters RokuFont01 backs (safe under a custom font)
+
+Real Unicode codepoints, but RokuUI-Regular does not contain them — they resolve through the same
+RokuFont01 fallback as the private-use glyphs above. That makes them the *safe* shapes to use in
+custom-font text.
+
+| Constant | Codepoint | Char | Description |
+|---|---|---|---|
+| `BLACK_CIRCLE` | `U+25CF` | ● | Dot raised to text centre, for use inside a text run |
+| `BLACK_STAR` | `U+2605` | ★ | Filled star |
+| `WHITE_STAR` | `U+2606` | ☆ | Outlined star |
+
+## 3. RokuUI-Regular symbols (no backstop under a custom font)
+
+Part of the default UI font, so they need no fallback under a system font. Under a custom app font
+there is no RokuFont01 backstop for them either. **These are the ten constants to audit if your
+app ships its own typeface.**
+
+| Constant | Codepoint | Char | Description |
+|---|---|---|---|
+| `BULLET` | `U+2022` | • | Bullet |
+| `ELLIPSIS` | `U+2026` | … | Horizontal ellipsis |
+| `EN_DASH` | `U+2013` | – | En dash |
+| `EM_DASH` | `U+2014` | — | Em dash |
+| `LEFT_ARROW` | `U+2190` | ← | Leftwards arrow |
+| `UP_ARROW` | `U+2191` | ↑ | Upwards arrow |
+| `RIGHT_ARROW` | `U+2192` | → | Rightwards arrow |
+| `DOWN_ARROW` | `U+2193` | ↓ | Downwards arrow |
+| `CHECK_MARK` | `U+2713` | ✓ | Check mark |
+| `BALLOT_X` | `U+2717` | ✗ | Ballot X |
+
+## What has no constant, on purpose
+
+Characters you can type directly get none: `·` middle dot, `°` degree, currency signs, maths
+operators, quotation marks. Type them. A constant would add a name to look up without adding
+anything the compiler or the device cares about.
+
+Geometric arrows `◀` and `▶` are in **neither** font and have no constants because they do not
+render. Reach for `LEFT_ARROW` / `RIGHT_ARROW`, or the bordered `LEFT_BUTTON_GLYPH` /
+`RIGHT_BUTTON_GLYPH` when you want the remote-button look.
+
+## Firmware placeholders
+
+The `{CONSTANT_NAME}` column above is the firmware's own placeholder syntax, used in translated
+firmware strings and resolved by the firmware's string layer. It is not a TypeScript symbol and it
+is not template syntax: putting `{BACK_BUTTON_GLYPH}` in a label renders those braces literally.
+Use the placeholder form only where you are explicitly producing text for something that resolves
+firmware placeholders, and interpolate the imported constant everywhere else.

package/skills/logging-and-errors/SKILL.md

@@ -0,0 +1,227 @@
+# Logging and Errors
+
+## Overview
+
+An RSG SDK TypeScript app reports what it is doing through one exported `logger`, and survives a
+throw through Solid's `ErrorBoundary`. Both have a platform edge that catches people out: log
+levels are enforced in **two** places, one of which deletes your call before the app ever runs,
+and the SDK already wraps every screen in a boundary whose fallback draws nothing — so the
+default shape of a failure here is a blank screen rather than a crash.
+
+## When to Use
+
+- a log level raised and nothing new appears
+- log levels configured somewhere that turns out to have no effect
+- `console` calls present while developing and gone from the build handed over
+- a screen that comes up blank with no crash and no stack
+- containing a throw so one bad screen does not take the app with it, or recovering afterwards
+- an uncaught-exception handler that never fires, or fires and then behaves unexpectedly
+- a crash stack that cannot be traced back to the TypeScript that produced it
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Getting logs **off** a device from a shell script or a CI job | The `cli-dev-loop` skill | This skill is about a line being emitted; collecting it afterwards is a different surface |
+| Getting logs off a device, or decoding a stack, inside an agent session | The `mcp-ai-dev-loop` skill | Same distinction, reached through tool calls rather than a shell |
+| What the running app costs in frames, memory or startup time | The `app-performance` skill | Instrumenting for cost is measurement, not reporting |
+| Which Solid primitives `@roku-sdk/solid` exports at all | The `solid-on-roku` skill | This skill owns the failure, not the export surface |
+
+## Read the reference first for this task
+
+| If the request is | Read now, before answering |
+|---|---|
+| Writing or debugging a `setUncaughtExceptionHandler` callback | `references/uncaught-exceptions.md` |
+
+The tables below say that the handler exists, what it never sees, and that registering one cannot
+be undone. Its timeout, its inverted `done` flag and the conditions under which it silently does
+nothing are only in the reference, and a handler written from the summary alone is wrong in ways
+that do not show up until something throws in production.
+
+## Quick Reference
+
+| Question | Answer |
+|---|---|
+| Get a logger | `import { logger } from "@roku-sdk/rsg-ts"` — the root one; `logger.getLogger("myscreen")` for a child |
+| Levels available | `trace`, `debug`, `info`, `warn`, `error`. There is no `fatal`, and `createLogger` is not exported |
+| Why a message is a function | `logger.info(() => \`...\`)` — the thunk is only invoked once the level check passes, so a filtered line costs nothing to build |
+| The two level knobs | `app.logger.baseLogLevel` **deletes** call sites at build time (default INFO in production builds); `app.logger.currentLogLevel` filters what remains at runtime (default ERROR; also enforced as a runtime backstop at the base level) |
+| Which one to raise | Whichever is higher wins. Raising only `currentLogLevel` recovers nothing a lower `baseLogLevel` already deleted |
+| Setting levels via `buildVariables` | A silent no-op — the build overwrites `__BASE_LOG_LEVEL__` and `__CURRENT_LOG_LEVEL__` itself |
+| Contain a throw | `<ErrorBoundary fallback={…}>` around the subtree, from `@roku-sdk/solid` |
+| Recover from one | `catchError` for a scoped throw, `resetErrorBoundaries` to retry every boundary |
+| Blank screen, no crash, no stack | The SDK's own boundary caught a root-component throw. One `error` line under source `btstp` is the entire evidence |
+| `console` in a shipped build | Dropped by `rk build`, kept by `rk dev`; `dropConsole: false` keeps them, and then `installConsolePolyfill()` restores the helpers |
+| Trace a stack back to TypeScript | Call `enableExceptionTagging()` before the code that can throw. Inside `main()`, before the anchor node, covers throws after `main()`; a throw at module top level needs the call in the entry file's first import |
+| An uncaught-exception handler | `setUncaughtExceptionHandler` — never sees an `ErrorBoundary` catch, sees nothing thrown before it registers, and registration is permanent |
+| Where these live | `logger`, `main`, `enableExceptionTagging` and `setUncaughtExceptionHandler` all come from `@roku-sdk/rsg-ts`; `installConsolePolyfill` only from `@roku-sdk/native` |
+
+## Instructions
+
+1. **Log through the exported `logger`, and give each area a child.** `logger` is the root;
+   `logger.getLogger("playback")` tags that area's lines. `createLogger` is deliberately module
+   private, so a child logger is the only sanctioned way to get a distinct source.
+
+2. **Pass a thunk, not a string.** Every method takes `() => string`. The level check runs first,
+   so an interpolation inside the thunk is never paid for on a filtered line. Building the string
+   at the call site throws that away.
+
+3. **Understand which level does what, because only one of them can be undone.**
+   - `baseLogLevel` is a **build-time** cut. Any statement calling a method below it is replaced
+     with `void 0;` in the source before the bundler sees it, so the call is not in the artifact
+     at all. Nothing at runtime can bring it back.
+   - `currentLogLevel` is a **runtime** filter over whatever survived, resolved once at module
+     load.
+
+   So diagnose in that order: if a line is missing, ask whether it was deleted before asking
+   whether it was filtered. The defaults are `INFO` for the base cut and `ERROR` for the runtime
+   filter, which is why a `debug` line is absent from a default build twice over.
+
+4. **Know what the build-time cut checks and what it does not.** It matches a whole expression
+   statement whose call target is a log method (e.g. `.trace`, `.debug`) on a receiver that is
+   recognised as an SDK logger binding in that file. Specifically, the receiver must be:
+   - A named import of `logger` (or an aliased import) from one of the SDK logger modules
+     (`@roku-sdk/rsg-ts` or `@roku-sdk/common`), or common's own relative `./logger` import.
+   - A child logger derived from any of the above via `const X = logger.getLogger("area")`
+     (and any further `.getLogger(…)` chains at module level).
+   - An inline `logger.getLogger("a").debug(…)` call in statement position.
+
+   Non-SDK receivers (`someLibrary.debug(…)`, `console.debug(…)`, `myEmitter.trace(…)`) are
+   never removed. Shadowing is respected: when a local binding reuses the name — any parameter
+   (constructor, accessor and destructured ones included), a `catch` binding, a loop variable, or
+   a local declaration — calls through it are left untouched.
+
+   One documented limitation: a logger exported from one module and re-imported under a
+   *different* import path (not one of the recognised specifiers) is not recognised by the
+   per-file pass and is not stripped at build time. The runtime backstop (see below) still
+   silences it. The sanctioned pattern is: import `logger` from the SDK and derive children
+   with `getLogger` in the same module.
+
+   A second limitation: inside a function, only a child derived directly from a recognised SDK
+   logger is stripped. A grandchild built from a function-local child — `const a =
+   logger.getLogger("a"); const b = a.getLogger("b"); b.debug(…)`, or inline
+   `a.getLogger("b").debug(…)` — is kept at build time. Like the case above, this only ever
+   leaves a call in (never removes a non-SDK one), and the runtime backstop still silences it.
+   Derive nested children at module level if you want them stripped.
+
+   Child loggers must be declared with `const`. A `let` or `var` child
+   (`let l = logger.getLogger("x")`) can be reassigned to some other object, so its calls are
+   kept at build time rather than risk deleting app code. The runtime backstop still silences them.
+
+   Only a bare statement is stripped. `const line = logger.debug(…)`, or a call guarded by
+   `&&`, survives — so a log statement written in an unusual shape will not be stripped as
+   expected.
+
+5. **Set levels in `app.logger`, never in `buildVariables`.** The two keys the logger reads are
+   `__BASE_LOG_LEVEL__` and `__CURRENT_LOG_LEVEL__`, and the build writes both itself —
+   unconditionally, after copying your `buildVariables` — then restores them only from
+   `app.logger`. So a value you put in `buildVariables` under either name is overwritten with an
+   empty string, which the reader treats exactly like an unset variable. You get the defaults,
+   with no warning that your setting was discarded.
+
+6. **Wrap a subtree that can throw in `ErrorBoundary`, and draw something in the fallback.** The
+   SDK already puts one boundary around the whole app, and its fallback returns nothing — so an
+   uncontained throw in a root component is a blank screen rather than a crash. That is the SDK
+   working as designed, not a missing feature. Your own boundary, closer to the risk, is what
+   turns it into a message the user can act on.
+
+7. **Recover with `catchError` or `resetErrorBoundaries`.** `catchError` handles a throw inside
+   one computation without unmounting a subtree; `resetErrorBoundaries` re-runs every boundary's
+   children, which is the "try again" button's implementation.
+
+8. **Expect `console` to disappear from the build you hand over.** `rk build` drops `console.*`
+   and `debugger`; `rk dev` keeps them. Set `dropConsole: false` when a build must keep them
+   on purpose — and note the helper methods (`count`, `group`, `assert` and the timing pair) come
+   from a polyfill that only auto-installs in a development build, so a production build that
+   keeps `console` also needs `installConsolePolyfill()` from `@roku-sdk/native`. Plain
+   `console.log`, `warn` and `error` are the runtime's own and are never wrapped. None of this
+   replaces `logger`: `console` has no levels, no sources and no build-time cut.
+
+9. **Call `enableExceptionTagging()` before the code that can throw**, when traces from this
+   build have to be resolvable later. Inside `main()`, before registering the anchor node, covers
+   throws from the `main()` callback onward. A throw while the bundle is still being evaluated
+   needs the call in the same module the entry file imports first (step 10). It marks each trace
+   with the build's source-map identity. It is idempotent, and calling it costs nothing at runtime
+   beyond the tagging itself. Turning a captured stack back into TypeScript afterwards is
+   `cli-dev-loop` from a shell and `mcp-ai-dev-loop` from a session — this step is only the app's half.
+
+10. **Reach for `setUncaughtExceptionHandler` only for what a boundary cannot catch**, and read
+    the reference before writing one. It replaces the SDK's default permanently, it never sees a
+    throw an `ErrorBoundary` already caught, and it is not the mechanism behind the blank screen
+    in step 6. It also misses anything thrown before it registers, and every module's top-level
+    code runs before `main()` is called. When a module can throw at its top level, register in
+    the entry file's first import rather than inside `main()`.
+
+## Render-thread transaction errors
+
+On firmware with `roku.Transaction.setErrorCallback`, SDK `main()` installs a default
+error-level logger under source `tx` before declaring app components. It reports each
+render-thread transaction error with its reason, message and available operation, node ID
+and property name. These asynchronous errors do not throw through `ErrorBoundary` or the
+uncaught-exception handler. Apps calling `roku.Transaction.setErrorCallback` themselves
+replace this default; accessors are valid only during that callback. Older firmware without
+the callback API is unchanged and cannot surface these errors through this SDK handler.
+
+## Example
+
+An app entry point that tags its traces, and a screen that contains its own failures instead of
+letting the SDK's blank fallback have them.
+
+```tsx rsg-skill=complete
+import { Label, LayoutGroup } from "@roku-sdk/components";
+import { type AnchorNodeImplementation, defineAnchorNode, FieldType, logger } from "@roku-sdk/rsg-ts";
+import { ErrorBoundary } from "@roku-sdk/solid";
+
+const screenLog = logger.getLogger("playback");
+
+const PlaybackScreenDescription = {
+    componentName: "PlaybackScreen",
+    extends: "Group" as const,
+    inputFields: {
+        assetId: FieldType.String("")
+    },
+    outputFields: {}
+};
+
+function NowPlaying(props: { assetId: string }) {
+    // The thunk is only invoked once the level check passes.
+    screenLog.info(() => `rendering asset ${props.assetId}`);
+    return <label text={props.assetId} width={800} height={48} color="0xFFFFFFFF" />;
+}
+
+const PlaybackScreen: AnchorNodeImplementation<typeof PlaybackScreenDescription> = inputs => (
+    <layoutGroup layoutDirection="vert">
+        <ErrorBoundary
+            fallback={error => {
+                // Without a fallback that draws, this subtree is simply absent.
+                screenLog.error(() => `playback failed: ${error.message}`);
+                return <label text="Playback unavailable" width={800} height={48} color="0xFF6666FF" />;
+            }}
+        >
+            <NowPlaying assetId={inputs.assetId ?? ""} />
+        </ErrorBoundary>
+    </layoutGroup>
+);
+
+export default defineAnchorNode(PlaybackScreenDescription, PlaybackScreen);
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| A level was raised, the app rebuilt, and the lines are still missing | `baseLogLevel` deleted the call sites; raising the runtime filter cannot restore a call that is not in the artifact | Raise `app.logger.baseLogLevel` and rebuild |
+| Levels set through `buildVariables` change nothing, and nothing warns | The build overwrites `__BASE_LOG_LEVEL__` and `__CURRENT_LOG_LEVEL__` with an empty string before restoring them from `app.logger` | Set them in `app.logger` |
+| A screen is blank, the app is still running, and there is no stack | A root component threw and the SDK's own boundary caught it; its fallback draws nothing | Search the log for source `btstp`; add your own `ErrorBoundary` closer to the risk |
+| An `ErrorBoundary` was added and the screen is still blank | The `fallback` returns nothing, or the boundary sits above the component that throws rather than around it | Return a real node from `fallback`; put the boundary around the risky subtree |
+| An uncaught-exception handler never fires for a render-time throw | A boundary caught it first, and the handler only sees what nothing caught | Handle it in the boundary; keep the handler for what escapes |
+| The app exits from the splash screen, and the handler never fires | A module threw at its top level while the bundle was evaluated, before the handler was registered inside `main()` | Register in a module the entry file imports first, as a bare `import "./…"` |
+| A registered handler cannot be swapped back to the SDK default | Registration replaces the default permanently, by design | Register once, at startup, and branch inside your own handler |
+| A handler was registered and does nothing at all, silently | `globalThis.Process` was unavailable, so the call warned and returned — and at the default runtime filter that warning is itself invisible | Read the reference; confirm the handler registers where the runtime provides it |
+| Diagnostics print in development and are gone from the shipped build | `rk build` drops `console.*` by default | Use `logger`, or set `dropConsole: false` deliberately |
+| `console` timing and grouping helpers are missing in a build that kept `console` | The polyfill auto-installs only in a development build | Call `installConsolePolyfill()` from `@roku-sdk/native` |
+| A captured stack cannot be matched to a build | The app never tagged its traces, or tagged them inside `main()` after a module had already thrown | Call `enableExceptionTagging()` before that code. Inside `main()` covers throws after it; a module top-level throw needs the call in the entry file's first import |
+
+`Logger`, `setUncaughtExceptionHandler` and `ErrorBoundary` are typed with TSDoc in the installed
+packages. Read an option there rather than guessing its name, and prefer it over any prose,
+including this file, when the two disagree.

package/skills/logging-and-errors/references/uncaught-exceptions.md

@@ -0,0 +1,137 @@
+# Uncaught exceptions
+
+`setUncaughtExceptionHandler` is the only hook for a throw that nothing in the app caught. It is a
+narrow API with four behaviours that are not guessable from its signature, each of which produces
+a handler that looks correct and is not.
+
+## What it does and does not see
+
+It is registered against the runtime's uncaught-exception capture callback. That means:
+
+- **Nothing thrown before the call reaches it.** Until `setUncaughtExceptionHandler` runs, only
+  the SDK's default handles a throw: it logs the error and `source_map_sha`, then the app exits.
+  The whole bundle is evaluated before `main()` is called. Each module's top-level code runs in
+  import order, and a module's imports run before its own body. So a handler registered inside
+  `main()` is too late for a module whose top level throws, such as a constant initialized from
+  a configuration read that fails. To cover that, register in a module of its own, and make it
+  the entry file's first import: `import "./install-exception-reporting";`. Keep it a bare
+  side-effect import. Import sorting keeps side-effect imports first and in the order written,
+  but sorts named imports alphabetically, which can move the handler below the module that
+  throws.
+- **An `ErrorBoundary` catch never reaches it.** A boundary handles the throw, so as far as the
+  runtime is concerned nothing escaped. Since the SDK wraps the whole app in a boundary already,
+  a render-time throw is caught before this handler is a possibility. If you want a monitoring
+  service to hear about render failures, report them from the boundary's `fallback`.
+- **Unhandled promise rejections never reach it.** They go to a separate runtime callback, which
+  the SDK sets to log the rejection at `error` and stop there. `setUncaughtExceptionHandler` does
+  not forward rejections. To act on one, register your own callback with
+  `globalThis.Process.setUnhandledRejectionCallback`, which replaces the SDK's logging.
+
+So the handler's actual scope is small. It covers a throw that happens after registration and
+outside any boundary and the reactive render path: module-level work in modules evaluated after
+it, the `main()` callback, a timer, a callback the SDK invoked directly, a listener.
+
+## The handler's contract
+
+```ts
+setUncaughtExceptionHandler(
+    async error => {
+        // error: Error. The only argument; the returned Promise is awaited.
+    },
+    { timeout: 5000, resume: false }
+);
+```
+
+| Element | Behaviour |
+|---|---|
+| `error` | The only argument. Never null: if the runtime hands over a falsy error, the SDK synthesizes one with the message `Uncaught exception (no error object provided)`, so reading `.message` or `.stack` is always safe. With `enableExceptionTagging()` active, `error.stack` ends in `[SourceMap: <sha>]`, the build's source-map identity. Send the stack as is, or it cannot be resolved later |
+| Return value | A Promise. The SDK awaits it for up to `timeout`, then tells the runtime to exit or resume |
+| `timeout` | Milliseconds the returned Promise is awaited for. Default **5000**, floor **100** — a smaller value is raised to the floor rather than rejected |
+| `resume` | Chooses what happens after. Default `false` |
+
+There is no `sha` argument and no `done` argument. A handler written as `(error, sha, done)` does
+not typecheck. The SDK logs the error message and `source_map_sha` itself, before your handler
+runs, and registering a handler does not suppress that line. The SDK also calls the runtime's
+`done` callback for you.
+
+## The `done` flag is inverted relative to `resume`
+
+This is the single easiest thing to get backwards, because the two names read as synonyms and
+mean opposites:
+
+| You pass | The SDK calls | The app |
+|---|---|---|
+| nothing, or `resume: false` | `done(true)` | exits |
+| `resume: true` | `done(false)` | resumes its event loop |
+
+`done(true)` means "yes, we are finished — exit", not "yes, the handler succeeded". Passing
+`resume: true` to keep an app alive through a background failure is legitimate, but understand
+that the app then continues from a state something already failed in.
+
+Both outcomes are unconditional: whether your handler resolves, rejects, or runs out its timeout,
+`done` is invoked with the flag chosen by `resume`. There is no path in which a failing handler
+changes the exit decision.
+
+## Registration is permanent
+
+Calling `setUncaughtExceptionHandler` replaces the currently registered handler, including the
+SDK's default. Only the last registration is active, and **there is no way to restore the SDK
+default afterwards** — no unregister, no argument that means "back to normal".
+
+The consequence for structure: register once, before anything can throw, and branch inside your own handler
+rather than swapping handlers per screen. A test that registers one has no clean way to undo it,
+which is why the module keeps an internal reset that is explicitly test-only and not exported for
+application use.
+
+## It can silently do nothing
+
+If `globalThis.Process` is unavailable when you call it, the function logs at `warn` and returns
+without registering anything. Two things make that hard to notice:
+
+- Nothing throws and nothing returns a failure — the call looks like it worked.
+- The default runtime log filter is `ERROR`, so the `warn` line explaining what happened is
+  itself filtered out.
+
+If a handler appears to be registered and never fires, distinguish this case from the
+`ErrorBoundary` case by lowering `currentLogLevel` to `WARN` and looking for that line before
+concluding the handler is wired up wrong.
+
+## Shape to copy
+
+A module of its own, `src/install-exception-reporting.ts`, that registers as it is evaluated:
+
+```ts rsg-skill=complete
+import { enableExceptionTagging, setUncaughtExceptionHandler } from "@roku-sdk/rsg-ts";
+
+enableExceptionTagging();
+
+setUncaughtExceptionHandler(
+    async error => {
+        await fetch("https://monitoring.example.com/exceptions", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ name: error.name, message: error.message, stack: error.stack })
+        });
+    },
+    { timeout: 2000 }
+);
+```
+
+The entry file imports it before anything else:
+
+```ts
+import "./install-exception-reporting";
+
+import { main, registerAnchorNode } from "@roku-sdk/rsg-ts";
+
+import MyApp from "./my-app";
+
+main(() => registerAnchorNode(MyApp));
+```
+
+`enableExceptionTagging()` comes first, so a trace captured by the handler is already tagged.
+The handler has nothing to call when it is done: the SDK finishes once the Promise settles or
+2000 ms elapse, whichever comes first. Omitting `resume` means the app exits afterwards, which
+is what you want unless you have a specific reason to keep running. It is also the only sensible
+choice for a throw during boot, because there is nothing to resume into: the throwing module
+never finished, and `main()` never registered the app.