@gooddata/sdk-ui-pluggable-host 11.40.0-alpha.3

package/esm/lib/chunkReloadGuard.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Optional callback invoked synchronously immediately before a stale-chunk hard reload.
+ * Gives the host app a chance to record telemetry before navigation cancels in-flight requests.
+ *
+ * @alpha
+ */
+export interface IStaleChunkReloadInfo {
+    /** Human-readable reason — e.g. the underlying preload error message. */
+    reason: string;
+    /** COMMITHASH of the build the tab was loaded with, or an empty string if unknown. */
+    commitHash: string;
+}
+/**
+ * @alpha
+ */
+export type StaleChunkReloadListener = (info: IStaleChunkReloadInfo) => void;
+/**
+ * Registers a listener invoked synchronously just before a stale-chunk hard reload,
+ * intended for telemetry. Called only when the reload actually happens — skipped
+ * reloads (loop-guard hits) do not fire the listener.
+ *
+ * @remarks
+ * Trackers should send the event via `navigator.sendBeacon` or `fetch` with `keepalive`
+ * because the page is navigating away immediately afterwards.
+ *
+ * @alpha
+ */
+export declare function setStaleChunkReloadListener(listener: StaleChunkReloadListener | undefined): void;
+/**
+ * Query-string parameter appended to the URL on a stale-chunk reload. The value
+ * is a timestamp; its only purpose is to make the navigation target a URL the
+ * browser has never seen before, defeating any cached HTML/remoteEntry that
+ * might otherwise replay the stale module graph.
+ *
+ * Exported so callers and tests can recognise (and strip) the marker if needed.
+ *
+ * @alpha
+ */
+export declare const STALE_CHUNK_RELOAD_PARAM = "_gdcr";
+/**
+ * Triggers a hard page reload once, guarded against loops by sessionStorage.
+ *
+ * If the same COMMITHASH already triggered a reload within the last 30 seconds,
+ * the call is a no-op so the user is not stuck reloading a broken build.
+ *
+ * @remarks
+ * Uses `location.replace` with a cache-busting query parameter rather than
+ * `location.reload()`. A soft reload honours the HTTP cache, which has bitten
+ * us when an intermediate chunk (max-age=30d) is still served from cache and
+ * keeps replaying a stale module graph after the deploy moved forward. Writing
+ * a unique URL forces the browser to treat it as a fresh navigation.
+ *
+ * @alpha
+ */
+export declare function reloadForStaleChunks(reason: string): void;
+/**
+ * Installs a window listener for `vite:preloadError`. When fired (e.g. a chunk has
+ * been removed by a redeploy), the page is hard-reloaded once to pick up new chunk
+ * hashes from a fresh index.html.
+ *
+ * Idempotent: calling more than once registers the listener only once.
+ *
+ * @alpha
+ */
+export declare function installPreloadErrorHandler(): void;
+/**
+ * Options for {@link installVersionWatcher}.
+ *
+ * @alpha
+ */
+export interface IVersionWatcherOptions {
+    /** URL of the COMMITHASH file emitted by the host build. */
+    url: string;
+    /** Poll interval in ms. Default: 5 minutes. */
+    intervalMs?: number;
+    /** Called once when a new deployment is detected. */
+    onNewDeployment: (newHash: string) => void;
+}
+/**
+ * Periodically polls the COMMITHASH file and fires `onNewDeployment` once when the
+ * deployed commit differs from the one the tab was loaded with. Stops polling
+ * after the first detection — the caller decides what to do (typically: show a
+ * "please reload" banner).
+ *
+ * Idempotent: calling more than once is a no-op after the first invocation.
+ *
+ * @alpha
+ */
+export declare function installVersionWatcher({ url, intervalMs, onNewDeployment }: IVersionWatcherOptions): void;

package/esm/lib/chunkReloadGuard.js

@@ -0,0 +1,203 @@
+// (C) 2026 GoodData Corporation
+const RELOAD_FLAG_KEY = "gd-chunk-reload-guard";
+const RELOAD_LOOP_WINDOW_MS = 30_000;
+let preloadErrorHandlerInstalled = false;
+let versionWatcherInstalled = false;
+let staleChunkReloadListener;
+function readReloadFlag() {
+    try {
+        const raw = sessionStorage.getItem(RELOAD_FLAG_KEY);
+        if (!raw) {
+            return undefined;
+        }
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.hash !== "string" || typeof parsed.at !== "number") {
+            return undefined;
+        }
+        return { hash: parsed.hash, at: parsed.at };
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeReloadFlag(hash) {
+    try {
+        sessionStorage.setItem(RELOAD_FLAG_KEY, JSON.stringify({ hash, at: Date.now() }));
+    }
+    catch {
+        // sessionStorage unavailable (privacy mode, sandboxed iframe). Without the
+        // anti-loop guard we accept the risk of a reload loop on a broken redeploy
+        // — that is still better than a silent 404 white screen.
+    }
+}
+function getCurrentHash() {
+    return typeof window === "undefined" ? "" : (window.COMMITHASH ?? "");
+}
+/**
+ * Registers a listener invoked synchronously just before a stale-chunk hard reload,
+ * intended for telemetry. Called only when the reload actually happens — skipped
+ * reloads (loop-guard hits) do not fire the listener.
+ *
+ * @remarks
+ * Trackers should send the event via `navigator.sendBeacon` or `fetch` with `keepalive`
+ * because the page is navigating away immediately afterwards.
+ *
+ * @alpha
+ */
+export function setStaleChunkReloadListener(listener) {
+    staleChunkReloadListener = listener;
+}
+/**
+ * Query-string parameter appended to the URL on a stale-chunk reload. The value
+ * is a timestamp; its only purpose is to make the navigation target a URL the
+ * browser has never seen before, defeating any cached HTML/remoteEntry that
+ * might otherwise replay the stale module graph.
+ *
+ * Exported so callers and tests can recognise (and strip) the marker if needed.
+ *
+ * @alpha
+ */
+export const STALE_CHUNK_RELOAD_PARAM = "_gdcr";
+/**
+ * Triggers a hard page reload once, guarded against loops by sessionStorage.
+ *
+ * If the same COMMITHASH already triggered a reload within the last 30 seconds,
+ * the call is a no-op so the user is not stuck reloading a broken build.
+ *
+ * @remarks
+ * Uses `location.replace` with a cache-busting query parameter rather than
+ * `location.reload()`. A soft reload honours the HTTP cache, which has bitten
+ * us when an intermediate chunk (max-age=30d) is still served from cache and
+ * keeps replaying a stale module graph after the deploy moved forward. Writing
+ * a unique URL forces the browser to treat it as a fresh navigation.
+ *
+ * @alpha
+ */
+export function reloadForStaleChunks(reason) {
+    if (typeof window === "undefined") {
+        return;
+    }
+    const currentHash = getCurrentHash();
+    const previous = readReloadFlag();
+    if (previous?.hash === currentHash && Date.now() - previous.at < RELOAD_LOOP_WINDOW_MS) {
+        console.error(`[host-runtime/chunk-reload-guard] Skipping reload for "${reason}" — already reloaded for the same build (${currentHash}) within ${RELOAD_LOOP_WINDOW_MS}ms.`);
+        return;
+    }
+    writeReloadFlag(currentHash);
+    console.warn(`[host-runtime/chunk-reload-guard] Reloading page due to: ${reason}`);
+    try {
+        staleChunkReloadListener?.({ reason, commitHash: currentHash });
+    }
+    catch (error) {
+        // Telemetry failures must never block the recovery reload.
+        console.error("[host-runtime/chunk-reload-guard] Stale-chunk reload listener threw.", error);
+    }
+    const target = new URL(window.location.href);
+    target.searchParams.set(STALE_CHUNK_RELOAD_PARAM, String(Date.now()));
+    window.location.replace(target.toString());
+}
+/**
+ * Installs a window listener for `vite:preloadError`. When fired (e.g. a chunk has
+ * been removed by a redeploy), the page is hard-reloaded once to pick up new chunk
+ * hashes from a fresh index.html.
+ *
+ * Idempotent: calling more than once registers the listener only once.
+ *
+ * @alpha
+ */
+export function installPreloadErrorHandler() {
+    if (preloadErrorHandlerInstalled || typeof window === "undefined") {
+        return;
+    }
+    preloadErrorHandlerInstalled = true;
+    window.addEventListener("vite:preloadError", (event) => {
+        const preloadEvent = event;
+        // Do NOT preventDefault. Vite's preload helper only rethrows when the event
+        // is left default-allowed; with preventDefault the helper returns undefined,
+        // and downstream wrappers (notably Module Federation's expose factory, which
+        // does `Object.assign({}, await import(...))`) silently produce an empty
+        // module — surfacing as a misleading "does not export a valid pluggable app"
+        // error from asPluggableApp instead of a preload failure. If the loop guard
+        // suppresses the reload, the original rejection still gives the caller a
+        // truthful failure to handle.
+        reloadForStaleChunks(`vite:preloadError (${preloadEvent.payload?.message ?? "unknown"})`);
+    });
+}
+/**
+ * Periodically polls the COMMITHASH file and fires `onNewDeployment` once when the
+ * deployed commit differs from the one the tab was loaded with. Stops polling
+ * after the first detection — the caller decides what to do (typically: show a
+ * "please reload" banner).
+ *
+ * Idempotent: calling more than once is a no-op after the first invocation.
+ *
+ * @alpha
+ */
+export function installVersionWatcher({ url, intervalMs = 5 * 60_000, onNewDeployment, }) {
+    if (versionWatcherInstalled || typeof window === "undefined") {
+        return;
+    }
+    const initialHash = getCurrentHash();
+    if (!initialHash) {
+        // Without a baseline we cannot detect change — the build did not inject COMMITHASH.
+        return;
+    }
+    versionWatcherInstalled = true;
+    let stopped = false;
+    let pendingTimeoutId;
+    const check = async () => {
+        if (stopped) {
+            return;
+        }
+        try {
+            const response = await fetch(url, { cache: "no-store", credentials: "same-origin" });
+            if (!response.ok) {
+                return;
+            }
+            const remoteHash = (await response.text()).trim();
+            if (remoteHash && remoteHash !== initialHash && !remoteHash.startsWith("<")) {
+                stopped = true;
+                try {
+                    onNewDeployment(remoteHash);
+                }
+                catch (error) {
+                    // Don't let a broken consumer kill the watcher (although we already stopped).
+                    console.error("[host-runtime/chunk-reload-guard] onNewDeployment threw.", error);
+                }
+            }
+        }
+        catch {
+            // Network blip; try again on the next tick.
+        }
+    };
+    const scheduleNextTick = () => {
+        if (stopped || pendingTimeoutId !== undefined) {
+            return;
+        }
+        // Skip ticks while the tab is hidden — the watcher resumes on visibilitychange.
+        // The first poll after install is gated the same way below.
+        if (document.hidden) {
+            return;
+        }
+        pendingTimeoutId = window.setTimeout(() => {
+            pendingTimeoutId = undefined;
+            void check().finally(scheduleNextTick);
+        }, intervalMs);
+    };
+    document.addEventListener("visibilitychange", () => {
+        if (stopped) {
+            return;
+        }
+        if (document.hidden) {
+            // Cancel a pending tick so we don't fire it the moment the tab returns —
+            // we'll schedule a fresh interval from the visibility-change instead.
+            if (pendingTimeoutId !== undefined) {
+                window.clearTimeout(pendingTimeoutId);
+                pendingTimeoutId = undefined;
+            }
+            return;
+        }
+        scheduleNextTick();
+    });
+    scheduleNextTick();
+}

package/esm/lib/hostNotifications.d.ts

@@ -0,0 +1,20 @@
+import { type IHostUiMountHandle, type IHostUiNotification } from "@gooddata/sdk-pluggable-application-model";
+/**
+ * Dispatches a notification into the currently mounted host UI module.
+ *
+ * @remarks
+ * If no UI is mounted yet (e.g. the host bootstrap is still in progress) the notification
+ * is queued and replayed when the host UI handle registers. The queue is capped at a small
+ * bounded size; oldest entries are dropped on overflow.
+ *
+ * @alpha
+ */
+export declare function dispatchHostNotification(notification: IHostUiNotification): void;
+/**
+ * Registers (or clears) the host UI mount handle that should receive notifications.
+ *
+ * @remarks
+ * Called by {@link HostUiContainer} after a successful mount and again with `undefined`
+ * on unmount. On register, any queued notifications are flushed in arrival order.
+ */
+export declare function setActiveHostHandle(handle: IHostUiMountHandle | undefined): void;

package/esm/lib/hostNotifications.js

@@ -0,0 +1,50 @@
+// (C) 2026 GoodData Corporation
+//
+// Routes runtime-detected notifications (e.g. a new deployment was published) to whichever
+// host UI module is currently mounted. Notifications dispatched before any UI is mounted
+// are queued and replayed once the UI registers itself, so the user is never silently dropped
+// because of a timing race between the host's detection and the UI mount.
+//
+// Bounds the buffer for pre-mount dispatches. In practice we expect at most one
+// notification before the UI mounts (the new-deployment toast), so this only matters
+// as defence against a misbehaving caller that loops.
+const MAX_QUEUE_SIZE = 16;
+let activeHandle;
+const queue = [];
+/**
+ * Dispatches a notification into the currently mounted host UI module.
+ *
+ * @remarks
+ * If no UI is mounted yet (e.g. the host bootstrap is still in progress) the notification
+ * is queued and replayed when the host UI handle registers. The queue is capped at a small
+ * bounded size; oldest entries are dropped on overflow.
+ *
+ * @alpha
+ */
+export function dispatchHostNotification(notification) {
+    if (activeHandle?.notify) {
+        activeHandle.notify(notification);
+        return;
+    }
+    if (queue.length >= MAX_QUEUE_SIZE) {
+        queue.shift();
+    }
+    queue.push(notification);
+}
+/**
+ * Registers (or clears) the host UI mount handle that should receive notifications.
+ *
+ * @remarks
+ * Called by {@link HostUiContainer} after a successful mount and again with `undefined`
+ * on unmount. On register, any queued notifications are flushed in arrival order.
+ */
+export function setActiveHostHandle(handle) {
+    activeHandle = handle;
+    if (!handle?.notify || queue.length === 0) {
+        return;
+    }
+    const drained = queue.splice(0, queue.length);
+    for (const notification of drained) {
+        handle.notify(notification);
+    }
+}

package/esm/lib/isProduction.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Reads the compile-time PRODUCTION flag if the consumer's bundler defines it
+ * (e.g. via vite's `define: { PRODUCTION: ... }`); defaults to false (dev-mode
+ * semantics) when undefined.
+ *
+ * Reading `PRODUCTION` directly as a bare identifier throws ReferenceError in
+ * any consumer whose bundler doesn't substitute it — `typeof` is the only safe
+ * way to probe for an unbound global without crashing.
+ *
+ * @internal
+ */
+export declare const isProduction: boolean;

package/esm/lib/isProduction.js

@@ -0,0 +1,13 @@
+// (C) 2026 GoodData Corporation
+/**
+ * Reads the compile-time PRODUCTION flag if the consumer's bundler defines it
+ * (e.g. via vite's `define: { PRODUCTION: ... }`); defaults to false (dev-mode
+ * semantics) when undefined.
+ *
+ * Reading `PRODUCTION` directly as a bare identifier throws ReferenceError in
+ * any consumer whose bundler doesn't substitute it — `typeof` is the only safe
+ * way to probe for an unbound global without crashing.
+ *
+ * @internal
+ */
+export const isProduction = typeof PRODUCTION !== "undefined" && PRODUCTION;

package/esm/loader/lastVisitedApp.d.ts

@@ -0,0 +1,11 @@
+import { type ApplicationScope } from "@gooddata/sdk-model";
+/**
+ * Returns the last visited app ID for the given scope, or `undefined` if none is stored
+ * or the stored value cannot be read.
+ */
+export declare function getLastVisitedApp(scope: ApplicationScope): string | undefined;
+/**
+ * Persists the app ID that the user last visited in the given scope.
+ * Silently swallows errors (e.g. storage full, private browsing).
+ */
+export declare function setLastVisitedApp(scope: ApplicationScope, appId: string): void;

package/esm/loader/lastVisitedApp.js

@@ -0,0 +1,43 @@
+// (C) 2026 GoodData Corporation
+const STORAGE_KEY = "gdc-host-lastVisitedApp";
+/**
+ * Safely parse the stored JSON record, falling back to an empty record on
+ * missing or corrupt values.
+ */
+function safeParse(raw) {
+    if (!raw) {
+        return {};
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Returns the last visited app ID for the given scope, or `undefined` if none is stored
+ * or the stored value cannot be read.
+ */
+export function getLastVisitedApp(scope) {
+    try {
+        return safeParse(localStorage.getItem(STORAGE_KEY))[scope] ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persists the app ID that the user last visited in the given scope.
+ * Silently swallows errors (e.g. storage full, private browsing).
+ */
+export function setLastVisitedApp(scope, appId) {
+    try {
+        const record = safeParse(localStorage.getItem(STORAGE_KEY));
+        record[scope] = appId;
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(record));
+    }
+    catch {
+        // Intentionally ignored — localStorage may be unavailable or full
+    }
+}

package/esm/loader/localLoader.d.ts

@@ -0,0 +1,16 @@
+import { type IPluggableApp } from "@gooddata/sdk-pluggable-application-model";
+/**
+ * @alpha
+ */
+export type LocalPluggableApplicationLoader = () => Promise<{
+    default?: IPluggableApp | unknown;
+    pluggableApp?: IPluggableApp;
+}>;
+/**
+ * Registers the local application loaders map. Called by the host or harness
+ * before any app loading occurs.
+ *
+ * @alpha
+ */
+export declare function registerLocalApplicationLoaders(loaders: Record<string, LocalPluggableApplicationLoader>): void;
+export declare function loadLocalPluggableApplication(moduleId: string): Promise<IPluggableApp>;

package/esm/loader/localLoader.js

@@ -0,0 +1,38 @@
+// (C) 2026 GoodData Corporation
+let registeredLoaders = {};
+/**
+ * Registers the local application loaders map. Called by the host or harness
+ * before any app loading occurs.
+ *
+ * @alpha
+ */
+export function registerLocalApplicationLoaders(loaders) {
+    registeredLoaders = loaders;
+    localAppPromises.clear();
+}
+const localAppPromises = new Map();
+function asPluggableApp(moduleId, loaded) {
+    const app = loaded.pluggableApp ?? loaded.default;
+    if (!app || typeof app.mount !== "function") {
+        throw new Error(`[host-runtime/local-loader] Local module "${moduleId}" does not export a valid pluggable app.`);
+    }
+    return app;
+}
+export function loadLocalPluggableApplication(moduleId) {
+    const cached = localAppPromises.get(moduleId);
+    if (cached) {
+        return cached;
+    }
+    const loader = registeredLoaders[moduleId];
+    if (!loader) {
+        return Promise.reject(new Error(`[host-runtime/local-loader] Unknown local module "${moduleId}" in registry.`));
+    }
+    const loadingPromise = loader()
+        .then((loaded) => asPluggableApp(moduleId, loaded))
+        .catch((error) => {
+        localAppPromises.delete(moduleId);
+        throw error;
+    });
+    localAppPromises.set(moduleId, loadingPromise);
+    return loadingPromise;
+}

package/esm/loader/pluggableApplicationsLoader.d.ts

@@ -0,0 +1,13 @@
+import { type PluggableApplicationRegistryItem } from "@gooddata/sdk-model";
+import { type IPluggableApp } from "@gooddata/sdk-pluggable-application-model";
+import { type IAppLifecycleCallbacks } from "../types/lifecycle.js";
+/**
+ * Registers app lifecycle callbacks used by the loader (e.g. for preload telemetry).
+ * Called by the host or harness at startup.
+ *
+ * @alpha
+ */
+export declare function registerAppLifecycleCallbacks(callbacks: IAppLifecycleCallbacks): void;
+export declare function getAppLifecycleCallbacks(): IAppLifecycleCallbacks | undefined;
+export declare function preloadPluggableApplication(app: PluggableApplicationRegistryItem): void;
+export declare function loadPluggableApplication(app: PluggableApplicationRegistryItem): Promise<IPluggableApp>;

package/esm/loader/pluggableApplicationsLoader.js

@@ -0,0 +1,55 @@
+// (C) 2026 GoodData Corporation
+import { isExternalPluggableApplicationRegistryItem, isLocalPluggableApplicationRegistryItem, isRemotePluggableApplicationRegistryItem, } from "@gooddata/sdk-model";
+import { now } from "../debug.js";
+import { loadLocalPluggableApplication } from "./localLoader.js";
+import { loadRemotePluggableApplication, preloadRemotePluggableApplication } from "./remoteLoader.js";
+let registeredLifecycle;
+/**
+ * Registers app lifecycle callbacks used by the loader (e.g. for preload telemetry).
+ * Called by the host or harness at startup.
+ *
+ * @alpha
+ */
+export function registerAppLifecycleCallbacks(callbacks) {
+    registeredLifecycle = callbacks;
+}
+export function getAppLifecycleCallbacks() {
+    return registeredLifecycle;
+}
+export function preloadPluggableApplication(app) {
+    if (isLocalPluggableApplicationRegistryItem(app)) {
+        registeredLifecycle?.onPreloadStarted?.(app.id);
+        const start = now();
+        loadLocalPluggableApplication(app.id)
+            .then(() => {
+            registeredLifecycle?.onPreloadCompleted?.(app.id, now() - start);
+        })
+            .catch(() => {
+            // Load errors are logged by loadLocalPluggableApplication
+        });
+        return;
+    }
+    if (isRemotePluggableApplicationRegistryItem(app)) {
+        registeredLifecycle?.onPreloadStarted?.(app.id);
+        const start = now();
+        preloadRemotePluggableApplication(app.remote)
+            .then(() => {
+            registeredLifecycle?.onPreloadCompleted?.(app.id, now() - start);
+        })
+            .catch(() => {
+            // Load errors are logged by preloadRemotePluggableApplication
+        });
+    }
+}
+export async function loadPluggableApplication(app) {
+    if (isExternalPluggableApplicationRegistryItem(app)) {
+        throw new Error(`[host-runtime/loader] External application "${app.id}" cannot be mounted in PluggableApplicationRenderer.`);
+    }
+    if (isLocalPluggableApplicationRegistryItem(app)) {
+        return loadLocalPluggableApplication(app.id);
+    }
+    if (isRemotePluggableApplicationRegistryItem(app)) {
+        return loadRemotePluggableApplication(app.remote);
+    }
+    throw new Error(`[host-runtime/loader] Unknown application type for "${JSON.stringify(app)}".`);
+}

package/esm/loader/redirectLogic.d.ts

@@ -0,0 +1,30 @@
+import { type PluggableApplicationRegistryItem } from "@gooddata/sdk-model";
+import { type IPlatformContext } from "@gooddata/sdk-pluggable-application-model";
+/**
+ * Thrown when the current URL does not correspond to any accessible application.
+ */
+export declare class AppNotFoundError extends Error {
+    constructor(message: string);
+}
+export interface IResolveRedirectTargetOptions {
+    /**
+     * Fully permission-filtered apps (including workspace permissions).
+     * Used for mount validation and as the redirect target when workspace permissions are available.
+     */
+    apps: PluggableApplicationRegistryItem[];
+    ctx: IPlatformContext;
+    pathname: string;
+    /** Fetches the first workspace ID for the current user. */
+    fetchFirstWorkspaceId: () => Promise<string | undefined>;
+}
+/**
+ * Resolves where the shell app should navigate given the current URL and permission context.
+ *
+ * @returns
+ * - A URL string → caller must navigate to this URL (e.g. via React Router)
+ * - `null` → the current URL is valid; render the active app
+ *
+ * @throws {AppNotFoundError} The current path maps to no accessible application (show 404)
+ * @throws {Error} Unexpected failure (show generic error screen)
+ */
+export declare function resolveRedirectTarget({ apps, ctx, pathname, fetchFirstWorkspaceId }: IResolveRedirectTargetOptions): Promise<string | null>;