@hot-updater/react-native 1.0.0-rc.16 → 1.0.0-rc.17

package/lib/typescript/module/wrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../../src/wrap.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA8B,MAAM,OAAO,CAAC;AAOnD,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EAEpB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,iBAAiB,EACjB,gCAAgC,EAChC,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAEtB,wBAAgB,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAEvD;AAED,wBAAgB,IAAI,CAClB,OAAO,EAAE,mBAAmB,GAC3B,CAAC,CAAC,SAAS,MAAM,EAClB,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KACrC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAuH1B"}
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../../src/wrap.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA8B,MAAM,OAAO,CAAC;AAOnD,OAAO,KAAK,EAEV,mBAAmB,EACnB,mBAAmB,EAEpB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,iBAAiB,EACjB,gCAAgC,EAChC,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAEtB,wBAAgB,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAEvD;AAED,wBAAgB,IAAI,CAClB,OAAO,EAAE,mBAAmB,GAC3B,CAAC,CAAC,SAAS,MAAM,EAClB,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KACrC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAqJ1B"}

package/lib/typescript/module/wrap.types.d.ts

@@ -1,4 +1,5 @@
 import type React from "react";
+import type { HotUpdaterClientPlugin } from "./clientPlugin";
 import type { HotUpdaterError } from "./error";
 import type { HotUpdaterHttpClient } from "./httpClient";
 import type { NotifyAppReadyResult } from "./native";
@@ -20,15 +21,12 @@ export type HotUpdaterFallbackComponentProps = {
 };
 interface CommonHotUpdaterOptions {
     /**
-     * Sends app-ready transitions and same-Bundle Release adoptions to the
-     * configured server. Defaults to `true`; set to `false` to disable client
-     * reporting. Debug builds (`__DEV__`) send nothing unless you pass
-     * `{ debug: true }`, so development sessions stay out of production data.
+     * Client plugins, such as `insights()` from
+     * `@hot-updater/react-native/plugins/insights`. Each plugin's `setup` runs
+     * once, and its hooks observe launches, update checks, downloads, and
+     * update failures. Plugin ids must be unique.
      */
-    insights?: boolean | {
-        /** Also report from debug builds. Defaults to `false`. */
-        debug?: boolean;
-    };
+    plugins?: readonly HotUpdaterClientPlugin[];
     /** Base URL of a server exposing the Hot Updater v1 client HTTP protocol. */
     baseURL: HotUpdaterBaseURL;
     requestHeaders?: Record<string, string>;
@@ -46,8 +44,6 @@ export type AutoUpdateOptions = CommonHotUpdaterOptions & {
 export type HotUpdaterInitOptions = CommonHotUpdaterOptions;
 export type HotUpdaterOptions = AutoUpdateOptions;
 type InternalCommonOptions = {
-    /** Whether this runtime reports, with the debug-build default applied. */
-    insights?: boolean;
     client: HotUpdaterHttpClient;
     requestHeaders?: Record<string, string>;
     requestTimeout?: number;

package/lib/typescript/module/wrap.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrap.types.d.ts","sourceRoot":"","sources":["../../../src/wrap.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wrap.types.d.ts","sourceRoot":"","sources":["../../../src/wrap.types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hot-updater/react-native",
-  "version": "1.0.0-rc.16",
+  "version": "1.0.0-rc.17",
   "description": "React Native OTA solution for self-hosted",
   "source": "./src/index.ts",
   "main": "./lib/commonjs/index.js",
@@ -18,11 +18,23 @@
         "default": "./lib/commonjs/index.js"
       }
     },
+    "./plugins/insights": {
+      "source": "./src/plugins/insights/index.ts",
+      "import": {
+        "types": "./lib/typescript/module/plugins/insights/index.d.ts",
+        "default": "./lib/module/plugins/insights/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/plugins/insights/index.d.ts",
+        "default": "./lib/commonjs/plugins/insights/index.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "src",
     "lib",
+    "plugins",
     "android",
     "ios",
     "cpp",
@@ -121,7 +133,7 @@
   "dependencies": {
     "use-sync-external-store": "1.5.0",
     "@hot-updater/core": "1.0.0-rc.15",
-    "@hot-updater/plugin-core": "1.0.0-rc.16"
+    "@hot-updater/plugin-core": "1.0.0-rc.17"
   },
   "scripts": {
     "build": "node ./scripts/sync-sdk-version.mjs run -- bob build",

package/plugins/insights/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@hot-updater/react-native/plugins/insights",
+  "private": true,
+  "source": "../../src/plugins/insights/index.ts",
+  "main": "../../lib/commonjs/plugins/insights/index.js",
+  "module": "../../lib/module/plugins/insights/index.js",
+  "types": "../../lib/typescript/commonjs/plugins/insights/index.d.ts"
+}

package/src/appReady.spec.ts

@@ -0,0 +1,393 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createNotifyReadResult, stubNotifyFrame } from "./appReady.test-utils";
+import type {
+  AppReadyResult,
+  HotUpdaterClientHooks,
+  HotUpdaterClientPlugin,
+} from "./clientPlugin";
+import type {
+  ActiveUpdateState,
+  LaunchTransition,
+  NotifyAppReadyResult,
+} from "./native";
+
+vi.mock("react-native", () => ({
+  Platform: { OS: "ios" },
+}));
+
+const mocks = vi.hoisted(() => {
+  Reflect.set(globalThis, "HotUpdater", { SDK_VERSION: "test-sdk-version" });
+  return {
+    getAppVersion: vi.fn(() => "1.0.0"),
+    getBundleId: vi.fn(() => "bundle-id"),
+    getChannel: vi.fn(() => "production"),
+    getActiveUpdateState: vi.fn<() => ActiveUpdateState>(),
+    getCohort: vi.fn(() => "123"),
+    getFingerprintHash: vi.fn(() => "fingerprint-hash"),
+    getInstallId: vi.fn(() => "install-id"),
+    getStorageItem: vi.fn<(key: string) => string | null>(() => null),
+    setStorageItem: vi.fn(),
+    readNotifyAppReady: vi.fn<
+      () => {
+        transition: LaunchTransition | null;
+        pending: boolean;
+        result: NotifyAppReadyResult;
+      }
+    >(() => createNotifyReadResult()),
+  };
+});
+
+vi.mock("./native", () => mocks);
+
+const recordingPlugin = (
+  hooks: (events: unknown[]) => HotUpdaterClientHooks = (events) => ({
+    onAppReady: (result) => {
+      events.push(["onAppReady", result]);
+    },
+    onBundleDownloaded: (info) => {
+      events.push(["onBundleDownloaded", info]);
+    },
+  }),
+) => {
+  const events: unknown[] = [];
+  const plugin: HotUpdaterClientPlugin = {
+    id: "recorder",
+    setup: () => hooks(events),
+  };
+  return { events, plugin };
+};
+
+const configure = async (
+  plugins: HotUpdaterClientPlugin[],
+  onError?: (error: unknown) => void,
+) => {
+  const { configurePlugins } = await import("./pluginHost");
+  configurePlugins(plugins, {
+    baseURL: "https://updates.example.com",
+    ...(onError ? { onError } : {}),
+  });
+};
+
+describe("app-ready reporting to plugins", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+    for (const mock of Object.values(mocks)) mock.mockReset();
+    mocks.getAppVersion.mockReturnValue("1.0.0");
+    mocks.getBundleId.mockReturnValue("bundle-id");
+    mocks.getChannel.mockReturnValue("production");
+    mocks.getActiveUpdateState.mockReturnValue({
+      activeSelection: null,
+      stableSelection: null,
+      verificationPending: false,
+    });
+    mocks.getCohort.mockReturnValue("123");
+    mocks.getFingerprintHash.mockReturnValue("fingerprint-hash");
+    mocks.getInstallId.mockReturnValue("install-id");
+    mocks.getStorageItem.mockReturnValue(null);
+    mocks.readNotifyAppReady.mockReturnValue(createNotifyReadResult());
+  });
+
+  it.each([
+    {
+      label: "running selection",
+      pending: false,
+      channel: "production",
+      expected: "release-running",
+    },
+    {
+      label: "staged selection",
+      pending: true,
+      channel: "production",
+      expected: "release-running",
+    },
+    {
+      label: "another channel",
+      pending: false,
+      channel: "preview",
+      expected: null,
+    },
+  ])(
+    "attributes an unchanged launch with $label",
+    async ({ pending, channel, expected }) => {
+      stubNotifyFrame();
+      const running = {
+        kind: "BUNDLE" as const,
+        releaseId: "release-running",
+        bundleId: "bundle-id",
+        channel,
+      };
+      mocks.getActiveUpdateState.mockReturnValue({
+        activeSelection: pending
+          ? {
+              ...running,
+              releaseId: "release-pending",
+              bundleId: "bundle-pending",
+            }
+          : running,
+        stableSelection: pending ? running : null,
+        verificationPending: pending,
+      });
+      const { events, plugin } = recordingPlugin();
+      await configure([plugin]);
+      const { handleNotifyAppReady } = await import("./appReady");
+
+      const readiness = handleNotifyAppReady({});
+      await vi.runOnlyPendingTimersAsync();
+      await readiness;
+
+      expect(events).toEqual([
+        [
+          "onAppReady",
+          {
+            status: "UNCHANGED",
+            channel: "production",
+            bundleId: "bundle-id",
+            releaseId: expected,
+            previousProcessExit: null,
+          } satisfies AppReadyResult,
+        ],
+      ]);
+    },
+  );
+
+  it.each(["UPDATE_APPLIED", "RECOVERED"] as const)(
+    "reports %s with the persisted transition and calls onNotifyAppReady",
+    async (status) => {
+      stubNotifyFrame();
+      mocks.readNotifyAppReady.mockReturnValue(
+        createNotifyReadResult(
+          { status, fromBundleId: "bundle-a", toBundleId: "bundle-b" },
+          {
+            type: status,
+            fromBundleId: "bundle-a",
+            fromReleaseId: "release-a",
+            toBundleId: "bundle-b",
+            toReleaseId: "release-b",
+            updateStrategy: "fingerprint",
+          },
+        ),
+      );
+      const { events, plugin } = recordingPlugin();
+      await configure([plugin]);
+      const onNotifyAppReady = vi.fn();
+      const { handleNotifyAppReady } = await import("./appReady");
+
+      const readiness = handleNotifyAppReady({ onNotifyAppReady });
+      await vi.runOnlyPendingTimersAsync();
+      await readiness;
+
+      expect(events).toEqual([
+        [
+          "onAppReady",
+          {
+            status,
+            channel: "production",
+            fromBundleId: "bundle-a",
+            fromReleaseId: "release-a",
+            toBundleId: "bundle-b",
+            toReleaseId: "release-b",
+            updateStrategy: "fingerprint",
+            previousProcessExit: null,
+          },
+        ],
+      ]);
+      expect(onNotifyAppReady).toHaveBeenCalledWith({
+        status,
+        fromBundleId: "bundle-a",
+        toBundleId: "bundle-b",
+      });
+    },
+  );
+
+  it("waits for native launch verification before reporting", async () => {
+    stubNotifyFrame();
+    mocks.readNotifyAppReady
+      .mockReturnValueOnce(createNotifyReadResult(undefined, null, true))
+      .mockReturnValueOnce(createNotifyReadResult(undefined, null, true))
+      .mockReturnValue(createNotifyReadResult());
+    const { events, plugin } = recordingPlugin();
+    await configure([plugin]);
+    const { handleNotifyAppReady } = await import("./appReady");
+
+    const readiness = handleNotifyAppReady({});
+    await vi.runOnlyPendingTimersAsync();
+    expect(events).toEqual([]);
+    await vi.runAllTimersAsync();
+    await readiness;
+
+    expect(mocks.readNotifyAppReady).toHaveBeenCalledTimes(3);
+    expect(events).toHaveLength(1);
+  });
+
+  it("reports the launch once per runtime while every init call gets readiness", async () => {
+    stubNotifyFrame();
+    const { events, plugin } = recordingPlugin();
+    await configure([plugin]);
+    const onNotifyAppReady = vi.fn();
+    const { handleNotifyAppReady } = await import("./appReady");
+
+    const first = handleNotifyAppReady({ onNotifyAppReady });
+    const second = handleNotifyAppReady({ onNotifyAppReady });
+    await vi.runOnlyPendingTimersAsync();
+    await Promise.all([first, second]);
+
+    expect(events).toHaveLength(1);
+    expect(onNotifyAppReady).toHaveBeenCalledTimes(2);
+  });
+
+  it("skips onAppReady for an applied launch without its persisted transition", async () => {
+    stubNotifyFrame();
+    mocks.readNotifyAppReady.mockReturnValue(
+      createNotifyReadResult(
+        {
+          status: "UPDATE_APPLIED",
+          fromBundleId: "bundle-a",
+          toBundleId: "bundle-b",
+        },
+        null,
+      ),
+    );
+    const { events, plugin } = recordingPlugin();
+    await configure([plugin]);
+    const onNotifyAppReady = vi.fn();
+    const { handleNotifyAppReady } = await import("./appReady");
+
+    const readiness = handleNotifyAppReady({ onNotifyAppReady });
+    await vi.runOnlyPendingTimersAsync();
+    await readiness;
+
+    expect(events).toEqual([]);
+    expect(onNotifyAppReady).toHaveBeenCalledOnce();
+  });
+
+  it("reports a throwing or rejecting hook through onError and keeps readiness", async () => {
+    stubNotifyFrame();
+    const onError = vi.fn();
+    const throwing: HotUpdaterClientPlugin = {
+      id: "throwing",
+      setup: () => ({
+        onAppReady: () => {
+          throw new Error("hook failed");
+        },
+      }),
+    };
+    const rejecting: HotUpdaterClientPlugin = {
+      id: "rejecting",
+      setup: () => ({
+        onAppReady: async () => {
+          throw new Error("hook rejected");
+        },
+      }),
+    };
+    await configure([throwing, rejecting], onError);
+    const onNotifyAppReady = vi.fn();
+    const { handleNotifyAppReady } = await import("./appReady");
+
+    const readiness = handleNotifyAppReady({ onNotifyAppReady });
+    await vi.runOnlyPendingTimersAsync();
+    await readiness;
+    await vi.runAllTimersAsync();
+
+    expect(onNotifyAppReady).toHaveBeenCalledWith({ status: "UNCHANGED" });
+    expect(onError).toHaveBeenCalledTimes(2);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: '[HotUpdater] Plugin "throwing" failed in onAppReady',
+        cause: expect.objectContaining({ message: "hook failed" }),
+      }),
+    );
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: '[HotUpdater] Plugin "rejecting" failed in onAppReady',
+      }),
+    );
+  });
+
+  it("delivers events after the launch, even when they happen first", async () => {
+    stubNotifyFrame();
+    const { events, plugin } = recordingPlugin();
+    await configure([plugin]);
+    const { emitAfterAppReady, handleNotifyAppReady } =
+      await import("./appReady");
+
+    const readiness = handleNotifyAppReady({});
+    emitAfterAppReady("onBundleDownloaded", () => ({
+      channel: "production",
+      fromBundleId: "bundle-id",
+      fromReleaseId: null,
+      toBundleId: "next-bundle",
+      toReleaseId: "next-release",
+      updateStrategy: "appVersion",
+      delivery: "manifest",
+      patchFallback: false,
+    }));
+    expect(events).toEqual([]);
+    await vi.runOnlyPendingTimersAsync();
+    await readiness;
+    await Promise.resolve();
+
+    expect(events.map((event) => (event as [string])[0])).toEqual([
+      "onAppReady",
+      "onBundleDownloaded",
+    ]);
+  });
+
+  it("passes on why the previous process exited, and keeps it for later events", async () => {
+    stubNotifyFrame();
+    mocks.readNotifyAppReady.mockReturnValue(
+      createNotifyReadResult(
+        {
+          status: "RECOVERED",
+          fromBundleId: "bundle-b",
+          toBundleId: "bundle-a",
+        },
+        {
+          type: "RECOVERED",
+          fromBundleId: "bundle-b",
+          fromReleaseId: null,
+          toBundleId: "bundle-a",
+          toReleaseId: null,
+          updateStrategy: "appVersion",
+        },
+        false,
+        "CRASH_NATIVE",
+      ),
+    );
+    const { events, plugin } = recordingPlugin();
+    await configure([plugin]);
+    const { getPreviousProcessExit, handleNotifyAppReady } =
+      await import("./appReady");
+    expect(getPreviousProcessExit()).toBeNull();
+
+    const readiness = handleNotifyAppReady({});
+    await vi.runOnlyPendingTimersAsync();
+    await readiness;
+
+    expect(events).toEqual([
+      [
+        "onAppReady",
+        expect.objectContaining({
+          status: "RECOVERED",
+          previousProcessExit: "CRASH_NATIVE",
+        }),
+      ],
+    ]);
+    expect(getPreviousProcessExit()).toBe("CRASH_NATIVE");
+  });
+
+  it("builds no event when no plugin listens", async () => {
+    stubNotifyFrame();
+    await configure([]);
+    const { handleNotifyAppReady } = await import("./appReady");
+
+    const readiness = handleNotifyAppReady({});
+    await vi.runOnlyPendingTimersAsync();
+    await readiness;
+
+    expect(mocks.getActiveUpdateState).not.toHaveBeenCalled();
+    expect(mocks.getBundleId).not.toHaveBeenCalled();
+  });
+});

package/src/{notifyAppReadyInsights.test-utils.ts → appReady.test-utils.ts}

@@ -1,20 +1,20 @@
 import { vi } from "vitest";
 
-import type {
-  NotifyAppReadyInsightsEvent,
-  NotifyAppReadyResult,
-} from "./native";
+import type { LaunchTransition, NotifyAppReadyResult } from "./native";
 
 export const createNotifyReadResult = (
   result: NotifyAppReadyResult = { status: "UNCHANGED" },
-  insightsEvent: NotifyAppReadyInsightsEvent | null = null,
+  transition: LaunchTransition | null = null,
   pending = false,
+  previousProcessExit: string | null = null,
 ): {
-  insightsEvent: NotifyAppReadyInsightsEvent | null;
+  transition: LaunchTransition | null;
+  previousProcessExit: string | null;
   pending: boolean;
   result: NotifyAppReadyResult;
 } => ({
-  insightsEvent,
+  transition,
+  previousProcessExit,
   pending,
   result,
 });

package/src/appReady.ts

@@ -0,0 +1,149 @@
+import type { AppReadyResult } from "./clientPlugin";
+import type { HotUpdaterError } from "./error";
+import {
+  getActiveUpdateState,
+  getBundleId,
+  getChannel,
+  type LaunchTransition,
+  type NotifyAppReadyResult,
+  readNotifyAppReady,
+} from "./native";
+import {
+  buildPluginEvent,
+  dispatchPluginHook,
+  emitPluginHook,
+} from "./pluginHost";
+
+export type NotifyAppReadyOptions = {
+  onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+  onError?: (error: HotUpdaterError | Error | unknown) => void;
+};
+
+type RequestAnimationFrame = (callback: (timestamp: number) => void) => number;
+
+let didEmitAppReady = false;
+/** Settles once this runtime's launch was read, whether it was reported or failed. */
+let appReadyRead: Promise<unknown> | null = null;
+/** Why the previous main process exited, read with this runtime's launch. */
+let previousProcessExit: string | null = null;
+
+/** Android 11+: why the app's previous main process exited, once the launch was read. */
+export const getPreviousProcessExit = (): string | null => previousProcessExit;
+
+const waitForNextFrame = () =>
+  new Promise<void>((resolve) => {
+    const requestAnimationFrame = (
+      globalThis as typeof globalThis & {
+        requestAnimationFrame?: RequestAnimationFrame;
+      }
+    )?.requestAnimationFrame;
+
+    if (requestAnimationFrame) {
+      requestAnimationFrame(() => resolve());
+      return;
+    }
+
+    void Promise.resolve().then(resolve);
+  });
+
+/**
+ * The Release the running bundle was selected as: the active or stable
+ * selection that names it on the current channel.
+ */
+export const getRunningReleaseId = (
+  bundleId: string,
+  channel: string,
+): string | null => {
+  const state = getActiveUpdateState();
+  return (
+    [state.activeSelection, state.stableSelection].find(
+      (selection) =>
+        selection?.bundleId === bundleId && selection.channel === channel,
+    )?.releaseId ?? null
+  );
+};
+
+const toAppReadyResult = (
+  result: NotifyAppReadyResult,
+  transition: LaunchTransition | null,
+): AppReadyResult | null => {
+  const channel = getChannel();
+  if (result.status === "UNCHANGED") {
+    const bundleId = getBundleId();
+    return {
+      status: "UNCHANGED",
+      channel,
+      bundleId,
+      releaseId: getRunningReleaseId(bundleId, channel),
+      previousProcessExit,
+    };
+  }
+  // Native persists the transition with every applied or recovered launch;
+  // a report without it cannot say what moved.
+  if (transition === null) return null;
+  return {
+    status: transition.type,
+    channel,
+    fromBundleId: transition.fromBundleId,
+    fromReleaseId: transition.fromReleaseId,
+    toBundleId: transition.toBundleId,
+    toReleaseId: transition.toReleaseId,
+    updateStrategy: transition.updateStrategy,
+    previousProcessExit,
+  };
+};
+
+const notifyAppReady = async (
+  options: NotifyAppReadyOptions,
+): Promise<NotifyAppReadyResult | undefined> => {
+  try {
+    let nativeReadResult: ReturnType<typeof readNotifyAppReady>;
+    do {
+      await waitForNextFrame();
+      nativeReadResult = readNotifyAppReady();
+    } while (nativeReadResult.pending);
+
+    const { result, transition } = nativeReadResult;
+    previousProcessExit = nativeReadResult.previousProcessExit;
+    if (!didEmitAppReady) {
+      didEmitAppReady = true;
+      emitPluginHook("onAppReady", () => toAppReadyResult(result, transition));
+    }
+
+    options.onNotifyAppReady?.(result);
+    return result;
+  } catch (error) {
+    const normalizedError =
+      error instanceof Error ? error : new Error(String(error));
+    options.onError?.(error);
+    console.warn("[HotUpdater] Failed to notify app ready:", normalizedError);
+    return undefined;
+  }
+};
+
+/** Reads this runtime's launch once native finalizes it and reports it to plugins. */
+export const handleNotifyAppReady = (
+  options: NotifyAppReadyOptions,
+): Promise<NotifyAppReadyResult | undefined> => {
+  const readiness = notifyAppReady(options);
+  appReadyRead ??= readiness;
+  return readiness;
+};
+
+/**
+ * Calls a plugin hook after this runtime's `onAppReady`, so plugins see the
+ * launch before anything that followed it. The event is built now, from the
+ * state it describes, and only when a plugin listens.
+ */
+export const emitAfterAppReady: typeof emitPluginHook = (
+  name,
+  createPayload,
+) => {
+  const payload = buildPluginEvent(name, createPayload);
+  if (payload === null) return;
+  if (appReadyRead === null) {
+    dispatchPluginHook(name, payload);
+    return;
+  }
+  void appReadyRead.then(() => dispatchPluginHook(name, payload));
+};

package/src/baseURL.ts

@@ -0,0 +1,15 @@
+import type { HotUpdaterBaseURL } from "./types";
+
+/** Resolves a functional baseURL and drops trailing slashes. */
+export const resolveBaseURL = async (
+  baseURL: HotUpdaterBaseURL,
+): Promise<string> => {
+  const resolvedBaseURL =
+    typeof baseURL === "function" ? await baseURL() : baseURL;
+
+  if (!resolvedBaseURL) {
+    throw new Error("baseURL function must return a non-empty string");
+  }
+
+  return resolvedBaseURL.replace(/\/+$/, "");
+};