@amazon-devices/expo-image 2.0.9000000000 → 3.0.0

package/kepler/ExpoImageComponent/ExpoImageView.h

@@ -0,0 +1,186 @@
+#pragma once
+
+#include <apmf/array.h>
+#include <apmf/iface/com/amazon/apmf/ISubscription.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/graphics/Size.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/react/IContext.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/react/IJsArray.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/react/IJsObject.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/react/ILayout.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IAccessibilityService.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IImage.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IImageLoader.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IImageView3.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IView.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IViewModule.h>
+#include <apmf/ptr.h>
+#include <apmf/string.h>
+
+#include "../ImageSourceInfo.h"
+#include "../contentposition/ImageContentPosition.h"
+#include "../enums/ImageContentFit.h"
+#include "../enums/ImagePriority.h"
+#include "AccessibilityDelegate.h"
+#include "ExpoImageStore.h"
+
+#include <deque>
+#include <limits>
+#include <memory>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace expoimage {
+
+using apmf::Ptr;
+using apmf::String;
+using apmf::View;
+template <typename T>
+using Array = apmf::Array<T>;
+using apmf::iface::com::amazon::kepler::uitoolkit::react::IContext;
+using apmf::iface::com::amazon::kepler::uitoolkit::react::IJsArray;
+using apmf::iface::com::amazon::kepler::uitoolkit::react::IJsObject;
+using apmf::iface::com::amazon::kepler::uitoolkit::react::ILayout;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IAccessibilityService;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IImageLoader;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IImageView3;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IView;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IViewModule;
+
+namespace gfx = apmf::iface::com::amazon::kepler::uitoolkit::graphics;
+namespace vi = apmf::iface::com::amazon::kepler::uitoolkit::view;
+
+// ExpoImageStore (the process-wide shared loader + decoded-image cache) is defined
+// in ExpoImageStore.h.
+
+/**
+ * Per-view state and logic for a single <Image> element.
+ * Created by ExpoImageComponentViewManager::makeView(), one instance per native view.
+ */
+class ExpoImageView {
+public:
+    ExpoImageView(
+            Ptr<IViewModule> viewModule,
+            Ptr<IView> container,
+            Ptr<IView> clipView,
+            Ptr<IImageView3> imageView,
+            std::shared_ptr<ExpoImageStore> store);
+
+    void updateProps(View<IJsObject> newProps, View<IContext> context);
+    void updateLayout(View<ILayout> newLayout);
+
+    Ptr<apmf::iface::com::amazon::apmf::ISubscription> lifecycleSub_;
+
+private:
+    void setContentFit(const std::string& value);
+    void setPlaceholderContentFit(const std::string& value);
+    void setAllowDownscaling(bool allow);
+    void setContentPosition(View<IJsObject> posObj);
+    void setTintColor(int color);
+    void setOverlayColor(int color);
+    void setBlurRadius(double radius);
+    void setSource(View<IJsArray> sourceArr);
+    void setPlaceholder(View<IJsArray> phArr);
+    void setPriority(const std::string& value);
+    void setTransition(View<IJsObject> transObj);
+    void setRecyclingKey(const std::string& value);
+    void setAccessibilityLabel(const std::string& value);
+    void setAlt(const std::string& value);
+    void setAccessible(bool value);
+
+    void loadSource(bool animate);
+    void loadPlaceholder();
+    bool loadHashImage(const std::string& uri, float width, float height, bool animate);
+    void animateTransition();
+    void applyContentPositionOffset();
+
+    bool shouldDeferRemoteLoad(const ImageSourceInfo& best) const;
+    std::optional<apmf::iface::com::amazon::kepler::uitoolkit::graphics::Size>
+            computePreferredSize(const ImageSourceInfo& best) const;
+    void loadHashSource(const ImageSourceInfo& best, bool animate);
+    void loadRemoteSource(const ImageSourceInfo& best, bool animate);
+    void loadHashPlaceholder(const ImageSourceInfo& best);
+    void loadRemotePlaceholder(const ImageSourceInfo& best);
+
+    void applyContentPositionOffset(ImageContentFit fit, bool allowDownscaling);
+    static void layoutImageView(
+            Ptr<IImageView3> imageView,
+            ImageContentFit fit,
+            bool allowDownscaling,
+            gfx::Size imageSize,
+            gfx::Size viewSize,
+            const ImageContentPosition& contentPosition);
+
+    struct DisplayState {
+        bool sourceLoaded{false};
+        // true once this view has displayed ANY real image
+        // (source or placeholder). Persists across source changes / recycling
+        // (it is NOT reset by setSource). Used to suppress placeholder re-show
+        // and the fade-from-blank transition on a view that already shows an
+        // image, so a recycled cell swaps atomically instead of flickering.
+        bool hasDisplayedImage{false};
+        gfx::Size loadedImageSize{0, 0};
+        ImageContentFit activeFit{ImageContentFit::Cover};
+        bool activeAllowDownscaling{true};
+        gfx::Size viewSize{0, 0};
+        ImageContentPosition contentPosition;
+        // URI of the source currently displayed, and the URI of an
+        // in-flight load. Kept in DisplayState (a shared_ptr captured by the load
+        // callback) rather than on ExpoImageView so that the async failure path can
+        // clear `pendingUri` and allow a retry even after the originating cell is
+        // gone. loadedUri short-circuits redundant reloads; pendingUri de-dups
+        // concurrent loads of the same URI.
+        std::string loadedUri;
+        std::string pendingUri;
+    };
+
+    struct SourceLoadCaptures {
+        Ptr<vi::IView> view;
+        Ptr<vi::IImageView3> imageView;
+        Ptr<vi::IViewModule> viewModule;
+        std::shared_ptr<DisplayState> state;
+        ImageContentFit contentFit;
+        bool allowDownscaling;
+        bool shouldAnimate;
+        float duration;
+        std::string timing;
+        std::shared_ptr<ExpoImageStore> store;  // cache decoded image on success
+        std::string uri;                         // raw source URI (load-state tracking)
+        std::string cacheKey;                    // cache key = uri + decode size
+    };
+    static void applySourceImage(const SourceLoadCaptures& captures, Ptr<vi::IImage> img);
+
+    Ptr<IViewModule> viewModule_;
+    Ptr<IView> view_;         // container passed back to Fabric (also accessibility root)
+    Ptr<IView> clipView_;     // plain IView wrapper with setContentClipping(true); clips descendants to cell bounds
+    Ptr<IImageView3> imageView_;  // IImageView child — setImage/setFit and setOffset/setSize (IImageView3 extends IView)
+    Ptr<IImageLoader> imageLoader_;
+    std::shared_ptr<ExpoImageStore> store_;  // shared loader + decoded-image cache
+    Ptr<IContext> context_;
+
+    std::vector<ImageSourceInfo> sources_;
+    std::vector<ImageSourceInfo> placeholders_;
+    ImageContentFit contentFit_{ImageContentFit::Cover};
+    ImageContentFit placeholderContentFit_{ImageContentFit::ScaleDown};
+    ImageContentPosition contentPosition_;
+    ImagePriority priority_{ImagePriority::Normal};
+    int tintColor_{std::numeric_limits<int>::max()};
+    int overlayColor_{std::numeric_limits<int>::max()};
+    double blurRadius_{0.0};
+    bool allowDownscaling_{true};
+    std::string recyclingKey_;
+    bool shouldClearOnSourceChange_{false};
+    float transitionDuration_{0.0f};
+    std::string transitionTiming_;
+    bool shouldAnimate_{false};
+    std::shared_ptr<DisplayState> displayState_ = std::make_shared<DisplayState>();
+    gfx::Size viewSize_{0, 0};
+
+    Ptr<ExpoImageAccessibilityDelegate> accessibilityDelegate_;
+    Ptr<IAccessibilityService> accessibilityService_;
+    std::string accessibilityLabel_;
+    std::string alt_;
+};
+
+}  // namespace expoimage

package/kepler/ExpoImageComponent/HashImageDecoder.cpp

@@ -0,0 +1,91 @@
+#include "HashImageDecoder.h"
+
+#include <apmf/iface/com/amazon/kepler/uitoolkit/graphics/Color.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/graphics/ICanvas.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/graphics/IGraphicsModule2.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/graphics/IPaint.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/graphics/ISurface.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/graphics/Rect.h>
+#include <apmf/process.h>
+
+#include "../blurhash/decode.h"
+#include "../thumbhash/decode.h"
+#include "../utils/SourceSelection.h"
+
+#include <algorithm>
+#include <cmath>
+
+namespace expoimage {
+
+namespace gfx = apmf::iface::com::amazon::kepler::uitoolkit::graphics;
+
+namespace {
+
+constexpr int kBlurhashMaxInternalDim = 32;
+
+/** Creates a graphics IImage from raw RGBA pixel data using ISurface. */
+apmf::Ptr<gfx::IImage> createImageFromPixels(const uint8_t* pixels, int width, int height) {
+    auto graphicsModule = apmf::GetProcessObject()
+            ->getComponent("/com.amazon.kepler.uitoolkit.graphics")
+            .TryQueryInterface<gfx::IGraphicsModule2>();
+    if (!graphicsModule) return nullptr;
+
+    auto surface = graphicsModule->makeSurface(gfx::SizeI{width, height});
+    if (!surface) return nullptr;
+
+    auto canvas = surface->getCanvas();
+    auto paint = graphicsModule->makePaint();
+
+    for (int y = 0; y < height; ++y) {
+        for (int x = 0; x < width; ++x) {
+            int idx = (y * width + x) * 4;
+            float r = pixels[idx] / 255.0f;
+            float g = pixels[idx + 1] / 255.0f;
+            float b = pixels[idx + 2] / 255.0f;
+            float a = pixels[idx + 3] / 255.0f;
+            paint->setColor(gfx::Color{r, g, b, a});
+            canvas->drawRect(
+                    gfx::Rect{static_cast<float>(x), static_cast<float>(y),
+                              static_cast<float>(x + 1), static_cast<float>(y + 1)},
+                    paint);
+        }
+    }
+    return surface->createSnapshot();
+}
+
+}  // anonymous namespace
+
+apmf::Ptr<gfx::IImage> decodeHashToImage(const std::string& uri, float width, float height) {
+    if (!std::isfinite(width) || !std::isfinite(height)) {
+        return nullptr;
+    }
+
+    auto delimPos = uri.find('/');
+    if (delimPos == std::string::npos) return nullptr;
+    auto hash = uriDecode(uri.substr(delimPos + 1));
+
+    int w = std::max(1, static_cast<int>(width));
+    int h = std::max(1, static_cast<int>(height));
+    const int channels = 4;
+    std::unique_ptr<uint8_t[]> pixels;
+
+    if (startsWith(uri, "blurhash")) {
+        int longest = std::max(w, h);
+        if (longest > kBlurhashMaxInternalDim) {
+            float scale = static_cast<float>(kBlurhashMaxInternalDim) / static_cast<float>(longest);
+            w = std::max(1, static_cast<int>(std::round(static_cast<float>(w) * scale)));
+            h = std::max(1, static_cast<int>(std::round(static_cast<float>(h) * scale)));
+        }
+        pixels = decodeBlurhash(hash.c_str(), w, h, 1, channels);
+    } else if (startsWith(uri, "thumbhash")) {
+        auto result = decodeThumbhash(hash);
+        w = result.width;
+        h = result.height;
+        pixels = std::move(result.pixelArray);
+    }
+
+    if (!pixels) return nullptr;
+    return createImageFromPixels(pixels.get(), w, h);
+}
+
+}  // namespace expoimage

package/kepler/ExpoImageComponent/HashImageDecoder.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#include <apmf/iface/com/amazon/kepler/uitoolkit/graphics/IImage.h>
+#include <apmf/ptr.h>
+
+#include <string>
+
+namespace expoimage {
+
+/**
+ * Decodes a blurhash or thumbhash URI into a graphics IImage.
+ * The URI format is "blurhash/<hash>" or "thumbhash:/<hash>".
+ * Returns nullptr if decoding fails.
+ */
+apmf::Ptr<apmf::iface::com::amazon::kepler::uitoolkit::graphics::IImage>
+decodeHashToImage(const std::string& uri, float width, float height);
+
+}  // namespace expoimage

package/kepler/ExpoImageComponent/ImageLoadListeners.cpp

@@ -0,0 +1,73 @@
+#include "ImageLoadListeners.h"
+
+#include <apmf/fn.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/react/IJsObjectBuilder.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/react/IPayloadDelegate.h>
+#include <apmf/log.h>
+
+namespace expoimage {
+
+using apmf::iface::com::amazon::kepler::uitoolkit::react::IJsObjectBuilder;
+
+APMF_DEFINE_LOGGER(ImageLoadListenerLogger,
+                   "com.amazon.kepler.uitoolkit.react.expoimage.imageload");
+using namespace apmf::log_levels;
+
+// --- SourceImageLoadListener ---
+
+SourceImageLoadListener::SourceImageLoadListener(
+        View<IEventEmitter> emitter, View<IView> view, std::function<void(Ptr<IImage>)> onLoad)
+    : emitter_(emitter), view_(view), onLoad_(std::move(onLoad)) {}
+
+void SourceImageLoadListener::onStart(View<IImageLoadRequest>) { emitter_->emit(view_, "loadStart"); }
+
+void SourceImageLoadListener::onProgress(View<IImageLoadRequest>, float progress) {
+    constexpr int32_t total = 10000;
+    emitter_->emitWithPayload(
+            view_, "progress",
+            apmf::Fn([progress, total](apmf::method::getPayload, View<IJsObjectBuilder> builder) {
+                builder->setInt("loaded", static_cast<int>(progress * total))->setInt("total", total);
+                return builder->build();
+            }));
+}
+
+void SourceImageLoadListener::onSuccess(View<IImageLoadRequest>, View<IImage> image) {
+    emitter_->emit(view_, "load");
+    if (onLoad_) onLoad_(image);
+    emitter_->emit(view_, "loadEnd");
+}
+
+void SourceImageLoadListener::onFailure(View<IImageLoadRequest>, ImageLoadError const&) {
+    APMF_LOG(ImageLoadListenerLogger, WARNING)
+            << "SourceImageLoadListener::onFailure: emitting 'error' + 'loadEnd'";
+    if (onLoad_) onLoad_(nullptr);
+    emitter_->emit(view_, "error");
+    emitter_->emit(view_, "loadEnd");
+}
+
+void SourceImageLoadListener::onCanceled(View<IImageLoadRequest>) {
+    APMF_LOG(ImageLoadListenerLogger, DEBUG)
+            << "SourceImageLoadListener::onCanceled: emitting 'loadEnd'";
+    emitter_->emit(view_, "loadEnd");
+}
+void SourceImageLoadListener::onPrefetchComplete(View<IImageLoadRequest>) {}
+
+// --- PlaceholderImageLoadListener ---
+
+PlaceholderImageLoadListener::PlaceholderImageLoadListener(std::function<void(Ptr<IImage>)> onLoad)
+    : onLoad_(std::move(onLoad)) {}
+
+void PlaceholderImageLoadListener::onStart(View<IImageLoadRequest>) {}
+void PlaceholderImageLoadListener::onProgress(View<IImageLoadRequest>, float) {}
+void PlaceholderImageLoadListener::onSuccess(View<IImageLoadRequest>, View<IImage> image) {
+    if (!image) return;
+    if (onLoad_) onLoad_(image);
+}
+void PlaceholderImageLoadListener::onFailure(View<IImageLoadRequest>, ImageLoadError const&) {
+    APMF_LOG(ImageLoadListenerLogger, WARNING)
+            << "PlaceholderImageLoadListener::onFailure: placeholder load failed (no event)";
+}
+void PlaceholderImageLoadListener::onCanceled(View<IImageLoadRequest>) {}
+void PlaceholderImageLoadListener::onPrefetchComplete(View<IImageLoadRequest>) {}
+
+}  // namespace expoimage

package/kepler/ExpoImageComponent/ImageLoadListeners.h

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <apmf/apmf_base.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/react/IEventEmitter.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IImage.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IImageLoadListener.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IImageLoadRequest.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IView.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/ImageLoadError.h>
+#include <apmf/ptr.h>
+
+#include <functional>
+
+namespace expoimage {
+
+using apmf::ApmfBase;
+using apmf::Ptr;
+using apmf::View;
+using apmf::iface::com::amazon::kepler::uitoolkit::react::IEventEmitter;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IImage;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IImageLoadListener;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IImageLoadRequest;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::ImageLoadError;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IView;
+
+struct SourceImageLoadListener : ApmfBase<SourceImageLoadListener, IImageLoadListener> {
+    SourceImageLoadListener(View<IEventEmitter> emitter, View<IView> view, std::function<void(Ptr<IImage>)> onLoad);
+    void onStart(View<IImageLoadRequest> request);
+    void onProgress(View<IImageLoadRequest> request, float progress);
+    void onSuccess(View<IImageLoadRequest> request, View<IImage> image);
+    void onFailure(View<IImageLoadRequest> request, ImageLoadError const& error);
+    void onCanceled(View<IImageLoadRequest> request);
+    void onPrefetchComplete(View<IImageLoadRequest> request);
+private:
+    Ptr<IEventEmitter> emitter_;
+    Ptr<IView> view_;
+    std::function<void(Ptr<IImage>)> onLoad_;
+};
+
+struct PlaceholderImageLoadListener : ApmfBase<PlaceholderImageLoadListener, IImageLoadListener> {
+    explicit PlaceholderImageLoadListener(std::function<void(Ptr<IImage>)> onLoad);
+    void onStart(View<IImageLoadRequest> request);
+    void onProgress(View<IImageLoadRequest> request, float progress);
+    void onSuccess(View<IImageLoadRequest> request, View<IImage> image);
+    void onFailure(View<IImageLoadRequest> request, ImageLoadError const& error);
+    void onCanceled(View<IImageLoadRequest> request);
+    void onPrefetchComplete(View<IImageLoadRequest> request);
+private:
+    std::function<void(Ptr<IImage>)> onLoad_;
+};
+
+}  // namespace expoimage

package/kepler/ExpoImageComponent/TransitionAnimator.cpp

@@ -0,0 +1,113 @@
+#include "TransitionAnimator.h"
+
+#include <apmf/apmf_base.h>
+#include <apmf/iface/com/amazon/apmf/MonotonicDuration.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IAnimationValue.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IAnimationValueBuilder.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IAnimator.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IAnimatorBuilder.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IAnimatorListener.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IInterpolator.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IInterpolatorModule.h>
+#include <apmf/log.h>
+
+namespace expoimage {
+
+using apmf::ApmfBase;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IAnimationValue;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IAnimationValueBuilder;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IAnimator;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IAnimatorBuilder;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IAnimatorListener;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IInterpolator;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IInterpolatorModule;
+
+APMF_DEFINE_LOGGER(TransitionAnimatorLogger,
+                   "com.amazon.kepler.uitoolkit.react.expoimage.transition");
+using namespace apmf::log_levels;
+
+/**
+ * Listener that updates view opacity on each animation frame.
+ * Holds a Ptr<IAnimator> to prevent the animator from being garbage collected
+ * before the animation completes.
+ */
+struct TransitionListener : ApmfBase<TransitionListener, IAnimatorListener> {
+    TransitionListener(Ptr<IView> view) : view_(view) {}
+
+    /** Stores the animator to prevent GC during animation. */
+    void setAnimator(Ptr<IAnimator> animator) { animator_ = animator; }
+
+    void onStart(View<IAnimator>) {}
+    void onEnd(View<IAnimator>) { if (view_) view_->setOpacity(1.0f); }
+    void onCancel(View<IAnimator>) { if (view_) view_->setOpacity(1.0f); }
+    void onPause(View<IAnimator>) {}
+    void onResume(View<IAnimator>) {}
+
+    void onUpdate(View<IAnimator> animator) {
+        if (!view_) return;
+        auto val = animator->getCurrentAnimationValue();
+        if (val) {
+            auto f = val->getFloatValue();
+            if (f) view_->setOpacity(*f);
+        }
+    }
+
+private:
+    Ptr<IView> view_;
+    Ptr<IAnimator> animator_;
+};
+
+namespace {
+
+Ptr<IInterpolator> makeInterpolator(View<IInterpolatorModule> module, const std::string& timing) {
+    if (timing == "ease-in") return module->makeEaseInCubicInterpolator();
+    if (timing == "ease-out") return module->makeEaseOutCubicInterpolator();
+    if (timing == "linear") return module->makeLinearInterpolator();
+    // "ease-in-out" and any unknown value fall through to the default.
+    return module->makeEaseInOutCubicInterpolator();
+}
+
+Ptr<IAnimationValue> makeFloatValue(View<IViewModule> vm, float v) {
+    auto b = vm->makeAnimationValueBuilder();
+    b->floatValue(v);
+    return b->build();
+}
+
+apmf::iface::com::amazon::apmf::MonotonicDuration toMonotonicDuration(float seconds) {
+    auto sec = static_cast<int64_t>(seconds);
+    auto nsFrac = static_cast<int32_t>((seconds - sec) * 1e9);
+    return apmf::iface::com::amazon::apmf::MonotonicDuration{{sec, nsFrac}};
+}
+
+}  // anonymous namespace
+
+void startFadeInTransition(
+        View<IViewModule> viewModule,
+        Ptr<IView> view,
+        float duration,
+        const std::string& timing) {
+    if (!view || duration <= 0.0f) {
+        APMF_LOG(TransitionAnimatorLogger, DEBUG)
+                << "startFadeInTransition: skipped (view=" << (view ? "ok" : "null")
+                << ", duration=" << duration << ")";
+        return;
+    }
+    APMF_LOG(TransitionAnimatorLogger, DEBUG)
+            << "startFadeInTransition: duration=" << duration << " timing=" << timing;
+
+    view->setOpacity(0.0f);
+
+    auto ab = viewModule->makeAnimatorBuilder();
+    ab->duration(toMonotonicDuration(duration));
+    ab->interpolator(makeInterpolator(viewModule->makeInterpolatorModule(), timing));
+    ab->animationBounds(makeFloatValue(viewModule, 0.0f), makeFloatValue(viewModule, 1.0f));
+    auto animator = ab->build();
+
+    // Listener keeps animator alive via setAnimator
+    auto listener = Ptr<TransitionListener>::Make(view);
+    animator->addAnimationListener(listener);
+    listener->setAnimator(animator);
+    animator->start();
+}
+
+}  // namespace expoimage

package/kepler/ExpoImageComponent/TransitionAnimator.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IView.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IViewModule.h>
+#include <apmf/ptr.h>
+
+#include <string>
+
+namespace expoimage {
+
+using apmf::Ptr;
+using apmf::View;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IView;
+using apmf::iface::com::amazon::kepler::uitoolkit::view::IViewModule;
+
+/**
+ * Starts a fade-in transition animation on the given view.
+ * Sets opacity to 0, then animates from 0 to 1 over the given duration.
+ * The animator is kept alive by the listener until the animation completes.
+ *
+ * @param viewModule  Used to create animator, interpolator, and animation values.
+ * @param view        The view whose opacity will be animated.
+ * @param duration    Duration in seconds.
+ * @param timing      Timing function: "ease-in", "ease-out", "ease-in-out", or "linear".
+ */
+void startFadeInTransition(
+        View<IViewModule> viewModule,
+        Ptr<IView> view,
+        float duration,
+        const std::string& timing);
+
+}  // namespace expoimage

package/kepler/ImageSourceInfo.h

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * PROPRIETARY/CONFIDENTIAL
+ * Use is subject to license terms.
+ */
+
+#pragma once
+
+#include <string>
+
+namespace expoimage {
+
+/** Parsed image source from JS props (uri, dimensions, scale). */
+struct ImageSourceInfo {
+    std::string uri;
+    float width{0};
+    float height{0};
+};
+
+}  // namespace expoimage

package/kepler/ViewManagerFactory.cpp

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * PROPRIETARY/CONFIDENTIAL
+ * Use is subject to license terms.
+ */
+
+#include "ViewManagerFactory.h"
+
+#include <apmf/component.h>
+#include <apmf/iface/com/amazon/apmf/InvalidArgumentError.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/view/IViewModule.h>
+
+#include "ExpoImageComponent/ExpoImageComponentViewManager.h"
+
+namespace expoimage {
+
+namespace view = apmf::iface::com::amazon::kepler::uitoolkit::view;
+
+Ptr<IViewManager> ViewManagerFactory::makeViewManager(StringView name) {
+    auto viewModule = apmf::GetProcessObject()
+                           ->getComponent("/com.amazon.kepler.uitoolkit.view")
+                           .TryQueryInterface<view::IViewModule>();
+    if (!viewModule) {
+        throw apmf::InvalidArgumentError("ExpoImage: failed to acquire IViewModule");
+    }
+    if (name == "ExpoImageAppComponent") {
+        return Ptr<ExpoImageComponentViewManager>::Make(viewModule);
+    }
+    throw apmf::InvalidArgumentError(
+            "ExpoImage: cannot make UI component '" + std::string(name) + "'");
+}
+
+}  // namespace expoimage
+
+APMF_COMPONENT("/com.amazon.kepler.uitoolkit.react.expoimageapp", expoimage::ViewManagerFactory);

package/kepler/ViewManagerFactory.h

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * PROPRIETARY/CONFIDENTIAL
+ *
+ * Use is subject to license terms.
+ */
+
+#pragma once
+
+#include <apmf/apmf_base.h>
+#include <apmf/iface/com/amazon/kepler/uitoolkit/react/IViewManagerFactory.h>
+#include <apmf/process.h>
+#include <apmf/ptr.h>
+#include <apmf/string_view.h>
+
+namespace expoimage {
+
+using apmf::ApmfBase;
+using apmf::Ptr;
+using apmf::StringView;
+using apmf::iface::com::amazon::kepler::uitoolkit::react::IViewManager;
+using apmf::iface::com::amazon::kepler::uitoolkit::react::IViewManagerFactory;
+
+struct ViewManagerFactory : ApmfBase<ViewManagerFactory, IViewManagerFactory> {
+    Ptr<IViewManager> makeViewManager(StringView name);
+};
+
+}  // namespace expoimage