meccha-chameleon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esteve Segura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EsteveSegura/MecchaChameleon.js/main/docs/demo.gif" width="720" alt="MecchaChameleon.js demo">
+</p>
+
+# MecchaChameleon.js
+
+A tiny WebGL overlay that lights a 2D figure from a **normal map** (relief +
+specular highlights) and floats it above your page. It's **non-interactive**
+(`pointer-events: none`) — purely visual. Optionally it can paint the real page
+behind the figure with a live **brush** effect and overlay a **shadow** texture.
+
+Zero dependencies. Ships as native **ESM** (`import`) and **CommonJS/UMD**
+(`require` and `<script>`), and is **tree-shakeable** (`"sideEffects": false`,
+no top-level side effects). The core ships no images (bring your own); optional
+presets with embedded images are available on demand.
+
+## Install
+
+```bash
+npm install meccha-chameleon
+```
+
+```js
+import MecchaChameleon from 'meccha-chameleon';
+
+MecchaChameleon.mount({
+  image: 'figure.png',           // base color PNG (with alpha)
+  normalMap: 'figure-normal.png',// normal map aligned to the figure
+  target: '#hero', width: 200    // anchor the figure over #hero
+});
+```
+
+Named imports also work:
+
+```js
+import { mount, update, unmount } from 'meccha-chameleon';
+```
+
+### Batteries-included presets (optional)
+
+Don't have a figure yet? Import a ready-made preset — the images come embedded
+as data URIs, so there's nothing to copy into `public/`, no bundler asset
+config, and no `file://` / CORS texture issues:
+
+```js
+import MecchaChameleon from 'meccha-chameleon';
+import mecha1 from 'meccha-chameleon/presets/mecha1';
+
+MecchaChameleon.mount({ ...mecha1, target: '#hero' });
+```
+
+Presets are **separate modules**: importing the core library never pulls them
+in, so they stay tree-shakeable. A bundler only ships a preset's images if you
+actually import that subpath (verified: a core-only build is ~20 KB; adding the
+preset adds ~2.5 MB — nothing in between).
+
+Or with a plain script tag (global `MecchaChameleon`):
+
+```html
+<script src="https://unpkg.com/meccha-chameleon"></script>
+<script>
+  MecchaChameleon.mount({ image: 'figure.png', normalMap: 'figure-normal.png' });
+</script>
+```
+
+> **WebGL note:** browsers will not load textures from `file://`. Serve your
+> page over HTTP (`npx http-server`, Vite, etc.).
+
+## API
+
+- `MecchaChameleon.mount(config)` — create the overlay.
+- `MecchaChameleon.update(partialConfig)` — change parameters **live** (light,
+  opacity, shadow, target…). Structural changes (`brush` and brush params) need
+  a fresh `mount()`.
+- `MecchaChameleon.unmount()` — remove it and detach all listeners.
+
+## Config
+
+Two assets are **required**: `image` (base color) and `normalMap`.
+
+| Key | Default | What it does |
+|-----|---------|--------------|
+| `image` | — | Base color PNG (with alpha). **Required.** |
+| `normalMap` | — | Normal map, same framing as the figure. **Required.** |
+| `target` | `null` | CSS selector (`#id`/`.class`) the figure is centered over. It tracks the element on scroll/resize. `null` or a missing element falls back to the viewport center. |
+| `width` | `200` | Width in px (height keeps the image aspect). |
+| `animateLight` | `false` | Light orbits on its own. |
+| `lightIntensity` | `0.45` | Light intensity. |
+| `ambient` | `0.22` | Fill light (0 = black shadows). |
+| `specularStrength` | `0.75` | Specular strength. |
+| `specularHardness` | `22` | Specular hardness (higher = smaller highlight). |
+| `relief` | `1` | Exaggerates the normal map. |
+| `lightZ` | `1.4` | Light height (lower = grazing = more relief). |
+| `lightRadius` | `0.35` | Orbit radius. |
+| `lightSpeed` | `0.35` | Orbit speed (turns/sec). |
+| `lightAngle` | `-0.7` | Fixed light angle (rad) when `animateLight:false`. |
+| `lightColor` | `'#ffffff'` | Light color. |
+| `tint` | `null` | Hex color multiplied over the base. |
+| `opacity` | `0.2` | Figure opacity. |
+| `blendMode` | `'normal'` | Figure `mix-blend-mode`. |
+| `brush` | `true` | Paint the real background inside the silhouette. |
+| `brushStrength` | `24` | Smear strength (px). |
+| `brushPosterize` | `17` | Color levels per channel (paint patches). 0 = off. |
+| `brushGrain` | `0.1` | Canvas/bristle grain (0–1). |
+| `brushUsesNormalMap` | `false` | `true` = rigid glass-like refraction following the shape. |
+| `shadow` | `null` | Shadow texture PNG (aligned to the figure). |
+| `shadowOpacity` | `0.3` | Shadow opacity. |
+| `shadowBlendMode` | `'normal'` | Shadow `mix-blend-mode`. |
+
+## Package layout
+
+- `src/meccha-chameleon.mjs` — native ESM (used by `import` / bundlers).
+- `src/meccha-chameleon.js` — CommonJS/UMD (used by `require` and CDN `<script>`).
+- `src/presets/*` — optional ready-made figures with embedded images, imported
+  on demand via `meccha-chameleon/presets/<name>`.
+
+Only `src/` (plus README and LICENSE) is published; the playground itself is not
+part of the package.
+
+## Playground / config generator
+
+`playground/index.html` is a visual editor: tune the sliders and it prints the
+exact `MecchaChameleon.mount({...})` config for the current look, with a **Copy**
+button. Serve it over HTTP:
+
+```bash
+npm run playground
+# or: npx http-server -c-1 -o playground/
+```
+
+The playground uses demo images under `playground/assets/` (tracked in the repo,
+but excluded from the npm package). Drop your own `image`, `normalMap` and
+(optional) `shadow` PNGs there to try your own figure.
+
+## Browser support
+
+`brush` uses `backdrop-filter` + SVG filters — solid in Chromium/Safari; the
+`url()` reference in `backdrop-filter` is weak in Firefox (the lit figure still
+works, the painted background may not).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "meccha-chameleon",
+  "version": "0.1.0",
+  "description": "WebGL overlay that lights a 2D figure from a normal map (relief + specular), with an optional live brush-painted background and shadow layer. Floats above the page and is non-interactive.",
+  "homepage": "https://github.com/EsteveSegura/MecchaChameleon.js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EsteveSegura/MecchaChameleon.js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/EsteveSegura/MecchaChameleon.js/issues"
+  },
+  "author": "Esteve Segura",
+  "type": "commonjs",
+  "main": "src/meccha-chameleon.js",
+  "module": "src/meccha-chameleon.mjs",
+  "unpkg": "src/meccha-chameleon.js",
+  "jsdelivr": "src/meccha-chameleon.js",
+  "exports": {
+    ".": {
+      "import": "./src/meccha-chameleon.mjs",
+      "require": "./src/meccha-chameleon.js",
+      "default": "./src/meccha-chameleon.js"
+    },
+    "./presets/*": {
+      "import": "./src/presets/*.mjs",
+      "require": "./src/presets/*.js",
+      "default": "./src/presets/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "webgl",
+    "normal-map",
+    "overlay",
+    "shader",
+    "lighting",
+    "specular",
+    "canvas",
+    "brush",
+    "painterly"
+  ],
+  "scripts": {
+    "playground": "http-server -c-1 -p 8080 -o playground/"
+  },
+  "license": "MIT"
+}

package/src/meccha-chameleon.js

@@ -0,0 +1,459 @@
+/**
+ * MecchaChameleon  —  WebGL engine
+ * Drops YOUR figure onto the page as a visual overlay and LIGHTS it in 3D from
+ * a normal map: relief, diffuse shading and specular highlights with a light
+ * that moves on its own. It can optionally paint the real page behind it with a
+ * live "brush" effect and overlay a shadow texture. Non-interactive (visual only).
+ *
+ * Install:
+ *   npm install meccha-chameleon
+ *
+ * As a module (bundler / ESM):
+ *   import MecchaChameleon from 'meccha-chameleon';
+ *   MecchaChameleon.mount({ image:'mecha_chameleon_pose1_albedo.png', normalMap:'mecha_chameleon_pose1_normal.png', target:'#hero', width:200 });
+ *
+ * As a <script> tag (global MecchaChameleon):
+ *   <script src="meccha-chameleon.js"></script>
+ *   <script>MecchaChameleon.mount({ image:'mecha_chameleon_pose1_albedo.png', normalMap:'mecha_chameleon_pose1_normal.png' });</script>
+ *
+ * NOTE: WebGL cannot load textures from file://. Serve the page over HTTP.
+ */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();      // CommonJS
+  else if (typeof define === 'function' && define.amd) define([], factory);          // AMD
+  else root.MecchaChameleon = factory();                                                    // <script> global
+})(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  var DEFAULTS = {
+    image: null,           // (REQUIRED) base color PNG (with alpha)
+    normalMap: null,       // (REQUIRED) normal map aligned to the figure
+
+    target: null,          // CSS selector (#id / .class) the figure is anchored to
+                           //   (centered over that element). Falls back to the
+                           //   viewport center when null or the element is missing.
+    width: 200,            // width in px (height keeps the image aspect ratio)
+
+    // --- Light ---
+    animateLight: false,    // the light orbits on its own
+    lightSpeed: 0.35,      // turns per second
+    lightRadius: 0.35,      // orbit radius (0..~1.5)
+    lightAngle: -0.7,      // fixed angle (rad) when animateLight = false
+    lightZ: 1.4,          // light height/closeness (lower = grazing = more relief)
+    lightColor: '#ffffff',
+    lightIntensity: 0.45,
+
+    ambient: 0.22,         // fill light (0 = black shadows)
+    specularStrength: 0.75,// highlight strength
+    specularHardness: 22,  // highlight size (higher = smaller spot)
+
+    relief: 1,           // exaggerates the normal map (1 = as-is)
+    tint: null,            // hex color multiplied over the base color (e.g. '#8fd0ff')
+
+    // --- Brush-painted background (CSS layer beneath the figure) ---
+    brush: true,          // paints the real background inside the silhouette
+    brushUsesNormalMap: false, // true = rigid refraction following the shape (glass);
+                           //         false = noise smear (brush strokes, more "painted")
+    brushStrength: 24,     // smear/displacement in px (the stroke drags the background)
+    brushFrequency: 0.03,  // stroke size: lower = thicker stroke
+    brushOctaves: 2,
+    brushBlur: 1.0,        // blur in px -> wet-paint look
+    brushPosterize: 17,     // tones per channel (flattens color into patches). 0 = off
+    brushGrain: 0.1,      // canvas/bristle texture (0 = smooth, 1 = strong)
+    brushSaturation: 1.25,
+    brushContrast: 1.08,
+
+    // --- Figure layer ---
+    opacity: 0.2,            // lower (e.g. 0.5) to see the painted background through the figure
+    blendMode: 'normal',   // canvas mix-blend-mode ('multiply', 'screen'...)
+
+    // --- Shadow layer (PNG texture on top of everything) ---
+    shadow: null,          // shadow PNG URL (transparent, aligned to the figure)
+    shadowOpacity: 0.3,    // individual shadow opacity
+    shadowBlendMode: 'normal', // shadow mix-blend-mode
+
+    zIndex: 2147483000,
+    id: 'meccha-chameleon-overlay'
+  };
+
+  var VERT =
+    'attribute vec2 aPos;varying vec2 vUv;' +
+    'void main(){vUv=vec2(aPos.x*0.5+0.5,1.0-(aPos.y*0.5+0.5));' +
+    'gl_Position=vec4(aPos,0.0,1.0);}';
+
+  var FRAG =
+    'precision mediump float;varying vec2 vUv;' +
+    'uniform sampler2D uAlbedo;uniform sampler2D uNormal;' +
+    'uniform vec3 uLightPos;uniform vec3 uLightColor;' +
+    'uniform float uIntensity;uniform float uAmbient;' +
+    'uniform float uSpecStrength;uniform float uShininess;' +
+    'uniform float uRelief;uniform vec3 uTint;uniform float uUseTint;' +
+    'void main(){' +
+    ' vec4 albedo=texture2D(uAlbedo,vUv);' +
+    ' if(albedo.a<0.01) discard;' +
+    ' vec3 nTex=texture2D(uNormal,vUv).rgb*2.0-1.0;' +
+    ' nTex.y=-nTex.y;' +               // flip G to screen space (y goes down)
+    ' nTex.xy*=uRelief;' +
+    ' vec3 N=normalize(nTex);' +
+    ' vec3 fragPos=vec3(vUv*2.0-1.0,0.0);' +
+    ' vec3 L=normalize(uLightPos-fragPos);' +
+    ' vec3 V=vec3(0.0,0.0,1.0);' +
+    ' vec3 H=normalize(L+V);' +
+    ' float diff=max(dot(N,L),0.0);' +
+    ' float spec=pow(max(dot(N,H),0.0),uShininess)*uSpecStrength;' +
+    ' vec3 base=albedo.rgb;' +
+    ' if(uUseTint>0.5) base*=uTint;' +
+    ' vec3 color=base*(uAmbient+diff*uLightColor*uIntensity)+spec*uLightColor;' +
+    ' gl_FragColor=vec4(color,albedo.a);' +
+    '}';
+
+  function hexRgb(h) {
+    h = String(h).replace('#', '');
+    if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+    var n = parseInt(h, 16);
+    return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];
+  }
+
+  // Injects the SVG <filter> that PAINTS the real background (brush effect):
+  // noise smear -> blur -> posterize (color patches) -> canvas grain.
+  function createBrushFilter(cfg, uid) {
+    var NS = 'http://www.w3.org/2000/svg';
+    var svg = document.createElementNS(NS, 'svg');
+    Object.assign(svg.style, { position: 'absolute', width: '0', height: '0', overflow: 'hidden' });
+    var f = document.createElementNS(NS, 'filter');
+    var fid = 'meccha-chameleon-brush-' + uid;
+    f.setAttribute('id', fid);
+    f.setAttribute('x', '-20%'); f.setAttribute('y', '-20%');
+    f.setAttribute('width', '140%'); f.setAttribute('height', '140%');
+    f.setAttribute('color-interpolation-filters', 'sRGB');
+
+    function el(tag, attrs) {
+      var e = document.createElementNS(NS, tag);
+      for (var k in attrs) e.setAttribute(k, attrs[k]);
+      f.appendChild(e);
+      return e;
+    }
+    function transfer(inName, out, slope, intercept, discreteTable) {
+      var ct = el('feComponentTransfer', { in: inName, result: out });
+      ['feFuncR', 'feFuncG', 'feFuncB'].forEach(function (fn) {
+        var fe = document.createElementNS(NS, fn);
+        if (discreteTable) { fe.setAttribute('type', 'discrete'); fe.setAttribute('tableValues', discreteTable); }
+        else { fe.setAttribute('type', 'linear'); fe.setAttribute('slope', slope); fe.setAttribute('intercept', intercept); }
+        ct.appendChild(fe);
+      });
+      return ct;
+    }
+
+    // 1) Smear map: coarse noise (brush strokes) or normal map (rigid refraction).
+    if (cfg.brushUsesNormalMap && cfg.normalMap) {
+      var im = el('feImage', { x: '0', y: '0', width: '100%', height: '100%',
+        preserveAspectRatio: 'none', result: 'map' });
+      im.setAttributeNS('http://www.w3.org/1999/xlink', 'xlink:href', cfg.normalMap);
+      im.setAttribute('href', cfg.normalMap);
+    } else {
+      el('feTurbulence', { type: 'fractalNoise',
+        baseFrequency: cfg.brushFrequency + ' ' + cfg.brushFrequency,
+        numOctaves: cfg.brushOctaves, seed: '7', stitchTiles: 'stitch', result: 'map' });
+    }
+
+    // 2) Displace the background (drags the texture like a brush stroke).
+    el('feDisplacementMap', { in: 'SourceGraphic', in2: 'map',
+      scale: cfg.brushStrength, xChannelSelector: 'R', yChannelSelector: 'G', result: 'smear' });
+
+    // 3) Blur to fuse into wet-paint strokes.
+    el('feGaussianBlur', { in: 'smear', stdDeviation: cfg.brushBlur, result: 'soft' });
+
+    var current = 'soft';
+
+    // 4) Posterize: flattens color into flat patches (the essence of "painted").
+    if (cfg.brushPosterize && cfg.brushPosterize > 1) {
+      var n = Math.round(cfg.brushPosterize), tv = [];
+      for (var i = 0; i < n; i++) tv.push((i / (n - 1)).toFixed(4));
+      transfer('soft', 'post', null, null, tv.join(' '));
+      current = 'post';
+    }
+
+    // 5) Canvas/bristle grain: fine gray noise multiplied on top.
+    if (cfg.brushGrain && cfg.brushGrain > 0) {
+      el('feTurbulence', { type: 'fractalNoise', baseFrequency: '0.7 0.7',
+        numOctaves: '2', seed: '11', result: 'gn0' });
+      // Noise -> opaque gray (RGB = luminance, alpha = 1), then compress its range.
+      el('feColorMatrix', { in: 'gn0', type: 'matrix', result: 'gg',
+        values: '0.33 0.33 0.33 0 0  0.33 0.33 0.33 0 0  0.33 0.33 0.33 0 0  0 0 0 0 1' });
+      var g = cfg.brushGrain;
+      transfer('gg', 'grain', String(g), String(1 - g)); // map [0,1] -> [1-g, 1] (mostly bright)
+      el('feBlend', { mode: 'multiply', in: current, in2: 'grain', result: 'painted' });
+      current = 'painted';
+    }
+
+    // Final output (ensures the active result is the last primitive).
+    el('feOffset', { in: current, dx: '0', dy: '0' });
+
+    svg.appendChild(f);
+    document.body.appendChild(svg);
+    return { svg: svg, fid: fid };
+  }
+
+  function compileShader(gl, type, src) {
+    var s = gl.createShader(type);
+    gl.shaderSource(s, src);
+    gl.compileShader(s);
+    if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
+      console.error('[meccha-chameleon] shader:', gl.getShaderInfoLog(s));
+    }
+    return s;
+  }
+
+  function loadTexture(gl, url, cb) {
+    var tex = gl.createTexture();
+    var img = new Image();
+    img.onload = function () {
+      gl.bindTexture(gl.TEXTURE_2D, tex);
+      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+      cb(tex, img.naturalWidth, img.naturalHeight);
+    };
+    img.onerror = function () { console.error('[meccha-chameleon] failed to load', url); };
+    img.src = url;
+    return tex;
+  }
+
+  var COUNTER = 0;
+
+  var MecchaChameleon = {
+    _state: null,
+    _raf: null,
+    _canvas: null,
+    _root: null,
+    _svg: null,
+    _shadow: null,
+    _ro: null,
+    _onReposition: null,
+
+    mount: function (options) {
+      this.unmount();
+      var cfg = Object.assign({}, DEFAULTS, options || {});
+      if (!cfg.image || !cfg.normalMap) {
+        console.error('[meccha-chameleon] Missing "image" and/or "normalMap".');
+        return this;
+      }
+      this._state = cfg;
+      var self = this;
+      var start = function () { self._init(cfg); };
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', start, { once: true });
+      } else { start(); }
+      return this;
+    },
+
+    _init: function (cfg) {
+      var dpr = (typeof window !== 'undefined' && window.devicePixelRatio) || 1;
+      var uid = ++COUNTER;
+      var self = this;
+
+      // Container above everything (non-interactive). Its left/top/position are
+      // set by _place(), which anchors it to cfg.target (or the viewport center).
+      var root = document.createElement('div');
+      root.id = cfg.id;
+      Object.assign(root.style, {
+        width: cfg.width + 'px',
+        transform: 'translate(-50%,-50%)',
+        zIndex: String(cfg.zIndex),
+        pointerEvents: 'none'
+      });
+      document.body.appendChild(root);
+      this._root = root;
+
+      // Anchor to the target selector now and keep it in sync as the page
+      // scrolls / reflows / resizes.
+      this._place();
+      this._onReposition = function () { self._place(); };
+      window.addEventListener('resize', this._onReposition);
+      window.addEventListener('scroll', this._onReposition, { passive: true, capture: true });
+      if (typeof ResizeObserver !== 'undefined') {
+        this._ro = new ResizeObserver(this._onReposition);
+        this._ro.observe(document.documentElement);
+        var tgt = cfg.target && document.querySelector(cfg.target);
+        if (tgt) this._ro.observe(tgt);
+      }
+
+      // Optional layer: the REAL background painted with the brush, clipped to the silhouette.
+      if (cfg.brush) {
+        var filter = createBrushFilter(cfg, uid);
+        this._svg = filter.svg;
+        var brushDiv = document.createElement('div');
+        var bf = 'url(#' + filter.fid + ') saturate(' + cfg.brushSaturation + ') contrast(' + cfg.brushContrast + ')';
+        var mask = 'url("' + cfg.image + '")';
+        Object.assign(brushDiv.style, {
+          position: 'absolute', inset: '0', pointerEvents: 'none',
+          WebkitBackdropFilter: bf, backdropFilter: bf,
+          WebkitMaskImage: mask, maskImage: mask,
+          WebkitMaskSize: '100% 100%', maskSize: '100% 100%',
+          WebkitMaskRepeat: 'no-repeat', maskRepeat: 'no-repeat'
+        });
+        root.appendChild(brushDiv);
+      }
+
+      // Lit figure layer (WebGL), above the brush.
+      var canvas = document.createElement('canvas');
+      Object.assign(canvas.style, {
+        position: 'relative', display: 'block',
+        width: '100%', height: 'auto',
+        pointerEvents: 'none',
+        opacity: String(cfg.opacity),
+        mixBlendMode: cfg.blendMode
+      });
+      root.appendChild(canvas);
+      this._canvas = canvas;
+
+      // Shadow layer (PNG) on top of everything, with its own opacity and blend mode.
+      if (cfg.shadow) {
+        var shadow = document.createElement('img');
+        shadow.src = cfg.shadow;
+        shadow.alt = '';
+        shadow.draggable = false;
+        Object.assign(shadow.style, {
+          position: 'absolute', left: '0', top: '0',
+          width: '100%', height: '100%',
+          pointerEvents: 'none', userSelect: 'none',
+          opacity: String(cfg.shadowOpacity),
+          mixBlendMode: cfg.shadowBlendMode
+        });
+        root.appendChild(shadow);
+        this._shadow = shadow;
+      }
+
+      var gl = canvas.getContext('webgl', { premultipliedAlpha: false, alpha: true })
+            || canvas.getContext('experimental-webgl');
+      if (!gl) { console.error('[meccha-chameleon] WebGL not available'); return; }
+
+      var prog = gl.createProgram();
+      gl.attachShader(prog, compileShader(gl, gl.VERTEX_SHADER, VERT));
+      gl.attachShader(prog, compileShader(gl, gl.FRAGMENT_SHADER, FRAG));
+      gl.linkProgram(prog);
+      gl.useProgram(prog);
+
+      var buf = gl.createBuffer();
+      gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+      gl.bufferData(gl.ARRAY_BUFFER,
+        new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]), gl.STATIC_DRAW);
+      var aPos = gl.getAttribLocation(prog, 'aPos');
+      gl.enableVertexAttribArray(aPos);
+      gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 0, 0);
+
+      gl.enable(gl.BLEND);
+      gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+
+      var U = {};
+      ['uLightPos', 'uLightColor', 'uIntensity', 'uAmbient', 'uSpecStrength',
+       'uShininess', 'uRelief', 'uTint', 'uUseTint', 'uAlbedo', 'uNormal']
+        .forEach(function (n) { U[n] = gl.getUniformLocation(prog, n); });
+
+      var ready = 0;
+      var texA = loadTexture(gl, cfg.image, function (t, w, h) {
+        // size the canvas to the image aspect ratio
+        var height = Math.round(cfg.width * (h / w));
+        canvas.style.height = height + 'px';
+        canvas.width = Math.round(cfg.width * dpr);
+        canvas.height = Math.round(height * dpr);
+        gl.viewport(0, 0, canvas.width, canvas.height);
+        if (++ready === 2) start();
+      });
+      var texN = loadTexture(gl, cfg.normalMap, function () {
+        if (++ready === 2) start();
+      });
+
+      function start() {
+        gl.activeTexture(gl.TEXTURE0); gl.bindTexture(gl.TEXTURE_2D, texA);
+        gl.uniform1i(U.uAlbedo, 0);
+        gl.activeTexture(gl.TEXTURE1); gl.bindTexture(gl.TEXTURE_2D, texN);
+        gl.uniform1i(U.uNormal, 1);
+        self._loop(gl, U);
+      }
+    },
+
+    // Positions the root: centered over cfg.target, or the viewport center as
+    // a fallback. Uses absolute (document) coords so it scrolls with the target,
+    // and fixed coords for the viewport-center fallback.
+    _place: function () {
+      var cfg = this._state, root = this._root;
+      if (!cfg || !root) return;
+      var el = cfg.target ? document.querySelector(cfg.target) : null;
+      if (el) {
+        var r = el.getBoundingClientRect();
+        var sx = window.pageXOffset || 0, sy = window.pageYOffset || 0;
+        root.style.position = 'absolute';
+        root.style.left = (r.left + sx + r.width / 2) + 'px';
+        root.style.top = (r.top + sy + r.height / 2) + 'px';
+      } else {
+        if (cfg.target) console.warn('[meccha-chameleon] target not found:', cfg.target);
+        root.style.position = 'fixed';
+        root.style.left = '50%';
+        root.style.top = '50%';
+      }
+    },
+
+    _loop: function (gl, U) {
+      var self = this;
+      function frame(ts) {
+        var cfg = self._state;
+        if (!cfg) return;
+        var t = (ts || 0) / 1000;
+        var ang = cfg.animateLight ? t * cfg.lightSpeed * Math.PI * 2 : cfg.lightAngle;
+        gl.uniform3f(U.uLightPos, Math.cos(ang) * cfg.lightRadius, Math.sin(ang) * cfg.lightRadius, cfg.lightZ);
+        var lc = hexRgb(cfg.lightColor);
+        gl.uniform3f(U.uLightColor, lc[0], lc[1], lc[2]);
+        gl.uniform1f(U.uIntensity, cfg.lightIntensity);
+        gl.uniform1f(U.uAmbient, cfg.ambient);
+        gl.uniform1f(U.uSpecStrength, cfg.specularStrength);
+        gl.uniform1f(U.uShininess, cfg.specularHardness);
+        gl.uniform1f(U.uRelief, cfg.relief);
+        if (cfg.tint) { var tn = hexRgb(cfg.tint); gl.uniform3f(U.uTint, tn[0], tn[1], tn[2]); gl.uniform1f(U.uUseTint, 1); }
+        else gl.uniform1f(U.uUseTint, 0);
+
+        gl.clearColor(0, 0, 0, 0);
+        gl.clear(gl.COLOR_BUFFER_BIT);
+        gl.drawArrays(gl.TRIANGLES, 0, 6);
+        self._raf = requestAnimationFrame(frame);
+      }
+      this._raf = requestAnimationFrame(frame);
+    },
+
+    // Change parameters LIVE: MecchaChameleon.update({ lightIntensity: 2 })
+    update: function (options) {
+      if (this._state && options) {
+        Object.assign(this._state, options);
+        if (this._canvas) {
+          if ('opacity' in options) this._canvas.style.opacity = String(options.opacity);
+          if ('blendMode' in options) this._canvas.style.mixBlendMode = options.blendMode;
+        }
+        if (this._shadow) {
+          if ('shadowOpacity' in options) this._shadow.style.opacity = String(options.shadowOpacity);
+          if ('shadowBlendMode' in options) this._shadow.style.mixBlendMode = options.shadowBlendMode;
+        }
+        // Re-anchor when the target selector changes.
+        if ('target' in options) this._place();
+      }
+      return this;
+    },
+
+    unmount: function () {
+      if (this._raf) cancelAnimationFrame(this._raf);
+      if (this._onReposition) {
+        window.removeEventListener('resize', this._onReposition);
+        window.removeEventListener('scroll', this._onReposition, { passive: true, capture: true });
+      }
+      if (this._ro) this._ro.disconnect();
+      if (this._root && this._root.parentNode) this._root.parentNode.removeChild(this._root);
+      if (this._svg && this._svg.parentNode) this._svg.parentNode.removeChild(this._svg);
+      this._raf = this._canvas = this._root = this._svg = this._shadow = this._state = null;
+      this._ro = this._onReposition = null;
+      return this;
+    }
+  };
+
+  return MecchaChameleon;
+});