@cocreate/plugins 1.8.0 → 1.9.0

package/CONTRIBUTING.md

@@ -13,7 +13,7 @@ Fork the [project on Github](https://github.com/CoCreate-app/CoCreate-plugins) a
 ```
 git clone https://github.com/contributor/CoCreate-plugins.git
 cd CoCreate-plugins
-git remote add upstream https://github.com/CoCreate-app/CoCreate-plugins.git
+git remote add upstream https://gitlab.com/cocreatejs/CoCreate-plugins.git
 ```
 
 ## Create a Topic Branch

package/README.md

@@ -1,92 +1,432 @@
-# CoCreate-plugins
-
-CoCreate plugins Take it for a spin in our [playground!](https://cocreate.app/docs/plugins)
-
-![minified](https://img.badgesize.io/https://cdn.cocreate.app/plugins/latest/CoCreate-plugins.min.js?style=flat-square&label=minified&color=orange)
-![gzip](https://img.badgesize.io/https://cdn.cocreate.app/plugins/latest/CoCreate-plugins.min.js?compression=gzip&style=flat-square&label=gzip&color=yellow)
-![brotli](https://img.badgesize.io/https://cdn.cocreate.app/plugins/latest/CoCreate-plugins.min.js?compression=brotli&style=flat-square&label=brotli)
-![GitHub latest release](https://img.shields.io/github/v/release/CoCreate-app/CoCreate-plugins?style=flat-square)
-![GitHub contributors](https://img.shields.io/github/contributors/CoCreate-app/CoCreate-plugins?style=flat-square)
-![License](https://img.shields.io/static/v1?style=flat-square&label=license&message=AGPL-3.0&color=green)
-![Hiring](https://img.shields.io/static/v1?style=flat-square&label=&message=Hiring&color=blueviolet)
-
-![CoCreate-plugins](https://cdn.cocreate.app/docs/CoCreate-plugins.gif)
-
-## [Docs & Demo](https://cocreate.app/docs/plugins)
-
-For a complete guide and working demo refer to the [doumentation](https://cocreate.app/docs/plugins)
-
-## CDN
-
-```html
-<script src="https://cdn.cocreate.app/plugins/latest/CoCreate-plugins.min.js"></script>
-```
-
-```html
-<script src="https://cdn.cocreate.app/plugins/latest/CoCreate-plugins.min.css"></script>
-```
-
-## NPM
-
-```shell
-$ npm i @cocreate/plugins
-```
-
-## yarn
-
-```shell
-$ yarn install @cocreate/plugins
-```
-
-# Table of Contents
-
--   [Table of Contents](#table-of-contents)
--   [Announcements](#announcements)
--   [Roadmap](#roadmap)
--   [How to Contribute](#how-to-contribute)
--   [About](#about)
--   [License](#license)
-
-<a name="announcements"></a>
-
-# Announcements
-
-All updates to this library are documented in our [CHANGELOG](https://github.com/CoCreate-app/CoCreate-plugins/blob/master/CHANGELOG.md) and [releases](https://github.com/CoCreate-app/CoCreate-plugins/releases). You may also subscribe to email for releases and breaking changes.
-
-<a name="roadmap"></a>
-
-# Roadmap
-
-If you are interested in the future direction of this project, please take a look at our open [issues](https://github.com/CoCreate-app/CoCreate-plugins/issues) and [pull requests](https://github.com/CoCreate-app/CoCreate-plugins/pulls). We would love to hear your feedback.
-
-<a name="about"></a>
-
-# About
-
-CoCreate-plugins is guided and supported by the CoCreate Developer Experience Team.
-
-Please Email the Developer Experience Team [here](mailto:develop@cocreate.app) in case of any queries.
-
-CoCreate-plugins is maintained and funded by CoCreate. The names and logos for CoCreate are trademarks of CoCreate, LLC.
-
-<a name="contribute"></a>
-
-# How to Contribute
-
-We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING](https://github.com/CoCreate-app/CoCreate-plugins/blob/master/CONTRIBUTING.md) guide for details.
-
-We want this library to be community-driven, and CoCreate led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create [issues](https://github.com/CoCreate-app/CoCreate-plugins/issues) and [pull requests](https://github.com/CoCreate-app/CoCreate-plugins/pulls) or merely upvote or comment on existing issues or pull requests.
-
-We appreciate your continued support, thank you!
-
-<a name="license"></a>
-
-# License
-
-This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
-
--   **Open Source Use**: For open-source projects and non-commercial use, this software is available under the AGPLv3. The AGPLv3 allows you to freely use, modify, and distribute this software, provided that all modifications and derivative works are also licensed under the AGPLv3. For the full license text, see the [LICENSE file](https://github.com/CoCreate-app/CoCreate-plugins/blob/master/LICENSE).
-
--   **Commercial Use**: For-profit companies and individuals intending to use this software for commercial purposes must obtain a commercial license. The commercial license is available when you sign up for an API key on our [website](https://cocreate.app). This license permits proprietary use and modification of the software without the copyleft requirements of the AGPLv3. It is ideal for integrating this software into proprietary commercial products and applications.
-
-If you have not purchased a commercial license and intend to use this software for commercial purposes, you are required to sign up for an API key on our website.
+# CoCreate Plugins
+
+A declarative browser plugin loader and runtime for CoCreate. It loads registered JavaScript and CSS resources, exposes their browser globals to the CoCreate AST, initializes plugin instances on DOM elements, and connects those instances to standard element value APIs.
+
+---
+
+## Documentation
+
+For interactive examples, visit the [CoCreate Plugins documentation](https://cocreate.app/docs/plugins).
+
+## Table of Contents
+
+- [Architectural Overview](#architectural-overview)
+- [Installation](#installation)
+- [Registering Plugin Resources](#registering-plugin-resources)
+- [Using the `plugin` Attribute](#using-the-plugin-attribute)
+- [AST Execution Model](#ast-execution-model)
+- [Element Value Integration](#element-value-integration)
+- [Programmatic API](#programmatic-api)
+- [Resource Loading](#resource-loading)
+- [Error Handling](#error-handling)
+- [Security](#security)
+- [Announcements](#announcements)
+- [Roadmap](#roadmap)
+- [How to Contribute](#how-to-contribute)
+- [License](#license)
+
+---
+
+## Architectural Overview
+
+`@cocreate/plugins` connects three parts of the browser runtime:
+
+1. A plugin definition in `window.CoCreateConfig.plugins` identifies the JavaScript and CSS resources.
+2. A DOM element's `plugin` attribute contains an AST configuration.
+3. The resolved plugin instance and other top-level AST values are attached to that element.
+
+```text
+CoCreateConfig.plugins
+        │
+        ├── load JavaScript and CSS
+        │
+        ▼
+window.PluginName
+        │
+        ├── AST executes plugin configuration
+        │
+        ▼
+element.PluginName
+```
+
+Plugin configurations execute sequentially. A constructor result created by one top-level key is therefore available to every key that follows it.
+
+The module observes `[plugin]` elements automatically, including elements added or updated after the initial page load.
+
+---
+
+## Installation
+
+### NPM
+
+```shell
+npm install @cocreate/plugins
+```
+
+### Yarn
+
+```shell
+yarn add @cocreate/plugins
+```
+
+### CDN
+
+```html
+<script src="https://cdn.cocreate.app/plugins/latest/CoCreate-plugins.min.js"></script>
+```
+
+When using the package as a module:
+
+```javascript
+import plugins from "@cocreate/plugins";
+```
+
+---
+
+## Registering Plugin Resources
+
+Plugin resource definitions live under `window.CoCreateConfig.plugins`. The property name should match the global name created by the external library.
+
+```javascript
+window.CoCreateConfig = {
+    plugins: {
+        SimpleBar: {
+            js: "https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.min.js",
+            css: "https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.css"
+        },
+        FullCalendar: {
+            js: "https://cdn.jsdelivr.net/npm/fullcalendar@6.1.15/index.global.min.js"
+        }
+    }
+};
+```
+
+Both `js` and `css` accept one resource or an array of resources. A resource can be a URL string or an object:
+
+```javascript
+window.CoCreateConfig.plugins.Example = {
+    js: [
+        {
+            src: "https://cdn.example.com/example.min.js",
+            crossOrigin: "anonymous",
+            integrity: "sha384-..."
+        }
+    ],
+    css: [
+        {
+            href: "https://cdn.example.com/example.min.css",
+            crossOrigin: "anonymous",
+            integrity: "sha384-..."
+        }
+    ]
+};
+```
+
+Plugins can also be registered at runtime:
+
+```javascript
+import { registerPlugin } from "@cocreate/plugins";
+
+registerPlugin("SimpleBar", {
+    js: "https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.min.js",
+    css: "https://cdn.jsdelivr.net/npm/simplebar@latest/dist/simplebar.css"
+});
+```
+
+Registration describes where a library is loaded from. Initialization behavior belongs in the element's `plugin` attribute.
+
+---
+
+## Using the `plugin` Attribute
+
+### Constructor or Function
+
+The simplest object form calls the registered global and assigns its result to the element under the same name.
+
+```html
+<div
+    plugin='{
+        "SimpleBar": ["$this", {}]
+    }'
+    style="max-height: 300px">
+</div>
+```
+
+This is conceptually equivalent to:
+
+```javascript
+element.SimpleBar = new SimpleBar(element, {});
+```
+
+`$this` resolves to the element containing the `plugin` attribute.
+
+For a global function that receives a single options object:
+
+```html
+<button
+    plugin='{
+        "Toastify": {
+            "text": "Saved successfully",
+            "duration": 3000
+        },
+        "Toastify.showToast": []
+    }'>
+    Show notification
+</button>
+```
+
+### Nested Constructor
+
+Some libraries expose constructors as properties of a global namespace. A single nested member identifies the constructor to invoke:
+
+```html
+<div
+    id="calendar"
+    plugin='{
+        "FullCalendar": {
+            "Calendar": [
+                "$this",
+                {
+                    "initialView": "dayGridMonth",
+                    "editable": true
+                }
+            ]
+        },
+        "FullCalendar.render": []
+    }'>
+</div>
+```
+
+The first key creates the instance:
+
+```javascript
+element.FullCalendar = new window.FullCalendar.Calendar(element, options);
+```
+
+The next key operates on that resolved instance:
+
+```javascript
+element.FullCalendar.render();
+```
+
+### Bare Plugin Name
+
+A plain attribute value invokes the registered global without arguments:
+
+```html
+<div plugin="ExamplePlugin"></div>
+```
+
+Use the JSON form whenever the plugin requires the element, options, or additional operations.
+
+### Multiple Configuration Blocks
+
+The attribute can contain an array. Each object is processed in order:
+
+```html
+<div
+    plugin='[
+        { "FirstPlugin": ["$this"] },
+        { "SecondPlugin": ["$this", {}] }
+    ]'>
+</div>
+```
+
+---
+
+## AST Execution Model
+
+Each configuration object is converted into one AST program and evaluated sequentially.
+
+```json
+{
+    "FullCalendar": {
+        "Calendar": ["$this", {}]
+    },
+    "FullCalendar.render": []
+}
+```
+
+Conceptually becomes:
+
+```json
+{
+    "FullCalendar": {
+        "$FullCalendar.Calendar": ["$this", {}]
+    },
+    "FullCalendar.render": {
+        "$FullCalendar.render": []
+    }
+}
+```
+
+Execution follows these rules:
+
+- Plugin globals are placed in the AST sandbox.
+- `$this` is the element being initialized.
+- Arrays are passed as positional arguments.
+- An object is passed as a single argument.
+- Native classes are instantiated with `new`.
+- Functions are called normally.
+- A resolved top-level value becomes available to subsequent keys.
+- Resolved top-level keys without dot notation are attached to the element.
+- Dotted keys represent operations and are not attached as element properties.
+
+Ordinary non-plugin keys remain part of the AST program, so they can store intermediate results or participate in later operations.
+
+```html
+<div
+    plugin='{
+        "ExamplePlugin": ["$this"],
+        "items": { "$ExamplePlugin.getItems": [] },
+        "count": "$items.length"
+    }'>
+</div>
+```
+
+After evaluation, `element.ExamplePlugin`, `element.items`, and `element.count` contain the corresponding resolved values.
+
+---
+
+## Element Value Integration
+
+The reserved `getValue` and `setValue` keys connect a plugin instance to CoCreate's standard element value interface. Unlike initialization operations, these AST expressions are stored and evaluated only when the corresponding element method is called.
+
+```html
+<div
+    id="calendar"
+    component
+    plugin='{
+        "FullCalendar": {
+            "Calendar": ["$this", { "events": [] }]
+        },
+        "FullCalendar.render": [],
+        "getValue": "$FullCalendar.getEvents",
+        "setValue": {
+            "$FullCalendar.addEvent": "$event.value"
+        }
+    }'>
+</div>
+```
+
+### Reading a Value
+
+```javascript
+const events = document.querySelector("#calendar").getValue();
+```
+
+The string method reference is invoked with no arguments. Asynchronous consumers can use:
+
+```javascript
+const events = await document.querySelector("#calendar").getValueAsync();
+```
+
+### Setting a Value
+
+```javascript
+document.querySelector("#calendar").setValue({
+    title: "Planning meeting",
+    start: "2026-09-01"
+});
+```
+
+The runtime scope exposes:
+
+| AST value | Description |
+| --- | --- |
+| `$event.value` | Value passed to `element.setValue(value)` |
+| `$event.dispatch` | Optional dispatch argument passed to `setValue` |
+| `$this` | Element containing the plugin instance |
+| `$PluginName` | Resolved plugin instance |
+
+---
+
+## Programmatic API
+
+### `registerPlugin(name, config)`
+
+Registers or replaces a resource definition in `window.CoCreateConfig.plugins`.
+
+```javascript
+registerPlugin("ExamplePlugin", {
+    js: "https://cdn.example.com/plugin.js",
+    css: "https://cdn.example.com/plugin.css"
+});
+```
+
+### `init(elements)`
+
+Finds and initializes plugin configurations. It accepts an element, collection, array, or selector and returns a promise.
+
+```javascript
+import { init } from "@cocreate/plugins";
+
+await init(document.querySelector("#calendar"));
+await init(document.querySelectorAll("[plugin]"));
+await init("[plugin]");
+```
+
+Calling `init()` directly is generally unnecessary because the module observes matching elements automatically. It is useful when application code needs to wait for plugin initialization to complete.
+
+---
+
+## Resource Loading
+
+- JavaScript resources are cached by URL and loaded once.
+- CSS resources already present in the document are not inserted again.
+- Multiple resources are loaded concurrently with `Promise.allSettled()`.
+- String resource definitions default to `crossOrigin="anonymous"`.
+- Object definitions can override `crossOrigin` or provide `integrity`.
+- After loading, the runtime waits briefly for the expected browser global.
+
+The configured name should match the library's browser global. A capitalized fallback is supported, so a configured `simpleBar` can resolve `window.SimpleBar`, but using the exact global name is recommended.
+
+---
+
+## Error Handling
+
+Resource failures are logged as warnings. Initialization fails when the expected global is still unavailable after loading:
+
+```text
+[Plugin System] Plugin 'ExamplePlugin' is not available on window.
+```
+
+Invalid JSON, AST failures, constructor errors, and method errors are reported with the original `plugin` attribute for debugging.
+
+Because initialization is asynchronous, application code that requires a completed instance should await `init()`.
+
+---
+
+## Security
+
+Plugin scripts execute with the same browser privileges as the application. Only register resources from trusted locations.
+
+For third-party CDN resources:
+
+- Pin versions instead of relying on floating tags such as `latest`.
+- Provide Subresource Integrity metadata when available.
+- Use an appropriate Content Security Policy.
+- Review the library's data access and network behavior.
+
+AST configuration controls how an already trusted plugin is initialized; it does not isolate untrusted JavaScript.
+
+---
+
+## Announcements
+
+Updates are documented in the project [CHANGELOG](https://github.com/CoCreate-app/CoCreate-plugins/blob/master/CHANGELOG.md) and [releases](https://github.com/CoCreate-app/CoCreate-plugins/releases).
+
+## Roadmap
+
+See the open [issues](https://github.com/CoCreate-app/CoCreate-plugins/issues) and [pull requests](https://github.com/CoCreate-app/CoCreate-plugins/pulls) for current development priorities.
+
+## How to Contribute
+
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/CoCreate-app/CoCreate-plugins/blob/master/CONTRIBUTING.md) before opening an issue or pull request.
+
+## License
+
+This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
+
+- **Open-source use:** Modifications and derivative works must comply with the AGPLv3. See the [LICENSE](https://github.com/CoCreate-app/CoCreate-plugins/blob/master/LICENSE).
+- **Commercial use:** A commercial license is available from [CoCreate](https://cocreate.app).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocreate/plugins",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "CoCreate plugins",
   "author": "CoCreate LLC",
   "license": "AGPL-3.0",
@@ -14,7 +14,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/CoCreate-app/CoCreate-plugins.git"
+    "url": "git+https://gitlab.com/cocreatejs/CoCreate-plugins.git"
   },
   "bugs": {
     "url": "https://github.com/CoCreate-app/CoCreate-plugins/issues"
@@ -27,14 +27,15 @@
   "type": "module",
   "main": "./src/index.js",
   "dependencies": {
-    "@cocreate/observer": "^1.22.0"
+    "@cocreate/observer": "^1.23.0",
+    "@cocreate/utils": "^1.54.0"
   },
   "devDependencies": {
-    "@cocreate/webpack": "^1.8.0"
+    "@cocreate/webpack": "^1.9.0"
   },
   "allowScripts": {
     "@cocreate/observer@1.19.0": true,
-    "@cocreate/utils@1.42.2": true,
+    "@cocreate/utils@1.52.0": true,
     "@cocreate/webpack@1.4.3": true
   }
 }

package/src/index.js

@@ -2,7 +2,9 @@ import Observer from '@cocreate/observer';
 import { astAsync } from '@cocreate/utils';
 
 const scriptCache = new Map();
-const cssMarker = typeof document !== 'undefined' 
+const pendingElements = new WeakSet();
+const initializedPlugins = new WeakMap();
+const cssMarker = typeof document !== 'undefined'
     ? document.head.querySelector('meta[name="viewport"]') || document.head.lastChild 
     : null;
 
@@ -110,7 +112,8 @@ function loadCSS(item) {
 
 /**
  * Preloads JS scripts and CSS stylesheets declared in global plugins config.
- * Runs in parallel using Promise.allSettled.
+ * Loads each plugin's JavaScript resources in declared order while allowing
+ * independent plugins and stylesheets to load in parallel.
  * @param {Array<string>} pluginNames - Names of target plugins to preload
  */
 async function preloadResources(pluginNames) {
@@ -126,7 +129,11 @@ async function preloadResources(pluginNames) {
             }
             if (config.js) {
                 const jsFiles = Array.isArray(config.js) ? config.js : [config.js];
-                jsFiles.forEach(src => promises.push(loadScript(src)));
+                promises.push((async () => {
+                    for (const src of jsFiles) {
+                        await loadScript(src);
+                    }
+                })());
             }
         }
     }
@@ -171,6 +178,91 @@ function getPluginLibrary(pluginName) {
     return null;
 }
 
+function getPluginNames(configBlock) {
+    const configuredPlugins = getPluginsConfig();
+    const pluginNames = new Set();
+
+    function collect(value) {
+        if (!value || typeof value !== 'object') return;
+
+        for (const [key, childValue] of Object.entries(value)) {
+            const name = key.replace(/^\$/, '').split('.')[0];
+            if (configuredPlugins[name] || getPluginLibrary(name)) {
+                pluginNames.add(name);
+            }
+            collect(childValue);
+        }
+    }
+
+    collect(configBlock);
+
+    return pluginNames;
+}
+
+function isClassLike(value) {
+    if (typeof value !== 'function') return false;
+
+    const source = Function.prototype.toString.call(value);
+    if (/^class\s|^class{/.test(source)) return true;
+
+    return !!value.prototype && Object.getOwnPropertyNames(value.prototype)
+        .some(member => member !== 'constructor');
+}
+
+function getPluginMember(library, path) {
+    let value = library;
+
+    for (const property of path) {
+        if (value === null || value === undefined || !(property in Object(value))) {
+            return undefined;
+        }
+        value = value[property];
+    }
+
+    return value;
+}
+
+function createPluginOperations(configBlock, pluginNames, libraries) {
+    const operations = [];
+
+    for (const [key, value] of Object.entries(configBlock)) {
+        const normalizedKey = key.replace(/^\$/, '');
+        const pluginName = normalizedKey.split('.')[0];
+
+        if (!pluginNames.has(pluginName)) {
+            operations.push({ ast: { [key]: value } });
+            continue;
+        }
+
+        let operator = normalizedKey;
+        let parameters = value;
+        const library = libraries['$' + pluginName];
+        const memberPath = normalizedKey.split('.').slice(1);
+        const pluginMember = getPluginMember(library, memberPath);
+        const members = value && typeof value === 'object' && !Array.isArray(value)
+            ? Object.entries(value)
+            : [];
+
+        if (
+            !normalizedKey.includes('.') &&
+            typeof library !== 'function' &&
+            members.length === 1
+        ) {
+            const [member, memberParameters] = members[0];
+            operator = `${pluginName}.${member.replace(/^\$/, '')}`;
+            parameters = memberParameters;
+        }
+
+        operations.push({
+            ast: { ['$' + operator]: parameters },
+            pluginName,
+            attach: !normalizedKey.includes('.') || isClassLike(pluginMember)
+        });
+    }
+
+    return operations;
+}
+
 /**
  * Parses element 'plugin' attribute, executes AST configuration via astAsync,
  * sets core library on window, and attaches instance onto element property.
@@ -183,6 +275,11 @@ async function processPlugin(el) {
     const rawPluginAttr = pluginAttrNode?.value?.trim();
     if (!rawPluginAttr) return;
 
+    // Added-node and attribute observers can discover the same element during
+    // separate mutation cycles. Do not initialize an unchanged plugin twice.
+    if (initializedPlugins.get(el) === rawPluginAttr) return;
+    initializedPlugins.set(el, rawPluginAttr);
+
     try {
         let configs = [];
 
@@ -193,62 +290,64 @@ async function processPlugin(el) {
             configs = [{ [rawPluginAttr]: [] }];
         }
 
-        const targetPlugins = new Set();
-        configs.forEach(conf => {
-            Object.keys(conf).forEach(k => {
-                if (!k.startsWith('\u0024')) {
-                    targetPlugins.add(k.split('.')[0]);
-                }
-            });
-        });
+        const configPlans = configs.map(configBlock => ({
+            configBlock,
+            pluginNames: getPluginNames(configBlock)
+        }));
+        const targetPlugins = new Set(
+            configPlans.flatMap(({ pluginNames }) => Array.from(pluginNames))
+        );
 
         await preloadResources(Array.from(targetPlugins));
 
-        for (const configBlock of configs) {
-            for (const [pluginName, astValue] of Object.entries(configBlock)) {
-                // Poll window to ensure script execution has completed
-                const pluginLib = await waitForPluginOnWindow(pluginName);
+        for (const { configBlock, pluginNames } of configPlans) {
+            const libraries = {};
 
-                // Ensure plugin library definition is attached to window once loaded
-                if (pluginLib && typeof window !== 'undefined' && !window[pluginName]) {
-                    window[pluginName] = pluginLib;
+            for (const pluginName of pluginNames) {
+                const library = await waitForPluginOnWindow(pluginName);
+                if (!library) {
+                    throw new Error(`Plugin '${pluginName}' is not available on window.`);
                 }
+                libraries['$' + pluginName] = library;
+            }
 
-                // Format operator key with $ for AST engine recognition (e.g. SimpleBar -> $SimpleBar)
-                const operatorName = pluginName.startsWith('\u0024') ? pluginName : `$${pluginName}`;
-
-                // Create constructor wrapper to safely instantiate class/function
-                const opWrapper = function(params) {
-                    const args = Array.isArray(params) ? params : [params];
-                    if (typeof pluginLib === 'function') {
-                        try {
-                            return new pluginLib(...args);
-                        } catch (e) {
-                            return pluginLib(...args);
-                        }
-                    }
-                    return pluginLib;
-                };
-
-                // Provide operator wrapper in context for AST registry lookup
-                const context = {
-                    [operatorName]: opWrapper
-                };
-
-                // Execute AST with the $ operator key so astAsync invokes operatorKey logic
-                const result = await astAsync({
-                    node: el,
-                    sandbox: context,
-                    executeAST: { [operatorName]: astValue }
+            const scope = { ...libraries, $this: el };
+
+            if (Object.prototype.hasOwnProperty.call(configBlock, '$return')) {
+                const value = await astAsync({
+                    executeAST: configBlock,
+                    sandbox: scope,
+                    node: el
                 });
 
-                if (result !== undefined && !pluginName.startsWith('\u0024')) {
-                    // Attach returned plugin instance directly onto element property
-                    el[pluginName] = result;
+                if (value !== undefined && pluginNames.size === 1) {
+                    const [pluginName] = pluginNames;
+                    el[pluginName] = value;
+                }
+                continue;
+            }
+
+            const operations = createPluginOperations(
+                configBlock,
+                pluginNames,
+                libraries
+            );
+
+            for (const operation of operations) {
+                const value = await astAsync({
+                    executeAST: operation.ast,
+                    sandbox: scope,
+                    node: el
+                });
+
+                if (operation.attach && value !== undefined) {
+                    scope['$' + operation.pluginName] = value;
+                    el[operation.pluginName] = value;
                 }
             }
         }
     } catch (err) {
+        initializedPlugins.delete(el);
         console.error('[Plugin System] Failed to parse and execute plugin configuration:', err, rawPluginAttr);
     }
 }
@@ -258,21 +357,33 @@ async function processPlugin(el) {
  * @param {Element|NodeList|Array|string} elements - Target element(s) or DOM query selector
  */
 export function init(elements) {
-    if (!elements) return;
+    if (!elements) return Promise.resolve([]);
 
     if (typeof elements === 'string') {
         elements = document.querySelectorAll(elements);
     }
 
     if (elements instanceof Element) {
-        processPlugin(elements);
+        return processPlugin(elements);
     } else if (elements.length !== undefined || Array.isArray(elements)) {
-        Array.from(elements).forEach(el => {
-            if (el instanceof Element) {
-                processPlugin(el);
-            }
-        });
+        return Promise.all(
+            Array.from(elements)
+                .filter(el => el instanceof Element)
+                .map(el => processPlugin(el))
+        );
     }
+
+    return Promise.resolve([]);
+}
+
+function scheduleInit(element) {
+    if (!element || pendingElements.has(element)) return;
+
+    pendingElements.add(element);
+    requestAnimationFrame(() => {
+        pendingElements.delete(element);
+        if (element.isConnected) init(element);
+    });
 }
 
 if (typeof document !== 'undefined') {
@@ -282,10 +393,12 @@ if (typeof document !== 'undefined') {
         types: ["addedNodes", "attributes"],
         selector: selector,
         attributeFilter: ["plugin"],
-        callback: (mutation) => init(mutation.target)
+        callback: (mutation) => {
+            scheduleInit(mutation.target);
+        }
     });
 
     init(document.querySelectorAll(selector));
 }
 
-export default { init, registerPlugin };
+export default { init, registerPlugin };

package/webpack.config.js

@@ -1,9 +1,13 @@
-const path = require("path");
-const MiniCssExtractPlugin = require("mini-css-extract-plugin");
-const { EsbuildPlugin } = require("esbuild-loader");
-const { FileUploader } = require("@cocreate/webpack");
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import MiniCssExtractPlugin from "mini-css-extract-plugin";
+import { EsbuildPlugin } from "esbuild-loader";
+import webpackPackage from "@cocreate/webpack";
 
-module.exports = async (env, argv) => {
+const { FileUploader } = webpackPackage;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default async (env, argv) => {
 	const isProduction = argv && argv.mode === "production";
 	const config = {
 		entry: {
@@ -52,7 +56,7 @@ module.exports = async (env, argv) => {
 				})
 			],
 			splitChunks: {
-				pluginsGroups: {
+				cacheGroups: {
 					defaultVendors: false
 				}
 			}