spyne 0.21.4 → 0.22.3

package/lib/spyne.umd.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
-     * Spyne 0.21.4
+     * Spyne 0.22.3
      * https://spynejs.org
      *
      * @license
@@ -15,7 +15,7 @@
      */
 
 /*!
- * spynejs 0.21.4
+ * spynejs 0.22.3
  * https://spynejs.org
  * (c) 2017-present Frank Batista
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spyne",
-  "version": "0.21.4",
+  "version": "0.22.3",
   "description": "Reactive Real-DOM Framework for Advanced Javascript applications",
   "sideEffects": true,
   "main": "./lib/spyne.esm.js",
@@ -18,7 +18,6 @@
     "eslint-fix-tests": "eslint --fix 'src/tests/**'",
     "report-coverage": "nyc report --reporter=text-lcov > coverage.lcov && codecov",
     "commit": "git-cz",
-    "start": "webpack-dev-server --hot",
     "build": "webpack --config webpack.config.js --mode production",
     "build:esm": "rollup --config rollup.config.js",
     "dev": "webpack --config webpack.config.js --mode development",
@@ -52,6 +51,7 @@
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.0",
     "@rollup/plugin-replace": "^6.0.2",
+    "@rollup/plugin-terser": "^1.0.0",
     "chai": "^4.3.9",
     "chai-dom": "^1.11.0",
     "clean-webpack-plugin": "^4.0.0",
@@ -72,19 +72,22 @@
     "karma-mocha": "^2.0.1",
     "karma-rollup-preprocessor": "^7.0.8",
     "karma-webpack": "^5.0.1",
-    "mocha": "^10.7.3",
+    "mocha": "^11.7.5",
     "rollup": "^2.79.2",
-    "rollup-plugin-terser": "^7.0.2",
     "webpack": "^5.94.0",
     "webpack-cli": "^5.1.4",
-    "webpack-dev-middleware": "^7.4.2",
-    "webpack-dev-server": "^5.1.0",
     "webpack-rxjs-externals": "^2.0.0"
   },
+  "overrides": {
+    "mocha": {
+      "serialize-javascript": "^7.0.4",
+      "diff": "^8.0.2"
+    }
+  },
   "config": {},
   "dependencies": {
     "dompurify": "^3.1.6",
-    "ramda": "^0.30.1",
+    "ramda": "^0.32.0",
     "rxjs": "^7.8.1"
   }
 }

package/rollup.config.js

@@ -2,7 +2,7 @@
 import resolve from '@rollup/plugin-node-resolve';
 import commonjs from '@rollup/plugin-commonjs';
 import json from '@rollup/plugin-json';
-import { terser } from 'rollup-plugin-terser';
+import terser from '@rollup/plugin-terser';
 
 export default {
   input: 'src/spyne/spyne.js',   // Your main entry (the "barrel")

package/src/spyne/channels/channels-map.js

@@ -2,6 +2,7 @@ import { SpyneChannelRoute } from './spyne-channel-route.js'
 import { SpyneChannelUI } from './spyne-channel-ui.js'
 import { SpyneChannelWindow } from './spyne-channel-window.js'
 import { SpyneChannelLifecycle } from './spyne-channel-lifecycle.js'
+import { SpyneChannelAI } from './spyne-channel-ai.js'
 
 import { Subject } from 'rxjs'
 import { ChannelProxy } from './channel-proxy.js'
@@ -84,6 +85,9 @@ export class ChannelsMap {
     this.viewStreamLifecycle = new SpyneChannelLifecycle()
     _map.set('CHANNEL_LIFECYCLE', this.viewStreamLifecycle)
 
+    this.aiStream = new SpyneChannelAI()
+    _map.set('CHANNEL_AI', this.aiStream)
+
     this.routeStream.initializeStream()
     this.domStream.initializeStream()
   }

package/src/spyne/channels/spyne-channel-ai.js

@@ -0,0 +1,45 @@
+import { Channel } from './channel.js'
+
+export class SpyneChannelAI extends Channel {
+  /**
+   * @module SpyneChannelAI
+   * @type core
+   *
+   * @desc
+   * Internal Channel that publishes rendering and disposing events of all ViewStreams whose property, proper.sendAIEvents is set to true.
+   *
+   * <h3>The two actions that are regsitered for this channel are:</h3>
+   * <ul>
+   * <li>CHANNEL_AI_RENDERED_EVENT</li>
+   * <li>CHANNEL_AI_DISPOSED_EVENT</li>
+   *  </ul>
+   * @constructor
+   * @property {String} CHANNEL_NAME - = 'CHANNEL_AI';
+   */
+
+  constructor(props = {}) {
+    super('CHANNEL_AI', props)
+  }
+
+  addRegisteredActions() {
+    return [
+      'CHANNEL_AI_RENDERED_EVENT',
+      'CHANNEL_AI_DISPOSED_EVENT'
+    ]
+  }
+
+  onViewStreamInfo(obj) {
+    const { action, srcElement } = obj
+    const payload = srcElement
+    payload.action = action
+    this.onSendEvent(action, payload)
+  }
+
+  onSendEvent(actionStr, payload = {}) {
+    const action = this.channelActions[actionStr]
+    const srcElement = {}
+    const event = undefined
+    const delayStream = () => this.sendChannelPayload(action, payload, srcElement, event)
+    window.setTimeout(delayStream, 0)
+  }
+}

package/src/spyne/spyne-app.js

@@ -6,7 +6,7 @@ import { sanitizeHTMLConfigure } from './utils/sanitize-html.js'
 import { sanitizeDataConfigure } from './utils/sanitize-data.js'
 
 const _channels = new ChannelsMap()
-const version = '0.21.4'
+const version = '0.22.3'
 
 class SpyneApplication {
   /**
@@ -41,7 +41,7 @@ class SpyneApplication {
   init(config = {}, testMode = false) {
     // this.channels = new ChannelsMap();
     /*!
-     * Spyne 0.21.4
+     * Spyne 0.22.3
      * https://spynejs.org
      *
      * @license

package/src/spyne/utils/channel-payload-filter.js

@@ -233,7 +233,7 @@ export class ChannelPayloadFilter {
     // LOOP THROUGH NODES IN querySelectorAll()
     const mapNodeArrWithEl = (sel) => {
       // convert nodelist to array of els
-      const nodeArr = flatten(document.querySelectorAll(sel))
+      const nodeArr = Array.from(document.querySelectorAll(sel))
       // els array to boolean array
       return rMap(compareEls, nodeArr)
     }

package/src/spyne/utils/sanitize-data.js

@@ -11,7 +11,7 @@ let forceStrict = false // legacy compatibility toggle
  * ------------------------------------------- */
 const SAFE_FOR_RICH_TEXT = {
   ALLOWED_TAGS: [
-    'a', 'b', 'i', 'em', 'strong', 'u', 'p', 'br', 'ul', 'ol', 'li',
+    'a', 'b', 'i', 'em', 'strong', 'u', 'p', 'br', 'ul', 'dl', 'dt', 'dd', 'ol', 'li', 'hr',
     'blockquote', 'pre', 'code', 'span', 'div', 'section', 'article', 'aside',
     'header', 'footer', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
     'table', 'thead', 'tbody', 'tr', 'td', 'th', 'img', 'figure', 'figcaption',
@@ -24,7 +24,7 @@ const SAFE_FOR_RICH_TEXT = {
   ],
   ALLOW_DATA_ATTR: true,
   FORBID_ATTR: ['onerror', 'onload', 'onclick', 'onmouseover', 'onfocus', 'onblur', 'onchange'],
-  FORBID_TAGS: ['script', 'object', 'embed', 'meta', 'link'],
+  FORBID_TAGS: ['script', 'object', 'embed', 'meta'],
   SAFE_URL_PATTERN: /^(https?:|mailto:|tel:|data:image\/)/i
 }
 

package/src/spyne/views/dom-element-template.js

@@ -2,15 +2,59 @@ import { includes, __, ifElse, path, prop, reject, is, isNil, isEmpty } from 'ra
 import sanitizeHTML from '../utils/sanitize-html.js'
 import { SpyneAppProperties } from '../utils/spyne-app-properties.js'
 
+/**
+ * DomElementTemplate
+ *
+ * Mustache-compatible template engine used by ViewStream and DomElement for HTML rendering.
+ *
+ * Supported syntax:
+ *   {{key}}                          variable interpolation, HTML-escaped
+ *   {{key.path.to.value}}            dot-notation property access
+ *   {{#key}}...{{/key}}              array/object sections
+ *   {{.}}                            current element inside a loop
+ *   {{#}}...{{/}}                    top-level bare array (passed as `data`)
+ *
+ * Nesting:
+ *   DomElementTemplate supports exactly ONE level of nested array sections.
+ *   A template like {{#rows}}...{{#cells}}...{{/cells}}...{{/rows}} is supported.
+ *   Deeper nesting — {{#a}}{{#b}}{{#c}}...{{/c}}{{/b}}{{/a}} — is NOT supported.
+ *
+ *   When a template has deeper nesting, a warning is logged in debug mode and
+ *   the third-level loop is not processed. This is a deliberate design choice:
+ *   deep hierarchical rendering belongs in nested ViewStreams, not in templates.
+ *   Nested ViewStreams provide proper lifecycle semantics, isolated rendering,
+ *   and clearer architectural boundaries than arbitrarily-nested templates.
+ *
+ * Not currently supported in nested loops:
+ *   - CMS proxy metadata (__cms__dataId, __cms__keyFor_*). Inner-loop CMS
+ *     editing is a future enhancement; until then, content inside an inner
+ *     loop is rendered as read-only from the CMS perspective.
+ */
 export class DomElementTemplate {
   constructor(template, data = {}, opts = {}) {
     this.template = this.formatTemplate(template)
     this.isProxyData = data.__cms__isProxy === true
     this.testMode = opts?.testMode
 
+    // Normalize triple-bracket tags to double-bracket.
+    //
+    // DomElementTemplate treats {{{key}}} as an alias for {{key}} — both
+    // interpolate the value as-is. Mustache's convention of "triple-bracket
+    // means unescaped" doesn't apply here because SpyneJS handles escaping
+    // and sanitization through `sanitize-data` (keyed on SpyneApp mode)
+    // before values reach the template, not through syntax-level escaping.
+    //
+    // We accept triple-bracket syntax so that authors and AI familiar with
+    // standard Mustache don't have their templates silently break when they
+    // reach for {{{key}}} out of habit. The normalization happens once here,
+    // so the rest of the engine only ever reasons about double-bracket tags.
+    this.template = DomElementTemplate.normalizeTripleBrackets(this.template)
+
     if (this.isProxyData === true) {
       if (SpyneAppProperties.enableCMSProxies === true) {
         this.template = SpyneAppProperties.formatTemplateForProxyData(this.template)
+      } else {
+        this.template = DomElementTemplate.formatTemplateForProxyData(this.template)
       }
     }
 
@@ -26,6 +70,13 @@ export class DomElementTemplate {
 
     this.templateData = data
 
+    // Stash used by per-iteration substitution so that CMS proxy lookups
+    // for string-array items (where __cms__dataId / __cms__keyFor_* live on
+    // the PARENT array, not on the individual string elements) can find the
+    // parent object at render time. Set by parseTheTmplLoop, cleared when
+    // that loop completes.
+    this.currentOuterLoopData = null
+
     const strArr = DomElementTemplate.getStringArray(this.template)
 
     let strMatches = this.template.match(DomElementTemplate.findTmplLoopsRE())
@@ -33,9 +84,9 @@ export class DomElementTemplate {
 
     const parseTmplLoopsRE = DomElementTemplate.parseTmplLoopsRE()
 
-    const parseTmplLoopFn =  this.parseTheTmplLoop.bind(this)
+    const parseTmplLoopFn = this.parseTheTmplLoop.bind(this)
 
-    const mapTmplLoop = (str, data) => {
+    const mapTmplLoop = (str) => {
       return str.replace(parseTmplLoopsRE, parseTmplLoopFn)
     }
 
@@ -52,6 +103,37 @@ export class DomElementTemplate {
     return /({{\.\*?}})/.test(str)
   }
 
+  /**
+   * Normalizes triple-bracket tags to double-bracket form.
+   *
+   *   {{{key}}}       → {{key}}
+   *   {{{a.b.c}}}     → {{a.b.c}}
+   *   {{{.}}}         → {{.}}
+   *   {{{.*}}}        → {{.*}}
+   *
+   * Section markers {{#key}} and {{/key}} are already two-bracket by
+   * convention and are not affected. Tags of the wrong shape (unbalanced,
+   * four or more brackets, etc.) are left untouched — anything the main
+   * parser doesn't recognize later will render as literal text, which is
+   * the correct failure mode for a logic-less template engine.
+   *
+   * This exists because DomElementTemplate treats {{{key}}} and {{key}}
+   * as interchangeable — sanitization and escaping are config-driven
+   * through `sanitize-data`, not syntax-driven through bracket count.
+   * Normalizing at construction time means the rest of the engine (loop
+   * regexes, CMS proxy wrapping, variable substitution) only reasons
+   * about one bracket style.
+   */
+  static normalizeTripleBrackets(template) {
+    if (typeof template !== 'string' || template.indexOf('{{{') === -1) {
+      return template
+    }
+    // Match balanced triple-brackets containing anything that isn't a
+    // brace character. Keeps the captured inner content, strips the
+    // outer third brace on each side.
+    return template.replace(/\{\{\{([^{}]+?)\}\}\}/g, '{{$1}}')
+  }
+
   // FIND CORRECT NESTED DATA
   static getNestedDataReducer(data = {}, param = '') {
     const dataReducer = (nestedData, str) => {
@@ -67,24 +149,63 @@ export class DomElementTemplate {
   static getStringArray(template) {
     const strArr = template.split(DomElementTemplate.findTmplLoopsRE())
     const emptyRE = /^([\\n\s\W]+)$/
+    // findTmplLoopsRE has TWO capture groups (the full loop match, and the
+    // \2-backreferenced key name). When used with String.prototype.split, the
+    // second group is emitted into the result array as a leaked chunk.
+    //
+    // The chunks arrive in a predictable 3-step cycle:
+    //   index 0:                pre-text before the first loop
+    //   index 1: full match     the loop (keep)
+    //   index 2: group-2 leak   the loop's key name (discard)
+    //   index 3:                between-loops text
+    //   index 4: full match
+    //   index 5: group-2 leak
+    //   ...
+    // So any index i where i >= 2 and (i - 2) % 3 === 0 is a key-name leak
+    // that should not flow into the render pipeline.
+    const withoutLeaks = strArr.filter((_, i) => !(i >= 2 && (i - 2) % 3 === 0))
     const filterOutEmptyStrings = s => s.match(emptyRE)
-    const finalStr =  reject(filterOutEmptyStrings, strArr)
+    const finalStr = reject(filterOutEmptyStrings, withoutLeaks)
 
     return finalStr
   }
 
+  /**
+   * Regex that finds top-level loop sections, pairing each opening tag with a
+   * closing tag of the SAME NAME via the \2 backreference. This is what makes
+   * {{#rows}}<tr>{{#cells}}<td>{{.}}</td>{{/cells}}</tr>{{/rows}} match as a
+   * single outer loop rather than getting truncated at the inner {{/cells}}.
+   */
   static findTmplLoopsRE() {
-    return /({{#[\w.]+}}[\w\n\s\W]+?{{\/[\w.]+}})/gm
+    return /({{#([\w.]+)}}[\w\n\s\W]+?{{\/\2}})/gm
   }
 
   static parseTmplLoopsRE() {
     return /({{#([\w.]+)}})([\w\n\s\W]+?)({{\/\2}})/gm
   }
 
+  /**
+   * Regex for finding a single inner loop inside an outer loop's body.
+   * Identical in form to parseTmplLoopsRE, but created fresh to avoid
+   * shared-lastIndex bugs with global regexes when used in .replace callbacks.
+   */
+  static innerLoopRE() {
+    return /({{#([\w.]+)}})([\w\n\s\W]+?)({{\/\2}})/gm
+  }
+
   static swapParamsForTagsRE() {
     return /({{)(.*?)(}})/gm
   }
 
+  /**
+   * Detects whether a template body contains any {{#key}}...{{/key}} pair.
+   * Used to decide whether the inner-loop pass is needed, and to detect
+   * two-level nesting for warning purposes.
+   */
+  static hasLoop(str) {
+    return DomElementTemplate.innerLoopRE().test(str)
+  }
+
   removeThis() {
     if (this !== undefined) {
       this.finalArr = undefined
@@ -94,16 +215,14 @@ export class DomElementTemplate {
   }
 
   /**
-   *
    * @desc Returns a document fragment generated from the template and any added data.
    */
-
   renderDocFrag() {
     let html = DomElementTemplate.replaceImgPath(this.finalArr.join(''))
     if (this.testMode !== true) {
       html = sanitizeHTML(html)
     }
-    const isTableSubTag =   /^([^>]*?)(<){1}(\b)(thead|col|colgroup|tbody|td|tfoot|tr|th)(\b)([^\0]*)$/.test(html)
+    const isTableSubTag = /^([^>]*?)(<){1}(\b)(thead|col|colgroup|tbody|td|tfoot|tr|th)(\b)([^\0]*)$/.test(html)
     const el = isTableSubTag ? html : document.createRange().createContextualFragment(html)
 
     window.setTimeout(this.removeThis, 2)
@@ -147,76 +266,211 @@ export class DomElementTemplate {
     return templateStr
   }
 
-  parseTheTmplLoop(str, p1, p2, p3) {
-    const reDot = /(\.)/gm
-    const subStr = p3
-    let elData = DomElementTemplate.getNestedDataReducer(this.templateData, p2)
+  /**
+   * Resolves a single inner loop (one level down) inside an outer-loop body,
+   * using `parentItem` as the data context. If the inner body itself contains
+   * another loop, a debug-mode warning is logged and that deeper loop is not
+   * processed.
+   *
+   * Returns the body string with any inner loop expanded, ready for
+   * outer-level variable substitution.
+   */
+  processInnerLoop(bodyStr, parentItem) {
+    const innerRE = DomElementTemplate.innerLoopRE()
+
+    return bodyStr.replace(innerRE, (fullMatch, openTag, innerKey, innerBody /*, closeTag */) => {
+      // Detect disallowed second-level nesting inside the inner body.
+      if (DomElementTemplate.hasLoop(innerBody) === true) {
+        if (SpyneAppProperties.debug === true && this.testMode !== true) {
+          console.warn(
+            'Spyne Warning: DomElementTemplate supports one level of nested array loops. ' +
+            `A deeper nested loop was detected inside "{{#${innerKey}}}". ` +
+            'Consider restructuring via nested ViewStreams instead.'
+          )
+        }
+        // Strip unsupported deeper-level section tags so they don't emit as
+        // garbled variables during substitution below.
+        innerBody = innerBody.replace(/{{[#/][\w.]+}}/g, '')
+      }
 
-    const arrayStringToObjAdapter = (d, str, i) => {
-      if (DomElementTemplate.isPrimitiveTag(str)) {
-        return parseString(d, str, i)
+      const innerData = DomElementTemplate.getNestedDataReducer(parentItem, innerKey)
+
+      if (isNil(innerData) === true || isEmpty(innerData)) {
+        return ''
       }
 
-      const createDataObj = () => {
-        const spyneLoopKey = d
-        const loopIndex = i
-        const loopNum = i + 1
+      const innerArr = Array.isArray(innerData) ? innerData : [innerData]
 
-        if (this.isProxyData) {
-          const __cms__dataId = elData.__cms__dataId
-          const keyIdStr = `__cms__keyFor_${d}`
-          const origKey = elData[keyIdStr]
-          return { spyneLoopKey, __cms__dataId, origKey, loopIndex, loopNum, d }
-        }
-        return { spyneLoopKey, loopIndex, loopNum }
+      // While processing an inner loop, the "outer" data for CMS string-item
+      // lookups is the current innerData (the array/object the inner items
+      // belong to), not the original outer-loop array. Swap it in, restore
+      // when the inner pass completes.
+      const previousOuter = this.currentOuterLoopData
+      this.currentOuterLoopData = innerData
+
+      const rendered = innerArr.map((innerItem, innerIdx) => {
+        return this.substituteForItem(innerBody, innerItem, innerIdx)
+      }).join('')
+
+      this.currentOuterLoopData = previousOuter
+      return rendered
+    })
+  }
+
+  /**
+   * Substitutes {{...}} variables in `str` using `item` as the data context.
+   *
+   * Three cases:
+   *
+   *   1. String item + primitive {{.}}/{{.*}} template:
+   *      direct text substitution (no CMS wrapping possible — this path only
+   *      runs when formatTemplateForProxyData has NOT wrapped the tag).
+   *
+   *   2. String item + non-primitive template:
+   *      can happen two ways: (a) a section iterating strings where
+   *      formatTemplateForProxyData has replaced {{.}}/{{.*}} with
+   *      {{spyneLoopKey}} + {{origKey}} inside a <spyne-cms-item> wrapper,
+   *      or (b) a non-proxy template with positional tokens only.
+   *      Build a context that satisfies both — spyneLoopKey = the string,
+   *      plus __cms__dataId / origKey looked up on the parent array when
+   *      proxy data is active.
+   *
+   *   3. Object item:
+   *      the conventional path — build a lookup object with the item's
+   *      properties plus positional tokens, substitute by property name
+   *      or dot-path.
+   */
+  substituteForItem(str, item, index) {
+    // Case 1: string item with a primitive-tag template.
+    if (typeof item === 'string') {
+      if (DomElementTemplate.isPrimitiveTag(str)) {
+        const escaped = item.replace(/\$/g, '$$$$') // $ -> $$ for replace() literal safety
+        return str.replace(DomElementTemplate.swapParamsForTagsRE(), escaped)
       }
 
-      return parseObject(createDataObj(), str, i)
+      // Case 2: string item with a non-primitive template.
+      const ctx = this.buildStringItemContext(item, index)
+      return this.substituteObject(str, ctx)
     }
 
-    const parseString = (item, str, index, origIndex) => {
-      item = item.replace(/\$/g, '$$$$') // $ → $$
-      return str.replace(DomElementTemplate.swapParamsForTagsRE(), item)
+    // Case 3: object item.
+    const dataObj = this.buildItemContext(item, index)
+    return this.substituteObject(str, dataObj)
+  }
+
+  /**
+   * Builds the per-iteration lookup context for a STRING item.
+   *
+   * Always includes:
+   *   - spyneLoopKey: the string itself (matches the CMS proxy wrapping,
+   *     which replaces {{.}}/{{.*}} inside string loops with {{spyneLoopKey}})
+   *   - loopIndex / loopNum: positional tokens
+   *
+   * When proxy data is active, additionally includes:
+   *   - __cms__dataId: the CMS identifier for the PARENT array (the string
+   *     items themselves are primitives and don't carry the id)
+   *   - origKey: the original key the CMS uses to address this specific
+   *     string within its parent, looked up via __cms__keyFor_<item>
+   */
+  buildStringItemContext(item, index) {
+    const context = {
+      spyneLoopKey: item,
+      loopIndex: index,
+      loopNum: index + 1
     }
 
-    // PARSING ARRAYS AND OBJECTS
-    const parseObject = (obj, str, i) => {
-      /// LOOP NUMBER VALUES AUTO ADDED
+    if (this.isProxyData === true) {
+      const outerData = this.currentOuterLoopData
+      if (outerData && typeof outerData === 'object') {
+        context.__cms__dataId = outerData.__cms__dataId || ''
+        const keyIdStr = `__cms__keyFor_${item}`
+        context.origKey = outerData[keyIdStr] !== undefined ? outerData[keyIdStr] : ''
+      } else {
+        context.__cms__dataId = ''
+        context.origKey = ''
+      }
+    }
 
-      // const loopIndex = i;
-      // const loopNum = i+1;
+    return context
+  }
 
-      const loopObj = (str, p1, p2) => {
-        // DOT SYNTAX CHECK
-        const hash = {
-          loopIndex: i,
-          loopNum: i + 1
-        }
+  /**
+   * Builds the per-iteration lookup context for an OBJECT item, including
+   * CMS-proxy metadata when this template is rendering proxied data.
+   */
+  buildItemContext(item, index) {
+    const context = Object.assign({}, item, {
+      loopIndex: index,
+      loopNum: index + 1
+    })
 
-        // IF {{.}}
-        if (reDot.test(p2) === false && obj[p2] !== undefined) {
-          return hash[p2] !== undefined ? hash[p2] : obj[p2]
-        }
+    if (this.isProxyData === true) {
+      context.__cms__dataId = item.__cms__dataId
+      context.spyneLoopKey = item
+      context.loopIndex = index
+      context.loopNum = index + 1
+    }
+
+    return context
+  }
+
+  /**
+   * Replaces {{key}} and {{a.b.c}} tokens in `str` using `ctx` as the source.
+   */
+  substituteObject(str, ctx) {
+    const reDot = /(\.)/gm
+    const positional = { loopIndex: ctx.loopIndex, loopNum: ctx.loopNum }
 
-        const dataReducedVal  = this.getDataValFromPathStr(p2, obj)
-        return hash[p2] !== undefined ? hash[p2] : dataReducedVal
+    const replacer = (match, p1, p2) => {
+      // Auto-injected positional tokens take precedence
+      if (positional[p2] !== undefined) return positional[p2]
+
+      // Simple key access
+      if (reDot.test(p2) === false && ctx[p2] !== undefined) {
+        return ctx[p2]
       }
-      return str.replace(DomElementTemplate.swapParamsForTagsRE(), loopObj)
+
+      // Dot-path access
+      return this.getDataValFromPathStr(p2, ctx)
     }
 
-    const mapStringData = (d, i) => typeof (d) === 'string' ? arrayStringToObjAdapter(d, subStr, i) : parseObject(d, subStr, i)
+    return str.replace(DomElementTemplate.swapParamsForTagsRE(), replacer)
+  }
+
+  /**
+   * Entry point for each top-level loop match. Extracts loop data, runs the
+   * inner-loop pass on the body for each iteration, then substitutes outer
+   * variables.
+   */
+  parseTheTmplLoop(str, p1, p2, p3) {
+    const outerBody = p3
+    const elData = DomElementTemplate.getNestedDataReducer(this.templateData, p2)
 
     if (isNil(elData) === true || isEmpty(elData)) {
       return ''
     }
 
-    if (elData.length === undefined) {
-      elData = [elData]
-    }
+    // Stash the outer data so that per-iteration substitution can look up
+    // CMS proxy metadata (__cms__dataId, __cms__keyFor_*) that lives on the
+    // parent array object — not on individual string elements.
+    const previousOuter = this.currentOuterLoopData
+    this.currentOuterLoopData = elData
+
+    const elArr = Array.isArray(elData) ? elData : [elData]
+
+    // Whether the outer body contains an inner loop is cheap to test and lets
+    // us skip the inner-loop processing entirely for the common single-level case.
+    const bodyHasInnerLoop = DomElementTemplate.hasLoop(outerBody)
+
+    const rendered = elArr.map((item, index) => {
+      const body = bodyHasInnerLoop
+        ? this.processInnerLoop(outerBody, item)
+        : outerBody
 
-    // convert to array if is string
-    elData = Array.isArray(elData) ? elData : [elData]
+      return this.substituteForItem(body, item, index)
+    }).join('')
 
-    return elData.map(mapStringData).join('')
+    this.currentOuterLoopData = previousOuter
+    return rendered
   }
 }