clarity-js 0.6.23

package/src/layout/mutation.ts

@@ -0,0 +1,232 @@
+import { Priority, Task, Timer } from "@clarity-types/core";
+import { Code, Event, Metric, Severity } from "@clarity-types/data";
+import { Constant, MutationHistory, MutationQueue, Setting, Source } from "@clarity-types/layout";
+import { bind } from "@src/core/event";
+import measure from "@src/core/measure";
+import * as task from "@src/core/task";
+import { time } from "@src/core/time";
+import { clearTimeout, setTimeout } from "@src/core/timeout";
+import { id } from "@src/data/metadata";
+import * as summary from "@src/data/summary";
+import * as internal from "@src/diagnostic/internal";
+import * as doc from "@src/layout/document";
+import * as dom from "@src/layout/dom";
+import encode from "@src/layout/encode";
+import * as region from "@src/layout/region";
+import traverse from "@src/layout/traverse";
+import processNode from "./node";
+
+let observers: MutationObserver[] = [];
+let mutations: MutationQueue[] = [];
+let insertRule: (rule: string, index?: number) => number = null;
+let deleteRule: (index?: number) => void = null;
+let queue: Node[] = [];
+let timeout: number = null;
+let activePeriod = null;
+let history: MutationHistory = {};
+
+
+export function start(): void {
+    observers = [];
+    queue = [];
+    timeout = null;
+    activePeriod = 0;
+    history = {};
+
+    if (insertRule === null) { insertRule = CSSStyleSheet.prototype.insertRule; }
+    if (deleteRule === null) { deleteRule = CSSStyleSheet.prototype.deleteRule; }
+
+    // Some popular open source libraries, like styled-components, optimize performance
+    // by injecting CSS using insertRule API vs. appending text node. A side effect of
+    // using javascript API is that it doesn't trigger DOM mutation and therefore we
+    // need to override the insertRule API and listen for changes manually.
+    CSSStyleSheet.prototype.insertRule = function(): number {
+      schedule(this.ownerNode);
+      return insertRule.apply(this, arguments);
+    };
+
+    CSSStyleSheet.prototype.deleteRule = function(): void {
+      schedule(this.ownerNode);
+      return deleteRule.apply(this, arguments);
+    };
+}
+
+export function observe(node: Node): void {
+  // Create a new observer for every time a new DOM tree (e.g. root document or shadowdom root) is discovered on the page
+  // In the case of shadow dom, any mutations that happen within the shadow dom are not bubbled up to the host document
+  // For this reason, we need to wire up mutations every time we see a new shadow dom.
+  // Also, wrap it inside a try / catch. In certain browsers (e.g. legacy Edge), observer on shadow dom can throw errors
+  try {
+    // In an edge case, it's possible to get stuck into infinite Mutation loop within Angular applications
+    // This appears to be an issue with Zone.js package, see: https://github.com/angular/angular/issues/31712
+    // As a temporary work around, ensuring Clarity can invoke MutationObserver outside of Zone (and use native implementation instead)
+    let api: string = window[Constant.Zone] && Constant.Symbol in window[Constant.Zone] ? window[Constant.Zone][Constant.Symbol](Constant.MutationObserver) : Constant.MutationObserver;
+    let observer =  api in window ? new window[api](measure(handle) as MutationCallback) : null;
+    if (observer) {
+      observer.observe(node, { attributes: true, childList: true, characterData: true, subtree: true });
+      observers.push(observer);
+    }
+  } catch (e) { internal.log(Code.MutationObserver, Severity.Info, e ? e.name : null); }
+}
+
+export function monitor(frame: HTMLIFrameElement): void {
+  // Bind to iframe's onload event so we get notified anytime there's an update to iframe content.
+  // This includes cases where iframe location is updated without explicitly updating src attribute
+  // E.g. iframe.contentWindow.location.href = "new-location";
+  if (dom.has(frame) === false) {
+    bind(frame, Constant.LoadEvent, generate.bind(this, frame, Constant.ChildList), true);
+  }
+}
+
+export function stop(): void {
+  for (let observer of observers) { if (observer) { observer.disconnect(); } }
+  observers = [];
+
+  // Restoring original insertRule
+  if (insertRule !== null) {
+    CSSStyleSheet.prototype.insertRule = insertRule;
+    insertRule = null;
+  }
+
+  // Restoring original deleteRule
+  if (deleteRule !== null) {
+    CSSStyleSheet.prototype.deleteRule = deleteRule;
+    deleteRule = null;
+  }
+
+  history = {};
+  mutations = [];
+  queue = [];
+  activePeriod = 0;
+  timeout = null;
+}
+
+export function active(): void {
+  activePeriod = time() + Setting.MutationActivePeriod;
+}
+
+function handle(m: MutationRecord[]): void {
+  // Queue up mutation records for asynchronous processing
+  let now = time();
+  summary.track(Event.Mutation, now);
+  mutations.push({ time: now, mutations: m});
+  task.schedule(process, Priority.High).then((): void => {
+      measure(doc.compute)();
+      measure(region.compute)();
+  });
+}
+
+async function process(): Promise<void> {
+  let timer: Timer = { id: id(), cost: Metric.LayoutCost };
+  task.start(timer);
+  while (mutations.length > 0) {
+    let record = mutations.shift();
+    for (let mutation of record.mutations) {
+      let state = task.state(timer);
+      if (state === Task.Wait) { state = await task.suspend(timer); }
+      if (state === Task.Stop) { break; }      
+      let target = mutation.target;
+      let type = track(mutation, timer);
+      if (type && target && target.ownerDocument) { dom.parse(target.ownerDocument); }
+      switch (type) {
+        case Constant.Attributes:
+            processNode(target, Source.Attributes);
+            break;
+        case Constant.CharacterData:
+            processNode(target, Source.CharacterData);
+            break;
+        case Constant.ChildList:
+          processNodeList(mutation.addedNodes, Source.ChildListAdd, timer);
+          processNodeList(mutation.removedNodes, Source.ChildListRemove, timer);
+          break;
+        case Constant.Suspend:
+          let value = dom.get(target);
+          if (value) { value.data.tag = Constant.SuspendMutationTag; }
+          break;
+        default:
+          break;
+      }
+    }
+    await encode(Event.Mutation, timer, record.time);
+  }
+  task.stop(timer);
+}
+
+function track(m: MutationRecord, timer: Timer): string {
+  let value = m.target ? dom.get(m.target.parentNode) : null;
+  // Check if the parent is already discovered and that the parent is not the document root
+  if (value && value.selector !== Constant.HTML) {
+    let inactive = time() > activePeriod;
+    let target = dom.get(m.target);
+    let element = target ? target.selector : m.target.nodeName;
+    // We use selector, instead of id, to determine the key (signature for the mutation) because in some cases
+    // repeated mutations can cause elements to be destroyed and then recreated as new DOM nodes
+    // In those cases, IDs will change however the selector (which is relative to DOM xPath) remains the same
+    let key = [value.selector, element, m.attributeName, names(m.addedNodes), names(m.removedNodes)].join();
+    // Initialize an entry if it doesn't already exist
+    history[key] = key in history ? history[key] : [0];
+    let h = history[key];
+    // Lookup any pending nodes queued up for removal, and process them now if we suspended a mutation before
+    if (inactive === false && h[0] >= Setting.MutationSuspendThreshold) { processNodeList(h[1], Source.ChildListRemove, timer); }
+    // Update the counter
+    h[0] = inactive ? h[0] + 1 : 1;
+    // Return updated mutation type based on if we have already hit the threshold or not
+    if (h[0] === Setting.MutationSuspendThreshold) {
+      // Store a reference to removedNodes so we can process them later
+      // when we resume mutations again on user interactions
+      h[1] = m.removedNodes;
+      return Constant.Suspend;
+    } else if (h[0] > Setting.MutationSuspendThreshold) { return Constant.Empty; }
+  }
+  return m.type;
+}
+
+function names(nodes: NodeList): string {
+  let output: string[] = [];
+  for (let i = 0; nodes && i < nodes.length; i++) { output.push(nodes[i].nodeName); }
+  return output.join();
+}
+
+async function processNodeList(list: NodeList, source: Source, timer: Timer): Promise<void> {
+  let length = list ? list.length : 0;
+  for (let i = 0; i < length; i++) {
+    if (source === Source.ChildListAdd) {
+      traverse(list[i], timer, source);
+    } else {
+      let state = task.state(timer);
+      if (state === Task.Wait) { state = await task.suspend(timer); }
+      if (state === Task.Stop) { break; }
+      processNode(list[i], source);
+    }
+  }
+}
+
+function schedule(node: Node): void {
+  // Only schedule manual trigger for this node if it's not already in the queue
+  if (queue.indexOf(node) < 0) { queue.push(node); }
+
+  // Cancel any previous trigger before scheduling a new one.
+  // It's common for a webpage to call multiple synchronous "insertRule" / "deleteRule" calls.
+  // And in those cases we do not wish to monitor changes multiple times for the same node.
+  if (timeout) { clearTimeout(timeout); }
+  timeout = setTimeout(trigger, Setting.LookAhead);
+}
+
+function trigger(): void {
+  for (let node of queue) { generate(node, Constant.CharacterData); }
+  queue = [];
+}
+
+function generate(target: Node, type: MutationRecordType): void {
+  measure(handle)([{
+    addedNodes: [target],
+    attributeName: null,
+    attributeNamespace: null,
+    nextSibling: null,
+    oldValue: null,
+    previousSibling: null,
+    removedNodes: [],
+    target,
+    type
+  }]);
+}

package/src/layout/node.ts

@@ -0,0 +1,211 @@
+import { Constant, Source } from "@clarity-types/layout";
+import { Code, Dimension, Severity } from "@clarity-types/data";
+import config from "@src/core/config";
+import * as dom from "./dom";
+import * as dimension from "@src/data/dimension";
+import * as internal from "@src/diagnostic/internal";
+import * as interaction from "@src/interaction";
+import * as mutation from "@src/layout/mutation";
+import * as schema from "@src/layout/schema";
+
+const IGNORE_ATTRIBUTES = ["title", "alt", "onload", "onfocus", "onerror"];
+
+export default function (node: Node, source: Source): Node {
+    let child: Node = null;
+
+    // Do not track this change if we are attempting to remove a node before discovering it
+    if (source === Source.ChildListRemove && dom.has(node) === false) { return child; }
+
+    // Special handling for text nodes that belong to style nodes
+    if (source !== Source.Discover &&
+        node.nodeType === Node.TEXT_NODE &&
+        node.parentElement &&
+        node.parentElement.tagName === "STYLE") {
+        node = node.parentNode;
+    }
+
+    let add = dom.has(node) === false;
+    let call = add ? "add" : "update";
+    let parent = node.parentElement ? node.parentElement : null;
+    let insideFrame = node.ownerDocument !== document;
+    switch (node.nodeType) {
+        case Node.DOCUMENT_TYPE_NODE:
+            parent = insideFrame && node.parentNode ? dom.iframe(node.parentNode) : parent;
+            let docTypePrefix = insideFrame ? Constant.IFramePrefix : Constant.Empty;
+            let doctype = node as DocumentType;
+            let docAttributes = { name: doctype.name, publicId: doctype.publicId, systemId: doctype.systemId };
+            let docData = { tag: docTypePrefix + Constant.DocumentTag, attributes: docAttributes };
+            dom[call](node, parent, docData, source);
+            break;
+        case Node.DOCUMENT_NODE:
+            // We check for regions in the beginning when discovering document and
+            // later whenever there are new additions or modifications to DOM (mutations)
+            if (node === document) dom.parse(document);
+            observe(node);
+            break;
+        case Node.DOCUMENT_FRAGMENT_NODE:
+            let shadowRoot = (node as ShadowRoot);
+            if (shadowRoot.host) {
+                let type = typeof (shadowRoot.constructor);
+                if (type === Constant.Function && shadowRoot.constructor.toString().indexOf(Constant.NativeCode) >= 0) {
+                    observe(shadowRoot);
+                    // See: https://wicg.github.io/construct-stylesheets/ for more details on adoptedStyleSheets.
+                    // At the moment, we are only able to capture "open" shadow DOM nodes. If they are closed, they are not accessible.
+                    // In future we may decide to proxy "attachShadow" call to gain access, but at the moment, we don't want to
+                    // cause any unintended side effect to the page. We will re-evaluate after we gather more real world data on this.
+                    let style = Constant.Empty as string;
+                    let adoptedStyleSheets: CSSStyleSheet[] = "adoptedStyleSheets" in shadowRoot ? shadowRoot["adoptedStyleSheets"] : [];
+                    for (let styleSheet of adoptedStyleSheets) { style += getCssRules(styleSheet); }
+                    let fragementData = { tag: Constant.ShadowDomTag, attributes: { style } };
+                    dom[call](node, shadowRoot.host, fragementData, source);
+                } else {
+                    // If the browser doesn't support shadow DOM natively, we detect that, and send appropriate tag back.
+                    // The differentiation is important because we don't have to observe pollyfill shadow DOM nodes,
+                    // the same way we observe real shadow DOM nodes (encapsulation provided by the browser).
+                    dom[call](node, shadowRoot.host, { tag: Constant.PolyfillShadowDomTag, attributes: {} }, source);
+                }
+            }
+            break;
+        case Node.TEXT_NODE:
+            // In IE11 TEXT_NODE doesn't expose a valid parentElement property. Instead we need to lookup parentNode property.
+            parent = parent ? parent : node.parentNode as HTMLElement;
+            // Account for this text node only if we are tracking the parent node
+            // We do not wish to track text nodes for ignored parent nodes, like script tags
+            // Also, we do not track text nodes for STYLE tags
+            // The only exception is when we receive a mutation to remove the text node, in that case
+            // parent will be null, but we can still process the node by checking it's an update call.
+            if (call === "update" || (parent && dom.has(parent) && parent.tagName !== "STYLE")) {
+                let textData = { tag: Constant.TextTag, value: node.nodeValue };
+                dom[call](node, parent, textData, source);
+            }
+            break;
+        case Node.ELEMENT_NODE:
+            let element = (node as HTMLElement);
+            let tag = element.tagName;
+            let attributes = getAttributes(element);
+            // In some cases, external libraries like vue-fragment, can modify parentNode property to not be in sync with the DOM
+            // For correctness, we first look at parentElement and if it not present then fall back to using parentNode
+            parent = node.parentElement ? node.parentElement : (node.parentNode ? node.parentNode as HTMLElement : null);
+            // If we encounter a node that is part of SVG namespace, prefix the tag with SVG_PREFIX
+            if (element.namespaceURI === Constant.SvgNamespace) { tag = Constant.SvgPrefix + tag; }
+
+            switch (tag) {
+                case "HTML":
+                    parent = insideFrame && parent ? dom.iframe(parent) : null;
+                    let htmlPrefix = insideFrame ? Constant.IFramePrefix : Constant.Empty;
+                    let htmlData = { tag: htmlPrefix + tag, attributes };
+                    dom[call](node, parent, htmlData, source);
+                    break;
+                case "SCRIPT":
+                    if (Constant.Type in attributes && attributes[Constant.Type] === Constant.JsonLD) {
+                        try {
+                            schema.ld(JSON.parse((element as HTMLScriptElement).text));
+                        } catch { /* do nothing */ }
+                    }
+                    break;
+                case "NOSCRIPT":
+                    break;
+                case "META":
+                    if (Constant.Property in attributes && Constant.Content in attributes) {
+                        let content = attributes[Constant.Content]
+                        switch(attributes[Constant.Property]) {
+                            case Constant.ogTitle:
+                                dimension.log(Dimension.MetaTitle, content)
+                                break;
+                            case Constant.ogType:
+                                dimension.log(Dimension.MetaType, content)
+                                break;
+                            case Constant.Generator:
+                                dimension.log(Dimension.Generator, content)
+                                break;
+                        } 
+                    }
+                    break;
+                case "HEAD":
+                    let head = { tag, attributes };
+                    if (location) { head.attributes[Constant.Base] = location.protocol + "//" + location.hostname; }
+                    dom[call](node, parent, head, source);
+                    break;
+                case "STYLE":
+                    let styleData = { tag, attributes, value: getStyleValue(element as HTMLStyleElement) };
+                    dom[call](node, parent, styleData, source);
+                    break;
+                case "IFRAME":
+                    let iframe = node as HTMLIFrameElement;
+                    let frameData = { tag, attributes };
+                    if (dom.sameorigin(iframe)) {
+                        mutation.monitor(iframe);
+                        frameData.attributes[Constant.SameOrigin] = "true";
+                        if (iframe.contentDocument && iframe.contentWindow && iframe.contentDocument.readyState !== "loading") {
+                            child = iframe.contentDocument;
+                        }
+                    }
+                    dom[call](node, parent, frameData, source);
+                    break;
+                default:
+                    let data = { tag, attributes };
+                    if (element.shadowRoot) { child = element.shadowRoot; }
+                    dom[call](node, parent, data, source);
+                    break;
+            }
+            break;
+        default:
+            break;
+    }
+    return child;
+}
+
+function observe(root: Node): void {
+    if (dom.has(root)) { return; }
+    mutation.observe(root); // Observe mutations for this root node
+    interaction.observe(root); // Observe interactions for this root node
+}
+
+function getStyleValue(style: HTMLStyleElement): string {
+    // Call trim on the text content to ensure we do not process white spaces ( , \n, \r\n, \t, etc.)
+    // Also, check if stylesheet has any data-* attribute, if so process rules instead of looking up text
+    let value = style.textContent ? style.textContent.trim() : Constant.Empty;
+    let dataset = style.dataset ? Object.keys(style.dataset).length : 0;
+    if (value.length === 0 || dataset > 0 || config.cssRules) {
+        value = getCssRules(style.sheet as CSSStyleSheet);
+    }
+    return value;
+}
+
+function getCssRules(sheet: CSSStyleSheet): string {
+    let value = Constant.Empty as string;
+    let cssRules = null;
+    // Firefox throws a SecurityError when trying to access cssRules of a stylesheet from a different domain
+    try { cssRules = sheet ? sheet.cssRules : []; } catch (e) {
+        internal.log(Code.CssRules, Severity.Warning, e ? e.name : null);
+        if (e && e.name !== "SecurityError") { throw e; }
+    }
+
+    if (cssRules !== null) {
+        for (let i = 0; i < cssRules.length; i++) {
+            value += cssRules[i].cssText;
+        }
+    }
+
+    return value;
+}
+
+function getAttributes(element: HTMLElement): { [key: string]: string } {
+    let output = {};
+    let attributes = element.attributes;
+    if (attributes && attributes.length > 0) {
+        for (let i = 0; i < attributes.length; i++) {
+            let name = attributes[i].name;
+            if (IGNORE_ATTRIBUTES.indexOf(name) < 0) {
+                output[name] = attributes[i].value;
+            }
+        }
+    }
+
+    // For INPUT tags read the dynamic "value" property if an explicit "value" attribute is not set
+    if (element.tagName === Constant.InputTag && !(Constant.Value in output) && (element as HTMLInputElement).value) {
+        output[Constant.Value] = (element as HTMLInputElement).value;
+    }
+
+    return output;
+}

package/src/layout/offset.ts

@@ -0,0 +1,19 @@
+import { OffsetDistance } from "@clarity-types/core";
+import { iframe } from "@src/layout/dom";
+
+export default function(element: HTMLElement): OffsetDistance {
+    let output: OffsetDistance = { x: 0, y: 0 };
+
+    // Walk up the chain to ensure we compute offset distance correctly
+    // In case where we may have nested IFRAMEs, we keep walking up until we get to the top most parent page
+    if (element && element.offsetParent) {
+        do {
+            let parent = element.offsetParent as HTMLElement;
+            let frame = parent === null ? iframe(element.ownerDocument) : null;
+            output.x += element.offsetLeft;
+            output.y += element.offsetTop;
+            element = frame ? frame : parent;
+        } while (element);
+    }
+    return output;
+}

package/src/layout/region.ts

@@ -0,0 +1,143 @@
+import { Event, Setting } from "@clarity-types/data";
+import { InteractionState, RegionData, RegionState, RegionQueue } from "@clarity-types/layout";
+import { time } from "@src/core/time";
+import * as dom from "@src/layout/dom";
+import encode from "@src/layout/encode";
+
+export let state: RegionState[] = [];
+let regionMap: WeakMap<Node, string> = null; // Maps region nodes => region name
+let regions: { [key: number]: RegionData } = {};
+let queue: RegionQueue[] = [];
+let watch = false;
+let observer: IntersectionObserver = null;
+
+export function start(): void {
+    reset();
+    observer = null;
+    regionMap = new WeakMap();
+    regions = {};
+    queue = [];
+    watch = window["IntersectionObserver"] ? true : false;
+    
+}
+
+export function observe(node: Node, name: string): void {
+    if (regionMap.has(node) === false) {
+        regionMap.set(node, name);
+        observer = observer === null && watch ? new IntersectionObserver(handler, {
+            // Get notified as intersection continues to change
+            // This allows us to process regions that get partially hidden during the lifetime of the page
+            // See: https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#creating_an_intersection_observer
+            // By default, intersection observers only fire an event when even a single pixel is visible and not thereafter.
+            threshold: [0,0.2,0.4,0.6,0.8,1]
+        }) : observer;
+        if (observer && node && node.nodeType === Node.ELEMENT_NODE) {
+            observer.observe(node as Element);
+        }
+    }
+}
+
+export function exists(node: Node): boolean {
+    // Check if regionMap is not null before looking up a node
+    // Since, dom module stops after region module, it's possible that we may set regionMap to be null
+    // and still attempt to call exists on a late coming DOM mutation (or addition), effectively causing a script error
+    return regionMap && regionMap.has(node);
+}
+
+export function track(id: number, event: Event): void {
+    let node = dom.getNode(id);
+    let data = id in regions ? regions[id] : { id, state: InteractionState.Rendered, name: regionMap.get(node) };
+    
+    // Determine the interaction state based on incoming event
+    let interactionState = InteractionState.Rendered;
+    switch (event) {
+        case Event.Click: interactionState = InteractionState.Clicked; break;
+        case Event.Input: interactionState = InteractionState.Input; break;
+    }
+    // Process updates to this region, if applicable
+    process(node, data, interactionState);
+}
+
+export function compute(): void {
+    // Process any regions where we couldn't resolve an "id" for at the time of last intersection observer event
+    // This could happen in cases where elements are not yet processed by Clarity's virtual DOM but browser reports a change, regardless.
+    // For those cases we add them to the queue and re-process them below
+    let q = [];
+    for (let r of queue) {
+        let id = dom.getId(r.node);
+        if (!(id in regions)) {
+            if (id) {
+                r.data.id = id;
+                regions[id] = r.data;
+                state.push(clone(r.data));
+            } else { q.push(r); }
+        }
+    }
+    queue = q;
+
+    // Schedule encode only when we have at least one valid data entry
+    if (state.length > 0) { encode(Event.Region); }
+}
+
+function handler(entries: IntersectionObserverEntry[]): void {
+    for (let entry of entries) {
+        let target = entry.target;
+        let rect = entry.boundingClientRect;
+        let overlap = entry.intersectionRect;
+        let viewport = entry.rootBounds;
+        // Only capture regions that have non-zero width or height to avoid tracking and sending regions
+        // that cannot ever be seen by the user. In some cases, websites will have a multiple copy of the same region
+        // like search box - one for desktop, and another for mobile. In those cases, CSS media queries determine which one should be visible.
+        // Also, if these regions ever become non-zero width or height (through AJAX, user action or orientation change) - we will automatically start monitoring them from that point onwards
+        if (regionMap.has(target) && rect.width + rect.height > 0 && viewport.width > 0 && viewport.height > 0) {
+            let id = target ? dom.getId(target) : null;
+            let data = id in regions ? regions[id] : { id, name: regionMap.get(target), state: InteractionState.Rendered };
+            
+            // For regions that have relatively smaller area, we look at intersection ratio and see the overlap relative to element's area
+            // However, for larger regions, area of regions could be bigger than viewport and therefore comparison is relative to visible area
+            let viewportRatio = overlap ? (overlap.width * overlap.height * 1.0) / (viewport.width * viewport.height) : 0;
+            let visible = viewportRatio > Setting.ViewportIntersectionRatio || entry.intersectionRatio > Setting.IntersectionRatio;
+
+            // Process updates to this region, if applicable
+            process(target, data, visible ? InteractionState.Visible : InteractionState.Rendered);
+
+            // Stop observing this element now that we have already received visibility signal
+            if (data.state >= InteractionState.Visible && observer) { observer.unobserve(target); }
+        }
+    }
+    if (state.length > 0) { encode(Event.Region); }
+}
+
+function process(n: Node, d: RegionData, s: InteractionState): void {
+    // Check if received a state that supersedes existing state
+    let updated = s > d.state;
+    d.state = updated ? s : d.state;
+    // If the corresponding node is already discovered, update the internal state
+    // Otherwise, track it in a queue to reprocess later.
+    if (d.id) {
+        if ((d.id in regions && updated) || !(d.id in regions)) {
+            regions[d.id] = d;
+            state.push(clone(d));
+        }
+    } else { queue.push({node: n, data: d}); }
+}
+
+function clone(r: RegionData): RegionState {
+    return { time: time(), data: { id: r.id, state: r.state, name: r.name }};
+}
+
+export function reset(): void {
+    state = [];   
+}
+
+export function stop(): void {
+    reset();
+    regionMap = null;
+    regions = {};
+    queue = [];
+    if (observer) {
+        observer.disconnect();
+        observer = null;
+    }
+    watch = false;
+}

package/src/layout/schema.ts

@@ -0,0 +1,66 @@
+import { Dimension, Metric, Setting } from "@clarity-types/data";
+import { Constant, JsonLD } from "@clarity-types/layout";
+import * as dimension from "@src/data/dimension";
+import * as metric from "@src/data/metric";
+
+const digitsRegex = /[^0-9\.]/g;
+
+/* JSON+LD (Linked Data) Recursive Parser */
+export function ld(json: any): void {
+    for (let key of Object.keys(json)) {
+        let value = json[key];
+        if (key === JsonLD.Type && typeof value === "string") {
+            value = value.toLowerCase();
+            /* Normalizations */
+            value = value.indexOf(JsonLD.Article) >= 0 || value.indexOf(JsonLD.Posting) >= 0 ? JsonLD.Article : value;
+            switch (value) {
+                case JsonLD.Article:
+                case JsonLD.Recipe:
+                    dimension.log(Dimension.SchemaType, json[key]);
+                    dimension.log(Dimension.AuthorName,  json[JsonLD.Creator]);
+                    dimension.log(Dimension.Headline,  json[JsonLD.Headline]);
+                    break;
+                case JsonLD.Product:
+                    dimension.log(Dimension.SchemaType, json[key]);
+                    dimension.log(Dimension.ProductName, json[JsonLD.Name]);
+                    dimension.log(Dimension.ProductSku, json[JsonLD.Sku]);
+                    if (json[JsonLD.Brand]) { dimension.log(Dimension.ProductBrand, json[JsonLD.Brand][JsonLD.Name]); }
+                    break;
+                case JsonLD.AggregateRating:
+                    if (json[JsonLD.RatingValue]) {
+                        metric.max(Metric.RatingValue, num(json[JsonLD.RatingValue], Setting.RatingScale));
+                        metric.max(Metric.BestRating, num(json[JsonLD.BestRating]));
+                        metric.max(Metric.WorstRating, num(json[JsonLD.WorstRating]));
+                    }
+                    metric.max(Metric.RatingCount, num(json[JsonLD.RatingCount]));
+                    metric.max(Metric.ReviewCount, num(json[JsonLD.ReviewCount]));
+                    break;
+                case JsonLD.Author:
+                    dimension.log(Dimension.AuthorName, json[JsonLD.Name]);
+                    break;
+                case JsonLD.Offer:
+                    dimension.log(Dimension.ProductAvailability, json[JsonLD.Availability]);
+                    dimension.log(Dimension.ProductCondition, json[JsonLD.ItemCondition]);
+                    dimension.log(Dimension.ProductCurrency, json[JsonLD.PriceCurrency]);
+                    dimension.log(Dimension.ProductSku, json[JsonLD.Sku]);
+                    metric.max(Metric.ProductPrice, num(json[JsonLD.Price]));
+                    break;
+                case JsonLD.Brand:
+                    dimension.log(Dimension.ProductBrand, json[JsonLD.Name]);
+                    break;
+            }
+        }
+        // Continue parsing nested objects
+        if (value !== null && typeof(value) === Constant.Object) { ld(value); }
+    }
+}
+
+function num(input: string | number, scale: number = 1): number {
+    if (input !== null) {
+        switch (typeof input) {
+            case Constant.Number: return Math.round((input as number) * scale);
+            case Constant.String: return Math.round(parseFloat((input as string).replace(digitsRegex, Constant.Empty)) * scale);
+        }
+    }
+    return null;
+}