spyne 0.25.0 → 0.26.0

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spyne",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Reactive Real-DOM Framework for Advanced Javascript applications",
   "sideEffects": true,
   "main": "./lib/spyne.esm.js",

package/src/spyne/channels/channel-payload-class.js

@@ -12,7 +12,11 @@ import {
   is
 } from 'ramda'
 import { SpyneAppProperties } from '../utils/spyne-app-properties.js'
-import { safeClone } from '../utils/safe-clone.js'
+import { safeClone, safeCloneDeep } from '../utils/safe-clone.js'
+
+// read-only facades for cms-proxied payload subtrees, cached per proxy so
+// repeated dispatches of the same canonical data reuse a single wrapper
+const _readOnlyFacadeCache = new WeakMap()
 
 export class ChannelPayload {
   /**
@@ -45,8 +49,7 @@ export class ChannelPayload {
 
     const channelPayloadItemObj = { channelName, action, srcElement, event }
     // Object.defineProperty(channelPayloadItemObj, 'payload', {get: () => clone(payload)});
-    const frozenPayload = ChannelPayload.deepFreeze(payload)
-    channelPayloadItemObj.payload = frozenPayload
+    channelPayloadItemObj.payload = ChannelPayload.deepFreeze(payload)
     /**
      * This is a convenience method that helps with destructuring by merging all properties.
      *
@@ -71,14 +74,47 @@ export class ChannelPayload {
       ChannelPayload.validateAction(action, channel, channelActionsArr)
     }
 
-    channelPayloadItemObj.clone = () => mergeAll([
-      { payload:safeClone(channelPayloadItemObj.payload) },
-      channelPayloadItemObj.payload,
-      { channel: clone(channel) },
-      { event: clone(event) },
-      { srcElement },
-      clone(channelPayloadItemObj.srcElement), { action: clone(channelPayloadItemObj.action) }
-    ])
+    channelPayloadItemObj.clone = () => {
+      return mergeAll([
+        { payload:safeClone(channelPayloadItemObj.payload) },
+        channelPayloadItemObj.payload,
+        { channel: clone(channel) },
+        { event: clone(event) },
+        { srcElement },
+        clone(channelPayloadItemObj.srcElement), { action: clone(channelPayloadItemObj.action) }
+      ])
+    }
+
+    /**
+     * Proxy-preserving version of clone. Returns the same merged shape, but
+     * the payload is copied with safeCloneDeep, so any CMS proxy objects —
+     * at the root or nested inside plain containers or arrays — are revived
+     * as writable proxy copies instead of being stripped by a structural
+     * clone. Use this when a handler treats the payload as its data source.
+     *
+     * @returns
+     * JSON Object
+     *
+     * @example
+     * TITLE['<h4>Retrieving Proxied Payload Data</h4>']
+     * onStoryEvent(e){
+     *    const data = e.safeClone();
+     *    this.addStoryArticle(data);
+     * }
+     *
+     */
+    channelPayloadItemObj.safeClone = () => {
+      const revivedPayload = safeCloneDeep(channelPayloadItemObj.payload)
+      return mergeAll([
+        { payload: revivedPayload },
+        revivedPayload,
+        { channel },
+        { event },
+        { srcElement },
+        channelPayloadItemObj.srcElement,
+        { action: channelPayloadItemObj.action }
+      ])
+    }
 
     const channelPayloadItemObjProps = {
       $dir: {
@@ -145,22 +181,81 @@ export class ChannelPayload {
     return isIterable ? compose(fromPairs, toPairs, clone)(o) : clone(o)
   }
 
+  /**
+   * Wraps a CMS-proxied payload subtree in a read-only facade. Payloads are
+   * reference-by-wire (every subscriber shares the same object), and freezing
+   * a proxy would freeze the CANONICAL cms target for the whole app — so
+   * instead the payload boundary gets a lightweight second proxy that blocks
+   * writes while reads (and nested reads) pass through. Consumers that need
+   * a writable copy call e.safeClone(). Facades are cached per proxy so
+   * repeated dispatches of the same data reuse one wrapper.
+   */
+  static createReadOnlyProxyFacade(proxyObj) {
+    if (_readOnlyFacadeCache.has(proxyObj)) {
+      return _readOnlyFacadeCache.get(proxyObj)
+    }
+
+    const warnBlockedWrite = (propName) => {
+      if (SpyneAppProperties.debug === true) {
+        console.warn(`Spyne Warning: blocked write of '${String(propName)}' on read-only channel payload data; use e.safeClone() for a writable copy`)
+      }
+      return true // silent no-op; returning false would throw in strict mode
+    }
+
+    const facade = new Proxy(proxyObj, {
+      get(target, propName) {
+        const val = target[propName]
+        // nested cms containers are proxies themselves — wrap them so deep
+        // writes are blocked too (cached, so repeat reads reuse the facade)
+        if (val !== null && typeof val === 'object' && val.__proxy__isProxy === true) {
+          return ChannelPayload.createReadOnlyProxyFacade(val)
+        }
+        return val
+      },
+      set(target, propName) {
+        return warnBlockedWrite(propName)
+      },
+      defineProperty(target, propName) {
+        return warnBlockedWrite(propName)
+      },
+      deleteProperty(target, propName) {
+        return warnBlockedWrite(propName)
+      }
+    })
+
+    _readOnlyFacadeCache.set(proxyObj, facade)
+    return facade
+  }
+
   static deepFreeze(o) {
     // return o;
     // return Object.freeze(o);
     const elIsDomElement = compose(lte(0), defaultTo(-1), prop('nodeType'))
 
+    // CMS proxy subtrees are NOT frozen (that would freeze the canonical cms
+    // target app-wide) — they are wrapped in a read-only facade instead, so
+    // the payload immutability contract holds without copies
+    if (o !== null && typeof o === 'object' && o.__proxy__isProxy === true) {
+      return ChannelPayload.createReadOnlyProxyFacade(o)
+    }
+
     try {
-      Object.freeze(o)
+      // children first: proxy subtrees must be swapped for their facades
+      // BEFORE the parent is frozen, or the assignment would be rejected
       Object.getOwnPropertyNames(o).forEach(function(prop) {
+        const val = o[prop]
         if (Object.prototype.hasOwnProperty.call(o, prop) &&
-            elIsDomElement(o[prop]) === false &&
-            o[prop] !== null &&
-            (typeof o[prop] === 'object' || typeof o[prop] === 'function') &&
-            !Object.isFrozen(o[prop])) {
-          ChannelPayload.deepFreeze(o[prop])
+            elIsDomElement(val) === false &&
+            val !== null &&
+            (typeof val === 'object' || typeof val === 'function') &&
+            !Object.isFrozen(val)) {
+          const processed = ChannelPayload.deepFreeze(val)
+          if (processed !== val) {
+            o[prop] = processed
+          }
         }
       })
+      Object.freeze(o)
     } catch (e) {
       // console.log("FREEZE ERR ",{o,e});
       return o

package/src/spyne/channels/channel.js

@@ -1,5 +1,6 @@
 import { registeredStreamNames } from './channels-config.js'
 import { ChannelPayload } from './channel-payload-class.js'
+import { safeCloneDeep } from '../utils/safe-clone.js'
 import { SpyneAppProperties } from '../utils/spyne-app-properties.js'
 import { RouteChannelUpdater } from '../utils/route-channel-updater.js'
 
@@ -318,6 +319,18 @@ export class Channel {
     const mergeProps = (d) => mergeAll([d, { action: prop('action', d) }, prop('payload', d), prop('srcElement', d)])
     const dataObj = obsVal => ({
       clone: () => mergeProps(obj.data),
+      // proxy-preserving clone — mirrors ChannelPayload.safeClone for
+      // channel-side getChannel subscribers
+      safeClone: () => {
+        const revivedPayload = safeCloneDeep(payload)
+        return mergeAll([
+          { payload: revivedPayload },
+          revivedPayload,
+          { action },
+          { srcElement },
+          { event: obsVal }
+        ])
+      },
       action,
       payload,
       srcElement,

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

@@ -3,10 +3,12 @@ import { checkIfObjIsNotEmptyOrNil } from '../utils/frp-tools.js'
 import { SpyneAppProperties } from '../utils/spyne-app-properties.js'
 import { SpyneUtilsChannelWindow } from '../utils/spyne-utils-channel-window.js'
 import { merge } from 'rxjs'
-import { map, debounceTime, skipWhile } from 'rxjs/operators'
+import { map, debounceTime, skipWhile, buffer, bufferCount, throttleTime, filter } from 'rxjs/operators'
 import { curry, pick, partialRight, mapObjIndexed, apply, map as rMap } from 'ramda'
 import { deepMerge } from '../utils/deep-merge.js'
 
+const customActionsArr = []
+
 export class SpyneChannelWindow extends Channel {
   /**
    * @module SpyneChannelWindow
@@ -21,6 +23,7 @@ export class SpyneChannelWindow extends Channel {
    * @param {Object} config
    * @property {Object} config - = {}; The config has several options used to listen to window and document events.
    * @property {Array} config.events - = []; Any window and document events can be added here.
+   * @property {Array} config.customEvents - = []; Application CustomEvents to capture. Each entry is either an event name string, or an object with a name property plus ONE rate/batch option: buffer (ms of quiet that closes a batch; emits one payload whose payload.detail is the array of batched details), count (batch every n events), debounce (ms; emits only the latest event), or throttle (ms; emits the leading event per window). Example: ['simple_event', {name: 'spyne_cms_item_connected', buffer: 400}].
    * @property {Object} config.mediaQueries - = {}; Media queries are added as key,value pairs; the key is the name of the boolean for the query, the value is the query itself.
    * @property {Boolean} config.listenForResize - = true; This is default listening for resize event.
    * @property {Boolean} config.listenForOrientation - = true; Listen for horizontal and landscape orientation changes on mobile devices.
@@ -181,12 +184,88 @@ export class SpyneChannelWindow extends Channel {
   getEventsFromConfig(config = this.domChannelConfig) {
     const obs$Arr = config.events
 
+    const customEntries = Array.isArray(config.customEvents)
+      ? config.customEvents.map(SpyneChannelWindow.conformCustomEventConfig).filter(entry => entry !== null)
+      : []
+
+    customEntries.forEach(entry => this.updateChannelActions(entry.name))
+
     const addWindowEventToArr = str => {
       const mapFn = SpyneChannelWindow.createCurriedGenericEvent(str)
       return SpyneUtilsChannelWindow.createDomObservableFromEvent(str, mapFn)
     }
 
-    return rMap(addWindowEventToArr, obs$Arr)
+    const addCustomEventToArr = ({ name, operator, value }) => {
+      const obs$ = addWindowEventToArr(name)
+      return operator === undefined ? obs$ : SpyneChannelWindow.customizeCustomEventObservable(obs$, operator, value)
+    }
+
+    return rMap(addWindowEventToArr, obs$Arr).concat(rMap(addCustomEventToArr, customEntries))
+  }
+
+  /**
+   * Normalizes a config.customEvents entry — an event name string or a
+   * {name, <operator>} object — to {name, operator, value}. Complexity is
+   * capped at one level: a single operator key (buffer, count, debounce or
+   * throttle); when several are set the first in that order wins.
+   */
+  static conformCustomEventConfig(entry) {
+    if (typeof entry === 'string') {
+      return { name: entry, operator: undefined, value: undefined }
+    }
+
+    if (entry !== null && typeof entry === 'object' && typeof entry.name === 'string') {
+      const operatorKeys = ['buffer', 'count', 'debounce', 'throttle']
+      const setKeys = operatorKeys.filter(key => entry[key] !== undefined)
+      const operator = setKeys[0]
+
+      if (setKeys.length > 1 && SpyneAppProperties.debug === true) {
+        console.warn(`Spyne Warning: the customEvent, ${entry.name}, sets multiple operators (${setKeys.join(', ')}); using ${operator}.`)
+      }
+
+      return { name: entry.name, operator, value: operator !== undefined ? entry[operator] : undefined }
+    }
+
+    console.warn(`Spyne Warning: the following config.customEvents entry is not a string or a {name} object and was skipped: ${JSON.stringify(entry)}`)
+    return null
+  }
+
+  /**
+   * Applies the entry's rate/batch operator to the conformed CustomEvent
+   * observable. buffer and count emit ONE batched payload (payload.detail is
+   * the array of each event's detail); debounce and throttle pass single
+   * conformed events through untouched.
+   */
+  static customizeCustomEventObservable(obs$, operator, value) {
+    switch (operator) {
+      case 'buffer':
+        // quiet-gap batching: the batch closes after `value` ms without a new event
+        return obs$.pipe(
+          buffer(obs$.pipe(debounceTime(value))),
+          filter(pArr => pArr.length > 0),
+          map(SpyneChannelWindow.mapBatchedEvents)
+        )
+      case 'count':
+        // fixed-size batching: a partial batch is held until it fills
+        return obs$.pipe(
+          bufferCount(value),
+          map(SpyneChannelWindow.mapBatchedEvents)
+        )
+      case 'debounce':
+        return obs$.pipe(debounceTime(value))
+      case 'throttle':
+        return obs$.pipe(throttleTime(value))
+      default:
+        return obs$
+    }
+  }
+
+  static mapBatchedEvents(pArr) {
+    const last = pArr[pArr.length - 1]
+    const { action, srcElement, event } = last
+    const detail = pArr.map(p => p.event !== undefined && p.event !== null ? p.event.detail : undefined)
+    const payload = { detail, isBatch: true, batchCount: pArr.length }
+    return { action, payload, srcElement, event }
   }
 
   getActiveObservables(config = this.domChannelConfig) {
@@ -245,8 +324,19 @@ export class SpyneChannelWindow extends Channel {
     return obs$.pipe(map(this.getMediaQueryMapFn.bind(this)))
   }
 
+  updateChannelActions(str) {
+    if (typeof str !== 'string') {
+      return
+    }
+    function getWindowAction() {
+      return `CHANNEL_WINDOW_${str.toUpperCase()}_EVENT`
+    }
+    const windowAction = getWindowAction()
+    customActionsArr.push(windowAction)
+  }
+
   addRegisteredActions() {
-    return [
+    const mainActions = [
       'CHANNEL_WINDOW_ABORT_EVENT',
       'CHANNEL_WINDOW_AFTERPRINT_EVENT',
       'CHANNEL_WINDOW_ANIMATIONEND_EVENT',
@@ -334,6 +424,8 @@ export class SpyneChannelWindow extends Channel {
       'CHANNEL_WINDOW_UNLOAD_EVENT',
       'CHANNEL_WINDOW_WHEEL_EVENT'
     ]
+
+    return mainActions.concat(customActionsArr)
   }
 
   onScrollLockEvent(e) {

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.25.0'
+const version = '0.26.0'
 
 class SpyneApplication {
   /**
@@ -41,7 +41,7 @@ class SpyneApplication {
   init(config = {}, testMode = false) {
     // this.channels = new ChannelsMap();
     /*!
-     * Spyne 0.25.0
+     * Spyne 0.26.0
      * https://spynejs.org
      *
      * @license
@@ -77,6 +77,7 @@ class SpyneApplication {
       mode: 'app',
       disableSanitize: false,
       iframes: {},
+      anchors: {},
       customElements: [],
       baseHref: undefined,
       IMG_PATH: imgPath,
@@ -95,6 +96,7 @@ class SpyneApplication {
 
           },
           events: [],
+          customEvents: [],
           listenForResize: true,
           listenForOrientation: true,
           listenForScroll: false,

package/src/spyne/spyne-plugins.js

@@ -128,16 +128,33 @@ export class SpynePlugin {
 
   checkForRequiredWindowEvent() {
     const requiredEvents = this.props.requiredEvents ?? []
+    const requiredCustomEvents = this.props.requiredCustomEvents ?? []
+
     const windowConfig = SpyneAppProperties.getChannelConfig('WINDOW')
 
     const missingEvents = requiredEvents.filter(evt => !windowConfig.events.includes(evt))
 
+    // entries on BOTH sides can be a name string or a {name, buffer|count|debounce|throttle}
+    // object — hosts declare how the event is conformed, plugins declare the exact
+    // configuration they expect, and matching is by name only
+    const entryName = entry => typeof entry === 'string' ? entry : entry?.name
+    const customEventNames = windowConfig.customEvents.map(entryName)
+    const missingCustomEvents = requiredCustomEvents.filter(evt => !customEventNames.includes(entryName(evt)))
+
     // If any are missing, log a single warning listing them
     if (missingEvents.length > 0) {
       console.warn(
           `plugin "${this.props.name}" requires the following config.WINDOW.events, --> ${missingEvents.join(', ')} <--`
       )
     }
+
+    if (missingCustomEvents.length > 0) {
+      // print the exact configuration entry so it can be pasted into the host config
+      const entryAsConfigStr = entry => typeof entry === 'string' ? `'${entry}'` : JSON.stringify(entry)
+      console.warn(
+        `plugin "${this.props.name}" requires the following config.WINDOW.customEvents, --> ${missingCustomEvents.map(entryAsConfigStr).join(', ')} <--`
+      )
+    }
   }
 
   defaultConfig() {

package/src/spyne/spyne.js

@@ -14,7 +14,7 @@ import { ChannelPayload } from './channels/channel-payload-class.js'
 import { ChannelPayloadFilter } from './utils/channel-payload-filter.js'
 import { SpynePlugin } from './spyne-plugins.js'
 import { deepMerge } from './utils/deep-merge.js'
-import { safeClone } from './utils/safe-clone.js'
+import { safeClone, safeCloneDeep, safeAugment, safeFilter, safeMap, safeReject } from './utils/safe-clone.js'
 import { SpyneAppProperties } from './utils/spyne-app-properties.js'
 import { SpyneApp } from './spyne-app.js'
 import { setSpyneWarningsDisabled } from './utils/spyne-warn.js'
@@ -40,6 +40,11 @@ export {
   SpynePlugin,
   deepMerge,
   safeClone,
+  safeCloneDeep,
+  safeAugment,
+  safeFilter,
+  safeMap,
+  safeReject,
   sanitizeData,
   sanitizeEventTarget,
   allowCustomElements,

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

@@ -16,7 +16,6 @@ import {
   mergeAll,
   F,
   omit,
-  flatten,
   any,
   curry,
   lte
@@ -218,8 +217,11 @@ export class ChannelPayloadFilter {
     const { payload, srcElement, event } = srcPayload || {}
 
     const reduceFindEl = (acc, src) => {
+      if (acc !== undefined) {
+        return acc
+      }
       const el = prop('el', src)
-      if (ChannelPayloadFilter.elIsDomElement(el) && acc === undefined) {
+      if (ChannelPayloadFilter.elIsDomElement(el)) {
         acc = el
       }
       return acc
@@ -227,35 +229,37 @@ export class ChannelPayloadFilter {
 
     const el = [srcElement, payload, prop('srcElement', event), srcPayload].reduce(reduceFindEl, undefined)
 
-    // RETURN BOOLEAN MATCH WITH PAYLOAD EL
-    const compareEls = (elCompare) => elCompare.isEqualNode((el))
-
-    // LOOP THROUGH NODES IN querySelectorAll()
-    const mapNodeArrWithEl = (sel) => {
-      // convert nodelist to array of els
-      const nodeArr = Array.from(document.querySelectorAll(sel))
-      // els array to boolean array
-      return rMap(compareEls, nodeArr)
+    // CHECK IF PAYLOAD EL EXISTS
+    const elCanMatch = el !== null && typeof el === 'object' && typeof el.matches === 'function'
+
+    // the payload element is tested directly with Element.matches — the same
+    // "is this el one of the selector's elements" answer as the previous
+    // document-wide querySelectorAll walk, without scanning the document on
+    // every dispatch (isEqualNode could also pass a structural lookalike of
+    // a matched node, which was an over-match, not a contract)
+    const elMatches = (sel) => {
+      try {
+        return el.matches(sel)
+      } catch (e) {
+        if (SpyneAppProperties.debug === true) {
+          console.warn(`Spyne Warning: The ChannelPayloadFilter selector, ${sel}, is not a valid css selector!`)
+        }
+        return false
+      }
     }
 
+    const matchesBoolArr = elCanMatch ? rMap(elMatches, arr) : []
+
     if (debugLabel !== undefined) {
-      const nodeArrResultsDebugger = compose(flatten, rMap(mapNodeArrWithEl))(arr)
       const selectorsArr = arr
-      console.log(`%c CHANNEL PAYLOAD FILTER DEBUGGER ["${debugLabel}"] - selectors: `, 'color:orange;', { el, selectorsArr, nodeArrResultsDebugger })
-    }
-
-    // CHECK IF PAYLOAD EL EXISTS
-    if (typeof (el) !== 'object') {
-      return false
+      console.log(`%c CHANNEL PAYLOAD FILTER DEBUGGER ["${debugLabel}"] - selectors: `, 'color:orange;', { el, selectorsArr, nodeArrResultsDebugger: matchesBoolArr })
     }
 
-    // LOOP THROUGH ALL SELECTORS IN MAIN ARRAY
-    const nodeArrResult = compose(flatten, rMap(mapNodeArrWithEl))(arr)
-    if (isEmpty(nodeArrResult) === true) {
+    if (elCanMatch === false || isEmpty(matchesBoolArr) === true) {
       return false
     }
 
-    return any(equals(true), nodeArrResult)
+    return any(equals(true), matchesBoolArr)
   }
 
   static elIsDomElement(o) {

package/src/spyne/utils/safe-clone.js

@@ -15,7 +15,7 @@ const getPropType = (prp) => {
   return type
 }
 
-const cmsDataReviveNestedProxyObj = (proxyObj, proxyReviverMethod) => {
+const cmsDataReviveNestedProxyObj = (proxyObj = {}, proxyReviverMethod) => {
   const { __proxy__proxyName } = proxyObj
 
   if (__proxy__proxyName === undefined) {
@@ -50,7 +50,7 @@ const cmsDataReviveNestedProxyObj = (proxyObj, proxyReviverMethod) => {
   return rootObj
 }
 
-export const safeClone = function(o) {
+const reviveIfProxy = (o = {}) => {
   const { __proxy__proxyName } = o
   if (__proxy__proxyName !== undefined) {
     const proxyReviverMethod = SpyneAppProperties.getProxyReviver(__proxy__proxyName)
@@ -58,6 +58,132 @@ export const safeClone = function(o) {
       return cmsDataReviveNestedProxyObj(o, proxyReviverMethod)
     }
   }
+  return undefined
+}
+
+/**
+ *
+ * Deep, proxy-preserving clone. Unlike safeClone — which only revives when the
+ * ROOT object is a proxy — this walks plain containers (objects and arrays)
+ * and revives any nested proxy it finds, so wrappers that hold proxied data
+ * (e.g. channel payloads, pageData containers) survive cloning intact.
+ * Functions are passed through by reference; cycles are guarded.
+ *
+ * @param {Object|Array} o
+ * @returns A writable copy in which every nested proxy has been revived
+ */
+export const safeCloneDeep = function(o, seen = new WeakSet()) {
+  if (o === null || typeof o !== 'object') {
+    return o
+  }
+
+  const revived = reviveIfProxy(o)
+  if (revived !== undefined) {
+    return revived
+  }
+
+  if (seen.has(o)) {
+    return o
+  }
+  seen.add(o)
+
+  if (Array.isArray(o)) {
+    return o.map(item => safeCloneDeep(item, seen))
+  }
+
+  const out = {}
+  Object.entries(o).forEach(([key, val]) => {
+    out[key] = safeCloneDeep(val, seen)
+  })
+  return out
+}
+
+/**
+ * Re-wraps a derived array with the SOURCE array's proxy metadata via the
+ * registered reviver. Native filter/reject/map keep element identity but
+ * return a plain array — losing the array-level proxy that string-item
+ * template loops (e.g. {{#titles}}) rely on for __cms__dataId / keyFor
+ * lookups. In production (no proxies) this is a single undefined check.
+ *
+ * Note: the reviver rebuilds its key/value map from the derived contents, so
+ * value-keyed lookups survive while original index positions shift.
+ */
+const rewrapArrayFromSource = (sourceArr, resultArr) => {
+  const proxyName = sourceArr?.__proxy__proxyName
+  if (proxyName === undefined) {
+    return resultArr
+  }
+  const proxyReviverMethod = SpyneAppProperties.getProxyReviver(proxyName)
+  if (typeof proxyReviverMethod !== 'function') {
+    return resultArr
+  }
+  return proxyReviverMethod(resultArr, sourceArr.__proxy__props)
+}
+
+/**
+ *
+ * Proxy-preserving Array.prototype.filter: elements keep their identity
+ * (native behavior) AND the returned array keeps the source array's proxy
+ * metadata. Use in place of ramda filter / arr.filter on CMS data.
+ */
+export const safeFilter = function(arr, predicate) {
+  return rewrapArrayFromSource(arr, arr.filter(predicate))
+}
+
+/**
+ *
+ * Proxy-preserving reject — inverse of safeFilter.
+ */
+export const safeReject = function(arr, predicate) {
+  return rewrapArrayFromSource(arr, arr.filter((item, i) => predicate(item, i) === false))
+}
+
+/**
+ *
+ * Proxy-preserving Array.prototype.map with an augment-in-place contract:
+ * proxied elements arrive in the callback as WRITABLE revived copies, so
+ * `safeMap(stories, s => { s.type = 'story'; return s; })` is safe by
+ * construction (no silent live-proxy write traps). Plain elements pass by
+ * reference exactly like native map, so production cost matches native.
+ * A callback that builds an entirely new object per element still strips
+ * that element's identity — there is nothing left to preserve.
+ */
+export const safeMap = function(arr, mapFn) {
+  const result = arr.map((item, i) => {
+    const isProxied = item !== null && typeof item === 'object' && item.__proxy__proxyName !== undefined
+    return mapFn(isProxied ? safeCloneDeep(item) : item, i)
+  })
+  return rewrapArrayFromSource(arr, result)
+}
+
+/**
+ *
+ * Revive-then-augment. Live CMS proxies silently ignore writes of new keys,
+ * so properties cannot be attached to them directly. This returns a writable,
+ * proxy-preserved copy of o with the given props applied — the sanctioned way
+ * to add view or route properties to CMS-proxied data.
+ *
+ * @param {Object|Array} o
+ * @param {Object} propsObj properties to assign onto the revived copy
+ * @returns A writable proxy-preserved copy carrying the extra props
+ */
+export const safeAugment = function(o, propsObj = {}) {
+  const target = safeCloneDeep(o)
+  Object.entries(propsObj).forEach(([key, val]) => {
+    target[key] = val
+  })
+  return target
+}
+
+export const safeClone = function(o, deep = false) {
+  const revived = reviveIfProxy(o)
+  if (revived !== undefined) {
+    return revived
+  }
+
+  if (deep === true) {
+    return safeCloneDeep(o)
+  }
 
   const isArr = is(Array)
   const isObj = is(Object)