@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills/fetch-and-data-loading/SKILL.md

@@ -0,0 +1,164 @@
+# Loading data over the network
+
+## Overview
+
+Requests in an RSG app go through a `fetch` the firmware provides. It looks like the web's and
+differs in three ways that all fail quietly: it takes **one argument**, an error status
+**resolves** rather than rejecting, and the types your editor shows you are the browser's
+rather than this platform's.
+
+That last one is the root of the other two showing up late. `fetch` is declared in no ambient
+file the compiler reads, so TypeScript falls through to its default DOM library — which means
+the unsupported two-argument call **compiles cleanly and fails at runtime**.
+
+**Reaching a host behind your own certificate authority is in
+`references/https-and-certificates.md`.** Read it when a request works against production and
+fails against staging. The tables below name the option; that file has where the bundle lives,
+how to make it the default for every request, and why a trust failure surfaces in a different
+place from an HTTP error.
+
+## When to Use
+
+| If the request is | Then |
+|---|---|
+| Calling an HTTP API from an RSG app | Here |
+| A POST or PUT with headers and a body | Here — and not the way the web writes it |
+| An error status that never reached your error handling | Here — `fetch` resolved |
+| Which type describes a response, when the editor says `Response` | Here |
+| A host whose certificate this box does not trust | `references/https-and-certificates.md` |
+| Whether aborting or streaming is available on this firmware | Here — ask at runtime |
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Filling a virtualized shelf's rows as the viewer approaches them | The `flex-grid` skill | That grid owns *when* a row is fetched. This skill owns the call it makes |
+| Feeding a SceneGraph-native list its items, or telling which components take data that way | The `sdk-components` skill | Recognising a `content`-fed node is a component question, not a transport one |
+| Which packages the app must declare, or where a file has to live to be imported | The `project-setup` skill | The scaffold already covers what this skill needs |
+| Reading what Roku itself holds about the viewer, or selling something in-channel | The `user-accounts-and-purchases` skill | That goes through a component and a command, not through HTTP |
+| Getting logs or a crash off a device | The `cli-dev-loop` or `mcp-ai-dev-loop` skill | Those are about observing the app, not about what it requests |
+
+## Quick Reference
+
+| Want | Do |
+|---|---|
+| A GET | `fetch(url)` — one argument |
+| Anything with a method, headers or a body | Build a `Request` and pass that: `fetch(new Request(url, init))` |
+| The parsed body | `await response.json()`, then assert your own shape |
+| Raw text | `await response.text()` |
+| To know an error status happened | Check `response.ok`. **The promise already resolved** |
+| A custom CA | `certificatesFile` on an `HttpsAgent` — see the reference |
+| To know if abort or streaming works here | `fetch.isFeatureSupported(...)` with a `FetchFeature` member |
+
+Where things come from:
+
+| | |
+|---|---|
+| `fetch` | A firmware global. Imported from nothing, declared in no ambient file — which is why the editor shows the DOM's |
+| `Request`, `Headers`, `HttpsAgent` | Globals too, but **installed by `@roku-sdk/native`**, which the scaffold already depends on |
+| `ResponseInstance`, `RequestInit`, `HttpsAgentOptions`, `FetchFeature` | Types, from `@roku-sdk/interfaces` |
+
+## Instructions
+
+1. **Pass one argument.** `fetch(url)` or `fetch(request)`. The two-argument form is the web's,
+   it typechecks here because the compiler is reading the DOM library, and the second argument
+   is ignored at runtime — so a POST silently becomes a GET.
+
+2. **Put method, headers and body on a `Request`.** That is where `RequestInit` belongs, and
+   `body` is typed **`string` only** — no form data, no object, no stream. Serialize first.
+
+3. **Check `ok` before reading the body.** A 4xx or 5xx is a *resolved* response, so error
+   handling written as a `catch` never sees it. Only a transport failure rejects.
+
+4. **Do not expect the response type your editor shows.** What a call really resolves to is
+   `ResponseInstance` from `@roku-sdk/interfaces`. Against the DOM types the compiler applies,
+   `await response.json()` comes back loose, so assert your own interface on it rather than
+   reaching for a generic that will not compile.
+
+5. **Ask before relying on an optional capability.** `fetch.isFeatureSupported(...)` answers for
+   `FetchFeature.STREAMING`, `ABORT_CONTROLLER` and `REQUEST_INIT`. A `false` is a branch to
+   write, not a failure to report.
+
+6. **Load from `onMount`, and let a signal carry the state.** Nothing about the request is
+   reactive on its own, so the pattern is: fire it on mount, write the result into a signal, and
+   render off that signal's three states — not yet, failed, arrived.
+
+7. **Do not switch a base URL on a build variable.** Those are compiled away, and a request to
+   the wrong environment is the one bug that looks like a server problem. Read the environment
+   from configuration the app can actually see at runtime.
+
+## Example
+
+A GET whose result drives the view, a POST built the way this runtime wants, and the `ok` check
+in the place it belongs.
+
+```tsx rsg-skill=complete
+import { Component, createSignal, onMount } from "@roku-sdk/solid";
+
+interface Title {
+    id: string;
+    name: string;
+}
+
+export const Shelf: Component<{ endpoint: string }> = props => {
+    const [titles, setTitles] = createSignal<Title[] | undefined>(undefined);
+    const [failed, setFailed] = createSignal(false);
+
+    const load = async () => {
+        try {
+            // One argument. A second one would compile and be ignored.
+            const response = await fetch(`${props.endpoint}/titles`);
+
+            // Already resolved, even on 404 — so this check is the error handling.
+            if (!response.ok) {
+                setFailed(true);
+                return;
+            }
+
+            // The compiler is using the DOM's Response here, so assert the shape.
+            const body = (await response.json()) as { titles: Title[] };
+            setTitles(body.titles);
+        } catch {
+            // Only a transport or trust failure lands here.
+            setFailed(true);
+        }
+    };
+
+    onMount(() => void load());
+
+    return (
+        <group>
+            <label text={failed() ? "could not load" : titles() === undefined ? "loading" : ""} />
+            <label text={(titles() ?? []).map(t => t.name).join(", ")} translation={[0, 48]} />
+        </group>
+    );
+};
+```
+
+A POST carries its method, headers and body on a `Request`, and the body is a string:
+
+```tsx
+const request = new Request(`${endpoint}/progress`, {
+    method: "POST",
+    headers: new Headers({ "Content-Type": "application/json" }),
+    body: JSON.stringify({ titleId, seconds })
+});
+
+const response = await fetch(request);
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| A POST arrives at the server as a GET with no body | The web's two-argument `fetch` — it compiled, and the second argument was ignored | Build a `Request` and pass that as the single argument |
+| A 404 or 500 never reaches the error path | The promise resolved; only a transport failure rejects | Check `response.ok` before reading the body |
+| A generic on the body parse will not compile | That generic is on this platform's response type, and the compiler is applying the DOM's | `await response.json()` and assert your own interface |
+| Sending an object or form data as `body` fails | `body` is typed `string` | Serialize it yourself |
+| `Request` resolves in the editor with no import, and it feels like a mistake | It is a global that `@roku-sdk/native` installs | Nothing to import for the value; take the *types* from `@roku-sdk/interfaces` |
+| Aborting silently does nothing on an older box | Abort support is optional on this platform | Gate it on `fetch.isFeatureSupported(FetchFeature.ABORT_CONTROLLER)` |
+| Requests work in production and fail against staging | The staging certificate is not in the platform trust store | `references/https-and-certificates.md` |
+| The app talks to the wrong environment in a release build | The base URL was chosen from a build variable, which the build removed | Read it from runtime configuration |
+
+Request and response types are documented with TSDoc in `@roku-sdk/interfaces`. Read a field's
+exact shape there rather than assuming the browser's.

package/skills/fetch-and-data-loading/references/https-and-certificates.md

@@ -0,0 +1,79 @@
+# Reaching a host behind your own certificate authority
+
+The body says *which* option points a request at a CA bundle. This file is the shape of it:
+where the bundle has to live, how to make it the default for every request instead of one, and
+what the failure looks like when it is missing.
+
+## The two scopes
+
+`HttpsAgent` is a constructor, and the agent it produces can be attached in two ways.
+
+**Per request.** Build the agent, put it on the request's `agent` field, and only that request
+uses it. Right for a single staging host while everything else keeps the platform trust store.
+
+**For the whole app.** `HttpsAgent.setGlobalAgent(agent)` installs it as the default, so every
+later call uses it without naming it. Right when every host the app talks to sits behind the
+same internal authority — which is the case that otherwise ends up copy-pasting an `agent`
+onto two dozen call sites and missing one.
+
+`setGlobalAgent` is a static on the constructor, not a method on an instance, and it takes the
+instance you built:
+
+```tsx
+const agent = new HttpsAgent({ certificatesFile: "pkg:/certs/internal-ca.crt" });
+HttpsAgent.setGlobalAgent(agent);
+```
+
+Install it once, before anything fetches — `main()` or the app's bootstrap, not inside a
+component that may mount twice.
+
+## Where the bundle lives
+
+`certificatesFile` is a URI the firmware reads, not a path the bundler resolves, so it is a
+`pkg:/` location and the file has to be inside the package. That makes it one of the few places
+in an RSG app where a hardcoded `pkg:/` URI is correct: the image-import rule exists because
+the build pipeline rewrites image paths, and it does not process a certificate bundle.
+
+Keep it under the app's `pkg/` directory so it ships, and remember that anything there is
+readable by anyone who unpacks the app — a CA bundle is public by nature, but a client
+certificate with a private key is not, and does not belong in a package.
+
+## Which type describes the options
+
+`HttpsAgentOptions` is `{ certificatesFile?: string }` and is exported from
+`@roku-sdk/interfaces`. Note that it is the *only* field: there is no verification-disabling
+switch here, and no per-host override. If a host fails to verify, the answer is the right
+bundle, not a way around the check.
+
+## What the failure looks like
+
+A missing or wrong bundle does not produce a distinct error class. The call rejects the way a
+transport failure rejects, because from the runtime's point of view the connection never
+completed — so it reaches a `catch`, not the `ok` check the body describes for HTTP statuses.
+
+That distinction is worth holding onto, because the two failures need opposite fixes:
+
+| What happened | Where it surfaces | Fix |
+|---|---|---|
+| The certificate could not be verified | The promise rejects, so a `catch` | Attach the CA bundle |
+| The server answered with 4xx or 5xx | The promise **resolves**; only `ok` is false | Read the status and handle it |
+
+So a request that works against production and rejects against staging is usually a trust
+problem rather than a server problem, and a request that "fails" with a body you can read is
+the opposite.
+
+## Checking the capability first
+
+Aborting a request mid-flight is optional on this platform. Ask before relying on it rather
+than discovering it on an older box:
+
+```tsx
+import { FetchFeature } from "@roku-sdk/interfaces";
+
+if (fetch.isFeatureSupported(FetchFeature.ABORT_CONTROLLER)) {
+    // safe to wire an AbortController to this request
+}
+```
+
+The same question answers for `FetchFeature.STREAMING` and `FetchFeature.REQUEST_INIT`. A
+`false` here is not an error to report — it is a branch to write.

package/skills/flex-grid/SKILL.md

@@ -0,0 +1,236 @@
+# FlexGrid
+
+## Overview
+
+`@roku-sdk/flex-grid` renders the shelves and poster grids a Roku app is mostly made of, at a
+size a device can hold: cells come from a recycled pool, only the rows near the viewport exist,
+and rows may be loaded page by page while the user is already moving. You describe the geometry
+and the cell component; the grid owns scrolling, focus movement inside itself, and the focus
+highlight.
+
+Every sample here is written against the **3.x line**. 2.x is maintained in parallel and differs in
+the plugin surface and in how a cell takes focus, so read the installed package's major before
+copying one — `BREAKING_CHANGES.md` in the install carries the 2.x-to-3.x table.
+
+## Read the reference first for these tasks
+
+| If the request is | Read now, before answering |
+|---|---|
+| A grid inside another grid's cell, or a grid handing focus to a sibling region at its edge | `references/focus-integration.md` |
+| The focus highlight, zoom, row titles, or any other plugin | `references/plugins.md` |
+
+The tables below name the callback or the factory and stop there: the arguments, the return
+contract that decides whether a key bubbles, and the subpath each plugin is imported from are
+only in the references. Answer these two from the reference and quote it — an answer assembled
+from a table row here is an invented API, and this package has several names that look right
+and do not exist.
+
+## When to Use
+
+- a row of cards, a shelf-of-shelves screen, or a poster grid that scrolls
+- rows whose data arrives after the screen is up, page by page
+- per-row geometry: different cell widths, heights or column counts per row
+- a grid that has to give focus back to a nav bar or menu at its edge
+- a second grid inside a cell of the first one
+- cells that must not all exist at once, because there are hundreds of them
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| A menu, settings list or short row of buttons | `FocusBoundary` + `useFocusable` from `@roku-sdk/navigation` | Nothing to virtualize, and the grid's geometry config costs more than the screen needs |
+| A full-screen image carousel | `@roku-sdk/slideshow` | It owns the transition and the one-item-at-a-time model the grid has no notion of |
+| The network call that fills a row — its method, headers, error status or a host this box does not trust | The `fetch-and-data-loading` skill | This skill owns *when* a row is fetched, which is the focus-driven half. What the request itself looks like is not a grid concern |
+| A `RowList`, `MarkupGrid` or another list that takes `itemComponentName` | The `sdk-components` skill names them | Those are SceneGraph-native lists exported by `@roku-sdk/components`. They render each item from compiled BrightScript XML, so a TypeScript component cannot be their item — which is the reason this renderer exists rather than wrapping them |
+
+## Quick Reference
+
+| Operation | API |
+|---|---|
+| Declare the packages (the scaffold ships neither) | `@roku-sdk/flex-grid`, plus `@roku-sdk/navigation` for a top-level grid, in the app's `dependencies` |
+| A grid in JSX | `defineFlexGrid<T>()` at module scope, rendered with the config as props |
+| A grid built imperatively | `createFlexGrid<T>(config)`, then render `handle.element` |
+| Reach the live grid from app code | `gridHandleRef={setGrid}` in JSX, or the `createFlexGrid` return value |
+| Required config | `numRows`, `numCols`, `cellSize`, `focus` (both axes), `getCellComponent` |
+| Where a row moves on screen | `focus.horizontal` / `focus.vertical`: `fixedFocusStrategy`, `floatingFocusStrategy`, `floatingFocusYStrategy`, `fixedFocusWrapStrategy` |
+| Feed rows as they load | `rows` (accessor) in JSX, or `handle.updateRows(startRow, rows)`; `undefined` is a row not loaded yet |
+| React to focus moving | `onFocusChanged(row, col, item)` — the prefetch hook |
+| Act on OK | `onItemSelected(row, col, item)`, returning `true` to consume it |
+| Focus this grid as a region | `focusId` — an identity the enclosing boundary's `initialFocus` or `setFocus` names |
+| Hand focus on at an edge | `onEdgeReached(edge)` — `edge` is `"top"`, `"bottom"`, `"left"` or `"right"`, and it returns nothing → `references/focus-integration.md` |
+| Send a key into a nested grid | `handle.forwardKeyEvent` → `references/focus-integration.md` |
+| Clip to a viewport | `enableClipping: true` with `width` and `height`, which the type then requires |
+| Clip one row's cards to a rect | `createRowCardsClipPlugin` from `@roku-sdk/flex-grid/row-clip` — in row coordinates and fixed within the row, so cards scroll through it; row chrome stays outside |
+| One backdrop behind several rows | `createRowBackdropPlugin` → `references/plugins.md` |
+| Jump somewhere | `jumpTo: [row, col]`, or `handle.jumpTo(row, col, animate)` for an unconditional repeat |
+| A row refilled with unrelated items starts at its first item | `handle.resetRowPosition(row)` beside the update — `updateRows` keeps the row's saved column and scroll |
+
+## Instructions
+
+1. **Declare the dependencies first.** `rk create` scaffolds neither `@roku-sdk/flex-grid` nor
+   `@roku-sdk/navigation` — which a top-level grid also needs, for the `RootFocusBoundary` it
+   registers under — and pnpm does not hoist, so until both are in the app's `dependencies`
+   the imports do not resolve and nothing below compiles. Give them whatever range the app's
+   other `@roku-sdk/*` packages already carry — the published version for an app installing
+   from the registry, `workspace:*` only inside the SDK's own pnpm workspace, where that
+   protocol resolves. Then run `rk build` once: until a build has generated this package's XML
+   type declarations, bare `tsc` reports errors inside the SDK's own files, so the build is the
+   type gate, not `type-check`.
+
+2. **Create the grid inside the root `FocusBoundary`'s owner.** A top-level grid *is* a nested
+   boundary: it reads the boundary context when its JSX is created. Built outside — in the
+   anchor node's body, or in a module-level factory — it becomes a second root, registers with
+   nobody, and every key is dropped while the screen looks correct. A scaffolded app has no
+   boundary at all: its anchor node still `extends: "Group"`, so wire that first — skill
+   `roku-sdk-focus-management`, Instruction 1 — and render the grid under it.
+
+3. **Give both axes a focus strategy.** `focus` is required and has no default. `fixed` keeps
+   the focused cell at one position and scrolls the content past it; `floating` moves the
+   highlight until it reaches the offset and scrolls after that.
+
+4. **Write the cell as a component over `CellRenderProps<T>`.** Read `focused()` inside JSX,
+   size from `width` / `height`, and treat `item` as possibly `undefined` — that is a row whose
+   data has not arrived, not an error.
+
+5. **Return the cell component from `getCellComponent` by identity, not by a fresh closure.**
+   Structural props are a remount dependency: a new function on every parent render rebuilds
+   the grid, which drops focus and re-warms the pool.
+
+6. **Load rows behind `onFocusChanged`.** Set `numRows` to what the dataset will hold, pass
+   `undefined` for rows you have not fetched, and fill them in as focus approaches.
+
+7. **Pass `focusId` only for a top-level grid.** Omitting it is what selects nested mode, where
+   the parent cell forwards keys instead — see the reference before writing either.
+
+## Example
+
+A top-level shelf grid: pooled cells, rows filled in as focus moves, a viewport to scroll
+inside, and the grid registered as a focus region under the screen's boundary.
+
+```tsx rsg-skill=complete
+import { Group, Label, Rectangle } from "@roku-sdk/components";
+import type { CellRenderProps } from "@roku-sdk/flex-grid";
+import { defineFlexGrid, fixedFocusStrategy, floatingFocusYStrategy } from "@roku-sdk/flex-grid";
+import { type Component, createSignal } from "@roku-sdk/solid";
+
+interface Card {
+    title: string;
+}
+
+const CELL_SIZE: [number, number] = [280, 158];
+const TOTAL_ROWS = 40;
+const COLUMNS = 6;
+
+// Module scope: the component identity has to be stable, because the grid
+// remounts when a structural prop changes identity.
+const Shelf = defineFlexGrid<Card>();
+
+const CardCell: Component<CellRenderProps<Card>> = props => (
+    <group>
+        <rectangle
+            width={props.width}
+            height={props.height}
+            color={props.focused() ? "0x0055FFFF" : "0x1A1A1AFF"}
+        />
+        <label text={props.item?.title ?? "…"} translation={[16, 120]} />
+    </group>
+);
+
+function cardCellComponent(): Component<CellRenderProps<Card>> {
+    return CardCell;
+}
+
+async function fetchRow(row: number): Promise<Card[]> {
+    // The app's own paging call.
+    return [{ title: `Row ${row}` }];
+}
+
+/**
+ * Rendered inside the screen's `RootFocusBoundary`, whose `initialFocus` names
+ * the same `focusId` this receives.
+ */
+export const PosterShelves: Component<{ focusId: object }> = props => {
+    const [rows, setRows] = createSignal<(Card[] | undefined)[]>(Array.from({ length: TOTAL_ROWS }));
+
+    const loadRow = (row: number): void => {
+        if (rows()[row] !== undefined) return;
+        void fetchRow(row).then(items =>
+            setRows(previous => {
+                const next = [...previous];
+                next[row] = items;
+                return next;
+            })
+        );
+    };
+
+    return (
+        <Shelf
+            focusId={props.focusId}
+            numRows={TOTAL_ROWS}
+            numCols={COLUMNS}
+            cellSize={CELL_SIZE}
+            cellSpacing={[24, 32]}
+            translation={[80, 240]}
+            // Without a viewport the scrolled rows paint over whatever is above
+            // the grid; `enableClipping` is the union arm that requires both sizes.
+            enableClipping={true}
+            width={1760}
+            height={840}
+            focus={{
+                horizontal: { strategy: fixedFocusStrategy, options: { focusOffset: 80 } },
+                vertical: { strategy: floatingFocusYStrategy, options: { focusOffset: 0 } }
+            }}
+            getCellComponent={cardCellComponent}
+            rows={rows}
+            onFocusChanged={row => loadRow(row)}
+            onItemSelected={(row, col, item) => {
+                if (item === undefined) return false;
+                openTitle(item);
+                return true;
+            }}
+        />
+    );
+};
+
+function openTitle(card: Card): void {
+    // app logic for the selected card
+}
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The grid draws but no key reaches it, and the root boundary's `initialFocus` never resolves | The grid was created outside the root boundary's owner, so it became a second root | Create it in a component rendered inside the boundary |
+| `Module '"@roku-sdk/flex-grid"' has no exported member 'Position'` (or `'PositionValue'`) | Both names arrived in 2.15.0; an older install types the edge argument as the bare literal union and exports neither | Compare `edge` against `"top"`, `"bottom"`, `"left"` and `"right"`. The enum's members hold those same strings, so the literal form compiles and matches on every version |
+| `Property 'setFocusBoundary' does not exist on type 'CellRenderProps<T>'`, or `declineUnhandledNavigation` rejected in the config | Both are 3.x additions later than 3.0.0, and an install predating them has neither | Give a composite cell its keys through `setKeyDelegate`, which every version has, and expect a nested grid there to claim movement keys rather than decline them → `references/focus-integration.md` |
+| Returning `true` from the edge callback changes nothing | `onEdgeReached` returns `void`: it reports, it does not consume | Move focus in the handler and expect no consume semantics |
+| `Property 'focusRef' does not exist` | The prop is `focusId`; `focusRef` appears in older prose and never existed | Use `focusId` |
+| The highlight config's fields are rejected | Two types share the name `FocusHighlightConfig`, and the main barrel's one is dead | Import it from `@roku-sdk/flex-grid/focus-highlight` |
+| Scrolled rows paint over the header, the nav bar, or the screen's edge | The grid has no viewport until one is asked for, so its rows draw outside its box | `enableClipping: true` with `width` and `height`; nothing but a screenshot catches this — the build and the tests both pass |
+| `width`/`height` suddenly required | `enableClipping: true` is a discriminated union arm that needs a viewport | Pass both, or drop the clipping |
+| A translated grid renders blank: the cells exist and hold their data, but nothing is inside the clip rect | `height` is the size of the grid's box, measured from its own origin, not a bottom edge on the screen. Versions before this fix read it both ways and gave a grid offset further down the screen than it was tall a negative viewport, scrolling every row above its own rect | Size the band itself and let `translation` place it: a 200-tall row at y=220 is `translation: [70, 220], height: 200`. Omitting `height` runs the grid to the bottom of the screen. A custom vertical strategy reading `viewportHeight` as a bottom edge has the same bug — the room below the focus line is `viewportTop + viewportHeight - focusOffset` |
+| A card shows where something opaque is drawn over the row — in the gap beside a panel, or past the end of the row | Nothing clips the row there. Hiding the card is the usual stand-in and it is not the same thing: it removes the card mid-slide, so the slot it was heading for fills by appearing instead of gliding in | `createRowCardsClipPlugin({ clip: row => [x, y, w, h] })` from `@roku-sdk/flex-grid/row-clip`, answering `undefined` for every other row. The rect is in the row's own coordinates and does not move with the row's horizontal scroll, so cards are cut at its edges and their motion is untouched — run it well past every edge nothing covers, or a focus ring or zoomed card is cut there too; row chrome stays outside, so a title beyond the rect still draws. Where the rect goes depends on where that row puts its cards in each of its states, which is worth measuring rather than assuming |
+| A clipped row renders blank, or loses its first cards | The rect is returned in a state where the opaque thing it hides behind is not drawn — most often the row is no longer focused, which in the same stroke usually undoes whatever spread the cards out. The cut then has nothing over it | Gate `clip` on exactly what draws the covering element, and answer `undefined` in every other state. Clipping a row unconditionally looks right until that row is not the focused one |
+| A band meant to sit behind two rows draws over part of one of them, or breaks at the seam between them | It was drawn as one row's `registerRowChrome(…, "back")` reaching past that row. Row chrome belongs to its own row | `createRowBackdropPlugin` from `@roku-sdk/flex-grid/row-backdrop`, one region over the rows → `references/plugins.md` |
+| A `layer: "back"` focus highlight disappears behind a row backdrop | `createRowBackdropPlugin` comes after `createFocusHighlightPlugin` in `plugins`, and the back layer draws in that order | List the backdrop plugin first |
+| Backdrop art squashes while the bob opens inside the band | A `size.fill` poster takes the region's height, which grows with the gap | `loadDisplayMode="scaleToZoom"` on the poster; place content that must not stretch against `size.height()` |
+| Focus resets and the grid flashes on unrelated state changes | A structural prop — `getCellComponent`, `plugins`, an options object — arrives as a new value each render | Hoist it, or keep it in a memo |
+| Every cell looks unfocused, or the wrong one is highlighted | `focused` was read at the top of the cell instead of inside JSX, or `props` was destructured | Call `props.focused()` in the JSX that depends on it |
+| A key the app wanted never arrives, though the grid handles the arrows | The grid claims seven keys, not five: the four movement keys, `OK`, `fastforward` and `rewind` | Name the extra ones in `handleAdditionalKeyEvents` and handle them where the reference shows. That list is filtered against the seven the grid already claims, so listing `fastforward` or `rewind` there is silently dropped rather than rejected |
+| `up` on the first row does nothing, and the boundary's `onUnhandledKey` never fires for it | The grid claimed that key and consumes it even though it moved nothing, so it never reaches the boundary the hand-off was written on | Move the hand-off to the grid's `onEdgeReached`, per `references/focus-integration.md`. `declineUnhandledNavigation: true` makes claimed keys that moved nothing bubble instead, which is how a nested grid escapes its own edges — reach for it there, not to rescue a top-level hand-off |
+| `tsc` reports `Property 'floatTween' does not exist on JSX.IntrinsicElements`, inside the SDK's files rather than yours | Those intrinsics come from XML type declarations that only `rk build` / `rk dev` generate, and a fresh install has none | Build once, then re-run. The build's own type check is the authoritative gate; bare `tsc` on a never-built app is not |
+| The device log floods with `Could not update the interpolator field ""` | By design: the grid creates its interpolators with an empty `fieldToInterp` and patches the target in from BrightScript | Ignore them, and search the log for the real error rather than reading it in order |
+
+`FlexGridConfig`, `FlexGridHandle` and `CellRenderProps` are typed with TSDoc in the installed
+package — read a field there rather than guessing its name, and prefer it over any prose,
+including this file, when the two disagree. The package ships raw TypeScript (`main` is
+`src/index.ts`), so read `node_modules/@roku-sdk/flex-grid/src/`: the config and the handle are
+in `flex-grid-base.tsx`, the cell props in `types.ts`. There are no `dist/*.d.ts` to consult.
+
+## Tween ownership
+
+Import `Tween` and `TweenProps` from `@roku-sdk/components`, not `@roku-sdk/flex-grid`.
+The grid export is deprecated and retained for one minor release. The lowercase `<tween>`
+intrinsic is declared by `@roku-sdk/components/jsx` and uses the native field contract.
+See the Tween value-shape contract in `documentation/core-concepts/tween.md` in the SDK source tree.