@cocreate/plugins 1.4.2 → 1.6.0

package/.github/workflows/automated.yml

@@ -9,33 +9,36 @@ jobs:
   about:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 16
-      - name: Jaid/action-sync-node-meta
-        uses: jaid/action-sync-node-meta@v1.4.0
-        with:
-          direction: overwrite-github
-          githubToken: "${{ secrets.GITHUB }}"
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Sync package.json description to GitHub About
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB }}
+        run: |
+          DESC=$(jq -r '.description // empty' package.json)
+          if [ -n "$DESC" ]; then
+            echo "Updating repository description to: $DESC"
+            gh api -X PATCH repos/${{ github.repository }} -f description="$DESC"
+          else
+            echo "No description found in package.json."
+          fi
 
   release:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v7
         with:
-          fetch-depth: 0 # Required so semantic-release can trace git tags/history
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB }} # Authenticates git CLI for tag/commit pushes
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
-          node-version: 22
+          node-version: '24'
 
       - name: Install Semantic Release & Plugins
-        # Installs semantic-release and its plugins on the runner
         run: |
           npm install -g semantic-release \
             @semantic-release/changelog \
@@ -43,12 +46,11 @@ jobs:
             @semantic-release/github \
             @semantic-release/git
 
-      - name: Run Semantic Release (Native)
+      - name: Run Semantic Release
         id: semantic
-        # This will automatically pick up your export default config file in the repository root
         run: npx semantic-release
         env:
-          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+          GITHUB_TOKEN: "${{ secrets.GITHUB }}"
           NPM_TOKEN: "${{ secrets.NPM_TOKEN }}"
 
     outputs:

package/CoCreate.config.js

@@ -1,4 +1,4 @@
-module.exports = {
+export default {
     "organization_id": "",
     "key": "",
     "host": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocreate/plugins",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "description": "CoCreate plugins",
   "author": "CoCreate LLC",
   "license": "AGPL-3.0",
@@ -24,12 +24,13 @@
     "type": "GitHub Sponsors ❤",
     "url": "https://github.com/sponsors/CoCreate-app"
   },
+  "type": "module",
   "main": "./src/index.js",
   "dependencies": {
-    "@cocreate/observer": "^1.20.0"
+    "@cocreate/observer": "^1.21.0"
   },
   "devDependencies": {
-    "@cocreate/webpack": "^1.6.0"
+    "@cocreate/webpack": "^1.7.0"
   },
   "allowScripts": {
     "@cocreate/observer@1.19.0": true,

package/src/index.js

@@ -1,236 +1,277 @@
-/********************************************************************************
- * Copyright (C) 2026 CoCreate and Contributors.
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- ********************************************************************************/
-
-import Observer from "@cocreate/observer";
-import { processOperators } from "./operators.js";
-
-const plugins = {};
+import Observer from '@cocreate/observer';
+import { astAsync } from '@cocreate/utils';
+
 const scriptCache = new Map();
-const cssMarker = typeof document !== 'undefined' ? document.querySelector('link[plugins]') : null;
+const cssMarker = typeof document !== 'undefined' 
+    ? document.head.querySelector('meta[name="viewport"]') || document.head.lastChild 
+    : null;
 
 /**
- * Initializes plugins on a collection of HTML elements.
- * @param {HTMLElement|HTMLElement[]|NodeList} elements 
+ * Retrieves the global plugin configuration object from window.CoCreateConfig.
+ * @returns {Object}
  */
-export function init(elements) {
-    if (!elements) return;
-    const collection = (elements instanceof HTMLElement || elements instanceof Element) 
-        ? [elements] 
-        : Array.from(elements);
-    
-    collection.forEach(el => {
-        if (el) {
-            processPlugin(el);
+function getPluginsConfig() {
+    if (typeof window !== 'undefined' && window.CoCreateConfig && window.CoCreateConfig.plugins) {
+        return window.CoCreateConfig.plugins;
+    }
+    return {};
+}
+
+/**
+ * Dynamically registers or updates a plugin definition in global config.
+ * @param {string} name - Plugin identifier
+ * @param {Object} config - Plugin configuration object (js, css, etc.)
+ */
+export function registerPlugin(name, config) {
+    if (typeof window !== 'undefined') {
+        window.CoCreateConfig = window.CoCreateConfig || {};
+        window.CoCreateConfig.plugins = window.CoCreateConfig.plugins || {};
+        window.CoCreateConfig.plugins[name] = config;
+    }
+}
+
+/**
+ * Dynamic script loader to ensure plugin scripts are loaded once.
+ * Sets crossOrigin="anonymous" by default for simple string URLs.
+ * @param {string|Object} item - Script URL or object with configuration
+ * @returns {Promise<void>}
+ */
+function loadScript(item) {
+    const src = typeof item === 'string' ? item : item?.src;
+    if (!src) return Promise.resolve();
+
+    if (scriptCache.has(src)) return scriptCache.get(src);
+
+    const promise = new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.src = src;
+        script.async = true;
+
+        // Default crossOrigin to "anonymous" unless explicitly set otherwise in an object
+        const crossOrigin = typeof item === 'object' && 'crossOrigin' in item ? item.crossOrigin : 'anonymous';
+        if (crossOrigin) {
+            script.crossOrigin = crossOrigin;
+        }
+
+        if (typeof item === 'object' && item.integrity) {
+            script.integrity = item.integrity;
+        }
+
+        script.onload = () => resolve();
+        script.onerror = () => {
+            scriptCache.delete(src);
+            reject(new Error(`Failed to load script: ${src}`));
+        };
+        document.head.appendChild(script);
+    });
+
+    scriptCache.set(src, promise);
+    return promise;
+}
+
+/**
+ * Dynamic CSS stylesheet loader for plugins.
+ * Sets crossOrigin="anonymous" by default for simple string URLs.
+ * @param {string|Object} item - Stylesheet URL or object with configuration
+ * @returns {Promise<void>}
+ */
+function loadCSS(item) {
+    const href = typeof item === 'string' ? item : item?.href;
+    if (!href) return Promise.resolve();
+
+    return new Promise((resolve, reject) => {
+        if (document.querySelector(`link[href="${href}"]`)) {
+            return resolve();
+        }
+        const link = document.createElement('link');
+        link.rel = 'stylesheet';
+        link.href = href;
+
+        // Default crossOrigin to "anonymous" unless explicitly set otherwise in an object
+        const crossOrigin = typeof item === 'object' && 'crossOrigin' in item ? item.crossOrigin : 'anonymous';
+        if (crossOrigin) {
+            link.crossOrigin = crossOrigin;
+        }
+
+        if (typeof item === 'object' && item.integrity) {
+            link.integrity = item.integrity;
+        }
+
+        link.onload = () => resolve();
+        link.onerror = () => reject(new Error(`Failed to load stylesheet: ${href}`));
+
+        if (cssMarker && cssMarker.parentNode) {
+            cssMarker.parentNode.insertBefore(link, cssMarker);
+        } else {
+            document.head.appendChild(link);
         }
     });
 }
 
+/**
+ * Preloads JS scripts and CSS stylesheets declared in global plugins config.
+ * Runs in parallel using Promise.allSettled.
+ * @param {Array<string>} pluginNames - Names of target plugins to preload
+ */
 async function preloadResources(pluginNames) {
+    const plugins = getPluginsConfig();
+    const promises = [];
+
     for (const name of pluginNames) {
-        const pluginDef = plugins[name];
-        if (pluginDef && !window[name]) {
-            if (pluginDef.css) {
-                pluginDef.css.forEach(href => {
-                    if (!document.querySelector(`link[href="${href}"]`)) {
-                        const link = document.createElement("link");
-                        link.rel = "stylesheet"; 
-                        link.href = href;
-                        if (cssMarker) cssMarker.parentNode.insertBefore(link, cssMarker);
-                        else document.head.appendChild(link);
-                    }
-                });
+        const config = plugins[name];
+        if (config) {
+            if (config.css) {
+                const cssFiles = Array.isArray(config.css) ? config.css : [config.css];
+                cssFiles.forEach(href => promises.push(loadCSS(href)));
             }
-
-            if (pluginDef.js) {
-                for (const item of pluginDef.js) {
-                    const src = typeof item === 'string' ? item : item.src;
-                    if (!src) continue;
-                    if (!scriptCache.has(src)) {
-                        const existingScript = document.querySelector(`script[src*="${src}"]`);
-                        if (existingScript && (existingScript.dataset.loaded === "true" || window[name])) {
-                            scriptCache.set(src, Promise.resolve());
-                        } else {
-                            const s = document.createElement("script");
-                            s.src = src;
-                            scriptCache.set(src, new Promise((resolve) => {
-                                s.onload = () => { s.dataset.loaded = "true"; resolve(); };
-                                s.onerror = () => resolve();
-                                document.head.appendChild(s);
-                            }));
-                        }
-                    }
-                    await scriptCache.get(src);
-                }
+            if (config.js) {
+                const jsFiles = Array.isArray(config.js) ? config.js : [config.js];
+                jsFiles.forEach(src => promises.push(loadScript(src)));
             }
         }
     }
+
+    const results = await Promise.allSettled(promises);
+    results.forEach(res => {
+        if (res.status === 'rejected') {
+            console.warn('[Plugin System]', res.reason.message || res.reason);
+        }
+    });
+}
+
+/**
+ * Helper to poll window for plugin library constructor if not immediately present.
+ * @param {string} pluginName - Target plugin identifier
+ * @param {number} retries - Number of retries
+ * @param {number} delay - Retry interval in ms
+ * @returns {Promise<Function|Object|null>}
+ */
+async function waitForPluginOnWindow(pluginName, retries = 5, delay = 50) {
+    for (let i = 0; i < retries; i++) {
+        const lib = getPluginLibrary(pluginName);
+        if (lib) return lib;
+        await new Promise(res => setTimeout(res, delay));
+    }
+    return getPluginLibrary(pluginName);
 }
 
+/**
+ * Helper to resolve and normalize plugin library constructor from window object.
+ * @param {string} pluginName - The target plugin identifier
+ * @returns {Function|Object|null}
+ */
+function getPluginLibrary(pluginName) {
+    if (typeof window === 'undefined') return null;
+    if (window[pluginName]) return window[pluginName];
+
+    // Try capitalized variant (e.g. 'simpleBar' -> 'SimpleBar')
+    const capitalized = pluginName.charAt(0).toUpperCase() + pluginName.slice(1);
+    if (window[capitalized]) return window[capitalized];
+
+    return null;
+}
+
+/**
+ * Parses element 'plugin' attribute, executes AST configuration via astAsync,
+ * sets core library on window, and attaches instance onto element property.
+ * @param {Element} el - DOM element with plugin attribute
+ */
 async function processPlugin(el) {
-    if (!el.attributes) return;
+    if (!el || !el.attributes) return;
 
-    // Direct attributes collection map lookup to avoid binding/context prototype errors
     const pluginAttrNode = el.attributes['plugin'] || el.attributes.getNamedItem?.('plugin');
     const rawPluginAttr = pluginAttrNode?.value?.trim();
     if (!rawPluginAttr) return;
 
-    const context = {
-        element: el,
-        this: el,
-        plugin: null,  // Tracks active sibling plugin instance
-        data: { ...el.dataset },
-        event: {},
-        crud: window.CoCreate?.crud || null
-    };
-
     try {
         let configs = [];
-        
-        // Unified Direct Parser: Pure JSON parsing with simple zero-argument fallback
+
         if (rawPluginAttr.startsWith('{') || rawPluginAttr.startsWith('[')) {
             const parsedConfig = JSON.parse(rawPluginAttr);
             configs = Array.isArray(parsedConfig) ? parsedConfig : [parsedConfig];
         } else {
-            // Symmetrical Fallback: Plain strings mapped straight to constructor blocks
             configs = [{ [rawPluginAttr]: [] }];
         }
-        
+
         const targetPlugins = new Set();
         configs.forEach(conf => {
             Object.keys(conf).forEach(k => {
-                if (!k.startsWith('$')) {
+                if (!k.startsWith('\u0024')) {
                     targetPlugins.add(k.split('.')[0]);
                 }
             });
         });
-        
+
         await preloadResources(Array.from(targetPlugins));
 
-        // Execute each configuration block sequentially
         for (const configBlock of configs) {
-            await executeConfigBlock(context, configBlock);
-        }
-    } catch (err) {
-        console.error("[Plugin System] Failed to parse and execute plugin configuration:", err, rawPluginAttr);
-    }
-}
+            for (const [pluginName, astValue] of Object.entries(configBlock)) {
+                // Poll window to ensure script execution has completed
+                const pluginLib = await waitForPluginOnWindow(pluginName);
 
-function instantiatePlugin(ConstructorFunc, argsArray) {
-    if (typeof ConstructorFunc !== 'function') return ConstructorFunc;
-    
-    // Check standard ES6 class structure
-    const isEs6Class = /^\s*class\s+/.test(ConstructorFunc.toString());
-    
-    if (isEs6Class) {
-        return new ConstructorFunc(...argsArray);
-    }
-    
-    try {
-        // Fallback Step A: Attempt standard function invocation (e.g. particlesJS)
-        return ConstructorFunc(...argsArray);
-    } catch (err) {
-        // Fallback Step B: If invocation throws constructor error (e.g. Babel transpiled ES5 classes)
-        if (err instanceof TypeError) {
-            return new ConstructorFunc(...argsArray);
-        }
-        throw err;
-    }
-}
+                // Ensure plugin library definition is attached to window once loaded
+                if (pluginLib && typeof window !== 'undefined' && !window[pluginName]) {
+                    window[pluginName] = pluginLib;
+                }
 
-async function executeConfigBlock(context, configBlock) {
-    for (const [key, value] of Object.entries(configBlock)) {
-        // 1. If key is an operator, process it natively via AST engine
-        if (key.startsWith("$")) {
-            await processOperators(context, { [key]: value });
-            continue;
-        }
+                // Format operator key with $ for AST engine recognition (e.g. SimpleBar -> $SimpleBar)
+                const operatorName = pluginName.startsWith('\u0024') ? pluginName : `$${pluginName}`;
 
-        // 2. Intercept standard lifecycle methods to bind them directly as functions on the Element
-        if (["getValue", "setValue", "read", "write"].includes(key)) {
-            context.element[key] = async function(...args) {
-                const localContext = {
-                    ...context,
-                    event: { ...context.event, value: args[0], arguments: args }
+                // 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;
                 };
-                return await processOperators(localContext, value);
-            };
-            continue;
-        }
-
-        const parts = key.split('.');
-        const rootPluginName = parts[0];
 
-        // 3. Resolve target from window object using dot notation
-        let ConstructorFunc = window;
-        for (const part of parts) {
-            if (ConstructorFunc) {
-                ConstructorFunc = ConstructorFunc[part];
-            }
-        }
-
-        // 4. If it's a function, treat it as a constructor to initialize the plugin
-        if (typeof ConstructorFunc === 'function' && !context.element[rootPluginName]) {
-            let constructorArgs = [];
-            if (value !== undefined) {
-                const evaluatedArgs = await processOperators(context, value);
-                constructorArgs = Array.isArray(evaluatedArgs) ? evaluatedArgs : [evaluatedArgs];
-            }
+                // Provide operator wrapper in context for AST registry lookup
+                const context = {
+                    [operatorName]: opWrapper
+                };
 
-            // Create the plugin instance and bind it directly to the element under its root name
-            const instance = instantiatePlugin(ConstructorFunc, constructorArgs);
-            context.element[rootPluginName] = instance;
-            context.plugin = instance; // Update context.plugin reference for sibling method chaining
-            continue;
-        }
+                // Execute AST with the $ operator key so astAsync invokes operatorKey logic
+                const result = await astAsync({
+                    node: el,
+                    sandbox: context,
+                    executeAST: { [operatorName]: astValue }
+                });
 
-        // 5. Explicit Instance Method Chaining (e.g. "FullCalendar.render")
-        let methodTarget = context.element[rootPluginName];
-        if (methodTarget && parts.length > 1) {
-            let method = methodTarget;
-            let parent = methodTarget;
-            for (let i = 1; i < parts.length; i++) {
-                parent = method;
-                if (method) method = method[parts[i]];
-            }
-            if (typeof method === 'function') {
-                let methodArgs = [];
-                if (value !== undefined) {
-                    const evaluatedArgs = await processOperators(context, value);
-                    methodArgs = Array.isArray(evaluatedArgs) ? evaluatedArgs : [evaluatedArgs];
+                if (result !== undefined && !pluginName.startsWith('\u0024')) {
+                    // Attach returned plugin instance directly onto element property
+                    el[pluginName] = result;
                 }
-                await method.apply(parent, methodArgs);
-                continue;
             }
         }
+    } catch (err) {
+        console.error('[Plugin System] Failed to parse and execute plugin configuration:', err, rawPluginAttr);
+    }
+}
 
-        // 6. Sibling Method Chaining (e.g. "render" directly on context.plugin)
-        if (context.plugin && typeof context.plugin[key] === 'function') {
-            let methodArgs = [];
-            if (value !== undefined) {
-                const evaluatedArgs = await processOperators(context, value);
-                methodArgs = Array.isArray(evaluatedArgs) ? evaluatedArgs : [evaluatedArgs];
-            }
-            await context.plugin[key].apply(context.plugin, methodArgs);
-            continue;
-        }
+/**
+ * Initializes plugins on single elements, collections, or selector query matches.
+ * @param {Element|NodeList|Array|string} elements - Target element(s) or DOM query selector
+ */
+export function init(elements) {
+    if (!elements) return;
 
-        // 7. Fallback: Process operators or generic actions on properties
-        await processOperators(context, { [key]: value });
+    if (typeof elements === 'string') {
+        elements = document.querySelectorAll(elements);
+    }
+
+    if (elements instanceof Element) {
+        processPlugin(elements);
+    } else if (elements.length !== undefined || Array.isArray(elements)) {
+        Array.from(elements).forEach(el => {
+            if (el instanceof Element) {
+                processPlugin(el);
+            }
+        });
     }
 }
 
@@ -244,11 +285,7 @@ if (typeof document !== 'undefined') {
         callback: (mutation) => init(mutation.target)
     });
 
-    import("./CoCreate.config.js")
-        .then((Config) => {
-            const data = Config.plugins || Config.default?.plugins || Config.default || {};
-            Object.assign(plugins, data);
-        })
-        .catch(() => {})
-        .finally(() => init(document.querySelectorAll(selector)));
-}
+    init(document.querySelectorAll(selector));
+}
+
+export default { init, registerPlugin };

package/src/operators.js

@@ -1,293 +0,0 @@
-/********************************************************************************
- * Copyright (C) 2026 CoCreate and Contributors.
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
- * by the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- ********************************************************************************/
-
-import { getValueFromObject, queryElements } from "@cocreate/utils";
-
-const IsomorphicGlobals = {
-    Math,
-    Number,
-    String,
-    Boolean,
-    Date,
-    JSON,
-    Array,
-    Object,
-    parseInt,
-    parseFloat,
-    encodeURIComponent,
-    decodeURIComponent,
-    btoa: (str) => {
-        if (typeof btoa === 'function') return btoa(String(str));
-        return Buffer.from(String(str)).toString("base64");
-    },
-    atob: (b64) => {
-        if (typeof atob === 'function') return atob(b64);
-        return Buffer.from(String(b64), "base64").toString("utf-8");
-    },
-    concat: (...args) => args.flat().map(arg => typeof arg === 'object' ? JSON.stringify(arg) : arg).join(''),
-    
-    // Core Asynchronous Flow Control Operators
-    await: {
-        all: async (promises) => Promise.all(promises),
-        any: async (promises) => Promise.any(promises),
-        race: async (promises) => Promise.race(promises),
-        allSettled: async (promises) => Promise.allSettled(promises),
-        delay: (ms) => new Promise(resolve => setTimeout(resolve, Number(ms) || 0))
-    }
-};
-
-const BrowserGlobals = {
-    get $organization_id() { return typeof localStorage !== 'undefined' ? localStorage.getItem("organization_id") : ""; },
-    get $user_id() { return typeof localStorage !== 'undefined' ? localStorage.getItem("user_id") : ""; },
-    get $client_id() { return typeof localStorage !== 'undefined' ? localStorage.getItem("clientId") : ""; },
-    get $session_id() { return typeof localStorage !== 'undefined' ? localStorage.getItem("session_id") : ""; },
-    get $innerWidth() { return typeof window !== 'undefined' ? window.innerWidth : 0; },
-    get $innerHeight() { return typeof window !== 'undefined' ? window.innerHeight : 0; },
-    get $href() { return typeof window !== 'undefined' ? window.location.href.replace(/\/$/, "") : ""; },
-    get $origin() { return typeof window !== 'undefined' ? window.location.origin : ""; },
-    get $protocol() { return typeof window !== 'undefined' ? window.location.protocol : ""; },
-    get $hostname() { return typeof window !== 'undefined' ? window.location.hostname : ""; },
-    get $host() { return typeof window !== 'undefined' ? window.location.host : ""; },
-    get $port() { return typeof window !== 'undefined' ? window.location.port : ""; },
-    get $pathname() { return typeof window !== 'undefined' ? window.location.pathname.replace(/\/$/, "") : ""; },
-    get $hash() { return typeof window !== 'undefined' ? window.location.hash : ""; },
-    get $subdomain() {
-        if (typeof window === 'undefined') return "";
-        const parts = window.location.hostname.split('.');
-        return parts.length > 2 ? parts[0] : "";
-    },
-    get $relativePath() {
-        if (typeof window === 'undefined') return "./";
-        const currentPath = window.location.pathname.replace(/\/[^\/]*$/, ""); 
-        const depth = currentPath.split("/").filter(Boolean).length;
-        return depth > 0 ? "../".repeat(depth) : "./";
-    },
-    get $path() {
-        if (typeof window === 'undefined') return "";
-        let path = window.location.pathname;
-        if (path.split("/").pop().includes(".")) path = path.replace(/\/[^\/]+$/, "/");
-        return path === "/" ? "" : path;
-    },
-    $true: () => true,
-    $false: () => false,
-    $parse: (value = "") => {
-        try { return JSON.parse(value); } catch (e) { return value; }
-    },
-    $query: function(selector) {
-        if (typeof document === 'undefined') return undefined;
-        let element = this?.element || null;
-        if (typeof selector === 'string') {
-            selector = selector.trim().replace(/^['"]|['"]$/g, '');
-        }
-        try {
-            const results = queryElements({ element, selector });
-            return results && results.length > 0 ? results[0] : undefined;
-        } catch (error) {
-            console.warn(`[AST Engine] Invalid $query selector => "${selector}"`, error);
-            return undefined;
-        }
-    },
-    $queryAll: function(selector) {
-        if (typeof document === 'undefined') return [];
-        let element = this?.element || null;
-        if (typeof selector === 'string') {
-            selector = selector.trim().replace(/^['"]|['"]$/g, '');
-            if (selector.includes('$document')) return [];
-        }
-        try {
-            const results = queryElements({ element, selector });
-            return results ? Array.from(results) : [];
-        } catch (error) {
-            console.warn(`[AST Engine] Invalid $queryAll selector => "${selector}"`, error);
-            return [];
-        }
-    }
-};
-
-const getSandboxScope = (context) => {
-    const isBrowser = typeof window !== 'undefined';
-    return {
-        ...IsomorphicGlobals,
-        ...(isBrowser ? BrowserGlobals : {}),
-        ...context
-    };
-};
-
-/**
- * Main recursive traversal loop of the AST Compiler.
- * Analyzes object structures from the inside-out to resolve nested expression boundaries.
- */
-export async function processOperators(context, execute) {
-    if (execute instanceof Promise) {
-        execute = await execute;
-    }
-
-    if (execute === null || execute === undefined) {
-        return execute;
-    }
-
-    if (Array.isArray(execute)) {
-        const evaluatedArray = [];
-        for (let i = 0; i < execute.length; i++) {
-            evaluatedArray[i] = await processOperators(context, execute[i]);
-        }
-        return evaluatedArray;
-    } else if (typeof execute === "object") {
-        const keys = Object.keys(execute);
-        
-        // Match operators starting with "$" except raw database storage parameters
-        const operatorKey = keys.find(k => k.startsWith("$") && !["$array", "$filter", "$storage", "$database"].includes(k));
-        
-        if (operatorKey && keys.length === 1) {
-            return await executeOperator(context, operatorKey, execute[operatorKey]);
-        }
-
-        const evaluatedObject = {};
-        for (const key of keys) {
-            let finalKey = key;
-
-            if (key.startsWith("$") && !["$array", "$filter", "$storage", "$database"].includes(key)) {
-                const resolvedKey = await executeOperator(context, key);
-                if (typeof resolvedKey === "string" || typeof resolvedKey === "number") {
-                    finalKey = String(resolvedKey);
-                }
-            }
-
-            let finalValue = execute[key];
-            if (typeof finalValue === "string" && finalValue.startsWith("$") && !["$array", "$filter", "$storage", "$database"].includes(finalValue)) {
-                finalValue = await executeOperator(context, finalValue);
-            } else if (Array.isArray(finalValue) || (typeof finalValue === "object" && finalValue !== null)) {
-                finalValue = await processOperators(context, finalValue);
-            }
-
-            evaluatedObject[finalKey] = finalValue;
-        }
-        
-        return evaluatedObject;
-    } else if (typeof execute === "string" && execute.startsWith("$") && !["$array", "$filter", "$storage", "$database"].includes(execute)) {
-        return await executeOperator(context, execute);
-    }
-
-    return execute;
-}
-
-async function executeOperator(context, operator, args) {
-    const localContext = {
-        state: {},
-        ...context
-    };
-
-    // Evaluate core context property mappings
-    if (args === undefined) {
-        if (operator.startsWith("$state.")) {
-            return getValueFromObject(localContext.state, operator.substring(7));
-        } else if (operator === "$state") {
-            return localContext.state;
-        } else if (operator.startsWith("$data.")) {
-            return getValueFromObject(localContext.data, operator.substring(6));
-        } else if (operator === "$data") {
-            return localContext.data;
-        } else if (operator.startsWith("$event.")) {
-            return getValueFromObject(localContext.event, operator.substring(7));
-        } else if (operator === "$event") {
-            return localContext.event;
-        } else if (operator.startsWith("$request.")) {
-            return getValueFromObject(localContext.request, operator.substring(9));
-        } else if (operator === "$request") {
-            return localContext.request;
-        } else if (operator.startsWith("$header.")) {
-            const headerKey = operator.substring(8).toLowerCase();
-            return localContext.request?.headers?.[headerKey];
-        } else if (operator === "$rawBody") {
-            return localContext.rawBody;
-        } else if (operator === "$this" || operator === "$element") {
-            return localContext.element;
-        } else if (operator === "$plugin" || operator === "$instance") {
-            return localContext.plugin;
-        } else if (operator === "$value") {
-            const el = localContext.element;
-            return el && typeof el.getValue === 'function' ? el.getValue() : "";
-        }
-    }
-
-    let isExplicitNew = false;
-    let cleanPath = operator.startsWith("$") ? operator.substring(1) : operator;
-    
-    if (cleanPath.startsWith("new.")) {
-        isExplicitNew = true;
-        cleanPath = cleanPath.substring(4);
-    }
-    
-    const parts = cleanPath.split('.');
-    const SandboxScope = getSandboxScope(localContext);
-
-    let target = SandboxScope[parts[0]];
-    let parentContext = SandboxScope;
-
-    if (target === undefined && localContext.element) {
-        target = localContext.element[parts[0]];
-        parentContext = localContext.element;
-    }
-
-    if (target !== undefined) {
-        for (let i = 1; i < parts.length; i++) {
-            parentContext = target;
-            target = target[parts[i]];
-            if (target === undefined) break;
-        }
-
-        if (typeof target === 'function') {
-            let argsArray = [];
-            if (args !== undefined) {
-                if (typeof args === 'object' && args !== null && (args.$args !== undefined || args.$arguments !== undefined)) {
-                    const explicitArgs = args.$args !== undefined ? args.$args : args.$arguments;
-                    
-                    if (Array.isArray(explicitArgs)) {
-                        argsArray = [];
-                        for (let i = 0; i < explicitArgs.length; i++) {
-                            argsArray.push(await processOperators(localContext, explicitArgs[i]));
-                        }
-                    } else {
-                        const evaluatedSingle = await processOperators(localContext, explicitArgs);
-                        argsArray = [evaluatedSingle];
-                    }
-                } else {
-                    const evaluatedSingle = await processOperators(localContext, args);
-                    argsArray = [evaluatedSingle];
-                }
-            }
-            
-            const isEs6Class = /^\s*class\s+/.test(target.toString());
-            
-            if (isExplicitNew || isEs6Class) {
-                return new target(...argsArray);
-            }
-
-            return await target.apply(parentContext, argsArray);
-        } else if (target !== undefined) {
-            return target;
-        }
-    }
-
-    return operator;
-}
-
-export { processOperators as processOperatorsAsync };
-export const customOperators = {}; 
-
-export default processOperators;