@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills/device-management/SKILL.md

@@ -0,0 +1,158 @@
+# Device Management
+
+## Overview
+
+The `rk` CLI keeps its own list of Rokus, and that list is not part of any project. Every command
+that touches a device resolves a target from it — or from a flag that overrides it, or from the
+environment when it is empty. Almost everything that goes wrong here is a question of which of
+those three won, so the useful first move is to find out rather than to guess.
+
+## When to Use
+
+- registering a Roku, or getting a developer password stored against one
+- keeping a stored developer password out of a shared repository
+- choosing which registered box commands land on, and changing it
+- running a single command against a box that was never registered
+- several worktrees or checkouts that disagree about which devices exist
+- a device list that is empty, or that holds an entry no file seems to declare
+- a device subcommand that runs, prints one line, and tells you nothing
+- registering, starting or stopping a Roku Cloud Emulator device, which is listed with the others but registered in a file of its own
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| An agent session whose MCP tools answer, and a tool call that reached the wrong box | The `mcp-ai-dev-loop` skill | A tool call carries its own target argument, so the fix is there and not in the CLI's store — even though the symptom reads identically |
+| Building, sideloading, driving a device or reading its logs | The `cli-dev-loop` skill | This skill ends the moment the box answers |
+| Signing an app, publishing it, or clearing what is installed | The `app-packaging` skill | Those act on the artifact, not on how the box is reached |
+| What `roku-config.ts` declares about the app | The `project-setup` skill | The device store is not project configuration and lives outside the repository |
+| What a freshly scaffolded app's `.gitignore` covers, beyond the device store | The `project-setup` skill | The scaffold's own output is its subject; the one entry that protects a stored password is below |
+| Leasing a box out of a shared pool | `documentation/advanced/rk/device-lease.md` and `documentation/advanced/rk/device-pool.md` | Leases are a separate mechanism from the device store; `rk` ships the `local` provider, and any other pool kind has to be registered by the caller |
+| Turning on developer mode on the television itself | Roku's own documentation | That happens on the box, and no CLI command can do it |
+
+## Quick Reference
+
+| Goal | Do |
+|---|---|
+| Register a Roku | `rk device add <ip>` |
+| Store its password | `rk device update <target> --password <pwd>` |
+| One password for every box | `rk device set-default-password` |
+| See the list and which one is active | `rk device ls` |
+| Switch the active box | `rk device set-active <target>` |
+| Stop pinning one | `rk device clear-active` |
+| Remove one | `rk device rm <target>` |
+| Find out which file is being read | `rk device store-path` |
+| Keep a stored password out of a shared repo | add `.roku` to `.gitignore` |
+| Send one command elsewhere | `--device <id\|ip\|name>`, or `--host` with `--password` |
+| Register a cloud device | `rk device add --rce <name> --snapshot <snapshot>`, then `rk device set-active rce:<name>` |
+| See every cloud device in the organisation, registered or not | `rk device ls --org` |
+| Start and stop it (billed while running) | `rk device start rce:<name>`, `rk device stop rce:<name>` |
+
+## Instructions
+
+1. **Two files can hold the list, and a local one wins outright.** The nearest
+   `.roku/roku-dev-config.json` found by walking upwards is used whenever it carries a `devices`
+   array; otherwise `~/roku-dev-config.json` supplies the list. When both exist the local one
+   still wins, and the CLI warns that it is doing so. `ROKU_DEV_CONFIG_PATH` replaces the home
+   path entirely. `rk device store-path` prints the file actually in effect, which settles the
+   question faster than reasoning about it.
+
+2. **The home file is the one worth keeping, because worktrees share it.** A local list belongs
+   to one checkout, so five worktrees mean five lists that drift apart. Delete the `devices`
+   array from the local config — the file may stay — and every checkout reads the central list.
+
+3. **The active pointer is resolved separately from the list.** A local config's
+   `activeDeviceId` outranks the home one even when every device is declared centrally. One
+   shared list with a different active box per worktree is therefore a supported arrangement
+   rather than a conflict, and it is worth knowing before "fixing" it.
+
+4. **`rk device add` cannot take a password.** For a box on your network it accepts `--name`,
+   `--id`, `--tag` and `--json`, and nothing else. Set the password afterwards with `rk device update <target> --password`, or set
+   one for every box at once with `rk device set-default-password`.
+
+5. **`--device` and `--host` are alternatives, not partners.** `--device` looks the box up in the
+   store, so it needs nothing else. `--host` bypasses the store entirely, so it needs
+   `--password` beside it. Passing both fails with a message saying exactly that, and the reason
+   is that they answer the same question two incompatible ways.
+
+6. **An empty store does not mean there is no device.** With `ROKU_DEV_TARGET` set to a valid
+   address, a synthetic entry is used, taking its password from `ROKU_DEV_PASSWORD` and showing
+   up tagged as having come from the environment. A CI image with no config file that still
+   reaches a box is almost always doing this.
+
+7. **Two advertised subcommands do nothing yet.** `ping` and `info` appear in the CLI's own
+   help and each prints a single line saying it is not yet implemented. Nothing is wrong with
+   the box; use `rk device ls` for what is registered. `rk device status` does work, but only
+   for a Roku Cloud Emulator device: with a box on your network active it says so and exits 0,
+   and naming one fails with `DEVICE_KIND_UNSUPPORTED`.
+
+8. **A local store puts a developer password inside the repository.** The password is written in
+   clear text into whichever `roku-dev-config.json` is in effect, so a local one lands at
+   `.roku/roku-dev-config.json` — a committable path. An app scaffolded by `rk create` ignores the
+   whole `.roku/` directory and is covered; any other project needs that entry added by hand,
+   before the first commit. `rk device add` warns while the directory is unignored and accepts any
+   of `.roku`, `/.roku`, `.roku/` or `/.roku/`, so the spelling its own warning suggests does
+   clear it — but it compares against those four forms and nothing else, so a pattern such as
+   `**/.roku` ignores the directory while leaving the warning in place. If the file was committed
+   already, `git rm --cached` it and treat the password as disclosed.
+
+9. **A Roku Cloud Emulator device is a second kind in the same listing, kept in its own file.**
+   `rk device ls` shows both kinds, but a registration lives in `~/roku-rce-devices.json`, beside
+   the RCE token in `~/roku-rce-config.json`; `ROKU_RCE_CONFIG_PATH` moves both, and
+   `~/roku-dev-config.json` holds LAN devices only. Neither is ever read from a project's
+   `.roku/`. `RK_RCE_TOKEN` outranks the saved token, and `rk device set-rce-token` saves one
+   without taking it as an argument. Name the device `rce:<name>` wherever a command takes one:
+   a bare name also resolves, but when a box on your network shares it the LAN box wins, with a
+   warning on stderr naming the `rce:` spelling. It has no address, so `--host` can never reach
+   it — use `--device`. Its developer password, like the token, is read from standard input,
+   never from an argument, so `rk device update <target> --password` is refused for it; from a
+   pipe only the first line is read. `rk device update rce:<name>` prints only what it changed,
+   and `--json` prints `{ device }`. It is billed while it runs and nothing starts it behind your
+   back: a command that needs it says `rk dev --start` or `rk device start`, and whoever starts it
+   should stop it. `documentation/advanced/rk/rce.md` covers creating one, snapshots, and what works on it.
+
+## Example
+
+Moving a checkout off its own private list and onto the shared one, then confirming what the CLI
+now reads.
+
+```bash
+# What is actually in effect right now.
+rk device store-path
+rk device ls
+
+# Register centrally and give the box its password in two steps, not one.
+rk device add 10.0.0.42 --name desk-ultra
+rk device update desk-ultra --password <pwd>
+rk device set-active desk-ultra
+```
+
+If `store-path` reported a `.roku/roku-dev-config.json` inside the checkout, remove the `devices`
+array from it first — otherwise the commands above write to a list only this worktree can see.
+
+A one-off box that should never be registered skips all of it:
+
+```bash
+rk ecp query/device-info --host 10.0.0.99 --password <pwd>
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `rk device add` rejects a password option | `add` takes only `--name`, `--id`, `--tag` and `--json` | `rk device update <target> --password` |
+| `rk device remove` is not recognised | The subcommand is `rm` | `rk device rm <target>` |
+| A tag-clearing option is rejected | No such option exists, though older documentation names one | Re-tag with `rk device update --tag` |
+| Two worktrees see different devices | Each has its own local `devices` array | Drop the local array; keep `~/roku-dev-config.json` |
+| A warning about a legacy local device list | Both files exist and the local one is winning | Migrate the list to the home file |
+| `--device` together with `--host` fails | They resolve the target two incompatible ways | `--device` for a stored box, `--host` with `--password` for an ad-hoc one |
+| `--host` alone is refused for want of a password | Bypassing the store also bypasses the stored password | Add `--password`, or register the box and use `--device` |
+| A device health subcommand prints one line and stops | `ping` and `info` are not implemented | `rk device ls` |
+| `rk device status` only prints that it reports on cloud devices, or refuses a box on your network | It reports on Roku Cloud Emulator devices only | `rk device ls` for a network box |
+| A command warns that a name "names a LAN device and a Roku Cloud Emulator device" | A box on your network shares the cloud device's name, and wins | `rce:<name>` for the cloud device |
+| `--host rce:<name>` is refused | A cloud device has no address of its own | `--device rce:<name>` |
+| A command says the cloud device is not running | Nothing starts one implicitly, since it is billed | `rk device start rce:<name>`, or `rk dev --start`; stop it afterwards |
+| `rk device ls` shows a cloud device as `unknown` | No RCE token is configured, or the service did not answer | `rk device set-rce-token`, or set `RK_RCE_TOKEN` |
+| The list is empty but commands still reach a box | `ROKU_DEV_TARGET` is set in the environment | `rk device store-path`, then check the environment |
+| `git status` offers to commit a file holding the developer password | A local store writes it to `.roku/roku-dev-config.json`, and the project was not scaffolded by `rk create`, so nothing ignores it | Ignore `.roku/`, then `git rm --cached` it if it was already committed |
+| The unignored-directory warning survives a `.gitignore` entry | The check recognises `.roku`, `/.roku`, `.roku/` and `/.roku/`, and no other pattern | Use one of those four forms rather than a glob |

package/skills/dialogs-and-modals/SKILL.md

@@ -0,0 +1,210 @@
+# Dialog lifecycle and multi-step flows
+
+## Overview
+
+A `StandardDialog` knows how to draw itself and how to take focus. What it does not know is
+*when* it should be up, what the caller learns when it goes down, or how one dialog leads to
+the next. That is app state, it lives above the component, and it is what this skill covers.
+
+The pattern is a provider at the app root that owns which dialog is showing, plus a registry
+so the scene can render the current one without knowing any of them by name. It is an
+**app-level pattern, not an SDK export** — there is no dialog provider to import. Copy it into
+the app and own it.
+
+## When to Use
+
+| If the request is | Then |
+|---|---|
+| Deciding when a dialog opens and closes, from somewhere other than the dialog itself | Here |
+| Telling apart "the viewer chose something" from "the viewer left" | Here — the close reason |
+| A flow of two or more dialogs where backing out returns to the previous step | Here — child dialogs |
+| A wait indicator that has to come down when the work it covers finishes | Here |
+| Teardown that runs twice when a dialog closes | Keep action completion idempotent; StandardDialog normalizes native close notifications |
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Which component draws the dialog, which areas and item types go inside it, or which pre-assembled variant fits | The `sdk-components` skill, and the dialog reference it declares | That skill owns composition. This one never assembles a dialog; it decides when one is up |
+| An overlay drawn out of ordinary nodes that has to hold the D-pad and dismiss on a key | The `focus-management` skill, and the focus-recipes reference it declares | `ModalBoundary` and `useModal` are the other path entirely. A hand-drawn overlay has no native modal to hand focus to, and that skill owns the wiring |
+| Focus inside a dialog, or which key dismisses it | The `focus-management` skill | A `StandardDialog` renders a native modal, so focus enters and returns on its own. Nothing here changes that |
+| A keyboard or PIN pad the viewer types into | The `sdk-components` skill for the component | Entry is its own subject. This skill only carries the flow the entry sits in |
+| Moving between whole screens rather than showing something over one | The `screen-navigation` skill | A dialog leaves the screen underneath mounted and focused-inactive; a screen change does not |
+
+## Quick Reference
+
+The provider's surface. Names are the ones the showcase pattern uses — keep them, because
+every dialog in the app reads them.
+
+| Member | Does |
+|---|---|
+| `setDialog(id, onClose, data?)` | Opens a dialog by id, with the callback that receives its result |
+| `closeDialog(params?)` | Closes the current one. Pops to the parent if there is one, otherwise calls `onClose` |
+| `openChildDialog(childId, data, parentData)` | Pushes a step. `parentData` is what gets restored underneath |
+| `getDialog()` | The current id, or `null` |
+| `getDialogData<T>()` | The data the current dialog was opened with |
+| `registerDialog(id, factory)` / `deregisterDialog(id)` | Registry, driven from `onMount` / `onCleanup` |
+| `getDialogElement()` | The current dialog as an element, for the scene to render |
+
+Two values come back through `closeDialog`:
+
+| Close param | Means |
+|---|---|
+| `reason: DialogCloseReason.ButtonPressed` | The viewer chose an action. `buttonId` says which |
+| `reason: DialogCloseReason.DialogCancelled` | The viewer left, or the dialog dismissed itself |
+
+## Instructions
+
+1. **Mount one provider at the app root** and have the scene render `getDialogElement()`.
+   The scene stays ignorant of every individual dialog, so adding one is a registration
+   rather than an edit to the scene.
+
+2. **Register from `onMount`, deregister from `onCleanup`.** A factory left registered after
+   its dialog is gone can still be built, which produces a dialog nothing owns.
+
+3. **Open with `setDialog(id, onClose, data)`.** The caller's `onClose` is where the result
+   lands, so the code that opened the dialog is the code that reacts to it — not the dialog.
+
+4. **Every dialog reports its own close.** Wire the component's `onWasClosed` to
+   `closeDialog(params)` and pass a reason. The component reports the native close event;
+   the provider decides what that means.
+
+5. **Keep action completion idempotent.** `StandardDialog` and its ready-made variants
+   report `onWasClosed` once per presented lifetime. A button handler and the later close
+   notification can still both reach app completion; guard that shared action path.
+   Raw native nodes and the legacy `Dialog` may report duplicate native close events.
+
+6. **Branch on the reason, not on the button index.** `ButtonPressed` with a `buttonId`
+   is a choice; `DialogCancelled` is the viewer leaving. Treating "closed" as "confirmed"
+   is how a flow commits something nobody agreed to.
+
+7. **Chain steps with `openChildDialog`, and read the result from `_childCloseParams`.**
+   When a child closes, the provider re-opens the parent with the child's close params merged
+   into its data, so the parent resumes rather than restarts. `parentData` is how the fields
+   the viewer already changed survive the round trip.
+
+8. **Close a progress dialog from the signal that measures it, not from a timer.** An effect
+   watching the value reacts the moment it lands, so what is displayed and what triggers the
+   close cannot drift apart. A timer sized to "about how long it takes" will sometimes close
+   at 95%.
+
+9. **Clear intervals and timeouts in `onCleanup`.** A dialog can go away while its work is
+   still running, and a timer that outlives it writes to signals nothing is reading.
+
+## Example
+
+A provider small enough to read, one dialog, and the close reason coming back to the caller.
+`DialogProvider` and `useDialogs` here are app code — this is the shape to copy, not an
+import to add.
+
+```tsx rsg-skill=complete
+import { StandardDialog, StdDlgButton, StdDlgButtonArea, StdDlgTextItem, StdDlgTitleArea } from "@roku-sdk/components";
+import { Accessor, Component, createContext, createSignal, JSX, Show, useContext } from "@roku-sdk/solid";
+
+export enum CloseReason {
+    ButtonPressed = 0,
+    DialogCancelled = 1
+}
+
+export interface CloseParams {
+    reason: CloseReason;
+    buttonId?: string;
+}
+
+interface FlowApi {
+    current: Accessor<string | null>;
+    open: (id: string, onClose: (params: CloseParams) => void) => void;
+    close: (params: CloseParams) => void;
+}
+
+const FlowContext = createContext<FlowApi>();
+
+export const DialogProvider: Component<{ children: JSX.Element }> = props => {
+    const [current, setCurrent] = createSignal<string | null>(null);
+    let onClose: ((params: CloseParams) => void) | undefined;
+
+    const open = (id: string, handler: (params: CloseParams) => void) => {
+        onClose = handler;
+        setCurrent(id);
+    };
+
+    const close = (params: CloseParams) => {
+        const handler = onClose;
+        onClose = undefined;
+        setCurrent(null);
+        handler?.(params);
+    };
+
+    return <FlowContext.Provider value={{ current, open, close }}>{props.children}</FlowContext.Provider>;
+};
+
+export function useDialogs(): FlowApi {
+    const api = useContext(FlowContext);
+    if (!api) {
+        throw new Error("useDialogs called outside DialogProvider");
+    }
+    return api;
+}
+
+export function ConfirmDelete() {
+    const dialogs = useDialogs();
+
+    // The button and the subsequent close can both complete this app action.
+    let reported = false;
+    const report = (params: CloseParams) => {
+        if (reported) {
+            return;
+        }
+        reported = true;
+        dialogs.close(params);
+    };
+
+    return (
+        <Show when={dialogs.current() === "confirm-delete"}>
+            <StandardDialog
+                initialFocusId="keep"
+                onButtonSelected={index =>
+                    report({ reason: CloseReason.ButtonPressed, buttonId: index === 0 ? "keep" : "delete" })
+                }
+                onWasClosed={() => report({ reason: CloseReason.DialogCancelled })}
+            >
+                <stdDlgTitleArea primaryTitle="Delete recording?" />
+                <stdDlgButtonArea>
+                    <stdDlgButton id="keep" text="Keep" />
+                    <stdDlgButton text="Delete" />
+                </stdDlgButtonArea>
+            </StandardDialog>
+        </Show>
+    );
+}
+```
+
+The caller decides what a close means:
+
+```tsx
+import { CloseReason, useDialogs } from "./dialog-flow";
+
+const dialogs = useDialogs();
+
+dialogs.open("confirm-delete", params => {
+    if (params.reason === CloseReason.ButtonPressed && params.buttonId === "delete") {
+        void removeRecording();
+    }
+    // DialogCancelled: the viewer left. Do nothing.
+});
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Teardown runs twice and the second run undoes something | Both a button handler and its subsequent close complete the app action | Guard shared completion with a flag, as in the example |
+| A flow commits an action the viewer never chose | "The dialog closed" was read as "the viewer confirmed" | Branch on `DialogCloseReason` — only `ButtonPressed` is a choice |
+| A child dialog closes and the parent comes back empty | The parent was re-opened without its previous data | Pass `parentData` to `openChildDialog`; read the child's result out of `_childCloseParams` |
+| A wait indicator closes slightly before or after the work finishes | A timer was sized to the expected duration | Drive the close from the signal that measures progress |
+| A dialog is gone but its timer still fires | The interval outlived the component | `clearInterval` / `clearTimeout` in `onCleanup` |
+| The scene shows nothing though the provider says a dialog is current | The dialog's factory was never registered, or was deregistered early | Register in `onMount`, deregister in `onCleanup`, and render `getDialogElement()` |
+| A second dialog replaces the first instead of stacking on it | `setDialog` was used where a step was meant | `openChildDialog` pushes; `setDialog` replaces |
+
+Props for the components themselves are typed with TSDoc in `@roku-sdk/components`. Read a
+prop there rather than guessing it from here.

package/skills/effects/SKILL.md

@@ -0,0 +1,183 @@
+# Effects
+
+## Overview
+
+`Effect` from `@roku-sdk/components` restyles a `Rectangle` or a `Poster` on the GPU: rounded
+corners, a border, a linear or radial gradient. It draws nothing itself. You attach it through the
+consumer's `effect` prop, which holds a **reference** to the node rather than a child, so one
+effect can serve any number of consumers, and it restyles only its consumer — it clips nothing.
+Effects need Roku OS 16.0 or later and the OpenGL backend; anywhere else the prop is ignored
+without an error.
+
+## When to Use
+
+- rounded corners, a border or a gradient on a panel, a card, a button surface or a poster
+- the same look on several nodes, or a look that changes with focus
+- a border or a gradient that animates
+- corners that come out on one device and not another, or on some images and not others
+- a gradient or a padding value that is set and changes nothing
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Clipping or fading a group of children through an image | `MaskGroup` and its `maskUri`, in the `sdk-components` skill | An Effect restyles its consumer only; it never touches the subtree |
+| `createEffect`, or any other reactive primitive | The `solid-on-roku` skill | Same word, unrelated API |
+| A click or a chime | `SoundEffect` from `@roku-sdk/components`; no skill covers audio playback | It plays audio and draws nothing |
+| The focus ring on a FlexGrid's focused cell | `createFocusHighlightPlugin`, in the `flex-grid` skill | The grid draws its own focus chrome; an Effect can style what that plugin's `render` returns |
+| Rounded corners on Roku OS 15 or earlier, or in BrightScript | A 9-patch image on a `Poster` | The Effect node does not exist below OS 16 |
+
+## Quick Reference
+
+| Job | Write |
+|---|---|
+| Rounded corners | `const fx = <effect borderRadius={24} />;` then `effect={fx}` |
+| One radius per corner | `borderRadius={[topLeft, topRight, bottomRight, bottomLeft]}` |
+| A border | `borderWidth` and `borderColor`; it is drawn **outside** the consumer's rect |
+| A linear gradient | `gradientStyle="linear"`, `gradientColors` (two to eight), `gradientAngle` in **degrees** |
+| A radial gradient | `gradientStyle="radial"`, `gradientCentre` and `gradientRadius`, both normalised |
+| The same look on several nodes | Pass the one `const` to each consumer's `effect` |
+| A look that follows focus | One hoisted effect whose fields read the signal, or two hoisted effects and `effect={focused() ? on : off}` |
+| An animated field | An `id` on the effect, `{fx}` rendered in the tree, `fieldToInterp="<id>.<field>"` |
+| A Poster | Add `shaderCompatible` |
+| Whether this device draws effects | `getDeviceInfo()` from `@roku-sdk/rsg-ts/runtime` — step 5 |
+
+Colours are RGBA hex strings such as `"0xFF0000FF"`. The samples use the lowercase `<effect>`
+intrinsic, as the `sdk-components` skill recommends for new code; the capitalised `Effect`
+component is a pass-through for it, and every rule here holds for both spellings unchanged.
+
+## Instructions
+
+1. **Hoist every effect into a `const` and pass the identifier.** A signal read by an effect's own
+   fields updates that node in place, hoisted or inline. What rebuilds the node is a signal read by
+   the `effect={…}` expression itself — a ternary or a function call there builds a new effect node
+   on every change and discards the old one, and nothing looks wrong on screen. Hoist each look and
+   choose between the constants, and the expression can only ever pick an existing node. Prefer the
+   `const` to `createMemo`, which reaches the same result with more machinery.
+
+```tsx rsg-skill=no-check
+// Rebuilt on every focus change: the expression builds the node.
+<rectangle effect={focused() ? <effect borderWidth={6} /> : <effect borderWidth={0} />} />
+```
+
+2. **Share by passing the same `const`.** The consumer never parents a node it references, so one
+   effect on a `Rectangle` and a `Poster` at once is well defined. No helper and no imperative
+   setter is involved.
+
+3. **To animate a field, give the effect an `id` and also render it into the tree.**
+   `fieldToInterp` resolves its target through `findNode()`, which walks the scene tree, and a node
+   held only by reference has no parent — the animation starts and silently moves nothing.
+   Rendering `{fx}` as a sibling costs nothing, since an Effect is not drawn. Keep it in the same
+   scope as the `Animation`. A tuple `borderRadius` cannot be interpolated; animate a single number.
+
+```tsx
+import { Animation, FloatFieldInterpolator } from "@roku-sdk/components";
+
+const pulse = <effect id="tile-pulse" borderRadius={24} borderWidth={2} borderColor="0x9B59B6FF" />;
+
+<group>
+    {pulse}
+    <rectangle width={300} height={300} color="0x1A1A2EFF" effect={pulse} />
+    <Animation ref={animRef} duration={2} repeat={true} easeFunction="linear">
+        <FloatFieldInterpolator fieldToInterp="tile-pulse.borderWidth" key={[0, 0.5, 1]} keyValue={[2, 14, 2]} />
+    </Animation>
+</group>;
+```
+
+4. **Set `shaderCompatible` on every `Poster` that takes an effect.** It asks for the bitmap to be
+   decoded into a format shaders can use. Without it the effect may still apply, depending on how
+   each source image decodes — which is how corners stay square on a few images and not the rest.
+   A `Rectangle` needs nothing.
+
+5. **Gate on the platform when the unstyled look is not acceptable.** Below Roku OS 16, or on a
+   backend other than OpenGL, the prop is ignored with no error and the node type does not even
+   exist. Check with `getDeviceInfo()` from `@roku-sdk/rsg-ts/runtime`: it can return `null`, and
+   the test is `Number(info.osVersion.major) >= 16 && info.graphicsPlatform === "opengl"`. Answer it
+   once per app and keep the result, as the example does: each call builds a new object, and a grid
+   of tiles would otherwise ask once per tile. Asking again never changes the answer — the SDK keeps
+   whatever the first call returned, `null` included. The firmware's own `supported`
+   field on the Effect node cannot be read from TypeScript — it is set once when the node is
+   created, before any handler can observe it — so do not reach for it. Nor can this check see
+   effects switched off in the device's configuration.
+
+6. **An Effect clips nothing.** A child of a rounded `Rectangle` can paint into and past the
+   corners. Lay children out inside the rounded area; to clip them to a shape, use `MaskGroup`.
+
+7. **Know the fields that fail silently on device.** A gradient draws nothing while
+   `gradientStyle` is `"none"`, its default, or with fewer than two or more than eight
+   `gradientColors`. `gradientStops` needs one entry per colour in `[0, 1]`. In `__DEV__` builds
+   the SDK warns once per distinct problem (and stays quiet while `gradientStyle` is `"none"`,
+   including empty colors/stops). `borderPadding` is the gap between the border and the content,
+   so with `borderWidth` at `0` it changes nothing — inset a child with layout instead.
+   `gradientFillContent` defaults to `true` and
+   `gradientFillBorder` to `false`.
+
+8. **`setPropMethod("effect")` is not how you share.** It builds a property descriptor for
+   `registerImperativeMethods`, which gives every node of a tag an imperative method that sets
+   `effect` — the same call the prop makes. Reach for it only when *which* node a consumer points at
+   changes outside render and a reactive expression would be worse, such as moving one focus effect
+   between the cells of a large grid from a key handler. Register once per tag, before the first
+   node of that tag is created.
+
+## Example
+
+A tile whose frame follows focus, shared by its background and its artwork, with a plain outline
+on devices that do not draw effects:
+
+```tsx rsg-skill=complete
+import { getDeviceInfo } from "@roku-sdk/rsg-ts/runtime";
+import { Show } from "@roku-sdk/solid";
+
+let drawsEffects: boolean | undefined;
+
+function deviceDrawsEffects(): boolean {
+    if (drawsEffects === undefined) {
+        const info = getDeviceInfo();
+        drawsEffects = info !== null && Number(info.osVersion.major) >= 16 && info.graphicsPlatform === "opengl";
+    }
+    return drawsEffects;
+}
+
+export function Tile(props: { posterUri: string; focused: boolean }) {
+    const effectsOn = deviceDrawsEffects();
+
+    const idle = <effect borderRadius={24} />;
+    const ring = <effect borderRadius={24} borderWidth={6} borderColor="0xFFFFFFFF" />;
+
+    return (
+        <>
+            <Show when={!effectsOn && props.focused}>
+                <rectangle width={312} height={182} translation={[-6, -6]} color="0xFFFFFFFF" />
+            </Show>
+            <rectangle width={300} height={170} color="0x1A1A2EFF" effect={props.focused ? ring : idle} />
+            <poster
+                width={300}
+                height={170}
+                loadDisplayMode="scaleToZoom"
+                shaderCompatible
+                effect={props.focused ? ring : idle}
+                uri={props.posterUri}
+            />
+        </>
+    );
+}
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Moving focus or changing selection feels heavier, and nothing looks wrong | The `effect={…}` expression reads a signal and builds a new node on every change | Hoist each effect into a `const` and choose between the constants |
+| An `Animation` targeting an effect field starts and moves nothing | `findNode()` cannot see a node held only by reference | Give the effect an `id` and render `{fx}` next to the `Animation` |
+| Some Posters show the effect and a few stay square | Whether the bitmap decodes into a shader-usable format varies by image | Set `shaderCompatible` on every Poster that takes an effect |
+| Corners, borders and gradients show on one device and not on another, with no error | That device runs Roku OS 15 or earlier, or not OpenGL | Gate on `getDeviceInfo()` and give those devices a fallback look |
+| `gradientColors` is set and no gradient draws | `gradientStyle` is still `"none"`, or there are fewer than two colours | Set `gradientStyle` to `"linear"` or `"radial"` |
+| A child paints over the rounded corners | An Effect restyles its consumer and never clips | Keep the child inside the rounded area, or clip it with `MaskGroup` |
+| `borderPadding` has no visible effect | It only spaces a border from the content, and `borderWidth` is `0` | Inset the child with layout |
+| A tuple `borderRadius` will not animate | Per-corner radii are one Vector4 field, not a float | Animate a single-number `borderRadius` |
+
+## Source of truth
+
+Prefer the typed source over any prose, including this file: read
+`node_modules/@roku-sdk/components/src/sg-nodes/effect.props.ts` for every field, its type and its
+default. The same wiring runs in the **Effect** entry of the SDK's showcase example.