@adaas/are-html 0.0.2

package/examples/jumpstart/src/concept.ts

@@ -0,0 +1,105 @@
+import { A_Concept, A_Context } from "@adaas/a-concept"
+// import { SignInComponent } from "./components/SignInComponent.component"
+import { ABtn } from "./components/A-Btn.component";
+// import { AInput } from "./components/A-Input.component";
+// import { ANavigation } from "./components/A-Navigation.component";
+import { A_Config, ConfigReader } from "@adaas/a-utils/a-config";
+import { A_Logger, A_LOGGER_ENV_KEYS } from "@adaas/a-utils/a-logger";
+import { A_SignalBus, A_SignalState } from "@adaas/a-utils/a-signal";
+import { A_Polyfill } from "@adaas/a-utils/a-polyfill";
+import { AreApp } from "src/containers/AreWebApp.container";
+import { AreRoot } from "src/lib/AreRoot/AreRoot.component";
+import { AreHTMLEngine } from "src/engine/AreHTML.engine";
+import { AreInit } from "@adaas/are";
+import { AreRoute } from "@adaas/are";
+import { AreContext } from "@adaas/are";
+import { AreHTMLEngineContext } from "src/engine/AreHTML.context";
+import { ListComponent } from "./components/List.component";
+import { AreDirectiveIf } from "src/directives/AreDirectiveIf.directive";
+import { AreDirectiveFor } from "src/directives/AreDirectiveFor.directive";
+
+
+// //  TODO: Fix for build system ---
+// window.process = { env: { NODE_ENV: 'production' }, cwd: () => "/" } as any; // --- IGNORE ---
+// window.__dirname = "/"; // --- IGNORE ---
+
+(async () => {
+    try {
+
+        const container = new AreApp({
+            name: 'ARE Jumpstart',
+            components: [
+                // ----------------------------------
+                // Allowed Entities 
+                // ----------------------------------
+                // ............
+                // ----------------------------------
+                // Allowed Commands 
+                // ----------------------------------
+                // ............
+                // ----------------------------------
+                // UI Components 
+                // ----------------------------------
+                ABtn,
+                ListComponent,
+                // ----------------------------------
+                // Directives 
+                // ----------------------------------
+                AreDirectiveIf,
+                AreDirectiveFor,
+                // ----------------------------------
+                // Engine Components 
+                // ----------------------------------
+                A_SignalBus,
+                // ----------------------------------
+                // Addons 
+                // ----------------------------------
+                AreRoot,
+                ConfigReader,
+                AreHTMLEngine,
+                A_Logger,
+            ],
+            entities: [
+                // ............
+                AreInit,
+                AreRoute
+            ],
+            fragments: [
+                new A_SignalState([AreRoute]),
+                new AreHTMLEngineContext(document.body.innerHTML),
+
+                new A_Config({
+                    defaults: {
+                        [A_LOGGER_ENV_KEYS.LOG_LEVEL]: 'info',
+                    }
+                }),
+            ]
+        });
+
+        const concept = new A_Concept({
+            name: 'adaas-are-example-jumpstart',
+            fragments: [new A_Config({
+                variables: ['CONFIG_VERBOSE', 'DEV_MODE'] as const,
+                defaults: {
+                    CONFIG_VERBOSE: true,
+                    DEV_MODE: true
+                }
+            })],
+            components: [A_Logger, ConfigReader, A_Polyfill],
+            containers: [container]
+        })
+
+        console.log('Building Concept...');
+        await concept.load();
+        console.log('✓ Concept loaded successfully.');
+        await concept.start();
+
+
+    } catch (error) {
+        const logger = A_Context.root.resolve<A_Logger>(A_Logger)!;
+        logger.error(error);
+    }
+
+
+
+})();

package/jest.config.ts

@@ -0,0 +1,61 @@
+import type { Config } from '@jest/types';
+
+const config: Config.InitialOptions = {
+    displayName: 'adaas-are-html',
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    resetModules: true,
+    rootDir: '.',
+    testMatch: ['<rootDir>/tests/**/*.test.ts'],
+    setupFilesAfterEnv: ['<rootDir>/tests/jest.setup.ts'],
+    moduleNameMapper: {
+        // ── @adaas/are — main entry and all sub-path imports used internally by the dist ──
+        "^@adaas/are$":                                       "<rootDir>/node_modules/@adaas/are/dist/node/index.js",
+        "^@adaas/are/attribute/(.*)":                         "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreAttribute/$1.js",
+        "^@adaas/are/compiler/(.*)":                          "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreCompiler/$1.js",
+        "^@adaas/are/component/(.*)":                         "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreComponent/$1.js",
+        "^@adaas/are/engine/(.*)":                            "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreEngine/$1.js",
+        "^@adaas/are/event/(.*)":                             "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreEvent/$1.js",
+        "^@adaas/are/instruction/types/(.*)":                 "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreInstruction/types/$1.js",
+        "^@adaas/are/instruction/(.*)":                       "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreInstruction/$1.js",
+        "^@adaas/are/interpreter/(.*)":                       "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreInterpreter/$1.js",
+        "^@adaas/are/lifecycle/(.*)":                         "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreLifecycle/$1.js",
+        "^@adaas/are/loader/(.*)":                            "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreLoader/$1.js",
+        "^@adaas/are/node/(.*)":                              "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreNode/$1.js",
+        "^@adaas/are/scene/(.*)":                             "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreScene/$1.js",
+        "^@adaas/are/signals/entities/(.*)":                  "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreSignals/entities/$1.js",
+        "^@adaas/are/signals/(.*)":                           "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreSignals/$1.js",
+        "^@adaas/are/store/(.*)":                             "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreStore/$1.js",
+        "^@adaas/are/syntax/(.*)":                            "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreSyntax/$1.js",
+        "^@adaas/are/tokenizer/(.*)":                         "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreTokenizer/$1.js",
+        "^@adaas/are/transformer/(.*)":                       "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreTransformer/$1.js",
+        "^@adaas/are/watcher/(.*)":                           "<rootDir>/node_modules/@adaas/are/dist/node/lib/AreWatcher/$1.js",
+
+        // ── @adaas/are-html internal path aliases (mirrors tsconfig.json paths) ──
+        // Base ARE-HTML entities
+        "@adaas/are-html/nodes/(.*)":        "<rootDir>/src/nodes/$1",
+        "@adaas/are-html/attributes/(.*)":   "<rootDir>/src/attributes/$1",
+        "@adaas/are-html/directives/(.*)":   "<rootDir>/src/directives/$1",
+        "@adaas/are-html/instructions/(.*)": "<rootDir>/src/instructions/$1",
+        "@adaas/are-html/watchers/(.*)":     "<rootDir>/src/watchers/$1",
+        "@adaas/are-html/signals/(.*)":      "<rootDir>/src/signals/$1",
+        // Custom lib exports
+        "@adaas/are-html/style/(.*)":        "<rootDir>/src/lib/AreStyle/$1",
+        "@adaas/are-html/directive/(.*)":    "<rootDir>/src/lib/AreDirective/$1",
+        "@adaas/are-html/root/(.*)":         "<rootDir>/src/lib/AreRoot/$1",
+        "@adaas/are-html/node":              "<rootDir>/src/lib/AreHTMLNode/AreHTMLNode",
+        "@adaas/are-html/attribute":         "<rootDir>/src/lib/AreHTMLAttribute/AreHTML.attribute",
+        // HTML engine basics
+        "@adaas/are-html/compiler":          "<rootDir>/src/engine/AreHTML.compiler",
+        "@adaas/are-html/constants":         "<rootDir>/src/engine/AreHTML.constants",
+        "@adaas/are-html/context":           "<rootDir>/src/engine/AreHTML.context",
+        "@adaas/are-html/engine":            "<rootDir>/src/engine/AreHTML.engine",
+        "@adaas/are-html/interpreter":       "<rootDir>/src/engine/AreHTML.interpreter",
+        "@adaas/are-html/lifecycle":         "<rootDir>/src/engine/AreHTML.lifecycle",
+        "@adaas/are-html/tokenizer":         "<rootDir>/src/engine/AreHTML.tokenizer",
+        "@adaas/are-html/transformer":       "<rootDir>/src/engine/AreHTML.transformer",
+        "@adaas/are-html/types":             "<rootDir>/src/engine/AreHTML.types",
+    },
+    collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts']
+};
+export default config;

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@adaas/are-html",
+  "version": "0.0.2",
+  "description": "A-Concept Rendering Engine (ARE) is a powerful rendering engine designed to work seamlessly with the A-Concept framework. This library provides an HTML engine implementation of ARE, enabling developers to create dynamic and interactive user interfaces for web applications using standard HTML syntax.",
+  "keywords": [
+    "a-concept",
+    "a-frame",
+    "a-utils",
+    "rendering-engine",
+    "html-engine",
+    "web-components",
+    "virtual-dom",
+    "reactivity-system",
+    "template-syntax",
+    "lifecycle-management",
+    "event-handling",
+    "state-management",
+    "scene-graph",
+    "instruction-set",
+    "are-html-engine"
+  ],
+  "license": "Apache-2.0",
+  "author": {
+    "name": "ADAAS YAZILIM LİMİTED ŞİRKETİ",
+    "email": "contact-us@adaas.org"
+  },
+  "homepage": "https://github.com/ADAAS-org/adaas-are-html#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ADAAS-org/adaas-are-html.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ADAAS-org/adaas-are-html/issues"
+  },
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/browser/index.d.mts",
+        "import": "./dist/browser/index.mjs"
+      },
+      "node": {
+        "types": "./dist/node/index.d.ts",
+        "import": "./dist/node/index.mjs",
+        "require": "./dist/node/index.cjs"
+      },
+      "default": {
+        "types": "./dist/node/index.d.ts",
+        "import": "./dist/node/index.mjs",
+        "require": "./dist/node/index.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "nodemonConfig": {
+    "ignore": [
+      "**/*.test.ts",
+      "**/*.spec.ts",
+      ".git",
+      "node_modules",
+      "**/dist/**"
+    ],
+    "watch": [
+      "examples",
+      "src"
+    ],
+    "exec": "node -r tsconfig-paths/register -r ts-node/register ",
+    "ext": "ts, js"
+  },
+  "scripts": {
+    "test": "jest",
+    "example:jumpstart": "nodemon ./examples/jumpstart/concept.ts",
+    "example:dashboard": "nodemon ./examples/dashboard/concept.ts",
+    "example:auxta": "nodemon ./examples/auxta/concept.ts",
+    "test:test": "nodemon ./src/test/app.ts",
+    "release": " npm run build && git add . && git commit -m \"new version created :: $(cat package.json | grep version | head -1  | awk -F: '{ print $2 }'  | sed 's/[\",]//g')\" && npm version patch && npm publish --access public",
+    "preversion": "echo test",
+    "version": "echo git add .",
+    "postversion": "git push --no-verify && git push --tags --no-verify && echo \"\n======Version Pushed Successfully=====\n\" ",
+    "echo-version": "echo $npm_package_version",
+    "build": "tsup --config tsup.config.ts"
+  },
+  "dependencies": {
+    "@adaas/a-concept": "^0.3.13",
+    "@adaas/a-frame": "^0.0.22",
+    "@adaas/a-utils": "^0.3.16",
+    "@adaas/are": "^0.0.9"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.14",
+    "@types/jest": "^29.5.12",
+    "@types/mocha": "^10.0.6",
+    "@types/node": "^24.9.1",
+    "axios": "^1.7.2",
+    "chai": "^5.1.0",
+    "dotenv": "^16.4.5",
+    "jest": "^29.7.0",
+    "mocha": "^10.4.0",
+    "nodemon": "^3.1.4",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "tscpaths": "^0.0.9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  }
+}

package/src/attributes/AreBinding.attribute.ts

@@ -0,0 +1,19 @@
+import { AreHTMLAttribute } from "@adaas/are-html/attribute";
+
+
+
+
+
+
+export class AreBindingAttribute extends AreHTMLAttribute {
+
+    // get value(): string {
+
+    //     const [firstPart, ...pathPart] = this.content.split('.');
+
+    //     const primaryObject = this.owner.store.get(firstPart);
+
+    //     return AreCommonHelper.extractPropertyByPath(primaryObject, pathPart.join('.')) as string;
+    // }
+
+}

package/src/attributes/AreDirective.attribute.ts

@@ -0,0 +1,26 @@
+import {  A_FormatterHelper } from "@adaas/a-concept";
+import type { AreDirective } from "@adaas/are-html/directive/AreDirective.component";
+import { AreHTMLAttribute } from "@adaas/are-html/attribute";
+import { AreStoreWatchingEntity } from "@adaas/are";
+import { AreHTMLNode } from "@adaas/are-html/node";
+
+
+
+export class AreDirectiveAttribute extends AreHTMLAttribute implements AreStoreWatchingEntity {
+
+    cache?: any
+
+    template?: AreHTMLNode
+
+    /**
+     * Returns a custom directive component associated with this attribute, if available.
+     * 
+     * The method uses the attribute's name to resolve the corresponding directive component from the scope. It constructs the expected directive name by converting the attribute name to PascalCase and prefixing it with "AreDirective". If a matching directive component is found in the scope, it is returned; otherwise, the method returns undefined.
+     */
+    get component(): AreDirective | undefined {
+        const component = this.scope.resolve<AreDirective>(`AreDirective${A_FormatterHelper.toPascalCase(this.name)}`) as AreDirective | undefined;
+
+        return component as AreDirective;
+    }
+
+}

package/src/attributes/AreEvent.attribute.ts

@@ -0,0 +1,5 @@
+import { AreHTMLAttribute } from "@adaas/are-html/attribute";
+
+
+export class AreEventAttribute extends AreHTMLAttribute {
+}

package/src/attributes/AreStatic.attribute.ts

@@ -0,0 +1,6 @@
+import { AreHTMLAttribute } from "@adaas/are-html/attribute";
+
+
+export class AreStaticAttribute extends AreHTMLAttribute {
+
+}

package/src/directives/AreDirectiveFor.directive.ts

@@ -0,0 +1,322 @@
+import { A_Caller, A_Inject, A_Scope } from "@adaas/a-concept";
+import { A_Logger } from "@adaas/a-utils/a-logger";
+import { AreDirectiveAttribute } from "@adaas/are-html/attributes/AreDirective.attribute";
+import { AreCompilerError, AreScene, AreStore } from "@adaas/are";
+import { AreDirective } from "@adaas/are-html/directive/AreDirective.component";
+import { AddCommentInstruction } from "@adaas/are-html/instructions/AddComment.instruction";
+import { AreHTMLNode } from "@adaas/are-html/node";
+import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
+
+
+type AreForExpression = {
+    key: string;
+    index: string | undefined;
+    arrayExpr: string;
+};
+
+
+@AreDirective.Priority(1)
+export class AreDirectiveFor extends AreDirective {
+
+
+    @AreDirective.Transform
+    transform(
+        @A_Inject(A_Caller) attribute: AreDirectiveAttribute,
+        @A_Inject(A_Scope) scope: A_Scope,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(AreScene) scene: AreScene,
+        @A_Inject(A_Logger) logger: A_Logger,
+        ...args: any[]
+    ) {
+
+        logger.debug(`[Transform] directive $FOR for <${attribute.owner.aseid.toString()}>`)
+
+        const node = attribute.owner;
+
+        /**
+         * Transfer the original node's scope (with all registered attributes and children)
+         * to the template clone, and give the owner node a fresh empty scope.
+         * This mirrors the $if directive's approach, making the owner a lightweight
+         * group container whose sole visible presence is a comment placeholder.
+         */
+        const forTemplate = node.cloneWithScope();
+
+        /**
+         * Remove the $for attribute from the template so iterative clones do not
+         * re-trigger this directive during their own transform phase.
+         * Re-register it on the owner so the reactive compile/update pipeline keeps working.
+         */
+        const forAttr = forTemplate.attributes.find(d => d.name === attribute.name);
+
+        if (forAttr) {
+            forTemplate.scope.deregister(forAttr);
+            node.scope.register(forAttr);
+        }
+
+        /**
+         * Re-initialize the owner node with its fresh scope so it becomes a valid
+         * group container that will own the generated item nodes as children.
+         */
+        node.init();
+
+        /**
+         * Store the template for use in compile and update.
+         */
+        attribute.template = forTemplate;
+
+
+        /**
+         * Parse the $for expression and evaluate the source array.
+         */
+        const { key, index, arrayExpr } = this.parseExpression(attribute.content);
+        const array = this.resolveArray(store, arrayExpr, attribute.content);
+
+        attribute.value = array;
+
+        console.log('Initial array for "for" directive:', scene);
+
+        /**
+         * For each item in the array, spawn a clone of the template with the
+         * item's store values pre-set and its scene activated.
+         *
+         * The children are added to the owner node before the main compiler's
+         * children iteration loop runs, so the main cycle will compile them —
+         * no explicit child.compile() call is needed here.
+         */
+        for (let i = 0; i < array.length; i++) {
+            this.spawnItemNode(attribute.template!, attribute.owner, key, index, array[i], i);
+        }
+
+        console.log('Template for "for" directive:', forTemplate);
+    }
+
+
+    @AreDirective.Compile
+    compile(
+        @A_Inject(A_Caller) attribute: AreDirectiveAttribute,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(AreScene) scene: AreScene,
+        ...args: any[]
+    ): void {
+        /**
+         * Replace the group node's default host declaration with a comment placeholder
+         * so the owner element itself does not render as a DOM element — the item nodes
+         * render as its children instead.
+         */
+        const hostInstruction = scene.host!;
+        const commentIdentifier = ` --- for: ${attribute.template!.id} --- `;
+        const declaration = new AddCommentInstruction({ content: commentIdentifier });
+
+        scene.setHost(declaration);
+        scene.planBefore(declaration, hostInstruction);
+        scene.unPlan(hostInstruction);
+    }
+
+
+    @AreDirective.Update
+    update(
+        @A_Inject(A_Caller) attribute: AreDirectiveAttribute,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(AreScene) scene: AreScene,
+        ...args: any[]
+    ): void {
+        /**
+         * Re-evaluate the source array.
+         */
+        const { key, index, arrayExpr } = this.parseExpression(attribute.content);
+        const newArray = this.resolveArray(store, arrayExpr, attribute.content);
+
+        const owner = attribute.owner;
+        const currentChildren = [...owner.children] as AreHTMLNode[];
+
+        attribute.value = newArray;
+
+        const newLen = newArray.length;
+
+        /**
+         * Build a set of new items for O(1) identity lookup.
+         * Uses reference equality — items that exist in newArray are "kept".
+         */
+        const newItemSet = new Set(newArray);
+
+        /**
+         * Partition existing children by identity: nodes whose stored item is
+         * still present in the new array are kept; the rest are removed.
+         * This correctly handles deletions from any position, not just the tail.
+         */
+        const keptChildren: AreHTMLNode[] = [];
+        const removedChildren: AreHTMLNode[] = [];
+
+        for (const child of currentChildren) {
+            const ctx = child.scope.resolveFlat(AreDirectiveContext);
+
+            if (ctx && newItemSet.has(ctx.scope[key])) {
+                keptChildren.push(child);
+            } else {
+                removedChildren.push(child);
+            }
+        }
+
+        /**
+         * Unmount and detach nodes whose items are no longer in the array.
+         */
+        for (const child of removedChildren) {
+            child.unmount();
+            owner.removeChild(child);
+        }
+
+        /**
+         * Update store values on kept nodes so their reactive bindings pick up
+         * the latest data and corrected indices without a full re-render.
+         */
+        for (let i = 0; i < keptChildren.length; i++) {
+            let directiveContext = keptChildren[i].scope.resolveFlat(AreDirectiveContext);
+
+            if (!directiveContext) {
+                directiveContext = new AreDirectiveContext(keptChildren[i].aseid);
+                keptChildren[i].scope.register(directiveContext);
+            }
+
+            directiveContext.scope = {
+                ...directiveContext.scope,
+                [key]: newArray[i],
+                [index || 'index']: i,
+            };
+        }
+
+        /**
+         * Append nodes for items added beyond the current kept count.
+         * These are created outside the main compile cycle so they need an
+         * explicit compile + mount to appear in the DOM.
+         */
+        for (let i = keptChildren.length; i < newLen; i++) {
+            const itemNode = this.spawnItemNode(attribute.template!, owner, key, index, newArray[i], i);
+
+            itemNode.transform();
+            itemNode.compile();
+            itemNode.mount();
+        }
+    }
+
+
+    // ─────────────────────────────────────────────────────────────────────────────
+    // ── Helpers ──────────────────────────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Parses the $for expression string into its constituent parts.
+     *
+     * Supported formats:
+     *   item in items
+     *   item, index in items
+     *   (item, index) in items
+     *   item in filter(items)
+     *   item, index in filter(items, 'active')
+     */
+    private parseExpression(content: string): AreForExpression {
+        const inIndex = content.lastIndexOf(' in ');
+        const keyAndIndex = content.slice(0, inIndex).trim().replace(/^\(|\)$/g, '');
+        const arrayExpr = content.slice(inIndex + 4).trim();
+        const keyParts = keyAndIndex.split(',').map(p => p.trim());
+
+        return {
+            key: keyParts[0],
+            index: keyParts[1] || undefined,
+            arrayExpr,
+        };
+    }
+
+    /**
+     * Resolves the array expression against the store.
+     * Supports both plain key lookups and function-call expressions:
+     *   items          → store.get('items')
+     *   filter(items)  → store.get('filter')(store.get('items'))
+     */
+    private resolveArray(store: AreStore, arrayExpr: string, fullContent: string): any[] {
+        let result: any;
+        const callMatch = arrayExpr.match(/^([^(]+)\((.+)\)$/);
+
+        if (callMatch) {
+            const fnName = callMatch[1].trim();
+            const fn = store.get(fnName as any);
+
+            if (typeof fn !== 'function')
+                throw new AreCompilerError({
+                    title: 'Invalid "for" Directive Function',
+                    description: `The expression "${fnName}" in the "for" directive does not resolve to a function in the store. Received: ${typeof fn}`,
+                });
+
+            const rawArgs = callMatch[2].split(',').map(a => a.trim());
+            const resolvedArgs = rawArgs.map(arg => {
+                if (arg.startsWith("'") && arg.endsWith("'")) return arg.slice(1, -1);
+                if (arg.startsWith('"') && arg.endsWith('"')) return arg.slice(1, -1);
+                if (!isNaN(Number(arg))) return Number(arg);
+                return store.get(arg as any);
+            });
+
+            result = (fn as Function)(...resolvedArgs);
+        } else {
+            result = store.get(arrayExpr as any);
+        }
+
+        if (!Array.isArray(result))
+            throw new AreCompilerError({
+                title: 'Invalid "for" Directive Value',
+                description: `The "for" directive expects an array but got ${typeof result}. Expression: "${fullContent}". Received: ${JSON.stringify(result)}`,
+            });
+
+        return result;
+    }
+
+    /**
+     * Creates a single item node from the template, registers it as a child of
+     * the owner, initialises it, injects item-scoped store values, and activates
+     * its scene so the mount/compile cycle will include it.
+     *
+     * NOTE: This method does NOT call compile() or mount() — the caller is
+     * responsible for doing so when the main lifecycle cycle won't cover it
+     * (i.e. during update, but not during the initial compile phase).
+     */
+    private spawnItemNode(
+        template: AreHTMLNode,
+        owner: AreHTMLNode,
+        key: string,
+        index: string | undefined,
+        item: any,
+        i: number,
+    ): AreHTMLNode {
+        const itemNode = template.clone() as AreHTMLNode;
+
+        owner.addChild(itemNode);
+
+        const queue = [itemNode];
+
+        while (queue.length > 0) {
+            const current = queue.shift()!
+
+            current.init();
+
+            queue.push(...current.children as AreHTMLNode[]);
+        }
+
+        /**
+         * Resolve or create a directive context for the item node. This is needed to hold the item-specific store values (e.g. the "item" and "index" in a "for" loop) that the template's bindings will reference during compile and update. The context is shared among all clones of the same template, but that's fine because each clone gets its own scope values assigned here.
+         */
+        let directiveContext = itemNode.scope.resolveFlat(AreDirectiveContext);
+
+        if (!directiveContext) {
+            directiveContext = new AreDirectiveContext(itemNode.aseid);
+            itemNode.scope.register(directiveContext);
+        }
+
+        directiveContext.scope = {
+            ...directiveContext.scope,
+            [key]: item,
+            [index || 'index']: i,
+        }
+
+        itemNode.scene.activate();
+
+        return itemNode;
+    }
+}