@roku-sdk/ai 0.0.0-stage → 2.18.0

package/skills/focus-management/SKILL.md

@@ -0,0 +1,205 @@
+# Focus Management
+
+## Overview
+
+D-pad focus in an RSG SDK TypeScript app is virtual: one SceneGraph node holds real focus
+for the whole screen, and which item is focused inside it is a SolidJS signal, so moving
+focus is a signal write rather than a SceneGraph call. `FocusBoundary` owns that state and
+`useFocusable` registers the items that can hold it, both from `@roku-sdk/navigation`.
+
+## Read the recipe first for two of these tasks
+
+| If the request is | Read now, before answering |
+|---|---|
+| A dialog or overlay that holds focus while open and gives it back on close | `references/focus-recipes.md` → *Hold focus inside a dialog, and give it back* |
+| Focus moving between regions on a key the layout does not already carry | `references/focus-recipes.md` → *Hand focus between regions of a screen* |
+
+The tables below name the API for both, and stop there: the props you pass it, and where the
+call has to sit for it to work at all, are only in the recipe. An answer assembled from a table
+row is an invented one — so read the recipe and quote it, and never hand the pointer to the
+user in place of an answer.
+
+## When to Use
+
+Use this whenever the question is which item is focused, or what a key press does to it:
+
+- a menu, row, list or grid that has to respond to the D-pad
+- highlighting the focused item and dimming the rest
+- an OK press that must act on the focused item
+- handing focus between regions of a screen
+- focus that starts on the wrong item, will not move, or is lost when the data changes
+- an item that must be skipped while it is disabled
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| An overlay you draw yourself out of ordinary nodes | `ModalBoundary` + `useModal` from `@roku-sdk/components`, wired from `references/focus-recipes.md` | It already implements enter on open, dismiss on `back`, and restore on close |
+| A `StandardDialog` | The `sdk-components` skill for what it is made of; nothing here for its focus | It renders a native SceneGraph modal, so focus enters and returns on its own. Point `initialFocusId` at the first button and leave `focusActive` alone — an enclosing `FocusBoundary` deactivates itself while it is up |
+| A region a `FlexGrid` owns — its edges, its cells, its keys | `@roku-sdk/flex-grid`'s own `onEdgeReached` | The grid claims seven keys from the boundary — up, down, left, right, `OK`, `fastforward` and `rewind` — and by default consumes them whether or not they moved anything, so `onUnhandledKey` never sees one and a hand-off written there is dead code. `declineUnhandledNavigation: true` on the grid is the exception: claimed keys that moved nothing then do bubble |
+| BrightScript component interop: `nextFocusUp`, `onFocusedChild`, focus driven on the render thread | `FocusableGroup` / `Focusable` | Those need real SceneGraph focus. It is a legacy path — do not start new work there |
+| Imperative key routing the user asked for by name, or that is already in the file | `KeyHandler` | Every key costs a BrightScript round trip and movement logic ends up per component |
+| Opening and closing a dialog from elsewhere in the app, telling a viewer's choice from a dismissal, or chaining several dialogs | The `dialogs-and-modals` skill | Holding focus while an overlay is up is this skill's job; deciding which overlay is up and what its close means is not |
+| Moving between whole screens | The `screen-navigation` skill | Screen routing is not a focus concern; focus work starts once the screen is up |
+
+## Quick Reference
+
+| Operation | API |
+|---|---|
+| Wire a screen for focus | `RootFocusBoundary` with `keyEvent`, `focusActive` and `setHandledKeys`, on an anchor node extending `FocusBoundaryBase` |
+| Make an item focusable | `useFocusable()`, then attach the returned `ref` and read `isFocused()` |
+| Act on OK on the focused item | `onKey: { OK: onPress(() => …) }` in `useFocusable` |
+| Name a key without memorising its runtime string | `RemoteKey` from `@roku-sdk/interfaces` — `onKey: { [RemoteKey.Select]: … }`. Four members read differently from the string they carry: `Select` is `"OK"`, `Fwd` is `"fastforward"`, `Rev` is `"rewind"`, `Info` is `"options"`. Bare strings stay valid |
+| Move on up/down, left/right, or all four | `navigation="vertical"`, `"horizontal"`, `"grid"` on the boundary |
+| Route movement in an irregular layout | `navigationMap`: a `Map` from each identity to its neighbour per direction |
+| Add a second region to a screen | A nested `FocusBoundary` with a `focusId` that the parent's `initialFocus` names |
+| Skip an item while it is disabled | `canReceiveFocus: () => !disabled()` |
+| Move focus from app logic | `useFocusActions()` → `setFocus(id)`; `focusedId()` to read it |
+| Act on a key nobody handled, such as `back` | `onUnhandledKey` on the boundary |
+| Reopen a region at its first item | `rememberLastFocus={false}` — the default `true` restores the last item |
+| Mark the item an inactive region will return to — dialog open, or focus in another region | `hasFootprint()` from `useFocusable` |
+
+## Instructions
+
+`@roku-sdk/navigation` is not in the set `rk create` installs. Add it to the app's own
+`package.json` first — `workspace:*` inside the SDK's pnpm workspace, otherwise the version the
+app's other `@roku-sdk/*` packages are on — or every import below fails to resolve.
+
+1. **Wire the screen once.** Give the screen's anchor node `extends: "FocusBoundaryBase"`,
+   `keyEvent` and `focusActive` as input fields and `handledKeys` as an output field, then
+   pass all three to `RootFocusBoundary`. Without this no key reaches TypeScript and nothing
+   moves. One per anchor node — never give a nested boundary its own `keyEvent`.
+
+2. **Wrap each region in a `FocusBoundary`** and set `navigation` to the axis the region
+   moves on. Nest a region by giving it a `focusId` that its parent's `initialFocus` or
+   `navigationMap` names.
+
+3. **Point `initialFocus` at something registered in that same boundary** — a child's
+   `useFocusable({ focusId })` identity, or a nested boundary's `focusId`. An identity
+   registered one level further down never matches, and focus starts nowhere.
+
+4. **Call `useFocusable()` in every item that can hold focus**, attach the returned `ref` to
+   the item's root node, and put the item's own keys in `onKey`. Use `onPress` / `onRelease`
+   to fire on one edge instead of guarding `press` by hand.
+
+5. **Leave directional keys to the boundary.** A leaf handles OK and its own keys; up, down,
+   left and right are the boundary's job, so do not add them to a leaf's `onKey`.
+
+6. **Read `isFocused()` inside JSX** or another reactive scope, and never destructure
+   `props`. Reading either once at the top of a component captures a value that never
+   updates again.
+
+7. **Iterate with `<For>`**, never `items.map()`. `map` recreates every child when the array
+   changes, which unregisters the focused item and drops focus.
+
+8. **Create a `focusId` only when something names it** — `initialFocus`, a `navigationMap`
+   entry, `setFocus`, a `focusedId()` comparison, or a `FlexGrid` `focusId`. Every other
+   item gets one automatically, and linear navigation follows registration order.
+
+## Example
+
+A screen wired end to end: the anchor node, one vertical region, three rows, per-row OK
+handling, and focus styling driven by `isFocused()`.
+
+```tsx rsg-skill=complete
+import { Group, Label, Rectangle } from "@roku-sdk/components";
+import { FocusBoundary, onPress, RootFocusBoundary, useFocusable } from "@roku-sdk/navigation";
+import { type AnchorNodeImplementation, defineAnchorNode, FieldType } from "@roku-sdk/rsg-ts";
+import { For } from "@roku-sdk/solid";
+
+const MainSceneDescription = {
+    componentName: "MainScene",
+    extends: "FocusBoundaryBase" as const,
+    inputFields: {
+        keyEvent: FieldType.Object(),
+        focusActive: FieldType.Boolean(true)
+    },
+    outputFields: {
+        handledKeys: FieldType.Object(),
+        exitApp: FieldType.Boolean()
+    }
+};
+
+// Two identities this screen names: the region the root boundary starts in,
+// and the row that region starts on.
+const menuId: object = {};
+const homeRowId: object = {};
+
+interface Item {
+    label: string;
+    disabled?: boolean;
+    focusId?: object;
+}
+
+const ITEMS: Item[] = [
+    { label: "Home", focusId: homeRowId },
+    { label: "Search" },
+    { label: "Settings", disabled: true }
+];
+
+function MenuRow(props: { item: Item; y: number; onSelect: (label: string) => void }) {
+    const { ref, isFocused } = useFocusable({
+        focusId: props.item.focusId,
+        onKey: { OK: onPress(() => props.onSelect(props.item.label)) },
+        canReceiveFocus: () => !props.item.disabled
+    });
+
+    return (
+        <group ref={ref} translation={[0, props.y]}>
+            <rectangle width={480} height={72} color={isFocused() ? "0x0055FFFF" : "0x1A1A1AFF"} />
+            <label
+                text={props.item.label}
+                translation={[24, 20]}
+                color={isFocused() ? "0xFFFFFFFF" : "0x8A8A8AFF"}
+            />
+        </group>
+    );
+}
+
+const MainScene: AnchorNodeImplementation<typeof MainSceneDescription> = (inputs, outputs) => (
+    <RootFocusBoundary
+        keyEvent={inputs.keyEvent as Parameters<typeof RootFocusBoundary>[0]["keyEvent"]}
+        focusActive={inputs.focusActive as boolean}
+        setHandledKeys={outputs.handledKeys}
+        initialFocus={menuId}
+        onUnhandledKey={{ back: onPress(() => outputs.exitApp(true)) }}
+    >
+        <FocusBoundary focusId={menuId} initialFocus={homeRowId} navigation="vertical">
+            <For each={ITEMS}>
+                {(item, index) => (
+                    <MenuRow item={item} y={index() * 88} onSelect={label => openScreen(label)} />
+                )}
+            </For>
+        </FocusBoundary>
+    </RootFocusBoundary>
+);
+
+function openScreen(label: string): void {
+    // app logic for the selected row
+}
+
+export default defineAnchorNode(MainSceneDescription, MainScene);
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Nothing moves and no handler fires | The anchor node is not wired, or the items have no boundary above them | `extends: "FocusBoundaryBase"`, `keyEvent` in, `handledKeys` out |
+| The focus fields were added, but `inputs.keyEvent` and `outputs.handledKeys` come out untyped | The scaffold annotates the descriptor `: AnchorNodeDescriptor`, which widens the field maps, and `AnchorNodeImplementation<typeof …>` derives its types from what `typeof` still knows | Drop the annotation and keep `as const` on `extends`, as the example does — the descriptor should be inferred, not declared |
+| The screen compiles but the app's `.test.tsx` stops compiling the moment the anchor node is wired: `Type '{}' is not assignable`, missing `keyEvent` and `focusActive` | `TestAnchorNode` derives the test component's props from the descriptor's field maps, so the three focus fields are now required props of it — the scaffolded `<TestApp />` passes none | Pass all three: `<TestApp keyEvent={{}} focusActive={true} handledKeys={() => undefined} />` — render `keyEvent` from a signal when the test has to press a key |
+| `'Row' cannot be used as a JSX component. Its return type 'Component' is not a valid JSX element` | A focusable leaf was annotated `function Row(props): Component`. `Component` is the type of the function, not of what it returns | Annotate the value — `const Row: Component<Props> = props => …` — or leave the return type inferred, as the example does |
+| OK works but the arrows do nothing | Wrong axis on `navigation`, or a `navigationMap` with that direction unmapped | Set the axis the region moves on; unmapped directions are deliberately not claimed |
+| Focus drops whenever the list updates | `items.map()` in the JSX | Use `<For>` |
+| The highlight never changes | `isFocused` read outside a reactive scope, or `props` destructured | Read it inside JSX, `createMemo`, `createEffect` or a callback |
+| Focus starts nowhere, and even `onUnhandledKey` is dead | `initialFocus` names an id registered deeper than this boundary, or one nothing registered | Point it at a direct child: a leaf's `focusId`, or a nested boundary's `focusId` |
+| Focus jumps back, or fights the keys | `gainFocus` on a SceneGraph node while the boundary is also moving focus | Inside a boundary, move focus with `setFocus` only |
+| One item is never reachable | Its `canReceiveFocus` returns false | Check the condition — a disabled item is skipped by design |
+| A whole branch looks unfocused — behind an open dialog, or once another region has focus | By design: `isFocused()` is `isActive() && focusedId() === focusId`, so it is false throughout an inactive branch, and false everywhere when `focusActive` is false | Draw the "focus returns here" marker from `hasFootprint()` |
+| Two regions react to one key, or a nested region steals keys | A nested boundary was given `keyEvent` | Only the root boundary gets it |
+| Focus is lost when app state changes | Focus state is held in app state and the subtree is rebuilt from it | Let the boundary own focus; read `isFocused()` |
+| A handler armed something on key-down and the key-up never arrived, so a hold never ends | A release is routed by focus *at key-up time*, and focus moved while the key was held — something now in the path claimed the release, or the key left `handledKeys` and BrightScript filtered it out | Set `captureKeyPress` on the boundary that owns the handler: a consumed press is bound to it and the release is delivered there directly. `FlexGrid` exposes the same flag |
+
+Props and options are typed with TSDoc in `@roku-sdk/navigation` — `IRootFocusBoundaryProps`,
+`IFocusBoundaryProps`, `UseFocusableOptions`, `FocusActions`. Read a prop there rather than
+guessing its name.

package/skills/focus-management/references/focus-recipes.md

@@ -0,0 +1,282 @@
+# Focus Recipes
+
+Two procedures that need more than a row in a table, and that the body of the skill
+therefore does not carry. Each is a whole screen's worth of decisions.
+
+## Hand focus between regions of a screen
+
+### First: check whether you need any code at all
+
+A boundary hands its keys upward when the focused child declines them **and** its own
+directional navigation finds no eligible neighbour. So for a regular layout — a menu on the
+left, content on the right — the hand-off is already implemented: wrap both regions in one
+boundary with `navigation="horizontal"`, and `right` at the menu's edge moves focus into the
+content region with no callback anywhere. Reach for the recipe below only when the hand-off is
+**conditional** (the target region has no data yet) or **non-directional** (`OK` on a menu row
+jumps into the content it describes).
+
+One region this recipe does not cover: a `FlexGrid`. It claims seven keys from the boundary — the
+four movement keys, `OK`, `fastforward` and `rewind` — so neither the parent's navigation nor its
+`onUnhandledKey` ever sees them, and the edge it reports arrives through the grid's own
+`onEdgeReached`. Everything below still applies to the *receiving* side — `setFocus` is how focus
+arrives at either kind of region.
+
+### Then: capture `setFocus` inside the boundary that owns both regions
+
+`useFocusActions()` resolves against the *nearest* boundary, and `setFocus` only reaches
+identities registered with that one. Both region boundaries register with their common parent,
+so the hook has to be called from a component rendered **inside** that parent — which is why
+this pattern exists as a component that renders nothing.
+
+```tsx rsg-skill=complete
+import { Group, Label, Rectangle } from "@roku-sdk/components";
+import { FocusBoundary, onPress, useFocusable, useFocusActions } from "@roku-sdk/navigation";
+import { type Component, For, onCleanup } from "@roku-sdk/solid";
+
+const menuId: object = {};
+const contentId: object = {};
+const firstMenuItemId: object = {};
+const firstCardId: object = {};
+
+const MENU = ["Home", "Movies", "Search"];
+const CARDS = ["A", "B", "C", "D"];
+
+function MenuRow(props: { label: string; focusId?: object; y: number; onEnter: () => void }) {
+    const { ref, isFocused } = useFocusable({
+        focusId: props.focusId,
+        onKey: { OK: onPress(() => props.onEnter()) }
+    });
+
+    return (
+        <group ref={ref} translation={[0, props.y]}>
+            <rectangle width={320} height={64} color={isFocused() ? "0x0055FFFF" : "0x1A1A1AFF"} />
+            <label text={props.label} translation={[24, 18]} />
+        </group>
+    );
+}
+
+function Card(props: { label: string; focusId?: object; x: number }) {
+    const { ref, isFocused } = useFocusable({ focusId: props.focusId });
+
+    return (
+        <group ref={ref} translation={[props.x, 0]}>
+            <rectangle width={240} height={135} color={isFocused() ? "0x0055FFFF" : "0x1A1A1AFF"} />
+            <label text={props.label} translation={[16, 100]} />
+        </group>
+    );
+}
+
+export const TwoRegionScreen: Component<{ focusId?: object; hasContent: () => boolean }> = props => {
+    // Written by the capture component below, read by the key handlers. Not a
+    // signal: nothing renders from it, and a signal write here would be a
+    // render-time update.
+    let focusRegion: ((id: object) => void) | undefined;
+
+    const CaptureRegionFocus: Component = () => {
+        const { setFocus } = useFocusActions();
+        focusRegion = setFocus;
+        onCleanup(() => {
+            focusRegion = undefined;
+        });
+        return null;
+    };
+
+    return (
+        <FocusBoundary focusId={props.focusId} initialFocus={menuId} navigation="horizontal">
+            <CaptureRegionFocus />
+
+            <FocusBoundary
+                focusId={menuId}
+                initialFocus={firstMenuItemId}
+                navigation="vertical"
+                onUnhandledKey={{
+                    // Non-directional hand-off: `right` is already handled by the
+                    // parent's horizontal navigation, but OK is not.
+                    OK: onPress(() => {
+                        if (props.hasContent()) focusRegion?.(contentId);
+                    })
+                }}
+            >
+                <For each={MENU}>
+                    {(label, index) => (
+                        <MenuRow
+                            label={label}
+                            focusId={index() === 0 ? firstMenuItemId : undefined}
+                            y={index() * 72}
+                            onEnter={() => focusRegion?.(contentId)}
+                        />
+                    )}
+                </For>
+            </FocusBoundary>
+
+            <group translation={[400, 0]}>
+                <FocusBoundary
+                    focusId={contentId}
+                    initialFocus={firstCardId}
+                    navigation="horizontal"
+                    onUnhandledKey={{ back: onPress(() => focusRegion?.(menuId)) }}
+                >
+                    <For each={CARDS}>
+                        {(label, index) => (
+                            <Card
+                                label={label}
+                                focusId={index() === 0 ? firstCardId : undefined}
+                                x={index() * 264}
+                            />
+                        )}
+                    </For>
+                </FocusBoundary>
+            </group>
+        </FocusBoundary>
+    );
+};
+```
+
+### Common mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `setFocus` on a region does nothing | It was called from a hook whose nearest boundary is one of the regions, not their parent | Capture `setFocus` in a component rendered as a direct child of the parent boundary |
+| The hand-off fires but focus lands on the wrong item | The region remembers where it was; that is `rememberLastFocus`, default `true` | Pass `rememberLastFocus={false}` on the region that should reopen at its first item |
+| `back` inside a region exits the screen instead of returning to the menu | The region did not claim `back`, so it bubbled past the parent to the root | Declare `back` in that region's `onUnhandledKey`; a handler that returns nothing consumes the key and stops it there |
+| The whole screen stops navigating after a region is added | The parent boundary has no `navigation` and no `navigationMap`, so it performs no movement at all — there is no default | Set the axis the regions are laid out on |
+
+## Hold focus inside a dialog, and give it back
+
+`ModalBoundary` and `useModal` from `@roku-sdk/components` implement this: enter on open,
+dismiss on a key you name, restore on close. Do not hand-wire a boundary, a scrim and a
+`Show` — the parts that are easy to get wrong are the ones this already does.
+
+Placement is the whole trick. `useModal().open()` calls `setFocus` on the modal's identity, so
+it must be called where the nearest boundary is the **common parent** of the content branch and
+the `ModalBoundary` — the same rule as region hand-off above, for the same reason.
+
+```tsx rsg-skill=complete
+import { Group, Label, ModalBoundary, Rectangle, useModal } from "@roku-sdk/components";
+import { FocusBoundary, onPress, useFocusable } from "@roku-sdk/navigation";
+import { type Component, createSignal, For } from "@roku-sdk/solid";
+
+const listId: object = {};
+const firstRowId: object = {};
+const confirmId: object = {};
+
+const ROWS = ["Play", "Add to list", "Delete"];
+
+function Button(props: { label: string; focusId?: object; x: number; onSelect: () => void }) {
+    const { ref, isFocused } = useFocusable({
+        focusId: props.focusId,
+        onKey: { OK: onPress(() => props.onSelect()) }
+    });
+
+    return (
+        <group ref={ref} translation={[props.x, 0]}>
+            <rectangle width={240} height={64} color={isFocused() ? "0x0055FFFF" : "0x2B2B2BFF"} />
+            <label text={props.label} translation={[24, 18]} />
+        </group>
+    );
+}
+
+/**
+ * Rendered inside the boundary that owns both branches, which is what lets
+ * `open()` reach the dialog.
+ */
+const ListWithConfirm: Component = () => {
+    const confirm = useModal();
+    const [result, setResult] = createSignal("");
+
+    const finish = (answer: string): void => {
+        setResult(answer);
+        confirm.close();
+    };
+
+    return (
+        <>
+            <FocusBoundary focusId={listId} initialFocus={firstRowId} navigation="vertical">
+                <For each={ROWS}>
+                    {(label, index) => (
+                        <Row
+                            label={label}
+                            focusId={index() === 0 ? firstRowId : undefined}
+                            y={index() * 72}
+                            onSelect={confirm.open}
+                        />
+                    )}
+                </For>
+                <label text={result()} translation={[0, 260]} />
+            </FocusBoundary>
+
+            <ModalBoundary
+                show={confirm.isOpen()}
+                focusId={confirm.focusId}
+                initialFocus={confirmId}
+                navigation="horizontal"
+                onDismiss={confirm.close}
+                dismissKeys={["back"]}
+                dim="0x000000AA"
+            >
+                <group translation={[520, 360]}>
+                    <rectangle width={880} height={240} color="0x14142AFF" />
+                    <label text="Delete this item?" translation={[48, 36]} />
+                    <group translation={[48, 140]}>
+                        <Button label="Delete" focusId={confirmId} x={0} onSelect={() => finish("deleted")} />
+                        <Button label="Cancel" x={280} onSelect={() => finish("kept")} />
+                    </group>
+                </group>
+            </ModalBoundary>
+        </>
+    );
+};
+
+function Row(props: { label: string; focusId?: object; y: number; onSelect: () => void }) {
+    const { ref, isFocused, hasFootprint } = useFocusable({
+        focusId: props.focusId,
+        onKey: { OK: onPress(() => props.onSelect()) }
+    });
+
+    // While the dialog is open every `isFocused()` in this branch is false, so the
+    // row the dialog will return to is drawn from `hasFootprint()` instead.
+    const color = (): string => {
+        if (isFocused()) return "0x0055FFFF";
+        return hasFootprint() ? "0x003399FF" : "0x1A1A1AFF";
+    };
+
+    return (
+        <group ref={ref} translation={[0, props.y]}>
+            <rectangle width={480} height={64} color={color()} />
+            <label text={props.label} translation={[24, 18]} />
+        </group>
+    );
+}
+
+export const ScreenWithDialog: Component<{ focusId?: object }> = props => (
+    <FocusBoundary focusId={props.focusId} initialFocus={listId}>
+        <ListWithConfirm />
+    </FocusBoundary>
+);
+```
+
+### How the restore works, and why you do not write it
+
+`close()` only clears `show`. Unmounting the dialog unregisters its boundary from the parent,
+and the parent moves focus to the neighbour it sat next to in registration order — the content
+branch. That branch then restores its own last focused child, because `rememberLastFocus`
+defaults to `true`. Nothing in your code names the item focus returns to, which is why nothing
+in your code can name the wrong one.
+
+### The footprint is not dialog-specific
+
+`hasFootprint()` is `!isActive() && focusedId() === focusId`, so it is true of any branch that is
+not the active one and still remembers an item. A dialog above it is one cause; focus moving to a
+sibling region is another. A row styled from it therefore keeps its subdued marker while the user
+is over in the menu — usually what you want, but decide it rather than discover it. To mark only
+the dialog case, pass the dialog's `isOpen()` down and gate the marker on it.
+
+### Common mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The dialog appears but keys still drive the list behind it | `show` is true while focus never moved — `open()` was not used, or `focusId` differs between `useModal` and `ModalBoundary` | Drive both from one `useModal()`: `show={m.isOpen()}` and `focusId={m.focusId}` |
+| `useModal` throws on mount | It was called outside any boundary | Call it from a component rendered inside the parent boundary |
+| The dialog cannot be dismissed | No `dismissKeys` key was pressed, and no child claimed one | `dismissKeys` defaults to `back`; name every key that should close it, and wire `onDismiss` |
+| The dialog opens with nothing focused | `initialFocus` names an identity that no child of the dialog registered | Point it at a button inside the dialog, or omit it entirely and let a hidden focusable be injected |
+| Everything behind the dialog looks unfocused, including the row focus will return to | Correct, and by design: `isFocused()` is false throughout an inactive branch | Draw that indicator from `hasFootprint()` |

package/skills/fonts-and-glyphs/SKILL.md

@@ -0,0 +1,176 @@
+# Fonts and Glyphs
+
+## Overview
+
+Two questions decide whether text in an RSG SDK app renders the way you meant: which typeface is
+supplying the characters, and whether that typeface actually has them. Get the first wrong and
+text comes out at a size nobody can read, or ignores the size you set. Get the second wrong and
+you ship empty boxes — and the boxes appear on a device you did not test, because the firmware's
+fallback font hides the problem everywhere else.
+
+## When to Use
+
+- text rendering as empty boxes, on any device or only on some, and whether `fallbackGlyph` helps
+- symbols that were fine until the app started shipping a typeface of its own
+- a symbol needed in a label — arrow, chevron, star, check mark, remote-button icon
+- text that renders far too small, or ignores the size you set
+- shipping a `.ttf` or `.otf` with the app, and a build that refuses two of them
+- deciding whether a shape should be a character at all
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Which node draws the text — `Label`, `SimpleLabel`, `ScrollingLabel`, `MultiStyleLabel` | The `sdk-components` skill | This skill owns the typeface, that one owns the node |
+| Brand marks, multi-colour or gradient artwork | The `sdk-components` skill | That is a `Poster` and an image, not a character |
+| Where an asset file belongs in the project before anything can import it | The `project-setup` skill | Project layout is that skill's job |
+
+## Read the reference first for this task
+
+| If the request is | Read now, before answering |
+|---|---|
+| Naming a specific glyph constant, or auditing which ones survive a custom font | `references/glyph-tables.md` |
+
+The body tells you which *group* a symbol falls in and what that means. The 45 constants, their
+codepoints and their three groups are only in the reference. Guessing a constant name is the one
+mistake here that compiles.
+
+## Quick Reference
+
+| Job | Reach for |
+|---|---|
+| Any arrow, chevron, star, tick, or remote-button icon | A named constant from `@roku-sdk/components/glyphs` — never a typed or escaped literal |
+| A character you can simply type (`·`, `°`, currency, quotes, maths) | Type it. These get no constants on purpose |
+| A brand mark or anything multi-colour | Not a character at all — that is `sdk-components` territory |
+| Set a typeface on a `Label` | A `Font` node in the `font` prop, with **both** `uri` and `size` |
+| `Font.size` | Points. **Defaults to 1**, which is why an otherwise correct font renders as a line of dots |
+| Set a typeface on a `SimpleLabel` | `fontUri` plus `fontSize` — no `Font` node |
+| Built-in font names | Ten. The eight `font:…SystemFont` names are **fixed size and ignore `fontSize`**; only `font:SystemFontFile` and `font:BoldSystemFontFile` respect it |
+| Ship a typeface with the app | `import fontUri from "./fonts/whatever.ttf"` — the import resolves to the packaged path at build time |
+| Two font files with the same filename | A build error if their contents differ, reuse if identical. Rename one |
+| Text arriving from outside with characters your font lacks | Constrain the text or widen the typeface. **`Font.fallbackGlyph` does not substitute anything on current firmware** — see instruction 8 |
+| A `Font` with a `size` and no `uri` | Draws nothing at all. It does not fall back to the system font — omit the `Font` node instead |
+| Which symbols survive a custom app font | The 32 private-use glyphs and `●` `★` `☆`. The other ten do not |
+
+## Instructions
+
+1. **Take symbols from the constants, not from your keyboard or an escape.** Import by name from
+   `@roku-sdk/components/glyphs` and interpolate. A literal like `"\uE025"` is the same character
+   today and an unlabelled magic number the moment the font revision moves; the constant for that
+   one is `LEFT_BUTTON_GLYPH`.
+
+2. **Know the one fact that decides whether a symbol renders: which font supplies it.** The
+   constants are grouped by that, not by codepoint:
+   - **RokuFont01 private-use glyphs** (32 of them) — RokuFont01 is the firmware's system-wide
+     fallback font, so these render under a system font *and* under a custom app font.
+   - **Unicode characters that RokuFont01 backs** — `●` `★` `☆`. Same fallback, so also safe.
+   - **RokuUI-Regular symbols** (10 of them — the arrows, dashes, bullet, ellipsis, tick and
+     ballot X). RokuUI-Regular is the default UI font but is **not** in the fallback chain. Under
+     a system font they are fine; under a custom app font they get no backstop and go tofu unless
+     your font happens to supply them.
+
+   So the counter-intuitive part: if your app ships a typeface, the constants that need care are
+   the plain-Unicode-looking ones, not the exotic private-use ones.
+
+3. **Remember that a custom font wins outright where it defines a codepoint.** No fallback occurs.
+   A licensed font carrying its own private-use glyphs at `U+E0xx` will render *those* in place of
+   the Roku icons, which looks like corruption rather than a font choice.
+
+4. **Give a `Font` node a `size`, always.** `Font.size` is in points and defaults to **1**. A
+   `Font` with a correct `uri` and no `size` is the classic "the font loaded but the text is
+   unreadable" report. Set both together and treat them as one prop.
+
+5. **On `SimpleLabel`, use `fontUri` and `fontSize` — and know which built-in names ignore the
+   size.** Of the ten built-in names, eight are fixed-size (`font:Smallest…`, `font:Small…`,
+   `font:Medium…`, `font:Large…`, each plain and `Bold`) and **discard `fontSize` silently**. Only
+   `font:SystemFontFile` and `font:BoldSystemFontFile`, and any font file of your own, respect it.
+   If a size change does nothing, the name is the reason.
+
+6. **Import font files; do not write packaged paths by hand.** `import fontUri from
+   "./fonts/inter.ttf"` gives you a string that is the packaged path, and the build copies the
+   file for you. Both `.ttf` and `.otf` are declared. Writing the path as a literal skips the copy
+   and ships a reference to a file that is not there.
+
+7. **Expect a build error when two font files share a filename.** The build keys them by filename
+   alone, so two files called `Inter.ttf` in different directories collide. Identical contents are
+   silently reused; different contents fail the build with a `Font naming conflict` naming both
+   sources. Rename one — the directory does not disambiguate them.
+
+8. **Do not plan around `fallbackGlyph`.** `Font.fallbackGlyph` reads like the answer to
+   uncontrollable text — a character of your choosing instead of a box — and on current firmware
+   it does not deliver one. Measured on a Roku Native running 16.0.4: set as a bare `u25CF` (the
+   form the SDK's own documentation shows) and as a literal `●`, against both a symbol only the
+   default UI font has and a codepoint no font on the device has, the boxes were unchanged in
+   every combination. The property is real and the SDK does forward it; what is missing is any
+   visible effect. Treat unsupported characters as something to prevent, not something to
+   substitute: constrain the text, or ship a typeface that covers it.
+
+9. **Do not use firmware placeholder syntax for app text.** Translated firmware strings may
+   contain tokens like `{BACK_BUTTON_GLYPH}`. Those are runtime text tokens resolved by the
+   firmware's own string layer, not TypeScript symbols; putting one in a label renders the braces
+   literally. Interpolate the imported constant instead.
+
+## Example
+
+A row of chevrons and a rating, using a bundled typeface — imported, sized, and with a fallback
+character for anything the typeface lacks.
+
+```tsx rsg-skill=complete
+import { BLACK_STAR, LEFT_BUTTON_GLYPH, RIGHT_BUTTON_GLYPH, WHITE_STAR } from "@roku-sdk/components/glyphs";
+import { Font, Label, LayoutGroup } from "@roku-sdk/components";
+
+import titleFontUri from "./fonts/title.ttf";
+
+function Rating(props: { filled: number; total: number }) {
+    return (
+        <label
+            text={BLACK_STAR.repeat(props.filled) + WHITE_STAR.repeat(props.total - props.filled)}
+            width={200}
+            height={48}
+            color="0xFFFFFFFF"
+        />
+    );
+}
+
+export function CarouselChrome(props: { title: string; rating: number }) {
+    return (
+        <layoutGroup layoutDirection="horiz" itemSpacings={[16]}>
+            {/* Private-use glyphs: the firmware fallback covers these even under a custom font. */}
+            <label text={LEFT_BUTTON_GLYPH} width={48} height={48} color="0xFFFFFFFF" />
+            <label
+                text={props.title}
+                width={600}
+                height={48}
+                color="0xFFFFFFFF"
+                // `size` is not optional in practice -- its default is 1 point,
+                // and a `Font` without a `uri` draws nothing at all.
+                font={<font uri={titleFontUri} size={32} />}
+            />
+            <Rating filled={props.rating} total={5} />
+            <label text={RIGHT_BUTTON_GLYPH} width={48} height={48} color="0xFFFFFFFF" />
+        </layoutGroup>
+    );
+}
+```
+
+## Anti-patterns
+
+Keyed by what you see on screen, because that is what arrives first.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Text shows empty boxes where symbols should be | The character is in neither font — geometric arrows like `◀` `▶` are the usual culprit | Use the named constant; `LEFT_ARROW` and friends are the shapes that exist |
+| Arrows, ticks and dashes vanished after the app shipped its own typeface | Those are RokuUI-Regular symbols and get no RokuFont01 backstop under a custom font | Keep them in system-font text, or make the custom typeface supply them |
+| Icons turned into unrelated shapes under a custom typeface | The custom font defines the same private-use codepoints and wins outright | Use a font without private-use glyphs, or draw those icons in system-font text |
+| Text renders at size 1 — a readable string, unreadably small | `Font.size` was left at its default | Set `size` whenever you set `uri` |
+| Changing the size does nothing at all | The `fontUri` names one of the eight fixed-size built-ins | Switch to `font:SystemFontFile` or a font file |
+| Characters from a backend show as boxes and `fallbackGlyph` changed nothing | It has no visible effect on current firmware, in either value form | Constrain the text or widen the typeface; do not keep tuning the value |
+| A label went completely blank after a `Font` node was added | The `Font` has a `size` but no `uri`, which draws nothing rather than falling back | Give it a `uri`, or drop the `Font` node and let the system font apply |
+| The build fails naming two font files | Same filename, different contents, keyed by filename | Rename one of them |
+| A private-use escape like `"\uE0nn"` sits in app code | The constant exists and the literal does not say which symbol it is | Import the constant |
+| Braces render literally in a label | Firmware placeholder syntax used as app text | Interpolate the constant |
+
+The glyph groups here are device-verified against firmware 15.3.5 on a Roku Express 4K+ — every
+constant rendered in a label under a custom typeface. Re-verify on a device rather than re-wording
+if you need to change what they claim. `IFontProps` and `ISimpleLabelProps` carry TSDoc in the
+installed package; prefer it over any prose, including this file, when the two disagree.