jailedthreejs 0.9.2-beta.0

package/dist/cell.js

@@ -0,0 +1,508 @@
+// cell.js
+//
+// The Cell class drives a single <cell> element:
+// - DOM → Three.js object conversion
+// - Event wiring / raycasting integration
+// - CSS → object painting
+// - Mutation observers (DOM + <style> changes)
+// - Per-frame update callbacks
+
+import * as THREE from 'three';
+import { fastRemove_arry, getClassMap } from './utils.js';
+import {
+  paintCell,
+  paintConvict,
+  deep_searchParms,
+  paintSpecificMuse,
+  paintConstantMuse,
+  getCSSRule
+} from './artist.js';
+import {
+  default_onCellClick_method,
+  default_onCellPointerMove_method,
+  default_onCellMouseDown_method,
+  default_onCellMouseUp_method,
+  default_onCellDoubleClick_method,
+  default_onCellContextMenu_method
+} from './NoScope.js';
+
+class Cell {
+  static allCells = new WeakMap();
+
+  /**
+   * Retrieve an existing Cell for a <cell> element.
+   *
+   * @param {HTMLElement} element
+   * @returns {Cell|null}
+   */
+  static getCell(element) {
+    if (Cell.allCells.has(element)) {
+      return Cell.allCells.get(element);
+    }
+    console.error('No Cell found with the element:', element);
+    return null;
+  }
+
+  /**
+   * @param {HTMLElement} cellElm
+   * @param {THREE.WebGLRenderer} renderer
+   * @param {THREE.Scene} scene
+   * @param {THREE.Camera|null} [camera=null]
+   * @param {Function|null} [_MainAnimMethod=null]
+   */
+  constructor(cellElm, renderer, scene, camera = null, _MainAnimMethod = null) {
+    this.cellElm = cellElm;
+    Object.defineProperty(cellElm, 'cell', {
+      value: this,
+      enumerable: false
+    });
+
+    this.threeRenderer = renderer;
+    this.loadedScene = scene;
+    this.focusedCamera = camera;
+
+    this.constantConvicts = [];
+    this.classyConvicts = [];
+    this.namedConvicts = [];
+    this._allConvictsByDom = new WeakMap();
+
+    this.updateFunds = [];
+    this._observedStyleElements = new WeakSet();
+    this._pendingStyleRepaint = false;
+
+    // paint constant :active rules each frame
+    this.updateFunds.push(() => {
+      this.constantConvicts.forEach(cC => {
+        paintConstantMuse(cC);
+      });
+    });
+
+    this._last_cast_caught = null;
+    this._lastHitPosition = null;
+    Cell.allCells.set(cellElm, this);
+
+    // initial scan
+    this._ScanCell();
+
+    // bind DOM event handlers
+    this._boundPointerMove = evt => {
+      default_onCellPointerMove_method(evt, this);
+    };
+    this._boundClick = evt => {
+      default_onCellClick_method(evt, this);
+    };
+    this._boundMouseDown = evt => {
+      default_onCellMouseDown_method(evt, this);
+    };
+    this._boundMouseUp = evt => {
+      default_onCellMouseUp_method(evt, this);
+    };
+    this._boundDoubleClick = evt => {
+      default_onCellDoubleClick_method(evt, this);
+    };
+    this._boundContextMenu = evt => {
+      evt.preventDefault();
+      default_onCellContextMenu_method(evt, this);
+    };
+
+    cellElm.addEventListener('mousemove', this._boundPointerMove);
+    cellElm.addEventListener('click', this._boundClick);
+    cellElm.addEventListener('mousedown', this._boundMouseDown);
+    cellElm.addEventListener('mouseup', this._boundMouseUp);
+    cellElm.addEventListener('dblclick', this._boundDoubleClick);
+    cellElm.addEventListener('contextmenu', this._boundContextMenu);
+
+    // initial paint
+    paintCell(this);
+
+    // Observe <style> content so keyframes / rules updates repaint
+    this._styleElemObserver = new MutationObserver(() => {
+      if (this._pendingStyleRepaint) return;
+      this._pendingStyleRepaint = true;
+      requestAnimationFrame(() => {
+        this._pendingStyleRepaint = false;
+        paintCell(this);
+        this.classyConvicts.concat(this.namedConvicts).forEach(paintSpecificMuse);
+      });
+    });
+
+    this._observeStyleElements = root => {
+      if (!root) return;
+      const targets = [];
+      if (root.nodeName === 'STYLE') {
+        targets.push(root);
+      } else if (typeof root.querySelectorAll === 'function') {
+        targets.push(...root.querySelectorAll('style'));
+      }
+      targets.forEach(styleEl => {
+        if (this._observedStyleElements.has(styleEl)) return;
+        this._observedStyleElements.add(styleEl);
+        this._styleElemObserver.observe(styleEl, {
+          childList: true,
+          characterData: true,
+          subtree: true
+        });
+      });
+    };
+
+    this._styleHostObserver = new MutationObserver(mutationList => {
+      mutationList.forEach(mutation => {
+        mutation.addedNodes.forEach(node => {
+          if (node.nodeType === Node.ELEMENT_NODE && node.nodeName === 'STYLE') {
+            this._observeStyleElements(node);
+          }
+        });
+      });
+    });
+
+    this._observeStyleElements(this.cellElm);
+    if (document.head) {
+      this._observeStyleElements(document.head);
+      this._styleHostObserver.observe(document.head, {
+        childList: true,
+        subtree: true
+      });
+    }
+
+    // Observe inline style/id/class changes and child mutations
+    this._styleObserver = new MutationObserver(mutationList => {
+      mutationList.forEach(mutation => {
+        if (mutation.target.nodeName === 'CANVAS') return;
+
+        switch (mutation.type) {
+          case 'childList': {
+            for (let i = 0; i < mutation.addedNodes.length; i++) {
+              const node = mutation.addedNodes[i];
+              if (node.nodeType === Node.ELEMENT_NODE && node.nodeName !== 'CANVAS') {
+                if (node.nodeName === 'STYLE') {
+                  this._observeStyleElements(node);
+                  paintCell(this);
+                } else {
+                  this.ScanElement(node);
+                  const convict = this.getConvictByDom(node);
+                  if (convict) {
+                    paintSpecificMuse(convict);
+                  }
+                }
+              }
+            }
+            for (let i = 0; i < mutation.removedNodes.length; i++) {
+              const node = mutation.removedNodes[i];
+              if (node.nodeType === Node.ELEMENT_NODE && node.nodeName !== 'CANVAS') {
+                this.removeConvict(this._allConvictsByDom.get(node));
+              }
+            }
+            break;
+          }
+          case 'attributes': {
+            const target = mutation.target;
+            const convict = target.convict;
+            if (!convict) break;
+
+            if (mutation.attributeName === 'id') {
+              convict.userData.domId = target.id;
+            } else if (mutation.attributeName === 'class') {
+              const nextClasses = Array.from(target.classList).filter(Boolean);
+              convict.userData.classList = nextClasses;
+              convict.name = nextClasses[0] || '';
+            } else if (mutation.attributeName === 'style') {
+              // inline style changed; repaint this convict
+              paintConvict(target, this);
+            }
+            break;
+          }
+        }
+      });
+    });
+
+    this._styleObserver.observe(this.cellElm, {
+      attributes: true,
+      childList: true,
+      attributeFilter: ['style', 'id', 'class'],
+      subtree: true
+    });
+
+    // Animation loop
+    this._running = true;
+    this._anim = _MainAnimMethod
+      ? _MainAnimMethod.bind(this)
+      : () => {
+          if (!this._running) return;
+          this.updateFunds.forEach(update => update());
+          requestAnimationFrame(this._anim);
+          if (this.focusedCamera) {
+            this.threeRenderer.render(this.loadedScene, this.focusedCamera);
+          }
+        };
+
+    // Resize handling
+    this._resizeObserver = new ResizeObserver(entries => {
+      for (const e of entries) {
+        const { width, height } = e.contentRect;
+        const dpr = window.devicePixelRatio || 1;
+        this.threeRenderer.setPixelRatio(dpr);
+
+        const safeWidth = Math.max(width, 1);
+        const safeHeight = Math.max(height, 1);
+        this.threeRenderer.setSize(safeWidth, safeHeight, false);
+
+        if (this.focusedCamera && this.focusedCamera.isPerspectiveCamera) {
+          this.focusedCamera.aspect = safeWidth / safeHeight;
+        }
+        if (this.focusedCamera) {
+          this.focusedCamera.updateProjectionMatrix();
+        }
+      }
+    });
+    this._resizeObserver.observe(this.cellElm);
+
+    this._anim();
+  }
+
+  /**
+   * Initial scan of cell children.
+   * @private
+   */
+  _ScanCell() {
+    for (let i = 0; i < this.cellElm.children.length; i++) {
+      const convictElm = this.cellElm.children[i];
+      this.ScanElement(convictElm);
+    }
+  }
+
+  /**
+   * Convert a DOM element into a Three.js object and wire it up.
+   *
+   * @param {HTMLElement} elm
+   */
+  ScanElement(elm) {
+    if (this._allConvictsByDom.has(elm)) return;
+
+    const parentObj = this.getConvictByDom(elm.parentElement) || this.loadedScene;
+    const instance = this.ConvertDomToObject(elm);
+
+    if (instance === null) {
+      // still recurse children
+      for (let i = 0; i < elm.children.length; i++) {
+        this.ScanElement(elm.children[i]);
+      }
+      return;
+    }
+
+    // Camera tags: configure projection
+    if (elm.tagName.includes('CAMERA')) {
+      const rect = this.cellElm.getBoundingClientRect();
+      const aspect = rect.height ? rect.width / rect.height : 1;
+
+      if (elm.tagName === 'PERSPECTIVECAMERA') {
+        instance.fov = 75;
+        instance.aspect = aspect;
+        instance.far = 1000;
+        instance.near = 0.1;
+      } else {
+        const frustumSize = 20;
+        instance.frustumSize = frustumSize;
+        instance.aspect = aspect;
+        instance.left = (-frustumSize * aspect) / 2;
+        instance.right = (frustumSize * aspect) / 2;
+        instance.top = frustumSize / 2;
+        instance.bottom = -frustumSize / 2;
+        instance.refreshLook = fSize => {
+          instance.frustumSize = fSize;
+          instance.left = (-fSize * instance.aspect) / 2;
+          instance.right = (fSize * instance.aspect) / 2;
+          instance.top = fSize / 2;
+          instance.bottom = -fSize / 2;
+          instance.updateProjectionMatrix();
+        };
+      }
+
+      const rectW = rect.width || 1;
+      const rectH = rect.height || 1;
+
+      if (elm.hasAttribute('render')) {
+        this.focusedCamera = instance;
+        this.focusedCamera.updateProjectionMatrix();
+        this.threeRenderer.setPixelRatio(window.devicePixelRatio || 1);
+        this.threeRenderer.setSize(rectW, rectH, false);
+      } else if (!this.focusedCamera) {
+        this.focusedCamera = instance;
+        this.focusedCamera.updateProjectionMatrix();
+      }
+    }
+
+    instance.userData.domEl = elm;
+    instance.userData.extraParams = [];
+    instance.userData.classList = [];
+    instance.transition = null;
+
+    parentObj.add(instance);
+
+    if (elm.id) {
+      instance.userData.domId = elm.id;
+      this.namedConvicts.push(instance);
+      if (!this.constantConvicts.includes(instance) && getCSSRule(`#${elm.id}:active`)) {
+        this.constantConvicts.push(instance);
+      }
+    }
+
+    const classList = Array.from(elm.classList || []).filter(Boolean);
+    if (classList.length) {
+      instance.userData.classList = classList;
+      instance.name = classList[0];
+      this.classyConvicts.push(instance);
+      const hasActiveRule = classList.some(cls => getCSSRule(`.${cls}:active`));
+      if (hasActiveRule && !this.constantConvicts.includes(instance)) {
+        this.constantConvicts.push(instance);
+      }
+    }
+
+    this._allConvictsByDom.set(elm, instance);
+
+    for (let i = 0; i < elm.children.length; i++) {
+      this.ScanElement(elm.children[i]);
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(elm, 'convict')) {
+      Object.defineProperty(elm, 'convict', {
+        value: this.getConvictByDom(elm),
+        enumerable: false
+      });
+    }
+  }
+
+  /**
+   * Tag → THREE.Object3D constructor.
+   *
+   * @param {HTMLElement} elm
+   * @returns {THREE.Object3D|null}
+   */
+  ConvertDomToObject(elm) {
+    if (elm.tagName === 'CANVAS') return null;
+
+    const key = elm.tagName.replace(/-/g, '');
+    const Ctor = getClassMap()[key];
+    if (!Ctor) {
+      console.warn(`Unknown THREE class for <${elm.tagName.toLowerCase()}>`);
+      return null;
+    }
+    return new Ctor();
+  }
+
+  /**
+   * Remove a convict and its children.
+   *
+   * @param {THREE.Object3D|null} convict
+   */
+  removeConvict(convict) {
+    if (!convict) return;
+
+    convict.children.slice().forEach(child => {
+      const domNode = child.userData?.domEl;
+      if (domNode) {
+        this.removeConvict(this._allConvictsByDom.get(domNode));
+      } else {
+        this.removeConvict(child);
+      }
+    });
+
+    fastRemove_arry(this.classyConvicts, convict);
+    fastRemove_arry(this.namedConvicts, convict);
+    fastRemove_arry(this.constantConvicts, convict);
+
+    if (convict.userData.domEl) {
+      this._allConvictsByDom.delete(convict.userData.domEl);
+      convict.userData.domEl.remove();
+    }
+
+    if (convict.parent) {
+      convict.parent.remove(convict);
+    }
+  }
+
+  /**
+   * Get convict by DOM element.
+   *
+   * @param {HTMLElement} element
+   */
+  getConvictByDom(element) {
+    return this._allConvictsByDom.get(element);
+  }
+
+  /**
+   * Get convict by DOM id (global document lookup).
+   *
+   * @param {string} id
+   */
+  getConvictById(id) {
+    const el = document.getElementById(id);
+    return el ? this._allConvictsByDom.get(el) : undefined;
+  }
+
+  /**
+   * Get all convicts with a given class.
+   *
+   * @param {string} className
+   * @returns {Array<THREE.Object3D>}
+   */
+  getConvictsByClass(className) {
+    const elements = Array.from(document.getElementsByClassName(className));
+    const out = [];
+    elements.forEach(elm => {
+      const convict = this.getConvictByDom(elm);
+      if (convict) out.push(convict);
+    });
+    return out;
+  }
+
+  /**
+   * Register a per-frame callback.
+   *
+   * @param {Function} fn
+   */
+  addUpdateFunction(fn) {
+    if (typeof fn === 'function') {
+      const bound = fn.bind(this);
+      bound.originalFn = fn;
+      this.updateFunds.push(bound);
+    }
+  }
+
+  /**
+   * Remove a previously registered per-frame callback.
+   *
+   * @param {Function} fn
+   */
+  removeUpdateFunction(fn) {
+    const idx = this.updateFunds.findIndex(item => item?.originalFn === fn);
+    if (idx >= 0) {
+      this.updateFunds.splice(idx, 1);
+    }
+  }
+
+  /**
+   * Tear down observers, handlers and canvas.
+   */
+  dispose() {
+    this._running = false;
+
+    this._resizeObserver.disconnect();
+    this._styleObserver.disconnect();
+    this._styleElemObserver.disconnect();
+    this._styleHostObserver.disconnect();
+
+    this.cellElm.removeEventListener('mousemove', this._boundPointerMove);
+    this.cellElm.removeEventListener('click', this._boundClick);
+    this.cellElm.removeEventListener('mousedown', this._boundMouseDown);
+    this.cellElm.removeEventListener('mouseup', this._boundMouseUp);
+    this.cellElm.removeEventListener('dblclick', this._boundDoubleClick);
+    this.cellElm.removeEventListener('contextmenu', this._boundContextMenu);
+
+    const canvas = this.threeRenderer.domElement;
+    if (canvas && canvas.parentNode) {
+      canvas.parentNode.removeChild(canvas);
+    }
+  }
+}
+
+export default Cell;

package/dist/index.js

@@ -0,0 +1,12 @@
+// index.js
+//
+// Entry point for the JailedThreeJS module.
+// Re-exports all public API in one place.
+
+export { default as Cell } from './cell.js';
+export { default as JThree } from './main.js';
+
+export * from './artist.js';
+export * from './NoScope.js';
+export * from './Train.js';
+export * from './utils.js';

package/dist/main.js

@@ -0,0 +1,136 @@
+// main.js
+//
+// JThree facade: finds <cell> elements, bootstraps renderer/scene/cell
+// for each, and keeps a WeakMap of created Cell instances.
+
+import * as THREE from 'three';
+import Cell from './cell.js';
+
+class JTHREE {
+  static __Loaded_Cells__ = new WeakMap();
+  static __StyleTag__ = null;
+
+  /**
+   * Convert all <cell> elements in the document.
+   */
+  static init_convert() {
+    if (!JTHREE.__StyleTag__ && document.head) {
+      const styleSheet = document.createElement('style');
+      styleSheet.textContent = `
+        cell > :not(canvas) {
+          display: none;
+        }
+      `;
+      document.head.appendChild(styleSheet);
+      JTHREE.__StyleTag__ = styleSheet;
+    }
+
+    document.querySelectorAll('cell').forEach(el => {
+      if (JTHREE.__Loaded_Cells__.has(el)) return;
+      JTHREE.create_THREEJSRENDERER(el);
+    });
+  }
+
+  /**
+   * Legacy alias.
+   */
+  static _convert_init_() {
+    return JTHREE.init_convert();
+  }
+
+  /**
+   * Create renderer + scene for a given <cell> element.
+   *
+   * @param {HTMLElement} cellEl
+   * @returns {Cell}
+   */
+  static create_THREEJSRENDERER(cellEl) {
+    if (JTHREE.__Loaded_Cells__.has(cellEl)) {
+      return JTHREE.__Loaded_Cells__.get(cellEl);
+    }
+
+    const { canvas, width, height, dpr } = createWebGLOverlay(cellEl);
+    const safeWidth = width || 1;
+    const safeHeight = height || 1;
+
+    const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+    renderer.setPixelRatio(dpr);
+    renderer.setSize(safeWidth, safeHeight, false);
+    renderer.setClearColor(0x000000, 1);
+
+    const scene = new THREE.Scene();
+
+    // Find explicit cameras
+    const regex = /camera/i;
+    const foundCameraElms = Array.from(cellEl.children).filter(child =>
+      regex.test(child.tagName) ||
+      regex.test(child.id) ||
+      regex.test(child.className)
+    );
+
+    let camera = null;
+    if (foundCameraElms.length === 0) {
+      camera = new THREE.PerspectiveCamera(75, safeWidth / safeHeight, 0.1, 1000);
+      console.warn('No camera found for', cellEl, '. Creating a default camera.');
+    }
+
+    const cell = new Cell(cellEl, renderer, scene, camera || null);
+    JTHREE.__Loaded_Cells__.set(cellEl, cell);
+
+    cellEl.dispatchEvent(
+      new CustomEvent('OnStart', { detail: { cell, CellEl: cellEl } })
+    );
+
+    return cell;
+  }
+}
+
+/**
+ * Create a WebGL canvas overlay on a host element.
+ *
+ * @param {HTMLElement} hostEl
+ * @param {Object} [glOptions={}]
+ * @returns {{canvas:HTMLCanvasElement, gl:WebGLRenderingContext, width:number, height:number, dpr:number}}
+ */
+function createWebGLOverlay(hostEl, glOptions = {}) {
+  const { width, height } = hostEl.getBoundingClientRect();
+  const dpr = window.devicePixelRatio || 1;
+
+  if (getComputedStyle(hostEl).position === 'static') {
+    hostEl.style.position = 'relative';
+  }
+
+  const canvas = document.createElement('canvas');
+  canvas.width = Math.max(1, Math.round(width * dpr));
+  canvas.height = Math.max(1, Math.round(height * dpr));
+  Object.assign(canvas.style, {
+    position: 'absolute',
+    top: '0',
+    left: '0',
+    width: `${width}px`,
+    height: `${height}px`,
+    pointerEvents: 'none',
+    //zIndex: '-999'
+  });
+
+  hostEl.appendChild(canvas);
+
+  const gl =
+    canvas.getContext('webgl2', glOptions) ||
+    canvas.getContext('webgl', glOptions) ||
+    canvas.getContext('experimental-webgl', glOptions);
+
+  if (!gl) {
+    throw new Error('Your browser doesn’t support WebGL.');
+  }
+
+  gl.viewport(0, 0, canvas.width, canvas.height);
+  return { canvas, gl, width, height, dpr };
+}
+
+// Auto-initialise on import.
+JTHREE.init_convert();
+window.JThree = JTHREE;
+
+export { JTHREE };
+export default JTHREE;