@roku-sdk/ads 0.0.0-stage → 2.19.0

package/src/ads.tsx

@@ -0,0 +1,388 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import type { IContentNodeProps } from "@roku-sdk/components";
+import { DomNode } from "@roku-sdk/interfaces";
+import type { Component } from "@roku-sdk/solid";
+
+import AdsXML from "./xml-components/ads/ads.xml";
+void AdsXML; // Ensure the import is preserved
+
+export type EventHandler<T> = (event: T) => void;
+
+/**
+ * States the RAF task reports. There is no failure state: if RAF is not linked the
+ * task cannot run far enough to report anything, so "never reached `"ready"`" is
+ * what an initialisation failure looks like.
+ */
+export type AdsState = "none" | "ready" | "stopped";
+export type EventHandlerAdsState = EventHandler<AdsState>;
+export type ShowAdsResult = "none" | "completed" | "user_exited" | "error";
+export type ConstructStitchedStreamResult = "none" | "completed" | "error";
+export type RenderStitchedStreamResult = "none" | "completed" | "user_exited" | "error";
+export type StitchedAdsInitResult = "none" | "completed" | "error";
+
+/**
+ * Ad counter shown during a CSAI break: `{ start: 1, total: 4 }` renders "Ad 1 of 4".
+ *
+ * A type alias rather than an interface so it stays assignable to the SceneGraph
+ * assocarray field the task reads it from.
+ */
+export type AdCounter = {
+    /** Position of the first ad in this call, 1-based. */
+    start: number;
+    /** Total ads the counter should count towards, across the whole break. */
+    total: number;
+};
+
+export type AdsCommand =
+    "none" | "getAds" | "showAds" | "stop" | "stitchedAdsInit" | "constructStitchedStream" | "renderStitchedStream";
+
+/*
+ * The five interfaces below describe the payload RAF hands back from `getAds()`,
+ * as observed crossing the SceneGraph bridge.
+ *
+ * Two things shape them. Field names are RAF's own and are **lowercase** over the
+ * bridge (`rendersequence`, `mimetype`) rather than camelCase. And RAF passes
+ * ad-server data through largely untouched, so which fields a given response
+ * carries depends on the VAST tag that answered: everything a pod is not
+ * structurally obliged to have is therefore optional, and a response may well
+ * carry fields not listed here.
+ *
+ * The one structural assumption is `AdPod.ads` — the task normalises RAF's reply
+ * to the pod array before writing it, and a pod with no ads has nothing to play.
+ */
+
+/**
+ * A single media stream for an ad creative. Several streams describe the same
+ * creative at different bitrates or in different formats.
+ */
+export interface AdStream {
+    /** Stream URL. */
+    url?: string;
+    /** Stream bitrate in kbps. */
+    bitrate?: number;
+    /** Video width in pixels. */
+    width?: number;
+    /** Video height in pixels. */
+    height?: number;
+    /** MIME type, e.g. `"video/mp4"`. */
+    mimetype?: string;
+    /** Stream provider. */
+    provider?: string;
+    /** Stream identifier assigned by the ad server, e.g. `"GDFP"`. */
+    id?: string;
+}
+
+/**
+ * One tracking event RAF fires for an ad or pod.
+ *
+ * Note the shape: tracking arrives as a flat list of events, not as a map keyed
+ * by event name, so finding one means searching on {@link AdTrackingEvent.event}.
+ */
+export interface AdTrackingEvent {
+    /** Event name, e.g. `"Impression"`, `"Start"`, `"Error"`. */
+    event?: string;
+    /** URL fired for the event. */
+    url?: string;
+    /** Ad this event belongs to. */
+    adid?: string;
+    /** Creative this event belongs to. */
+    creativeid?: string;
+    /** Whether RAF has already fired it. */
+    triggered?: boolean;
+}
+
+/** A companion banner offered alongside an ad. */
+export interface CompanionAd {
+    /** Banner asset URL. */
+    url?: string;
+    /** Banner width in pixels. */
+    width?: number;
+    /** Banner height in pixels. */
+    height?: number;
+    /** MIME type of the banner asset. */
+    mimetype?: string;
+    /** Banner provider. */
+    provider?: string;
+    /** Click-through URL. */
+    clickthrough?: string;
+    /** Tracking events for the banner. */
+    tracking?: AdTrackingEvent[];
+}
+
+/** A single ad within an ad pod. */
+export interface Ad {
+    /** Ad duration in seconds. */
+    duration?: number;
+    /** Ad title from VAST. */
+    adtitle?: string;
+    /** Creative streams, typically the same creative at several bitrates. */
+    streams?: AdStream[];
+    /** Tracking events, as a flat list rather than keyed by event name. */
+    tracking?: AdTrackingEvent[];
+    /** Companion banners offered with this ad. */
+    companionads?: CompanionAd[];
+    /** Click-through URL. */
+    clickthrough?: string;
+    /** Ad identifier. */
+    adid?: string;
+    /** Creative identifier. */
+    creativeid?: string;
+    /** Creative ad identifier from VAST. */
+    creativeadid?: string;
+    /** Ad server the creative came from. */
+    adserver?: string;
+    /** Ad system named in the VAST response. */
+    adsystem?: string;
+    /** Identifier for the ad request that produced this ad. */
+    requestid?: string;
+    /** Stream format reported for the creative. */
+    streamformat?: string;
+    /** VAST `AdParameters`, passed through as the opaque string the tag carried. */
+    adparameters?: string;
+}
+
+/**
+ * A pod (group) of one or more ads. Pods correspond to ad breaks.
+ *
+ * There is no ad count: it is `ads.length`. The break's slot is
+ * {@link AdPod.rendersequence}, a string, and its scheduled offset is
+ * {@link AdPod.rendertime} — which RAF acts on itself, so neither is a cue the
+ * app has to schedule against.
+ */
+export interface AdPod {
+    /** Ads in this pod, in playback order. */
+    ads: Ad[];
+    /** Duration of the entire pod in seconds. */
+    duration?: number;
+    /** Where the break sits: `"preroll"`, `"midroll"` or `"postroll"`. */
+    rendersequence?: string;
+    /**
+     * Playback position in seconds the break is scheduled at. RAF schedules the
+     * break itself, so this describes the pod rather than being something the app
+     * has to act on.
+     */
+    rendertime?: number;
+    /** Tracking events for the pod, as a flat list. */
+    tracking?: AdTrackingEvent[];
+    /** Whether the pod has already been viewed. */
+    viewed?: boolean;
+}
+
+/**
+ * Handler for the ad pods a `getAds` command returns.
+ *
+ * The underlying SceneGraph field is an untyped array, so {@link AdPod} is a
+ * narrowing of it rather than a guarantee the bridge enforces. It matches what
+ * RAF was observed to send, and its fields are optional accordingly — but a pod
+ * field is worth reading only if the app genuinely needs it. Deciding whether a
+ * break exists takes just `pods.length`.
+ */
+export type EventHandlerAdPods = EventHandler<AdPod[]>;
+
+/**
+ * Props for the {@link Ads} SceneGraph Task wrapper.
+ *
+ * The underlying `ads` component runs RAF (`Roku_Ads()`) in a background BrightScript
+ * task. TypeScript drives ad fetch and render by writing reactive props; the task
+ * invokes callbacks when results are ready.
+ *
+ * Typical CSAI flow:
+ * 1. Wait for {@link IAdsProps.onAdsState} with `"ready"`
+ * 2. Set {@link IAdsProps.adUrl} and {@link IAdsProps.command} to `"getAds"`
+ * 3. Handle {@link IAdsProps.onGetAdsResult}; if pods are returned, set {@link IAdsProps.command} to `"showAds"`
+ * 4. Handle {@link IAdsProps.onShowAdsResult} and resume content playback
+ * 5. When the component is unmounted, set {@link IAdsProps.command} to `"stop"` to stop the RAF task.
+ */
+export interface IAdsProps {
+    /** When `true`, enables verbose RAF debug logging on the device. */
+    debugOutput?: boolean;
+
+    /**
+     * Command dispatched to the RAF task. Write it **last**: the task reads the other
+     * fields at the moment the command arrives, so a data field set after it is not
+     * seen by the command it was meant for.
+     *
+     * Common to every mode:
+     * - `"none"` — matches no branch in the task, so it does nothing. That is what
+     *   makes it usable as the reset value described below.
+     * - `"getAds"` — fetch pods for the current {@link IAdsProps.adUrl}; answered by
+     *   {@link IAdsProps.onGetAdsResult}. An empty or unset `adUrl` is answered with
+     *   an empty array without a network request.
+     * - `"stop"` — leave the task's command loop, driving {@link IAdsProps.onAdsState}
+     *   to `"stopped"`. No command after it is observed.
+     *
+     * CSAI — client-side insertion:
+     * - `"showAds"` — render the pods from the most recent `getAds` into
+     *   {@link IAdsProps.adView}; answered by {@link IAdsProps.onShowAdsResult}. A
+     *   missing `adView` is reported as `"error"`.
+     *
+     * SSAI — server-stitched insertion:
+     * - `"stitchedAdsInit"` — hand the raw `getAds` result to RAF's stitched playback
+     *   and switch the task to SSAI mode; answered by
+     *   {@link IAdsProps.onStitchedAdsInitResult}. Empty pods are reported as
+     *   `"error"` and leave the mode alone. Stitched ads met later surface through
+     *   {@link IAdsProps.onStitchedAdResult}, which content position drives rather
+     *   than this command.
+     *
+     * CSAS — client-side stitching:
+     * - `"constructStitchedStream"` — build a stream from
+     *   {@link IAdsProps.contentMetadata}; answered by
+     *   {@link IAdsProps.onConstructStitchedStreamResult}. On failure the task reverts
+     *   to CSAI mode, reported only as `"error"`.
+     * - `"renderStitchedStream"` — play that stream into {@link IAdsProps.adView};
+     *   answered by {@link IAdsProps.onRenderStitchedStreamResult}.
+     *
+     * **Compared by value.** Writing a value equal to the current one writes nothing,
+     * so the same command twice in a row silently does nothing the second time. Reset
+     * through `"none"` between two identical commands.
+     */
+    command?: AdsCommand;
+
+    /**
+     * Fired when the RAF task state changes (notably `"ready"` after init).
+     *
+     * A failure to initialise arrives as `"ready"` never being reported, not as a
+     * state of its own — there is nothing to branch on, so treat a missing
+     * `"ready"` as the error.
+     */
+    onAdsState?: EventHandlerAdsState;
+
+    /**
+     * VMAP/VAST ad server URL passed to `Roku_Ads().setAdUrl()` before each `getAds`.
+     *
+     * **Note:** Mid-roll cue points observed by the task reuse the last `adUrl` set via
+     * the `"getAds"` command. Per-break URL updates are not currently supported.
+     */
+    adUrl?: string;
+
+    /**
+     * Fired when a `getAds` command completes. Receives an array of ad pods.
+     *
+     * Unlike the string result handlers, this fires once per command with no `"none"`
+     * sentinel: the field is an array, so the observer fires on the write itself.
+     */
+    onGetAdsResult?: EventHandlerAdPods;
+
+    /**
+     * SceneGraph node RAF renders ads into during `showAds`.
+     * For non-stitched CSAI, any renderable node whose lifetime spans the ad break is valid.
+     */
+    adView?: DomNode;
+
+    /**
+     * Content playback node (typically a `Video`) whose `position` field the RAF task observes
+     * to trigger mid-roll `getAds` calls automatically.
+     *
+     * **Note:** The task binds to the first non-invalid `contentView` and does not re-observe
+     * on subsequent changes. If the Video node is replaced (e.g., content navigation), the
+     * `<Ads>` component must be unmounted and remounted to rebind mid-roll observation.
+     */
+    contentView?: DomNode;
+
+    /** Content metadata used in CSAS mode to construct the stitched stream. `Roku_Ads().constructStitchedStream()`. */
+    contentMetadata?: IContentNodeProps | Record<string, unknown>;
+
+    /**
+     * Optional `{ start, total }` ad counter RAF draws during a `showAds` break, so
+     * `{ start: 1, total: 4 }` reads "Ad 1 of 4". Use it when the app renders part of
+     * a break itself and RAF's own count would be wrong. Omitted, RAF counts the pod
+     * it was given.
+     */
+    adCounter?: AdCounter;
+
+    /**
+     * Fired when a `showAds` command completes. Receives `"completed"` when the break
+     * played through, `"user_exited"` when the viewer left it early (typically Back),
+     * or `"error"` when {@link IAdsProps.adView} is missing.
+     *
+     * `"user_exited"` is not a failure, and the two usually call for different
+     * handling: content resumes after `"completed"`, while leaving a break early
+     * generally means leaving the content too.
+     *
+     * **Fires with `"none"` first.** The task clears the field to that sentinel before
+     * running the break, so the real value arrives in a later call. Treat `"none"` as
+     * "no result yet" rather than as a failure.
+     */
+    onShowAdsResult?: EventHandler<ShowAdsResult>;
+
+    /**
+     * Fired when a `stitchedAdsInit` command completes. Receives `"completed"` once
+     * non-empty pods have been handed to RAF and the task has switched to SSAI mode,
+     * or `"error"` when there were no pods to hand over.
+     *
+     * RAF reports nothing back from this call, so `"completed"` says the pods were
+     * passed on, not that RAF accepted them.
+     *
+     * **Fires with `"none"` first**, as {@link IAdsProps.onShowAdsResult} does.
+     */
+    onStitchedAdsInitResult?: EventHandler<StitchedAdsInitResult>;
+
+    /**
+     * Fired for each stitched ad the task handles during SSAI playback, with the context
+     * RAF reports for it.
+     *
+     * Driven by `contentView` position, **not** by the `stitchedAdsInit` command —
+     * {@link IAdsProps.onStitchedAdsInitResult} is that command's acknowledgement.
+     */
+    onStitchedAdResult?: EventHandler<Record<string, unknown>>;
+
+    /**
+     * Fired when a `constructStitchedStream` command completes. Receives `"completed"`
+     * once the stream is built, or `"error"` when {@link IAdsProps.contentMetadata} is
+     * missing or RAF could not build it — in which case the task reverts to CSAI mode.
+     *
+     * **Fires with `"none"` first**, as {@link IAdsProps.onShowAdsResult} does.
+     */
+    onConstructStitchedStreamResult?: EventHandler<ConstructStitchedStreamResult>;
+
+    /**
+     * Fired when a `renderStitchedStream` command completes. Receives `"completed"` when
+     * the stream played through, `"user_exited"` when playback ended before that, or
+     * `"error"` when no stream has been constructed or {@link IAdsProps.adView} is missing.
+     *
+     * **Fires with `"none"` first**, as {@link IAdsProps.onShowAdsResult} does.
+     */
+    onRenderStitchedStreamResult?: EventHandler<RenderStitchedStreamResult>;
+
+    /** Enable audience measurement. Set before issuing `command = "getAds"` so RAF has measurement context when ad pods are fetched. */
+    enableAdMeasurements?: boolean;
+
+    /** Content genre for audience measurement. Set before `command = "getAds"`. */
+    contentGenre?: string;
+
+    /** Content ID for audience measurement. Set before `command = "getAds"`. */
+    contentId?: string;
+}
+
+/**
+ * Headless SceneGraph Task that bridges TypeScript to Roku Advertising Framework (RAF).
+ *
+ * Renders no visible UI — mount it in the component tree and drive ad operations via
+ * {@link IAdsProps.command} and the callback props on {@link IAdsProps}.
+ *
+ * @example
+ * ```tsx
+ * <Ads
+ *     debugOutput={true}
+ *     adUrl={vmapUrl}
+ *     adView={adViewNode}
+ *     contentView={videoNode}
+ *     command={adCommand()}
+ *     onAdsState={(state) => state === "ready" && setAdCommand("getAds")}
+ *     onGetAdsResult={(pods) => pods.length && setAdCommand("showAds")}
+ *     onShowAdsResult={(result) => result === "completed" && setContentControl("play")}
+ * />
+ * ```
+ */
+export const Ads: Component<IAdsProps> = props => {
+    // `contentMetadata` is widened in the public API to accept a typed
+    // `IContentNodeProps`, but the native <ads> field is a SceneGraph assocarray
+    // (`Record<string, unknown>`) and TS interfaces have no index signature. The
+    // shapes are structurally compatible at runtime, so coerce just this field at
+    // the boundary; the spread stays reactive since the proxy is unchanged.
+    return (
+        <ads {...(props as Omit<IAdsProps, "contentMetadata"> & { contentMetadata?: Record<string, unknown> })}></ads>
+    );
+};

package/src/index.ts

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+export { Ads } from "./ads";
+export type {
+    AdsState,
+    EventHandlerAdsState,
+    AdsCommand,
+    EventHandlerAdPods,
+    EventHandler,
+    IAdsProps,
+    Ad,
+    AdCounter,
+    AdPod,
+    AdStream,
+    AdTrackingEvent,
+    CompanionAd,
+    ShowAdsResult,
+    StitchedAdsInitResult,
+    ConstructStitchedStreamResult,
+    RenderStitchedStreamResult
+} from "./ads";

package/src/xml-components/ads/ads.brs

@@ -0,0 +1,198 @@
+' Copyright (c) 2026 Roku, Inc.
+' SPDX-License-Identifier: MIT
+
+' RAF bridge Task for the @roku-sdk/ads <Ads> component.
+'
+' TypeScript drives ad fetch/render by writing SG interface fields on this Task node.
+' Results flow back through getAdsResult / showAdsResult / adsState, which the TS
+' wrapper exposes as reactive callbacks.
+'
+' CSAI flow (pre-roll):
+'   adsState = "ready"  →  command = "getAds"  →  command = "showAds"  →  resume content
+'
+' Mid-roll: once contentView is set, this task observes Video.position and calls
+' getAds(msg) automatically at cue points. The app must still issue showAds.
+
+Library "Roku_Ads.brs"
+
+Sub init()
+    m.top.getAdsResult = []
+    m.top.functionName = "adsEventLoop"
+    m.top.control = "run"
+End Sub
+
+sub adsEventLoop()
+    raf = Roku_Ads()
+    ' Pods from the most recent getAds; passed to showAds until the next getAds.
+    ads = []
+    contentView = invalid
+    contentMetadata = invalid
+    mode = "csai" ' default to CSAI mode
+    csasStream = invalid
+    ' Set while pods written to getAdsResult are unacted on; holds off the cue-point fetch.
+    podsPending = false
+
+    msgPort = CreateObject("roMessagePort")
+    m.top.observeField("command", msgPort)
+    m.top.observeField("debugOutput", msgPort)
+    m.top.observeField("contentView", msgPort)
+    m.top.observeField("contentMetadata", msgPort)
+    m.top.observeField("enableAdMeasurements", msgPort)
+    m.top.observeField("contentGenre", msgPort)
+    m.top.observeField("contentId", msgPort)
+
+    ' Signals TypeScript (onAdsState) that RAF is initialised and commands can be sent.
+    m.top.adsState = "ready"
+
+    while true
+        msg = wait(0, msgPort)
+        if msg = invalid then continue while
+        field = msg.getField()
+        if field = "command"
+            cmd = msg.getData()
+            ' Any command clears the hold: the app has acted on the pods it was handed.
+            podsPending = false
+            if cmd = "getAds"
+                if m.top.adUrl = "" or m.top.adUrl = invalid
+                    ' Drop the held pods too, or a later showAds renders what the app was told it has none of.
+                    ads = []
+                    updateGetAdsResult([])
+                else
+                    raf.setAdUrl(m.top.adUrl)
+                    ads = raf.getAds()
+                    podsPending = updateGetAdsResult(ads) > 0
+                end if
+            else if cmd = "showAds"
+                ' Clear before both outcomes, not just the render: writing the same
+                ' value the field already holds notifies nobody.
+                m.top.showAdsResult = "none"
+                if m.top.adView = invalid
+                    m.top.showAdsResult = "error"
+                else
+                    ' CSAI: ads render into adView (3rd arg), ad counter into ctx (2nd).
+                    ' RAF returns false when the viewer left the break early, not on error.
+                    if raf.showAds(ads, adCounterCtx(m.top.adCounter), m.top.adView)
+                        m.top.showAdsResult = "completed"
+                    else
+                        m.top.showAdsResult = "user_exited"
+                    end if
+                end if
+            else if cmd = "constructStitchedStream"
+                m.top.constructStitchedStreamResult = "none"
+                if contentMetadata = invalid
+                    m.top.constructStitchedStreamResult = "error"
+                else
+                    csasStream = raf.constructStitchedStream(contentMetadata, ads)
+                    ' Re-observe contentMetadata so a subsequent CSAS session can update it.
+                    m.top.observeField("contentMetadata", msgPort)
+                    if csasStream <> invalid
+                        mode = "csas"
+                        m.top.constructStitchedStreamResult = "completed"
+                    else
+                        mode = "csai" ' fall back to CSAI mode if constructStitchedStream fails
+                        m.top.constructStitchedStreamResult = "error"
+                    end if
+                end if
+            else if cmd = "renderStitchedStream"
+                m.top.renderStitchedStreamResult = "none"
+                if csasStream = invalid
+                    m.top.renderStitchedStreamResult = "error"
+                else if m.top.adView = invalid
+                    m.top.renderStitchedStreamResult = "error"
+                else if raf.renderStitchedStream(csasStream, m.top.adView)
+                    m.top.renderStitchedStreamResult = "completed"
+                else
+                    m.top.renderStitchedStreamResult = "user_exited"
+                end if
+            else if cmd = "stitchedAdsInit"
+                m.top.stitchedAdsInitResult = "none"
+                ' Pass raw RAF result (not normalized array) — stitchedAdsInit
+                ' needs the full assocarray returned by getAds(), not just the
+                ' extracted pod array that updateGetAdsResult writes to the field.
+                adPods = ads
+                if type(ads) = "roAssociativeArray" then adPods = ads.ads
+                if adPods = invalid or adPods.count() = 0
+                    ' Nothing to initialise: staying in CSAI would leave position
+                    ' events offering mid-roll pods for a stream never set up for them.
+                    m.top.stitchedAdsInitResult = "error"
+                else
+                    raf.stitchedAdsInit(ads) ' pass raw result, not extracted pods
+                    mode = "ssai" ' switch to SSAI mode
+                    ' RAF returns nothing here: "completed" means pods were handed over, not accepted.
+                    m.top.stitchedAdsInitResult = "completed"
+                end if
+            else if cmd = "stop"
+                exit while
+            end if
+        else if field = "contentView"
+            contentView = m.top.contentView
+            if contentView <> invalid
+                ' One-shot hook: mid-roll getAds is driven by position changes on contentView.
+                contentView.observeField("position", msgPort)
+                m.top.unobserveField("contentView")
+            end if
+        else if field = "contentMetadata"
+            metadata = m.top.contentMetadata
+            if metadata <> invalid
+                contentMetadata = CreateObject("roSGNode", "ContentNode")
+                contentMetadata.Update(metadata, true)
+                m.top.unobserveField("contentMetadata")
+            end if
+        else if field = "position"
+            if mode = "csai" and podsPending
+                ' Skip one fetch so the outstanding pods survive, and clear the hold
+                ' unconditionally so an app that issues no command cannot stall mid-roll.
+                podsPending = false
+            else if mode = "csai"
+                ' Only notify TS when RAF returns actual pods at a cue point.
+                ' NOTE: mid-roll reuses the last adUrl set via the "getAds" command.
+                ' Per-break URL updates are not currently supported.
+                midRollAds = raf.getAds(msg)
+                if midRollAds <> invalid and midRollAds.count() > 0
+                    ads = midRollAds
+                    podsPending = updateGetAdsResult(ads) > 0
+                end if
+            else if mode = "ssai"
+                currentAdContext = raf.stitchedAdHandledEvent(msg, contentView)
+                if currentAdContext <> invalid
+                    m.top.stitchedAdResult = currentAdContext
+                end if
+            end if
+        else if field = "debugOutput"
+            raf.setDebugOutput(msg.getData())
+        else if field = "enableAdMeasurements"
+            raf.enableAdMeasurements(msg.getData() = true)
+        else if field = "contentGenre"
+            genre = msg.getData()
+            if genre <> "" then raf.setContentGenre(genre)
+        else if field = "contentId"
+            cid = msg.getData()
+            if cid <> "" then raf.setContentId(cid)
+        end if
+    end while
+    m.top.adsState = "stopped"
+End Sub
+
+' Writes pods to getAdsResult and returns how many were written. RAF may return a
+' bare array or an assocarray with an "ads" key.
+' No reset-before-write here: RAF returns a new array reference each call, so the
+' SG observer fires without needing a sentinel clear (unlike showAdsResult which is a string).
+function updateGetAdsResult(ads) as Integer
+    if ads = invalid then ads = []
+    if type(ads) = "roArray"
+        m.top.getAdsResult = ads
+    else
+        result = ads.ads
+        if result = invalid then result = []
+        m.top.getAdsResult = result
+    end if
+    return m.top.getAdsResult.count()
+end function
+
+' RAF's showAds ctx argument: { start, total } renders an "Ad 1 of 4" counter.
+' An unset SG assocarray field arrives as an empty one, which RAF must not be given.
+function adCounterCtx(counter) as Object
+    if counter = invalid then return invalid
+    if counter.count() = 0 then return invalid
+    return counter
+end function

package/src/xml-components/ads/ads.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (c) 2026 Roku, Inc.
+SPDX-License-Identifier: MIT
+-->
+<component name="ads" extends="Task">
+    <script type="text/brightscript" uri="ads.brs" />
+    <interface>
+        <field id="debugOutput" type="boolean" value="false" />
+        <field id="command" type="string" value="none" />
+        <field id="adsState" type="string" value="none" />
+
+        <field id="adUrl" type="string" value="" />
+        <field id="adView" type="node" />
+        <field id="contentView" type="node" />
+        <field id="contentMetadata" type="assocarray" />
+        <field id="getAdsResult" type="array" />
+        <field id="showAdsResult" type="string" value="none" />
+        <!-- Optional { start, total } ad counter passed to showAds as RAF's ctx. -->
+        <field id="adCounter" type="assocarray" />
+
+        <!-- SSAI specific fields -->
+        <field id="stitchedAdResult" type="assocarray" />
+        <field id="stitchedAdsInitResult" type="string" value="none" />
+
+        <!-- CSAS specific fields -->
+        <field id="constructStitchedStreamResult" type="string" value="none" />
+        <field id="renderStitchedStreamResult" type="string" value="none" />
+
+        <!-- Audience measurement specific fields -->
+        <field id="enableAdMeasurements" type="boolean" value="false" />
+        <field id="contentGenre" type="string" value="" />
+        <field id="contentId" type="string" value="" />
+    </interface>
+</component>