@adaas/are-html 0.0.21 → 0.0.23

package/jest.config.ts

@@ -17,6 +17,7 @@ const config: Config.InitialOptions = {
         "@adaas/are-html/instructions/(.*)": "<rootDir>/src/instructions/$1",
         "@adaas/are-html/watchers/(.*)":     "<rootDir>/src/watchers/$1",
         "@adaas/are-html/signals/(.*)":      "<rootDir>/src/signals/$1",
+        "@adaas/are-html/helpers/(.*)":      "<rootDir>/src/helpers/$1",
         // Custom lib exports
         "@adaas/are-html/style/(.*)":        "<rootDir>/src/lib/AreStyle/$1",
         "@adaas/are-html/directive/(.*)":    "<rootDir>/src/lib/AreDirective/$1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/are-html",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "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",
@@ -73,6 +73,7 @@
     "example:signal-routing": "nodemon ./examples/signal-routing/concept.ts",
     "example:component-styles": "nodemon ./examples/component-styles/concept.ts",
     "example:auxta": "nodemon ./examples/auxta/concept.ts",
+    "example:for-perf": "nodemon ./examples/for-perf/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",
@@ -82,16 +83,16 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@adaas/a-concept": "^0.3.27",
-    "@adaas/a-frame": "^0.1.14",
-    "@adaas/a-utils": "^0.3.32",
-    "@adaas/are": "^0.0.21"
+    "@adaas/a-concept": "^0.3.29",
+    "@adaas/a-frame": "^0.1.18",
+    "@adaas/a-utils": "^0.3.34",
+    "@adaas/are": "^0.0.24"
   },
   "devDependencies": {
-    "@adaas/a-concept": "^0.3.27",
-    "@adaas/a-frame": "^0.1.14",
-    "@adaas/a-utils": "^0.3.32",
-    "@adaas/are": "^0.0.21",
+    "@adaas/a-concept": "^0.3.29",
+    "@adaas/a-frame": "^0.1.18",
+    "@adaas/a-utils": "^0.3.34",
+    "@adaas/are": "^0.0.24",
     "@types/chai": "^4.3.14",
     "@types/jest": "^29.5.12",
     "@types/mocha": "^10.0.6",

package/src/directives/AreDirectiveFor.directive.ts

@@ -7,6 +7,8 @@ import { AddCommentInstruction } from "@adaas/are-html/instructions/AddComment.i
 import { AreHTMLNode } from "@adaas/are-html/node";
 import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 import { A_Frame } from "@adaas/a-frame/core";
+import { AreSchedulerHelper } from "@adaas/are-html/helpers/AreScheduler.helper";
+import { AreHTMLEngineContext } from "@adaas/are-html/context";
 
 
 type AreForExpression = {
@@ -17,6 +19,12 @@ type AreForExpression = {
     trackExpr: string | undefined;
 };
 
+/**
+ * Per-`$for` reentrancy state used to serialize chunked (async) renders.
+ * Keyed by the directive attribute instance (one per `$for` in the template).
+ */
+type AreForRenderState = { running: boolean; pending: boolean };
+
 
 @A_Frame.Define({
     namespace: 'a-are-html',
@@ -25,6 +33,32 @@ type AreForExpression = {
 @AreDirective.Priority(1)
 export class AreDirectiveFor extends AreDirective {
 
+    /**
+     * Lists whose number of NEW item nodes is at or below this threshold render
+     * fully synchronously — byte-for-byte the previous behavior. Typical UIs
+     * (menus, small tables) are therefore completely unaffected; only genuinely
+     * large lists pay the (tiny) scheduling cost to keep the main thread responsive.
+     */
+    private static readonly SYNC_THRESHOLD = 100;
+
+    /**
+     * Per-chunk time budget (ms). During a large-list render we mount item nodes
+     * until this much time has elapsed, then yield to the browser so it can paint
+     * and process input before the next chunk. ~16ms targets one animation frame.
+     */
+    private static readonly CHUNK_BUDGET_MS = 16;
+
+    /**
+     * Per-attribute serialization state. A new update() that arrives while a
+     * chunked render of the SAME `$for` is still in flight does NOT start a second
+     * concurrent pass (which could interleave mutations on the shared children
+     * list); instead it marks `pending` and the in-flight run re-runs once more
+     * with the latest data when it finishes. This guarantees the children list is
+     * only ever mutated by one pass at a time and the final state always reflects
+     * the most recent store value.
+     */
+    private static readonly renderState = new WeakMap<object, AreForRenderState>();
+
 
     @AreDirective.Transform
     transform(
@@ -76,7 +110,12 @@ export class AreDirectiveFor extends AreDirective {
          * 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);
+        // Item-scoped variables from an enclosing directive (e.g. the `row` of an
+        // outer `$for`) so a nested `$for="cell in row.cells"` resolves correctly.
+        // Use resolve() (not resolveFlat) so the ENCLOSING item's context — which
+        // lives on an ancestor scope, not on this directive's own node — is found.
+        const contextScope = attribute.owner.scope.resolve(AreDirectiveContext)?.scope || {};
+        const array = this.resolveArray(store, arrayExpr, attribute.content, contextScope);
 
         attribute.value = array;
 
@@ -122,14 +161,50 @@ export class AreDirectiveFor extends AreDirective {
         @A_Inject(AreStore) store: AreStore,
         @A_Inject(AreScene) scene: AreScene,
         ...args: any[]
-    ): void {
+    ): void | Promise<void> {
+        /**
+         * Serialize chunked renders per `$for`. If a previous large-list render
+         * is still streaming item nodes across macrotasks, do NOT start a second
+         * concurrent pass — that would interleave two diffs over the same shared
+         * children list (and leave half-compiled item nodes that the next diff
+         * would wrongly "reuse"). Mark a pass as pending instead; the in-flight
+         * run re-diffs once more from the latest store value when it completes.
+         */
+        let state = AreDirectiveFor.renderState.get(attribute);
+        if (!state) {
+            state = { running: false, pending: false };
+            AreDirectiveFor.renderState.set(attribute, state);
+        }
+        if (state.running) {
+            state.pending = true;
+            return;
+        }
+
+        return this.performUpdate(attribute, store, scene, state);
+    }
+
+    /**
+     * Core of the `$for` update: re-diff the source array against the current
+     * children, reconcile reused/removed items, then mount the new ones (small
+     * lists synchronously, large lists time-sliced). Never called while another
+     * pass for the same `$for` is in flight (see `update`).
+     */
+    private performUpdate(
+        attribute: AreDirectiveAttribute,
+        store: AreStore,
+        scene: AreScene,
+        state: AreForRenderState,
+    ): void | Promise<void> {
         /**
          * Re-evaluate the source array.
          */
         const { key, index, arrayExpr, trackExpr } = this.parseExpression(attribute.content);
-        const newArray = this.resolveArray(store, arrayExpr, attribute.content);
-
         const owner = attribute.owner;
+        // Item-scoped variables from an enclosing directive (see transform()).
+        // resolve() walks ancestor scopes to find the enclosing item's context.
+        const contextScope = owner.scope.resolve(AreDirectiveContext)?.scope || {};
+        const newArray = this.resolveArray(store, arrayExpr, attribute.content, contextScope);
+
         const currentChildren = [...owner.children] as AreHTMLNode[];
 
         attribute.value = newArray;
@@ -167,17 +242,31 @@ export class AreDirectiveFor extends AreDirective {
             remaining.add(child);
         }
 
-        // ── 2. Walk desired list; reuse existing or spawn new ───────────────
-        const desired: AreHTMLNode[] = [];
-        const newOnes: AreHTMLNode[] = [];
+        // ── 2. Walk desired list; reuse existing or record items to create ──
+        // NOTE: new item nodes are NOT spawned here. Spawning (cloneWithScope +
+        // subtree init + scene activation) is the dominant cost of a large
+        // render, so it is deferred into the time-sliced loop below alongside
+        // transform/compile/mount. Existing (keyed) children are reconciled in
+        // place synchronously — that is cheap and keeps reused rows stable.
+        const toCreate: Array<{ item: any; idx: number; key: any }> = [];
+
+        // Final identity → node map covering BOTH reused and newly created item
+        // nodes, plus the desired key order. After all items are mounted these
+        // drive the DOM reorder pass (step 5) so the rendered order always
+        // matches the source array — making prepend / shuffle / arbitrary
+        // reorders move existing rows instead of only appending at the end.
+        const finalByKey = new Map<any, AreHTMLNode>();
+        const orderedKeys: any[] = new Array(newArray.length);
 
         for (let i = 0; i < newArray.length; i++) {
             const item = newArray[i];
             const k = computeKey(item, i);
+            orderedKeys[i] = k;
             const existing = childByKey.get(k);
 
             if (existing) {
                 remaining.delete(existing);
+                finalByKey.set(k, existing);
 
                 let directiveContext = existing.scope.resolveFlat(AreDirectiveContext);
                 if (!directiveContext) {
@@ -189,11 +278,8 @@ export class AreDirectiveFor extends AreDirective {
                     [key]: item,
                     [index || 'index']: i,
                 };
-                desired.push(existing);
             } else {
-                const itemNode = this.spawnItemNode(attribute.template!, owner, key, index, item, i);
-                desired.push(itemNode);
-                newOnes.push(itemNode);
+                toCreate.push({ item, idx: i, key: k });
             }
         }
 
@@ -206,8 +292,14 @@ export class AreDirectiveFor extends AreDirective {
             owner.removeChild(child);
         }
 
-        // ── 4. Mount only the new ones (kept children stay where they are). ─
-        for (const child of newOnes) {
+        // ── 4. Create + mount the new item nodes. ───────────────────────────
+        // `spawnItemNode` appends to `owner.children` immediately; new rows are
+        // therefore mounted at the end (just before the anchor comment). The
+        // reorder pass (step 5) then moves any out-of-position node so the final
+        // DOM order matches the source array.
+        const createItem = (desc: { item: any; idx: number; key: any }) => {
+            const child = this.spawnItemNode(attribute.template!, owner, key, index, desc.item, desc.idx);
+            finalByKey.set(desc.key, child);
             child.transform();
             child.compile();
             // While detached, stop after compile: the item's instructions are
@@ -215,6 +307,110 @@ export class AreDirectiveFor extends AreDirective {
             // the correct container once the condition becomes truthy. Mounting
             // here would hoist the item to the nearest mounted ancestor.
             if (attached) child.mount();
+        };
+
+        // Small lists → fully synchronous, identical to the previous behavior.
+        if (toCreate.length <= AreDirectiveFor.SYNC_THRESHOLD) {
+            for (const desc of toCreate) createItem(desc);
+            // ── 5. Reorder live DOM to match the source array order ──────────
+            if (attached) this.reconcileOrder(owner, orderedKeys, finalByKey);
+            return this.finishUpdate(attribute, store, scene, state);
+        }
+
+        // Large lists → time-sliced render. Create item nodes until the frame
+        // budget elapses, then yield to the browser (zero-delay macrotask) so
+        // it can paint and stay responsive instead of blocking for the whole
+        // batch. The `state.running` flag (see `update`) prevents any other
+        // update() for this `$for` from interleaving while we stream.
+        state.running = true;
+        let cursor = 0;
+
+        const processChunk = (): void | Promise<void> => {
+            try {
+                const start = AreSchedulerHelper.now();
+                while (cursor < toCreate.length) {
+                    createItem(toCreate[cursor]);
+                    cursor++;
+                    if (AreSchedulerHelper.now() - start >= AreDirectiveFor.CHUNK_BUDGET_MS) break;
+                }
+            } catch (error) {
+                // Never leave the `$for` wedged in the running state on failure,
+                // or every future update would be silently deferred forever.
+                state.running = false;
+                state.pending = false;
+                throw error;
+            }
+
+            if (cursor < toCreate.length) {
+                return new Promise<void>(resolve => {
+                    AreSchedulerHelper.scheduleMacrotask(() => resolve(processChunk()));
+                });
+            }
+
+            // ── 5. Reorder live DOM to match the source array order ──────────
+            if (attached) this.reconcileOrder(owner, orderedKeys, finalByKey);
+            return this.finishUpdate(attribute, store, scene, state);
+        };
+
+        return processChunk();
+    }
+
+    /**
+     * Repositions the item nodes' DOM elements so the rendered order matches the
+     * source array order. The keyed diff (steps 1–4) reuses existing nodes in
+     * place and mounts new ones at the end; without this pass a `prepend` or
+     * `shuffle` would leave reused rows where they were and pile new rows at the
+     * bottom. We walk the desired order RIGHT-TO-LEFT, keeping a `ref` pointer to
+     * the element each item must precede (starting at the `$for` anchor comment),
+     * and only call `insertBefore` when an element is not already in position —
+     * so a plain `append` (already-correct order) performs ZERO DOM moves.
+     */
+    private reconcileOrder(
+        owner: AreHTMLNode,
+        orderedKeys: any[],
+        finalByKey: Map<any, AreHTMLNode>,
+    ): void {
+        const context = owner.scope.resolve<AreHTMLEngineContext>(AreHTMLEngineContext);
+        if (!context) return;
+
+        const anchor = context.getNodeElement(owner);
+        if (!anchor || !anchor.parentNode) return;
+
+        const parent = anchor.parentNode;
+        let ref: Node = anchor;
+
+        for (let i = orderedKeys.length - 1; i >= 0; i--) {
+            const node = finalByKey.get(orderedKeys[i]);
+            if (!node) continue;
+
+            const element = context.getNodeElement(node);
+            // Element may be missing if the item is still detached/unmounted.
+            if (!element || element.parentNode !== parent) continue;
+
+            // Already immediately before `ref` — no move needed.
+            if (element.nextSibling !== ref) {
+                parent.insertBefore(element, ref);
+            }
+            ref = element;
+        }
+    }
+
+
+    /**
+     * Completes an update pass. If another update() arrived while a chunked
+     * render was streaming, run exactly one more pass now from the latest store
+     * value so the final DOM always reflects the most recent data.
+     */
+    private finishUpdate(
+        attribute: AreDirectiveAttribute,
+        store: AreStore,
+        scene: AreScene,
+        state: AreForRenderState,
+    ): void | Promise<void> {
+        state.running = false;
+        if (state.pending) {
+            state.pending = false;
+            return this.performUpdate(attribute, store, scene, state);
         }
     }
 
@@ -310,14 +506,32 @@ export class AreDirectiveFor extends AreDirective {
      * Supports both plain key lookups and function-call expressions:
      *   items          → store.get('items')
      *   filter(items)  → store.get('filter')(store.get('items'))
+     *
+     * `contextScope` carries item-scoped variables introduced by an enclosing
+     * directive (e.g. the `row` of an outer `$for`). It is consulted BEFORE the
+     * store so a nested `$for="cell in row.cells"` resolves `row` from the
+     * parent iteration instead of looking for a (non-existent) top-level store
+     * key. Leading identifiers not present in the context fall back to the store.
      */
-    private resolveArray(store: AreStore, arrayExpr: string, fullContent: string): any[] {
+    private resolveArray(
+        store: AreStore,
+        arrayExpr: string,
+        fullContent: string,
+        contextScope: Record<string, any> = {},
+    ): any[] {
+        // Resolve a leading identifier from the directive context first, then
+        // the store — mirrors how bindings/interpolations evaluate scoped vars.
+        const getRoot = (rawKey: string): any => {
+            const k = rawKey.replace(/\?$/, '');
+            return (k in contextScope) ? contextScope[k] : store.get(k as any);
+        };
+
         let result: any;
         const callMatch = arrayExpr.match(/^([^(]+)\((.+)\)$/);
 
         if (callMatch) {
             const fnName = callMatch[1].trim();
-            const fn = store.get(fnName as any);
+            const fn = getRoot(fnName);
 
             if (typeof fn !== 'function')
                 throw new AreCompilerError({
@@ -334,14 +548,14 @@ export class AreDirectiveFor extends AreDirective {
                 const stripped = arg.replace(/\?$/, '');
                 if (stripped.includes('.')) {
                     const parts = stripped.split('.').map(p => p.replace(/\?$/, ''));
-                    let val: any = store.get(parts[0] as any);
+                    let val: any = getRoot(parts[0]);
                     for (let j = 1; j < parts.length; j++) {
                         if (val == null) return undefined;
                         val = val[parts[j]];
                     }
                     return val ?? undefined;
                 }
-                return store.get(stripped as any);
+                return getRoot(stripped);
             });
 
             result = (fn as Function)(...resolvedArgs);
@@ -350,13 +564,13 @@ export class AreDirectiveFor extends AreDirective {
             // Strip optional-chaining `?` suffix from each segment so that
             // `record?.keywords` resolves the same as `record.keywords`.
             const parts = arrayExpr.split('.').map(p => p.replace(/\?$/, ''));
-            result = store.get(parts[0] as any);
+            result = getRoot(parts[0]);
             for (let i = 1; i < parts.length; i++) {
                 if (result == null) break;
                 result = result[parts[i]];
             }
         } else {
-            result = store.get(arrayExpr.replace(/\?$/, '') as any);
+            result = getRoot(arrayExpr);
         }
 
         // null / undefined from optional-chaining expressions (e.g. `record?.keywords`)

package/src/engine/AreHTML.compiler.ts

@@ -13,6 +13,7 @@ import { AddAttributeInstruction} from "@adaas/are-html/instructions/AddAttribut
 import { AddTextInstruction} from "@adaas/are-html/instructions/AddText.instruction";
 import { AddListenerInstruction} from "@adaas/are-html/instructions/AddListener.instruction";
 import { AddStyleInstruction } from "@adaas/are-html/instructions/AddStyle.instruction";
+import { AddStaticHTMLInstruction } from "@adaas/are-html/instructions/AddStaticHTML.instruction";
 import { AreHTMLNode } from "@adaas/are-html/node";
 
 
@@ -39,6 +40,18 @@ export class AreHTMLCompiler extends AreCompiler {
     ): void {
         super.compile(node, scene, logger, ...args);
 
+        /**
+         * Static-island materialisation. When the tokenizer flagged this node as
+         * a static island its inner subtree was never exploded into child nodes,
+         * so there is nothing for the base compiler to walk. Emit a single
+         * AddStaticHTML instruction carrying the captured inner markup; the
+         * interpreter injects it onto the host element in one pass (and decodes
+         * HTML entities for free).
+         */
+        if (node.isStaticIsland && scene.host) {
+            scene.plan(new AddStaticHTMLInstruction(scene.host, { html: node.staticInnerHTML! }));
+        }
+
         if (node.styles?.styles) {
             const host = scene.host;
             if (host) {

package/src/engine/AreHTML.constants.ts

@@ -181,3 +181,145 @@ export function toDOMString(value: any): string {
 }
 
 
+// ─────────────────────────────────────────────────────────────────────────────
+// ── Static-island detection ──────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Standard HTML element names that are safe to materialise wholesale via
+ * `innerHTML` / a cached `<template>` clone.
+ *
+ * The set is intentionally an allow-list of plain HTML flow/phrasing/table/list
+ * /form-display tags. Anything NOT in this set — custom elements, registered
+ * ARE components (resolved by PascalCase tag), and SVG/MathML elements — is
+ * excluded so those subtrees keep flowing through the normal per-node pipeline
+ * (SVG needs createElementNS; components need their own lifecycle).
+ */
+export const STANDARD_HTML_TAGS = new Set<string>([
+    // root / sections
+    'html', 'body', 'header', 'footer', 'main', 'nav', 'section', 'article',
+    'aside', 'address', 'hgroup',
+    // headings
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    // grouping
+    'div', 'p', 'span', 'pre', 'blockquote', 'figure', 'figcaption',
+    'hr', 'br', 'wbr',
+    // lists
+    'ul', 'ol', 'li', 'dl', 'dt', 'dd', 'menu',
+    // text-level / phrasing
+    'a', 'b', 'i', 'u', 's', 'em', 'strong', 'small', 'mark', 'abbr', 'cite',
+    'q', 'code', 'kbd', 'samp', 'var', 'sub', 'sup', 'time', 'data', 'dfn',
+    'bdi', 'bdo', 'ruby', 'rt', 'rp', 'del', 'ins',
+    // media / embedded (no special namespace handling needed)
+    'img', 'picture', 'source', 'figure', 'audio', 'video', 'track',
+    // tables
+    'table', 'caption', 'colgroup', 'col', 'thead', 'tbody', 'tfoot',
+    'tr', 'th', 'td',
+    // forms (display only — these still render fine from innerHTML)
+    'label', 'fieldset', 'legend', 'datalist', 'option', 'optgroup', 'output',
+    'progress', 'meter',
+    // interactive
+    'details', 'summary', 'dialog',
+]);
+
+/**
+ * Detects whether an inner-markup string is a fully *static island* — i.e. it
+ * contains no ARE-reactive constructs and therefore can be rendered in one shot
+ * (browser-parsed `innerHTML` / cached `<template>` clone) instead of being
+ * exploded into one AreNode per element/text/interpolation.
+ *
+ * A subtree is static iff it contains:
+ *   1. no `{{ }}` interpolations, and
+ *   2. no dynamic attributes (`$`-directive / `:`-binding / `@`-event), and
+ *   3. only standard HTML tags (no custom elements, ARE components or SVG).
+ *
+ * The scanner is quote-aware so a `:` / `@` / `$` inside an attribute *value*
+ * (e.g. `href="http://…"`, `style="color:red"`) is never mistaken for a
+ * dynamic-attribute prefix. The detector is deliberately conservative: any
+ * ambiguity resolves to `false` (skip the optimisation, keep the safe path).
+ *
+ * NOTE: pure-text content (no tags at all) is also considered static — this is
+ * what lets `&nbsp;`, `&amp;`, `&#160;` and friends decode correctly, since the
+ * browser HTML parser handles entities that hand-built text nodes do not.
+ */
+export function isStaticMarkup(inner: string): boolean {
+    if (!inner) return false;
+    // 1. interpolations make the subtree dynamic
+    if (inner.indexOf('{{') !== -1) return false;
+
+    const n = inner.length;
+    let i = 0;
+
+    while (i < n) {
+        const lt = inner.indexOf('<', i);
+        if (lt === -1) break; // remaining content is plain text — safe
+
+        // HTML comment — inert, skip over it
+        if (inner.startsWith('<!--', lt)) {
+            const end = inner.indexOf('-->', lt + 4);
+            if (end === -1) return false; // malformed
+            i = end + 3;
+            continue;
+        }
+
+        // closing tag, doctype or processing instruction — skip to its '>'
+        if (inner[lt + 1] === '/' || inner[lt + 1] === '!' || inner[lt + 1] === '?') {
+            const gt = inner.indexOf('>', lt);
+            if (gt === -1) return false;
+            i = gt + 1;
+            continue;
+        }
+
+        // opening tag — extract the tag name
+        const nameMatch = /^<([a-zA-Z][a-zA-Z0-9-]*)/.exec(inner.slice(lt));
+        if (!nameMatch) { i = lt + 1; continue; }
+
+        const tag = nameMatch[1].toLowerCase();
+        // custom element / ARE component / non-standard (incl. SVG) → not static
+        if (tag.indexOf('-') !== -1 || !STANDARD_HTML_TAGS.has(tag)) return false;
+
+        // walk the opening tag (quote-aware) to find its closing '>' and inspect
+        // attribute-name boundaries for dynamic prefixes
+        let j = lt + nameMatch[0].length;
+        let inSingle = false;
+        let inDouble = false;
+        let atNameBoundary = true; // true right after whitespace / '/' inside a tag
+        let tagEnd = -1;
+
+        while (j < n) {
+            const ch = inner[j];
+
+            if (inDouble) {
+                if (ch === '"') inDouble = false;
+            } else if (inSingle) {
+                if (ch === "'") inSingle = false;
+            } else if (ch === '"') {
+                inDouble = true;
+                atNameBoundary = false;
+            } else if (ch === "'") {
+                inSingle = true;
+                atNameBoundary = false;
+            } else if (ch === '>') {
+                tagEnd = j;
+                break;
+            } else if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r' || ch === '/') {
+                atNameBoundary = true;
+            } else {
+                // a dynamic-attribute prefix only counts when it STARTS an
+                // attribute name (i.e. sits at a name boundary, outside quotes)
+                if (atNameBoundary && (ch === '$' || ch === ':' || ch === '@')) {
+                    return false;
+                }
+                atNameBoundary = false;
+            }
+            j++;
+        }
+
+        if (tagEnd === -1) return false; // unterminated tag — bail to safe path
+        i = tagEnd + 1;
+    }
+
+    return true;
+}
+
+