@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills/sdk-components/SKILL.md

@@ -0,0 +1,213 @@
+# SDK Components
+
+## Overview
+
+`@roku-sdk/components` is the package an RSG SDK TypeScript app draws with: mostly thin typed
+wrappers over SceneGraph nodes, plus a few helpers that wrap no node at all. Everything here is
+imported in source at compile time. A partner shipping a player as a separate component library
+from a URL at runtime is a Dynamic Component Library — the `app-packaging` skill routes those, and
+the API is `@roku-sdk/runtime/component-library`, not a `Poster`, `Label` or any other export from
+this package. This skill answers "which one renders this", not "what are its props" — the props
+ship as TSDoc in the consumer's own `node_modules`, and the last section says where.
+
+## Read the reference first for these tasks
+
+| If the request is | Read now, before answering |
+|---|---|
+| A dialog of any kind — a confirmation, a message, a prompt, anything modal | `references/dialogs.md` |
+
+A dialog is composed from areas, each a separately named component, and the tables below do
+not name them. Answer from the reference and quote it: a dialog assembled out of a `Group` and
+some labels is the wrong answer even when it renders.
+
+## When to Use
+
+- choosing the component for a job: a block of text, an image, a row of buttons, a spinner
+- laying a screen out with `Group`, `LayoutGroup` or `MaskGroup`
+- a component that compiles and renders nothing, or renders in the wrong place
+- deciding whether a component is the encouraged one for new work
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Focus, D-pad movement, or the state that dims an unfocused item | The `focus-management` skill | `Focusable`, `FocusableGroup`, `KeyHandler`, `ModalBoundary` and `useModal` are exports of this package that that skill owns outright. It also owns `FocusBoundary` and `useFocusable`, which live in `@roku-sdk/navigation` and are where new focus work goes |
+| A virtualized shelf or poster grid in TypeScript | The `flex-grid` skill | That renderer owns its cells, its keys and its edges |
+| Loading a component library from a URL at runtime, or referencing a node a partner shipped separately | The `app-packaging` skill, which routes to `documentation/core-concepts/dcl.md` and `@roku-sdk/runtime/component-library` | The words "component library" name a delivery mechanism. None of the exports below are fetched from a URL at runtime |
+| Deciding *when* a dialog is up, what the caller learns when it closes, or a flow of several dialogs in sequence | The `dialogs-and-modals` skill | This skill owns what a dialog is made of. Which one is showing, and what its close means to the code that opened it, is app state above the component |
+| Scaffolding, dependencies, `roku-config.ts`, where an image file lives | The `project-setup` skill | This skill starts once the app renders |
+| Rounded corners, a border or a gradient on a `Rectangle` or `Poster` | The `effects` skill | An `Effect` is wired through a prop rather than rendered, and where it is created, how it is shared and animated, and which devices draw it are all there |
+
+## Quick Reference
+
+| Job | Reach for | Give it |
+|---|---|---|
+| Position or group children | `Group` | Nothing — it draws nothing itself |
+| Stack children in a row or column | `LayoutGroup` | `layoutDirection`, `itemSpacings` |
+| A solid block of colour | `Rectangle` | `width`, `height` (`color` defaults to white) |
+| Clip or fade children against a shape | `MaskGroup` | `maskUri` |
+| Rounded corners, a border, or a gradient on a surface | `Effect`, whose wiring this row deliberately does not repeat | The `effects` skill — an effect is passed through a prop, and the rules for it live there |
+| One line of text | `Label` | `text` |
+| Text positioned by its own centre or edge | `SimpleLabel` | `text`, `horizOrigin`, `vertOrigin` |
+| Text too long for its box that should march past | `ScrollingLabel` | `text` |
+| A synopsis in a fixed box the user scrolls | `ScrollableText` | `text`, `width`, `height` |
+| Text with inline styled runs | `MultiStyleLabel` | `text`, `drawingStyles` |
+| A typeface | `Font`, whose props this row deliberately does not repeat | The `fonts-and-glyphs` skill — a typeface is wrong without its size and its fallback, and shipping one needs the import contract that lives there too |
+| An image | `Poster` | `uri`, plus `loadDisplayMode` when it has to fit a fixed box |
+| One button | `Button` | `text`, and `showFocusFootprint` when it is not inside a `ButtonGroup` |
+| A row or column of buttons | `ButtonGroup` | `buttons` (strings), `onButtonSelected` (the index) |
+| A loading indicator | `BusySpinner` | `uri`, e.g. `"theme:ActionHudSpinner"` |
+| A dialog | The components named in `references/dialogs.md`, which this row deliberately does not repeat | `references/dialogs.md` — a dialog is wrong without its areas, and their props are only there |
+| Animate a field to a target | `Tween` from `@roku-sdk/components` | `targetNode`, `field`, and `targetValue` or `targetVector` |
+| Video or audio playback | `Video`, `Audio` | A `VideoContentNode` as `content` |
+| Data for a SceneGraph-native list | `ContentNode` | The fields that list reads |
+
+For the declarative `<tween>` primitive and the components `Tween` wrapper, read the Tween value-shape contract in `documentation/core-concepts/tween.md` in the SDK source tree.
+
+## Instructions
+
+1. **Assume nothing is required, because almost nothing is.** Every prop inherited from
+   `INodeProps` is optional, so a component with no props at all compiles. It just does not
+   render. The type system will not tell you that `Label` needs `text`, that `Rectangle` needs
+   `width` and `height`, that `Poster` needs `uri`, or that `MaskGroup` needs `maskUri`. Treat the
+   Quick Reference's third column as the real signature.
+
+2. **The handful of genuinely required props are worth knowing** because they are the only
+   compile errors this package gives you: `ButtonRow` needs `buttons`, `Dialog` needs `close`,
+   `RsgPalette` needs `colors`, `MarkupList` and `MarkupGrid` need `itemComponentName`, and
+   `KeyHandler` needs `onKeyEvent` plus exactly one of `keys` or `handleAllKeys`.
+
+3. **Write the lowercase intrinsic, not the capitalized wrapper, in new code.** Most of these
+   components are pure pass-throughs — `Rectangle` is exactly `props => <rectangle {...props} />`
+   — and the lowercase tag is already typed against the same props interface. So `<rectangle>`,
+   `<group>`, `<label>` and friends need no import and render identically. The wrappers are
+   supported and not deprecated, so existing code is fine as it stands and an app author may
+   use either; but samples, demos and generated code should be consistent about the intrinsic.
+   The exceptions are the components in step 4, which are not pass-throughs and must keep their
+   capitalized form. Full reasoning: `references/scenegraph-node-spelling.md`.
+
+4. **These are not pass-throughs — always write them capitalized.** `Audio` (renders `content`
+   as a child), `VideoContentNode`, the five keyboard components `CustomKeyboard`,
+   `DynamicKeyboard`, `DynamicKeyGrid`, `DynamicMiniKeyboard` and `DynamicPinPad` (they call
+   `retainAsset()` so the backing XML survives tree-shaking), the six dialogs `Dialog`,
+   `StandardDialog`, `StandardKeyboardDialog`, `StandardMessageDialog`, `StandardPinPadDialog`
+   and `StandardProgressDialog` (they wrap in `<Modal>`), `ListPanel` (forwards to a different
+   node), and the logic-bearing `Focusable`, `FocusableGroup`, `KeyHandler`, `Modal`,
+   `Container`, `ButtonRow`, `BlendedBusySpinner`, `BoundingTracker` and `ChannelStore`. A
+   lowercase tag here either fails to compile or silently drops the behaviour.
+
+5. **`<group>` now needs an import like everything else.** It used to be registered as a
+   capitalized JSX intrinsic, uniquely in the package, so a forgotten or misspelled import of
+   `Group` did not fail the build and a layout could misbehave with nothing to point at. That
+   alias has been removed: write `<group>` for the node, or import `Group` from
+   `@roku-sdk/components` if you want the wrapper.
+
+6. **If it is fed by a `content` ContentNode, it is a SceneGraph-native list.** Eleven are:
+   `RowList`, `ZoomRowList`, `MarkupList`, `MarkupGrid`, `PosterGrid`, `LabelList`, `CheckList`,
+   `RadioButtonList`, `TimeGrid`, `TargetGroup` and `TargetList`. Six of them also take an
+   `itemComponentName` — required on `MarkupList` and `MarkupGrid` — which names a compiled
+   BrightScript component by string, and that is what renders each item. A TypeScript component
+   therefore cannot be an item of one. Name them when a reader asks about them; for a scrolling
+   shelf or poster grid written in TypeScript, the answer is `@roku-sdk/flex-grid`. (`Video` and
+   `Audio` take a `content` node too, but they are players, not lists.)
+
+7. **Prefer these over the four that are still exported but not the current answer.**
+   `StandardDialog` over `Dialog` — Roku OS 10 introduced the newer node with palette support,
+   and `Dialog` remains only for backward compatibility. `RsgPalette` over `RSGPalette`, which
+   is the same value under a deprecated alias. `ButtonGroup` over `ButtonRow`, which is a
+   convenience wrapper built on the legacy `Focusable` / `FocusableGroup` focus model rather
+   than on `FocusBoundary`. And `Container` only for deliberate node pooling — it renders
+   nothing itself, and detaching a node through it on firmware 15.2.x destroys that node
+   (fixed in 15.3).
+
+8. **On an intrinsic, attribute order is behaviour: handlers first, `uri` last.** A capitalized
+   wrapper spreads its props, and the spread path hoists event handlers ahead of regular props
+   before any are applied. An intrinsic written with inline attributes does not go through that
+   path — the compiler emits one `setProp` per attribute in source order and nothing reorders
+   them. Two consequences. A property that can synchronously fire an event will fire it before a
+   handler written after it, and the event is lost: `<poster uri={u} onLoadStatus={h} />` drops
+   the event when the image is already cached, `<poster onLoadStatus={h} uri={u} />` does not.
+   (The spread path reorders handlers first; inline intrinsic attributes are not reordered.) And the `Poster` load starts when
+   `uri` lands, so a `loadDisplayMode` or a size written after it applies to a load already in
+   flight. Full reasoning: `references/scenegraph-node-spelling.md`.
+
+9. **Read the TSDoc for anything this skill does not answer.** Every export ships as raw
+   TypeScript with its documentation attached, at
+   `node_modules/@roku-sdk/components/src/sg-nodes/<node>.tsx` — `poster.tsx`, `label.tsx`,
+   `standard-dialog.tsx` and so on. The few components not backed by a single SceneGraph node
+   sit one level up in `src/`: `container.tsx`, `button-row.tsx`, `key-handler.tsx`.
+   `ModalBoundary` is re-exported from `@roku-sdk/navigation`. There is no bundled `.d.ts` and no
+   package README to consult instead.
+
+## Example
+
+Intrinsics for the plain nodes — `poster` and `label` need no import, because each is a
+pass-through with a lowercase tag.
+
+The composite nodes are written here as the capitalized `LayoutGroup`, `ButtonGroup` and
+`BusySpinner` components, which is the spelling that compiles on every version. Their intrinsic
+tags are spelled `layoutGroup`, `buttonGroup` and `busySpinner` from SDK v2.15.0 onward, and were
+`layoutgroup`, `buttongroup` and `busyspinner` on v2.14.0 and earlier; the components wrap
+whichever the installed version provides, so prefer them in code meant to survive the rename.
+
+```tsx rsg-skill=complete
+import { BusySpinner, ButtonGroup, LayoutGroup } from "@roku-sdk/components";
+import { Show } from "@roku-sdk/solid";
+
+interface DetailPanelProps {
+    title: string;
+    posterUri: string;
+    loading: boolean;
+    onAction: (index: number) => void;
+}
+
+export function DetailPanel(props: DetailPanelProps) {
+    return (
+        <layoutGroup layoutDirection="horiz" itemSpacings={[40]}>
+            {/* `uri` last: the load starts when it lands. */}
+            <poster width={300} height={400} loadDisplayMode="scaleToFit" uri={props.posterUri} />
+            <layoutGroup layoutDirection="vert" itemSpacings={[24]}>
+                <label text={props.title} width={900} />
+                <Show
+                    when={props.loading}
+                    fallback={
+                        <buttonGroup
+                            buttons={["Play", "More Info"]}
+                            onButtonSelected={(index: number) => props.onAction(index)}
+                        />
+                    }
+                >
+                    <busySpinner uri="theme:ActionHudSpinner" />
+                </Show>
+            </layoutGroup>
+        </layoutGroup>
+    );
+}
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| A component compiles but nothing appears | The prop that gives it content or size is optional and was left off | `Label` needs `text`; `Rectangle` and `ScrollableText` need `width` and `height`; `Poster` needs `uri`; `MaskGroup` needs `maskUri` |
+| A `LayoutGroup` centres its children somewhere unexpected | Alignment is relative to the group's own `translation`, not to the screen | Position the group, then let it align within itself |
+| A lone `Button` has no background until it is focused | `showFocusFootprint` defaults off outside a `ButtonGroup` | Set `showFocusFootprint={true}` |
+| Text is set but renders at an unreadable size, or a symbol comes out as an empty box | The typeface, not the node | The `fonts-and-glyphs` skill |
+| A `MaskGroup` masks nothing on some hardware | Masking is OpenGL-only; elsewhere children draw unmasked | Do not rely on it for correctness, only for polish |
+| A TypeScript component cannot be used as a list item | That list renders items from BrightScript XML named by `itemComponentName` | Use `@roku-sdk/flex-grid` for a shelf or grid written in TypeScript |
+| Rounded corners, a border or a gradient is missing, stutters, or will not animate | An `Effect` problem, not a component choice | The `effects` skill |
+| The question names a component library, a URL at runtime, or a partner binary shipped separately | Those words describe a Dynamic Component Library, not a choice between `Poster` and `Label` | The `app-packaging` skill: it owns the routing, and names `@roku-sdk/runtime/component-library` for loading and referencing |
+
+## Tween
+
+`Tween` is a logic-bearing wrapper and must remain capitalized. Use `targetNode` with a node
+or a getter returning one. The old `targetRef` name is a deprecated alias for one minor release;
+`targetNode` wins when both are supplied. The wrapper uses the native field types in `ITweenProps`,
+except that its `onAnimationState` callback receives `(state, value)` rather than the intrinsic's
+single `[state, value]` tuple. It binds the target before triggers and releases it on cleanup.
+It defaults to `outCubic`; the native intrinsic defaults to `linear`.
+
+The native node is selected when firmware supports the `tween` feature. Import `@roku-sdk/compat`
+for `RsgTweenShim` on older firmware. Without compat, unsupported firmware throws a missing-feature
+error rather than silently rendering an inert node. Axis and settle value shapes are described in
+the linked value-shape contract.

package/skills/sdk-components/references/dialogs.md

@@ -0,0 +1,148 @@
+# Composing a StandardDialog
+
+A `StandardDialog` is assembled from areas, and each area holds items. Nothing about it is
+positioned by hand: the dialog sizes and stacks its own areas, and `width` / `height` default
+to the system size (1038 FHD, 692 HD) when left at 0.
+
+## The areas
+
+| Area | Where it goes | Required |
+|---|---|---|
+| `StdDlgTitleArea` | Top, at most one | — |
+| `StdDlgContentArea` | Between title and buttons, at most one | — |
+| `StdDlgButtonArea` | Always the bottom, at most one | — |
+| `StdDlgSideCardArea` | Left or right of the rest, at most one | `width` |
+| `RsgPalette` | A child, or the `palette` prop | `colors` |
+
+Ordering in the JSX does not decide layout — the dialog places each area by its type — but
+writing them top-to-bottom keeps the source readable.
+
+## The items that go in the content area
+
+`StdDlgTextItem` (`text`) and `StdDlgMultiStyleTextItem` (`drawingStyles`, `audioGuideText`)
+for prose, `StdDlgBulletTextItem` for a list, `StdDlgGraphicItem` for an image,
+`StdDlgProgressItem` (`text`) and `StdDlgDeterminateProgressItem` for progress,
+`StdDlgKeyboardItem` for entry, and `StdDlgCustomItem` when nothing else fits.
+
+Wrap a set of choices in a `StdDlgItemGroup`: it tightens the spacing and enforces
+one-of-N selection across the `StdDlgActionCardItem`s inside it. An action card is focusable
+and holds its own `StdDlgTextItem` as its label.
+
+Buttons are `StdDlgButton` (`text`), and they belong directly inside `StdDlgButtonArea` —
+nowhere else. The side card never takes key focus, so nothing interactive belongs in it.
+
+## A confirmation dialog
+
+```tsx rsg-skill=complete
+import {
+    StandardDialog,
+    StdDlgButton,
+    StdDlgButtonArea,
+    StdDlgContentArea,
+    StdDlgTextItem,
+    StdDlgTitleArea
+} from "@roku-sdk/components";
+
+interface ConfirmDeleteProps {
+    onChoice: (index: number) => void;
+    onClosed: () => void;
+}
+
+export function ConfirmDelete(props: ConfirmDeleteProps) {
+    return (
+        <StandardDialog
+            initialFocusId="confirm-cancel"
+            onButtonSelected={index => props.onChoice(index)}
+            onWasClosed={() => props.onClosed()}
+        >
+            <stdDlgTitleArea primaryTitle="Delete recording?" />
+            <stdDlgContentArea>
+                <stdDlgTextItem text="This removes it from every device on your account." />
+            </stdDlgContentArea>
+            <stdDlgButtonArea>
+                <stdDlgButton id="confirm-cancel" text="Cancel" />
+                <stdDlgButton text="Delete" />
+            </stdDlgButtonArea>
+        </StandardDialog>
+    );
+}
+```
+
+`onButtonSelected` reports the index of the button in the order they are declared, so the
+handler switches on 0 and 1 rather than on a label.
+
+This reference stops at the dialog itself. Who decides it should be up, what the caller learns
+when it goes down, and how one dialog leads to the next are app state — the
+`dialogs-and-modals` skill owns that. `StandardDialog` normalizes native close notifications
+to at most one `onWasClosed` per presented lifetime while mounted; button/action completion
+remains app state. Unmount releases ownership and retires callbacks, so do not wait for a
+close notification from a component you have already disposed.
+
+## Preparing before presentation
+
+The lifecycle props in this section require SDK 2.17.0 (not available in 2.16.0).
+
+Use `ready={false}` to prepare the dialog without presenting its content. An optional
+`fallback` is a **raw native dialog element**, not a nested `StandardProgressDialog`
+component (which would create a second modal owner):
+
+```tsx rsg-skill=complete
+import { StandardDialog } from "@roku-sdk/components";
+
+const DeferredDialog = (props: { open: boolean; ready: boolean; onClose: () => void }) => (
+    <StandardDialog
+        open={props.open}
+        ready={props.ready}
+        replaceExisting={false}
+        fallback={
+            <standardDialog optionsDialog>
+                <stdDlgContentArea><stdDlgProgressItem text="Loading" /></stdDlgContentArea>
+            </standardDialog>
+        }
+        onWasClosed={props.onClose}
+        onBlocked={props.onClose}
+        title="Preferences"
+        optionsDialog
+    >
+        {/* StdDlg areas and items */}
+    </StandardDialog>
+);
+```
+
+`open` defaults to true. Setting it false requests native closure; `onWasClosed` follows
+the native event. Unmount requests closure of only the owned modal and retires its observers.
+Native dismissal does not reopen on a late readiness update; toggle `open` after native
+closure to start another lifetime. `replaceExisting` defaults to true for existing consumers;
+false reports `onBlocked` rather than replacing an unrelated native dialog. The fallback
+and ready content share that ownership, so their handoff does not report a terminal close.
+`onOpened` confirms the main dialog's native attachment and initial focus, not bitmap
+readiness or drawn pixels. `title` and `optionsDialog` are native dialog properties.
+
+`close` also stays on the native dialog, without a Modal proxy. Native `close` is
+always-notify: an actual field assignment closes regardless of the Boolean value.
+Solid does not rewrite an unchanged prop. Clearing `scene.dialog` is not the native
+close operation. Non-preemption is opt-in with `replaceExisting={false}`.
+
+## Focus is not yours to wire
+
+`StandardDialog` renders a native SceneGraph modal, so SceneGraph moves focus into it when it
+appears and back out when it closes. Point `initialFocusId` at the button that should be
+focused first and stop there. An enclosing `FocusBoundary` goes inactive on its own while the
+dialog is up; setting `focusActive` by hand fights the platform.
+
+`ModalBoundary` and `useModal` are the other path, not an addition to this one. They exist for
+an overlay you draw yourself out of ordinary nodes, which has no native modal to hand focus
+to. Choose one: a `StandardDialog`, or a hand-drawn overlay inside a `ModalBoundary`. The
+`focus-management` skill owns the second.
+
+## Ready-made variants
+
+When the composition above is more than the job needs, four dialogs arrive pre-assembled and
+take the same props as `StandardDialog`: `StandardMessageDialog` for a message and buttons,
+`StandardKeyboardDialog` for text entry, `StandardPinPadDialog` for a PIN, and
+`StandardProgressDialog` for a wait. They exist as separate modules so an app that uses one
+does not pay for the XML of the others.
+
+`Dialog` is the pre-OS-10 node. It is still exported and still works — note its required
+`close` prop, which dismisses the dialog whenever it is *set*, whatever the value, so it is
+normally passed as `close={false}` — but new work should use `StandardDialog`.

package/skills/sdk-components/references/scenegraph-node-spelling.md

@@ -0,0 +1,123 @@
+# SceneGraph Node Spelling: Intrinsics vs. Component Wrappers
+
+Most SceneGraph nodes can be written two ways in an RSG SDK TypeScript app:
+
+```tsx
+import { Rectangle } from "@roku-sdk/components";
+
+<Rectangle width={200} height={100} color="0x333355FF" />;
+```
+
+```tsx
+<rectangle width={200} height={100} color="0x333355FF" />;
+```
+
+Both compile. Both type-check against the same `IRectangleProps`. Both produce the same node
+at runtime. The capitalised form is a component whose entire body is
+`props => <rectangle {...props} />`.
+
+**Recommended for new work: the lowercase intrinsic.** The wrappers are supported and are not
+deprecated — an existing app has no reason to churn, and either spelling is a legitimate
+choice. This page explains the recommendation so the reasoning travels with it.
+
+## Why the intrinsic is recommended
+
+The lowercase tag is the node. The capitalised export adds a component to the tree that exists
+only to spread its props straight through, so the intrinsic is one less indirection between
+what you write and what renders.
+
+It also needs no import, which removes a class of mistake rather than merely discouraging one.
+Capitalised names collide with names an app plausibly wants for its own components — `Button`,
+`Panel`, `Video` and `ProgressBar` are all reasonable names for something in your own codebase,
+and importing ours shadows yours.
+
+The remaining reason is consistency. Two spellings with no stated preference means every author
+and every code-generating agent picks arbitrarily, and a codebase ends up with both. Picking one
+for new work is worth more than which one gets picked.
+
+## The `<Group>` alias, which used to be a trap
+
+`Group` was once registered as a capitalised JSX intrinsic under `@roku-sdk/solid` — uniquely in
+the package, nothing else was. A file could write `<Group>` with no import at all and still
+compile, so a forgotten or misspelled `Group` import did not fail the build and a layout could
+misbehave with nothing to point at.
+
+That alias has been removed. `Group` is now an ordinary export like every other wrapper: import
+it if you want it, or write `<group>` for the node. Both spell the same node, and the
+recommendation above still applies — prefer `<group>`.
+
+## Put event handlers first in the attribute list
+
+This one matters for correctness, not style, and it applies specifically to intrinsics.
+
+A capitalised wrapper spreads its props (`props => <rectangle {...props} />`), and the spread
+path reorders event handlers ahead of regular props before any of them are applied. An intrinsic
+written with inline attributes does not go through that path: the compiler emits one
+`setProp` call per attribute, in source order, and nothing reorders them.
+
+So for an intrinsic, the order you write the attributes in is the order they are applied. If a
+property assignment can synchronously fire an event, and its handler is written after that
+property, the event fires before the handler exists and is lost:
+
+```tsx rsg-skill=no-check
+// Wrong: if the image is already in the cache, the load completes during the
+// uri assignment — before onLoadStatus is registered — and the event is dropped.
+<poster uri={posterUri} onLoadStatus={handleLoad} />
+
+// Right: the handler is registered before the property that can fire it.
+<poster onLoadStatus={handleLoad} uri={posterUri} />
+```
+
+This is the same defect that was fixed for the spread path only. Inline intrinsic attributes
+are applied in source order, so write handlers first. It is a good habit regardless, since it
+makes the ordering explicit rather than incidental.
+
+## Where the recommendation is binding
+
+Samples, demos, documentation examples and the packaged AI skills should use intrinsics
+consistently. This is the part that does the work — code-generating agents imitate surrounding
+code far more reliably than they follow prose guidance, so example code that uses the
+capitalised form teaches the capitalised form regardless of what any doc says.
+
+Application code is the developer's call. Nothing here is enforced by lint, and no wrapper is
+scheduled for removal.
+
+## Nodes with no intrinsic equivalent
+
+Some exports are not pass-throughs. They add behaviour, and the capitalised component is the
+only correct way to use them:
+
+| Component | What it adds |
+|---|---|
+| `Audio` | Renders `content` as a child rather than spreading props alone |
+| `VideoContentNode` | A distinct typed view over `<contentNode>` |
+| `CustomKeyboard`, `DynamicKeyboard`, `DynamicKeyGrid`, `DynamicMiniKeyboard`, `DynamicPinPad` | Call `retainAsset()` so the backing XML survives tree-shaking |
+| `Dialog`, `StandardDialog`, `StandardKeyboardDialog`, `StandardMessageDialog`, `StandardPinPadDialog`, `StandardProgressDialog` | Wrap their node in `<Modal>` |
+| `ListPanel` | Forwards to `<managedListPanel>`, a different node |
+| `Focusable`, `FocusableGroup`, `KeyHandler`, `Modal`, `Container`, `ButtonRow`, `BlendedBusySpinner`, `BoundingTracker`, `ChannelStore` | Real logic, no single backing node |
+
+Writing a lowercase tag in place of one of these either fails to compile or silently drops the
+behaviour the wrapper existed to provide.
+
+## Migrating (optional)
+
+Props, types and rendered output are unchanged, so the edit is mechanical and the import can
+usually be dropped:
+
+```tsx
+// before
+import { Group, Rectangle, Label } from "@roku-sdk/components";
+
+<Group>
+    <Rectangle width={w} height={h} color="0x333355FF" />
+    <Label text="Hello" horizAlign="center" />
+</Group>;
+
+// after
+<group>
+    <rectangle width={w} height={h} color="0x333355FF" />
+    <label text="Hello" horizAlign="center" />
+</group>;
+```
+
+Check the table above first — a `Dialog` or a `CustomKeyboard` must keep its wrapper.

package/skills/sdk-installation/SKILL.md

@@ -0,0 +1,129 @@
+# SDK Installation
+
+## Overview
+
+Stable `@roku-sdk/*` packages install from registry.npmjs.org with ordinary pnpm
+commands. No registry override or token is needed. Check the effective registry,
+requested version and lockfile when an install fails; adding authentication is
+not the fix for a public package.
+
+## When to Use
+
+- a first install into a project that has none of the SDK yet
+- pnpm cannot find an `@roku-sdk` package, or returns 401 or 404 for that scope
+- an install succeeds locally but fails on another machine or in a pipeline
+- moving SDK versions or staying on a package's older major line
+- satisfying a peer dependency or avoiding duplicate reactive runtimes
+- confirming where installed packages resolved
+
+### When not to use
+
+| Situation                                                                      | Use instead                                                                   | Because                                                                 |
+| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| A package the app lists because its code imports it, or configuring a scaffold | The `project-setup` skill                                                     | That starts once packages resolve; a package's required peers stay here |
+| A resolved package's API does not behave as expected                           | The skill for that area                                                       | Installation is finished                                                |
+| A different company's private registry                                         | That registry's documentation                                                 | This skill covers public SDK consumption                                |
+| Signing or publishing an app                                                   | The `app-packaging` skill                                                     | That ships an app outwards; this brings dependencies in                 |
+| Releasing the SDK itself or obtaining a prerelease                             | The release process or preview access instructions supplied by the maintainer | npmjs.com carries stable releases; this is the stable consuming side    |
+
+## Quick Reference
+
+| Goal                               | Do                                                                               |
+| ---------------------------------- | -------------------------------------------------------------------------------- |
+| Install stable packages            | `pnpm add @roku-sdk/components` — registry.npmjs.org, no token                   |
+| Check the effective package source | `pnpm config get registry` and `pnpm config get @roku-sdk:registry`              |
+| Check a published version or tag   | `pnpm view @roku-sdk/flex-grid dist-tags`                                        |
+| Stay on an older major             | Use `^2.0.0`; older patches may use `latest-2.16`, but confirm it exists |
+| Verify installed versions          | Inspect `pnpm-lock.yaml` and run `pnpm list`                                     |
+| Satisfy FlexGrid's peers           | Declare all six in the app's `package.json`, including `@roku-sdk/runtime`       |
+| Install in CI                      | `pnpm install --frozen-lockfile`; public installs need no auth token             |
+
+## Instructions
+
+1. **Install from the public registry.** Use Node 24 or later and pnpm 11.
+   If the SDK packages are already listed in `package.json`, run `pnpm install`;
+   otherwise use `pnpm add` to declare them. No project registry file or token
+   setup is required for stable SDK packages.
+
+2. **Check effective configuration before fixing a 401 or 404.** The default
+   registry should be `https://registry.npmjs.org/`. An unset `@roku-sdk:registry`
+   uses that default; an obsolete scope override still wins over it. Remove
+   stale overrides or authentication settings from the configuration that owns
+   them. Verify the requested package, version and dist-tag with `pnpm view`.
+   A public install does not need a new read token.
+
+3. **Check local and CI environments separately.** A runner can inherit
+   different user or environment registry configuration even with identical
+   repository files. Match Node/pnpm versions, confirm access to
+   registry.npmjs.org, and use the committed lockfile with `--frozen-lockfile`.
+   Do not add a CI authentication step for public packages.
+
+4. **Transitive packages install automatically; required peers are different.**
+   Which dependencies the app lists because it imports them is `project-setup`.
+   A package's peer contract is this skill's subject: inspect it with
+   `pnpm view @roku-sdk/flex-grid peerDependencies`.
+
+5. **Move packages released together together.** Keep a shared version range
+   across the coordinated SDK packages. A package on an independent major line,
+   such as FlexGrid, has its own version, but its peer ranges still require
+   compatible SDK versions.
+
+6. **Prefer a semver range over a moving dist-tag for a major line.** `^2.0.0`
+   receives compatible 2.x fixes and cannot select 3.x. A stable line can have
+   a tag such as `latest-2.16` for older patches; newest-line releases carry only
+   `latest`. Check the published tags before installing by one.
+   FlexGrid 3.x owns `latest`, while its 2.x maintenance tag is `maintenance-2x`.
+   Read the package's `BREAKING_CHANGES.md` before changing majors. Prerelease
+   channels are not available on npmjs.com.
+
+7. **Declare all of FlexGrid's peers in the app.** They are `@roku-sdk/common`,
+   `@roku-sdk/components`, `@roku-sdk/interfaces`, `@roku-sdk/navigation`,
+   `@roku-sdk/runtime` and `@roku-sdk/solid`. They let the app own one shared
+   reactive runtime. Satisfy the floors declared by the selected grid release
+   rather than upgrading the grid alone.
+
+8. **Verify the lockfile, not just the install's exit code.** Check the
+   `@roku-sdk/*` versions and integrity entries in `pnpm-lock.yaml` against the
+   installed tree. Packages should resolve from registry.npmjs.org. Modern
+   pnpm lockfiles usually omit download URLs and derive the registry from
+   configuration: no host string is not evidence of failure. If an older entry
+   explicitly points elsewhere, remove its obsolete registry override and run
+   `pnpm install --registry https://registry.npmjs.org`, then review the lockfile
+   diff. Do not hand-edit integrity hashes or introduce tarball URLs.
+
+## Example
+
+In a consumer app with no SDK dependencies yet:
+
+```bash
+pnpm add @roku-sdk/rsg-ts @roku-sdk/components @roku-sdk/solid @roku-sdk/tooling
+pnpm config get registry
+# Expected: https://registry.npmjs.org/
+pnpm config get @roku-sdk:registry
+# Unset is normal: the scope uses the default registry.
+pnpm view @roku-sdk/rsg-ts version --registry https://registry.npmjs.org
+pnpm list @roku-sdk/rsg-ts @roku-sdk/components
+```
+
+Review the `@roku-sdk/*` entries in `pnpm-lock.yaml`, then commit it with
+`package.json`. A CI runner installs the same tree with:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+For the exact exports and peer contract of an installed package, inspect its
+`package.json` and typed source under `node_modules/@roku-sdk/`.
+
+## Common Mistakes
+
+| Symptom                      | Cause                                                       | Fix                                                                                            |
+| ---------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 401 for public SDK packages  | Unexpected registry or stale authentication configuration   | Check default and scoped configuration on that machine; use registry.npmjs.org without a token |
+| 404 or no matching version   | Misspelled package or unpublished version/tag               | Inspect `pnpm view`; use a published stable version                                            |
+| Works locally, fails in CI   | Different configuration, network access or toolchain        | Check the runner's effective registry and Node/pnpm versions; no public read token is needed   |
+| Frozen lockfile mismatch     | Dependency declarations changed without the lockfile        | Update locally and commit both files                                                           |
+| Lockfile has no registry URL | Current pnpm stores integrity and versions rather than URLs | Check effective registry configuration and installed versions, not a grep's empty output       |
+| Unrequested major upgrade    | A moving dist-tag was used instead of a range               | Pin the intended major with a range; confirm tags before deliberate one-off installs           |
+| Duplicate reactive runtime   | Required peers were omitted or incompatible                 | Declare all six FlexGrid peers and satisfy their ranges                                        |
+| `workspace:*` cannot resolve | The app is outside the SDK workspace                        | Replace workspace ranges with published versions                                               |