@collagejs/core 0.5.0 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Micro library for framework-agnostic micro-frontends
 
-**🚧🚧 I'M LATE.  WORK IN PROGRESS... ETA: JULY, 2026 🚧🚧**
+**🚧 I'M CATCHING UP FAST.  WORK IN PROGRESS... ETA: JULY, 2026 🚧**
 
 **If you're interested, star ⭐ the repository to get updates on the progress in your GH homepage.**
 
@@ -26,6 +26,7 @@ type UnmountFn = () => Promise<void>;
 interface CorePiece<TProps, TCap> {
     mount: (target: HTMLElement | ShadowRoot, props?: TProps) => Promise<UnmountFn>;
     update?: (props: TProps) => Promise<void>;
+    relocate?: (source: AcceptableTarget, target: AcceptableTarget) => Promise<'supported' | 'done' | 'unsupported'>
     readonly capabilities?: CorePieceCapabilities & TCap;
 };
 ```
@@ -35,9 +36,10 @@ In short:  Micro-frontend creators must simply provide a way to generate an obje
 
 - `mount` mounts the micro-frontend user interface in the document
 - `update` updates the properties given to the micro-frontend
+- `relocate` migrates all root DOM elements in the current target to the new target without a mounting cycle
 - `capabilities` is a feature introduced in v0.5.0 that allows core piece objects to declare its capabilities (see more in its own section)
 
-The `update` function is optional.  The `mount` function must return a cleanup function that, ideally, reverts the mounting process.
+Only the `mount` function is required and must return a cleanup function that, ideally, reverts the mounting process.
 
 This object, once obtained by the consuming project/micro-frontend, is given to the `<Piece>` component.  The implementation of this component is framework-specific.  For example, the `<Piece>` component found in the `@collagejs/svelte` package is a **Svelte** component.
 
@@ -78,7 +80,8 @@ export function buildTestPiece<TProps extends Record<string, any> = Record<strin
             callbacks?.update?.(props);
             pre.textContent = JSON.stringify(props, null, 2);
             return Promise.resolve();
-        }
+        },
+        relocate: () => Promise.resolve('supported'),
     };
 }
 ```
@@ -90,11 +93,10 @@ The key learnings here are:
 2. Inside `mount()`, we do whatever we need to do to mount our user interface inside the target element.
 3. We return a cleanup function that unmounts the user interface.
 4. We optionally provide the `update()` method for property reactivity.
+5. We optionally provide the `relocate()` method for runtime flexibility.  Fun fact:  *CollageJS* can mount in shadow DOM, and reactively changing this setting triggers relocation.
 
 You can export from a single project as many of these factory functions as desired.  You are not constrained to expose just one *CollageJS* piece per project.  Export as many as needed/wanted.
 
-This is how packages like `@collagejs/svelte` work:  When mounting, it calls Svelte's `mount()` function with the given options (if any are given), and returns a cleanup function that calls `unmount()` on the component.  Updating properties is as simple as using a reactive object, at which point Svelte itself takes over the reacting part.
-
 ## Router Needs
 
 As you may (or may not) know, `single-spa` is a client-side router that defines a contract similar to `CorePiece` above.  *CollageJS*, on the other hand, doesn't provide a router.  Use whichever client-side router you wish in your micro-frontend projects.
@@ -108,7 +110,7 @@ There are 2 reasons:
 
 Yes, it is very handy to mount/dismount MFE's as the location URL changes.  This makes routing a popular choice, but not a mandatory one.  MFE's can come and go for any reason, like button clicks, timers or anything a developer can imagine.
 
-Maintenance is an issue.  The `single-spa` core team has had hard times trying to accommodate everyone's needs, especially when dealing with clashing behavior between their router and some framework's router, because people create MFE's with their own router built-in.  On top of this, `single-spa`'s layout web component, which is a "define your routes in markup" helper, lacks features that people want because they exist in other router engines.
+Maintenance is an issue.  The `single-spa` core team has had hard times trying to accommodate everyone's needs, especially when dealing with clashing behavior between their router and some framework's router, because people create MFE's with their own router built-in.  On top of this, `single-spa`'s layout web component, which is a "define your routes in markup" helper (web component), lacks features that people want because they exist in other router engines.
 
 So, the conclusion here is:  *CollageJS* takes care of micro-frontends.  Just that.
 
@@ -132,19 +134,19 @@ You can easily create a new *CollageJS* root project by telling GitHub to create
 - How routers and routes are laid out in markup
 - How fallback content works
 
-> 🪤**The Catch**:  It is a Svelte project.  Ideally, you should know [Svelte](https://svelte.dev) to take full advantage of it.  With `single-spa`, you would have to learn how it worked, and how its layout web component worked.  With this one, you should learn at least a little Svelte.  Some learning curve on both sides.  The good thing about this one is that Svelte knowledge is much more far-reaching.  Svelte is very easy and fun.  We promise.
+> 🪤**The Catch**:  It is a Svelte project.  Ideally, you should know [Svelte](https://svelte.dev) to take full advantage of it.  With `single-spa`, you would have to learn how it worked, and how its layout web component worked.  With this one, you should learn at least a little Svelte.  Some learning curve exists on both sides.  The good thing about this one is that Svelte knowledge is much more far-reaching.  Svelte is very easy and fun.  We promise.
 
 ## For the `single-spa` Savvy
 
-If you know/are used to `single-spa`, you're almost up to speed with *CollageJS*.  Basically, there's no concept of a "root config" project, but of course, there's always a "root" project.  Use whatever framework/technology you want to produce it.
+If you know/are used to `single-spa`, you're almost up to speed with *CollageJS*.  Basically, there's no concept of a "root config" project, but of course, there's always a "root" project.  Use whichever framework/technology you want to produce it.
 
-Then the micro-frontends:  The concept doesn't exist.  At this point (after creating a root UI project), you're 100% free to do as you wish.  Just mount *CollageJS pieces*, which are basically  the equivalent of `single-spa` parcels.  You don't get a router provided, you bring your own, or don't bring a router.  No worries.  Who says that a router is required?  Not us.  You can trigger "parcel" loading by any means at your disposal:  Button clicks, timers, window events, and yes, also location URL changes (routing) if you want.
+Then the micro-frontends:  The concept doesn't exist.  At this point (after creating a root UI project), you just mount *CollageJS pieces* which are basically the equivalent of `single-spa` parcels.  You don't get a router provided, you bring your own, or don't bring a router.  No worries.  Who says that a router is required?  Not us.  You can trigger "parcel" loading by any means at your disposal:  Button clicks, timers, window events, and yes, also location URL changes (routing) if you want.
 
 ### Technical Differences
 
 While `single-spa` asks you to shape your module exports in a particular way (the lifecycle functions), *CollageJS* imposes no such restriction.  It is just not necessary.  Just make sure you can get an object of type `CorePiece` to the `<Piece>` component of your preferred framework.  Then use your framework's marvels to make the `<Piece>` component appear or disappear.
 
-Yes, you'll still be working with import maps.  They are super handy.  We provide an enhanced (and simplified at the same time) version of `import-map-overrides` named `@collagejs/imo`.  It only supports the `overridable-importmap` type (and therefore only native import maps for native ES modules), but carries support for our `@collagejs/vite-aim` plug-in that lets you statically import from micro-frontends.  **That's right!  We are free from dynamic `import()` calls!**  We can statically import from micro-frontends.  Furthermore, it has a more modern user interface:
+Yes, you'll still be working with import maps.  They are super handy.  We provide an enhanced (and simplified at the same time) version of `import-map-overrides` named `@collagejs/imo`.  It only supports the `overridable-importmap` type (and therefore only native import maps for native ES modules), but carries support for our `@collagejs/vite-aim` plug-in that lets you statically import from micro-frontends and auto-externalizes anything in the import map.  **That's right!  We are free from dynamic `import()` calls!**  We can statically import from micro-frontends.  Furthermore, it has a more modern user interface:
 
 ![Main screen of @collagejs/imo](./_docs/collagejs-imo.png)
 
@@ -160,22 +162,18 @@ Gone.  There's no equivalent in *CollageJS*, as experience with `single-spa` has
 
 ## I'm Curious about `capabilities`
 
-Ok, in a nutshell, what inspired this feature was implementing the ability to mount micro-frontends (and its CSS) inside shadow root objects, plus give the developers a good DX.  In short:  If you, the dev, said you wanted the MFE in an open shadow root, but then changed your mind and now you want a closed shadow root, we have to unmount and remount or some other hacky things, like a full page reload.  But for this case, and at least in Svelte, we could relocate the component's generated DOM tree without remounting.
-
-This sounds great, but what if that breaks the MFE?  So the safe path is not to take advantage of cool features.  This conclusion made me sad as a developer.  Therefore, enter `capabilties`.
-
-The `capabilities` object simply states what the core piece object is able to withstand.  The core library defines 2 capabilities, and devs can add user-defined ones to the object.
+The `capabilities` property is a place where core piece developers can declare what their pieces are capable of.  The *CollageJS* core library defines a small set of these, but developers are free to define their own.  These are useful for custom mounting implementations in large projects, where additional impositions can be placed on developed pieces.  Because core pieces are closed in nature, this is a simple way to inform consumers about the piece's capabilities.
 
-One of the stock (or "official" if you will) capabilities is `relocatable: boolean`.  If a core piece object returns `true` for `relocatable`, it is making this statement:  "I can take DOM relocation operations without going through the mounting lifecycle".
+> 👴 If you're a C/C++ developer that knows COM/ActiveX, this is kind of the equivalent of `IUnknown::QueryInterface()`, where interfaces are layers of additional capabilities.
 
-With this reassurance at hand, framework adapters like `@collagejs/svelte` and others that can pull the trick cleanly can go ahead and do it, enhancing DX.  This made me happy once more as a developer, and hope that it makes more devs happy.
+Yes, you may also extend the core piece object and work with interfaces in TypeScript.  Your choice.
 
 ## Packages
 
 | Package | Status | Links | Description |
 | - | - | - | - |
 | `@collagejs/core` | ✔️ | (This repo) | Core functionality.  Provides the general mounting and unmounting logic. |
-| `@collagejs/vite-css` | ✔️ | [Repo](https://github.com/collagejs/vite) | Vite plug-in that offers a CSS-mounting algorithm that is fully compatible with Vite's CSS bundling, including split CSS.  It also features FOUC prevention. |
+| `@collagejs/vite-css` | ✔️ | [Repo](https://github.com/collagejs/vite) | Vite plug-in that offers a CSS-mounting algorithm that is fully compatible with Vite's CSS bundling, including split CSS.  It also features FOUC prevention, shadow root mounting and relocation. |
 | `@collagejs/vite-im` | ✔️ | [Repo](https://github.com/collagejs/vite) | Vite plug-in that injects an import map and optionally the `@collagejs/imo` package to define bare module identifiers for easy micro-frontend loading and debugging. |
 | `@collagejs/vite-aim` | ✔️ | [Repo](https://github.com/collagejs/vite) | Vite-plugin that auto-externalizes the module identifiers found in the application's import map.  It receives the import map live (and with overrides) from the client.  This enables static imports (no more dynamic `import()` calls). |
 | `@collagejs/imo` | ✔️ | [Repo](https://github.com/collagejs/imo) | Our version of `import-map-overrides` that does the usual overriding of import map entries, plus it transmits the final import map to Vite development servers found in it. |
@@ -190,4 +188,4 @@ With this reassurance at hand, framework adapters like `@collagejs/svelte` and o
 | Repository | Description |
 | - | - |
 | [Root Template](https://github.com/collagejs/root-template) | Root template repository that can be used to create new repositories for *CollageJS* root projects, with client-side routing already configured. |
-| (-) | Repository of *CollageJS* pieces made in various front-end technologies for your reference and inspiration. |
+| [Gallery](https://github.com/collagejs/gallery) | Repository of *CollageJS* pieces made in various front-end technologies for your reference and inspiration. |

package/dist/MountedPiece.d.ts

@@ -7,5 +7,6 @@ export declare class MountedPiece<TProps extends Record<string, any> = Record<st
     [mountKey](target: AcceptableTarget, props?: TProps): Promise<void>;
     unmount(): Promise<void>;
     update(props: TProps): Promise<void>;
+    relocate(target: AcceptableTarget, newTarget: AcceptableTarget, customRelocate?: (source: AcceptableTarget, target: AcceptableTarget) => Promise<boolean>): Promise<boolean>;
     get capabilities(): (CorePieceCapabilities & TCap) | undefined;
 }

package/dist/MountedPiece.js

@@ -30,6 +30,66 @@ async function doUpdate(update, props) {
     }
     return await update(props);
 }
+function relocationResultValue(result) {
+    if (Array.isArray(result)) {
+        return result[0];
+    }
+    return result;
+}
+async function doRelocate(relocate, target, newTarget) {
+    const rollbackFns = new Stack();
+    let safeState = true;
+    const doRelocateInternal = async (rel) => {
+        const maybePushRollback = (result) => {
+            if (Array.isArray(result) && (result[0] === 'done' || result[0] === 'supported')) {
+                rollbackFns.push(result[1]);
+            }
+            else if (result === 'done') {
+                safeState = false;
+            }
+        };
+        if (Array.isArray(rel)) {
+            let supported = false;
+            for (const fn of rel) {
+                const r = await doRelocateInternal(fn);
+                const rValue = relocationResultValue(r);
+                if (rValue === 'supported') {
+                    supported = true;
+                }
+                else if (rValue === 'unsupported') {
+                    if (safeState) {
+                        while (rollbackFns.size) {
+                            await rollbackFns.pop()?.();
+                        }
+                        return 'unsupported';
+                    }
+                    throw new Error("Relocation function returned 'unsupported' after another relocation function returned 'done' without a rollback.  The piece's state is now inconsistent.");
+                }
+            }
+            return supported ? 'supported' : 'done';
+        }
+        try {
+            const r = await rel(target, newTarget);
+            maybePushRollback(r);
+            return relocationResultValue(r);
+        }
+        catch (error) {
+            if (safeState) {
+                while (rollbackFns.size) {
+                    await rollbackFns.pop()?.();
+                }
+                console.warn("Relocation function failed.  Piece relocation has been rolled back.", error);
+                return 'unsupported';
+            }
+            throw new Error("Relocation function failed after another relocation function returned 'done' without a rollback.  The piece's state is now inconsistent.");
+        }
+    };
+    const internalResult = await doRelocateInternal(relocate);
+    if (rollbackFns.size > 0 && relocationResultValue(internalResult) === 'supported' && safeState) {
+        return rollbackFns;
+    }
+    return internalResult;
+}
 export class MountedPiece {
     #piece;
     #id;
@@ -68,6 +128,35 @@ export class MountedPiece {
     update(props) {
         return doUpdate(this.#piece.update, props);
     }
+    async relocate(target, newTarget, customRelocate) {
+        if (!this.#piece.relocate) {
+            return Promise.resolve(false);
+        }
+        const result = await doRelocate(this.#piece.relocate, target, newTarget);
+        if (result === 'done') {
+            return true;
+        }
+        if (result === 'unsupported') {
+            return false;
+        }
+        // At this point, custom relocation must finish the job.
+        if (!customRelocate) {
+            throw new Error("Relocation of this piece is 'supported', but no custom relocation function was provided.");
+        }
+        if (result === 'supported') {
+            return await customRelocate(target, newTarget);
+        }
+        try {
+            return await customRelocate(target, newTarget);
+        }
+        catch (error) {
+            while (result.size) {
+                await result.pop()?.();
+            }
+            console.warn("Custom relocation function failed.  Piece relocation has been rolled back.", error);
+            return false;
+        }
+    }
     get capabilities() {
         return this.#piece.capabilities;
     }

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export { mountPiece } from './mountPiece.js';
 export { mountPieceKey } from './common.js';
 export { ensureGlobalCollageJs } from './global.js';
 export { preventRemount } from './preventRemount.js';
+export { noopPiece } from './noopPiece.js';
+export { Stack } from './Stack.js';

package/dist/index.js

@@ -2,3 +2,5 @@ export { mountPiece } from './mountPiece.js';
 export { mountPieceKey } from './common.js';
 export { ensureGlobalCollageJs } from './global.js';
 export { preventRemount } from './preventRemount.js';
+export { noopPiece } from './noopPiece.js';
+export { Stack } from './Stack.js';

package/dist/noopPiece.d.ts

@@ -0,0 +1,12 @@
+import type { CorePiece } from "./types.js";
+/**
+ * Utility function that provides a no-op `CorePiece` object. This is useful for testing or when a placeholder piece is
+ * needed.
+ *
+ * **⚠️IMPORTANT**:  The returned object is a singleton.  This is **not** a factory function that creates a new object
+ * each time it is called.  If you need a new object, you should create your own.
+ * @template TProps The type of the properties for the `CorePiece`. Defaults to `Record<string, any>`.
+ * @template TCap The type of the capabilities for the `CorePiece`. Defaults to an empty object `{}`.
+ * @returns {CorePiece<TProps, TCap>} A no-op `CorePiece` object properly typed.
+ */
+export declare function noopPiece<TProps extends Record<string, any> = Record<string, any>, TCap extends Record<string, any> = {}>(): CorePiece<TProps, TCap>;

package/dist/noopPiece.js

@@ -0,0 +1,16 @@
+const np = {
+    mount: () => Promise.resolve(() => Promise.resolve()),
+};
+/**
+ * Utility function that provides a no-op `CorePiece` object. This is useful for testing or when a placeholder piece is
+ * needed.
+ *
+ * **⚠️IMPORTANT**:  The returned object is a singleton.  This is **not** a factory function that creates a new object
+ * each time it is called.  If you need a new object, you should create your own.
+ * @template TProps The type of the properties for the `CorePiece`. Defaults to `Record<string, any>`.
+ * @template TCap The type of the capabilities for the `CorePiece`. Defaults to an empty object `{}`.
+ * @returns {CorePiece<TProps, TCap>} A no-op `CorePiece` object properly typed.
+ */
+export function noopPiece() {
+    return np;
+}

package/dist/types.d.ts

@@ -20,6 +20,29 @@ export type UnmountFn = () => Promise<void>;
  * @returns A promise to the cleanup function that unmounts the piece.
  */
 export type MountFn<TProps extends Record<string, any> = Record<string, any>> = (target: AcceptableTarget, props?: MountProps<TProps>) => Promise<UnmountFn>;
+/**
+ * Supported return values of `CorePiece.relocate` functions.
+ */
+export type RelocationResultValue = 'supported' | 'unsupported' | 'done';
+/**
+ * Defines the signature of rollback functions that can be returned by `CorePiece.relocate` functions.  These functions
+ * can be provided when returning `done` or `supported` from a relocation function, and will be called if the
+ * relocation chain fails.
+ * @returns A promise that resolves once the rollback process concludes.
+ */
+export type RelocationRollbackFn = () => Promise<void>;
+/**
+ * Defines the possible return values of `CorePiece.relocate`.
+ */
+export type RelocationResult = RelocationResultValue | [Exclude<RelocationResultValue, 'unsupported'>, RelocationRollbackFn];
+/**
+ * Type that defines the signature of the functions accepted in `CorePiece.relocate`.
+ * @param parent The current parent of the piece's root element(s).
+ * @param newParent The new parent where the piece's root element(s) will be relocated.
+ * @returns A promise that resolves to one of the acceptable values.  See `RelocationResult` and related types for
+ * details.
+ */
+export type RelocateFn = (parent: AcceptableTarget, newParent: AcceptableTarget) => Promise<RelocationResult>;
 /**
  * Type that defines the signature of the functions accepted in `CorePiece.update`.
  * @param props The new property values for the mounted piece.
@@ -33,7 +56,11 @@ export type Mount<TProps extends Record<string, any> = Record<string, any>> = Mo
 /**
  * Defines the accepted shapes for `CorePiece.update`.
  */
-export type Update<TProps extends Record<string, any> = Record<string, any>> = UpdateFn<TProps> | UpdateFn<TProps>[] | Update[];
+export type Update<TProps extends Record<string, any> = Record<string, any>> = UpdateFn<TProps> | UpdateFn<TProps>[] | Update<TProps>[];
+/**
+ * Defines the accepted shapes for `CorePiece.relocate`.
+ */
+export type Relocate = RelocateFn | RelocateFn[] | Relocate[];
 /**
  * Defines the capabilities of a `CorePiece` object recognized by the core *CollageJS* library.  These capabilities are
  * used to determine how the core library should handle the piece's lifecycle, or whether a particular action or
@@ -50,18 +77,6 @@ export type CorePieceCapabilities = {
      * **💡TIP**:  Official framework adapters provide this functionality.
      */
     remountable?: boolean;
-    /**
-     * Indicates that the piece allows relocation of its HTML markup to a new parent without unmounting.  For the best
-     * development experience, piece objects should always strive to be relocatable.
-     *
-     * If `false`, `Piece` components created with official framework adapters will most likely have to ask HMR to
-     * perform a full page reload whenever the developer changes shadow DOM options, like moving from an open to a
-     * closed shadow root.
-     *
-     * If `true` **and if the framework is capable** (i. e. Svelte), the piece can be relocated without unmounting, and
-     * HMR will be able to update the shadow root options without a full page reload.
-     */
-    relocatable?: boolean;
 };
 /**
  * Defines the contract that objects must follow in order to be mountable as *CollageJS* pieces (micro-frontends).
@@ -77,14 +92,58 @@ export interface CorePiece<TProps extends Record<string, any> = Record<string, a
      * while mounted in the document, and all property values must have been passed during mounting.
      */
     update?: Update<TProps>;
+    /**
+     * Either relocates the root element(s) of the piece to a new parent, or prepares the piece for relocation.  This
+     * is optional.  If not provided, the piece won't support relocation of its root element(s) to a new parent, and
+     * the piece will be unmounted and remounted instead in pertinent cases.
+     *
+     * ### Return Values
+     *
+     * + `done`:  The relocation succeeded and was made entirely by the piece.
+     * + `unsupported`:  The piece does not support relocation.
+     * + `supported`:  The piece supports relocation, but the relocation must be performed by the caller.
+     *
+     * Additionally, the values `done` and `supported` can be returned as a tuple with a rollback function that will be
+     * called if the relocation chain fails after this function has returned `done` or `supported`.
+     *
+     * ### Rollback Functions
+     *
+     * If a relocation function returns a rollback function, it will be called if any of the following occurs:
+     *
+     * + Another relocation function returns `unsupported` after this one returned `done` or `supported`.
+     * + Another relocation function throws an error after this one returned `done` or `supported`.
+     *
+     * ### When Using Multiple Relocation Functions
+     *
+     * If multiple relocation functions are provided, they will be called in order:
+     *
+     * + If the first of them returns `unsupported`, the relocation process will stop.
+     * + If all of them return `done`, the relocation is considered successful.
+     * + If any of them returns `'supported'`, the remaining functions are still called, but the caller will
+     * run its relocation process after all functions have been called, even if they return `'done'`.
+     * + If any of them returns `unsupported` after one or more of them returned `'supported'` or `done` without a
+     * rollback function, the piece's state is considered inconsistent and an error will be thrown.
+     */
+    relocate?: Relocate;
     /**
      * Declares the capabilities of the piece.  This is optional.  If not provided, the piece will be assumed to have no
-     * capabilities, and the core library will treat it as a simple piece that can be mounted once and unmounted once, and
-     * that cannot be relocated or re-mounted.
+     * capabilities.
+     *
+     * ### Notable Exception
+     *
+     * The library defines the `remountable` capability, which is informative only.  The core library cannot enforce
+     * this capability, so `CorePiece` developers should use the `preventRemount()` function (or equivalent) to throw an
+     * error if the piece is mounted more than once for pieces that cannot withstand multiple mountings.
+     *
+     * Official framework adapters query the value of `capabilities.remountable` and act accordingly to their best
+     * ability, and at least emit a warning if a non-remountable piece is mounted more than once.
      *
-     * **💡TIP**: Always try to at least create pieces that are relocatable by not storing the original target element in
-     * the piece's state.  Instead, just use the piece's root element's `parentElement` property to determine the
-     * current parent element.
+     * Only the author of a `CorePiece` object can guarantee that the piece is remountable.  We encourage developers to
+     * be explicit about this capability when creating `CorePiece` objects.
+     *
+     * > ℹ️ **NOTE:**  Official framework adapters are free to choose which default value for `capabilities.remountable`
+     * > they will use while creating `CorePiece` objects when the property is not provided in order to maximize
+     * > framework feature usage (perhaps a framework can guarantee component state automatically, or perhaps it cannot).
      */
     readonly capabilities?: CorePieceCapabilities & TCap;
 }
@@ -100,6 +159,10 @@ export interface MountedPiece<TProps extends Record<string, any> = Record<string
      * Function used to unmount the `CorePiece` object.
      */
     unmount: UnmountFn;
+    /**
+     * Function used to relocate the `CorePiece` object to a new parent without unmounting.
+     */
+    relocate: (source: AcceptableTarget, target: AcceptableTarget, customRelocate?: (source: AcceptableTarget, target: AcceptableTarget) => Promise<boolean>) => Promise<boolean>;
     /**
      * The version of the global `mountPiece` function that tracks mounted children so their unmounting is
      * synchronized with this piece's unmount event.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@collagejs/core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Core functionality for CollageJS.",
   "type": "module",
   "main": "./dist/index.js",