@collagejs/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 collagejs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# <img src="src/logos/collagejs-48.svg" alt="Svelte Router Logo" width="48" height="48" align="left">&nbsp;CollageJS
+
+> Micro library for framework-agnostic micro-frontends
+
+**🚧🚧 YOU'RE EARLY.  WORK IN PROGRESS... 🚧🚧**
+
+*If you would like to express youself, head to the [Discussions board](https://github.com/collagejs/collagejs/discussions).*
+
+[Full Documentation](https://collagejs.dev)
+
+*CollageJS* is a very, very small library that enables the composition of a web user interface with micro-frontends created with any technology (Svelte, React, Vue, Solid, HTMX, etc.).  It is heavily inspired by the *parcel* concept in the excellent `single-spa` routing library.
+
+## How It Works
+
+*CollageJS* defines a contract that must be fulfilled by an object.  This contract is defined as the following TypeScript types (simplified):
+
+```typescript
+type UnmountFn = () => Promise<void>;
+type MountFn<TProps> = (target: HTMLElement, props?: TProps) => Promise<UnmountFn>;
+type Mount<TProps> = MountFn<TProps> | MountFn<TProps>[] | Mount<TProps>[];
+type UpdateFn<TProps> = (props: TProps) => Promise<void>;
+type Update<TProps> = UpdateFn<TProps> | UpdateFn<TProps>[] | Update[];
+
+interface CorePiece<TProps> {
+    mount: Mount<TProps>;
+    update?: Update<TProps>;
+};
+```
+> ℹ️ These types were simplified.  See the real ones after installing the library.
+
+In short:  Micro-frontend creators must simply provide a way to generate an object that fulfills the above `CorePiece` interface, where:
+
+- `mount` mounts the micro-frontend user interface in the document
+- `update` updates the properties given to the micro-frontend
+
+The `update` function is optional.  The `mount` function 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.
+
+## 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.
+
+### Why No Router
+
+There are 2 reasons.  The first one is quite simple:  A router is not mandatory to implement and use micro-frontends.  Micro-frontends can come and go for any reason, such as the user clicking a button, a timer running out, etc.  The "micro-frontend" concept is not tied to routing.
+
+The second reason is maintenance:  Historically, the `single-spa` router has had a tough time pleasing everyone because most often than not, micro-frontends come with their own "sub-routers" installed.  MFE's created in React usually come featuring the `react-router` router; SolidJS MFE's come with `@solidjs/router`, etc. and the mixture has sometimes caused problems.  Furthermore, `single-spa` provides a web component to configure the router in markup format, which has caused even more issues.  Moreover, this layout component lacks features people are used to having within their own frameworks of choice.
+
+In light of this:  **Bring Your Own Router**.  It is just better.  There are routers out there supported by entire teams with great many features, and developers probably learned to use them already.  Not providing a router (unlike `single-spa`) is one less thing to learn for consumers of this library.
+
+Do you disagree with this?  Perhaps you need one and don't know which one would work best?  No problem!  We can recommend one:  Create a "root" **Vite + Svelte** project and use `@svelte-router/core` ([documentation](https://svelte-router.dev)).  This is a multi-route-matching router designed for micro-frontends.  It is very simple to use and learn, even if you have never used Svelte before.
+
+**"But I don't want to learn Svelte"**, you might say.  Well, it's understandable.  However, if you're coming from a `single-spa` experience, learning a bit of Svelte to configure the root router is no different than learning `single-spa`'s layout web component.
+
+In the end, it is your choice.
+
+## 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.
+
+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.
+
+### 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 can still use import maps, and can even continue using the excellent `import-map-overrides` package.  It is encouraged.
+
+#### Where Did the `unmount` Lifecycle Function Go?
+
+In *CollageJS*, `CorePiece.mount()` returns the clean-up (unmounting) function.
+
+#### And What About `bootstrap`?
+
+Gone.  There's no equivalent in *CollageJS*, as experience with `single-spa` has demonstrated that is rarely needed, and if needed, one can do this initialization easily without having to impose the function requirement.  At least for now, there's no foreseeable future where an initialization function similar to `single-spa`'s `bootstrap()` will be defined.
+
+## Packages
+
+| Package | Status | Description |
+| - | - | - |
+| `@collagejs/core` | ✔️ | Core functionality.  Provides the general mounting and unmouting logic. |
+| `@collagejs/vite` | ❌ | Vite plug-in that offers a CSS-mounting algorithm that is fully compatible with Vite's CSS bundling, including split CSS. |
+| `@collagejs/svelte` | ✔️ | Svelte component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
+| `@collagejs/react` | ❌ | React component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
+| `@collagejs/solidjs` | ❌ | SolidJS component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
+| `@collagejs/vue` | ❌ | VueJS component library that can be used to create `CorePiece`-compliant objects and to mount `CorePiece` objects (of any technology) by providing the `<Piece>` component. |
+| `@collagejs/angular` | ❌ | **External help needed.**  We don't have expertise in Angular, nor do we want to acquire it.  If you're an Angular developer, please consider contributing. |

package/dist/MountedPiece.d.ts

@@ -0,0 +1,10 @@
+import type { CorePiece, MountPiece } from "./types.js";
+export declare const mountKey: unique symbol;
+export declare class MountedPiece<TProps extends Record<string, any> = Record<string, any>> {
+    #private;
+    get mountPiece(): MountPiece<TProps>;
+    constructor(piece: CorePiece<TProps>, mountPiece: MountPiece<TProps>, parent?: MountedPiece);
+    [mountKey](target: HTMLElement, props?: TProps): Promise<void>;
+    unmount(): Promise<void>;
+    update(props: TProps): Promise<void>;
+}

package/dist/MountedPiece.js

@@ -0,0 +1,70 @@
+import { mountPieceKey } from "./common.js";
+import { Stack } from "./Stack.js";
+export const mountKey = Symbol();
+let pieceIdCounter = 0;
+function generatePieceId() {
+    return `cjsp-${++pieceIdCounter}-${Date.now().toString(36)}`;
+}
+async function doMount(mount, target, props) {
+    if (Array.isArray(mount)) {
+        const unmountFns = new Stack();
+        for (const m of mount) {
+            unmountFns.push(await doMount(m, target, props));
+        }
+        return async () => {
+            for (const u of unmountFns) {
+                await u();
+            }
+        };
+    }
+    return await mount(target, props);
+}
+async function doUpdate(update, props) {
+    if (!update)
+        return;
+    if (Array.isArray(update)) {
+        for (const u of update) {
+            await doUpdate(u, props);
+        }
+        return;
+    }
+    return await update(props);
+}
+export class MountedPiece {
+    #piece;
+    #id;
+    #childPieces;
+    #parent;
+    #cleanup;
+    #mountPiece;
+    get mountPiece() {
+        return this.#mountPiece;
+    }
+    constructor(piece, mountPiece, parent) {
+        this.#piece = piece;
+        this.#parent = parent;
+        this.#id = generatePieceId();
+        this.#childPieces = new Stack();
+        this.#mountPiece = mountPiece.bind(this);
+    }
+    async [mountKey](target, props) {
+        this.#cleanup = await doMount(this.#piece.mount, target, { ...props, [mountPieceKey]: this.#mountPiece });
+        if (this.#parent) {
+            this.#parent.#childPieces.push(this);
+        }
+    }
+    async unmount() {
+        if (this.#childPieces.size) {
+            for (const childPiece of this.#childPieces) {
+                await childPiece.unmount();
+            }
+        }
+        await this.#cleanup?.();
+        if (this.#parent) {
+            this.#parent.#childPieces.delete((item) => item.#id === this.#id);
+        }
+    }
+    update(props) {
+        return doUpdate(this.#piece.update, props);
+    }
+}

package/dist/Stack.d.ts

@@ -0,0 +1,99 @@
+/**
+ * A generic stack implementation providing standard stack operations.
+ * Follows LIFO (Last In, First Out) principle.
+ *
+ * @template T The type of elements stored in the stack
+ */
+export declare class Stack<T> {
+    #private;
+    /**
+     * Adds an element to the top of the stack.
+     *
+     * @param item The item to push onto the stack
+     * @returns The new size of the stack
+     */
+    push(item: T): number;
+    /**
+     * Removes and returns the top element from the stack.
+     *
+     * @returns The top element, or undefined if the stack is empty
+     */
+    pop(): T | undefined;
+    /**
+     * Returns the top element without removing it.
+     *
+     * @returns The top element, or undefined if the stack is empty
+     */
+    peek(): T | undefined;
+    /**
+     * Returns the top element without removing it.
+     * Alias for peek() method.
+     *
+     * @returns The top element, or undefined if the stack is empty
+     */
+    top(): T | undefined;
+    /**
+     * Checks if the stack is empty.
+     *
+     * @returns True if the stack contains no elements, false otherwise
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns the number of elements in the stack.
+     *
+     * @returns The size of the stack
+     */
+    get size(): number;
+    /**
+     * Returns the number of elements in the stack.
+     * Alias for size property.
+     *
+     * @returns The length of the stack
+     */
+    get length(): number;
+    /**
+     * Removes all elements from the stack.
+     */
+    clear(): void;
+    /**
+     * Removes the first element that matches the predicate function.
+     * Searches from top to bottom of the stack.
+     *
+     * @param predicate Function that tests each element for removal
+     * @returns True if an element was removed, false if no match was found
+     */
+    delete(predicate: (item: T) => boolean): boolean;
+    /**
+     * Returns a shallow copy of the stack as an array.
+     * The first element in the array represents the bottom of the stack.
+     *
+     * @returns A copy of the internal array
+     */
+    toArray(): T[];
+    /**
+     * Creates a new stack from an array of items.
+     * The first element in the array becomes the bottom of the stack.
+     *
+     * @param items Array of items to initialize the stack with
+     * @returns A new Stack instance
+     */
+    static fromArray<U>(items: U[]): Stack<U>;
+    /**
+     * Returns a string representation of the stack.
+     *
+     * @returns String representation showing stack contents
+     */
+    toString(): string;
+    /**
+     * Allows iteration over the stack from top to bottom.
+     *
+     * @returns Iterator that yields elements from top to bottom
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Returns an iterator that yields elements from bottom to top.
+     *
+     * @returns Iterator that yields elements from bottom to top
+     */
+    bottomToTop(): Iterator<T>;
+}

package/dist/Stack.js

@@ -0,0 +1,139 @@
+/**
+ * A generic stack implementation providing standard stack operations.
+ * Follows LIFO (Last In, First Out) principle.
+ *
+ * @template T The type of elements stored in the stack
+ */
+export class Stack {
+    #items = [];
+    /**
+     * Adds an element to the top of the stack.
+     *
+     * @param item The item to push onto the stack
+     * @returns The new size of the stack
+     */
+    push(item) {
+        return this.#items.push(item);
+    }
+    /**
+     * Removes and returns the top element from the stack.
+     *
+     * @returns The top element, or undefined if the stack is empty
+     */
+    pop() {
+        return this.#items.pop();
+    }
+    /**
+     * Returns the top element without removing it.
+     *
+     * @returns The top element, or undefined if the stack is empty
+     */
+    peek() {
+        return this.#items[this.#items.length - 1];
+    }
+    /**
+     * Returns the top element without removing it.
+     * Alias for peek() method.
+     *
+     * @returns The top element, or undefined if the stack is empty
+     */
+    top() {
+        return this.peek();
+    }
+    /**
+     * Checks if the stack is empty.
+     *
+     * @returns True if the stack contains no elements, false otherwise
+     */
+    isEmpty() {
+        return this.#items.length === 0;
+    }
+    /**
+     * Returns the number of elements in the stack.
+     *
+     * @returns The size of the stack
+     */
+    get size() {
+        return this.#items.length;
+    }
+    /**
+     * Returns the number of elements in the stack.
+     * Alias for size property.
+     *
+     * @returns The length of the stack
+     */
+    get length() {
+        return this.size;
+    }
+    /**
+     * Removes all elements from the stack.
+     */
+    clear() {
+        this.#items = [];
+    }
+    /**
+     * Removes the first element that matches the predicate function.
+     * Searches from top to bottom of the stack.
+     *
+     * @param predicate Function that tests each element for removal
+     * @returns True if an element was removed, false if no match was found
+     */
+    delete(predicate) {
+        for (let i = this.#items.length - 1; i >= 0; i--) {
+            if (predicate(this.#items[i])) {
+                this.#items.splice(i, 1);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Returns a shallow copy of the stack as an array.
+     * The first element in the array represents the bottom of the stack.
+     *
+     * @returns A copy of the internal array
+     */
+    toArray() {
+        return [...this.#items];
+    }
+    /**
+     * Creates a new stack from an array of items.
+     * The first element in the array becomes the bottom of the stack.
+     *
+     * @param items Array of items to initialize the stack with
+     * @returns A new Stack instance
+     */
+    static fromArray(items) {
+        const stack = new Stack();
+        stack.#items = [...items];
+        return stack;
+    }
+    /**
+     * Returns a string representation of the stack.
+     *
+     * @returns String representation showing stack contents
+     */
+    toString() {
+        return `Stack[${this.#items.join(', ')}]`;
+    }
+    /**
+     * Allows iteration over the stack from top to bottom.
+     *
+     * @returns Iterator that yields elements from top to bottom
+     */
+    *[Symbol.iterator]() {
+        for (let i = this.#items.length - 1; i >= 0; i--) {
+            yield this.#items[i];
+        }
+    }
+    /**
+     * Returns an iterator that yields elements from bottom to top.
+     *
+     * @returns Iterator that yields elements from bottom to top
+     */
+    *bottomToTop() {
+        for (let i = 0; i < this.#items.length; i++) {
+            yield this.#items[i];
+        }
+    }
+}

package/dist/common.d.ts

@@ -0,0 +1 @@
+export declare const mountPieceKey: unique symbol;

package/dist/common.js

@@ -0,0 +1 @@
+export const mountPieceKey = Symbol.for("collagejs.mountPiece");

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './types.js';
+export { mountPiece } from './mountPiece.js';
+export { mountPieceKey } from './common.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { mountPiece } from './mountPiece.js';
+export { mountPieceKey } from './common.js';

package/dist/internal-types.d.ts

@@ -0,0 +1,8 @@
+import type { UnmountFn, UpdateFn } from "./types.js";
+export declare namespace Internal {
+    type MountedPiece<TProps extends Record<string, any> = Record<string, any>> = {
+        update: UpdateFn<TProps>;
+        unmount: UnmountFn;
+        childPieces: Map<string, MountedPiece>;
+    };
+}

package/dist/internal-types.js

@@ -0,0 +1 @@
+export {};

package/dist/logos/collagejs-128.svg

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="128" height="128" viewBox="0 0 128 128" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="primaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#4F46E5"/>
+      <stop offset="100%" stop-color="#7C3AED"/>
+    </linearGradient>
+    <linearGradient id="secondaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#06B6D4"/>
+      <stop offset="100%" stop-color="#0EA5E9"/>
+    </linearGradient>
+    <linearGradient id="accentGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#10B981"/>
+      <stop offset="100%" stop-color="#059669"/>
+    </linearGradient>
+    <linearGradient id="warningGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#F59E0B"/>
+      <stop offset="100%" stop-color="#D97706"/>
+    </linearGradient>
+    <filter id="dropShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="1" dy="2" stdDeviation="2" flood-opacity="0.2"/>
+    </filter>
+  </defs>
+  
+  <!-- No background - clean floating pieces -->
+  
+  <!-- Simplified collage pieces -->
+  <!-- Main piece (top-left) -->
+  <path d="M20 30 L55 25 L60 45 L50 60 L30 55 L20 40 Z" 
+        fill="url(#primaryGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.9"/>
+  
+  <!-- Secondary piece (top-right) -->
+  <path d="M70 20 L105 30 L100 50 L90 45 L80 35 L70 30 Z" 
+        fill="url(#secondaryGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.85"/>
+  
+  <!-- Third piece (center-left) -->
+  <path d="M15 65 L45 60 L50 80 L40 90 L25 85 L15 75 Z" 
+        fill="url(#accentGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.8"/>
+  
+  <!-- Fourth piece (bottom-right) -->
+  <path d="M55 75 L95 80 L90 100 L75 105 L60 95 L55 85 Z" 
+        fill="url(#warningGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.85"/>
+  
+  <!-- Small connecting dots for detail -->
+  <circle cx="60" cy="50" r="4" fill="url(#secondaryGrad)" opacity="0.8"/>
+  <circle cx="80" cy="65" r="3" fill="url(#accentGrad)" opacity="0.8"/>
+  
+  <!-- Central JS text with enhanced visibility -->
+  <text x="64" y="74" 
+        font-family="'SF Pro Display', 'Segoe UI', -apple-system, sans-serif" 
+        font-size="24" 
+        font-weight="700" 
+        text-anchor="middle" 
+        fill="url(#primaryGrad)"
+        stroke="#FFFFFF"
+        stroke-width="1"
+        paint-order="stroke fill">JS</text>
+</svg>

package/dist/logos/collagejs-16.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="16" height="16" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="primaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#4F46E5"/>
+      <stop offset="100%" stop-color="#7C3AED"/>
+    </linearGradient>
+    <linearGradient id="warningGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#F59E0B"/>
+      <stop offset="100%" stop-color="#D97706"/>
+    </linearGradient>
+  </defs>
+  
+  <!-- Pure geometric representation -->
+  <path d="M3 4 L7 3 L8 6 L6 8 L4 7 L3 5 Z" fill="url(#primaryGrad)" opacity="0.9"/>
+  <path d="M9 3 L13 4 L12 7 L10 6 L9 5 Z" fill="#06B6D4" opacity="0.8"/>
+  <path d="M2 9 L6 8 L7 11 L5 13 L3 12 L2 10 Z" fill="#10B981" opacity="0.8"/>
+  <rect x="8" y="9" width="6" height="4" rx="1" fill="url(#warningGrad)" opacity="0.8"/>
+</svg>

package/dist/logos/collagejs-48.svg

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="48" height="48" viewBox="0 0 48 48" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="primaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#4F46E5"/>
+      <stop offset="100%" stop-color="#7C3AED"/>
+    </linearGradient>
+    <linearGradient id="secondaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#06B6D4"/>
+      <stop offset="100%" stop-color="#0EA5E9"/>
+    </linearGradient>
+    <linearGradient id="accentGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#10B981"/>
+      <stop offset="100%" stop-color="#059669"/>
+    </linearGradient>
+    <linearGradient id="warningGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#F59E0B"/>
+      <stop offset="100%" stop-color="#D97706"/>
+    </linearGradient>
+  </defs>
+  
+  <!-- No background - ultra minimal -->
+  
+  <!-- Very simplified geometric shapes -->
+  <path d="M8 12 L20 10 L22 18 L18 22 L12 20 L8 16 Z" 
+        fill="url(#primaryGrad)" 
+        opacity="0.9"/>
+  
+  <path d="M26 8 L38 12 L36 20 L32 18 L28 14 L26 12 Z" 
+        fill="url(#secondaryGrad)" 
+        opacity="0.85"/>
+  
+  <path d="M6 26 L18 24 L20 32 L16 36 L10 34 L6 30 Z" 
+        fill="url(#accentGrad)" 
+        opacity="0.8"/>
+  
+  <rect x="24" y="28" width="16" height="12" rx="2" 
+        fill="url(#warningGrad)" 
+        opacity="0.85"/>
+  
+  <!-- Enhanced JS text with stroke -->
+  <text x="24" y="28" 
+        font-family="'SF Pro Display', 'Segoe UI', -apple-system, sans-serif" 
+        font-size="10" 
+        font-weight="700" 
+        text-anchor="middle" 
+        fill="#FFFFFF"
+        stroke="url(#primaryGrad)"
+        stroke-width="0.5">JS</text>
+</svg>

package/dist/logos/collagejs-512.svg

@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="512" height="512" viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <!-- Gradients for depth and modern look -->
+    <linearGradient id="primaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#4F46E5"/>
+      <stop offset="100%" stop-color="#7C3AED"/>
+    </linearGradient>
+    <linearGradient id="secondaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#06B6D4"/>
+      <stop offset="100%" stop-color="#0EA5E9"/>
+    </linearGradient>
+    <linearGradient id="accentGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#10B981"/>
+      <stop offset="100%" stop-color="#059669"/>
+    </linearGradient>
+    <linearGradient id="warningGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#F59E0B"/>
+      <stop offset="100%" stop-color="#D97706"/>
+    </linearGradient>
+    <!-- Drop shadows -->
+    <filter id="dropShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="4" dy="6" stdDeviation="8" flood-opacity="0.15"/>
+    </filter>
+    <filter id="glow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="3" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+  
+  <!-- No background - pieces float freely -->
+  
+  <!-- Main collage pieces - representing micro-frontend components -->
+  <!-- Large primary piece (top-left) -->
+  <path d="M80 120 L220 100 L240 180 L200 240 L120 220 L80 160 Z" 
+        fill="url(#primaryGrad)" 
+        filter="url(#glow)" 
+        opacity="0.95"/>
+  
+  <!-- Secondary piece (top-right) -->
+  <path d="M280 80 L420 120 L400 200 L360 180 L320 140 L280 120 Z" 
+        fill="url(#secondaryGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.85"/>
+  
+  <!-- Third piece (center-left) -->
+  <path d="M60 260 L180 240 L200 320 L160 360 L100 340 L60 300 Z" 
+        fill="url(#accentGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.8"/>
+  
+  <!-- Fourth piece (bottom-center) -->
+  <path d="M220 300 L380 320 L360 400 L300 420 L240 380 L220 340 Z" 
+        fill="url(#warningGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.85"/>
+  
+  <!-- Fifth piece (right) -->
+  <path d="M380 200 L460 240 L440 320 L400 300 L380 260 Z" 
+        fill="url(#primaryGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.7"/>
+  
+  <!-- Small connecting pieces for detail -->
+  <circle cx="240" cy="200" r="16" fill="url(#secondaryGrad)" opacity="0.8"/>
+  <circle cx="320" cy="260" r="12" fill="url(#accentGrad)" opacity="0.8"/>
+  <circle cx="180" cy="300" r="10" fill="url(#primaryGrad)" opacity="0.8"/>
+  
+  <!-- Stylized "JS" text with enhanced visibility -->
+  <g transform="translate(256, 400)">
+    <text x="0" y="0" 
+          font-family="'SF Pro Display', 'Segoe UI', -apple-system, sans-serif" 
+          font-size="72" 
+          font-weight="700" 
+          text-anchor="middle" 
+          fill="url(#primaryGrad)"
+          stroke="#FFFFFF"
+          stroke-width="2"
+          paint-order="stroke fill">JS</text>
+  </g>
+  
+  <!-- CollageJS text -->
+  <g transform="translate(256, 450)">
+    <text x="0" y="0" 
+          font-family="'SF Pro Display', 'Segoe UI', -apple-system, sans-serif" 
+          font-size="28" 
+          font-weight="500" 
+          text-anchor="middle" 
+          fill="#374151">Collage</text>
+  </g>
+  
+  <!-- Subtle connection lines showing pieces working together -->
+  <line x1="150" y1="160" x2="200" y2="200" stroke="url(#primaryGrad)" stroke-width="3" opacity="0.3"/>
+  <line x1="280" y1="140" x2="320" y2="180" stroke="url(#secondaryGrad)" stroke-width="3" opacity="0.3"/>
+  <line x1="200" y1="280" x2="280" y2="300" stroke="url(#accentGrad)" stroke-width="3" opacity="0.3"/>
+</svg>

package/dist/logos/collagejs-64.svg

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="64" height="64" viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="primaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#4F46E5"/>
+      <stop offset="100%" stop-color="#7C3AED"/>
+    </linearGradient>
+    <linearGradient id="secondaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#06B6D4"/>
+      <stop offset="100%" stop-color="#0EA5E9"/>
+    </linearGradient>
+    <linearGradient id="accentGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#10B981"/>
+      <stop offset="100%" stop-color="#059669"/>
+    </linearGradient>
+    <linearGradient id="warningGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#F59E0B"/>
+      <stop offset="100%" stop-color="#D97706"/>
+    </linearGradient>
+  </defs>
+  
+  <!-- No background - minimal clean design -->
+  
+  <!-- Simplified geometric pieces -->
+  <path d="M10 15 L28 12 L30 22 L25 30 L15 28 L10 20 Z" 
+        fill="url(#primaryGrad)" 
+        opacity="0.9"/>
+  
+  <path d="M35 10 L52 15 L50 25 L45 22 L40 17 L35 15 Z" 
+        fill="url(#secondaryGrad)" 
+        opacity="0.85"/>
+  
+  <path d="M8 32 L22 30 L25 40 L20 45 L12 42 L8 37 Z" 
+        fill="url(#accentGrad)" 
+        opacity="0.8"/>
+  
+  <path d="M28 37 L47 40 L45 50 L37 52 L30 47 L28 42 Z" 
+        fill="url(#warningGrad)" 
+        opacity="0.85"/>
+  
+  <!-- Small connecting dot for detail -->
+  <circle cx="40" cy="32" r="2" fill="url(#secondaryGrad)" opacity="0.8"/>
+  
+  <!-- Central JS with stroke for visibility -->
+  <text x="32" y="37" 
+        font-family="'SF Pro Display', 'Segoe UI', -apple-system, sans-serif" 
+        font-size="12" 
+        font-weight="700" 
+        text-anchor="middle" 
+        fill="url(#primaryGrad)"
+        stroke="#FFFFFF"
+        stroke-width="0.8"
+        paint-order="stroke fill">JS</text>
+</svg>

package/dist/logos/collagejs-icon.svg

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="256" height="256" viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="primaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#4F46E5"/>
+      <stop offset="100%" stop-color="#7C3AED"/>
+    </linearGradient>
+    <linearGradient id="secondaryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#06B6D4"/>
+      <stop offset="100%" stop-color="#0EA5E9"/>
+    </linearGradient>
+    <linearGradient id="accentGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#10B981"/>
+      <stop offset="100%" stop-color="#059669"/>
+    </linearGradient>
+    <linearGradient id="warningGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#F59E0B"/>
+      <stop offset="100%" stop-color="#D97706"/>
+    </linearGradient>
+    <filter id="dropShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="2" dy="3" stdDeviation="4" flood-opacity="0.15"/>
+    </filter>
+  </defs>
+  
+  <!-- Subtle universal background -->
+  <defs>
+    <radialGradient id="universalBg" cx="50%" cy="50%" r="70%">
+      <stop offset="0%" stop-color="#F8FAFC" stop-opacity="0.9"/>
+      <stop offset="100%" stop-color="#E2E8F0" stop-opacity="0.7"/>
+    </radialGradient>
+  </defs>
+  <rect width="256" height="256" fill="url(#universalBg)"/>
+  
+  <!-- Stylized collage pieces arranged in a pleasing composition -->
+  <path d="M40 60 L110 50 L120 90 L100 120 L60 110 L40 80 Z" 
+        fill="url(#primaryGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.9"/>
+  
+  <path d="M140 40 L210 60 L200 100 L180 90 L160 70 L140 60 Z" 
+        fill="url(#secondaryGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.85"/>
+  
+  <path d="M30 130 L90 120 L100 160 L80 180 L50 170 L30 150 Z" 
+        fill="url(#accentGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.8"/>
+  
+  <path d="M110 150 L190 160 L180 200 L150 210 L120 190 L110 170 Z" 
+        fill="url(#warningGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.85"/>
+  
+  <path d="M190 100 L230 120 L220 160 L200 150 L190 130 Z" 
+        fill="url(#primaryGrad)" 
+        filter="url(#dropShadow)" 
+        opacity="0.7"/>
+  
+  <!-- Central focus point -->
+  <circle cx="128" cy="128" r="8" fill="url(#secondaryGrad)" opacity="0.8"/>
+  
+  <!-- Clean, modern "JS" -->
+  <text x="128" y="145" 
+        font-family="'SF Pro Display', 'Segoe UI', -apple-system, sans-serif" 
+        font-size="36" 
+        font-weight="700" 
+        text-anchor="middle" 
+        fill="url(#primaryGrad)">JS</text>
+</svg>

package/dist/logos/logo.d.ts

@@ -0,0 +1,24 @@
+declare module "@collagejs/core/logo/16" {
+    const content: string;
+    export default content;
+}
+
+declare module "@collagejs/core/logo/48" {
+    const content: string;
+    export default content;
+}
+
+declare module "@collagejs/core/logo/64" {
+    const content: string;
+    export default content;
+}
+
+declare module "@collagejs/core/logo/128" {
+    const content: string;
+    export default content;
+}
+
+declare module "@collagejs/core/logo/512" {
+    const content: string;
+    export default content;
+}

package/dist/mountPiece.d.ts

@@ -0,0 +1,10 @@
+import { MountedPiece } from "./MountedPiece.js";
+import type { CorePiece } from "./types.js";
+export declare function mountPieceCore<TProps extends Record<string, any> = Record<string, any>>(this: MountedPiece | undefined, piece: CorePiece<TProps>, target: HTMLElement, props?: TProps): Promise<MountedPiece<TProps>>;
+/**
+ * Mounts the CollageJS piece as a child of the target element.
+ * @param piece The CollageJS piece to mount.
+ * @param target The target element to mount the piece to.
+ * @param props The properties to pass to the piece.
+ */
+export declare function mountPiece<TProps extends Record<string, any> = Record<string, any>>(piece: CorePiece<TProps>, target: HTMLElement, props?: TProps): Promise<import("./types.js").MountedPiece<TProps>>;

package/dist/mountPiece.js

@@ -0,0 +1,15 @@
+import { MountedPiece, mountKey } from "./MountedPiece.js";
+export async function mountPieceCore(piece, target, props) {
+    const mp = new MountedPiece(piece, (mountPieceCore), this);
+    await mp[mountKey](target, props);
+    return mp;
+}
+/**
+ * Mounts the CollageJS piece as a child of the target element.
+ * @param piece The CollageJS piece to mount.
+ * @param target The target element to mount the piece to.
+ * @param props The properties to pass to the piece.
+ */
+export function mountPiece(piece, target, props) {
+    return (mountPieceCore.bind(undefined))(piece, target, props);
+}

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+export type MountProps<TProps extends Record<string, any> = Record<string, any>> = TProps & {
+    [x: symbol]: MountPiece<TProps>;
+};
+export type UnmountFn = () => Promise<void>;
+export type MountFn<TProps extends Record<string, any> = Record<string, any>> = (target: HTMLElement, props?: MountProps<TProps>) => Promise<UnmountFn>;
+export type UpdateFn<TProps extends Record<string, any> = Record<string, any>> = (props: TProps) => Promise<void>;
+export type Mount<TProps extends Record<string, any> = Record<string, any>> = MountFn<TProps> | MountFn<TProps>[] | Mount<TProps>[];
+export type Update<TProps extends Record<string, any> = Record<string, any>> = UpdateFn<TProps> | UpdateFn<TProps>[] | Update[];
+export interface CorePiece<TProps extends Record<string, any> = Record<string, any>> {
+    mount: Mount<TProps>;
+    update?: Update<TProps>;
+}
+export type FactoryFnUntyped = () => Promise<CorePiece>;
+export type Factories = Record<string, FactoryFnUntyped>;
+export type CollageModule = {
+    bootstrap: UnmountFn;
+    unload: UnmountFn;
+    factories: Factories;
+};
+export interface MountedPiece<TProps extends Record<string, any> = Record<string, any>> {
+    update: UpdateFn<TProps>;
+    unmount: UnmountFn;
+    mountPiece: MountPiece<TProps>;
+}
+export type MountPiece<TProps extends Record<string, any> = Record<string, any>> = (piece: CorePiece<TProps>, target: HTMLElement, props?: TProps) => Promise<MountedPiece<TProps>>;

package/dist/types.js

@@ -0,0 +1,3 @@
+;
+;
+export {};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@collagejs/core",
+  "version": "0.1.0",
+  "description": "Core functionality for CollageJS.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "test": "npm run test:unit && npm run test:types",
+    "test:unit": "ts-mocha -n loader=ts-node/esm -p ./tsconfig.json --require ./tests/setup.ts ./tests/ut/**/*.test.ts",
+    "test:watch": "ts-mocha -n loader=ts-node/esm -p ./tsconfig.json --require ./tests/setup.ts ./tests/ut/**/*.test.ts --watch",
+    "test:types": "tstyche ./tests/typetests",
+    "build": "tsc && pwsh -File ./post-build.ps1 && publint",
+    "check": "tsc --noEmit"
+  },
+  "keywords": [
+    "collage",
+    "collage-js",
+    "single-spa",
+    "micro-frontend"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/collagejs/core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/collagejs/core/issues"
+  },
+  "homepage": "https://collagejs.dev",
+  "author": {
+    "email": "webJose@gmail.com",
+    "name": "José Pablo Ramírez Vargas"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./logo/16": {
+      "types": "./dist/logos/logo.d.ts",
+      "default": "./dist/logos/collagejs-16.svg"
+    },
+    "./logo/48": {
+      "types": "./dist/logos/logo.d.ts",
+      "default": "./dist/logos/collagejs-48.svg"
+    },
+    "./logo/64": {
+      "types": "./dist/logos/logo.d.ts",
+      "default": "./dist/logos/collagejs-64.svg"
+    },
+    "./logo/128": {
+      "types": "./dist/logos/logo.d.ts",
+      "default": "./dist/logos/collagejs-128.svg"
+    },
+    "./logo/512": {
+      "types": "./dist/logos/logo.d.ts",
+      "default": "./dist/logos/collagejs-512.svg"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/chai": "^5.2.2",
+    "@types/jsdom": "^27.0.0",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.0.1",
+    "@types/sinon": "^21.0.0",
+    "chai": "^6.0.1",
+    "jsdom": "^27.3.0",
+    "mocha": "^11.7.2",
+    "publint": "^0.3.11",
+    "sinon": "^21.0.0",
+    "ts-mocha": "^11.1.0",
+    "ts-node": "^10.9.2",
+    "tstyche": "^5.0.2",
+    "typescript": "^5.8.2"
+  }
+}