@roku-sdk/components 0.0.0-stage → 2.18.0

package/src/sg-nodes/__tests__/prop-forwarding.test.tsx

@@ -0,0 +1,1049 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, test } from "@jest/globals";
+import { registerInternStringApi } from "@roku-sdk/common/string-interner";
+import { transactionManager } from "@roku-sdk/common/transaction";
+import {
+    AnimatedImage,
+    Animation,
+    Audio,
+    BifDisplay,
+    BusySpinner,
+    Button,
+    ButtonGroup,
+    CheckList,
+    ColorFieldInterpolator,
+    ContentNode,
+    FloatFieldInterpolator,
+    Font,
+    Group,
+    Label,
+    LabelList,
+    LayoutGroup,
+    MarkupGrid,
+    MarkupList,
+    MaskGroup,
+    MultiStyleLabel,
+    Overhang,
+    Panel,
+    PanelSet,
+    Poster,
+    PosterGrid,
+    ProgressBar,
+    RadioButtonList,
+    Rectangle,
+    RowList,
+    Scene,
+    ScrollableText,
+    ScrollingLabel,
+    SequentialAnimation,
+    SimpleLabel,
+    SoundEffect,
+    TargetGroup,
+    TargetList,
+    TargetSet,
+    TimeGrid,
+    TrickPlayBar,
+    Vector2DFieldInterpolator,
+    Video,
+    VideoContentNode,
+    ZoomRowList
+} from "@roku-sdk/components";
+import type { Component, JSX } from "@roku-sdk/components/types";
+import { DomNode, InternStringApi, StructuredDataApi, TreeManipulationApi } from "@roku-sdk/interfaces";
+import { makeSolidRenderer } from "@roku-sdk/solid";
+
+/**
+ * Captured, human-readable record of everything the SolidJS renderer forwards
+ * to the SceneGraph TreeManipulationApi for a single wrapper render.
+ *
+ * Keys are prop names (the user-visible names on the component), values
+ * describe which TM setter was invoked and with what value.
+ */
+type Captured = Record<string, CapturedEntry>;
+
+type CapturedEntry =
+    | { kind: "bool"; value: boolean }
+    | { kind: "int"; value: number }
+    | { kind: "float"; value: number }
+    | { kind: "string"; value: string }
+    | { kind: "array"; value: unknown[] }
+    | { kind: "object"; value: Record<string, unknown> }
+    | { kind: "nodeRef"; value: string }
+    | { kind: "null" }
+    | { kind: "eventHandler" }
+    | { kind: "focus"; value: boolean };
+
+interface CapturedForwardedProps {
+    captured: Captured;
+    order: string[];
+}
+
+const commitEarly = transactionManager.commitEarly;
+
+/**
+ * Replicates the `isEventHandler` classification used by the SolidJS renderer:
+ * any prop whose key matches the shape `on[A-Z]...`.
+ *
+ * Kept in sync with `packages/solid/src/solid.ts`.
+ */
+function isEventHandler(key: string): boolean {
+    return key.length > 2 && key[0] === "o" && key[1] === "n" && key[2] >= "A" && key[2] <= "Z";
+}
+
+/**
+ * Replicates the renderer's on-prop -> event-name transformation.
+ * `onFocus` -> `focus`, `onLoadStatus` -> `loadStatus`.
+ *
+ * Kept in sync with `packages/solid/src/solid.ts`.
+ */
+function transformEventName(eventName: string): string {
+    return eventName.slice(2).charAt(0).toLowerCase() + eventName.slice(3);
+}
+
+/**
+ * Render a wrapper component with a given sample-prop object and return a
+ * deterministic record of every TM API call that represents prop forwarding.
+ *
+ * The returned record is suitable for direct `toMatchSnapshot()` comparison -
+ * inserting or dropping any prop anywhere in the thin wrapper pipeline will
+ * surface as a diff in the snapshot file.
+ *
+ * `buildProps` is a factory so that JSX.Element values (which require the
+ * SolidJS renderer to be initialized) are evaluated after the mock renderer
+ * is wired up.
+ */
+function captureForwardedProps<P extends object>(
+    Component: Component<P>,
+    buildProps: () => P & { children?: JSX.Element }
+): CapturedForwardedProps {
+    // --- Intern string API (id -> string reverse map) ---
+    const internForward = new Map<string, object>();
+    const internReverse = new Map<object, string>();
+    let internRef = 0;
+    const mockIntern: InternStringApi = {
+        internString: (str: string): object => {
+            const existing = internForward.get(str);
+            if (existing) return existing;
+            const ref = { id: ++internRef };
+            internForward.set(str, ref);
+            internReverse.set(ref, str);
+            return ref;
+        }
+    };
+    registerInternStringApi(mockIntern);
+
+    const resolveInterned = (ref: unknown): string => {
+        if (ref && typeof ref === "object") {
+            const s = internReverse.get(ref as object);
+            if (s !== undefined) return s;
+        }
+        return String(ref);
+    };
+
+    // --- Node refs: { id } + side-channel tag map so JSX.Element props can be labelled. ---
+    const nodeTag = new WeakMap<object, string>();
+    let nodeCounter = 0;
+
+    const nodeRefToLabel = (ref: unknown): string => {
+        if (ref && typeof ref === "object") {
+            const tag = nodeTag.get(ref as object);
+            if (tag) return `<ref:${tag}>`;
+        }
+        return "<ref>";
+    };
+
+    // --- Structured data API: refs ARE the JS values so snapshots capture
+    //     full array/object contents. ---
+    const mockSd: StructuredDataApi = {
+        createObject: () => ({}),
+        createArray: () => [],
+        insertBool: (o, p, v) => {
+            (o as Record<string, unknown>)[resolveInterned(p)] = v;
+        },
+        insertNull: (o, p) => {
+            (o as Record<string, unknown>)[resolveInterned(p)] = null;
+        },
+        insertInt: (o, p, v) => {
+            (o as Record<string, unknown>)[resolveInterned(p)] = v;
+        },
+        insertFloat: (o, p, v) => {
+            (o as Record<string, unknown>)[resolveInterned(p)] = v;
+        },
+        insertString: (o, p, v) => {
+            (o as Record<string, unknown>)[resolveInterned(p)] = v;
+        },
+        insertObject: (o, p, v) => {
+            (o as Record<string, unknown>)[resolveInterned(p)] = v;
+        },
+        insertArray: (o, p, v) => {
+            (o as Record<string, unknown>)[resolveInterned(p)] = v;
+        },
+        insertNodeRef: (o, p, v) => {
+            (o as Record<string, unknown>)[resolveInterned(p)] = nodeRefToLabel(v);
+        },
+        appendBool: (a, v) => {
+            (a as unknown[]).push(v);
+        },
+        appendNull: a => {
+            (a as unknown[]).push(null);
+        },
+        appendInt: (a, v) => {
+            (a as unknown[]).push(v);
+        },
+        appendFloat: (a, v) => {
+            (a as unknown[]).push(v);
+        },
+        appendString: (a, v) => {
+            (a as unknown[]).push(typeof v === "string" ? v : resolveInterned(v));
+        },
+        appendObject: (a, v) => {
+            (a as unknown[]).push(v);
+        },
+        appendArray: (a, v) => {
+            (a as unknown[]).push(v);
+        },
+        appendNodeRef: (a, v) => {
+            (a as unknown[]).push(nodeRefToLabel(v));
+        },
+        getArray: () => undefined,
+        getObject: () => undefined
+    };
+
+    // Record every call along with the target node so we can filter down
+    // to the wrapper's root element AFTER rendering is complete.
+    type Entry = { nodeRef: object; propName: string; entry: CapturedEntry };
+    const allCalls: Entry[] = [];
+    const focusCalls: { nodeRef: object; value: boolean }[] = [];
+
+    const push = (nodeRef: unknown, propRef: unknown, entry: CapturedEntry) => {
+        if (!nodeRef || typeof nodeRef !== "object") return;
+        allCalls.push({ nodeRef: nodeRef as object, propName: resolveInterned(propRef), entry });
+    };
+
+    const mockTm: TreeManipulationApi = {
+        createNode: (_anchor, tagRef) => {
+            const ref: object = { id: ++nodeCounter };
+            const tagName = resolveInterned(tagRef);
+            nodeTag.set(ref, tagName);
+            return ref;
+        },
+        appendNode: () => undefined,
+        insertNodeBefore: () => undefined,
+        removeNode: () => undefined,
+        setNodePropNull: (_a, n, p) => push(n, p, { kind: "null" }),
+        setNodePropBool: (_a, n, p, v) => push(n, p, { kind: "bool", value: v }),
+        setNodePropInt: (_a, n, p, v) => push(n, p, { kind: "int", value: v }),
+        setNodePropFloat: (_a, n, p, v) => push(n, p, { kind: "float", value: v }),
+        setNodePropString: (_a, n, p, v) => push(n, p, { kind: "string", value: v }),
+        setNodePropObject: (_a, n, p, v) => push(n, p, { kind: "object", value: v as Record<string, unknown> }),
+        setNodePropArray: (_a, n, p, v) => push(n, p, { kind: "array", value: v as unknown[] }),
+        setNodePropNodeRef: (_a, n, p, v) => push(n, p, { kind: "nodeRef", value: nodeRefToLabel(v) }),
+        removeNodeProp: () => undefined,
+        updateNodeProps: () => undefined,
+        removeNodeProps: () => undefined,
+        registerFieldChangeHandler: (_a, n, p) => push(n, p, { kind: "eventHandler" }),
+        unregisterFieldHandler: () => undefined,
+        setFocus: (_a, n, v) => {
+            if (n && typeof n === "object") focusCalls.push({ nodeRef: n as object, value: v });
+        }
+    };
+
+    const { renderer } = makeSolidRenderer(mockTm, mockSd, mockSd);
+    const anchorName = { id: 0 };
+
+    const anchorNode: DomNode = { r: {}, n: anchorName } as DomNode;
+    const props = buildProps();
+    const dispose = renderer.render((() => <Component {...props} />) as unknown as () => DomNode, anchorNode);
+    commitEarly();
+
+    // The wrapper's root DomNode is the first direct child of the anchor.
+    const rootDom = anchorNode.c && anchorNode.c[0];
+    const rootNodeRef = rootDom?.r as object | undefined;
+
+    dispose();
+
+    const captured: Captured = {};
+    if (rootNodeRef) {
+        for (const { nodeRef, propName, entry } of allCalls) {
+            if (nodeRef === rootNodeRef) captured[propName] = entry;
+        }
+        for (const { nodeRef, value } of focusCalls) {
+            if (nodeRef === rootNodeRef) captured["gainFocus"] = { kind: "focus", value };
+        }
+    }
+
+    return {
+        captured: sortKeys(captured),
+        order: allCalls.filter(({ nodeRef }) => nodeRef === rootNodeRef).map(({ propName }) => propName)
+    };
+}
+
+function sortKeys(obj: Captured): Captured {
+    const out: Captured = {};
+    for (const k of Object.keys(obj).sort()) {
+        out[k] = obj[k];
+    }
+    return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Canonical sample values - reused across wrappers to keep snapshots stable
+// ─────────────────────────────────────────────────────────────────────────
+
+const V2: [number, number] = [10, 20];
+const V2B: [number, number] = [30, 40];
+const RECT: [number, number, number, number] = [0, 0, 100, 200];
+const URI_RES = { hd: "pkg:/a-hd.png", fhd: "pkg:/a-fhd.png" };
+
+// Common properties every IGroupProps component forwards.
+const buildGroupProps = () => ({
+    id: "node-id",
+    focusable: true,
+    visible: true,
+    translation: V2,
+    opacity: 0.5,
+    rotation: 1.57,
+    scale: V2,
+    scaleRotateCenter: V2,
+    childRenderOrder: "renderLast" as const,
+    inheritParentTransform: true,
+    inheritParentOpacity: true,
+    clippingRect: RECT,
+    renderPass: 1,
+    muteAudioGuide: false,
+    enableRenderTracking: true,
+    onRenderTracking: () => {},
+    onFocusedChild: () => {}
+});
+
+// ─────────────────────────────────────────────────────────────────────────
+// Thin-wrapper table - each row = one snapshot row under `describe.each`.
+// Keep entries alphabetical by `name` for readability.
+// ─────────────────────────────────────────────────────────────────────────
+
+type WrapperRow = {
+    name: string;
+    Component: Component<Record<string, unknown>>;
+    // Props are built lazily because JSX.Element values must be created
+    // AFTER makeSolidRenderer() has run.
+    props: () => Record<string, unknown>;
+};
+
+const WRAPPERS: WrapperRow[] = [
+    {
+        name: "Animation",
+        Component: Animation as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "anim",
+            control: "start",
+            duration: 0.5,
+            easeFunction: "linear",
+            repeat: true,
+            delay: 0.1,
+            optional: false,
+            onState: () => {}
+        })
+    },
+    {
+        name: "Audio",
+        Component: Audio as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "audio",
+            contentIsPlaylist: false,
+            loop: true,
+            control: "play",
+            notificationInterval: 0.5,
+            seek: 5.5,
+            content: <ContentNode title="song" />,
+            onState: () => {},
+            onPosition: () => {},
+            onDuration: () => {},
+            onAudioFormat: () => {},
+            onBufferingStatus: () => {},
+            onErrorCode: () => {}
+        })
+    },
+    {
+        name: "BifDisplay",
+        Component: BifDisplay as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "bif",
+            width: 240,
+            height: 135
+        })
+    },
+    {
+        name: "BusySpinner",
+        Component: BusySpinner as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "spinner",
+            uri: "pkg:/images/spinner.png",
+            control: "start",
+            clockwise: true,
+            spinInterval: 1.0
+        })
+    },
+    {
+        name: "Button",
+        Component: Button as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "btn",
+            text: "Click me",
+            textColor: "#FFFFFFFF",
+            focusedTextColor: "#000000FF",
+            iconUri: "pkg:/images/icon.png",
+            focusBitmapUri: "pkg:/images/focus.9.png",
+            onButtonSelected: () => {}
+        })
+    },
+    {
+        name: "ButtonGroup",
+        Component: ButtonGroup as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "btn-group",
+            textColor: "#FFFFFFFF",
+            focusedTextColor: "#000000FF",
+            iconUri: "pkg:/icons/a.png",
+            height: 64,
+            minWidth: 200,
+            maxWidth: 600,
+            focusButton: 1,
+            buttons: ["One", "Two", "Three"],
+            layoutDirection: "vert",
+            horizAlignment: "left",
+            vertAlignment: "top",
+            itemSpacings: [8, 8],
+            onButtonSelected: () => {}
+        })
+    },
+    {
+        name: "CheckList",
+        Component: CheckList as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "checklist",
+            itemSize: V2,
+            checkedState: [true, false, true],
+            checkOnSelect: true,
+            checkedIconUri: "pkg:/check.png",
+            uncheckedIconUri: "pkg:/uncheck.png",
+            checkedFocusIconUri: "pkg:/check-focus.png",
+            uncheckedFocusIconUri: "pkg:/uncheck-focus.png"
+        })
+    },
+    {
+        name: "ColorFieldInterpolator",
+        Component: ColorFieldInterpolator as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "color-interp",
+            key: [0.0, 1.0],
+            keyValue: ["#FF0000FF", "#00FF00FF"],
+            fieldToInterp: "color"
+        })
+    },
+    {
+        name: "ContentNode",
+        Component: ContentNode as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "content",
+            title: "My Title",
+            description: "Description text",
+            contentType: "episode",
+            hdPosterUrl: "pkg:/poster-hd.jpg",
+            actors: ["Alice", "Bob"],
+            categories: ["drama", "sci-fi"],
+            length: 3600,
+            starRating: 80,
+            live: false,
+            streamBitrates: [500, 1500, 3000]
+        })
+    },
+    {
+        name: "FloatFieldInterpolator",
+        Component: FloatFieldInterpolator as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "float-interp",
+            key: [0.0, 1.0],
+            keyValue: [0.0, 1.0],
+            fieldToInterp: "opacity"
+        })
+    },
+    {
+        name: "Font",
+        Component: Font as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "font",
+            uri: "pkg:/fonts/Roboto-Bold.ttf",
+            size: 28,
+            fallbackGlyph: "?"
+        })
+    },
+    {
+        name: "Group",
+        Component: Group as Component<Record<string, unknown>>,
+        props: () => ({ ...buildGroupProps() })
+    },
+    {
+        name: "Group (ResType values)",
+        Component: Group as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "res",
+            translation: { hd: V2, fhd: V2B },
+            scaleRotateCenter: { hd: V2, fhd: V2B },
+            clippingRect: { hd: RECT, fhd: [10, 10, 50, 50] as [number, number, number, number] }
+        })
+    },
+    {
+        name: "Label",
+        Component: Label as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "label",
+            text: "Hello",
+            color: "#FFFFFFFF",
+            width: 300,
+            height: 80,
+            font: "font:MediumSystemFont",
+            horizAlign: "center",
+            vertAlign: "center",
+            monospacedDigits: true,
+            numLines: 1,
+            maxLines: 3,
+            wrap: true,
+            displayPartialLines: false,
+            ellipsizeOnBoundary: true,
+            wordBreakChars: "-",
+            ellipsisText: "…",
+            lineSpacing: 4,
+            truncateOnDelimiter: ",",
+            leadingEllipsis: false,
+            onIsTextEllipsized: () => {},
+            onWrappedLines: () => {}
+        })
+    },
+    {
+        name: "LabelList",
+        Component: LabelList as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "ll",
+            itemSize: V2,
+            numRows: 8,
+            drawFocusFeedback: true,
+            textHorizAlign: "left",
+            color: "#CCCCCCFF",
+            focusedColor: "#FFFFFFFF",
+            font: <Font uri="pkg:/font.ttf" size={24} />,
+            focusedFont: <Font uri="pkg:/font-bold.ttf" size={24} />,
+            onItemSelected: () => {},
+            onItemFocused: () => {}
+        })
+    },
+    {
+        name: "LabelList (gainFocus)",
+        Component: LabelList as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "ll-focus",
+            itemSize: V2,
+            gainFocus: true
+        })
+    },
+    {
+        name: "LayoutGroup",
+        Component: LayoutGroup as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "layout",
+            layoutDirection: "horiz",
+            horizAlignment: "center",
+            vertAlignment: "top",
+            itemSpacings: [8, 16],
+            addItemSpacingAfterChild: true
+        })
+    },
+    {
+        name: "MarkupGrid",
+        Component: MarkupGrid as unknown as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "markup-grid",
+            itemComponentName: "MyItem",
+            itemSize: V2,
+            numRows: 3,
+            numColumns: 4,
+            content: <ContentNode />,
+            imageWellBitmapUri: "pkg:/well.png"
+        })
+    },
+    {
+        name: "MarkupList",
+        Component: MarkupList as unknown as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "markup-list",
+            itemComponentName: "MyItem",
+            itemSize: V2,
+            content: <ContentNode />
+        })
+    },
+    {
+        name: "MaskGroup",
+        Component: MaskGroup as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "mask",
+            maskUri: "pkg:/mask.png",
+            maskSize: V2,
+            maskOffset: V2B,
+            onMaskBitmapWidth: () => {},
+            onMaskBitmapHeight: () => {}
+        })
+    },
+    {
+        name: "MultiStyleLabel",
+        Component: MultiStyleLabel as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "msl",
+            text: "Hello <b>world</b>",
+            color: "#FFFFFFFF",
+            width: 400,
+            wrap: true,
+            drawingStyles: {
+                bold: { fontSize: 24, fontUri: "font:MediumBoldSystemFont", color: "#FFFFFFFF" }
+            }
+        })
+    },
+    {
+        name: "Overhang",
+        Component: Overhang as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "overhang",
+            color: "#00FF00FF",
+            backgroundUri: "pkg:/bg.png",
+            logoUri: "pkg:/logo.png",
+            title: "App Title",
+            showClock: true,
+            optionsAvailable: false,
+            dividerBitmapUri: "pkg:/div.png"
+        })
+    },
+    {
+        name: "Panel",
+        Component: Panel as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "panel",
+            panelSize: "full",
+            width: 1920,
+            height: 1080,
+            leftPosition: 0,
+            leftOnly: false,
+            hasNextPanel: true,
+            isFullScreen: false,
+            goBackCount: 1,
+            overhangTitle: "Title",
+            onIsOffscreenLeft: () => {}
+        })
+    },
+    {
+        name: "PanelSet",
+        Component: PanelSet as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "panel-set",
+            width: 1920,
+            height: 1080,
+            slideDuration: 0.25,
+            onIsGoingBack: () => {},
+            onNumPanels: () => {}
+        })
+    },
+    {
+        name: "AnimatedImage",
+        Component: AnimatedImage as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "animated-image",
+            width: 200,
+            height: 300,
+            loadWidth: 200,
+            loadHeight: 300,
+            loadDisplayMode: "scaleToFit",
+            mimeType: "video/mp4",
+            control: "loop",
+            loadingBitmapUri: "pkg:/loading.png",
+            loadingBitmapOpacity: 0.5,
+            failedBitmapUri: "pkg:/failed.png",
+            failedBitmapOpacity: 1.0,
+            audioGuideText: "Animated image",
+            onState: () => {},
+            onError: () => {},
+            onMediaWidth: () => {},
+            onMediaHeight: () => {},
+            uri: URI_RES
+        })
+    },
+    {
+        name: "Poster",
+        Component: Poster as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "poster",
+            width: 200,
+            height: 300,
+            loadSync: false,
+            loadWidth: 200,
+            loadHeight: 300,
+            loadDisplayMode: "scaleToFit",
+            blendColor: "#FFFFFFFF",
+            loadingBitmapUri: "pkg:/loading.png",
+            loadingBitmapOpacity: 0.5,
+            failedBitmapUri: "pkg:/failed.png",
+            failedBitmapOpacity: 1.0,
+            audioGuideText: "Poster image",
+            onLoadStatus: () => {},
+            onBitmapWidth: () => {},
+            onBitmapHeight: () => {},
+            onBitmapMargins: () => {},
+            uri: URI_RES
+        })
+    },
+    {
+        name: "PosterGrid",
+        Component: PosterGrid as unknown as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "poster-grid",
+            content: <ContentNode />,
+            basePosterSize: V2,
+            useAtlas: false,
+            posterDisplayMode: "scaleToFit",
+            loadingBitmapUri: "pkg:/loading.png",
+            failedBitmapUri: "pkg:/failed.png",
+            caption1NumLines: 1
+        })
+    },
+    {
+        name: "ProgressBar",
+        Component: ProgressBar as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "progress-bar",
+            width: 800,
+            height: 8,
+            percentage: 0.5
+        })
+    },
+    {
+        name: "RadioButtonList",
+        Component: RadioButtonList as unknown as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "radio",
+            itemSize: V2,
+            checkedItem: 0,
+            checkOnSelect: true,
+            checkedIconUri: "pkg:/r-check.png",
+            uncheckedIconUri: "pkg:/r-uncheck.png",
+            checkedFocusIconUri: "pkg:/r-check-focus.png",
+            uncheckedFocusIconUri: "pkg:/r-uncheck-focus.png"
+        })
+    },
+    {
+        name: "Rectangle",
+        Component: Rectangle as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "rect",
+            width: 100,
+            height: 50,
+            color: "#FF0000FF",
+            blendingEnabled: true
+        })
+    },
+    {
+        name: "RowList",
+        Component: RowList as unknown as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "row-list",
+            content: <ContentNode />,
+            itemComponentName: "Item",
+            rowTitleComponentName: "Title",
+            rowItemSize: [V2, V2B],
+            rowItemSpacing: [V2, V2B],
+            showRowLabel: [true, false],
+            focusXOffset: [0, 10],
+            jumpToRowItem: [0, 0]
+        })
+    },
+    {
+        name: "Scene",
+        Component: Scene as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "scene",
+            backgroundURI: "pkg:/bg.jpg",
+            backgroundColor: "#000000FF",
+            backExitsScene: false,
+            dialog: <ContentNode />,
+            palette: <ContentNode />,
+            onCurrentDesignResolution: () => {}
+        })
+    },
+    {
+        name: "ScrollableText",
+        Component: ScrollableText as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "scrollable",
+            text: "Long text",
+            color: "#FFFFFFFF",
+            font: "font:SmallSystemFont",
+            width: 400,
+            height: 200,
+            lineSpacing: 4,
+            horizAlign: "left",
+            vertAlign: "top",
+            scrollbarTrackBitmapUri: "pkg:/track.png",
+            scrollbarThumbBitmapUri: "pkg:/thumb.png"
+        })
+    },
+    {
+        name: "ScrollingLabel",
+        Component: ScrollingLabel as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "scrolling",
+            text: "Ticker",
+            color: "#FFFFFFFF",
+            font: "font:MediumSystemFont",
+            maxWidth: 400,
+            height: 32,
+            scrollSpeed: 1.0,
+            repeatCount: 3,
+            horizAlign: "left",
+            vertAlign: "center"
+        })
+    },
+    {
+        name: "SequentialAnimation",
+        Component: SequentialAnimation as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "seq",
+            control: "start",
+            repeat: false,
+            delay: 0.2,
+            optional: false
+        })
+    },
+    {
+        name: "SimpleLabel",
+        Component: SimpleLabel as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "simple",
+            text: "Hi",
+            color: "#FFFFFFFF",
+            fontUri: "font:MediumSystemFont",
+            fontSize: 24,
+            horizOrigin: "left",
+            vertOrigin: "center"
+        })
+    },
+    {
+        name: "SoundEffect",
+        Component: SoundEffect as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "sfx",
+            uri: "pkg:/sfx/select.wav",
+            control: "play",
+            volume: 0.75,
+            onState: () => {},
+            onLoadStatus: () => {}
+        })
+    },
+    {
+        name: "TargetGroup",
+        Component: TargetGroup as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "tg",
+            itemComponentName: "MyItem",
+            content: <ContentNode />,
+            targetSet: <TargetSet targetRects={[RECT]} />,
+            defaultTargetSetFocusIndex: 0,
+            wrap: false,
+            duration: 0.25,
+            easeFunction: "outQuad",
+            showTargetRects: false,
+            jumpToItem: 0,
+            animateToItem: 0,
+            animateToTargetSet: 0
+        })
+    },
+    {
+        name: "TargetList",
+        Component: TargetList as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "tl",
+            itemComponentName: "MyItem",
+            content: <ContentNode />,
+            unfocusedTargetSet: <TargetSet targetRects={[RECT]} />,
+            advanceKey: "right",
+            reverseKey: "left"
+        })
+    },
+    {
+        name: "TargetSet",
+        Component: TargetSet as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "ts",
+            targetRects: [RECT, [10, 10, 50, 50]],
+            focusIndex: 1,
+            color: "#FF0000FF"
+        })
+    },
+    {
+        name: "TimeGrid",
+        Component: TimeGrid as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "timegrid",
+            content: <ContentNode />,
+            contentStartTime: 1700000000,
+            duration: 7200,
+            leftEdgeTargetTime: 1700000000,
+            channelInfoComponentName: "ChannelInfo",
+            itemComponentName: "Program",
+            numRows: 6,
+            rowHeight: 96
+        })
+    },
+    {
+        name: "TrickPlayBar",
+        Component: TrickPlayBar as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "trickplay",
+            trackBlendColor: "#FFFFFFFF",
+            filledBarBlendColor: "#00FF00FF",
+            thumbBlendColor: "#FF0000FF"
+        })
+    },
+    {
+        name: "Vector2DFieldInterpolator",
+        Component: Vector2DFieldInterpolator as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "v2-interp",
+            key: [0.0, 1.0],
+            keyValue: [V2, V2B],
+            fieldToInterp: "translation"
+        })
+    },
+    {
+        name: "Video",
+        Component: Video as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "video",
+            content: <ContentNode url="http://example.com/video.mp4" />,
+            control: "play",
+            loop: false,
+            seek: 0,
+            width: 1920,
+            height: 1080,
+            enableUI: true,
+            globalCaptionMode: "On",
+            mute: false
+        })
+    },
+    {
+        name: "VideoContentNode",
+        Component: VideoContentNode as Component<Record<string, unknown>>,
+        props: () => ({
+            id: "video-content",
+            title: "Movie",
+            url: "http://example.com/movie.mp4",
+            streamFormat: "mp4",
+            live: false
+        })
+    },
+    {
+        name: "ZoomRowList",
+        Component: ZoomRowList as unknown as Component<Record<string, unknown>>,
+        props: () => ({
+            ...buildGroupProps(),
+            id: "zoom-row",
+            content: <ContentNode />,
+            itemComponentName: "Item",
+            rowDecorationComponentName: "Deco",
+            rowWidth: 1600,
+            rowHeight: 180,
+            rowZoomHeight: 240,
+            rowItemAspectRatio: 1.78
+        })
+    }
+];
+
+// ─────────────────────────────────────────────────────────────────────────
+
+describe("sg-nodes thin wrappers forward every prop to the TM API", () => {
+    describe.each(WRAPPERS)("$name", ({ Component, props }) => {
+        test("forwards props to TreeManipulationApi (snapshot)", () => {
+            const { captured } = captureForwardedProps(Component, props);
+            expect(captured).toMatchSnapshot();
+        });
+
+        // Verifies every `on*` handler prop reaches the TM layer via
+        // `registerFieldChangeHandler`. Separate from the snapshot so a
+        // missed handler surfaces as a direct, readable diff rather than
+        // requiring a reviewer to decode the snapshot.
+        test("forwards every on* handler prop as a registered event handler", () => {
+            const builtProps = props() as Record<string, unknown>;
+            const expectedEvents = new Set(
+                Object.keys(builtProps)
+                    .filter(k => isEventHandler(k) && typeof builtProps[k] === "function")
+                    .map(transformEventName)
+            );
+
+            const { captured } = captureForwardedProps(Component, props);
+            const actualEvents = new Set(
+                Object.entries(captured)
+                    .filter(([, v]) => v.kind === "eventHandler")
+                    .map(([k]) => k)
+            );
+
+            expect(actualEvents).toEqual(expectedEvents);
+        });
+    });
+
+    test("AnimatedImage installs configuration and handlers before its URI", () => {
+        const animatedImage = WRAPPERS.find(({ name }) => name === "AnimatedImage");
+        if (!animatedImage) throw new Error("AnimatedImage forwarding fixture is missing");
+
+        const { order } = captureForwardedProps(animatedImage.Component, () => ({
+            uri: URI_RES,
+            ...animatedImage.props()
+        }));
+        const uriIndex = order.indexOf("uri");
+
+        expect(uriIndex).toBeGreaterThan(-1);
+        // TM uses native field names; transformEventName maps onState to state, etc.
+        for (const prop of ["loadDisplayMode", "state", "error", "mediaWidth", "mediaHeight"]) {
+            expect(order.indexOf(prop)).toBeGreaterThan(-1);
+            expect(order.indexOf(prop)).toBeLessThan(uriIndex);
+        }
+    });
+});