@roku-sdk/compat 0.0.0-stage → 2.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roku, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @roku-sdk/compat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shims for SceneGraph nodes that the SDK renders but firmware does not report as supported.
+
+The package is a side-effect import. `rk build` and `rk dev` inject it ahead of the app entry, so
+apps do not import it themselves. Set `app.compat: false` in `roku-config.ts` to leave it out.
+
+## What it does
+
+Each shim registers a tag alias with `registerTagAlias` from `@roku-sdk/solid`. When the tag is
+created, the alias asks `hasFeature("tween")` from `@roku-sdk/runtime/has-feature` whether the firmware
+has the real node. If it does, the real node is created. If not, the shim is created instead.
+
+| Tag       | Native node | Firmware feature           | Shim           |
+| --------- | ----------- | -------------------------- | -------------- |
+| `<tween>` | `Tween`     | `roku.hasFeature("tween")` | `RsgTweenShim` |
+
+`hasFeature` returns false when `roku` or `roku.hasFeature` is absent, including Jest.
+The firmware feature set starts empty;
+until firmware adds `"tween"`, devices use the shim regardless of their OS version.
+
+When `app.compat: false`, the Roku build injects only the native-or-refusal registration, not
+the shim XML or BrightScript. Importing `@roku-sdk/rsg-ts` alone performs no registration; only
+the Roku build injects these entries.
+
+In a Roku build without shims, creating a gated tag when its feature is not reported throws an
+error naming the missing firmware feature and this package. That is deliberate: a SceneGraph node type the
+firmware does not have fails silently and leaves an empty screen.
+
+## Retiring a shim
+
+Removing a shim drops support for every firmware that does not report its native feature, so it is a breaking
+change:
+
+- Remove shims only in a major SDK release, and state which firmware features that release requires.
+- Batch removals into one release rather than shipping one breaking release per shim.
+- Remove the shim's directory here and its entry in `refuse-gated-tags.ts` once all supported
+  firmware reports the feature. `@roku-sdk/solid` does not change.
+
+An app that must keep running on older firmware can stay on the last `@roku-sdk/compat` release
+that has the shim it needs.

package/eslint.config.mjs

@@ -0,0 +1,3 @@
+import rokuSdkToolsLinterConfig from "@roku-sdk/dev-tools/linter-config/eslint.config.mjs";
+
+export default rokuSdkToolsLinterConfig;

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@roku-sdk/compat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.18.0",
+  "description": "Shims that stand in for SceneGraph nodes older Roku OS firmware lacks",
+  "sideEffects": true,
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./refuse-gated-tags": "./src/refuse-gated-tags.ts"
+  },
+  "type": "module",
+  "files": [
+    "src/",
+    "eslint.config.mjs",
+    "tsconfig.json",
+    "xml.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "npm": ">=8.5.0",
+    "node": ">=24.0.0"
+  },
+  "peerDependencies": {
+    "@roku-sdk/runtime": "^2.18.0",
+    "@roku-sdk/solid": "^2.18.0"
+  },
+  "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/solid": "2.18.0",
+    "@roku-sdk/interfaces": "2.18.0",
+    "@roku-sdk/runtime": "2.18.0"
+  },
+  "author": "Roku Inc",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/rokudev/rsg-sdk.git",
+    "directory": "packages/compat"
+  },
+  "homepage": "https://gitlab.com/rokudev/rsg-sdk/-/tree/main/packages/compat#readme",
+  "bugs": {
+    "url": "https://gitlab.com/rokudev/rsg-sdk/-/issues"
+  },
+  "scripts": {
+    "test": "jest --passWithNoTests",
+    "coverage": "jest --coverage --runInBand --passWithNoTests --testTimeout=60000 --forceExit",
+    "clean": "rm -rf dist",
+    "lint": "eslint --no-error-on-unmatched-pattern \"src/**/*.{ts,tsx,mjs,cjs,js}\""
+  }
 }

package/src/__tests__/refuse-gated-tags.test.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { beforeAll, describe, expect, jest, test } from "@jest/globals";
+import { hasFeature } from "@roku-sdk/runtime/has-feature";
+import { hasTagAlias, registerTagAlias } from "@roku-sdk/solid";
+
+jest.mock("@roku-sdk/solid", () => ({ hasTagAlias: jest.fn(), registerTagAlias: jest.fn() }));
+jest.mock("@roku-sdk/runtime/has-feature", () => ({ hasFeature: jest.fn() }));
+
+let resolveTween: (() => string) | undefined;
+beforeAll(async () => {
+    await import("../refuse-gated-tags");
+    resolveTween = jest.mocked(registerTagAlias).mock.calls.find(([tag]) => tag === "tween")?.[1];
+});
+
+describe("tween refusal alias", () => {
+    test("checks for an existing alias before registering", () => {
+        expect(hasTagAlias).toHaveBeenCalledWith("tween");
+        expect(resolveTween).toBeDefined();
+    });
+    test("keeps the native node only when firmware reports tween", () => {
+        jest.mocked(hasFeature).mockReturnValue(true);
+        expect(resolveTween!()).toBe("tween");
+        expect(hasFeature).toHaveBeenCalledWith("tween");
+    });
+    test("refuses with the missing feature and compat named", () => {
+        jest.mocked(hasFeature).mockReturnValue(false);
+        expect(resolveTween!).toThrow('<tween> requires the "tween" firmware feature or @roku-sdk/compat');
+    });
+});

package/src/__tests__/tween-shim-source.test.ts

@@ -0,0 +1,276 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+// Source-contract guards, not a BrightScript execution harness. Device parity still needs
+// the tween-parity fixture on both firmware versions; Jest cannot run SceneGraph Animation.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { describe, expect, test } from "@jest/globals";
+
+const shim = readFileSync(path.join(__dirname, "../tween/rsg-tween-shim.brs"), "utf8");
+const body = (name: string): string => {
+    const match = shim.match(new RegExp(`(?:sub|function) ${name}\\([^]*?end (?:sub|function)`, "i"));
+    expect(match).not.toBeNull();
+    return match![0];
+};
+
+describe("Tween BrightScript native-contract source guards", () => {
+    test("binds anonymous target references without requiring a caller-assigned id", () => {
+        const bind = body("bindField");
+        expect(bind).toContain('if m.top.targetNode.id = "" then');
+        expect(bind).toContain('m.top.targetNode.id = "rsg-tween-" + createObject("roDeviceInfo").GetRandomUUID()');
+        expect(bind.indexOf("GetRandomUUID()")).toBeLessThan(bind.indexOf("desiredField ="));
+        expect(body("onTargetNodeChanged")).not.toContain('if target.id = "" then return');
+    });
+
+    test("uses the last-written scalar or vector trigger", () => {
+        expect(body("init")).toContain("m.useScalarTarget = true");
+        expect(body("onTargetValueChanged")).toContain("m.useScalarTarget = true");
+        expect(body("onTargetVectorChanged")).toContain("m.useScalarTarget = false");
+        expect(body("buildVectorTarget")).toContain(
+            "if not m.useScalarTarget and m.top.targetVector <> invalid and m.top.targetVector.count() >= 2 then"
+        );
+        for (const name of ["fireAnimation", "snapWithoutAnim"]) {
+            expect(body(name)).toContain(
+                "if not m.useScalarTarget and m.top.targetVector <> invalid and m.top.targetVector.count() >= 1 then"
+            );
+            expect(body(name)).toContain("toVal = m.top.targetVector[0]");
+        }
+    });
+
+    test("reports an integer millisecond remainder without 32-bit epoch arithmetic", () => {
+        const report = body("fireAnimationStop");
+        expect(report).toContain("totalMs# = currentTime.AsSeconds() * 1000#");
+        expect(report).toContain("Int(delaySeconds * 1000#)");
+        expect(report).toContain("seconds# = Int(totalMs# / 1000#)");
+        expect(report).toContain("milliseconds = Int(totalMs# - seconds# * 1000#)");
+        expect(report).toContain("[seconds#, milliseconds]");
+        expect(
+            body("onProposedStopsChanged").match(/fireAnimationStop\(index, closestStop, newDuration\)/g)
+        ).toHaveLength(2);
+    });
+
+    test("rejects underfoot candidates in both moving searches and stops zero-distance settles without restarting", () => {
+        const selection = body("pickStop1D");
+        expect(selection).toContain("stopPosition > fromPos");
+        expect(selection).toContain("stopPosition < fromPos");
+        expect(selection).not.toMatch(/stopPosition [<>]= fromPos/);
+        expect(selection).toContain("closestStop = defaultTo");
+        expect(selection).toContain("index = -1");
+        // The vector search uses the same strict comparison, per component.
+        const vector = body("pickStopVector");
+        for (const c of [0, 1]) {
+            expect(vector).toContain(`not (candidate[${c}] > fromVec[${c}])`);
+            expect(vector).toContain(`not (candidate[${c}] < fromVec[${c}])`);
+        }
+        expect(vector).not.toMatch(/candidate\[\d\] [<>]= fromVec/);
+        const settle = body("onProposedStopsChanged");
+        const fastPaths = [...settle.matchAll(/if newDistance = 0 then([^]*?)end if/g)].map(match => match[1]);
+        expect(fastPaths).toHaveLength(2);
+        for (const fastPath of fastPaths) {
+            expect(fastPath).toContain("stopAtValue(");
+            expect(fastPath).toContain("fireAnimationStop(index, closestStop, 0)");
+            expect(fastPath).toContain("return");
+            expect(fastPath).not.toContain('"start"');
+        }
+        expect(fastPaths[0]).toContain("stopAtValue(fromPos)");
+        expect(fastPaths[1]).toContain("stopAtValue(fromVec)");
+    });
+
+    test("pins the stopped value before stop for scalar and vector snaps and settles", () => {
+        const stop = body("stopAtValue");
+        expect(stop).toMatch(/m\.interp\.keyValue = \[value, value\][^]*m\.anim\.control = "stop"/);
+        const snap = body("fireAnimation");
+        expect(snap).toContain("stopAtValue(toVal)");
+        expect(snap).toContain("stopAtValue(toVec)");
+        const settle = body("onProposedStopsChanged");
+        expect(settle).toContain("stopAtValue(fromPos)");
+        expect(settle).toContain("stopAtValue(fromVec)");
+    });
+
+    test("reads the current easing at the shared start point, including settle re-arms", () => {
+        const arm = body("armSpan");
+        expect(arm).toMatch(/m\.anim\.easeFunction = m\.top\.easeFunction[^]*m\.anim\.control {4}= "start"/);
+        expect(shim.match(/m\.anim\.easeFunction = m\.top\.easeFunction/g)).toHaveLength(1);
+        expect(body("onProposedStopsChanged").match(/armSpan\(/g)).toHaveLength(2);
+    });
+
+    test("starts every span through armSpan, which records the armed destination", () => {
+        // The retry timer's start is the only other.
+        expect(shim.match(/control\s*= "start"/g)).toHaveLength(2);
+        const arm = body("armSpan");
+        expect(arm).toMatch(/m\.interp\.keyValue = \[fromValue, toValue\][^]*m\.anim\.control {4}= "start"/);
+        // Stop resets the target to keyValue[0]; writing the keys after it would flash the
+        // previous span's start for a frame on every animated retarget or settle.
+        expect(arm).toMatch(/m\.interp\.keyValue = \[fromValue, toValue\][^]*m\.anim\.control {4}= "stop"/);
+        expect(arm.indexOf("m.interp.keyValue")).toBeLessThan(arm.indexOf('m.anim.control    = "stop"'));
+        expect(arm).toContain("m.armed = { node: m.top.targetNode, to: toValue }");
+        expect(body("fireAnimation").match(/armSpan\(/g)).toHaveLength(2);
+        expect(body("onProposedStopsChanged")).toContain("armSpan(fromPos, closestStop, newDuration)");
+        expect(body("onProposedStopsChanged")).toContain("armSpan([fromVec[0], fromVec[1]], toVec, newDuration)");
+        // Snaps and pins land on a destination too, so they record it as well.
+        expect(body("stopAtValue")).toContain("m.armed = { node: m.top.targetNode, to: value }");
+        expect(body("snapWithoutAnim").match(/m\.armed = \{ node: m\.top\.targetNode, to: /g)).toHaveLength(2);
+    });
+
+    test("a stopped transition with no parent releases the Animation", () => {
+        expect(body("onAnimStateChanged")).toMatch(
+            /m\.anim\.state = "stopped" and m\.top\.getParent\(\) = invalid then releaseDetached\(\)/
+        );
+        // Deferred a frame on the retry timer, not run inside the Animation's own state observer.
+        const detached = body("releaseDetached");
+        expect(detached).toContain("m.releasePending = true");
+        expect(detached).toContain("startRetryTimer()");
+        expect(detached).not.toContain("releaseAnim()");
+        expect(body("onRetryTimerFire")).toMatch(/m\.top\.getParent\(\) = invalid then releaseAnim\(\)/);
+    });
+
+    test("a stopped transition with a parent does not release", () => {
+        const state = body("onAnimStateChanged");
+        expect(state).not.toMatch(/getParent\(\) <> invalid/);
+        expect(state).not.toContain("releaseAnim()");
+        // The condition requires a missing parent, so an attached node just goes idle.
+        expect(state.match(/releaseDetached\(\)/g)).toHaveLength(1);
+        expect(state).toMatch(/getParent\(\) = invalid then releaseDetached/);
+        expect(state).toContain("m.top.animationState = [data.getData(), curVal]");
+    });
+
+    test("has no owner guard Timer", () => {
+        expect(shim).not.toMatch(/ownerGuard|OwnerGuard/);
+        // The retry timer is the only Timer the shim creates.
+        expect(shim.match(/createObject\("roSGNode", "Timer"\)/g)).toHaveLength(1);
+    });
+
+    test("skips a write of the armed destination, never across a target change or a stop", () => {
+        const guard = body("isArmedFor");
+        expect(guard).toContain("if m.armed = invalid then return false");
+        // Keyframes armed on a previous target (FlexGrid's X tween follows the focused row)
+        // must not carry over to the new one.
+        expect(guard).toContain("if not m.armed.node.isSameNode(m.top.targetNode) then return false");
+        expect(guard).toContain("if ownX and abs(armedTo[0] - target[0]) >= 0.01 then return false");
+        expect(guard).toContain("if ownY and abs(armedTo[1] - target[1]) >= 0.01 then return false");
+        expect(body("onTargetNodeChanged")).toMatch(/m\.armed = invalid[^]*fireAnimation\(\)/);
+        expect(body("onControlChanged")).toContain('if ctrl = "stop" then m.armed = invalid');
+        expect(body("releaseAnim")).toContain("m.armed = invalid");
+        // Checked after the snap path, so a duration-0 write always lands, and before the restart.
+        const fire = body("fireAnimation");
+        const floatGuard = fire.indexOf("if isArmedFor(toVal, true, true) then return");
+        const vectorGuard = fire.indexOf('if isArmedFor(toVec, axis <> "y", axis <> "x") then return');
+        expect(floatGuard).toBeGreaterThan(fire.indexOf("stopAtValue(toVal)"));
+        expect(floatGuard).toBeLessThan(fire.indexOf("armSpan(fromVal, toVal, m.top.duration)"));
+        expect(vectorGuard).toBeGreaterThan(fire.indexOf("stopAtValue(toVec)"));
+        expect(vectorGuard).toBeLessThan(fire.indexOf("armSpan(fromVec, toVec, m.top.duration)"));
+    });
+
+    test('resolves the axis to "x", "y" or "all" so there is one vector axis path', () => {
+        const resolve = body("resolvedAxis");
+        expect(resolve).toContain('if axis = "x" or axis = "y" then return axis');
+        expect(resolve).toContain('return "all"');
+        expect(shim).not.toContain('"both"');
+        expect(shim).not.toContain("AxisBoth");
+
+        // Nothing outside resolvedAxis() may branch on the raw axis field.
+        for (const name of ["buildVectorTarget", "fireAnimation", "onProposedStopsChanged", "normalizeVectorStops"]) {
+            expect(body(name)).not.toContain("m.top.axis");
+        }
+    });
+
+    test("settles one whole [x, y] candidate on every owned component instead of a dominant axis", () => {
+        const settle = body("onProposedStopsChanged");
+        // The dominant-axis hack and the per-component projection are gone.
+        expect(settle).not.toContain("abs(kvTo[0] - kvFrom[0]) >= abs(kvTo[1] - kvFrom[1])");
+        expect(settle).not.toContain("isAxisPair");
+        expect(settle).not.toContain("for axisIdx");
+        expect(shim).not.toMatch(/function pickStop2D/);
+        // The axis decides which components are owned; one point is chosen for all of them.
+        expect(settle).toContain('ownX = (axis <> "y")');
+        expect(settle).toContain('ownY = (axis <> "x")');
+        expect(settle).toContain("picked = pickStopVector(stops, fromVec, ownX, ownY, dirX, dirY, unfiltered)");
+        expect(settle).toContain("if ownX then toVec[0] = candidate[0]");
+        expect(settle).toContain("if ownY then toVec[1] = candidate[1]");
+        // Speed is held along the path, so both distances are Euclidean over owned components.
+        expect(settle).toContain("newDistance = vecDistance(fromVec, toVec, ownX, ownY)");
+        expect(settle).toContain("originalDistance = vecDistance(kvFrom, kvTo, ownX, ownY)");
+        // A single candidate or a span that moves no owned component drops the direction filter.
+        expect(settle).toContain("unfiltered = (stops.count() = 1) or (dirX = 0 and dirY = 0)");
+        // Nothing ahead keeps the armed destination, like the 1D path.
+        expect(settle).toContain("candidate = [kvTo[0], kvTo[1]]");
+    });
+
+    test("picks the nearest accepted candidate by Euclidean distance", () => {
+        expect(body("vecDistance")).toContain("return sqr(dx * dx + dy * dy)");
+        const vector = body("pickStopVector");
+        expect(vector).toContain("distance = vecDistance(fromVec, candidate, ownX, ownY)");
+        expect(vector).toContain("best = -1");
+        // A component that is not moving (dir 0) adds no constraint: only signed dirs filter.
+        expect(vector).toContain("if dirX > 0 and");
+        expect(vector).toContain("if dirY < 0 and");
+    });
+
+    test("normalizes the vector stop shapes to [x, y] tuples", () => {
+        const normalize = body("normalizeVectorStops");
+        // A flat pair is two candidates, never one destination point.
+        expect(normalize).not.toContain("return [[stops[0], stops[1]]]");
+        expect(body("onProposedStopsChanged")).toContain("normalized = normalizeVectorStops(stops, axis)");
+    });
+
+    test('accepts only [x, y] pairs as stops on axis "all", skipping scalars instead of lifting them', () => {
+        const normalize = body("normalizeVectorStops");
+        // Under "all" a stop must have the vector's arity; a scalar is skipped, not lifted to
+        // [s, s] (the lift settled a legacy flat [X, Y] focus stop onto the row below).
+        const allBranch = normalize.slice(normalize.indexOf('if axis = "all" then'), normalize.indexOf("else if"));
+        expect(allBranch).toContain('if type(candidate) = "roArray" and candidate.count() = 2 then');
+        expect(allBranch).toContain("skipped = skipped + 1");
+        expect(allBranch).not.toContain("[candidate, candidate]");
+        // Skips are logged once per settle, after the loop, not per entry.
+        expect(normalize.indexOf("print")).toBeGreaterThan(normalize.indexOf("end for"));
+        // "x" / "y" still read a scalar as the owned coordinate.
+        expect(normalize.slice(normalize.indexOf("else if"))).toContain("candidates.push([candidate, candidate])");
+        // No usable candidate means no settle; the reported index maps back into proposedStops.
+        const settle = body("onProposedStopsChanged");
+        expect(settle).toContain("if stops.count() = 0 then return");
+        expect(settle).toContain("index = normalized.indices[index]");
+    });
+
+    test('accepts only scalars as stops on axis "x" / "y", skipping arrays instead of reading one component', () => {
+        const normalize = body("normalizeVectorStops");
+        // Under "x" / "y" a stop is the one owned coordinate; an array of any length, [x, y]
+        // included, is skipped and counted with the "all" skips, never read on one component.
+        const axisBranch = normalize.slice(normalize.indexOf("else if"), normalize.indexOf("end for"));
+        expect(axisBranch).toContain('else if type(candidate) = "roArray" then\n            skipped = skipped + 1');
+        expect(axisBranch).not.toContain("candidate.count() >= 2");
+        expect(normalize).not.toMatch(/count\(\) >= 2/);
+        // Scalars still compete, reported at their original index.
+        expect(axisBranch).toContain("candidates.push([candidate, candidate])");
+        expect(axisBranch).toContain("indices.push(i)");
+        // One log per settle names the expected shape for the axis in use.
+        const log = normalize.slice(normalize.indexOf("end for"));
+        expect(log).toContain("not [x, y] pairs on axis");
+        expect(log).toContain("not scalars on axis");
+        expect(log.match(/print /g)).toHaveLength(2);
+    });
+
+    test("only replays written targets and compares node identity rather than id strings", () => {
+        expect(body("init")).toContain("m.targetWritten = false");
+        for (const name of ["onTargetValueChanged", "onTargetVectorChanged"]) {
+            expect(body(name)).toContain("m.targetWritten = true");
+        }
+        const rebind = body("onTargetNodeChanged");
+        expect(rebind).toContain("target.isSameNode(m.lastTarget)");
+        expect(rebind).toContain("if m.targetWritten then fireAnimation()");
+        expect(rebind).not.toContain("m.top.axis");
+        expect(rebind).not.toContain("m.lastTargetId");
+    });
+});
+
+test("filters array stops before scalar arithmetic and preserves source indices", () => {
+    const settle = body("onProposedStopsChanged");
+    expect(settle).toMatch(/normalizeScalarStops\(stops\)[^]*if stops.count\(\) = 0 then return[^]*pickStop1D\(stops/);
+    expect(settle).toMatch(
+        /index = picked\[0\][^]*if index < 0 then[^]*index = 0[^]*else[^]*index = normalized.indices\[index\]/
+    );
+    expect(body("pickStop1D")).toContain("index = -1");
+    expect(body("normalizeScalarStops")).toContain('if type(candidate) = "roArray" then');
+    expect(body("normalizeScalarStops")).toContain("if skipped > 0 then print");
+});

package/src/__tests__/tween.test.ts

@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { beforeAll, describe, expect, jest, test } from "@jest/globals";
+import { hasFeature } from "@roku-sdk/runtime/has-feature";
+import { registerTagAlias } from "@roku-sdk/solid";
+
+jest.mock("@roku-sdk/solid", () => ({ registerTagAlias: jest.fn() }));
+jest.mock("@roku-sdk/runtime/has-feature", () => ({ hasFeature: jest.fn() }));
+
+let resolveTween: (() => string) | undefined;
+
+beforeAll(async () => {
+    await import("../index");
+    resolveTween = jest.mocked(registerTagAlias).mock.calls.find(([tag]) => tag === "tween")?.[1];
+});
+
+describe("tween shim alias", () => {
+    test("is registered for the tween tag", () => {
+        expect(resolveTween).toBeDefined();
+    });
+
+    test("keeps the native node when the firmware has it", () => {
+        jest.mocked(hasFeature).mockReturnValue(true);
+        expect(resolveTween!()).toBe("tween");
+        expect(hasFeature).toHaveBeenCalledWith("tween");
+    });
+
+    test("creates the shim when the firmware does not", () => {
+        jest.mocked(hasFeature).mockReturnValue(false);
+        expect(resolveTween!()).toBe("RsgTweenShim");
+        expect(hasFeature).toHaveBeenCalledWith("tween");
+    });
+});

package/src/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import "./tween";

package/src/refuse-gated-tags.ts

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+// Injected only by Roku builds without compat; importing rsg-ts alone stays tree-shakeable.
+import { hasFeature } from "@roku-sdk/runtime/has-feature";
+import { hasTagAlias, registerTagAlias } from "@roku-sdk/solid";
+
+const GATED_TAGS: Record<string, string> = { tween: "tween" };
+
+for (const [tag, feature] of Object.entries(GATED_TAGS)) {
+    if (hasTagAlias(tag)) continue;
+    registerTagAlias(tag, () => {
+        if (hasFeature(feature)) return tag;
+        throw new Error(
+            `<${tag}> requires the "${feature}" firmware feature or @roku-sdk/compat: this firmware does not report that feature.`
+        );
+    });
+}

package/src/tween/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import "./rsg-tween-shim.xml";
+
+import { hasFeature } from "@roku-sdk/runtime/has-feature";
+import { registerTagAlias } from "@roku-sdk/solid";
+
+registerTagAlias("tween", () => (hasFeature("tween") ? "tween" : "RsgTweenShim"));

package/src/tween/rsg-tween-shim.brs

@@ -0,0 +1,618 @@
+' Copyright (c) 2026 Roku, Inc.
+' SPDX-License-Identifier: MIT
+'
+' Stand-in for the firmware Tween node when firmware does not report the "tween" feature.
+'
+' Drives an Animation + FloatFieldInterpolator | Vector2dFieldInterpolator pair against the
+' Tween field contract. The pair is built here and inserted next to this node, in its parent,
+' so `fieldToInterp` resolves the target's id in the scope the target lives in; it is removed
+' again when targetNode is cleared, or when a span ends after this node was detached from its
+' parent (see onAnimStateChanged and releaseDetached). Value type (float vs vector2d) is detected from the target
+' field and the trigger written; a scalar written to a vector field is auto-expanded to [v, v].
+'
+' Axis modes are "x", "y" and "all", resolved by resolvedAxis() before anything reasons about
+' them, so there is one vector code path.
+'
+' Settle (onProposedStopsChanged): candidates are accepted strictly ahead in the direction of
+' travel (> / <), a stationary span takes the absolute-nearest (sticky step), and the settle
+' duration scales to hold velocity (floored at 0.02s, 0.05s zero-span fallback). On a vector
+' field a candidate is a whole [x, y] point: it must be strictly ahead on every owned component
+' that moves, the nearest such point by Euclidean distance wins, and it is applied to every
+' owned component at once. There is no dominant axis.
+'
+' A candidate has the same arity as the value it settles. On a float field, or a vector field
+' under axis "x" / "y", that is a scalar: the coordinate on the owned component; an array
+' there is skipped. Under axis "all" it is an [x, y] pair; a scalar there is skipped, never
+' lifted to [s, s]. See normalizeVectorStops().
+
+sub init()
+    m.anim         = invalid
+    m.interp       = invalid
+    m.armed        = invalid   ' { node, to }: the last destination armed or pinned, and on which node
+    m.retryTimer   = invalid
+    m.releasePending = false   ' a detached node's Animation is to be released on the next frame
+    m.pendingFire  = false
+    m.lastTarget = invalid
+    m.targetWritten = false
+    m.useScalarTarget = true
+    m.valueType    = invalid   ' "float" | "vector2d", detected lazily
+end sub
+
+' Vector fields animate as vector2d; everything else as float. A targetVector write also
+' forces vector2d (handled at its trigger).
+function detectValueType() as string
+    field = m.top.field
+    if field = "translation" or field = "scale" or field = "scaleRotateCenter" then
+        return "vector2d"
+    end if
+    return "float"
+end function
+
+' Lazily build m.anim / m.interp in this node's parent. Returns false while there is no target
+' or no parent to put them in.
+function ensureAnimReady() as boolean
+    if m.top.targetNode = invalid then return false
+    parent = m.top.getParent()
+    if parent = invalid then return false
+    if m.valueType = invalid then m.valueType = detectValueType()
+
+    if m.anim <> invalid then
+        animParent = m.anim.getParent()
+        if animParent = invalid or not animParent.isSameNode(parent) then
+            if animParent <> invalid then animParent.removeChild(m.anim)
+            parent.appendChild(m.anim)
+        end if
+    else
+        m.anim = createObject("roSGNode", "Animation")
+        m.anim.repeat = false
+        m.anim.observeFieldScopedEx("state", "onAnimStateChanged")
+        parent.appendChild(m.anim)
+    end if
+
+    wantType = "FloatFieldInterpolator"
+    if m.valueType = "vector2d" then wantType = "Vector2DFieldInterpolator"
+    if m.interp <> invalid and LCase(m.interp.subtype()) <> LCase(wantType) then
+        m.anim.removeChild(m.interp)
+        m.interp = invalid
+    end if
+    if m.interp = invalid then
+        m.interp = createObject("roSGNode", wantType)
+        m.interp.key = [0.0, 1.0]
+        m.anim.appendChild(m.interp)
+    end if
+    return true
+end function
+
+' Take the animation out of the parent, so a disposed tween leaves nothing behind in a tree
+' it no longer belongs to and holds no node.
+sub releaseAnim()
+    m.pendingFire = false
+    m.releasePending = false
+    m.armed = invalid
+    if m.retryTimer <> invalid then m.retryTimer.control = "stop"
+    if m.anim = invalid then return
+    m.anim.unobserveFieldScoped("state")
+    m.anim.control = "stop"
+    animParent = m.anim.getParent()
+    if animParent <> invalid then animParent.removeChild(m.anim)
+    m.anim = invalid
+    m.interp = invalid
+end sub
+
+' The Animation lives beside this node, not under it, so removing this node from the tree does
+' not remove it. The usual release is immediate: the Tween wrapper clears targetNode when it is
+' disposed, and onTargetNodeChanged calls releaseAnim. For a raw <tween> removed mid-flight
+' without clearing targetNode there is no timer and no polling: a span is finite and every span
+' that starts ends in "stopped", so that transition is the moment to check ownership (see
+' onAnimStateChanged). The Animation lingers in the parent until its span ends. A raw <tween>
+' removed while idle or paused is not caught: a paused span never reaches "stopped", and a node
+' has no destructor and no observable parent to hook instead. Clear targetNode first.
+'
+' The release is deferred by one frame rather than run inside the Animation's own state
+' observer, because unobserving a field and removing the node from inside that field's callback
+' is not something SceneGraph documents as safe. The deferral reuses the retry Timer.
+sub releaseDetached()
+    m.releasePending = true
+    startRetryTimer()
+end sub
+
+' A trigger can arrive before this node is inserted into its parent; retry on the next frames
+' until it is.
+sub scheduleRetry()
+    m.pendingFire = true
+    startRetryTimer()
+end sub
+
+sub startRetryTimer()
+    if m.retryTimer = invalid then
+        m.retryTimer = createObject("roSGNode", "Timer")
+        m.retryTimer.duration = 0.001
+        m.retryTimer.repeat = false
+        m.retryTimer.observeFieldScoped("fire", "onRetryTimerFire")
+        m.top.appendChild(m.retryTimer)
+    end if
+    m.retryTimer.control = "start"
+end sub
+
+sub onRetryTimerFire()
+    if m.releasePending then
+        m.releasePending = false
+        ' Re-check: a new span may have started, or the node been re-attached, since the request.
+        if m.anim <> invalid then
+            if m.anim.state = "stopped" and m.top.getParent() = invalid then releaseAnim()
+        end if
+        return
+    end if
+    if not m.pendingFire then return
+    if m.top.targetNode = invalid then return
+    fireAnimation()
+end sub
+
+' Bind the interpolator to the CURRENT target's field. Without a rebind on target change a
+' pooled node recycled onto another cell keeps animating its previous owner.
+sub bindField()
+    ' Interpolators address a node by id, but the public API only requires a reference.
+    ' Give anonymous targets a stable unique id without changing a caller-assigned id.
+    if m.top.targetNode.id = "" then
+        m.top.targetNode.id = "rsg-tween-" + createObject("roDeviceInfo").GetRandomUUID()
+    end if
+    desiredField = m.top.targetNode.id + "." + m.top.field
+    if m.interp.fieldToInterp <> desiredField then
+        m.interp.fieldToInterp = desiredField
+    end if
+end sub
+
+' Target-node changes animate the standing target, but only after a target write.
+sub onTargetNodeChanged()
+    target = m.top.targetNode
+    if target = invalid then
+        m.lastTarget = invalid
+        releaseAnim()
+        return
+    end if
+    if m.lastTarget <> invalid then
+        if target.isSameNode(m.lastTarget) then return
+    end if
+    m.lastTarget = target
+    ' Whatever was armed belongs to the previous node; the new one starts from its own value.
+    m.armed = invalid
+
+    if m.targetWritten then fireAnimation()
+end sub
+
+sub onTargetValueChanged()
+    m.useScalarTarget = true
+    m.targetWritten = true
+    m.valueType = detectValueType()
+    fireAnimation()
+end sub
+
+sub onTargetVectorChanged()
+    m.useScalarTarget = false
+    m.targetWritten = true
+    ' An explicit vector target forces vector2d regardless of field name.
+    m.valueType = "vector2d"
+    fireAnimation()
+end sub
+
+sub onControlChanged()
+    if m.anim = invalid then return
+    ctrl = m.top.control
+    if ctrl = "" then return
+    ' A stop puts the target back at the span's start, so the armed destination no longer holds.
+    if ctrl = "stop" then m.armed = invalid
+    m.anim.control = ctrl
+end sub
+
+' The axis mode. Every read of the axis goes through here so there is exactly one set of
+' vector semantics: "x" and "y" move one component and hold the other at preserveOther,
+' "all" moves the whole vector.
+function resolvedAxis() as string
+    axis = m.top.axis
+    if axis = "x" or axis = "y" then return axis
+    return "all"
+end function
+
+' Build the vector2d target from the trigger inputs (scalar auto-expansion + axis rules).
+function buildVectorTarget() as object
+    if not m.useScalarTarget and m.top.targetVector <> invalid and m.top.targetVector.count() >= 2 then
+        return [m.top.targetVector[0], m.top.targetVector[1]]
+    end if
+    v = m.top.targetValue
+    axis = resolvedAxis()
+    preserveOther = m.top.preserveOther
+    if axis = "y" then return [preserveOther, v]
+    if axis = "x" then return [v, preserveOther]
+    ' "all": the scalar goes on both slots (uniform scale), as the native node does.
+    return [v, v]
+end function
+
+sub fireAnimation()
+    ' A trigger can be written before targetNode; the native node keeps it, so hold it until
+    ' onTargetNodeChanged delivers a target.
+    if m.top.targetNode = invalid then
+        m.pendingFire = true
+        return
+    end if
+    if not ensureAnimReady() then
+        if m.top.duration = 0 then
+            snapWithoutAnim()
+        else
+            scheduleRetry()
+        end if
+        return
+    end if
+    m.pendingFire = false
+    bindField()
+
+    targetNode = m.top.targetNode
+
+    if m.valueType = "float" then
+        toVal = m.top.targetValue
+        if not m.useScalarTarget and m.top.targetVector <> invalid and m.top.targetVector.count() >= 1 then
+            toVal = m.top.targetVector[0]
+        end if
+        if m.top.duration = 0 then
+            stopAtValue(toVal)
+            targetNode.setField(m.top.field, toVal)
+            return
+        end if
+        if isArmedFor(toVal, true, true) then return
+        fromVal = targetNode.getField(m.top.field)
+        armSpan(fromVal, toVal, m.top.duration)
+    else
+        toVec = buildVectorTarget()
+        if m.top.duration = 0 then
+            stopAtValue(toVec)
+            targetNode.setField(m.top.field, toVec)
+            return
+        end if
+        axis = resolvedAxis()
+        if isArmedFor(toVec, axis <> "y", axis <> "x") then return
+        liveVec = targetNode.getField(m.top.field)
+        if liveVec = invalid then liveVec = [0, 0]
+        preserveOther = m.top.preserveOther
+        if axis = "y" then
+            fromVec = [preserveOther, liveVec[1]]
+        else if axis = "x" then
+            fromVec = [liveVec[0], preserveOther]
+        else
+            fromVec = liveVec
+        end if
+        armSpan(fromVec, toVec, m.top.duration)
+    end if
+
+    date = createObject("roDateTime")
+    m.top.animationStart = [date.AsSeconds(), date.GetMilliseconds()]
+end sub
+
+' The one place a span starts. Records the destination so a later write of the same one is a
+' no-op (see isArmedFor). Every start reads the current ease, including a settle re-arm.
+' Stop resets the target to keyValue[0], so the new keys go in first: the reset then lands on
+' fromValue (the live position) rather than on the previous span's start.
+sub armSpan(fromValue as dynamic, toValue as dynamic, duration as float)
+    m.anim.easeFunction = m.top.easeFunction
+    m.anim.duration   = duration
+    m.interp.keyValue = [fromValue, toValue]
+    m.anim.control    = "stop"
+    m.anim.control    = "start"
+    m.armed = { node: m.top.targetNode, to: toValue }
+end sub
+
+' True when `target` is the destination last armed or pinned on the current target node, on
+' every owned component. Writing it again must not restart: FlexGrid re-writes the settled
+' position as a settle lands, and a restart re-arms the last few pixels over the full duration,
+' so the end of the settle crawls. The other renderer implementations follow the same rule. A
+' target-node change and a "stop" control clear the record, so neither is ever skipped.
+function isArmedFor(target as dynamic, ownX as boolean, ownY as boolean) as boolean
+    if m.armed = invalid then return false
+    if not m.armed.node.isSameNode(m.top.targetNode) then return false
+    armedTo = m.armed.to
+    if type(target) <> "roArray" then
+        if type(armedTo) = "roArray" then return false
+        return abs(armedTo - target) < 0.01
+    end if
+    if type(armedTo) <> "roArray" then return false
+    if ownX and abs(armedTo[0] - target[0]) >= 0.01 then return false
+    if ownY and abs(armedTo[1] - target[1]) >= 0.01 then return false
+    return true
+end function
+
+' Stop resets the target to keyValue[0], so pin both keys before issuing the control.
+sub stopAtValue(value as dynamic)
+    m.interp.keyValue = [value, value]
+    m.anim.control = "stop"
+    m.armed = { node: m.top.targetNode, to: value }
+end sub
+
+' A snap needs no animation, so it lands even before this node has a parent.
+sub snapWithoutAnim()
+    m.pendingFire = false
+    if m.valueType = invalid then m.valueType = detectValueType()
+    if m.valueType = "float" then
+        toVal = m.top.targetValue
+        if not m.useScalarTarget and m.top.targetVector <> invalid and m.top.targetVector.count() >= 1 then
+            toVal = m.top.targetVector[0]
+        end if
+        m.top.targetNode.setField(m.top.field, toVal)
+        m.armed = { node: m.top.targetNode, to: toVal }
+    else
+        toVec = buildVectorTarget()
+        m.top.targetNode.setField(m.top.field, toVec)
+        m.armed = { node: m.top.targetNode, to: toVec }
+    end if
+end sub
+
+sub onProposedStopsChanged(data as dynamic)
+    if m.anim = invalid or m.interp = invalid then return
+    if not ensureAnimReady() then return
+    stops = data.getData()
+    if stops = invalid or stops.count() = 0 then return
+    if m.interp.keyValue = invalid or m.interp.keyValue.count() < 2 then return
+    bindField()
+
+    targetNode = m.top.targetNode
+    kvFrom = m.interp.keyValue[0]
+    kvTo   = m.interp.keyValue[1]
+
+    if m.valueType = "float" then
+        normalized = normalizeScalarStops(stops)
+        stops = normalized.candidates
+        if stops.count() = 0 then return
+        fromPos = targetNode.getField(m.top.field)
+        isIncreasing = (kvTo > kvFrom)
+        isStationary = (kvTo = kvFrom)
+        picked = pickStop1D(stops, fromPos, isIncreasing, isStationary, kvTo)
+        index = picked[0]
+        if index < 0 then
+            index = 0
+        else
+            index = normalized.indices[index]
+        end if
+        closestStop = picked[1]
+
+        originalDistance = abs(kvTo - kvFrom)
+        newDistance = abs(closestStop - fromPos)
+        if newDistance = 0 then
+            stopAtValue(fromPos)
+            fireAnimationStop(index, closestStop, 0)
+            return
+        end if
+        newDuration = scaleSettle(m.anim.duration, originalDistance, newDistance)
+
+        armSpan(fromPos, closestStop, newDuration)
+
+        fireAnimationStop(index, closestStop, newDuration)
+        return
+    end if
+
+    ' vector2d. One code path for every axis mode. A candidate is a whole [x, y] point, chosen
+    ' once and applied to every component the axis owns: "x" and "y" own one component and hold
+    ' the other where it is, "all" owns both. There is no dominant-axis selection, so a diagonal glide settles X and Y together onto one candidate.
+    axis = resolvedAxis()
+    normalized = normalizeVectorStops(stops, axis)
+    stops = normalized.candidates
+    ' No candidate of the right arity: no settle. The armed span keeps running to its own
+    ' target and onAnimationStop does not fire, as for an empty proposedStops.
+    if stops.count() = 0 then return
+
+    fromVec = targetNode.getField(m.top.field)
+    if fromVec = invalid then fromVec = [0, 0]
+
+    ownX = (axis <> "y")
+    ownY = (axis <> "x")
+    dirX = 0
+    dirY = 0
+    if ownX then dirX = sgn(kvTo[0] - kvFrom[0])
+    if ownY then dirY = sgn(kvTo[1] - kvFrom[1])
+
+    ' One candidate is a destination, not a choice, so the direction-of-travel filter is
+    ' dropped for it. A span that moves no owned component (FlexGrid's sticky-step arming)
+    ' also drops the filter and takes the absolute-nearest candidate.
+    unfiltered = (stops.count() = 1) or (dirX = 0 and dirY = 0)
+
+    picked = pickStopVector(stops, fromVec, ownX, ownY, dirX, dirY, unfiltered)
+    index = picked[0]
+    if index < 0 then
+        ' Nothing ahead: keep the armed span running to its own target, as the 1D path does
+        ' when no candidate is accepted.
+        candidate = [kvTo[0], kvTo[1]]
+        index = 0
+    else
+        candidate = stops[index]
+        ' Report the index into proposedStops as written, not into the filtered list.
+        index = normalized.indices[index]
+    end if
+
+    toVec = [fromVec[0], fromVec[1]]
+    if ownX then toVec[0] = candidate[0]
+    if ownY then toVec[1] = candidate[1]
+
+    ' The reported position is a scalar: the owned component for "x"/"y", and for "all" the
+    ' component that travels further, which is also the one that dominated the pre-unification
+    ' report.
+    reportIdx = 0
+    if axis = "y" then reportIdx = 1
+    if axis = "all" and abs(toVec[1] - fromVec[1]) > abs(toVec[0] - fromVec[0]) then reportIdx = 1
+    closestStop = toVec[reportIdx]
+
+    newDistance = vecDistance(fromVec, toVec, ownX, ownY)
+    originalDistance = vecDistance(kvFrom, kvTo, ownX, ownY)
+    if newDistance = 0 then
+        stopAtValue(fromVec)
+        fireAnimationStop(index, closestStop, 0)
+        return
+    end if
+    newDuration = scaleSettle(m.anim.duration, originalDistance, newDistance)
+
+    armSpan([fromVec[0], fromVec[1]], toVec, newDuration)
+
+    fireAnimationStop(index, closestStop, newDuration)
+end sub
+
+' Euclidean length of b - a over the owned components; an unowned component contributes 0.
+function vecDistance(a as object, b as object, ownX as boolean, ownY as boolean) as float
+    dx = 0
+    dy = 0
+    if ownX then dx = b[0] - a[0]
+    if ownY then dy = b[1] - a[1]
+    return sqr(dx * dx + dy * dy)
+end function
+
+' Bring `proposedStops` on a vector field to one shape, a list of [x, y] candidates, keeping
+' only entries whose arity matches the value being settled. Each entry is judged on its own,
+' so in a mixed list the valid entries still compete. Returns { candidates, indices }, where
+' indices[k] is the proposedStops index candidates[k] came from.
+'
+'   - axis "x" / "y": the settled value is the one owned coordinate, so a candidate must be a
+'     scalar s (only the owned component is read; [s, s] is just a carrier). An array of any
+'     length, [x, y] included, is skipped and logged once per settle.
+'   - axis "all": the settled value is the whole vector, so a candidate must be an [x, y]
+'     pair. Scalars, and arrays of any other length, are skipped and logged once per settle.
+'
+' Scalars are deliberately not lifted to [s, s] under "all". That lift turned a legacy flat
+' [X, Y] focus-highlight stop into two diagonal candidates [X, X] and [Y, Y]: holding left
+' and releasing settled the highlight onto the row below. The same rule extends to wider
+' values: a Rect2D field would take [x, y, w, h] candidates and skip anything else.
+'
+' Pairs are likewise not read on one component under "x" / "y": a pair there is the wrong
+' arity for the one coordinate being settled, and reading half of it hides a caller that
+' meant "all".
+function normalizeVectorStops(stops as object, axis as string) as object
+    candidates = []
+    indices = []
+    skipped = 0
+    for i = 0 to stops.count() - 1
+        candidate = stops[i]
+        if axis = "all" then
+            if type(candidate) = "roArray" and candidate.count() = 2 then
+                candidates.push(candidate)
+                indices.push(i)
+            else
+                skipped = skipped + 1
+            end if
+        else if type(candidate) = "roArray" then
+            skipped = skipped + 1
+        else
+            candidates.push([candidate, candidate])
+            indices.push(i)
+        end if
+    end for
+    if skipped > 0 then
+        if axis = "all" then
+            print "RsgTweenShim: skipped "; skipped; " proposedStops entries that are not [x, y] pairs on axis "; chr(34); "all"; chr(34)
+        else
+            print "RsgTweenShim: skipped "; skipped; " proposedStops entries that are not scalars on axis "; chr(34); axis; chr(34)
+        end if
+    end if
+    return { candidates: candidates, indices: indices }
+end function
+
+' Vector candidate selection. A candidate is accepted when it lies strictly ahead on every
+' owned component that is moving (a component the span does not move imposes no constraint);
+' among accepted candidates the nearest by Euclidean distance over the owned components wins.
+' Unfiltered (single destination or stationary span) accepts everything. Returns [index] with
+' -1 when nothing was accepted.
+function pickStopVector(stops as object, fromVec as object, ownX as boolean, ownY as boolean, dirX as integer, dirY as integer, unfiltered as boolean) as object
+    best = -1
+    bestDistance = invalid
+    for i = 0 to stops.count() - 1
+        candidate = stops[i]
+        accept = true
+        if not unfiltered then
+            if dirX > 0 and not (candidate[0] > fromVec[0]) then accept = false
+            if dirX < 0 and not (candidate[0] < fromVec[0]) then accept = false
+            if dirY > 0 and not (candidate[1] > fromVec[1]) then accept = false
+            if dirY < 0 and not (candidate[1] < fromVec[1]) then accept = false
+        end if
+        if accept then
+            distance = vecDistance(fromVec, candidate, ownX, ownY)
+            if bestDistance = invalid or distance < bestDistance then
+                bestDistance = distance
+                best = i
+            end if
+        end if
+    end for
+    return [best]
+end function
+
+' Unified 1D candidate selection: accept strictly ahead in the direction of travel; a
+' stationary span takes the absolute-nearest. Returns [index, stopValue].
+' Float fields take scalar stops only, retaining the caller's original indices.
+function normalizeScalarStops(stops as object) as object
+    candidates = []
+    indices = []
+    skipped = 0
+    for i = 0 to stops.count() - 1
+        candidate = stops[i]
+        if type(candidate) = "roArray" then
+            skipped = skipped + 1
+        else
+            candidates.push(candidate)
+            indices.push(i)
+        end if
+    end for
+    if skipped > 0 then print "RsgTweenShim: skipped "; skipped; " proposedStops entries that are not scalars on a float field"
+    return { candidates: candidates, indices: indices }
+end function
+
+function pickStop1D(stops as object, fromPos as float, isIncreasing as boolean, isStationary as boolean, defaultTo as float) as object
+    closestStop = defaultTo
+    minDistance = invalid
+    index = -1
+    for i = 0 to stops.count() - 1
+        stopPosition = stops[i]
+        distance = abs(stopPosition - fromPos)
+        accept = false
+        if isStationary then
+            accept = true
+        else if isIncreasing then
+            if stopPosition > fromPos then accept = true
+        else
+            if stopPosition < fromPos then accept = true
+        end if
+        if accept then
+            if minDistance = invalid or distance < minDistance then
+                minDistance = distance
+                closestStop = stopPosition
+                index = i
+            end if
+        end if
+    end for
+    return [index, closestStop]
+end function
+
+' Velocity-preserving settle duration: hold the original span's units-per-second across
+' the shortened distance. Zero-length span → 0.05s; floored at 0.02s.
+function scaleSettle(originalDuration as float, originalDistance as float, newDistance as float) as float
+    if originalDistance > 0 then
+        newDuration = originalDuration * newDistance / originalDistance
+    else
+        newDuration = 0.05
+    end if
+    if newDuration < 0.02 then newDuration = 0.02
+    return newDuration
+end function
+
+sub onAnimStateChanged(data as dynamic)
+    ' A span has ended. If this node was detached meanwhile, nobody owns the Animation any more.
+    ' Judge the live state, not the notification: a restart delivers "stopped" after armSpan has
+    ' already started the next span.
+    if m.anim <> invalid then
+        if m.anim.state = "stopped" and m.top.getParent() = invalid then releaseDetached()
+    end if
+    curVal = invalid
+    if m.top.targetNode <> invalid and m.top.field <> "" then
+        curVal = m.top.targetNode.getField(m.top.field)
+    end if
+    m.top.animationState = [data.getData(), curVal]
+end sub
+
+' Keep epoch milliseconds in double precision: a 32-bit BRS integer overflows here.
+sub fireAnimationStop(index as integer, stopPos as float, delaySeconds as float)
+    currentTime = createObject("roDateTime")
+    totalMs# = currentTime.AsSeconds() * 1000# + currentTime.GetMilliseconds() + Int(delaySeconds * 1000#)
+    seconds# = Int(totalMs# / 1000#)
+    milliseconds = Int(totalMs# - seconds# * 1000#)
+    m.top.animationStop = [index, stopPos, [seconds#, milliseconds]]
+end sub

package/src/tween/rsg-tween-shim.xml

@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2026 Roku, Inc. -->
+<!-- SPDX-License-Identifier: MIT -->
+<!--
+    Stand-in for the firmware `Tween` node when firmware does not report the "tween" feature.
+
+    `@roku-sdk/compat` aliases the `<tween>` tag to this component when the firmware has no
+    native `Tween`, so app source is unchanged either way. It presents the same field contract
+    as the native node, defaults included, and nothing more: a field the native node lacks would
+    work with the shim and break with the native node. It drives an `Animation` + `*FieldInterpolator` pair it
+    builds itself.
+
+    That pair is inserted next to this node, in its parent, rather than under it: an
+    interpolator resolves the `id` in `fieldToInterp` within the component scope that holds its
+    `Animation`, and this component's own scope cannot see the target. Because the pair is not
+    under this node, removing this node does not remove it. The `Tween` wrapper clears `targetNode`
+    when it is disposed, which releases the pair at once. A raw `<tween>` removed mid-flight
+    without clearing `targetNode` is released when its span ends, which is the next "stopped"
+    state; nothing polls. A raw `<tween>` removed while idle or paused never reaches that state,
+    so its Animation stays in the parent; clear `targetNode` first.
+
+    Field-order discipline (BrightScript fires onChange in declaration order): all config
+    fields (targetNode, field, duration, easeFunction, axis, preserveOther) are declared
+    BEFORE the trigger fields (targetValue, targetVector) so their writes land before the
+    trigger's onChange fires.
+-->
+<component name="RsgTweenShim" extends="Group">
+    <interface>
+        <!-- ── Config (must precede the trigger fields) ──────────────────────────── -->
+        <field id="targetNode" type="node" onChange="onTargetNodeChanged" />
+        <!-- Field on targetNode to animate ("translation", "scale", "opacity", ...). -->
+        <field id="field" type="string" value="translation" />
+        <field id="duration" type="float" value="0.333" />
+        <field id="easeFunction" type="string" value="linear" />
+        <!-- axis: "x" | "y" | "all". Vector fields only. Anything other than "x" or "y" is
+             "all". -->
+        <!-- @ts-field axis { type: "'x' | 'y' | 'all'" } -->
+        <field id="axis" type="string" value="all" />
+        <!-- Value held on the non-animated axis for single-axis vector animation. -->
+        <field id="preserveOther" type="float" value="0" />
+
+        <!-- ── Triggers (writing one starts the animation) ───────────────────────── -->
+        <!-- Float target. For a vector field a scalar is auto-expanded to [v, v]. -->
+        <field id="targetValue" type="float" value="0" onChange="onTargetValueChanged" />
+        <!-- Vector2d target [x, y]. -->
+        <!-- @ts-field targetVector { type: "[number, number]" } -->
+        <field id="targetVector" type="array" value="[]" onChange="onTargetVectorChanged" />
+
+        <!-- Settle candidates. A candidate has the arity of the settled value: float fields
+             and axis x/y on a vector field: number[]; axis all (the default) on a vector field:
+             [number, number][]; axis is ignored on float fields. Entries of the wrong arity are
+             skipped (a scalar under "all" is never expanded to [s, s], an array under "x" / "y"
+             is never read on one component). On a vector field one whole point is chosen
+             (strictly ahead on every moving owned component, then nearest) and applied to every
+             component the axis owns. -->
+        <!-- @ts-field proposedStops { type: "number[] | [number, number][]" } -->
+        <field id="proposedStops" type="array" value="[]" onChange="onProposedStopsChanged" />
+
+        <!-- Explicit playback control: "start" | "stop" | "pause" | "resume" | "finish". -->
+        <field id="control" type="string" value="" onChange="onControlChanged" />
+
+        <!-- ── Outputs (render thread → TypeScript) ──────────────────────────────── -->
+        <!-- @ts-field animationStart { propName: "onAnimationStart", type: "(t: [number, number]) => void" } -->
+        <field id="animationStart" type="array" value="[0,0]" />
+        <!-- @ts-field animationStop { propName: "onAnimationStop", type: "(t: [number, number, [number, number]]) => void" } -->
+        <field id="animationStop" type="array" value="[0,0]" />
+        <!-- @ts-field animationState { propName: "onAnimationState", type: "(t: [import(\"@roku-sdk/components\").AnimationState, number | import(\"@roku-sdk/components\").Vector2D]) => void" } -->
+        <field id="animationState" type="array" value="[]" />
+    </interface>
+    <script type="text/brightscript" uri="rsg-tween-shim.brs" />
+</component>

package/src/tween/rsg-tween-shim.xml.d.ts

@@ -0,0 +1,79 @@
+// Auto-generated TypeScript declarations for XML component import.
+// DO NOT EDIT — this file is regenerated during build.
+//
+// Source component: RsgTweenShim
+// Extends: Group
+
+import type { IGroupProps } from "@roku-sdk/components";
+import type { TypedXmlComponent } from "@roku-sdk/interfaces";
+
+interface RsgTweenShimFields {
+    targetNode: import("@roku-sdk/interfaces").DomNode;
+    /** @default "translation" */
+    field: string;
+    /** @default "0.333" */
+    duration: number;
+    /** @default "linear" */
+    easeFunction: string;
+    /** @default "all" */
+    axis: string;
+    /** @default "0" */
+    preserveOther: number;
+    /** @default "0" */
+    targetValue: number;
+    /** @default "[]" */
+    targetVector: unknown[];
+    /** @default "[]" */
+    proposedStops: unknown[];
+    /** @default "" */
+    control: string;
+    /** @default "[0,0]" */
+    animationStart: unknown[];
+    /** @default "[0,0]" */
+    animationStop: unknown[];
+    /** @default "[]" */
+    animationState: unknown[];
+}
+
+export interface IRsgTweenShimProps extends IGroupProps {
+    targetNode?: import("@roku-sdk/interfaces").DomNode;
+    field?: string;
+    duration?: number;
+    easeFunction?: string;
+    axis?: 'x' | 'y' | 'all';
+    preserveOther?: number;
+    targetValue?: number;
+    targetVector?: [number, number];
+    proposedStops?: number[] | [number, number][];
+    control?: string;
+    onAnimationStart?: (t: [number, number]) => void;
+    onAnimationStop?: (t: [number, number, [number, number]]) => void;
+    onAnimationState?: (t: [import("@roku-sdk/components").AnimationState, number | import("@roku-sdk/components").Vector2D]) => void;
+}
+
+declare const _default: TypedXmlComponent<"RsgTweenShim", RsgTweenShimFields>;
+export default _default;
+
+declare module "@roku-sdk/solid" {
+    namespace JSX {
+        interface IntrinsicElements {
+            rsgTweenShim: IRsgTweenShimProps;
+        }
+    }
+}
+
+declare module "@roku-sdk/solid/jsx-runtime" {
+    namespace JSX {
+        interface IntrinsicElements {
+            rsgTweenShim: IRsgTweenShimProps;
+        }
+    }
+}
+
+declare module "solid-js" {
+    namespace JSX {
+        interface IntrinsicElements {
+            rsgTweenShim: IRsgTweenShimProps;
+        }
+    }
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "@roku-sdk/dev-tools/typescript-config/tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "types": ["@roku-sdk/interfaces/global"]
+    },
+    "include": ["src/**/*"],
+    "exclude": ["dist", "node_modules"],
+    "files": ["xml.d.ts"]
+}

package/xml.d.ts

@@ -0,0 +1,4 @@
+declare module "*.xml" {
+    const componentName: string;
+    export default componentName;
+}