@roku-sdk/ai 2.18.0 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roku-sdk/ai",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "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.0"
   },
   "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