@roku-sdk/ai 0.0.0-stage → 2.19.0

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.

package/skills/mcp-ai-dev-loop/SKILL.md

@@ -0,0 +1,189 @@
+# MCP AI Dev Loop
+
+## Overview
+
+The SDK ships an MCP server, and it is how an agent reaches a Roku: put the current code on
+the device, see what it did, drive it, read what it said, and turn a crash back into
+TypeScript. Everything below is one of those five steps. The server exposes far more tools
+than this skill names — the surface grows — so enumerate what the server offers and match it
+to the step you are on, rather than trusting any list, including this one.
+
+## Read the reference first for these tasks
+
+| If the request is | Read now, before answering |
+|---|---|
+| A crash, an uncaught exception, a stack trace, or console output from the device | `references/crash-and-console.md` |
+| Setting a breakpoint, pausing the app, or reading values in a paused frame | `references/live-debugging.md` |
+
+Decoding is the step with the most ways to look finished and be wrong — a stack decoded
+against the wrong build reads perfectly and points at the wrong line.
+
+A debug session also breakpoints and steps, which is worth knowing before you reach for a
+`console.log` and a redeploy. One rule governs it and costs a rebuild to learn the hard way:
+`cdp_eval` evaluates in the running app, but the first debugger tool of any kind — arming a
+breakpoint included — disables it for the rest of that connection, and only a new session
+brings it back. Read whatever you can with `cdp_eval` first. A session that has spent it is
+not stuck, though: `cdp_debugger_eval_frame` reads values in a stopped frame's own scope for
+that session's whole life, and the reference is how you reach a frame worth reading.
+
+## When to Use
+
+- deploying an app under development to a device and confirming what landed
+- capturing the screen, or reading the rendered node tree, of a running app
+- sending remote keys to walk the app somewhere without touching hardware
+- collecting device logs, or finding a line in them
+- a device the tools cannot see, or a deploy that lands stale code
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| No Roku tools in the session at all, or a client that will not connect | The `mcp-setup` skill | That is transport and editor config; everything here assumes a session that already lists tools |
+| A shell script, a CI step, or anything with no agent in it | The `cli-dev-loop` skill | These tools exist inside an agent session; a build runner has to call `rk` itself, and the CLI's directories and flags differ from what the tools expose |
+| Registering a Roku with the CLI, or which box a *shell* command reaches | The `device-management` skill | A tool call names its own target, so a tool that answered the wrong box is fixed here; the CLI's stored list is fixed there |
+| Installing a signed package through the device's developer web page | Roku's own documentation | That is a browser workflow, and nothing here drives it |
+| Debugging a web, mobile or desktop app | That platform's tooling | The tools here speak to a Roku and nothing else |
+| Writing the app's code or its project configuration | The `sdk-components` and `project-setup` skills | This skill starts once there is something to run |
+| Testing a component without a device | The `testing` skill | That renders into an in-process tree; nothing here is involved |
+| An app that janks, drops frames, or grows its memory, and the question is what it costs | The `app-performance` skill | These tools report what the app did, not how long it took to do it |
+
+## Quick Reference
+
+| Step | Call | Notes |
+|---|---|---|
+| Find the device | `list_devices` | Always first. Nothing else can target sensibly until you know what is registered and which is active |
+| Register one | `add_device`, then `activate_device` | Needed once per device; `update_default_auth` sets the password used for sideloading |
+| Build and deploy | `deploy_app` | Builds **and** sideloads in one call. This is the normal way to get code onto a device |
+| Build only | `build_app` | Produces an artifact without touching the device |
+| Sideload an existing artifact | `sideload_app` | Does not build. Reads the directory you point it at |
+| See the screen | `capture_screen` | Returns an image, and writes a file |
+| Read the node tree | `ecp` with `command: "query/app-ui"` | The rendered tree of the running app, as JSON |
+| Read device facts | `ecp` with `command: "query/device-info"` | Model, firmware, resolution |
+| Press a key | `ecp` with `command: "keypress"` | One key |
+| Press several | `ecp` with `command: "keysequence"` | One call for a whole path through the UI. Prefer it over a run of single presses |
+| Name a key for either of those | The **wire** name, not the runtime one | `Select` (not `OK`), `Rev` (not `rewind`), `Fwd` (not `fastforward`), `Info` (not `options`). Every element is validated before anything reaches the device, so one wrong name fails the whole call with `ECP_INVALID_KEY` |
+| Deep-link | `ecp` with `command: "input"` | Launch parameters, without navigating there by hand |
+| Collect logs | `logs` — `start`, then `get` or `search` | A session must exist before there is anything to read |
+| Decode a crash | `decode_stack_trace` | `references/crash-and-console.md` |
+| Confirm the server is up | `get_server_health` | The fastest way to tell whether `rk server` is running, which decides what the rest of the surface can do |
+| Start or stop a cloud device | `device_start`, `device_stop` | Roku Cloud Emulator only, billed while it runs. The server stops what it started; see instruction 11 |
+
+## Instructions
+
+1. **`list_devices` first, every session.** It returns what is registered and which one is
+   active, and every other tool's targeting is defined against that. Without a device the
+   failure arrives several steps later, worded as though the app were at fault.
+
+2. **Target with `device` or with `host`, never both.** `device` selects a registered device
+   by id, IP or name; `host` addresses one directly and skips the store. Passing both is an
+   error. Passing neither uses the active device, and if none is active the tool says so.
+   The targeting parameters are not uniform, though — `capture_screen` takes `device` and not
+   `host`, so a screenshot needs the device to be in the store even when a deploy to the same
+   box by `host` has just worked. Read the schema of the tool you are calling rather than
+   assuming this one. A Roku Cloud Emulator device is named `rce:<name>` in `device`; it has
+   no address, so `host` can never reach it.
+
+3. **Deploy with `deploy_app` and stop there.** It builds and sideloads in one call, into
+   `dist-dev`. Since `sideload_app` reads `dist-dev` too, following a deploy with a sideload
+   only re-sends what was just sent; reach for `sideload_app` when you have an artifact and no
+   reason to rebuild, not as a second half of deploying.
+
+4. **The two directories are the one thing to keep straight.** `deploy_app` writes and reads
+   `dist-dev`. `build_app` writes `dist-build`. `sideload_app` reads `dist-dev` unless you
+   pass `outDir`. So `build_app` followed by a bare `sideload_app` is the pairing that sends
+   stale code, or fails outright when `dist-dev` was never built: pass
+   `outDir: "dist-build"` to match them, or use `deploy_app` and think about neither.
+
+   That pairing now reports itself rather than passing silently. A bare `sideload_app` whose
+   `dist-dev` is older than `dist-build` returns a warning naming both paths, their build
+   times, and the `outDir` to pass — it still sends the artifact you asked for, so read the
+   warning rather than assuming the newer one went. When the directory holds nothing at all,
+   the error names a command that could have created it and reports where a `pkg-dir` was
+   actually found. A project that sets `outDir` in `roku-config.ts` avoids the split entirely:
+   the sideload path reads project config, so an `outDir` from config or from the parameter is
+   treated as deliberate and draws no warning. Sideloading Hermes bytecode (`index.hbc`) also
+   returns a warning, since a device without the `rsg_typescript` token refuses to launch it.
+
+5. **Never reach the device's network endpoints yourself.** No `curl`, no hand-built request
+   to a device port. The tools carry the device's password, retry sensibly and report failure
+   in a way you can act on; a raw request does none of that and its silence looks like success.
+
+6. **Look before you conclude.** `capture_screen` says what a person would see;
+   `ecp` with `query/app-ui` says what the app actually built. They answer different questions
+   and disagree in the interesting cases — a node present in the tree but invisible on screen
+   is a layout or a colour bug, not a rendering one.
+
+7. **Screenshot pixels are not layout coordinates.** The app lays out in design space, usually
+   1920×1080; `capture_screen` returns the device's own resolution, which is 1280×720 on an HD
+   box. Multiply by 1.5 going from a measured screenshot pixel to a coordinate in the code, and
+   report positions back to a human in design space. Confirm both ends before you rely on the
+   ratio: the design space is the app's `ui_resolutions`, and the device's output is the
+   `ui-resolution` field of `query/device-info`. On a device already in FHD they match 1:1.
+   A frame from the installer rather than ECP (`source: "installer"`, always on a Roku Cloud
+   Emulator device and on a secure retail device without an ECP token) is the exception to
+   reading the ratio off the device: its size is not fixed, so take the ratio from the
+   returned image's own dimensions. That path also captures only while the sideloaded app is
+   in the foreground, unless the device's auth token grants the `screenshot` permission.
+
+8. **Prefer one `keysequence` to a run of `keypress` calls.** Each call is a round trip, and a
+   sequence keeps the timing consistent. After the last key, capture or query rather than
+   assuming the app kept up.
+
+9. **Some tools need the server, and say so.** `logs`, `get_server_health` and the profiling
+   and debug-session families only work when `rk server` is running; the rest fall back to
+   running the CLI in process. `get_server_health` is the quickest way to tell which side of
+   that line a session is on, and a tool that needs a server names one in its failure. Getting
+   a server running, and pointing a client at it, is the `mcp-setup` skill's subject.
+
+10. **Clean up what you instrumented.** Log lines added to chase a bug, probe nodes injected
+    into the tree, stopwatch wrappers around a function: tag them all with one prefix when you
+    add them, and remove them by that prefix before you finish.
+
+11. **A Roku Cloud Emulator device costs money while it runs, so start one only when asked.**
+    No tool starts a stopped device implicitly; a call that
+    needs it fails with `RCE_DEVICE_NOT_RUNNING`, worded for a shell (`rk device start`). In a
+    session the equivalent is `device_start`, which takes a minute or two and makes the server
+    the device's owner. The server stops it on `device_stop`, after a stretch with no tool call or
+    session touching it, and whenever the server exits — but call `device_stop` yourself when
+    the work is done rather than leaning on the idle timer. `device_stop` refuses a device the
+    server did not start (`RCE_NOT_SERVER_OWNED`); that one belongs to whoever started it. It also
+    refuses one another MCP session started (`RCE_NOT_SESSION_OWNED`): pass `force: true` only when
+    the user means to stop it. If a stop fails, the server keeps the device and retries about
+    every 30 seconds and on exit, but call `device_stop` again rather than assume it went. Both
+    tools need a running `rk server`, and the device must already be registered with
+    `rk device add --rce`, which is the `device-management` skill's subject.
+
+## Example
+
+A session that gets code onto a device and confirms it, in the order the tools are called:
+
+```text
+list_devices                      -> which device, and is one active
+deploy_app       { root }         -> builds dist-dev, sideloads, launches
+capture_screen   {}               -> the screen as it is now
+ecp              { command: "keysequence", keys: ["right", "right", "Select"] }
+ecp              { command: "query/app-ui" }   -> the tree after the presses
+logs             { action: "start" }
+logs             { action: "search", filter: "MyScreen" }
+```
+
+Each step answers one question. If a step returns something you did not expect, stop and find
+out why before sending the next key — a crashed app accepts keypresses silently, and every
+observation after that point describes a device that is no longer running your app.
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The device is running older code than the source | `build_app` wrote `dist-build` and a bare `sideload_app` read `dist-dev` | Use `deploy_app`, or pass `outDir: "dist-build"` to `sideload_app`. The sideload now warns when the directory it read is older than the other one |
+| A tool reports no device | Nothing registered, or nothing active | `list_devices`, then `activate_device`; `add_device` if the list is empty |
+| Sideloading is refused | Developer mode is off, or the device password is wrong | Enable developer mode on the box, then set the password with `update_default_auth` |
+| `logs` fails before it reads anything | It requires server mode, and there was no session | Start `rk server`, then `logs` with `action: "start"` before `get` or `search` |
+| Keys appear to do nothing | The app crashed, or focus is not where you assumed | `capture_screen`, then `ecp` with `query/app-ui`; check the logs for an exception |
+| A screenshot looks right but the test of it fails | Measured in device pixels, compared against design coordinates | Convert before comparing |
+| A tool fails with `RCE_DEVICE_NOT_RUNNING` and suggests `rk device start` | Nothing starts a billed device implicitly; the message is worded for a shell | `device_start` if the user wants it running, then `device_stop` when done |
+| `device_stop` fails with `RCE_NOT_SESSION_OWNED` | Another MCP session (another editor window, another agent) started the device | Leave it, or pass `force: true` if the user asked for it stopped |
+| `device_start` fails with `RCE_DEVICE_STOPPING` | A stop of that device is still under way | Wait for it, then call `device_start` again |
+| `capture_screen` fails with `SCREENSHOT_NOT_OK` on a cloud or secure retail device | The sideloaded app is not in the foreground | Deploy or relaunch the app, then capture |
+| `capture_screen` on a LAN device fails with `SCREEN_CAPTURE_ERROR`, naming an auth token | A secure device, every retail Roku among them, serves no ECP capture without a Roku-issued token, and no developer password was at hand for the installer fallback | `update_default_auth`, or `rk device update <device> --password <password>` from a shell, then capture again |
+| Sideloading to a cloud device is refused for its password | Its password is kept with its registration; `update_default_auth` never applies to it | `rk device update rce:<name>` from a shell, as the error names |

package/skills/mcp-ai-dev-loop/references/crash-and-console.md

@@ -0,0 +1,68 @@
+# Crashes and console output
+
+A thrown error reaches you by one of two routes, and which one you have decides how much work
+is left.
+
+## Route 1: a live debug session, where the stacks arrive decoded
+
+`cdp_session_create` builds the app in debug mode, deploys it, loads the source map and
+connects. With a session up:
+
+- `cdp_errors_read` returns the exceptions the app has thrown, **with their stacks already
+  mapped back to TypeScript**. Nothing else to do.
+- `cdp_console_read` returns console output, so a `console.log` added to narrow something down
+  is readable without starting a log session at all.
+- `cdp_console_clear_errors` and `cdp_console_clear_console` empty those buffers. Clear before
+  reproducing, and what you read afterwards is only what this attempt produced.
+
+One session per device. Redeploying through `cdp_session_update` clears both buffers as part
+of the update, so read what you need *before* you redeploy, not after.
+
+This route is strictly better than searching a log buffer when you can have it: the stack
+comes back resolved, and console output is separated from every other line the device emits.
+
+## Route 2: the log stream, where the stack arrives raw
+
+Without a session, an uncaught exception is written to the device log along with a
+`source_map_sha=` line naming the build it came from. That is what `logs` gives you, and the
+stack in it contains bundle positions rather than TypeScript positions: `index.js` for plain
+`rk dev`, or `index.hbc` for a build using `--compile-ts`.
+
+Hand the whole thing to `decode_stack_trace`. Do not try to read it, and do not open a source
+map yourself: JS frames need the ESBuild map; bytecode frames need a composed map or the
+Hermes and ESBuild maps.
+
+## Getting the decode right
+
+`stackTrace` is the only required parameter. Paste the raw text — surrounding log noise is
+fine, since only `index.hbc` and `index.js` frames are read — and the tool finds the build's
+SHA in the `source_map_sha=` or `[SourceMap: ...]` marker the runtime emitted.
+
+The other four parameters are the difference between a decode you can trust and one that
+merely succeeds:
+
+| Parameter | When you need it |
+|---|---|
+| `buildDir` | When the app is not at the root the server is running from. Resolution is anchored at that root, so in a monorepo an app in a subdirectory reports `No HBC source map found` for every frame until you pass this — point it at the build's `bundle` directory |
+| `sha` | When the trace has no marker, or you are deliberately decoding against an older build |
+| `context` | Lines of source shown around each frame; defaults to 2 |
+| `dclDirs` | When frames name a Dynamic Component Library rather than `index` — map each library name to its own build directory |
+
+**The failure to watch for**: a `sha` that names a directory which does not exist does not
+error. It falls back to auto-detection and decodes against whatever build is newest locally,
+which produces a confident answer pointing at the wrong line. If a decoded frame does not
+match the code you think ran, suspect this before suspecting the frame.
+
+Source maps never leave your machine — only the JavaScript bundle (or bytecode with `--compile-ts`) is on the device — so a decode
+is only as good as the build directory still sitting in your working tree. Decode before you
+rebuild.
+
+## Tagging exceptions
+
+`enableExceptionTagging()` appends a `[SourceMap: <sha>]` marker to every `Error.stack`, which
+is what makes an error caught and logged by the app's own code decodable later. It is opt-in
+and idempotent.
+
+Uncaught exceptions do not need it: the runtime logs the SHA line for those on its own. Turn it
+on when the app catches errors and reports them itself — that is the case where the stack
+reaches your log without the runtime's marker attached.

package/skills/mcp-ai-dev-loop/references/live-debugging.md

@@ -0,0 +1,129 @@
+# Live debugging: breakpoints and paused frames
+
+A debug session can do more than report what already went wrong. It can stop the app on a line
+you choose and let you read the values that reached it — which is the difference between
+inferring why a handler misbehaved and watching it happen.
+
+Creating a session, and reading errors or console output from one, is
+`references/crash-and-console.md`. This file starts once a session is up.
+
+## `cdp_eval` keeps working alongside the debugger
+
+`cdp_eval` evaluates an expression inside the running app without stopping it, and it keeps
+working for the whole life of the connection — including after a `cdp_debugger_*` tool has
+enabled the Debugger domain, arming a breakpoint, or being genuinely paused.
+
+While paused, `cdp_debugger_eval_frame` is still the better tool for inspecting the paused
+code itself: it evaluates in the frame's own scope, so a handler's arguments and locals are in
+scope by name, which `cdp_eval` (global scope only) can't see. It requires a `callFrameId`,
+which `cdp_debugger_state` returns for each frame of the current pause. Reach for it because of
+that extra visibility, not because `cdp_eval` has stopped working.
+
+A breakpoint, not a blind pause, is still the reliable way into a stopped app: `cdp_debugger_pause`
+against an idle app (nothing running, no timers/animation/input) simply times out after about
+five seconds — there's no JavaScript execution to interrupt. A breakpoint on a line you know
+executes, followed by driving the app to it, always lands where you intended.
+
+## The flow
+
+Six steps, and the order matters more than any single call:
+
+1. **`cdp_source_grep`** — find the line by searching the *deployed* bundle, matched by
+   TypeScript path. This is also how you get a path in the form the next step demands.
+2. **`cdp_breakpoint_set`** — arm it. The response reports the compiled line it mapped to.
+3. **Drive the app to that line** — `ecp` with `command: "keypress"`, or whatever reaches the
+   code. Once it stops the app itself is frozen: its UI stops responding, and anything that waits
+   on the app to do something will wait forever. The debugger tools are what still answer.
+4. **`cdp_debugger_state`** — read the pause. It returns a `callFrameId` per frame, each already
+   mapped back to a TypeScript file and line, with the SDK's own frames below yours.
+5. **`cdp_debugger_eval_frame`** — read values in that frame's scope, by name. A handler's
+   arguments and locals are simply in scope; nothing has to be logged to be visible.
+6. **`cdp_debugger_resume`** — let it go.
+
+`cdp_debugger_pause` is deliberately absent from that list. It interrupts at the next statement
+the app happens to execute, which means it either times out on an idle app or lands somewhere
+you did not choose on a busy one. It answers exactly one question — whether the app is executing
+JavaScript at all — and is not a way to reach a line.
+
+## When a breakpoint does not stop where you expect
+
+Keyed on the symptom, because that is the order you meet them in:
+
+| What you see | What it means | What to do |
+|---|---|---|
+| `Could not map src/file.tsx:120 to a compiled location: the file exists on disk but is not part of the bundle`, HTTP 400 | The path resolved, but the file is not in the bundle that is on the device: tree-shaken out, or not reachable from the entry | Confirm with `cdp_source_list` or `cdp_source_grep`. Nothing is wrong with the path or the line |
+| `Could not map …` ending `(project root: …)`, or `: no compiled code at or after this line` | The first: the path matches no source in the map. A path is accepted as absolute, as relative to the session's project root, or as the raw source-map path. The second: the file is in the bundle but nothing is compiled at or after that line, as at the end of a file | First: take the path from `cdp_source_list` or `cdp_source_resolve`. Second: use an earlier line, and confirm the extent with `cdp_source_get` |
+| `Breakpoint creation failed` | The location exists but the engine refused it — an import or declaration that produced no reachable instruction | Move to a statement that executes at run time |
+| The call **succeeds**, reports `active: true`, and nothing ever stops | Two different causes, below. This is the expensive one, because nothing surfaces it | Do not trust `active: true`. It means the line was *mapped*, not that it can be reached |
+
+**Read that first message carefully, because its wording is the trap.** `Could not map … to a
+compiled location` sounds like *this line is not executable*, and the natural reaction is to go
+looking for a different line. It is almost always the path. A relative path fails this way even
+when the line is perfect:
+
+- Fails: `src/components/player.tsx`
+- Works: `/Users/you/project/src/components/player.tsx`
+
+For the accepted-but-silent case, there are two causes and they need different fixes:
+
+| Cause | How to confirm |
+|---|---|
+| The line number matches your working tree, not the build on the device | `cdp_source_get` reads the deployed bundle. If what it shows at that line is not what your editor shows, the breakpoint is on whatever used to be there. Rebuild with `cdp_session_update` rather than by hand: it redeploys into the same session and re-maps every breakpoint against the new build, **reporting the ones it can no longer place** — which turns this silent case into a named failure |
+| The line carries no executable statement — a comment, a blank line, a type-only declaration | The mapping snaps to a nearby compiled offset and reports success for a location that can never be reached. Move to a statement that runs |
+
+One more message worth recognising rather than fearing: `the app's compiled script has not been
+observed yet`. It is close to unreachable in practice, because enabling the domain makes the
+engine replay its already-loaded scripts before acknowledging. If it does appear, the session
+attached earlier than the app's own bundle loaded.
+
+## Two habits
+
+**Resume before concluding.** A component that renders more than once per interaction stops once
+per render, and the first stop need not be the interesting one — a single key press stops twice on
+a handler that runs on both the press and the release edge, and the values differ between them.
+Read the first frame, resume, and see whether another stop follows before deciding what happened.
+
+**Step only once you are in the right frame.** `cdp_debugger_step_over`, `_step_into` and
+`_step_out` are cheap once a pause is where you want it and nearly useless as a way of getting
+there. Prefer a second breakpoint over stepping toward a distant line.
+
+## Before a long session: the request limiter
+
+The server rate-limits itself, and a debugging sweep is the one workflow that reaches the ceiling:
+**100 requests per rolling 15 minutes**, counted across every route but the health check, so tool
+calls and CDP traffic share the budget. Exceeding it returns HTTP 429 with `RATE_LIMIT_EXCEEDED`.
+
+That is worth knowing in advance because of how it presents. Calls start failing partway through a
+session that was working, which reads like the app having crashed or the device having dropped off
+— and the instinct is to redeploy, which spends more requests.
+
+Raise it before you start, not after: `--no-rate-limit` when launching the server, or
+`RK_DISABLE_RATE_LIMIT=1` in its environment. Both are read once at startup, so a server that is
+already running has to be restarted for either to matter.
+
+## Reading the deployed source
+
+`cdp_source_list`, `cdp_source_get`, `cdp_source_grep` and `cdp_source_resolve` all read the
+bundle **that is on the device**, addressed by TypeScript path. That is the point of them: they are
+not a convenience over opening the file locally, they are the only way to see what the device
+actually has. Every stale-line problem above is diagnosed with them, and `cdp_source_list` is where
+an exact path comes from when a project-relative one does not match.
+
+Two things to expect from `cdp_source_list`. It returns the SDK's and dependencies' sources
+alongside the app's own, so the app's files are a small minority of a long list — filter rather
+than read it. And the session summary's file count is not the length of that list; treat it as
+"a source map loaded" and nothing more.
+
+## Not to be confused: the `dap_*` family
+
+`dap_*` speaks Roku's own socket-based BrightScript debug protocol on TCP 8081. It is **not** the
+Microsoft Debug Adapter Protocol, and the resemblance of the name is the whole problem — every one
+of those tool descriptions says so in capitals. Nothing on this page uses that family: TypeScript
+running under the JavaScript engine is debugged through the `cdp_*` tools.
+
+## What belongs elsewhere
+
+| If the question is | Go to |
+|---|---|
+| An exception that has already been thrown, or console output | `references/crash-and-console.md` — a session reports those with stacks already mapped, and no breakpoint is involved |
+| What something costs — memory, frame time, why the app janks | The `app-performance` skill. It owns the measurement tools, and this page is about correctness, not cost |