@openmrs/esm-extensions 10.0.1-pre.5255 → 10.0.1-pre.5263

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 11 files with swc (183.17ms)
+[0] Successfully compiled: 11 files with swc (123.7ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/render.d.ts

@@ -1,12 +1,35 @@
 /** @module @category Extension */
-import { type Parcel, type ParcelConfig } from 'single-spa';
+import { type AppProps, type CustomProps, type Parcel, type ParcelConfig, type ParcelProps } from 'single-spa';
 export interface CancelLoading {
     (): void;
 }
+type MountParcel = AppProps['mountParcel'];
+/**
+ * Mounts a parcel through the framework's host parcel, which lets single-spa release the parcel,
+ * its `domElement` and everything rendered into it once it unmounts. Prefer this to single-spa's
+ * `mountRootParcel()`, which retains all three for the lifetime of the page.
+ *
+ * @param parcelConfig The parcel config, or a function that loads one
+ * @param customProps The props to mount the parcel with, including the `domElement` to render into
+ * @returns The parcel handle; mounting completes with its `mountPromise`
+ */
+export declare function renderParcel<T = CustomProps>(parcelConfig: ParcelConfig, customProps: ParcelProps & T): Promise<ReturnType<MountParcel>>;
+/**
+ * Provides the equivalent of {@link renderParcel} for callers that need a `mountParcel()` they can
+ * call synchronously, single-spa-react's `<Parcel mountParcel={...} />` being the usual case.
+ *
+ * The parcel it returns is a stand-in until the real one exists, so its `getStatus()` reports
+ * `LOADING_SOURCE_CODE` rather than the real status for a short while after mounting. Prefer
+ * {@link renderParcel} wherever the caller can await it.
+ *
+ * @returns A `mountParcel()` that mounts through the host parcel
+ */
+export declare function createParcelMounter(): MountParcel;
 /**
  * Mounts into a DOM node (representing an extension slot)
  * a lazy-loaded component from *any* frontend module
  * that registered an extension component for this slot.
  */
 export declare function renderExtension(domElement: HTMLElement, extensionSlotName: string, extensionSlotModuleName: string, extensionId: string, renderFunction?: (application: ParcelConfig) => ParcelConfig, additionalProps?: Record<string, any>): Promise<Parcel | null>;
+export {};
 //# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,OAAO,EAAmB,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAK7E,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,CAAC;CACV;AAID;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,WAAW,EACvB,iBAAiB,EAAE,MAAM,EACzB,uBAAuB,EAAE,MAAM,EAC/B,WAAW,EAAE,MAAM,EACnB,cAAc,GAAE,CAAC,WAAW,EAAE,YAAY,KAAK,YAAuB,EACtE,eAAe,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GACxC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyDxB"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAKpB,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,CAAC;CACV;AAED,KAAK,WAAW,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;AAgD3C;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,WAAW,EAChD,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,WAAW,GAAG,CAAC,GAC3B,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAGlC;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,WAAW,CAEjD;AAoCD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,WAAW,EACvB,iBAAiB,EAAE,MAAM,EACzB,uBAAuB,EAAE,MAAM,EAC/B,WAAW,EAAE,MAAM,EACnB,cAAc,GAAE,CAAC,WAAW,EAAE,YAAY,KAAK,YAAuB,EACtE,eAAe,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GACxC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyDxB"}

package/dist/render.js

@@ -3,6 +3,96 @@ import { getExtensionNameFromId, getExtensionRegistration } from "./extensions.j
 import { checkStatus } from "./helpers.js";
 import { updateInternalExtensionStore } from "./store.js";
 let parcelCount = 0;
+let parcelMounter = null;
+/**
+ * Resolves the function used to mount extensions, which is the `mountParcel()` of a long-lived
+ * parcel of our own rather than single-spa's `mountRootParcel()`.
+ *
+ * single-spa only removes a parcel from its owner's registry when it unmounts if that owner has a
+ * name, and the internal object backing `mountRootParcel()` has none (fixed in single-spa 7).
+ * Anything mounted with it is therefore retained for the lifetime of the page, along with the
+ * `domElement` it was given and the whole subtree rendered into it. Extensions mounted through a
+ * named owner are pruned as they should be.
+ *
+ * The host parcel is mounted at most once, lazily, and never unmounted; if mounting it fails we
+ * fall back to `mountRootParcel()`, since leaking is better than not rendering.
+ */ function getParcelMounter() {
+    parcelMounter ?? (parcelMounter = new Promise((resolve, reject)=>{
+        const host = mountRootParcel({
+            name: 'openmrs-extension-host',
+            bootstrap: ()=>Promise.resolve(),
+            mount: (props)=>{
+                // single-spa types a parcel's lifecycle props as only the custom props it was mounted
+                // with, but they also carry the props single-spa itself injects, `mountParcel` included.
+                resolve(props.mountParcel);
+                return Promise.resolve();
+            },
+            unmount: ()=>Promise.resolve()
+        }, {
+            domElement: document.createElement('div')
+        });
+        host.mountPromise.catch(reject);
+    }).catch((err)=>{
+        console.error('The host parcel used to mount extensions could not be mounted. Falling back to mounting ' + 'extensions as root parcels, which leaks their DOM elements.', err);
+        return mountRootParcel;
+    }));
+    return parcelMounter;
+}
+/**
+ * Mounts a parcel through the framework's host parcel, which lets single-spa release the parcel,
+ * its `domElement` and everything rendered into it once it unmounts. Prefer this to single-spa's
+ * `mountRootParcel()`, which retains all three for the lifetime of the page.
+ *
+ * @param parcelConfig The parcel config, or a function that loads one
+ * @param customProps The props to mount the parcel with, including the `domElement` to render into
+ * @returns The parcel handle; mounting completes with its `mountPromise`
+ */ export async function renderParcel(parcelConfig, customProps) {
+    const mountParcel = await getParcelMounter();
+    return mountParcel(parcelConfig, customProps);
+}
+/**
+ * Provides the equivalent of {@link renderParcel} for callers that need a `mountParcel()` they can
+ * call synchronously, single-spa-react's `<Parcel mountParcel={...} />` being the usual case.
+ *
+ * The parcel it returns is a stand-in until the real one exists, so its `getStatus()` reports
+ * `LOADING_SOURCE_CODE` rather than the real status for a short while after mounting. Prefer
+ * {@link renderParcel} wherever the caller can await it.
+ *
+ * @returns A `mountParcel()` that mounts through the host parcel
+ */ export function createParcelMounter() {
+    return mountParcel;
+}
+/**
+ * Adapts the asynchronous `renderParcel()` to single-spa's synchronous `mountParcel()` signature,
+ * by returning an object that stands in for the parcel and forwards each call to the real one once
+ * it resolves. A caller that serialises its calls on `mountPromise`, as single-spa-react's
+ * `<Parcel>` does, never observes the stand-in; one that doesn't sees `getStatus()` report
+ * `LOADING_SOURCE_CODE` until the parcel is mounted, and an unmounted parcel's `update()` and
+ * `unmount()` deferred rather than rejected.
+ */ function mountParcel(config, props) {
+    let mounted;
+    const pending = renderParcel(config, props).then((parcel)=>mounted = parcel);
+    return {
+        mount: ()=>pending.then((parcel)=>parcel.mount()),
+        unmount: ()=>pending.then((parcel)=>parcel.unmount()),
+        update: (customProps)=>pending.then((parcel)=>parcel.update?.(customProps)),
+        getStatus: ()=>mounted?.getStatus() ?? 'LOADING_SOURCE_CODE',
+        // Derived lazily so a mount failure surfaces only on the promise the caller actually reads,
+        // instead of becoming an unhandled rejection on the ones it ignores.
+        get loadPromise () {
+            return pending.then((parcel)=>parcel.loadPromise);
+        },
+        get bootstrapPromise () {
+            return pending.then((parcel)=>parcel.bootstrapPromise);
+        },
+        get mountPromise () {
+            return pending.then((parcel)=>parcel.mountPromise);
+        },
+        get unmountPromise () {
+            return pending.then((parcel)=>parcel.unmountPromise);
+        }
+    };
+}
 /**
  * Mounts into a DOM node (representing an extension slot)
  * a lazy-loaded component from *any* frontend module
@@ -40,7 +130,7 @@ let parcelCount = 0;
             });
             const lifecycle = await load();
             const id = parcelCount++;
-            parcel = mountRootParcel(renderFunction({
+            parcel = await renderParcel(renderFunction({
                 ...lifecycle,
                 name: `${extensionSlotName}/${extensionName}-${id}`
             }), {

package/mock.ts

@@ -1,6 +1,5 @@
 import { vi } from 'vitest';
 import { getGlobalStore } from '@openmrs/esm-state/mock';
-import { type WorkspaceGroupRegistration, type WorkspaceRegistration } from '.';
 
 export const attach = vi.fn();
 export const detach = vi.fn();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-extensions",
-  "version": "10.0.1-pre.5255",
+  "version": "10.0.1-pre.5263",
   "license": "MPL-2.0",
   "description": "Coordinates extensions and extension points in the OpenMRS Frontend",
   "type": "module",
@@ -57,21 +57,21 @@
     "lodash-es": "^4.17.21"
   },
   "peerDependencies": {
-    "@openmrs/esm-api": "^10.0.1-pre.5255",
-    "@openmrs/esm-config": "^10.0.1-pre.5255",
-    "@openmrs/esm-expression-evaluator": "^10.0.1-pre.5255",
-    "@openmrs/esm-feature-flags": "^10.0.1-pre.5255",
-    "@openmrs/esm-state": "^10.0.1-pre.5255",
-    "@openmrs/esm-utils": "^10.0.1-pre.5255",
+    "@openmrs/esm-api": "^10.0.1-pre.5263",
+    "@openmrs/esm-config": "^10.0.1-pre.5263",
+    "@openmrs/esm-expression-evaluator": "^10.0.1-pre.5263",
+    "@openmrs/esm-feature-flags": "^10.0.1-pre.5263",
+    "@openmrs/esm-state": "^10.0.1-pre.5263",
+    "@openmrs/esm-utils": "^10.0.1-pre.5263",
     "single-spa": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "10.0.1-pre.5255",
-    "@openmrs/esm-config": "10.0.1-pre.5255",
-    "@openmrs/esm-expression-evaluator": "10.0.1-pre.5255",
-    "@openmrs/esm-feature-flags": "10.0.1-pre.5255",
-    "@openmrs/esm-state": "10.0.1-pre.5255",
-    "@openmrs/esm-utils": "10.0.1-pre.5255",
+    "@openmrs/esm-api": "10.0.1-pre.5263",
+    "@openmrs/esm-config": "10.0.1-pre.5263",
+    "@openmrs/esm-expression-evaluator": "10.0.1-pre.5263",
+    "@openmrs/esm-feature-flags": "10.0.1-pre.5263",
+    "@openmrs/esm-state": "10.0.1-pre.5263",
+    "@openmrs/esm-utils": "10.0.1-pre.5263",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@vitest/coverage-v8": "^4.1.2",

package/src/render.test.ts

@@ -0,0 +1,223 @@
+/* eslint-disable testing-library/render-result-naming-convention -- these tests render extensions, not components */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Parcel, ParcelConfig } from 'single-spa';
+
+const hostParcelName = 'openmrs-extension-host';
+
+vi.mock('single-spa', () => ({ mountRootParcel: vi.fn() }));
+
+vi.mock('./extensions', () => ({
+  getExtensionNameFromId: (extensionId: string) => extensionId,
+  getExtensionRegistration: () => ({
+    name: 'test-extension',
+    moduleName: 'test-module',
+    meta: {},
+    load: () => Promise.resolve(lifecycles),
+  }),
+}));
+
+vi.mock('./helpers', () => ({ checkStatus: () => true }));
+
+vi.mock('./store', () => ({ updateInternalExtensionStore: vi.fn() }));
+
+const lifecycles = {
+  bootstrap: () => Promise.resolve(),
+  mount: () => Promise.resolve(),
+  unmount: () => Promise.resolve(),
+};
+
+/**
+ * A stand-in for the external parcel representation single-spa returns. single-spa only provides
+ * `update()` for a config that has an update lifecycle, so `hasUpdate` allows omitting it.
+ */
+function fakeParcel({ hasUpdate = true } = {}): Parcel {
+  return {
+    mount: vi.fn(() => Promise.resolve()),
+    unmount: vi.fn(() => Promise.resolve()),
+    ...(hasUpdate ? { update: vi.fn(() => Promise.resolve()) } : {}),
+    getStatus: () => 'MOUNTED',
+    loadPromise: Promise.resolve(),
+    bootstrapPromise: Promise.resolve(),
+    mountPromise: Promise.resolve(),
+    unmountPromise: Promise.resolve(),
+  } as unknown as Parcel;
+}
+
+/**
+ * Loads a fresh copy of the module under test, which caches the host parcel's mounter in module
+ * scope, wired to a fake single-spa whose host parcel either mounts or fails to mount.
+ */
+async function loadRenderModule({ hostMountFails = false } = {}) {
+  vi.resetModules();
+
+  const { mountRootParcel } = await import('single-spa');
+  const hostMountParcel = vi.fn(() => fakeParcel());
+
+  vi.mocked(mountRootParcel).mockImplementation(((config: ParcelConfig, props: Record<string, unknown>) => {
+    if ('name' in config && config.name === hostParcelName) {
+      if (hostMountFails) {
+        return { ...fakeParcel(), mountPromise: Promise.reject(new Error('mount failed')) };
+      }
+
+      const mountPromise = Promise.resolve()
+        .then(() => (config as { bootstrap: (props: unknown) => Promise<void> }).bootstrap(props))
+        .then(() =>
+          (config as { mount: (props: unknown) => Promise<void> }).mount({ ...props, mountParcel: hostMountParcel }),
+        );
+
+      return { ...fakeParcel(), mountPromise };
+    }
+
+    return fakeParcel();
+  }) as typeof mountRootParcel);
+
+  const { createParcelMounter, renderExtension, renderParcel } = await import('./render');
+
+  const mountTestExtension = () =>
+    renderExtension(document.createElement('div'), 'test-slot', 'slot-module', 'test-extension#instance');
+
+  return {
+    mountRootParcel: vi.mocked(mountRootParcel),
+    hostMountParcel,
+    mountTestExtension,
+    renderParcel,
+    createParcelMounter,
+  };
+}
+
+describe('renderExtension', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  it('mounts extensions through the host parcel rather than as root parcels', async () => {
+    const { mountRootParcel, hostMountParcel, mountTestExtension } = await loadRenderModule();
+
+    const parcel = await mountTestExtension();
+
+    expect(hostMountParcel).toHaveBeenCalledTimes(1);
+    expect(parcel).toBe(hostMountParcel.mock.results[0].value);
+    expect(mountRootParcel).toHaveBeenCalledTimes(1);
+    expect(mountRootParcel).toHaveBeenCalledWith(
+      expect.objectContaining({ name: hostParcelName }),
+      expect.objectContaining({ domElement: expect.anything() }),
+    );
+  });
+
+  it('mounts the host parcel only once, including for concurrent renders', async () => {
+    const { mountRootParcel, hostMountParcel, mountTestExtension } = await loadRenderModule();
+
+    await Promise.all([mountTestExtension(), mountTestExtension(), mountTestExtension()]);
+    await mountTestExtension();
+
+    expect(mountRootParcel).toHaveBeenCalledTimes(1);
+    expect(hostMountParcel).toHaveBeenCalledTimes(4);
+  });
+
+  it('falls back to mounting root parcels if the host parcel cannot be mounted', async () => {
+    const { mountRootParcel, hostMountParcel, mountTestExtension } = await loadRenderModule({
+      hostMountFails: true,
+    });
+
+    const parcel = await mountTestExtension();
+
+    expect(parcel).not.toBeNull();
+    expect(hostMountParcel).not.toHaveBeenCalled();
+    expect(console.error).toHaveBeenCalled();
+    expect(mountRootParcel).toHaveBeenCalledTimes(2);
+    expect(mountRootParcel).toHaveBeenLastCalledWith(
+      expect.objectContaining({ name: 'test-slot/test-extension#instance-0' }),
+      expect.objectContaining({
+        _extensionContext: expect.objectContaining({ extensionId: 'test-extension#instance' }),
+      }),
+    );
+
+    // a second render must not retry mounting the host parcel
+    await mountTestExtension();
+    expect(mountRootParcel).toHaveBeenCalledTimes(3);
+  });
+});
+
+describe('renderParcel', () => {
+  it('mounts the parcel through the host parcel', async () => {
+    const { mountRootParcel, hostMountParcel, renderParcel } = await loadRenderModule();
+    const domElement = document.createElement('div');
+
+    const parcel = await renderParcel(lifecycles, { domElement, someProp: 'value' });
+
+    expect(hostMountParcel).toHaveBeenCalledWith(lifecycles, { domElement, someProp: 'value' });
+    expect(parcel).toBe(hostMountParcel.mock.results[0].value);
+    expect(mountRootParcel).toHaveBeenCalledTimes(1);
+    expect(mountRootParcel).toHaveBeenCalledWith(expect.objectContaining({ name: hostParcelName }), expect.anything());
+  });
+});
+
+describe('createParcelMounter', () => {
+  it('returns the parcel synchronously and forwards to the real parcel once it has mounted', async () => {
+    const { hostMountParcel, createParcelMounter } = await loadRenderModule();
+    const domElement = document.createElement('div');
+
+    const parcel = createParcelMounter()(lifecycles, { domElement });
+
+    // the host parcel's mounter is only resolved asynchronously, so nothing is mounted yet
+    expect(hostMountParcel).not.toHaveBeenCalled();
+    expect(parcel.getStatus()).toBe('LOADING_SOURCE_CODE');
+
+    await parcel.mountPromise;
+
+    expect(hostMountParcel).toHaveBeenCalledWith(lifecycles, { domElement });
+    expect(parcel.getStatus()).toBe('MOUNTED');
+  });
+
+  it('forwards update and unmount to the real parcel', async () => {
+    const { hostMountParcel, createParcelMounter } = await loadRenderModule();
+    const domElement = document.createElement('div');
+
+    const parcel = createParcelMounter()(lifecycles, { domElement });
+    await parcel.mountPromise;
+    await parcel.update?.({ domElement, someProp: 'value' });
+    await parcel.unmount();
+
+    const realParcel = hostMountParcel.mock.results[0].value;
+    expect(realParcel.update).toHaveBeenCalledWith({ domElement, someProp: 'value' });
+    expect(realParcel.unmount).toHaveBeenCalledTimes(1);
+    await expect(parcel.unmountPromise).resolves.toBeUndefined();
+  });
+
+  it('resolves update as a no-op if the real parcel has no update lifecycle', async () => {
+    const { hostMountParcel, createParcelMounter } = await loadRenderModule();
+    hostMountParcel.mockImplementationOnce(() => fakeParcel({ hasUpdate: false }));
+    const domElement = document.createElement('div');
+
+    const parcel = createParcelMounter()(lifecycles, { domElement });
+    await parcel.mountPromise;
+
+    await expect(parcel.update?.({ domElement })).resolves.toBeUndefined();
+  });
+
+  it('reports a failure to mount on mountPromise rather than throwing synchronously', async () => {
+    const { hostMountParcel, createParcelMounter } = await loadRenderModule();
+    hostMountParcel.mockImplementationOnce(() => {
+      throw new Error('parcel cannot be mounted without a domElement');
+    });
+
+    const parcel = createParcelMounter()(lifecycles, { domElement: document.createElement('div') });
+
+    await expect(parcel.mountPromise).rejects.toThrow('parcel cannot be mounted without a domElement');
+    // callers unmount only a MOUNTED parcel, so a parcel that never mounted must not claim to be
+    expect(parcel.getStatus()).not.toBe('MOUNTED');
+  });
+
+  it('mounts through the same host parcel as renderParcel', async () => {
+    const { mountRootParcel, hostMountParcel, renderParcel, createParcelMounter } = await loadRenderModule();
+    const domElement = document.createElement('div');
+
+    await Promise.all([
+      renderParcel(lifecycles, { domElement }),
+      createParcelMounter()(lifecycles, { domElement }).mountPromise,
+    ]);
+
+    expect(mountRootParcel).toHaveBeenCalledTimes(1);
+    expect(hostMountParcel).toHaveBeenCalledTimes(2);
+  });
+});

package/src/render.ts

@@ -1,5 +1,12 @@
 /** @module @category Extension */
-import { mountRootParcel, type Parcel, type ParcelConfig } from 'single-spa';
+import {
+  mountRootParcel,
+  type AppProps,
+  type CustomProps,
+  type Parcel,
+  type ParcelConfig,
+  type ParcelProps,
+} from 'single-spa';
 import { getExtensionNameFromId, getExtensionRegistration } from './extensions';
 import { checkStatus } from './helpers';
 import { updateInternalExtensionStore } from './store';
@@ -8,7 +15,118 @@ export interface CancelLoading {
   (): void;
 }
 
+type MountParcel = AppProps['mountParcel'];
+
 let parcelCount = 0;
+let parcelMounter: Promise<MountParcel> | null = null;
+
+/**
+ * Resolves the function used to mount extensions, which is the `mountParcel()` of a long-lived
+ * parcel of our own rather than single-spa's `mountRootParcel()`.
+ *
+ * single-spa only removes a parcel from its owner's registry when it unmounts if that owner has a
+ * name, and the internal object backing `mountRootParcel()` has none (fixed in single-spa 7).
+ * Anything mounted with it is therefore retained for the lifetime of the page, along with the
+ * `domElement` it was given and the whole subtree rendered into it. Extensions mounted through a
+ * named owner are pruned as they should be.
+ *
+ * The host parcel is mounted at most once, lazily, and never unmounted; if mounting it fails we
+ * fall back to `mountRootParcel()`, since leaking is better than not rendering.
+ */
+function getParcelMounter(): Promise<MountParcel> {
+  parcelMounter ??= new Promise<MountParcel>((resolve, reject) => {
+    const host = mountRootParcel(
+      {
+        name: 'openmrs-extension-host',
+        bootstrap: () => Promise.resolve(),
+        mount: (props) => {
+          // single-spa types a parcel's lifecycle props as only the custom props it was mounted
+          // with, but they also carry the props single-spa itself injects, `mountParcel` included.
+          resolve((props as unknown as AppProps).mountParcel);
+          return Promise.resolve();
+        },
+        unmount: () => Promise.resolve(),
+      },
+      { domElement: document.createElement('div') },
+    );
+
+    host.mountPromise.catch(reject);
+  }).catch((err) => {
+    console.error(
+      'The host parcel used to mount extensions could not be mounted. Falling back to mounting ' +
+        'extensions as root parcels, which leaks their DOM elements.',
+      err,
+    );
+    return mountRootParcel;
+  });
+
+  return parcelMounter;
+}
+
+/**
+ * Mounts a parcel through the framework's host parcel, which lets single-spa release the parcel,
+ * its `domElement` and everything rendered into it once it unmounts. Prefer this to single-spa's
+ * `mountRootParcel()`, which retains all three for the lifetime of the page.
+ *
+ * @param parcelConfig The parcel config, or a function that loads one
+ * @param customProps The props to mount the parcel with, including the `domElement` to render into
+ * @returns The parcel handle; mounting completes with its `mountPromise`
+ */
+export async function renderParcel<T = CustomProps>(
+  parcelConfig: ParcelConfig,
+  customProps: ParcelProps & T,
+): Promise<ReturnType<MountParcel>> {
+  const mountParcel = await getParcelMounter();
+  return mountParcel(parcelConfig, customProps);
+}
+
+/**
+ * Provides the equivalent of {@link renderParcel} for callers that need a `mountParcel()` they can
+ * call synchronously, single-spa-react's `<Parcel mountParcel={...} />` being the usual case.
+ *
+ * The parcel it returns is a stand-in until the real one exists, so its `getStatus()` reports
+ * `LOADING_SOURCE_CODE` rather than the real status for a short while after mounting. Prefer
+ * {@link renderParcel} wherever the caller can await it.
+ *
+ * @returns A `mountParcel()` that mounts through the host parcel
+ */
+export function createParcelMounter(): MountParcel {
+  return mountParcel;
+}
+
+/**
+ * Adapts the asynchronous `renderParcel()` to single-spa's synchronous `mountParcel()` signature,
+ * by returning an object that stands in for the parcel and forwards each call to the real one once
+ * it resolves. A caller that serialises its calls on `mountPromise`, as single-spa-react's
+ * `<Parcel>` does, never observes the stand-in; one that doesn't sees `getStatus()` report
+ * `LOADING_SOURCE_CODE` until the parcel is mounted, and an unmounted parcel's `update()` and
+ * `unmount()` deferred rather than rejected.
+ */
+function mountParcel(config: ParcelConfig, props: ParcelProps & CustomProps): Parcel {
+  let mounted: Parcel | undefined;
+  const pending = renderParcel(config, props).then((parcel) => (mounted = parcel));
+
+  return {
+    mount: () => pending.then((parcel) => parcel.mount()),
+    unmount: () => pending.then((parcel) => parcel.unmount()),
+    update: (customProps) => pending.then((parcel) => parcel.update?.(customProps)),
+    getStatus: () => mounted?.getStatus() ?? 'LOADING_SOURCE_CODE',
+    // Derived lazily so a mount failure surfaces only on the promise the caller actually reads,
+    // instead of becoming an unhandled rejection on the ones it ignores.
+    get loadPromise() {
+      return pending.then((parcel) => parcel.loadPromise);
+    },
+    get bootstrapPromise() {
+      return pending.then((parcel) => parcel.bootstrapPromise);
+    },
+    get mountPromise() {
+      return pending.then((parcel) => parcel.mountPromise);
+    },
+    get unmountPromise() {
+      return pending.then((parcel) => parcel.unmountPromise);
+    },
+  };
+}
 
 /**
  * Mounts into a DOM node (representing an extension slot)
@@ -56,7 +174,7 @@ export async function renderExtension(
 
       const lifecycle = await load();
       const id = parcelCount++;
-      parcel = mountRootParcel(
+      parcel = await renderParcel(
         renderFunction({
           ...lifecycle,
           name: `${extensionSlotName}/${extensionName}-${id}`,