@roku-sdk/ai 2.19.0 → 2.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roku-sdk/ai",
-  "version": "2.19.0",
+  "version": "2.19.1",
   "description": "AI skills library and manifest for the Roku RSG TypeScript SDK",
   "type": "module",
   "main": "src/index.ts",
@@ -25,7 +25,7 @@
     "@jest/globals": "^30.4.1",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.1",
-    "@roku-sdk/dev-tools": "2.19.0"
+    "@roku-sdk/dev-tools": "2.19.1"
   },
   "author": "Roku Inc",
   "license": "MIT",

package/skills/mcp-ai-dev-loop/SKILL.md

@@ -58,7 +58,7 @@ that session's whole life, and the reference is how you reach a frame worth read
 | Sideload an existing artifact | `sideload_app` | Does not build. Reads the directory you point it at |
 | See the screen | `capture_screen` | Returns an image, and writes a file |
 | Read the node tree | `ecp` with `command: "query/app-ui"` | The rendered tree of the running app, as JSON |
-| Read device facts | `ecp` with `command: "query/device-info"` | Model, firmware, resolution |
+| Read device facts | `ecp` with `command: "query/device-info"` | Model, firmware, resolution; an SDK app needs `software-version` 16.0 or later |
 | Press a key | `ecp` with `command: "keypress"` | One key |
 | Press several | `ecp` with `command: "keysequence"` | One call for a whole path through the UI. Prefer it over a run of single presses |
 | Name a key for either of those | The **wire** name, not the runtime one | `Select` (not `OK`), `Rev` (not `rewind`), `Fwd` (not `fastforward`), `Info` (not `options`). Every element is validated before anything reaches the device, so one wrong name fails the whole call with `ECP_INVALID_KEY` |
@@ -102,7 +102,8 @@ that session's whole life, and the reference is how you reach a frame worth read
    actually found. A project that sets `outDir` in `roku-config.ts` avoids the split entirely:
    the sideload path reads project config, so an `outDir` from config or from the parameter is
    treated as deliberate and draws no warning. Sideloading Hermes bytecode (`index.hbc`) also
-   returns a warning, since a device without the `rsg_typescript` token refuses to launch it.
+   returns a warning, since a device without the `rsg_typescript` token refuses to launch it, and so does
+   installing to a device older than Roku OS 16.0, naming the version it runs.
 
 5. **Never reach the device's network endpoints yourself.** No `curl`, no hand-built request
    to a device port. The tools carry the device's password, retry sensibly and report failure
@@ -178,6 +179,7 @@ observation after that point describes a device that is no longer running your a
 | The device is running older code than the source | `build_app` wrote `dist-build` and a bare `sideload_app` read `dist-dev` | Use `deploy_app`, or pass `outDir: "dist-build"` to `sideload_app`. The sideload now warns when the directory it read is older than the other one |
 | A tool reports no device | Nothing registered, or nothing active | `list_devices`, then `activate_device`; `add_device` if the list is empty |
 | Sideloading is refused | Developer mode is off, or the device password is wrong | Enable developer mode on the box, then set the password with `update_default_auth` |
+| The install succeeds but the app never runs, on a box where other apps do | The device is on a Roku OS older than 16.0, the minimum an SDK app needs | The install's `warnings` name the version; otherwise `ecp` with `command: "query/device-info"` and read `software-version`. The device's software has to be updated, which no tool does |
 | `logs` fails before it reads anything | It requires server mode, and there was no session | Start `rk server`, then `logs` with `action: "start"` before `get` or `search` |
 | Keys appear to do nothing | The app crashed, or focus is not where you assumed | `capture_screen`, then `ecp` with `query/app-ui`; check the logs for an exception |
 | A screenshot looks right but the test of it fails | Measured in device pixels, compared against design coordinates | Convert before comparing |

package/skills/project-setup/SKILL.md

@@ -7,6 +7,10 @@ runs. Five things then own the project: `roku-config.ts` (app config and manifes
 `tsconfig.json` (one `extends` line), `package.json` (the `@roku-sdk/*` dependencies),
 `src/` (TypeScript and imported images) and `pkg/` (static assets copied verbatim).
 
+An SDK app runs on **Roku OS 16.0 or later**. Below 16.0 a device runs one only with a
+Roku-issued authorization token, so update the device's software rather than working around
+it. A feature with a higher floor of its own says so where it is documented.
+
 ## Read the reference first for these tasks
 
 | If the request is | Read now, before answering |
@@ -28,6 +32,7 @@ there is nothing in it to answer from.
 - the app's TypeScript setup is wrong: JSX or SDK types not resolving
 - declaration generation stops on an XML component base the SDK does not map, or whether built-in mappings still apply alongside yours in `dtsOptions`
 - `rk` cannot find the config, or a first run on a device is not working yet
+- which Roku OS version a device needs before an app will run on it
 
 ### When not to use
 
@@ -46,6 +51,7 @@ there is nothing in it to answer from.
 | Task | Do this |
 |---|---|
 | Create an app | `npx rk create my-app` — name lowercase, letters, digits, hyphens |
+| Check a device can run the app | `npx rk ecp query/device-info --json` — `software-version` must be 16.0 or later |
 | Change title, version, splash, resolutions | `manifestEntries` in `roku-config.ts` |
 | An XML base declaration generation does not recognise | `dtsOptions.componentMapping` in `roku-config.ts`; keep sibling `includeDefaults` on so the SDK's own mappings still merge |
 | Configure anything else in `roku-config.ts` | `references/roku-config.md` — the field names are only there |
@@ -202,6 +208,7 @@ and that direction belongs to the `mcp-ai-dev-loop` skill.
 | `.roku/` is git-ignored but `rk` still warns that it is not | The check recognises `.roku`, `/.roku`, `.roku/` and `/.roku/`, and no other pattern | Use one of those four forms rather than a glob such as `**/.roku` |
 | The build stops on an XML component whose base the declaration generation does not recognise, and no SDK version ever mapped it | The base is the app's own, so only the app can declare it | Add it under `dtsOptions.componentMapping` in `roku-config.ts`, and leave the sibling `includeDefaults` on so the SDK's own mappings still merge in |
 | `rk` cannot find the config | It walks up from the current directory | Run from inside the app, or pass `--config` |
+| The app builds, but the device will not run it | The device is on a Roku OS older than 16.0 | Read `software-version` from `npx rk ecp query/device-info`; update the device's software, then install again |
 | The build fails on something the installed version handles — a base component the SDK maps itself, a define it sets itself — or otherwise behaves like an older SDK | `rk` prefers a running `rk server`, which executes the build with the tooling it loaded at startup, from whatever project it was started in. Reinstalling the app's packages cannot change code already resident in that process | `rk server status` to see it, `rk server stop` then start it again from this app, or pass `--local` to skip server discovery for one command |
 | A package you import is missing at build time | pnpm does not hoist it in | Declare it in the app's own `package.json` |
 | An import of `solid-js` does not resolve, or its API does nothing on the device | `solid-js` belongs to `@roku-sdk/solid`, not to the app, and only the re-exported part drives the SceneGraph renderer | Import from `@roku-sdk/solid` |

package/skills-manifest.json

@@ -125,12 +125,14 @@
     },
     {
       "name": "project-setup",
-      "description": "Use when an RSG SDK TypeScript app has to be created or its project-level configuration is wrong \u2014 scaffolding a new app, what roku-config.ts owns (title, version, splash, manifest entries, and dtsOptions such as includeDefaults when declaration generation does not recognise an XML base), the app's tsconfig.json, which @roku-sdk packages the app must list because its own code imports them, what the scaffold's .gitignore covers after rk create, or where a file such as an image has to live before it can be imported in code. Not for resolving SDK packages from npmjs.com, which version line installs, or a peer an SDK package requires the app to declare, which is the sdk-installation skill's subject.",
+      "description": "Use when an RSG SDK TypeScript app has to be created or its project-level configuration is wrong \u2014 scaffolding a new app, what roku-config.ts owns (title, version, splash, manifest entries, and dtsOptions such as includeDefaults when declaration generation does not recognise an XML base), the app's tsconfig.json, which @roku-sdk packages the app must list because its own code imports them, what the scaffold's .gitignore covers after rk create, which Roku OS version a device needs before an app runs on it (16.0 or later), or where a file such as an image has to live before it can be imported in code. Not for resolving SDK packages from npmjs.com, which version line installs, or a peer an SDK package requires the app to declare, which is the sdk-installation skill's subject.",
       "triggers": [
         "roku-config",
         "scaffold",
         "tsconfig",
-        "rk create"
+        "rk create",
+        "minimum roku os",
+        "roku os version"
       ],
       "path": "skills/project-setup/SKILL.md",
       "references": [

package/src/__tests__/trigger-routing.test.ts

@@ -30,6 +30,12 @@ describe("trigger routing — shipped manifest routes cleanly", () => {
         expect(router.route("FocusBoundary")).toBe("focus-management");
     });
 
+    it("routes a question about the minimum Roku OS to project-setup", () => {
+        const router = buildRouter(shippedManifest());
+        expect(router.route("minimum Roku OS")).toBe("project-setup");
+        expect(router.route("Roku OS version")).toBe("project-setup");
+    });
+
     it("routes case-insensitively", () => {
         expect(route(shippedManifest(), "FOCUS")).toBe("focus-management");
     });