@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills/ads-and-raf/references/integration-flows.md

@@ -0,0 +1,332 @@
+# Ads integration flows: CSAI, SSAI and CSAS
+
+One complete wired module per mode. All three obey the same protocol — wait for `"ready"`, set the
+data fields then `command`, read the matching callback — and differ only in which commands they
+issue and which nodes they need.
+
+## What differs between the three
+
+| | CSAI | SSAI | CSAS |
+|---|---|---|---|
+| Command sequence | `getAds` → `showAds`, per break | `getAds` → `stitchedAdsInit` | `getAds` → `constructStitchedStream` → `renderStitchedStream` |
+| `adView` | required | not used | required |
+| `contentView` | required | required | not used |
+| `contentMetadata` | not used | not used | required |
+| Who owns the `Video` | the app | the app | RAF — the app renders no `Video` at all |
+| Result callbacks | `onGetAdsResult`, `onShowAdsResult` | `onGetAdsResult`, `onStitchedAdResult` | `onGetAdsResult`, `onConstructStitchedStreamResult`, `onRenderStitchedStreamResult` |
+
+The `Video`-ownership row is the one that surprises people. CSAS hands RAF a single stream that
+already has the ads spliced in, and RAF plays it; there is no content `Video` in the tree and no
+`contentView` to give, so nothing in a CSAS module reacts to playback position.
+
+## CSAI: pause the content, play the break, resume
+
+The break's resume point has to be captured **before** the content is stopped, because stopping it
+is what discards the position. `position` is milliseconds and `ContentNode`'s `playStart` is
+seconds. `-1` is the "not started" sentinel: 0 ms is a real cue point, so 0 cannot be it.
+
+Mid-roll arrives as another `onGetAdsResult`, from a `getAds` the task fired itself. That is why
+the same handler serves pre-roll and every mid-roll, and why the empty-pods branch is guarded on
+`position() === -1` — an empty mid-roll result means "no fill for this break", and restarting
+content on it would fight the playback already running.
+
+```tsx rsg-skill=complete
+import type { AdsCommand, AdsState, EventHandler, EventHandlerAdPods, ShowAdsResult } from "@roku-sdk/ads";
+import { Ads } from "@roku-sdk/ads";
+import { Component, ContentNode, Group, MediaControl, Rectangle, Video } from "@roku-sdk/components";
+import { DomNode } from "@roku-sdk/interfaces";
+import { createSignal } from "@roku-sdk/solid";
+
+const AD_TAG = "https://example.com/tag.vmap";
+const CONTENT_URL = "https://example.com/content.m3u8";
+
+export const CsaiPlayer: Component = () => {
+    const [command, setCommand] = createSignal<AdsCommand>("none");
+    const [adUrl, setAdUrl] = createSignal("");
+    const [adView, setAdView] = createSignal<DomNode | undefined>();
+    const [contentView, setContentView] = createSignal<DomNode | undefined>();
+    const [control, setControl] = createSignal<MediaControl>("none");
+    const [position, setPosition] = createSignal(-1);
+    const [playStart, setPlayStart] = createSignal(0);
+
+    const handleAdsState = (state: AdsState) => {
+        if (state !== "ready") return;
+        setAdUrl(AD_TAG);
+        setCommand("getAds");
+    };
+
+    const handleGetAdsResult: EventHandlerAdPods = pods => {
+        if (pods.length > 0) {
+            setPlayStart(position() === -1 ? 0 : position() / 1000);
+            setControl("stop");
+            setCommand("showAds");
+        } else if (position() === -1) {
+            setControl("play");
+        }
+    };
+
+    const handleShowAdsResult: EventHandler<ShowAdsResult> = result => {
+        if (result === "none") return;
+        if (result === "completed") {
+            setControl("play");
+            setCommand("none");
+        } else {
+            setControl("stop");
+            setCommand("stop");
+        }
+    };
+
+    return (
+        <group>
+            <Video
+                width={1920}
+                height={1080}
+                content={<contentNode url={CONTENT_URL} playStart={playStart()} />}
+                control={control()}
+                notificationInterval={1.0}
+                onPosition={value => setPosition(value)}
+                ref={element => setContentView(element)}
+                gainFocus={control() === "play"}
+            />
+            <rectangle
+                width={1920}
+                height={1080}
+                color="0x000000FF"
+                visible={control() !== "play"}
+                ref={element => setAdView(element)}
+            />
+            <Ads
+                adUrl={adUrl()}
+                adView={adView()}
+                contentView={contentView()}
+                command={command()}
+                onAdsState={handleAdsState}
+                onGetAdsResult={handleGetAdsResult}
+                onShowAdsResult={handleShowAdsResult}
+            />
+        </group>
+    );
+};
+```
+
+`gainFocus={control() === "play"}` is doing more than it looks. An ad break takes focus and does
+not give it back, so without a re-assertion on resume the app plays content that answers no remote
+keys. Tying it to the resume condition is the cheapest correct place for it.
+
+## SSAI: the stream already contains the ads
+
+The app plays one stream and asks RAF what is on screen. `getAds` here exists only to give
+`stitchedAdsInit` its pods — nothing is rendered from the result.
+
+There is a **race worth respecting**: `stitchedAdsInit` has to reach the task before position
+events start arriving, because the task is still in CSAI mode until it lands, and a position event
+that arrives first is treated as a CSAI cue point. Start playback from
+`onStitchedAdsInitResult` rather than from `onGetAdsResult`, and the race is answered by the
+protocol instead of by a timing margin. Only `"completed"` may start playback: an `"error"` means
+the mode never changed, so playing anyway puts position events back on the CSAI cue-point path
+against a stream that was never initialised.
+
+`onStitchedAdResult` receives RAF's own associative array, so its keys are lowercase:
+`evthandled`, not `evtHandled`. That is the general rule for anything RAF returns.
+
+The module below needs **2.15.0 or newer**: that is the release `onStitchedAdsInitResult` and its
+`StitchedAdsInitResult` type arrived in. The `stitchedAdsInit` command itself is older, but nothing
+acknowledged it before then, so on 2.14.0 the only place to start playback from is
+`onGetAdsResult` — which is the race above, answerable there by a timing margin and nothing better.
+
+```tsx rsg-skill=complete
+import type {
+    AdsCommand,
+    AdsState,
+    EventHandler,
+    EventHandlerAdPods,
+    StitchedAdsInitResult
+} from "@roku-sdk/ads";
+import { Ads } from "@roku-sdk/ads";
+import { Component, ContentNode, Group, MediaControl, Video } from "@roku-sdk/components";
+import { DomNode } from "@roku-sdk/interfaces";
+import { createSignal } from "@roku-sdk/solid";
+
+const AD_TAG = "https://example.com/tag.vmap";
+const STITCHED_URL = "https://example.com/stitched.m3u8";
+
+export const SsaiPlayer: Component = () => {
+    const [command, setCommand] = createSignal<AdsCommand>("none");
+    const [adUrl, setAdUrl] = createSignal("");
+    const [contentView, setContentView] = createSignal<DomNode | undefined>();
+    const [control, setControl] = createSignal<MediaControl>("none");
+    const [adPlaying, setAdPlaying] = createSignal(false);
+
+    const handleAdsState = (state: AdsState) => {
+        if (state !== "ready") return;
+        setAdUrl(AD_TAG);
+        setCommand("getAds");
+    };
+
+    const handleGetAdsResult: EventHandlerAdPods = pods => {
+        if (pods.length === 0) {
+            setControl("play");
+            return;
+        }
+        setCommand("stitchedAdsInit");
+    };
+
+    // Playback starts here, once the task confirms it is in SSAI mode.
+    const handleStitchedAdsInitResult: EventHandler<StitchedAdsInitResult> = result => {
+        if (result === "none") return;
+        if (result === "error") {
+            // Still in CSAI: position events would drive mid-roll against a stream never
+            // set up for it, so this is terminal rather than a warning to play past.
+            setCommand("stop");
+            return;
+        }
+        setControl("play");
+    };
+
+    const handleStitchedAdResult: EventHandler<Record<string, unknown>> = result => {
+        setAdPlaying(result?.evthandled === true);
+    };
+
+    return (
+        <group>
+            <Video
+                width={1920}
+                height={1080}
+                content={<contentNode url={STITCHED_URL} />}
+                control={control()}
+                notificationInterval={1.0}
+                ref={element => setContentView(element)}
+                gainFocus={control() === "play" && !adPlaying()}
+            />
+            <Ads
+                adUrl={adUrl()}
+                contentView={contentView()}
+                command={command()}
+                onAdsState={handleAdsState}
+                onGetAdsResult={handleGetAdsResult}
+                onStitchedAdsInitResult={handleStitchedAdsInitResult}
+                onStitchedAdResult={handleStitchedAdResult}
+            />
+        </group>
+    );
+};
+```
+
+`stitchedAdsInit` on empty pods changes no mode and answers `"error"`. The `pods.length === 0`
+branch above is what keeps that case from arising at all; the result is the backstop, and reading
+it as anything other than terminal leaves the app playing a stitched stream through a task still
+in CSAI.
+
+## CSAS: build one stream, then render it
+
+Two commands in sequence, each gated on the previous one's result. `contentMetadata` describes the
+content to be stitched: a `ContentNode` prop bag, so `url` and `length` in seconds.
+
+The task writes `"none"` to both result fields before it writes the real value, so guard on it
+before branching. The shape to avoid is `if (result === "completed") { … } else { fail }`: it puts
+the sentinel down the failure path, which here means abandoning the session before RAF has
+answered.
+
+A failed `constructStitchedStream` puts the task back in CSAI mode. Its `"error"` result is the
+only notice of that, so treat it as terminal for the session rather than retrying
+`renderStitchedStream`.
+
+```tsx rsg-skill=complete
+import type {
+    AdsCommand,
+    AdsState,
+    ConstructStitchedStreamResult,
+    EventHandler,
+    EventHandlerAdPods,
+    RenderStitchedStreamResult
+} from "@roku-sdk/ads";
+import { Ads } from "@roku-sdk/ads";
+import { Component, Group, IContentNodeProps, Rectangle } from "@roku-sdk/components";
+import { DomNode } from "@roku-sdk/interfaces";
+import { createSignal } from "@roku-sdk/solid";
+
+const AD_TAG = "https://example.com/tag.vmap";
+
+export const CsasPlayer: Component<{ onFinished: () => void }> = props => {
+    const [command, setCommand] = createSignal<AdsCommand>("none");
+    const [adUrl, setAdUrl] = createSignal("");
+    const [adView, setAdView] = createSignal<DomNode | undefined>();
+    const [contentMetadata, setContentMetadata] = createSignal<IContentNodeProps>();
+    const [playing, setPlaying] = createSignal(false);
+
+    const handleAdsState = (state: AdsState) => {
+        if (state !== "ready") return;
+        setContentMetadata({ url: "https://example.com/content.m3u8", length: 600 });
+        // Measurement fields must be in place before the pods are fetched.
+        setAdUrl(AD_TAG);
+        setPlaying(true);
+        setCommand("getAds");
+    };
+
+    const handleGetAdsResult: EventHandlerAdPods = () => {
+        setCommand("constructStitchedStream");
+    };
+
+    const handleConstructResult: EventHandler<ConstructStitchedStreamResult> = result => {
+        if (result === "none") return;
+        if (result === "completed") {
+            setCommand("renderStitchedStream");
+        } else {
+            setPlaying(false);
+            props.onFinished();
+        }
+    };
+
+    const handleRenderResult: EventHandler<RenderStitchedStreamResult> = result => {
+        if (result === "none") return;
+        // "user_exited" is a viewer back-out, not a failure.
+        setPlaying(false);
+        setCommand("none");
+        props.onFinished();
+    };
+
+    return (
+        <group>
+            <rectangle
+                width={1920}
+                height={1080}
+                color="0x000000FF"
+                visible={playing()}
+                gainFocus={playing()}
+                ref={element => setAdView(element)}
+            />
+            <Ads
+                adUrl={adUrl()}
+                adView={adView()}
+                contentMetadata={contentMetadata()}
+                command={command()}
+                enableAdMeasurements={true}
+                contentGenre="Entertainment"
+                contentId="csas-sample"
+                onAdsState={handleAdsState}
+                onGetAdsResult={handleGetAdsResult}
+                onConstructStitchedStreamResult={handleConstructResult}
+                onRenderStitchedStreamResult={handleRenderResult}
+            />
+        </group>
+    );
+};
+```
+
+`onGetAdsResult` ignores its pods here on purpose: `constructStitchedStream` reads the ads the task
+already holds, so there is nothing for the app to pass along and no reason to inspect them.
+
+## Debug output
+
+`debugOutput={true}` turns on RAF's own logging, which is the only view into what the library did
+with a tag it rejected. It is verbose and belongs in development only — set it from the same
+`"ready"` branch that sets `adUrl`, and leave it off in anything you ship.
+
+## Stopping
+
+`command = "stop"` ends the task's loop and reports `"stopped"` on `onAdsState`. Issue it while the
+component is still mounted — from a Back key handler, or wherever the app decides to leave the
+player. Doing it from `onCleanup` alone is best-effort: SolidJS may already have disposed the
+effect that writes the field, and `onAdsState` is gone either way, so nothing confirms it. The task
+does self-terminate when SceneGraph destroys the node, so the cleanup is a reasonable belt-and-
+braces addition — just not the primary path.

package/skills/app-packaging/SKILL.md

@@ -0,0 +1,107 @@
+# App Packaging
+
+## Overview
+
+`rk device package` and `rk dcl` talk to a Roku over its developer interface: they sign using the key
+already on that box and manage what it holds, so they need a device. Signing is where the SDK
+stops. Getting a version onto a channel, staged for review or live, is done by uploading the
+signed `.pkg` in the Roku Developer Dashboard; the SDK has no command for it.
+
+## When to Use
+
+- producing a signed `.pkg` from an app that is already installed on a device
+- a signing step in CI, where nothing can be typed at a prompt
+- pointing a box at a different signing key, or checking which developer ID it now reports
+- getting a version onto a channel, staged for review or published outright, and which part of
+  that the SDK does
+- listing or clearing the dev channel and the Dynamic Component Libraries a device holds
+- a partner shipping a library separately for the app to load from a URL at runtime, and where
+  setting that library up and referencing a node from it is written down
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Installing `@roku-sdk` packages from npmjs.com | The `sdk-installation` skill | That is what arrives; this is what leaves |
+| Cutting a release of the SDK's own packages | The repository's release process | This ships an app to a channel, not a library to a registry |
+| Producing the build that then gets signed | The `cli-dev-loop` skill | Signing starts from an app that already exists on the box |
+| Writing the code that builds a Dynamic Component Library, or loads one and pulls a node out of it | `documentation/core-concepts/dcl.md` | No other skill covers it, so the two Quick Reference rows below are the whole routing answer: `rk dcl` manages the ones a device already holds, and building one is an app whose `roku-config.ts` sets `app.type: "dcl"`, side-loaded like any other |
+| What `roku-config.ts` declares about the app | The `project-setup` skill | Its `package` block is read here, but the file belongs there |
+| Reaching the device at all, or which one a command lands on | The `device-management` skill | Everything here takes `--device` or `--host`; what those resolve to is decided there |
+
+## Quick Reference
+
+| Goal | Do |
+|---|---|
+| Sign what is installed on the device | `rk device package sign` |
+| Sign with nothing to type at | `ROKU_SIGNING_PASSWORD` in the environment |
+| Point a box at another signing key | `rk device package rekey <pkg-path>` |
+| See what is installed | `rk device package ls` |
+| Remove the dev channel | `rk device package delete` |
+| Re-image the installed dev channel as squashfs | `rk device package squashfs` |
+| Get a version onto a channel, staged or live | Upload the signed `.pkg` in the Roku Developer Dashboard; no `rk` command does this |
+| DCLs on a device | `rk dcl ls`, `rk dcl delete <filename>`, `rk dcl delete-all` |
+| A partner's library the app loads at runtime | Build it as its own app with `app.type: "dcl"` in `roku-config.ts`; the host resolves it from the channel store by library name |
+| Referencing a node out of that library | `getComponentLibraryFactory()` from `@roku-sdk/runtime/component-library`, then `factory.createLibrary(<name>)`, `library.load()` and `getDCLComponent(library, <node>)` from `@roku-sdk/rsg-ts` — full walkthrough in `documentation/core-concepts/dcl.md` |
+
+## Instructions
+
+1. **The signing password resolves from three places, in one order.** `--signing-password`
+   first, then the `ROKU_SIGNING_PASSWORD` environment variable, then a masked prompt. The
+   prompt needs a TTY on both stdin and stdout; without one the command fails immediately and
+   names the first two. A CI job therefore has exactly one tier it can use — the environment
+   variable. The flag is the wrong answer there, because the value lands in the process list and
+   in any log that echoes the command it was given.
+
+2. **`rk device package sign` signs the app on the device, not a file on disk.** It requires a box with
+   a dev channel already installed and keyed; a box without one fails saying so, and the fix is
+   to sideload first. The signed file lands in `--out`, falling back to `package.outDir` from
+   `roku-config.ts`, and then to the working directory. Name `--out` in a job, so the step that
+   collects the artifact does not depend on where the command ran.
+
+3. **`rekey` finds its package from the project when it is not given one.** The positional wins;
+   otherwise `package.signingKeyPackage` is used, and with neither the command explains both.
+   `--dev-id` falls back to `package.devId` the same way, and it is an assertion rather than an
+   input: the developer ID the box reports afterwards is checked against it.
+
+4. **Putting a version on a channel happens in the Developer Dashboard.** The SDK signs; it does
+   not upload, stage, wait on review or promote. Whether a version goes live or stays with QA is
+   chosen there, against the signed `.pkg` this skill produced. Do not offer an `rk` command or
+   flag for any of those steps, and do not read a `publishing` block in `roku-config.ts` as
+   evidence of one: the block is accepted, and `rk` does not read it.
+
+5. **Only a signed `.pkg` goes onto a channel.** What `rk build` writes to `dist-build` is
+   unsigned: side-load it, then sign it on the device with `rk device package sign`. That signed `.pkg`
+   is the file to upload.
+
+6. **`device package` and `dcl` name a box.** Both take `--device` for a box in the store, or `--host`
+   with `--password` for one by address, and both work the same whether the command went through
+   a running server or `--local`. The two ways of naming a box are exclusive: `--host` together
+   with `--device` is an error, and `--host` alone still needs a password, because an address is
+   not in the store to carry one.
+
+## Example
+
+A CI job that signs without a prompt, keeping the password out of the command line and putting
+the artifact in a fixed directory for the job to collect.
+
+```bash
+# ROKU_SIGNING_PASSWORD comes from the job's secret store, never from an argument.
+# --out fixes where the .pkg lands, whatever directory the job runs in.
+rk device package sign --device ci-box --out dist-build/package --json
+```
+
+The `.pkg` in `dist-build/package` is then uploaded in the Roku Developer Dashboard, where the
+version is kept for review or published.
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Signing fails in CI asking for a password, and works on a laptop | The prompt is the only tier left, and it needs a TTY | Set `ROKU_SIGNING_PASSWORD` in the job environment |
+| The signed file is not where the next step looks | `--out` was omitted, so it fell back to `package.outDir` or the working directory | Pass `--out`, or set `package.outDir` to the directory that step reads |
+| An unsigned build is offered for upload | The output of `rk build` was taken as the release artifact | Sideload it, then `rk device package sign`; only the signed `.pkg` uploads |
+| An agent proposes an `rk` command to upload, stage or promote a version | The SDK has none | Sign with `rk device package sign`, then upload in the Roku Developer Dashboard |
+| `rekey` reports the wrong developer ID | `--dev-id` or `package.devId` asserts the expected one and it did not match | Confirm which key the box should hold before rekeying it |
+| Signing fails saying no dev channel is installed | Nothing is on the box to sign | Sideload the app first, then sign |
+| `--host` is rejected, or reaches a box you did not mean | It cannot be combined with `--device`, and on its own it still needs `--password` | Give `--host` with `--password`, and drop `--device` — the store is not consulted for an address |

package/skills/app-performance/SKILL.md

@@ -0,0 +1,133 @@
+# App Performance
+
+## Overview
+
+An RSG SDK TypeScript app that stutters, drops frames or grows its memory is diagnosed by
+measuring it on the device, and there are two measurements: a Perfetto trace, which says where
+the time went, and a CDP heap read, which says how much memory is held. They do not coexist —
+the heap read rebuilds the app in debug mode — so decide which question you are asking before
+recording anything. This skill covers taking the measurement and classifying what it shows.
+
+## When to Use
+
+- an animation, scroll or transition that janks or drops frames on real hardware
+- a key press whose effect arrives late, or a screen that takes too long to appear
+- memory that climbs the longer the app is left running
+- a recorded trace that has to be read: which thread, which slice, which interval blocks
+- confirming that a change actually improved something, rather than assuming it did
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| The everyday deploy, screenshot, drive and log loop | The `mcp-ai-dev-loop` skill | Those tools answer what the app did, not what it cost |
+| The tracing tools refuse, or no tools are present | The `mcp-setup` skill | The Perfetto tools need a running server; that is setup |
+| A grid's own configuration or API | The `flex-grid` skill | Once a trace names the grid, the fix is that component's subject |
+| A slow build, install or CI job | The `cli-dev-loop` skill | Nothing here measures anything but the running app; how the build and install steps are invoked belongs there |
+| A test that never touches hardware | The `testing` skill | Timings from an in-process tree describe the host machine |
+| A test that passes some runs and fails others, on a device or off it | The `testing` skill for an in-process test; for one that drives real hardware, no skill in this library covers it — take it to the repository's own device-test guidance | Flakiness is a determinism problem; nothing here measures whether a result is repeatable, and a trace of a passing run says nothing about the failing one |
+
+## Quick Reference
+
+| Question | Call | Gives |
+|---|---|---|
+| Where did the frame time go | `perfetto_enable`, then `perfetto_start` / `perfetto_stop` | A trace file to open in the Perfetto UI |
+| The same recording with no agent session | `rk perfetto` | The CLI spelling of those three calls; the analysis afterwards is identical and stays here |
+| How much JS memory is held | `cdp_session_create`, then `cdp_heap_usage` | Total and used heap bytes |
+| Which JavaScript function is hot, or what retains memory | The `cpu-and-heap-profiling` skill | A CPU profile or heap snapshot file |
+| Release the debug session | `cdp_session_end` | One session per device; this frees it |
+| Which TypeScript ran inside a slow window | Redeploy with `deploy_app`'s `perfettoPaths` | Named slices for instrumented functions |
+| Which callback fired | The `EventCallback` slice under `observer.callback`, in an instrumented build | Function name and source position |
+
+## Instructions
+
+1. **Pick the measurement from the question, not the other way round.** "It janks" is a trace.
+   "It grows" is a heap read. Recording the wrong one is expensive in a way that is not obvious
+   later, because both produce plausible-looking numbers.
+
+2. **Enable tracing before the app launches.** `perfetto_enable` configures the device; the app
+   reads that configuration at startup. Enabling after the app is already running yields a trace
+   missing exactly the early work most worth seeing, and it looks like a successful recording.
+   The order is `perfetto_enable`, then deploy, then `perfetto_start` — reproduce the problem —
+   then `perfetto_stop`.
+
+3. **Read the trace against the render threads first.** `RenderThr:Main` carries `render` and
+   `swapBuffers` and is where the frame budget is decided; `AuxRenderThread` carries work that
+   can steal from it, and `consumeAllTasks` running on either during an animation is one of the
+   three usual causes of jank. TypeScript work arrives under the `rokuos.typescript` category.
+   Locate those in the track list before reading a single slice, because every rule below is
+   stated relative to where a slice sits.
+
+4. **The frame budget is `render` plus `swapBuffers` inside 16.67 ms.** Past that the frame is
+   dropped. The usual causes are one long `render`, meaning a heavy scene or too many nodes, or
+   an `observer.callback` over 1 ms delaying the first `render`.
+
+5. **Only two transaction intervals block, and only in one direction.** Going from TypeScript to
+   the render thread, `transaction.start` to `transaction.commit` blocks, and so does
+   `transaction.update` to `transaction.end`; over roughly 300 ms during an animation is what
+   makes a smooth scroll jank. The trace points carrying `toTS` are the other direction, and a
+   wide span there does **not** stall the render thread. Reading one as a stall is the most
+   common way to spend a day on the wrong slice.
+
+6. **Attribute the inside of a slow window by instrumenting, not by guessing.** Redeploying with
+   `deploy_app` and `perfettoPaths: ["packages/solid/src"]` — `--perfetto-paths` is the same
+   thing spelled for a terminal — names the reactive work inside the interval, where a
+   `createElement` slice means a SceneGraph node was created — during an animation that is
+   itself the finding. Widen to `solid-js` only if the narrower path is not enough: each
+   tracepoint costs roughly 10–30 microseconds per call, so a broad path distorts what you came
+   to measure. The value is matched as a substring of the source file path, so it depends on where
+   the SDK sits: `packages/solid/src` inside this workspace, `@roku-sdk/solid/src` in an app that
+   installed it. A path that matches nothing instruments nothing and reports no error, which reads
+   as an interval with no TypeScript in it. Naming every `createSignal` and `createMemo` makes
+   reactive slices attributable, but only in a build with `solidDevMode: true` at the top level
+   of `roku-config.ts` built with `rk dev --debug` (or `--solid-dev-mode` on any JS build), which is
+   off by default. Plain `rk dev` ignores the config field, and a build that precompiles to Hermes
+   bytecode skips it, so reactive work in a production trace stays anonymous no matter how
+   the config is set. The switch also adds overhead at component and signal creation, which is
+   one more reason the trace it names is not the one to quote timings from.
+
+7. **A heap read changes the build, so never compare its timings with a trace.**
+   `cdp_session_create` builds and sideloads unminified JavaScript with the debug preset
+   (debugger probe stubs, config overrides); plain `rk dev` also ships JavaScript by default. `cdp_heap_usage` reports total and used bytes from that app. Memory numbers
+   are meaningful, timings from that build are not. Only one session may exist per device, so
+   end it with `cdp_session_end` before starting another.
+
+8. **One trace is not evidence.** A TypeScript slice that spikes may have had garbage collection
+   run inside it, and one that spikes on a render thread may simply have been scheduled away.
+   Trust what repeats across frames, and re-record the same interaction after a fix rather than
+   declaring the fix worked.
+
+9. **Remove what you instrumented.** Extra tracepoint paths, temporary slices and debug builds
+   all outlive the investigation if nothing takes them out. Redeploy normally before handing the
+   app back, or the next person measures your instrumentation.
+
+## Example
+
+Recording a scroll that janks, in the order the calls have to happen:
+
+```text
+perfetto_enable  {}                       -> device configured; must precede launch
+deploy_app       { root }                 -> the app starts with tracing on
+perfetto_start   {}                       -> returns sessionId and filePath
+                                          -- reproduce the jank now
+perfetto_stop    { sessionId }            -> filePath, bytes, durationMs
+```
+
+Then, in the trace: find the `keyEvent` that starts the scroll, follow the run of `render` and
+`swapBuffers` after it on `RenderThr:Main`, and measure the first frame that exceeds 16.67 ms.
+Everything overlapping that timestamp on the other two threads is the candidate set; a
+`transaction.start` to `transaction.commit` gap spanning it is the answer, and a `toTS` span
+spanning it is not.
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The trace is missing the startup or first-animation work | Tracing was enabled after the app launched | `perfetto_enable` first, then deploy, then `perfetto_start` |
+| A wide transaction span sits over the dropped frame but changing that code does nothing | It was a `toTS` span, which does not block the render thread | Measure `transaction.start` to `transaction.commit` instead |
+| Timings look far worse than users report | They were read from a build made for a heap session, which has no Hermes bytecode | Trace a normal build; use the debug build only for memory |
+| `cdp_session_create` is refused | A session already exists for that device | `cdp_session_end`, then create the new one |
+| Instrumented slices are everywhere and nothing is legible | The instrumentation path was widened before the narrow one was read | Start at `packages/solid/src` and add more only if it falls short |
+| Reactive work shows up unnamed | Named slices need solid's development build, which a production build skips outright | Set `solidDevMode: true` and redeploy with `rk dev --debug`, or pass `--solid-dev-mode` |
+| A fix looks like an improvement in one recording | A single spike can be garbage collection or a context switch | Re-record and compare what repeats across frames |
+| The tracing tools report that they need a server | Perfetto tools are server-mode only | Start one — see the `mcp-setup` skill |