@roku-sdk/components 2.18.0 → 2.19.1

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@roku-sdk/components",
-  "version": "2.18.0",
+  "version": "2.19.1",
   "description": "Roku SceneGraph Solid components",
   "sideEffects": [
     "src/**/*.brs",
     "src/sg-nodes/animation.tsx",
     "src/sg-nodes/audio.tsx",
+    "src/sg-nodes/effect.tsx",
     "src/sg-nodes/sound-effect.tsx",
     "src/sg-nodes/video.tsx"
   ],
@@ -47,20 +48,20 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@roku-sdk/common": "2.18.0",
-    "@roku-sdk/runtime": "2.18.0",
-    "@roku-sdk/solid": "2.18.0",
-    "@roku-sdk/navigation": "2.18.0",
-    "@roku-sdk/interfaces": "2.18.0"
+    "@roku-sdk/common": "2.19.1",
+    "@roku-sdk/interfaces": "2.19.1",
+    "@roku-sdk/navigation": "2.19.1",
+    "@roku-sdk/solid": "2.19.1",
+    "@roku-sdk/runtime": "2.19.1"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.1",
     "jest-transform-stub": "^2.0.0",
-    "@roku-sdk/dev-tools": "2.18.0",
-    "@roku-sdk/testing-library": "2.18.0",
-    "@roku-sdk/compat": "2.18.0"
+    "@roku-sdk/dev-tools": "2.19.1",
+    "@roku-sdk/testing-library": "2.19.1",
+    "@roku-sdk/compat": "2.19.1"
   },
   "author": "Roku Inc",
   "license": "MIT",

package/src/__tests__/effect-gradient-validation.test.tsx

@@ -0,0 +1,133 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+// ---------------------------------------------------------------------------
+// Effect warns in __DEV__ when gradientColors / gradientStops violate the firmware
+// constraints (2–8 colors, stops length and [0, 1] range) while gradientStyle is not
+// "none". Quiet for valid gradients and for style "none" with empty arrays (effects-lab
+// edit-demo). Each distinct problem is reported once per node; nothing without __DEV__.
+// ---------------------------------------------------------------------------
+
+import "@roku-sdk/compat";
+
+import { afterEach, beforeEach, describe, expect, jest, test } from "@jest/globals";
+import { createSignal, type JSX } from "@roku-sdk/solid";
+
+import { Effect, installEffectGradientDevValidation } from "../sg-nodes/effect";
+import { commitEarly, createAnchorNode, installSolidTestRenderer } from "../test-helpers/tween-test-setup";
+
+async function flushMicrotasks(): Promise<void> {
+    await Promise.resolve();
+    await Promise.resolve();
+}
+
+describe("Effect gradient prop warning (dev only)", () => {
+    let render: ReturnType<typeof installSolidTestRenderer>;
+    let warn: jest.SpiedFunction<typeof console.warn>;
+    let realDev: boolean | undefined;
+    let dispose: (() => void) | undefined;
+
+    beforeEach(() => {
+        realDev = (globalThis as { __DEV__?: boolean }).__DEV__;
+        (globalThis as { __DEV__?: boolean }).__DEV__ = true;
+        installEffectGradientDevValidation();
+        render = installSolidTestRenderer();
+        warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        dispose?.();
+        dispose = undefined;
+        (globalThis as { __DEV__?: boolean }).__DEV__ = realDev;
+        warn.mockRestore();
+    });
+
+    const mount = (element: JSX.Element): void => {
+        dispose = render(() => <group>{element}</group>, createAnchorNode());
+        commitEarly();
+    };
+
+    const effectWarnings = (): string[] =>
+        warn.mock.calls.map(c => String(c[0])).filter(message => message.startsWith("Effect"));
+
+    test("warns when gradientColors has fewer than 2 entries", async () => {
+        mount(<effect gradientStyle="linear" gradientColors={["0xFF0000FF"]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([
+            'Effect: gradientColors must have 2–8 entries when gradientStyle is "linear" (got 1).'
+        ]);
+    });
+
+    test("warns when gradientColors has more than 8 entries", async () => {
+        const colors = Array.from({ length: 9 }, (_, i) => `0xFF00000${i}`);
+        mount(<effect gradientStyle="radial" gradientColors={colors} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([
+            'Effect: gradientColors must have 2–8 entries when gradientStyle is "radial" (got 9).'
+        ]);
+    });
+
+    test("warns when gradientStops length does not match gradientColors", async () => {
+        mount(
+            <effect gradientStyle="linear" gradientColors={["0xFF0000FF", "0x0000FFFF"]} gradientStops={[0, 0.5, 1]} />
+        );
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual(["Effect: gradientStops length (3) must equal gradientColors length (2)."]);
+    });
+
+    test("warns when a gradientStops entry is outside [0, 1]", async () => {
+        mount(<effect gradientStyle="linear" gradientColors={["0xFF0000FF", "0x0000FFFF"]} gradientStops={[0, 1.5]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual(["Effect: gradientStops entries must be in [0, 1] (got 1.5 at index 1)."]);
+    });
+
+    test("includes id in the warning when the effect has one", async () => {
+        mount(<effect id="hero-fill" gradientStyle="linear" gradientColors={["0xFF0000FF"]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([
+            'Effect[id=hero-fill]: gradientColors must have 2–8 entries when gradientStyle is "linear" (got 1).'
+        ]);
+    });
+
+    test("warns through the PascalCase Effect wrapper", async () => {
+        mount(<Effect gradientStyle="linear" gradientColors={["0xFF0000FF"]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([
+            'Effect: gradientColors must have 2–8 entries when gradientStyle is "linear" (got 1).'
+        ]);
+    });
+
+    test("is silent for a valid gradient", async () => {
+        mount(<effect gradientStyle="linear" gradientColors={["0xFF0000FF", "0x0000FFFF"]} gradientStops={[0, 1]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([]);
+    });
+
+    test("is silent for gradientStyle none with empty colors and stops (effects-lab edit-demo)", async () => {
+        mount(<effect gradientStyle="none" gradientColors={[]} gradientStops={[]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([]);
+    });
+
+    test("reports each distinct problem once per node across updates", async () => {
+        const [colors, setColors] = createSignal<string[]>(["0xFF0000FF"]);
+        mount(<effect gradientStyle="linear" gradientColors={colors()} />);
+        await flushMicrotasks();
+        setColors(["0xFF0000FF"]);
+        commitEarly();
+        await flushMicrotasks();
+        setColors(Array.from({ length: 9 }, (_, i) => `0xFF00000${i}`));
+        commitEarly();
+        await flushMicrotasks();
+        // Same key "colors:count" — still one warning even though the count changed.
+        expect(effectWarnings()).toEqual([
+            'Effect: gradientColors must have 2–8 entries when gradientStyle is "linear" (got 1).'
+        ]);
+    });
+
+    test("is silent without __DEV__", async () => {
+        (globalThis as { __DEV__?: boolean }).__DEV__ = false;
+        mount(<effect gradientStyle="linear" gradientColors={["0xFF0000FF"]} />);
+        await flushMicrotasks();
+        expect(effectWarnings()).toEqual([]);
+    });
+});

package/src/sg-nodes/__tests__/imperative-methods.test.ts

@@ -264,5 +264,13 @@ describe("imperative methods", () => {
             const unlisted = registrars.filter(file => !patterns.some(pattern => pattern.test(file)));
             expect(unlisted).toEqual([]);
         });
+
+        it("lists effect.tsx in sideEffects so the gradient dev observer is not tree-shaken", () => {
+            const { sideEffects } = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")) as {
+                sideEffects: string[];
+            };
+            const patterns = sideEffects.map(globToRegExp);
+            expect(patterns.some(pattern => pattern.test("src/sg-nodes/effect.tsx"))).toBe(true);
+        });
     });
 });

package/src/sg-nodes/content-node.props.ts

@@ -1303,7 +1303,7 @@ export interface IVideoContentNodeProps extends IContentNodeProps {
      *
      * Valid values: `"mp4"`, `"hls"`, `"ism"`, `"dash"`, `"mkv"`.
      *
-     * @remarks The RSG SDK does not currently wire this through for
+     * @remarks The RSG 2.0 SDK does not currently wire this through for
      * `VideoContentNode`; omit it and rely on URL / player behavior until support
      * lands.
      */

package/src/sg-nodes/content-node.tsx

@@ -129,7 +129,7 @@ export const ContentNode: Component<IContentNodeProps> = props => {
  * content with stream URL and format. Typically used as a child of a Video node.
  *
  * @remarks Assigning {@link IVideoContentNodeProps.streamformat} is not supported
- * by the RSG SDK yet; use `url` (and other forwarded fields) only.
+ * by the RSG 2.0 SDK yet; use `url` (and other forwarded fields) only.
  *
  * @example
  * ```tsx

package/src/sg-nodes/dialog.tsx

@@ -12,7 +12,7 @@ export type { IDialogProps } from "./dialog.props";
  * regions. Dialogs intercept all key events except Home and are closed automatically
  * by Back or Home.
  *
- * > **Note:** Consider using StandardDialog (Roku OS 10.0+) for new development, which
+ * > **Note:** Consider using StandardDialog for new development, which
  * > provides updated graphics and color palette support.
  *
  * @example

package/src/sg-nodes/effect.props.ts

@@ -39,7 +39,7 @@ export interface IEffectProps extends INodeProps {
      * Per-corner border radius in pixels.
      * - A single number applies a uniform radius to all corners.
      * - A four-element tuple sets each corner independently: `[topLeft, topRight, bottomRight, bottomLeft]`.
-     *   The tuple is one Vector4 field, so a `FloatFieldInterpolator` cannot animate it.
+     *   The tuple is one Vector4 field, so a FloatFieldInterpolator cannot animate it.
      * @default 0
      */
     borderRadius?: number | [number, number, number, number];
@@ -72,12 +72,15 @@ export interface IEffectProps extends INodeProps {
     /**
      * Ordered list of RGBA color stops for the gradient (e.g. `["0xFF0000FF", "0x0000FFFF"]`).
      * At least two colors are required for the gradient to render. Maximum of 8 colors.
+     * Outside that range the gradient does not render; in `__DEV__` builds the SDK warns once
+     * when `gradientStyle` is not `"none"`.
      */
     gradientColors?: string[];
 
     /**
      * Normalized stop positions `[0, 1]` corresponding to each entry in `gradientColors`.
-     * If omitted, colors are distributed evenly across the gradient. A length mismatch is not reported.
+     * If omitted, colors are distributed evenly across the gradient. In `__DEV__` builds the SDK
+     * warns once on a length mismatch or an entry outside `[0, 1]` when `gradientStyle` is not `"none"`.
      */
     gradientStops?: number[];
 

package/src/sg-nodes/effect.tsx

@@ -1,10 +1,140 @@
 // Copyright (c) 2026 Roku, Inc.
 // SPDX-License-Identifier: MIT
 
-import type { IEffectProps } from "./effect.props";
+import type { DomNode, TmValue } from "@roku-sdk/interfaces";
+import { registerSetPropertyObserver } from "@roku-sdk/solid";
+
+import type { GradientStyle, IEffectProps } from "./effect.props";
 import { Component } from "./types";
 export type { GradientStyle, IEffectProps } from "./effect.props";
 
+declare const __DEV__: boolean;
+
+const TRACKED_PROPS: ReadonlySet<string> = new Set(["gradientStyle", "gradientColors", "gradientStops", "id"]);
+
+interface EffectGradientState {
+    gradientStyle?: GradientStyle;
+    gradientColors?: string[];
+    gradientStops?: number[];
+    id?: string;
+    warned: Set<string>;
+    scheduled: boolean;
+}
+
+/**
+ * Dev-only: describe each way gradient props violate the firmware's silent constraints.
+ * Returns `[key, message]` pairs so a caller can report each distinct problem once.
+ *
+ * Quiet while `gradientStyle` is `"none"` or unset — authors may park empty colors/stops
+ * and turn the style on later (see apps/effects-lab edit-demo).
+ */
+function gradientPropProblems(
+    style: GradientStyle | undefined,
+    colors: readonly string[] | undefined,
+    stops: readonly number[] | undefined,
+    nodeLabel: string
+): [key: string, message: string][] {
+    if (style === undefined || style === "none") {
+        return [];
+    }
+
+    const problems: [string, string][] = [];
+    const colorList = Array.isArray(colors) ? colors : [];
+    const colorCount = colorList.length;
+
+    if (colorCount < 2 || colorCount > 8) {
+        problems.push([
+            "colors:count",
+            `${nodeLabel}: gradientColors must have 2–8 entries when gradientStyle is "${style}" (got ${colorCount}).`
+        ]);
+    }
+
+    if (stops !== undefined) {
+        const stopList = Array.isArray(stops) ? stops : [];
+        if (stopList.length !== colorCount) {
+            problems.push([
+                "stops:length",
+                `${nodeLabel}: gradientStops length (${stopList.length}) must equal gradientColors length (${colorCount}).`
+            ]);
+        }
+        const outOfRange = stopList.findIndex(stop => !(typeof stop === "number" && stop >= 0 && stop <= 1));
+        if (outOfRange !== -1) {
+            problems.push([
+                "stops:range",
+                `${nodeLabel}: gradientStops entries must be in [0, 1] (got ${String(stopList[outOfRange])} at index ${outOfRange}).`
+            ]);
+        }
+    }
+
+    return problems;
+}
+
+function nodeLabelFor(state: EffectGradientState): string {
+    return state.id !== undefined && state.id !== "" ? `Effect[id=${state.id}]` : "Effect";
+}
+
+let effectGradientObserverInstalled = false;
+
+/**
+ * Installs the `__DEV__` setProperty observer that validates Effect gradient props for both
+ * `<effect>` and `<Effect>`. Safe to call more than once; no-ops when `__DEV__` is off.
+ * Tests call this after enabling `__DEV__` because Jest loads modules with `__DEV__` false.
+ */
+export function installEffectGradientDevValidation(): void {
+    if (typeof __DEV__ === "undefined" || !__DEV__) return;
+    if (effectGradientObserverInstalled) return;
+    effectGradientObserverInstalled = true;
+
+    const stateByNode = new WeakMap<DomNode, EffectGradientState>();
+
+    registerSetPropertyObserver((node: DomNode, name: string, value: TmValue): void => {
+        if (typeof __DEV__ === "undefined" || !__DEV__) return;
+        if (node.t !== "effect") return;
+        if (!TRACKED_PROPS.has(name)) return;
+
+        let state = stateByNode.get(node);
+        if (!state) {
+            state = { warned: new Set(), scheduled: false };
+            stateByNode.set(node, state);
+        }
+
+        switch (name) {
+            case "gradientStyle":
+                state.gradientStyle = value as GradientStyle;
+                break;
+            case "gradientColors":
+                state.gradientColors = value as string[];
+                break;
+            case "gradientStops":
+                state.gradientStops = value as number[];
+                break;
+            case "id":
+                state.id = value as string;
+                break;
+        }
+
+        if (state.scheduled) return;
+        state.scheduled = true;
+        const pending = state;
+        queueMicrotask(() => {
+            pending.scheduled = false;
+            const label = nodeLabelFor(pending);
+            for (const [key, message] of gradientPropProblems(
+                pending.gradientStyle,
+                pending.gradientColors,
+                pending.gradientStops,
+                label
+            )) {
+                if (pending.warned.has(key)) continue;
+                pending.warned.add(key);
+                console.warn(message);
+            }
+        });
+    });
+}
+
+installEffectGradientDevValidation();
+
 /**
  * Effect applies GPU shader-based rendering to a Rectangle or Poster.
  *
@@ -12,9 +142,7 @@ export type { GradientStyle, IEffectProps } from "./effect.props";
  * Poster to enable rounded corners, borders, and gradient fills. Set
  * `shaderCompatible` on a Poster that takes one.
  *
- * Prefer the `<effect>` intrinsic for most uses. The `Effect` wrapper is a pure
- * passthrough (`<effect {...props} />`) and exists for consistency with the component
- * library.
+ * Prefer the `<effect>` intrinsic for most uses. The Effect wrapper is a pure passthrough (`<effect {...props} />`) and exists for consistency with the component library.
  *
  * {@includeCode ../../../../examples/showcase/src/components/showcases/effect-showcase/shared-effect-showcase.tsx#docs:effect-shared}
  *

package/src/sg-nodes/font.tsx

@@ -12,11 +12,11 @@ export type { IFontProps } from "./font.props";
  * be specified using the `font:` prefix (e.g., `font:MediumBoldSystemFont`).
  *
  * **Components that support Font:**
- * - `Label` / `MultiStyleLabel`: via `font` prop
- * - `ScrollableText`: via `font` prop
- * - `ScrollingLabel`: via `font` prop
- * - `LabelList`: via `font` and `focusedFont` props
- * - `PosterGrid`: via `caption1Font` and `caption2Font` props
+ * - Label / MultiStyleLabel: via `font` prop
+ * - ScrollableText: via `font` prop
+ * - ScrollingLabel: via `font` prop
+ * - LabelList: via `font` and `focusedFont` props
+ * - PosterGrid: via `caption1Font` and `caption2Font` props
  *
  * @see {@link https://developer.roku.com/dev/docs/font}
  *

package/src/sg-nodes/list-panel.props.ts

@@ -72,13 +72,12 @@ export interface IListPanelProps extends IPanelProps {
 }
 
 /**
- * Properties for the unmanaged SceneGraph ListPanel component.
+ * Properties for the raw `<listPanel>` SceneGraph element.
  *
- * This interface represents the raw ListPanel properties without the automatic
- * child management provided by the managed `ListPanel` component. It is used
- * internally and is not exposed to developers.
- *
- * @internal
+ * These are the {@link IListPanelProps} plus the `list` and `nextPanel` node fields, which the
+ * managed `ListPanel` component fills in from its children. They type the lower-case
+ * `listPanel` JSX intrinsic and the generated SceneGraph declarations. Prefer the managed
+ * `ListPanel` component; use the raw element only when you set `list` and `nextPanel` yourself.
  */
 export interface IFullPanelProps extends IListPanelProps {
     /**

package/src/sg-nodes/list-panel.tsx

@@ -16,7 +16,7 @@ export type { IListPanelProps, IFullPanelProps } from "./list-panel.props";
  * - Children extending `ArrayGrid` (LabelList, MarkupList) are automatically assigned to `list`
  * - Children extending `Panel` are automatically assigned to `nextPanel`
  *
- * Declare the list child **before** the panel child. The panel is matched to the row it was
+ * Declare the list child before the panel child. The panel is matched to the row it was
  * built for by consulting the list, so a panel declared first cannot be attributed to a row.
  *
  * While an asynchronously supplied `nextPanel` is still the previous row's, `ListPanel`
@@ -27,7 +27,7 @@ export type { IListPanelProps, IFullPanelProps } from "./list-panel.props";
  * its associated next panel as JSX children rather than explicit property assignments.
  *
  * @see {@link https://developer.roku.com/dev/docs/listpanel | Roku ListPanel Documentation}
- * @see **ListPanel, GridPanel Best Practices** at the internal RSG SDK documentation (knowledge-base/list-grid-panel-best-practice.md)
+ * @see **ListPanel, GridPanel Best Practices** at the internal RSG 2.0 SDK documentation (knowledge-base/list-grid-panel-best-practice.md)
  *
  * @example
  * ```tsx

package/src/sg-nodes/markup-list.props.ts

@@ -54,9 +54,7 @@ export interface IMarkupListProps extends IArrayGridProps {
     /**
      * Specifies the content for the list.
      *
-     * Should be a single root `ContentNode` with one child `ContentNode` per item.
-     * If the data contains section markers (`CONTENTTYPE="SECTION"`), section
-     * dividers will be drawn between each section, optionally with an icon and/or label.
+     * Should be a single root ContentNode with one child ContentNode per item. If the data contains section markers (`CONTENTTYPE="SECTION"`), section dividers will be drawn between each section, optionally with an icon and/or label.
      *
      * **Important:** Place `content` before `jumpToItem` and `animateToItem` in the
      * component. When content is updated dynamically, update `jumpToItem`/`animateToItem`

package/src/sg-nodes/panel-set.props.ts

@@ -59,7 +59,7 @@ export interface IPanelSetProps extends IGroupProps {
      * The value is `true` when the PanelSet panels are sliding right, back towards the original
      * home position, as a result of a Left or Back key press. The value is `false` otherwise.
      *
-     * @see **ListPanel, GridPanel Best Practices** at the internal RSG SDK documentation (knowledge-base/list-grid-panel-best-practice.md) for handling slidingBack prop
+     * @see **ListPanel, GridPanel Best Practices** at the internal RSG 2.0 SDK documentation (knowledge-base/list-grid-panel-best-practice.md) for handling slidingBack prop
      */
     onIsGoingBack?: EventHandler<boolean>;
 

package/src/sg-nodes/poster.tsx

@@ -14,7 +14,7 @@ export type { PosterDisplayMode, LoadDisplayMode, PosterLoadStatus, BitmapMargin
  * dimension information. See the Static Image Management documentation for details.
  *
  * **Attribute ordering pitfall:** When using `<poster>` as a JSX intrinsic,
- * write event handlers (`onLoadStatus`, etc.) **before** `uri` and other props that trigger
+ * write event handlers (`onLoadStatus`, etc.) before `uri` and other props that trigger
  * synchronous events on assignment. If `uri` is set first and the image is already cached,
  * the load event fires before your handler is registered and is silently dropped.
  * Writing handlers first is good practice regardless.

package/src/sg-nodes/standard-keyboard-dialog.tsx

@@ -11,8 +11,7 @@ export type { IKeyboardDomain, IStandardKeyboardDialogProps } from "./standard-k
 /**
  * Displays a keyboard dialog for text and voice entry of alphanumeric characters and symbols.
  *
- * `StandardKeyboardDialog` is a pre-built dialog similar to the legacy KeyboardDialog node,
- * but includes voice entry functionality through its internal DynamicKeyboard node.
+ * StandardKeyboardDialog is a pre-built dialog similar to the legacy KeyboardDialog node, but includes voice entry functionality through its internal DynamicKeyboard node.
  *
  * The {@link IStandardKeyboardDialogProps.keyboardDomain | keyboardDomain} property controls
  * how voice input is processed:

package/src/sg-nodes/standard-message-dialog.tsx

@@ -11,8 +11,7 @@ export type { IStandardBulletType, IStandardMessageDialogProps } from "./standar
 /**
  * Displays a message dialog with optional title, text blocks, bulleted list, and buttons.
  *
- * `StandardMessageDialog` is a pre-built dialog similar to the legacy Dialog node. It provides
- * a convenient way to display informational messages with:
+ * StandardMessageDialog is a pre-built dialog similar to the legacy Dialog node. It provides a convenient way to display informational messages with:
  * - One or more text blocks at the top ({@link IStandardMessageDialogProps.message | message})
  * - An optional bulleted/numbered/lettered list ({@link IStandardMessageDialogProps.bulletText | bulletText})
  * - One or more text blocks at the bottom ({@link IStandardMessageDialogProps.bottomMessage | bottomMessage})

package/src/sg-nodes/standard-pinpad-dialog.tsx

@@ -11,9 +11,7 @@ export type { IStandardPinPadDialogProps } from "./standard-pinpad-dialog.props"
 /**
  * Displays a PIN pad dialog for text and voice entry of numeric PIN codes.
  *
- * `StandardPinPadDialog` is a pre-built dialog similar to the legacy PinDialog node,
- * but includes voice entry of numeric digits through its internal DynamicPinPad and
- * VoiceTextEditBox nodes.
+ * StandardPinPadDialog is a pre-built dialog similar to the legacy PinDialog node, but includes voice entry of numeric digits through its internal DynamicPinPad and VoiceTextEditBox nodes.
  *
  * @example
  * ```tsx

package/src/sg-nodes/standard-progress-dialog.tsx

@@ -11,12 +11,9 @@ export type { IStandardProgressDialogProps } from "./standard-progress-dialog.pr
 /**
  * Displays a progress dialog with a spinning indicator and message.
  *
- * `StandardProgressDialog` is a pre-built dialog similar to the legacy ProgressDialog node.
- * It displays a spinning progress indicator for tasks with an indeterminate duration.
+ * StandardProgressDialog is a pre-built dialog similar to the legacy ProgressDialog node. It displays a spinning progress indicator for tasks with an indeterminate duration.
  *
- * Note: Unlike other standard dialogs, `StandardProgressDialog` has no buttons — it only
- * displays a spinner with a message. Close the dialog programmatically by setting
- * {@link IStandardProgressDialogProps.close | close} to `true` or by unmounting the component.
+ * Note: Unlike other standard dialogs, StandardProgressDialog has no buttons — it only displays a spinner with a message. Close the dialog programmatically by setting {@link IStandardProgressDialogProps.close | close} to `true` or by unmounting the component.
  *
  * @example
  * ```tsx

package/src/sg-nodes/time-grid.props.ts

@@ -604,9 +604,9 @@ export interface ITimeGridNowNextModeProps {
  * and each cell within a row represents a program with its time slot.
  *
  * The content tree structure is:
- * - Root `ContentNode`
- *   - Channel `ContentNode` per row (with `title`, `hdPosterUrl` for logo)
- *     - Program `ContentNode` per cell (with `title`, `description`, `playStart`, `playDuration`)
+ * - Root ContentNode
+ *   - Channel ContentNode per row (with `title`, `hdPosterUrl` for logo)
+ *     - Program ContentNode per cell (with `title`, `description`, `playStart`, `playDuration`)
  *
  * Program nodes use `playStart` (epoch seconds) and `playDuration` (seconds)
  * to determine their horizontal position and width in the grid.

package/src/sg-nodes/video.props.ts

@@ -151,7 +151,7 @@ export type SubtitleSelectionPreferenceRule =
     { language: string[] } | { caption: string } | { descriptive: string | string[] } | { easyReader: string };
 
 /**
- * Subtitle track selection preferences (Roku OS 12.5+).
+ * Subtitle track selection preferences.
  *
  * @see {@link https://developer.roku.com/dev/docs/video}
  */
@@ -168,7 +168,7 @@ export interface ISubtitleSelectionPreferences {
 export type AudioSelectionPreferenceRule = { language: string[] } | { descriptive: string | string[] };
 
 /**
- * Audio track selection preferences (Roku OS 12.5+).
+ * Audio track selection preferences.
  *
  * @see {@link https://developer.roku.com/dev/docs/video}
  */
@@ -198,7 +198,7 @@ export interface IVideoPlaybackProps {
     /** Play state command (play, pause, stop, prebuffer, etc.). */
     control?: VideoControl;
     /**
-     * When true, STOP runs asynchronously (Roku OS 12.5+). `state` becomes `stopping` then `stopped`.
+     * When true, STOP runs asynchronously. `state` becomes `stopping` then `stopped`.
      */
     asyncStopSemantics?: boolean;
     /** Fired when playback state changes (buffering, playing, error, etc.). */
@@ -363,6 +363,62 @@ export interface IVideoUiProps {
     pivotNode?: JSX.Element;
 }
 
+/**
+ * One entry of the Video node `availableAudioTracks` field.
+ *
+ * Firmware always emits every key below; the TypeScript and BrightScript
+ * bridges both build each entry from the media player's audio track list.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IVideoAudioTrack {
+    /**
+     * Language code as declared by the stream. Roku docs describe an ISO 639-2
+     * three-letter code (`"eng"`), but the value is passed through from the
+     * manifest, so two-letter codes such as `"en"` also occur.
+     */
+    Language: string;
+    /** Descriptive name of the audio track. */
+    Name: string;
+    /**
+     * Human-readable audio format description from the demuxer, for example
+     * `"ISO/IEC 14496-3, Advanced Audio Coding, ADTS container"`. Not listed in
+     * the Roku docs; may be an empty string when the demuxer reports no format.
+     */
+    Format: string;
+    /** Track identifier; assign it to `audioTrack` to select the track. */
+    Track: string;
+    /** HLS "public.accessibility.describes-video", or a DASH audio description. */
+    HasAccessibilityDescription: boolean;
+    /** DASH Enhanced Audio Intelligibility track. */
+    HasAccessibilityEAI: boolean;
+}
+
+/**
+ * One entry of the Video node `availableSubtitleTracks` field.
+ *
+ * Firmware always emits every key below.
+ *
+ * @see {@link https://developer.roku.com/dev/docs/video}
+ */
+export interface IVideoSubtitleTrack {
+    /** Descriptive name of the subtitle track. */
+    Description: string;
+    /**
+     * Language code as declared by the stream. Roku docs describe an ISO 639-2
+     * three-letter code (`"eng"`), but two-letter codes such as `"en"` also occur.
+     */
+    Language: string;
+    /** Track identifier; assign it to `subtitleTrack` to select the track. */
+    TrackName: string;
+    /** HLS "public.accessibility.describes-music-and-sound". */
+    HasAccessibilityDescription: boolean;
+    /** HLS "public.accessibility.transcribes-spoken-dialog", or DASH captions. */
+    HasAccessibilityCaption: boolean;
+    /** DASH sign-language interpretation. */
+    HasAccessibilitySign: boolean;
+}
+
 /**
  * Closed caption and subtitle styling fields.
  *
@@ -375,6 +431,10 @@ export interface IVideoCaptionProps {
     suppressCaptions?: boolean;
     /** Selected subtitle track identifier (read/write). */
     subtitleTrack?: string;
+    /** Fired with the subtitle tracks found in the stream and content metadata (read-only on the node). */
+    onAvailableSubtitleTracks?: EventHandler<IVideoSubtitleTrack[]>;
+    /** Fired when the playing subtitle track changes; carries the track identifier (`TrackName`). */
+    onCurrentSubtitleTrack?: EventHandler<string>;
     /**
      * Caption styling keys (Text/Font, Text/Size, Background/Color, etc.) per Roku docs.
      */
@@ -391,6 +451,15 @@ export interface IVideoAudioProps {
     mute?: boolean;
     /** Selected audio track identifier (prefer platform selection when possible). */
     audioTrack?: string;
+    /**
+     * Fired with the audio tracks found in the stream (read-only on the node).
+     *
+     * @example
+     * <Video onAvailableAudioTracks={tracks => setTracks(tracks)} onCurrentAudioTrack={id => setActive(id)} />
+     */
+    onAvailableAudioTracks?: EventHandler<IVideoAudioTrack[]>;
+    /** Fired when the playing audio track changes; carries the track identifier (`Track`). */
+    onCurrentAudioTrack?: EventHandler<string>;
     /**
      * When true, continues video on audio track switch (HLS only; set before any control command).
      */
@@ -478,7 +547,7 @@ export interface VideoRef extends ComponentRef<IVideoProps> {
     /**
      * Stop playback and release the video stream. Equivalent to setting
      * `control="stop"`. With {@link IVideoPlaybackProps.asyncStopSemantics} true
-     * (Roku OS 12.5+) the state transitions through `stopping` to `stopped`;
+     * the state transitions through `stopping` to `stopped`;
      * otherwise the transition to `stopped` is synchronous.
      */
     stop: () => void;

package/src/sg-nodes/video.tsx

@@ -24,6 +24,8 @@ export type {
     IDownloadedSegmentInfo,
     ITrickPlayProps,
     IVideoUiProps,
+    IVideoAudioTrack,
+    IVideoSubtitleTrack,
     IVideoCaptionProps,
     IVideoAudioProps,
     IVideoMiscProps,