@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills/testing/SKILL.md

@@ -0,0 +1,147 @@
+# Testing Components
+
+## Overview
+
+`@roku-sdk/testing-library` renders a component through the same Solid renderer the app
+uses, into an in-process tree of plain objects, and hands back queries over that tree. A
+test therefore asserts on tags and prop values, never on pixels. `rk create` already
+scaffolds `jest.config.mjs` and a passing example test, so writing a test is adding a
+file — there is no harness to build first.
+
+Children render for real. The renderer, the reactive graph and every nested component are
+the app's own; only the platform edge beneath them is substituted. These are component
+tests rather than isolated unit tests, which decides two things: do not mock a child to
+get at its parent, and expect a broken child to fail its parent's test.
+
+## When to Use
+
+- writing a test for a component, or reading one that is already there
+- asserting that a node rendered, or that one of its props holds a particular value
+- driving a D-pad press or any other key event through a component
+- snapshotting the rendered tree, and updating that snapshot on purpose
+- a test whose assertion reads a value the app gets right, because it ran before the
+  update it is asserting on
+
+That last one has one cause and two fixes, both in `references/async-and-timing.md`. Read
+it whenever a value is stale, whenever the component under test awaits anything, or before
+reaching for a timer.
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Proving behaviour on real hardware | The `mcp-ai-dev-loop` skill, or a `device-tests/` suite | Nothing here touches a Roku. The tree is a JavaScript object, so a passing test says what the component built, not what the screen showed |
+| A React or web component test | That library's own documentation | Those render into a DOM and query it by text and role; these queries run over SceneGraph tags and props, and none of them transfer |
+| A legacy BrightScript channel | Roku's own BrightScript unit-testing documentation | A different runtime and a different toolchain |
+| Adding Jest itself, or a dependency the app is missing | The `project-setup` skill | That is project configuration; this skill starts once `pnpm test` runs |
+
+## Quick Reference
+
+| Task | Do this |
+|---|---|
+| Render | `const view = await render(() => <TestApp />)` — `render` is async, and an un-awaited one hands back a promise with no queries on it |
+| Get something renderable | `const TestApp = TestAnchorNode(App)` at module scope, where `App` is the tuple `defineAnchorNode` returned |
+| One node by tag | `getByTag("label")` — tags are the lowercase SceneGraph names: `label`, `rectangle`, `group`, `poster`, `key-handler` |
+| Every node by tag | `getAllByTag("label")` |
+| One node by prop value | `getByProp("text", "Play")`, or `getByProp("id", "titleLabel")` |
+| Tolerate absence | `queryByTag`, `queryAllByTag`, `queryByProp` — `null` or `[]` where the `get` forms throw. There is no `getAllByProp` |
+| Read a found node | `props(node)`, `children(node)`, `tag(node)` |
+| Press a key | `await fireEvent(getByTag("key-handler"), "onKeyEvent", { key: "right", press: true })` |
+| Snapshot the tree | `expect(toString(2)).toMatchSnapshot()` |
+| Let a pending update land | `await view.transaction()` |
+| End the test | `dispose()` — synchronous, so there is nothing to await |
+| Configure Jest | one line in `jest.config.mjs`: `export { default } from "@roku-sdk/dev-tools/jest-config/jest.config.mjs";` |
+
+## Instructions
+
+1. **Wrap the component once, at module scope.** `TestAnchorNode(App)` takes the tuple
+   `defineAnchorNode` returned — the component's default export — and returns something
+   `render` can mount. Building it inside each test rebuilds the component definition per
+   test for no benefit.
+
+2. **`await render(...)`.** It returns the queries, `fireEvent`, `transaction`, `toString`
+   and `dispose` in one object; destructure the ones the test uses. The await is not
+   ceremony: the first commit of the tree is queued and flushed inside `render`, so without
+   it there is nothing to query.
+
+3. **Let the `get` forms be the assertion.** `getByTag` and `getByProp` throw when nothing
+   matches, naming the tag or the prop they looked for, so `getByProp("text", "Play")` on
+   its own already fails the test if that label is absent. Wrapping it in an `expect` adds
+   a line and no information. Reach for `queryByProp` only when absence is the thing being
+   asserted, and then assert on the `null` it returns.
+
+4. **Drive input through the key handler node.** Focus and key routing in this SDK end at a
+   `key-handler` node, so `getByTag("key-handler")` is the entry point for a press, and the
+   payload is `{ key, press }` — `press: true` is the key going down, `false` its release.
+   Key names are Roku's: `up`, `down`, `left`, `right`, `OK`, `back`. `fireEvent` is async
+   and awaits the resulting commit, so `await` it and then assert directly.
+
+5. **Snapshot with `toString(2)`**, which serializes the tree with an indent of two and
+   omits internal node references. It is the whole rendered structure, so it is the right
+   tool for "this component still builds what it built" and the wrong one for a single
+   value — a snapshot that changes on every edit stops being read.
+
+6. **`dispose()` at the end of every test.** It tears the tree down and releases the
+   renderer. Tests that skip it leak state into the next one, and the failure shows up in
+   whichever test runs after, not in the one that caused it. It is Solid's disposer and
+   returns nothing, so awaiting it is a no-op that reads as though it were async.
+
+## Example
+
+```tsx rsg-skill=complete
+/// <reference types="jest" />
+
+import { Label, LayoutGroup } from "@roku-sdk/components";
+import type { AnchorNodeDescriptor, AnchorNodeImplementation } from "@roku-sdk/rsg-ts";
+import { defineAnchorNode } from "@roku-sdk/rsg-ts";
+import { render, TestAnchorNode } from "@roku-sdk/testing-library";
+
+const GreetingDescriptor: AnchorNodeDescriptor = {
+    componentName: "Greeting",
+    extends: "Group" as const,
+    inputFields: {},
+    outputFields: {}
+};
+
+const GreetingImpl: AnchorNodeImplementation<typeof GreetingDescriptor> = () => (
+    <layoutGroup layoutDirection="vert">
+        <label id="titleLabel" text="Hello" width={1920} height={100} />
+    </layoutGroup>
+);
+
+const Greeting = defineAnchorNode(GreetingDescriptor, GreetingImpl);
+const TestGreeting = TestAnchorNode(Greeting);
+
+describe("Greeting", () => {
+    test("renders the title", async () => {
+        const { getByProp, toString, dispose } = await render(() => <TestGreeting />);
+
+        // Throws when absent, so this line is the assertion.
+        getByProp("text", "Hello");
+        getByProp("id", "titleLabel");
+        expect(toString(2)).toMatchSnapshot();
+
+        dispose();
+    });
+
+    test("renders no subtitle", async () => {
+        const { queryByProp, dispose } = await render(() => <TestGreeting />);
+
+        // The tolerant form, because absence is what is being asserted.
+        expect(queryByProp("id", "subtitleLabel")).toBeNull();
+
+        dispose();
+    });
+});
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `getByProp is not a function`, or every query is `undefined` | `render` was called without `await` | `const view = await render(...)` |
+| `No node found with tag name: ...` on a node that is plainly in the JSX | The node's tag is the SceneGraph name, not the component's | Snapshot the tree with `toString(2)` once and read the tags off it |
+| `getAllByProp is not a function` | It does not exist — the `All` forms are tag-only | Use `getAllByTag`, or `queryAllByTag` and filter on `props(node)` |
+| An assertion reads the value from before the event | The commit had not been applied yet | See `references/async-and-timing.md` |
+| A test passes alone and fails in the suite | A previous test never disposed | `dispose()` at the end of every test |
+| The snapshot file churns on unrelated edits | A whole-tree snapshot is standing in for a value assertion | Snapshot once for structure; assert values with `getByProp` |

package/skills/testing/references/async-and-timing.md

@@ -0,0 +1,97 @@
+# Async and timing in a component test
+
+The symptom is always the same: an assertion reads a prop, gets the value from before the
+thing that was supposed to change it, and the app is demonstrably correct when run. The
+cause is that renders are committed in a batch. A prop write does not land on the node the
+moment the signal changes; it is queued, and the queue is flushed on a commit. Between
+those two points the tree still holds the old value, and a query run there reads it.
+
+`render` and `fireEvent` both await that flush for you, which is why most tests never meet
+this. It surfaces where the change is triggered by something else.
+
+## The two fixes, in order of preference
+
+**1. Await the call that caused the change.** Both entry points are already async and
+already flush:
+
+```tsx
+import { render, TestAnchorNode } from "@roku-sdk/testing-library";
+
+import App from "./app";
+
+const TestApp = TestAnchorNode(App);
+
+const view = await render(() => <TestApp />);
+await view.fireEvent(view.getByTag("key-handler"), "onKeyEvent", { key: "right", press: true });
+// The tree is committed here. Assert directly.
+view.getByProp("text", "Focused: 1");
+```
+
+An un-awaited `fireEvent` is the single most common source of a stale read, and it is
+silent: the call still fires, the assertion still runs, and it simply runs early.
+
+**2. Flush explicitly with `transaction()`** when the change came from somewhere the test
+did not await — a signal the test set directly, a callback the component invoked, a promise
+the component under test kicked off:
+
+```tsx
+// Same `view` as above.
+setItems(["a", "b"]);
+await view.transaction();
+view.getByProp("text", "2 items");
+```
+
+`transaction()` resolves when the queued commit has been applied. That is all it does. It
+does not wait for a network call, a timer, or any promise the component is holding, so it
+is the fix for a batching problem and never for a slow one.
+
+## There is no `waitFor` and no `findBy*`
+
+This library ships neither, deliberately: both exist to paper over an unknown settling time,
+and in a tree with an explicit commit there is not one to guess at. If an assertion needs a
+retry loop, something in the component is genuinely asynchronous, and the test should await
+that thing rather than poll the tree. Expose it — resolve a promise the test holds, or call
+a callback the test passed in — and await that, then `transaction()`.
+
+Where a component's own promise cannot be reached, yielding to the microtask queue before
+flushing is the honest last resort, and it belongs in the one test that needs it rather
+than in shared setup:
+
+```tsx
+await Promise.resolve();
+await view.transaction();
+```
+
+## Fake timers do not flush a commit
+
+The commit is scheduled as a microtask, not on a timer, so `jest.advanceTimersByTime` does
+not make a queued prop write land. A test with fake timers on still awaits the flush the
+same way every other test does:
+
+```tsx
+import { render, TestAnchorNode } from "@roku-sdk/testing-library";
+
+import App from "./app";
+
+const TestApp = TestAnchorNode(App);
+
+jest.useFakeTimers();
+
+const view = await render(() => <TestApp />);
+jest.advanceTimersByTime(5000);
+// The timer's callback ran; its effect on the tree has not landed yet.
+await view.transaction();
+view.getByProp("text", "Timed out");
+```
+
+The shared Jest setup in `@roku-sdk/dev-tools` leaves real timers in place and restores them
+after each test that turns them on, so a test opts in and does not have to clean up by hand.
+Opt in only when the component reads the clock. For a value that is merely late, fake timers
+are the wrong tool: the commit is not waiting on a timer, so advancing one changes nothing.
+
+## Disposal is part of timing
+
+`dispose()` tears the tree down. It is Solid's disposer and returns nothing, so there is
+nothing to await. Skipping it leaves a live tree behind, and the reactive work it is still
+doing lands during whichever test runs next — which is why "passes alone, fails in the
+suite" is nearly always a missing `dispose`, and why the failure names the wrong test.

package/skills/user-accounts-and-purchases/SKILL.md

@@ -0,0 +1,164 @@
+# Viewer accounts and in-channel purchases
+
+## Overview
+
+`ChannelStore` from `@roku-sdk/components` is the one component that reaches Roku's account
+and commerce services. It covers three jobs: reading who the viewer is, remembering them
+across their devices, and selling them something.
+
+It is **not called like a function**. You render one, put the input on a data prop, register
+the handler the answer will arrive on, and then set `command`. The result comes back
+asynchronously on that handler, never as a return value. Everything below follows from that.
+
+## When to Use
+
+| If the request is | Then |
+|---|---|
+| Reading the viewer's Roku account details to pre-fill a form | Here |
+| Remembering a signed-in viewer so their next device does not ask again | Here |
+| Proving to your own backend that a request came from a real Roku | Here |
+| Listing, selling or confirming something inside the channel | Here |
+| An auth gate in front of content, driven by whether a stored credential came back | Here |
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Signing a build, uploading a version, or the beta channel | The `app-packaging` skill | Those are about shipping the app. This is about the viewer using it. The word "channel" appears on both sides and means different things |
+| Installing SDK packages with `pnpm` | The `sdk-installation` skill | That brings dependencies into the app; it does not authenticate a viewer |
+| A Roku's developer password, or which box a command reaches | The `device-management` skill | Also a developer credential. Nothing here reads or writes it |
+| Calling your own partner API over the network | The `fetch-and-data-loading` skill | Use that for your backend, and this only for what Roku itself holds. The attestation token below is the bridge between them |
+| How to spell the component, or why it keeps its backing asset | The `sdk-components` skill | That skill owns the spelling table and the tree-shaking rule |
+
+**Viewer credentials and developer credentials are different things** and three skills own the
+second kind. Nothing in this skill touches a signing password, a registry token or a box's
+developer password.
+
+## Quick Reference
+
+Eleven commands, plus `"none"`. Each result arrives on its own handler prop.
+
+| Job | Command | Result arrives on |
+|---|---|---|
+| Who is this viewer | `getUserData` | `onUserDataObject` |
+| Where are they | `getUserRegionData` | `onUserRegionDataObject` |
+| Remember them | `storeChannelCredData` | `onStoreChannelCredDataStatusObject` |
+| Are they already known | `getChannelCred` | `onChannelCredObject` |
+| What can I sell | `getCatalog` | `onCatalogObject` |
+| Sell it | `doOrder` | `onOrderStatusObject` |
+| What do they own | `getPurchases` / `getAllPurchases` | `onPurchasesObject` — **and the status separately on `onPurchasesStatusObject`** |
+| Partner-billed order | `requestPartnerOrder` / `confirmPartnerOrder` | `onRequestPartnerOrderStatusObject` / `onConfirmPartnerOrderStatusObject` |
+| Prove the box is genuine | `getDeviceAttestationToken` | `onDeviceAttestationTokenObject` |
+| Idle | `"none"` | — |
+
+Input props that pair with them: `requestedUserData` (`"all"`, or a comma-separated list such
+as `"email,firstname,lastname"`), `channelCredData`, `orderObject`, `deltaOrder`,
+`requestPartnerOrderObject`, `confirmPartnerOrderObject`.
+
+## Instructions
+
+1. **Render one `ChannelStore` and drive `command` from a signal.** Start it at `"none"`. One
+   instance serves every command; there is no need for one per operation.
+
+2. **Set the data prop before you set the command.** The component reads its inputs when the
+   command changes, so a command set in the same breath as its data may act on the previous
+   value. Set the data signal, then the command signal.
+
+3. **Return `command` to `"none"` once a result has arrived.** It is the idle value, and it is
+   how the next request of the same kind is distinguishable from the last one. Left on the
+   previous command, a re-request can look like nothing happened.
+
+4. **Read the answer only on the matching handler.** Every result is
+   `(event: T) => void` — a plain callback, not a promise — so the code that reacts to a
+   command lives beside the render rather than after the call.
+
+5. **Ask for the narrowest `requestedUserData` you need.** `"all"` returns the whole profile.
+   A comma-separated list returns only those fields, which is both less to handle and less
+   to justify.
+
+6. **Adjust a basket with `deltaOrder`, not by rebuilding `orderObject`.** It applies one
+   change on its own, and a **negative quantity removes** rather than adding a negative line.
+
+7. **Read the result's `status`, and expect the credential as a string.** Every result
+   carries `status`, where **0 means success** — an arrived handler is not the same as a
+   successful command. Purchases are the one command that splits the two apart: the data
+   arrives on `onPurchasesObject` and the status on `onPurchasesStatusObject`, so a failed
+   request shows up as a status rather than as an empty list. And `getChannelCred` returns the credential as a **JSON string** in
+   `json`, not as structured fields, so it has to be parsed.
+
+8. **Treat `getChannelCred` as the auth gate.** On launch, ask; if a credential comes back,
+   the viewer is known and no sign-in screen is needed. If nothing does, show one, and store
+   the result with `storeChannelCredData` so the next device skips it.
+
+9. **Send the attestation token to your backend, not to your own logic.** It is a signed JWT
+   whose point is that a server can verify it. Checking it inside the app proves nothing,
+   because anything that can fake the request can fake the check.
+
+## Example
+
+The auth gate: ask on launch, and store what a sign-in produced.
+
+```tsx rsg-skill=complete
+import { ChannelStore, ChannelStoreCommand, IChannelCred, IStoreChannelCredDataStatus } from "@roku-sdk/components";
+import { Component, createSignal, onMount } from "@roku-sdk/solid";
+
+export const AuthGate: Component = () => {
+    const [command, setCommand] = createSignal<ChannelStoreCommand>("none");
+    const [credData, setCredData] = createSignal("");
+    const [known, setKnown] = createSignal<boolean | undefined>(undefined);
+
+    onMount(() => setCommand("getChannelCred"));
+
+    const onCred = (event: IChannelCred) => {
+        // `status` 0 is success. The credential itself is a JSON *string* in `json`.
+        setKnown(event.status === 0);
+        setCommand("none");
+    };
+
+    const onStored = (event: IStoreChannelCredDataStatus) => {
+        setKnown(event.status === 0);
+        setCommand("none");
+    };
+
+    return (
+        <group>
+            <ChannelStore
+                command={command()}
+                channelCredData={credData()}
+                onChannelCredObject={onCred}
+                onStoreChannelCredDataStatusObject={onStored}
+            />
+            <label
+                text={known() === undefined ? "checking" : known() ? "welcome back" : "please sign in"}
+                translation={[96, 96]}
+            />
+            <label text={credData() === "" ? "" : "credential pending"} translation={[96, 160]} />
+        </group>
+    );
+};
+
+/** Wire this to whatever your sign-in screen produces. */
+export function rememberViewer(setCredData: (v: string) => void, setCommand: (c: ChannelStoreCommand) => void) {
+    return (token: string) => {
+        setCredData(token); // data first
+        setCommand("storeChannelCredData"); // then the command
+    };
+}
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| A command acts on the previous value | Data and command were set together, and the component read its inputs on the change | Set the data prop first, then the command |
+| Re-issuing the same command appears to do nothing | `command` never returned to `"none"`, so there was no change to react to | Reset it to `"none"` in the handler |
+| The handler never fires | The result was expected as a return value, or the wrong handler prop was wired | Each command has exactly one handler prop — match them from the table above |
+| A basket ends up with a negative line | A removal was expressed by adding a negative entry to `orderObject` | A negative quantity on `deltaOrder` is the removal |
+| The whole profile arrives when two fields were wanted | `requestedUserData` was left at `"all"` | Pass the comma-separated list instead |
+| An attestation check passes for a forged request | The token was verified inside the app | Verify it on a server. In-app verification is not a check |
+| A viewer is asked to sign in on every device | The credential was kept in app state rather than stored | `storeChannelCredData` puts it where the viewer's other boxes can read it |
+
+`ChannelStore` is backed by a BrightScript XML extension rather than a native SceneGraph node,
+which is why it behaves like a service rather than a view — it draws nothing. Every prop and
+result type is documented with TSDoc in `@roku-sdk/components`; read a field's exact shape
+there rather than inferring it from here.