@openmrs/esm-extensions 10.0.1-pre.5393 → 10.0.1-pre.5396

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 11 files with swc (135.83ms)
+[0] Successfully compiled: 11 files with swc (155.99ms)
 [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.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,WAAW,EAEhB,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;AAwJ3C;;;;;;;;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,CAsGxB"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,WAAW,EAEhB,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;AAyR3C;;;;;;;;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,CAQlC;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,CAsGxB"}

package/dist/render.js

@@ -32,11 +32,100 @@ let parcelMounter = null;
                 return isPromiseLike(result) ? result : Promise.reject(new Error(`Lifecycle function ${which} at array index ${index} for parcel ${name} did not return a promise`));
             }), Promise.resolve(undefined));
 }
+/**
+ * Empties the props object single-spa is holding for a parcel.
+ *
+ * If a parcel's `unmount()` rejects, single-spa retains it in the `SKIP_BECAUSE_BROKEN` state,
+ * including holding on to the props, which can include the DOM node if it was successfully
+ * mounted. Since we hand single-spa the props, we can clear that object here which helps reduce
+ * the memory pressure of the retained parcels
+ */ function releaseProps(props) {
+    for (const key of Object.keys(props)){
+        delete props[key];
+    }
+}
+/**
+ * Watches a parcel's lifecycles and releases its props once single-spa has no further use for them,
+ * which is only ever after a failure: a parcel that unmounts cleanly is dropped by single-spa
+ * itself, taking its props with it.
+ *
+ * The timing matters, because single-spa keeps calling lifecycles past the failure that broke the
+ * parcel and they are handed these same props.
+ *
+ * Which object gets released moves over the parcel's life, since `update()` replaces the props
+ * single-spa holds rather than merging into them. See {@link trackUpdates}.
+ *
+ * @param props The object single-spa was mounted with, which must not be the caller's own
+ */ function trackProps(props) {
+    let tracked = props;
+    let mountFailed = false;
+    const release = ()=>releaseProps(tracked);
+    return {
+        retarget (next) {
+            tracked = {
+                ...next
+            };
+            return tracked;
+        },
+        release,
+        onSettled (which, failed) {
+            switch(which){
+                case 'bootstrap':
+                    // single-spa breaks the parcel there and then, without calling anything else.
+                    if (failed) {
+                        release();
+                    }
+                    return;
+                case 'mount':
+                    // A parcel whose mount fails is unmounted before it is broken, so that the extension gets
+                    // to tear down whatever it managed to render. The release waits for that unmount.
+                    mountFailed || (mountFailed = failed);
+                    return;
+                case 'unmount':
+                    if (failed || mountFailed) {
+                        release();
+                    }
+                    return;
+            }
+        }
+    };
+}
+/**
+ * Points a parcel's `update()` at a copy of the props it is given, which {@link trackProps} then
+ * follows in place of the ones the parcel was mounted with.
+ *
+ * single-spa's `update()` assigns the props it is given over the ones it holds, so without this a
+ * later failure would empty the mount-time copy while single-spa kept the updated one — which, for
+ * the workspaces' `<Parcel>`, carries the `domElement` and everything rendered into it.
+ *
+ * single-spa attaches `update()` to the parcel only once its config has loaded, and only for a
+ * config that has an update lifecycle, so this intercepts the assignment rather than the method:
+ * callers such as `<Extension>` read `update` to decide whether the parcel can be updated at all.
+ */ function trackUpdates(parcel, tracker) {
+    const wrap = (update)=>(customProps)=>update.call(parcel, tracker.retarget(customProps)).catch((err)=>{
+                if (parcel.getStatus() === 'SKIP_BECAUSE_BROKEN') {
+                    tracker.release();
+                }
+                throw err;
+            });
+    let tracked = parcel.update && wrap(parcel.update);
+    return Object.defineProperty(parcel, 'update', {
+        configurable: true,
+        enumerable: true,
+        get: ()=>tracked,
+        set: (update)=>{
+            tracked = update && wrap(update);
+        }
+    });
+}
 /**
  * Wraps a lifecycle so that it rejects once `millis` have elapsed, clearing the timer as soon as it
  * settles either way. Rejecting puts the parcel into the same broken state single-spa's own
  * `dieOnTimeout` would, but without leaving a timer holding the parcel for the full deadline.
- */ function withDeadline(lifecycle, millis, name, which) {
+ *
+ * Reporting each outcome to `onSettled` from here rather than from the parcel's own promises leaves
+ * a rejection no caller handles free to reach the global unhandled rejection handler.
+ */ function withDeadline(lifecycle, millis, name, which, onSettled) {
     const run = toSingleFn(lifecycle, name, which);
     return (props)=>{
         let timer;
@@ -46,10 +135,16 @@ let parcelMounter = null;
         return Promise.race([
             run(props),
             deadline
-        ]).finally(()=>clearTimeout(timer));
+        ]).finally(()=>clearTimeout(timer)).then((value)=>{
+            onSettled(which, false);
+            return value;
+        }, (err)=>{
+            onSettled(which, true);
+            throw err;
+        });
     };
 }
-/** Applies {@link lifecycleDeadlines} to a resolved parcel config. */ function boundLifecycles(parcelConfig) {
+/** Applies {@link lifecycleDeadlines} to a resolved parcel config. */ function boundLifecycles(parcelConfig, onSettled) {
     // A parcel that declares its own timeouts is bounding itself, so it is left to single-spa.
     if (parcelConfig.timeouts) {
         return parcelConfig;
@@ -57,7 +152,7 @@ let parcelMounter = null;
     const name = parcelConfig.name ?? 'parcel';
     const bounded = Object.fromEntries(Object.keys(lifecycleDeadlines).filter((which)=>parcelConfig[which]).map((which)=>[
             which,
-            withDeadline(parcelConfig[which], lifecycleDeadlines[which], name, which)
+            withDeadline(parcelConfig[which], lifecycleDeadlines[which], name, which, onSettled)
         ]));
     return {
         ...parcelConfig,
@@ -67,11 +162,11 @@ let parcelMounter = null;
 /**
  * Applies {@link boundLifecycles} to a parcel config, resolving the function form first so that a
  * lazily loaded config gets the deadlines too.
- */ function withLifecycleDeadlines(parcelConfig) {
+ */ function withLifecycleDeadlines(parcelConfig, onSettled) {
     if (typeof parcelConfig === 'function') {
-        return ()=>parcelConfig().then(boundLifecycles);
+        return ()=>parcelConfig().then((resolved)=>boundLifecycles(resolved, onSettled));
     }
-    return boundLifecycles(parcelConfig);
+    return boundLifecycles(parcelConfig, onSettled);
 }
 /**
  * Resolves the function used to mount extensions, which is the `mountParcel()` of a long-lived
@@ -117,7 +212,13 @@ let parcelMounter = null;
  * @returns The parcel handle; mounting completes with its `mountPromise`
  */ export async function renderParcel(parcelConfig, customProps) {
     const mountParcel = await getParcelMounter();
-    return mountParcel(withLifecycleDeadlines(parcelConfig), customProps);
+    // Copied because single-spa holds onto this object for as long as it holds the parcel, and
+    // {@link releaseProps} empties it; the caller's own object is unchanged.
+    const props = {
+        ...customProps
+    };
+    const tracker = trackProps(props);
+    return trackUpdates(mountParcel(withLifecycleDeadlines(parcelConfig, tracker.onSettled), props), tracker);
 }
 /**
  * Provides the equivalent of {@link renderParcel} for callers that need a `mountParcel()` they can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-extensions",
-  "version": "10.0.1-pre.5393",
+  "version": "10.0.1-pre.5396",
   "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.5393",
-    "@openmrs/esm-config": "^10.0.1-pre.5393",
-    "@openmrs/esm-expression-evaluator": "^10.0.1-pre.5393",
-    "@openmrs/esm-feature-flags": "^10.0.1-pre.5393",
-    "@openmrs/esm-state": "^10.0.1-pre.5393",
-    "@openmrs/esm-utils": "^10.0.1-pre.5393",
+    "@openmrs/esm-api": "^10.0.1-pre.5396",
+    "@openmrs/esm-config": "^10.0.1-pre.5396",
+    "@openmrs/esm-expression-evaluator": "^10.0.1-pre.5396",
+    "@openmrs/esm-feature-flags": "^10.0.1-pre.5396",
+    "@openmrs/esm-state": "^10.0.1-pre.5396",
+    "@openmrs/esm-utils": "^10.0.1-pre.5396",
     "single-spa": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "10.0.1-pre.5393",
-    "@openmrs/esm-config": "10.0.1-pre.5393",
-    "@openmrs/esm-expression-evaluator": "10.0.1-pre.5393",
-    "@openmrs/esm-feature-flags": "10.0.1-pre.5393",
-    "@openmrs/esm-state": "10.0.1-pre.5393",
-    "@openmrs/esm-utils": "10.0.1-pre.5393",
+    "@openmrs/esm-api": "10.0.1-pre.5396",
+    "@openmrs/esm-config": "10.0.1-pre.5396",
+    "@openmrs/esm-expression-evaluator": "10.0.1-pre.5396",
+    "@openmrs/esm-feature-flags": "10.0.1-pre.5396",
+    "@openmrs/esm-state": "10.0.1-pre.5396",
+    "@openmrs/esm-utils": "10.0.1-pre.5396",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@vitest/coverage-v8": "^4.1.2",

package/src/render.single-spa.test.ts

@@ -17,6 +17,11 @@ function goodLifecycles(): LifeCycles {
   };
 }
 
+/** The `domElement` a lifecycle was handed, which is whichever props single-spa held at the time. */
+function elementOf(props: unknown) {
+  return (props as { domElement?: HTMLElement }).domElement;
+}
+
 afterEach(() => {
   vi.restoreAllMocks();
 });
@@ -28,10 +33,40 @@ describe('renderParcel against the real single-spa', () => {
     await parcel.mountPromise;
     expect(parcel.getStatus()).toBe('MOUNTED');
 
+    // single-spa leaves `update` off a parcel whose config has no update lifecycle, and `<Extension>`
+    // reads it to decide whether the parcel can be updated at all.
+    expect(parcel.update).toBeUndefined();
+
     await parcel.unmount();
     expect(parcel.getStatus()).toBe('NOT_MOUNTED');
   });
 
+  it('leaves the props intact for the unmount single-spa runs after a failed mount', async () => {
+    const domElement = document.createElement('div');
+    const callerProps = { domElement };
+    const unmountedWith: Array<unknown> = [];
+
+    const parcel = await renderParcel(
+      {
+        ...goodLifecycles(),
+        mount: () => Promise.reject(new Error('mount failed')),
+        unmount: (props) => {
+          unmountedWith.push((props as { domElement?: HTMLElement }).domElement);
+          return Promise.resolve();
+        },
+      },
+      callerProps,
+    );
+
+    await expect(parcel.mountPromise).rejects.toThrow(/mount failed/);
+
+    // single-spa unmounts a parcel whose mount failed so the extension can tear down whatever it
+    // rendered, so the props it retains cannot be released until that unmount has had them.
+    expect(unmountedWith).toEqual([domElement]);
+    expect(parcel.getStatus()).toBe('SKIP_BECAUSE_BROKEN');
+    expect(callerProps).toEqual({ domElement });
+  });
+
   it('breaks a parcel whose mount does not return a promise', async () => {
     // single-spa would fail this parcel on its own; the deadline wrapper has to not paper over it.
     const lifecycles = { ...goodLifecycles(), mount: (() => undefined) as never };
@@ -58,6 +93,95 @@ describe('renderParcel against the real single-spa', () => {
     expect(parcel.getStatus()).toBe('SKIP_BECAUSE_BROKEN');
   });
 
+  it('hands the props of the latest update to the unmount that breaks the parcel', async () => {
+    const mounted = document.createElement('div');
+    const updated = document.createElement('div');
+    const callerProps = { domElement: updated, someProp: 'updated' };
+    const unmountedWith: Array<HTMLElement | undefined> = [];
+
+    const parcel = await renderParcel(
+      {
+        ...goodLifecycles(),
+        update: () => Promise.resolve(),
+        unmount: (props) => {
+          unmountedWith.push(elementOf(props));
+          return Promise.reject(new Error('unmount failed'));
+        },
+      },
+      { domElement: mounted },
+    );
+
+    await parcel.mountPromise;
+    await parcel.update?.(callerProps);
+
+    // single-spa rejects `unmountPromise` separately from the call, so both are asserted against.
+    const brokeUnmount = expect(parcel.unmountPromise).rejects.toThrow(/unmount failed/);
+    await expect(parcel.unmount()).rejects.toThrow(/unmount failed/);
+    await brokeUnmount;
+
+    // single-spa assigns the props of an update over the ones it holds rather than merging into
+    // them, so from here on it is the updated copy that a failure has to empty, and the mount-time
+    // copy that nothing is holding.
+    expect(unmountedWith).toEqual([updated]);
+    expect(parcel.getStatus()).toBe('SKIP_BECAUSE_BROKEN');
+    expect(callerProps).toEqual({ domElement: updated, someProp: 'updated' });
+  });
+
+  it('breaks a parcel whose update lifecycle fails', async () => {
+    const domElement = document.createElement('div');
+    const updatedWith: Array<HTMLElement | undefined> = [];
+
+    const parcel = await renderParcel(
+      {
+        ...goodLifecycles(),
+        update: (props) => {
+          updatedWith.push(elementOf(props));
+          return Promise.reject(new Error('update failed'));
+        },
+      },
+      { domElement },
+    );
+
+    await parcel.mountPromise;
+    await expect(parcel.update?.({ domElement })).rejects.toThrow(/update failed/);
+
+    // Nothing follows this: single-spa neither unmounts the parcel nor runs another lifecycle, so
+    // the props it is left holding are the ones the failed update swapped in.
+    expect(updatedWith).toEqual([domElement]);
+    expect(parcel.getStatus()).toBe('SKIP_BECAUSE_BROKEN');
+  });
+
+  it('keeps the props of an update rejected on an unmounted parcel for its next mount', async () => {
+    const mounted = document.createElement('div');
+    const updated = document.createElement('div');
+    const mountedWith: Array<HTMLElement | undefined> = [];
+
+    const parcel = await renderParcel(
+      {
+        ...goodLifecycles(),
+        update: () => Promise.resolve(),
+        mount: (props) => {
+          mountedWith.push(elementOf(props));
+          return Promise.resolve();
+        },
+      },
+      { domElement: mounted },
+    );
+
+    await parcel.mountPromise;
+    await parcel.unmount();
+
+    // single-spa swaps the props in before it checks the status, so this rejection still leaves it
+    // holding them — and a parcel that is merely unmounted can be mounted again.
+    await expect(parcel.update?.({ domElement: updated })).rejects.toThrow(/not mounted/);
+    expect(parcel.getStatus()).toBe('NOT_MOUNTED');
+
+    await parcel.mount();
+
+    expect(parcel.getStatus()).toBe('MOUNTED');
+    expect(mountedWith).toEqual([mounted, updated]);
+  });
+
   it('breaks a parcel whose mount overruns its deadline', async () => {
     vi.useFakeTimers();
 

package/src/render.test.ts

@@ -56,6 +56,16 @@ function fakeParcel({ hasUpdate = true } = {}): Parcel {
   } as unknown as Parcel;
 }
 
+/**
+ * A fake parcel paired with its own `update` mock. `renderParcel()` replaces `update` on the parcel
+ * it is given, so this is the only way left to see the props single-spa was actually handed.
+ */
+function fakeParcelWithUpdate() {
+  const update = vi.fn((_: Record<string, unknown>) => Promise.resolve());
+
+  return { parcel: { ...fakeParcel(), update } as unknown as Parcel, update };
+}
+
 /**
  * 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.
@@ -357,6 +367,169 @@ describe('renderParcel', () => {
     );
   });
 
+  it('holds the props single-spa retains until the unmount that follows a failed mount', async () => {
+    const { hostMountParcel, renderParcel } = await loadRenderModule();
+    const domElement = document.createElement('div');
+    const callerProps = { domElement, someProp: 'value' };
+    const failure = new Error('mount failed');
+
+    await renderParcel({ ...lifecycles, mount: () => Promise.reject(failure) }, callerProps);
+
+    const [bounded, retained] = hostMountParcel.mock.calls[0] as [typeof lifecycles, Record<string, unknown>];
+
+    await expect(bounded.mount({ domElement })).rejects.toBe(failure);
+
+    // single-spa unmounts a parcel whose mount failed before breaking it, and hands that unmount
+    // these props, so releasing them any earlier would deny the extension its own cleanup.
+    expect(retained).toEqual({ domElement, someProp: 'value' });
+
+    await bounded.unmount({ domElement });
+
+    // single-spa keeps a broken parcel, and with it these props, for the lifetime of the page, so
+    // emptying them is the only way to stop it retaining the element and everything rendered into it.
+    expect(retained).toEqual({});
+    expect(callerProps).toEqual({ domElement, someProp: 'value' });
+  });
+
+  it('empties the retained props as soon as bootstrap fails', async () => {
+    const { hostMountParcel, renderParcel } = await loadRenderModule();
+    const domElement = document.createElement('div');
+    const failure = new Error('bootstrap failed');
+
+    await renderParcel({ ...lifecycles, bootstrap: () => Promise.reject(failure) }, { domElement });
+
+    const [bounded, retained] = hostMountParcel.mock.calls[0] as [typeof lifecycles, Record<string, unknown>];
+
+    // Nothing follows a failed bootstrap, so there is no later lifecycle to hold the props for.
+    await expect(bounded.bootstrap({ domElement })).rejects.toBe(failure);
+
+    expect(retained).toEqual({});
+  });
+
+  it('empties the retained props when unmount fails', async () => {
+    const { hostMountParcel, renderParcel } = await loadRenderModule();
+    const domElement = document.createElement('div');
+    const failure = new Error('unmount failed');
+
+    await renderParcel({ ...lifecycles, unmount: () => Promise.reject(failure) }, { domElement });
+
+    const [bounded, retained] = hostMountParcel.mock.calls[0] as [typeof lifecycles, Record<string, unknown>];
+
+    await bounded.mount({ domElement });
+    await expect(bounded.unmount({ domElement })).rejects.toBe(failure);
+
+    expect(retained).toEqual({});
+  });
+
+  it('empties the retained props when a lifecycle overruns its deadline', async () => {
+    vi.useFakeTimers();
+
+    try {
+      const { hostMountParcel, renderParcel } = await loadRenderModule();
+      const domElement = document.createElement('div');
+
+      await renderParcel({ ...lifecycles, unmount: () => new Promise(() => {}) }, { domElement });
+
+      const [hung, retained] = hostMountParcel.mock.calls[0] as [typeof lifecycles, Record<string, unknown>];
+
+      await hung.mount({ domElement });
+
+      // Asserted against before the clock is advanced, so the rejection is never unhandled.
+      const overran = expect(hung.unmount({ domElement })).rejects.toThrow(/did not settle within 15000ms/);
+      await vi.advanceTimersByTimeAsync(15_000);
+      await overran;
+
+      expect(retained).toEqual({});
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('leaves the retained props alone while the parcel is healthy', async () => {
+    const { hostMountParcel, renderParcel } = await loadRenderModule();
+    const domElement = document.createElement('div');
+
+    await renderParcel(lifecycles, { domElement });
+
+    const [bounded, retained] = hostMountParcel.mock.calls[0] as [typeof lifecycles, Record<string, unknown>];
+
+    await bounded.mount({ domElement });
+    await bounded.unmount({ domElement });
+
+    expect(retained).toEqual({ domElement });
+  });
+
+  it('tracks a copy of the props update() replaces the retained ones with', async () => {
+    const { hostMountParcel, renderParcel } = await loadRenderModule();
+    const domElement = document.createElement('div');
+    const updatedElement = document.createElement('div');
+    const callerProps = { domElement: updatedElement, someProp: 'updated' };
+    const failure = new Error('unmount failed');
+
+    const { parcel: hosted, update } = fakeParcelWithUpdate();
+
+    hostMountParcel.mockImplementationOnce(() => hosted);
+
+    const parcel = await renderParcel({ ...lifecycles, unmount: () => Promise.reject(failure) }, { domElement });
+    const [bounded] = hostMountParcel.mock.calls[0] as [typeof lifecycles, Record<string, unknown>];
+
+    await parcel.update?.(callerProps);
+
+    // single-spa assigns these over the props it holds rather than merging into them, so it is this
+    // copy — the one carrying the updated `domElement` — that a failure has to empty.
+    const [retained] = update.mock.calls[0];
+    expect(retained).toEqual(callerProps);
+    expect(retained).not.toBe(callerProps);
+
+    await bounded.mount({ domElement });
+    await expect(bounded.unmount({ domElement })).rejects.toBe(failure);
+
+    expect(retained).toEqual({});
+    expect(callerProps).toEqual({ domElement: updatedElement, someProp: 'updated' });
+  });
+
+  it('empties the props of an update that leaves the parcel broken', async () => {
+    const { hostMountParcel, renderParcel } = await loadRenderModule();
+    const domElement = document.createElement('div');
+    const failure = new Error('update failed');
+
+    const { parcel: hosted, update } = fakeParcelWithUpdate();
+
+    hostMountParcel.mockImplementationOnce(() => hosted);
+
+    const parcel = await renderParcel(lifecycles, { domElement });
+
+    update.mockImplementationOnce(() => Promise.reject(failure));
+    vi.spyOn(hosted, 'getStatus').mockReturnValue('SKIP_BECAUSE_BROKEN');
+
+    await expect(parcel.update?.({ domElement })).rejects.toBe(failure);
+
+    // A broken parcel never runs another lifecycle, so nothing later would release these.
+    const [retained] = update.mock.calls[0];
+    expect(retained).toEqual({});
+  });
+
+  it('keeps the props of an update rejected because the parcel is not mounted', async () => {
+    const { hostMountParcel, renderParcel } = await loadRenderModule();
+    const domElement = document.createElement('div');
+    const failure = new Error('Cannot update parcel because it is not mounted');
+
+    const { parcel: hosted, update } = fakeParcelWithUpdate();
+
+    hostMountParcel.mockImplementationOnce(() => hosted);
+
+    const parcel = await renderParcel(lifecycles, { domElement });
+
+    update.mockImplementationOnce(() => Promise.reject(failure));
+    vi.spyOn(hosted, 'getStatus').mockReturnValue('NOT_MOUNTED');
+
+    await expect(parcel.update?.({ domElement, someProp: 'value' })).rejects.toBe(failure);
+
+    // These are the props a remount would use, and an unmounted parcel can still be mounted again.
+    const [retained] = update.mock.calls[0];
+    expect(retained).toEqual({ domElement, someProp: 'value' });
+  });
+
   it('leaves a parcel that declares its own timeouts to single-spa', async () => {
     const { hostMountParcel, renderParcel } = await loadRenderModule();
     const domElement = document.createElement('div');
@@ -389,14 +562,17 @@ describe('createParcelMounter', () => {
     const { hostMountParcel, createParcelMounter } = await loadRenderModule();
     const domElement = document.createElement('div');
 
+    const { parcel: hosted, update } = fakeParcelWithUpdate();
+
+    hostMountParcel.mockImplementationOnce(() => hosted);
+
     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);
+    expect(update).toHaveBeenCalledWith({ domElement, someProp: 'value' });
+    expect(hosted.unmount).toHaveBeenCalledTimes(1);
     await expect(parcel.unmountPromise).resolves.toBeUndefined();
   });
 

package/src/render.ts

@@ -25,6 +25,19 @@ type ParcelConfigObject = Extract<ParcelConfig, LifeCycles>;
 type LifecycleFn = Exclude<LifeCycles['mount'], readonly unknown[]>;
 type LifecycleName = keyof typeof lifecycleDeadlines;
 
+/** Reports how one of a parcel's lifecycles settled. */
+type LifecycleSettled = (which: LifecycleName, failed: boolean) => void;
+
+/** Follows the props object single-spa holds for a parcel, so it can be emptied on failure. */
+interface PropsTracker {
+  /** Reports how one of the parcel's lifecycles settled. */
+  onSettled: LifecycleSettled;
+  /** Tracks a copy of `next` in place of the props tracked so far, and returns it to pass on. */
+  retarget(next: Record<string, unknown>): Record<string, unknown>;
+  /** Empties the tracked props. */
+  release(): void;
+}
+
 /**
  * How long each lifecycle gets before the parcel is marked dead. Loading and unloading are left
  * out, as their timing is unpredictable. These are meant to be generous.
@@ -70,16 +83,121 @@ function toSingleFn(lifecycle: LifecycleFn | Array<LifecycleFn>, name: string, w
     );
 }
 
+/**
+ * Empties the props object single-spa is holding for a parcel.
+ *
+ * If a parcel's `unmount()` rejects, single-spa retains it in the `SKIP_BECAUSE_BROKEN` state,
+ * including holding on to the props, which can include the DOM node if it was successfully
+ * mounted. Since we hand single-spa the props, we can clear that object here which helps reduce
+ * the memory pressure of the retained parcels
+ */
+function releaseProps(props: Record<string, unknown>) {
+  for (const key of Object.keys(props)) {
+    delete props[key];
+  }
+}
+
+/**
+ * Watches a parcel's lifecycles and releases its props once single-spa has no further use for them,
+ * which is only ever after a failure: a parcel that unmounts cleanly is dropped by single-spa
+ * itself, taking its props with it.
+ *
+ * The timing matters, because single-spa keeps calling lifecycles past the failure that broke the
+ * parcel and they are handed these same props.
+ *
+ * Which object gets released moves over the parcel's life, since `update()` replaces the props
+ * single-spa holds rather than merging into them. See {@link trackUpdates}.
+ *
+ * @param props The object single-spa was mounted with, which must not be the caller's own
+ */
+function trackProps(props: Record<string, unknown>): PropsTracker {
+  let tracked = props;
+  let mountFailed = false;
+  const release = () => releaseProps(tracked);
+
+  return {
+    retarget(next) {
+      tracked = { ...next };
+
+      return tracked;
+    },
+    release,
+    onSettled(which, failed) {
+      switch (which) {
+        case 'bootstrap':
+          // single-spa breaks the parcel there and then, without calling anything else.
+          if (failed) {
+            release();
+          }
+
+          return;
+        case 'mount':
+          // A parcel whose mount fails is unmounted before it is broken, so that the extension gets
+          // to tear down whatever it managed to render. The release waits for that unmount.
+          mountFailed ||= failed;
+
+          return;
+        case 'unmount':
+          if (failed || mountFailed) {
+            release();
+          }
+
+          return;
+      }
+    },
+  };
+}
+
+/**
+ * Points a parcel's `update()` at a copy of the props it is given, which {@link trackProps} then
+ * follows in place of the ones the parcel was mounted with.
+ *
+ * single-spa's `update()` assigns the props it is given over the ones it holds, so without this a
+ * later failure would empty the mount-time copy while single-spa kept the updated one — which, for
+ * the workspaces' `<Parcel>`, carries the `domElement` and everything rendered into it.
+ *
+ * single-spa attaches `update()` to the parcel only once its config has loaded, and only for a
+ * config that has an update lifecycle, so this intercepts the assignment rather than the method:
+ * callers such as `<Extension>` read `update` to decide whether the parcel can be updated at all.
+ */
+function trackUpdates(parcel: Parcel, tracker: PropsTracker): Parcel {
+  const wrap =
+    (update: NonNullable<Parcel['update']>): Parcel['update'] =>
+    (customProps) =>
+      update.call(parcel, tracker.retarget(customProps)).catch((err: unknown) => {
+        if (parcel.getStatus() === 'SKIP_BECAUSE_BROKEN') {
+          tracker.release();
+        }
+
+        throw err;
+      });
+
+  let tracked = parcel.update && wrap(parcel.update);
+
+  return Object.defineProperty(parcel, 'update', {
+    configurable: true,
+    enumerable: true,
+    get: () => tracked,
+    set: (update: Parcel['update']) => {
+      tracked = update && wrap(update);
+    },
+  });
+}
+
 /**
  * Wraps a lifecycle so that it rejects once `millis` have elapsed, clearing the timer as soon as it
  * settles either way. Rejecting puts the parcel into the same broken state single-spa's own
  * `dieOnTimeout` would, but without leaving a timer holding the parcel for the full deadline.
+ *
+ * Reporting each outcome to `onSettled` from here rather than from the parcel's own promises leaves
+ * a rejection no caller handles free to reach the global unhandled rejection handler.
  */
 function withDeadline(
   lifecycle: LifecycleFn | Array<LifecycleFn>,
   millis: number,
   name: string,
   which: LifecycleName,
+  onSettled: LifecycleSettled,
 ): LifecycleFn {
   const run = toSingleFn(lifecycle, name, which);
 
@@ -92,12 +210,23 @@ function withDeadline(
       );
     });
 
-    return Promise.race([run(props), deadline]).finally(() => clearTimeout(timer));
+    return Promise.race([run(props), deadline])
+      .finally(() => clearTimeout(timer))
+      .then(
+        (value) => {
+          onSettled(which, false);
+          return value;
+        },
+        (err) => {
+          onSettled(which, true);
+          throw err;
+        },
+      );
   };
 }
 
 /** Applies {@link lifecycleDeadlines} to a resolved parcel config. */
-function boundLifecycles(parcelConfig: ParcelConfigObject): ParcelConfigObject {
+function boundLifecycles(parcelConfig: ParcelConfigObject, onSettled: LifecycleSettled): ParcelConfigObject {
   // A parcel that declares its own timeouts is bounding itself, so it is left to single-spa.
   if ((parcelConfig as { timeouts?: unknown }).timeouts) {
     return parcelConfig;
@@ -107,7 +236,7 @@ function boundLifecycles(parcelConfig: ParcelConfigObject): ParcelConfigObject {
   const bounded = Object.fromEntries(
     (Object.keys(lifecycleDeadlines) as Array<LifecycleName>)
       .filter((which) => parcelConfig[which])
-      .map((which) => [which, withDeadline(parcelConfig[which], lifecycleDeadlines[which], name, which)]),
+      .map((which) => [which, withDeadline(parcelConfig[which], lifecycleDeadlines[which], name, which, onSettled)]),
   );
 
   return { ...parcelConfig, ...bounded };
@@ -117,12 +246,12 @@ function boundLifecycles(parcelConfig: ParcelConfigObject): ParcelConfigObject {
  * Applies {@link boundLifecycles} to a parcel config, resolving the function form first so that a
  * lazily loaded config gets the deadlines too.
  */
-function withLifecycleDeadlines(parcelConfig: ParcelConfig): ParcelConfig {
+function withLifecycleDeadlines(parcelConfig: ParcelConfig, onSettled: LifecycleSettled): ParcelConfig {
   if (typeof parcelConfig === 'function') {
-    return (() => parcelConfig().then(boundLifecycles)) as ParcelConfig;
+    return (() => parcelConfig().then((resolved) => boundLifecycles(resolved, onSettled))) as ParcelConfig;
   }
 
-  return boundLifecycles(parcelConfig);
+  return boundLifecycles(parcelConfig, onSettled);
 }
 
 /**
@@ -182,7 +311,12 @@ export async function renderParcel<T = CustomProps>(
   customProps: ParcelProps & T,
 ): Promise<ReturnType<MountParcel>> {
   const mountParcel = await getParcelMounter();
-  return mountParcel(withLifecycleDeadlines(parcelConfig), customProps);
+  // Copied because single-spa holds onto this object for as long as it holds the parcel, and
+  // {@link releaseProps} empties it; the caller's own object is unchanged.
+  const props = { ...customProps };
+  const tracker = trackProps(props);
+
+  return trackUpdates(mountParcel(withLifecycleDeadlines(parcelConfig, tracker.onSettled), props), tracker);
 }
 
 /**