@roku-sdk/ai 2.18.0 → 2.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roku-sdk/ai",
-  "version": "2.18.0",
+  "version": "2.19.1",
   "description": "AI skills library and manifest for the Roku RSG TypeScript SDK",
   "type": "module",
   "main": "src/index.ts",
@@ -19,13 +19,13 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "zod": "^3.23.8"
+    "zod": "^4.6.6"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.1",
-    "@roku-sdk/dev-tools": "2.18.0"
+    "@roku-sdk/dev-tools": "2.19.1"
   },
   "author": "Roku Inc",
   "license": "MIT",

package/skills/effects/SKILL.md

@@ -103,11 +103,13 @@ const pulse = <effect id="tile-pulse" borderRadius={24} borderWidth={2} borderCo
 6. **An Effect clips nothing.** A child of a rounded `Rectangle` can paint into and past the
    corners. Lay children out inside the rounded area; to clip them to a shape, use `MaskGroup`.
 
-7. **Know the fields that fail silently.** A gradient draws nothing while `gradientStyle` is
-   `"none"`, its default, or with fewer than two or more than eight `gradientColors`.
-   `gradientStops` needs one entry per colour, and a mismatch is not reported. `borderPadding` is
-   the gap between the border and the content, so with `borderWidth` at `0` it changes nothing —
-   inset a child with layout instead. `gradientFillContent` defaults to `true` and
+7. **Know the fields that fail silently on device.** A gradient draws nothing while
+   `gradientStyle` is `"none"`, its default, or with fewer than two or more than eight
+   `gradientColors`. `gradientStops` needs one entry per colour in `[0, 1]`. In `__DEV__` builds
+   the SDK warns once per distinct problem (and stays quiet while `gradientStyle` is `"none"`,
+   including empty colors/stops). `borderPadding` is the gap between the border and the content,
+   so with `borderWidth` at `0` it changes nothing — inset a child with layout instead.
+   `gradientFillContent` defaults to `true` and
    `gradientFillBorder` to `false`.
 
 8. **`setPropMethod("effect")` is not how you share.** It builds a property descriptor for

package/skills/focus-management/SKILL.md

@@ -57,7 +57,7 @@ Use this whenever the question is which item is focused, or what a key press doe
 | 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` |
+| Mark the item an inactive region will return to — dialog open, or focus in another region | `hasFootprint()` from `useFocusable`; `hasReturnFootprint()` when nested regions or `rememberLastFocus={false}` must mark only where focus will land, and `useFocusActions().hasReturnFootprint()` for the region itself |
 
 ## Instructions
 
@@ -70,6 +70,11 @@ app's other `@roku-sdk/*` packages are on — or every import below fails to res
    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`.
 
+   For TypeScript descriptors, keep `FocusBoundaryBase`: registration selects the native
+   component when firmware reports `hasFeature("focusBoundaryBase")`, otherwise
+   `FocusBoundaryBaseShim`. XML/BrightScript does not go through that remap: extend or
+   create `FocusBoundaryBaseShim` by name to keep working on existing firmware.
+
 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.

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

@@ -271,6 +271,14 @@ sibling region is another. A row styled from it therefore keeps its subdued mark
 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.
 
+It is also evaluated against its own boundary alone, so a nested region focus will not pass back
+through keeps marking its last child, and so does a region with `rememberLastFocus={false}` that
+will reopen at `initialFocus`. When only items focus will actually land on should be marked,
+use `hasReturnFootprint()` from `useFocusable` instead; `useFocusActions().hasReturnFootprint()`
+answers the same question for the whole region. Each dormant sibling region under the nearest
+active ancestor still marks its own item — the one focus reaches when the user moves there — so
+the tree shows a single footprint only while the root itself is inactive.
+
 ### Common mistakes
 
 | Symptom | Cause | Fix |

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

@@ -48,6 +48,7 @@ mistake here that compiles.
 | 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 |
+| Wait until a font can be measured | `whenFontReady(ref)` or `createFontReady(fontRef)` from `@roku-sdk/rsg-ts/runtime` — never a fixed timer |
 | 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 |
@@ -110,6 +111,59 @@ mistake here that compiles.
    firmware's own string layer, not TypeScript symbols; putting one in a label renders the braces
    literally. Interpolate the imported constant instead.
 
+10. **Wait for a font with `whenFontReady`, not a timer.** `getFontMeasure()` throws
+    `"Font is not yet loaded"` until the GfxFont is published. Current firmware has no Font
+    `loadStatus` field; use `whenFontReady(ref)` (promise) or `createFontReady(fontRef)`
+    (Solid accessor that cancels on cleanup; pass `() => props.uri` or similar as its second
+    argument when the `<font>` node's `uri` or `size` can change) from `@roku-sdk/rsg-ts/runtime`, which keep
+    working when one ships. Do not copy the fixed 100ms / 500ms timer stubs from older
+    examples — those race on a cold cache. A `<font>` that is not on a drawn label is only
+    published if `preUpdate` is set before `uri` and `size`; without it the font never loads
+    and the wait never resolves.
+
+## Measuring a font
+
+`whenFontReady` and `createFontReady` ship in SDK 2.19.0. On 2.18.0 and earlier they are
+not exported from `@roku-sdk/rsg-ts/runtime`.
+
+Capture the Font node's `TmNodeRef` from `ref={node => … node.r}`, then wait before measuring:
+
+```tsx rsg-skill=complete
+import { getFontMeasure, whenFontReady, createFontReady } from "@roku-sdk/rsg-ts/runtime";
+import { createEffect, createSignal, type Component } from "@roku-sdk/solid";
+import type { TmNodeRef } from "@roku-sdk/interfaces";
+
+export const MeasuredTitle: Component<{ text: string; uri: string }> = props => {
+    const [fontRef, setFontRef] = createSignal<TmNodeRef>();
+    // The key restarts the wait when `uri` changes on this same <font> node.
+    const fontReady = createFontReady(fontRef, () => props.uri);
+    const [width, setWidth] = createSignal(0);
+
+    createEffect(() => {
+        if (!fontReady()) return;
+        const ref = fontRef();
+        if (!ref) return;
+        setWidth(getFontMeasure().getOneLineWidth(ref, props.text, 1920));
+    });
+
+    return (
+        <label
+            text={props.text}
+            width={width() || 600}
+            height={48}
+            color="0xFFFFFFFF"
+            font={<font uri={props.uri} size={32} ref={node => setFontRef(node.r)} />}
+        />
+    );
+};
+
+// Imperative form (same wait, no Solid helper):
+async function measureOnce(ref: TmNodeRef, text: string): Promise<number> {
+    await whenFontReady(ref);
+    return getFontMeasure().getOneLineWidth(ref, text, 1920);
+}
+```
+
 ## Example
 
 A row of chevrons and a rating, using a bundled typeface — imported, sized, and with a fallback
@@ -169,6 +223,7 @@ Keyed by what you see on screen, because that is what arrives first.
 | 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 |
+| `getFontMeasure` throws `"Font is not yet loaded"` or returns 0 | Measured before the GfxFont published; a fixed timer was too short | `await whenFontReady(ref)` or `createFontReady(fontRef)` — never a fixed timer |
 
 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

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");
     });