Profile.js

/*************************************************************************
 *  @license
 *
 *
 *  Copyright © 2019, 2024 Glenn Wilton
 *  O2 Creative Limited
 *  www.o2creative.co.nz
 *  support@o2creative.co.nz
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 *
 */

'use strict';

const convert = require('./convert');
const colorEngineDef = require('./def');
const eIntent = colorEngineDef.eIntent;
const eProfileType = colorEngineDef.eProfileType;
const decode = require('./decodeICC');
const encode = require('./encodeICC');

// Stamped into every profile this engine generates rather than decodes. These
// files are committed and opened in inspectors, and nothing about ICC bytes
// distinguishes a test fixture from a profile somebody should assign to real
// artwork -- so the file says so itself.
const SYNTHETIC_COPYRIGHT = 'Synthetic test profile generated by jsColorEngine. '
    + 'Not a characterisation of any real device. Not for production colour management.';

/**
 * ============================================================================
 *  Profile.js — load, decode and synthesize ICC profiles
 * ============================================================================
 *
 *  The `Profile` class is the data layer of the engine. It does not perform
 *  any colour conversions itself — it produces a normalized, in-memory
 *  description of a colour profile that `Transform.js` then consumes to
 *  build pipelines.
 *
 *  Two fundamentally different ways to construct a profile:
 *
 *    1. ICC FILE  — decode the bytes of a real `.icc` / `.icm` file via
 *       `decodeICC.js`. Supports ICC v2 and v4, RGB / Gray / Lab / CMYK
 *       (and 2CLR / 3CLR / 4CLR / CMY ) device colour spaces, with PCS
 *       in either Lab or XYZ. All four standard rendering intents plus
 *       the AtoB/BtoA LUT pairs are extracted.
 *
 *    2. VIRTUAL  — synthesize a profile in memory from primaries + gamma.
 *       Supported names: sRGB, AdobeRGB, AppleRGB, ColorMatchRGB,
 *       ProPhotoRGB, Lab, LabD50, LabD65. No I/O, no decode, no file
 *       parsing — just maths. See `createVirtualProfile`.
 *
 *  ----------------------------------------------------------------------------
 *  IMPORTANT: ICC vs VIRTUAL — when does loading a real profile pay off?
 *  ----------------------------------------------------------------------------
 *
 *  Most RGB ICC profiles in the wild (sRGB.icc, AdobeRGB1998.icc,
 *  ProPhoto.icm, every monitor profile your OS ships) are MATRIX + TRC
 *  profiles — i.e. three primary XYZ tristimuli and three tone curves,
 *  no LUTs at all. The maths is exactly the same as what
 *  `createVirtualProfile` builds in-memory, so:
 *
 *      `'*sRGB'`                                  ←→   functionally identical
 *      `Profile().load('sRGB.icc', cb)`
 *
 *  for any colour transform built on top. The difference is purely
 *  startup cost:
 *
 *      virtual profile:   ~0 ms, no I/O, no decode, deterministic numbers
 *      ICC matrix file:   network/disk fetch + binary decode + adaptation
 *
 *  When TO load a real ICC profile:
 *
 *    - The profile is a CMYK or 3CLR/4CLR device profile (LUT-based; no
 *      virtual equivalent exists).
 *    - It's a printer/scanner ICC with a real measurement-derived AtoB
 *      LUT — the gamut mapping there is real data, not a formula.
 *    - It's a custom monitor profile generated by a calibrator (the
 *      primaries and TRC will not match a virtual sRGB).
 *    - You need to faithfully reproduce another CMM's interpretation of
 *      a specific embedded profile.
 *
 *  When NOT to bother:
 *
 *    - You just want "sRGB" as a working space → use `'*sRGB'`.
 *    - Adobe RGB, ProPhoto, Apple RGB, ColorMatch — same story.
 *
 *  As a small optimization, when this loader decodes an RGB profile
 *  whose tags are matrix + TRC only (no AtoB / BtoA LUTs), it
 *  AUTO-PROMOTES it to the same `RGBMatrix` fast path that virtual
 *  profiles use (see `readICCProfile` and `createRGBMatrix` below).
 *  Downstream `Transform.js` cannot tell them apart — they hit the
 *  identical inlined matrix-and-gamma kernel.
 *
 *  ----------------------------------------------------------------------------
 *  ENVIRONMENTS
 *  ----------------------------------------------------------------------------
 *
 *  The loader runs in three places:
 *    - Browser (XHR, base64)
 *    - Node.js (fs, http)
 *    - Adobe CEP extensions (`window.cep.fs`)
 *
 *  Each load entry-point picks the right backend automatically based on
 *  `isInNode()` / `isInCep()` probes at the bottom of this file.
 *
 *  ----------------------------------------------------------------------------
 *  LIFECYCLE & ERROR REPORTING
 *  ----------------------------------------------------------------------------
 *
 *      profile.loaded       true once decoded successfully (sync or async)
 *      profile.loadError    true if decode failed; check `profile.lastError`
 *      profile.lastError    { err: number|string, text: string }
 *      profile.unsuportedTags  // sic — see Pr3
 *
 *  All the file-based loaders accept an optional `afterLoad(profile)`
 *  callback. Combine with `loadPromise()` for `await`-friendly use.
 *
 *  ----------------------------------------------------------------------------
 *  KNOWN ISSUES (TODO)
 *  ----------------------------------------------------------------------------
 *
 *    Pr3: Two property names contain typos:
 *           `unsuportedTags`                       (missing 'p')
 *           `virutalProfileUsesD50AdaptedPrimaries` (transposed letters)
 *         Both are now dual-aliased onto correctly-spelled siblings:
 *           `unsupportedTags`
 *           `virtualProfileUsesD50AdaptedPrimaries`
 *         Read or write either name. The typo'd versions are flagged
 *         `@deprecated` in JSDoc so IDE autocomplete will surface a
 *         warning; the corrected names are the way forward. The typos
 *         will not be removed (would break existing consumers).
 *
 *    Pr4: `loadURL` is asynchronous (callback fires later); `loadFile`,
 *         `loadBase64`, `loadBinary`, `loadVirtualProfile` are
 *         SYNCHRONOUS (callback fires before the dispatch returns).
 *         For uniform behaviour use `loadPromise()`.
 *
 *    Pr5: Reusing one Profile instance across multiple `load()` calls
 *         only resets `loaded` / `loadError`. Stale `rgb`, `A2B`, `B2A`,
 *         `tags`, etc. linger if the new profile lacks those tags. Best
 *         practice: a new `Profile()` per profile.
 *
 *  ----------------------------------------------------------------------------
 *  CONSTRUCTOR
 *  ----------------------------------------------------------------------------
 *
 * @param dataOrUrl     - Uint8Array
 *                      - String:  'data:base64...' - load from base64 encoded string
 *                      - String:  'file:filename'  - load from local drive using platform File API
 *                      - String:  'http://...'     - load via XHR / http
 *                      - String:  '*name'          - create a virtual profile in memory
 *                                 -'*sRGB'          - sRGB
 *                                 -'*AdobeRGB'      - Adobe RGB (1998)
 *                                 -'*AppleRGB'      - Apple RGB
 *                                 -'*ColorMatchRGB' - ColorMatch RGB
 *                                 -'*ProPhotoRGB'   - ProPhoto RGB
 *                                 -'*Lab'           - Lab D50
 *                                 -'*LabD50'        - Lab D50
 *                                 -'*LabD65'        - Lab D65
 *
 * @param afterLoad     - function(profile) - callback fired when the
 *                        profile finishes loading (success or failure).
 *                        See Pr4 — sync for in-memory paths, async for
 *                        URL / network paths.
 * @constructor
 */

class Profile {

    // ========================================================================
    //  CONSTRUCTOR & STATE
    // ========================================================================

    constructor(dataOrUrl, afterLoad) {
        this.loaded = false;
        this.loadError = false;
        this.type = 0;
        this.name = '';
        this.header = {};
        this.intent = 0;
        this.tags = [];
        this.description = '';
        this.tagDescription = '';
        this.copyright = '';
        this.technology = '';
        this.viewingConditions = '';
        this.characterizationTarget = '';
        this.mediaWhitePoint = null;
        this.PCSEncode = 2;
        this.PCSDecode = 2;
        this.PCS8BitScale = 0;
        this.version = 0;
        this.pcs = false;
        this.blackPoint = null;
        this.luminance = null;
        this.chromaticAdaptation = null;

        /**
         * @deprecated Typo kept for backwards compatibility — prefer
         *             `virtualProfileUsesD50AdaptedPrimaries`. Both
         *             names are read by `createVirtualProfile` (the
         *             corrected one wins if both are set), so old and
         *             new code both work.
         */
        this.virutalProfileUsesD50AdaptedPrimaries = true;
        this.virtualProfileUsesD50AdaptedPrimaries = true;

        /**
         * @deprecated Typo kept for backwards compatibility — prefer
         *             `unsupportedTags`. Both names point at the same
         *             array (re-aliased at the end of `decodeFile`),
         *             so `.push()` from either is visible from both.
         */
        this.unsuportedTags = [];
        this.unsupportedTags = this.unsuportedTags;
        this.Gray = {
            kTRC: null,
            inv_kTRC: null,
        };
        this.rgb = {
            rTRC: null,
            rTRCInv: null,

            gTRC: null,
            gTRCInv: null,

            bTRC: null,
            bTRCInv: null,

            rXYZ: null,
            gXYZ: null,
            bXYZ: null
        };
        this.RGBMatrix = {
            gamma: 0,
            cRx: 0,
            cRy: 0,
            cGx: 0,
            cGy: 0,
            cBx: 0,
            cBy: 0
        };

        this.PCSWhitepoint = convert.d50;
        this.outputChannels = 0;
        this.lastError = {err: 0, text: 'No Error'};
        this.binaryHash  = false;   // FNV-1a hex over raw ICC bytes, set by loadBinary()
        this.virtualName = false;   // '*sRGB' etc., set by loadVirtualProfile()
        this.sizeBytes   = 0;       // declared ICC profile size, set by decodeFile()

        // These are floating point but more
        // complicated and also additional to
        // 8/16 bit tables so not implemented yet
        this.B2D = [null, null, null, null];
        this.D2B = [null, null, null, null];

        this.A2B = [null, null, null];
        this.B2A = [null, null, null];

        this.absoluteAdaptationIn = {
            Xa: 1,
            Ya: 1,
            Za: 1
        };

        this.absoluteAdaptationOut = {
            Xa: 1,
            Ya: 1,
            Za: 1
        };

        if (dataOrUrl) {
            this.load(dataOrUrl, afterLoad);
        }
    };

    // ========================================================================
    //  LOADERS — dispatcher + per-source variants
    // ========================================================================

    /**
     * Promise-flavoured wrapper around `load()`. Resolves with the
     * `Profile` instance once the load has finished, including a failed
     * one, so check `.loaded` and `.lastError` afterwards.
     * Use this when you want `await profile.loadPromise(url)` rather
     * than callback wiring.
     *
     * @param {Uint8Array|string} dataOrUrl  See `load()`.
     * @returns {Promise<Profile>}
     */
    loadPromise(dataOrUrl) {
        return new Promise((resolve, reject) => {
            this.load(dataOrUrl, (loaded) => {
                if (loaded) {
                    resolve(loaded);
                } else {
                    reject(new Error("Profile failed to load"));
                }
            });
        });
    }

    /**
     * Top-level loader. Sniffs the source type and dispatches to the
     * right backend:
     *
     *   `Uint8Array`        → loadBinary   (sync)
     *   `'*name'`           → loadVirtualProfile (sync)
     *   `'file:...'`        → loadFile     (sync; Node / CEP only)
     *   `'data:...'`        → loadBase64   (sync)
     *   anything else       → loadURL      (async; XHR or http.get)
     *
     * See Pr4 in the file header about the sync/async split.
     *
     * @param {Uint8Array|string} dataOrUrl  Source identifier (see above).
     * @param {function(Profile):void} [afterLoad]  Completion callback.
     */
    load(dataOrUrl, afterLoad) {
        this.loaded = false;
        this.loadError = false;
        if (Object.prototype.toString.call(dataOrUrl) === '[object Uint8Array]') {
            this.loadBinary(dataOrUrl, afterLoad);
        } else if (dataOrUrl.substring(0, 1) === '*') {
            this.loadVirtualProfile(dataOrUrl, afterLoad);
        } else if (dataOrUrl.substring(0, 5).toLowerCase() === 'file:') {
            this.loadFile(dataOrUrl, afterLoad);
        } else if (dataOrUrl.substring(0, 5).toLowerCase() === 'data:') {
            this.loadBase64(dataOrUrl, afterLoad)
        } else {
            this.loadURL(dataOrUrl, afterLoad);
        }
    };

    /**
     * Decode a profile already in memory as a `Uint8Array`. Synchronous.
     * A view into a larger buffer (`byteOffset !== 0`, e.g. a TIFF 34675
     * tag or JPEG APP2 slice) is copied to a compact array first so
     * decode does not read the host file's header as ICC bytes.
     *
     * @param {Uint8Array} binary             Raw profile bytes.
     * @param {function(Profile):void} [afterLoad]
     * @param {boolean} [searchForProfile]    If true, scans the buffer
     *        for an embedded `'ICC_PROFILE'` marker first (e.g. when
     *        passing a JPEG / TIFF byte stream containing an APP2 / IPTC
     *        ICC payload).
     */
    loadBinary(binary, afterLoad, searchForProfile) {
        this.loaded = this.readICCProfile(binary, searchForProfile);
        this.loadError = !this.loaded;
        if(this.loaded && binary && binary.length){
            this.binaryHash = _profileFnv1a32(binary, this.sizeBytes);
        }
        if(typeof afterLoad === 'function'){
            afterLoad(this);
        }
    };

    /**
     * Load a profile from the local filesystem. Synchronous. Available
     * in Node.js (via `fs.readFileSync`) and Adobe CEP (via
     * `window.cep.fs.readFile`). Not supported in plain browsers.
     *
     * Accepts either a bare path or a `'file:...'`-prefixed string.
     *
     * @param {string} filename
     * @param {function(Profile):void} [afterLoad]
     */
    loadFile(filename, afterLoad) {
        if(filename.substring(0, 5).toLowerCase() === 'file:'){
            filename = filename.substring(5, filename.length);
        }

        var binaryData = this.readBinaryFile(filename);
        if (binaryData !== false) {
            this.loaded = this.readICCProfile(binaryData);
            this.loadError = !this.loaded;
        } else {
            this.loadError = true;
            this.loaded = false;
        }

        if(typeof afterLoad === 'function'){
            afterLoad(this);
        }
    };

    /**
     * Load a profile from a base64-encoded string. Synchronous. Accepts
     * either a bare base64 payload or a `'data:...'`-prefixed string
     * (the prefix is stripped — note no MIME parsing, just the literal
     * 5-char marker).
     *
     * @param {string} base64
     * @param {function(Profile):void} [afterLoad]
     */
    loadBase64(base64, afterLoad) {
        if(base64.substring(0, 5).toLowerCase() === 'data:'){
            base64 = base64.substring(5, base64.length);
        }

        var data = base64ToUint8Array(base64);
        this.loaded = this.readICCProfile(data);
        this.loadError = !this.loaded;
        if(typeof afterLoad === 'function'){
            afterLoad(this);
        }
    };

    /**
     * Load a profile over HTTP. ASYNCHRONOUS — the `afterLoad` callback
     * fires after the network round-trip completes, not before this
     * method returns. Uses `http.get` in Node and `XMLHttpRequest` in
     * the browser.
     *
     * @param {string} url
     * @param {function(Profile):void} [afterLoad]
     */
    loadURL(url, afterLoad) {
        var _this = this;

        if(isInNode()){
            nodeLoadFileFromURL(url, processData);
        } else {
            XHRLoadBinary(url, processData);
        }

        function processData(result, errorString) {
            _this.lastError = {err: errorString === '' ? 0 : -1, text: errorString};
            if(result) {
                _this.loaded = _this.readICCProfile(result);
                _this.loadError = !_this.loaded;
            } else {
                _this.loaded = false;
                _this.loadError = true;
            }
            if(typeof afterLoad === 'function'){
                afterLoad(_this);
            }
        }
    };

    /**
     * Build a virtual profile by name (no file I/O). Synchronous.
     *
     * Accepts either a bare name (`'sRGB'`) or a `'*'`-prefixed string
     * (`'*sRGB'`); the leading `*` is what the dispatcher in `load()`
     * uses to pick this branch.
     *
     * See `createVirtualProfile` for the supported name list.
     *
     * @param {string} name
     * @param {function(Profile):void} [afterLoad]
     */
    loadVirtualProfile(name, afterLoad) {
        this.virtualName = (name.substring(0, 1) === '*') ? name : ('*' + name);
        if(name.substring(0, 1) === '*'){
            name = name.substring(1, name.length);
        }
        this.loaded = this.createVirtualProfile(name);
        this.loadError = !this.loaded;
        if(typeof afterLoad === 'function'){
            afterLoad(this);
        }
    };

    /**
     * Synchronous filesystem read backing `loadFile`. Returns either a
     * `Uint8Array` of the file contents or `false` on failure (and
     * populates `this.lastError` with a structured error object).
     *
     * Throws in environments other than Node and CEP.
     *
     * @param {string} filename
     * @returns {Uint8Array|false}
     */
    readBinaryFile(filename) {
        let b64String;
        if (isInCep()) {
            if(window.cep && window.cep.fs && window.cep.fs.readFile){
                //
                // In adobe illustrator cep enviroment
                //
                let file = window.cep.fs.readFile(filename, cep.encoding.Base64);
                if (file.err === 0) {
                    // FIX (Pr2): formerly fell through to the isInNode()
                    // branch (which is false in CEP) and then threw
                    // 'not supported in this environment' — so even
                    // SUCCESSFUL CEP file reads broke. Return the
                    // decoded payload directly here.
                    return base64ToUint8Array(file.data);
                } else {
                    this.lastError = {
                        err: file.err,
                        text: file.errorString = [
                            'NO_ERROR', //0
                            'ERR_UNKNOWN', //1
                            'ERR_INVALID_PARAMS', //2
                            'ERR_NOT_FOUND', //3
                            'ERR_CANT_READ', // 4
                            'ERR_UNSUPPORTED_ENCODING', // 5
                            'ERR_CANT_WRITE', // 6
                            'ERR_OUT_OF_SPACE', // 7
                            'ERR_NOT_FILE', // 8
                            'ERR_NOT_DIRECTORY', // 9
                            'ERR_FILE_EXISTS', // 10
                            'UNABLE TO PARSE FILE', //11,
                            'ERR_DIRECTORY_NOT_FOUND' //12
                        ][file.err] || 'UNKNOWN ERROR ' + file.err
                    };
                    return false;
                }
            }
        }

        if(isInNode()){
            //
            // In node, we can use the Buffer class
            //
            const fs = require("fs");
            try {
                b64String = fs.readFileSync(filename, {encoding: 'base64'});
            } catch (e) {
                this.lastError = {
                    err: e,
                    text: e.message
                };
                return false;
            }
            return base64ToUint8Array(b64String)
        }

        // Not supported in browser
        throw new Error('readBinaryFile not supported in this environment');
    }

    // ========================================================================
    //  VIRTUAL PROFILES — synthesize a profile from primaries + gamma
    // ========================================================================

    /**
     * Build an in-memory profile from a hard-coded primaries / gamma
     * recipe. No file I/O.
     *
     * Recognized names (case-insensitive, spaces stripped):
     *
     *   `lab` / `labd50`             — Lab D50 abstract profile
     *   `labd65`                     — Lab D65 abstract profile
     *   `srgb`                       — sRGB working space (gamma 2.2 + sRGB special)
     *   `adobe` / `adobergb` /
     *   `adobe1998` / `adobe1998rgb` — Adobe RGB (1998), gamma 2.2
     *   `apple` / `applergb`         — Apple RGB, gamma 1.8
     *   `colormatch` / `colormatchrgb` — ColorMatch RGB, gamma 1.8, D50
     *   `prophoto` / `prophotorgb`   — ProPhoto RGB, gamma 1.8, D50
     *
     * For RGB names the primaries are stored EITHER pre-adapted to D50
     * OR as their native chromaticities, controlled by
     * `this.virutalProfileUsesD50AdaptedPrimaries` (sic — see Pr3 in
     * the file header) — D50-adapted by default, matching the ICC v4
     * convention so transforms with a D50 PCS need no extra step.
     *
     * Returns true on success, false on unsupported name (and sets
     * `this.lastError`).
     *
     * Internally calls a `computeRGBProfile` helper that calculates
     * both the legacy 3x3 matrix and the modern XYZ matrix (and their
     * inverses) from the primaries.
     *
     * @param {string} name
     * @returns {boolean}
     */
    createVirtualProfile(name) {

        // Honour the corrected property name as input too — if the
        // caller set `virtualProfileUsesD50AdaptedPrimaries` (no typo)
        // mirror it onto the legacy spelling that the read sites
        // below actually consume. Lets new code use the right name
        // without us having to update every read site.
        if (this.virtualProfileUsesD50AdaptedPrimaries !== this.virutalProfileUsesD50AdaptedPrimaries) {
            this.virutalProfileUsesD50AdaptedPrimaries = this.virtualProfileUsesD50AdaptedPrimaries;
        }

        // Virtual Profiles are this.version = v4 so that by default the Transform will output PCS V4 encoded date
        // http://www.brucelindbloom.com/index.html?WorkingSpaceInfo.html
        //
        //                  gamma   white   x           y           Y           x           y           Y           x           y           Y
        // Adobe RGB (1998)	2.2	    D65     0.6400      0.3300      0.297361    0.2100      0.7100      0.627355    0.1500      0.0600      0.075285
        // Apple RGB        1.8     D65     0.6250      0.3400      0.244634    0.2800      0.5950      0.672034    0.1550      0.0700      0.083332
        // Best RGB         2.2     D50     0.7347      0.2653      0.228457    0.2150      0.7750      0.737352    0.1300      0.0350      0.034191
        // Beta RGB         2.2     D50     0.6888      0.3112      0.303273    0.1986      0.7551      0.663786    0.1265      0.0352      0.032941
        // Bruce RGB        2.2     D65     0.6400      0.3300      0.240995    0.2800      0.6500      0.683554    0.1500      0.0600      0.075452
        // CIE RGB          2.2     E       0.7350      0.2650      0.176204    0.2740      0.7170      0.812985    0.1670      0.0090      0.010811
        // ColorMatch RGB   1.8     D50     0.6300      0.3400      0.274884    0.2950      0.6050      0.658132    0.1500      0.0750      0.066985
        // Don RGB 4        2.2     D50     0.6960      0.3000      0.278350    0.2150      0.7650      0.687970    0.1300      0.0350      0.033680
        // ECI RGB v2       L*      D50     0.6700      0.3300      0.320250    0.2100      0.7100      0.602071    0.1400      0.0800      0.077679
        // Ekta Space PS5   2.2     D50     0.6950      0.3050      0.260629    0.2600      0.7000      0.734946    0.1100      0.0050      0.004425
        // NTSC RGB         2.2     C       0.6700      0.3300      0.298839    0.2100      0.7100      0.586811    0.1400      0.0800      0.114350
        // PAL/SECAM RGB    2.2     D65     0.6400      0.3300      0.222021    0.2900      0.6000      0.706645    0.1500      0.0600      0.071334
        // ProPhoto RGB     1.8     D50     0.7347      0.2653      0.288040    0.1596      0.8404      0.711874    0.0366      0.0001      0.000086
        // SMPTE-C RGB      2.2     D65     0.6300      0.3400      0.212395    0.3100      0.5950      0.701049    0.1550      0.0700      0.086556
        // sRGB             ≈2.2    D65     0.6400      0.3300      0.212656    0.3000      0.6000      0.715158    0.1500      0.0600      0.072186
        // Wide Gamut RGB   2.2     D50     0.7350      0.2650      0.258187    0.1150      0.8260      0.724938    0.1570      0.0180      0.016875

        //Working Space Primaries Adapted to D50
        //                      x           y           Y           x           y           Y           x           y           Y
        // Adobe RGB (1998)	    0.648431	0.330856	0.311114	0.230154	0.701572	0.625662	0.155886	0.066044	0.063224
        // Apple RGB	        0.634756	0.340596	0.255166	0.301775	0.597511	0.672578	0.162897	0.079001	0.072256
        // Best RGB	            0.734700	0.265300	0.228457	0.215000	0.775000	0.737352	0.130000	0.035000	0.034191
        // Beta RGB	            0.688800	0.311200	0.303273	0.198600	0.755100	0.663786	0.126500	0.035200	0.032941
        // Bruce RGB	        0.648431	0.330856	0.252141	0.300115	0.640960	0.684495	0.155886	0.066044	0.063364
        // CIE RGB	            0.737385	0.264518	0.174658	0.266802	0.718404	0.824754	0.174329	0.000599	0.000588
        // ColorMatch RGB	    0.630000	0.340000	0.274884	0.295000	0.605000	0.658132	0.150000	0.075000	0.066985
        // Don RGB 4	        0.696000	0.300000	0.278350	0.215000	0.765000	0.687970	0.130000	0.035000	0.033680
        // ECI RGB v2	        0.670000	0.330000	0.320250	0.210000	0.710000	0.602071	0.140000	0.080000	0.077679
        // Ekta Space PS5	    0.695000	0.305000	0.260629	0.260000	0.700000	0.734946	0.110000	0.005000	0.004425
        // NTSC RGB	            0.671910	0.329340	0.310889	0.222591	0.710647	0.591737	0.142783	0.096145	0.097374
        // PAL/SECAM RGB	    0.648431	0.330856	0.232289	0.311424	0.599693	0.707805	0.155886	0.066044	0.059906
        // ProPhoto RGB	        0.734700	0.265300	0.288040	0.159600	0.840400	0.711874	0.036600	0.000100	0.000086
        // SMPTE-C RGB	        0.638852	0.340194	0.221685	0.331007	0.592082	0.703264	0.162897	0.079001	0.075052
        // sRGB	                0.648431	0.330856	0.222491	0.321152	0.597871	0.716888	0.155886	0.066044	0.060621
        // Wide Gamut RGB	    0.735000	0.265000	0.258187	0.115000	0.826000	0.724938	0.157000	0.018000	0.016875

        // https://infoscience.epfl.ch/record/34089/files/SusstrunkBS99.pdf?version=3
        // http://www.babelcolor.com/index_htm_files/A%20review%20of%20RGB%20color%20spaces.pdf

        var redxxY, greenxyY, bluexyY, mediaWhitePoint;

        // Set for RGB, Will change if we are a Lab profile
        this.outputChannels = 3;
        this.version = 4;
        this.pcs = 'XYZ';
        this.colorSpace = 'RGB';
        this.header = {
            profileSize: 0,
            cmmType: 0,
            version: 4,
            pClass: 'mntr',
            space: 'rgb',
            pcs: 'XYZ',
            date: new Date(),
            signature: '',
            platform: '',
            flags: 0,
            attributes: 0,
            intent: 3,
            PCSilluminant: convert.d50
        };

        switch (String(name).replace(' ', '').toLowerCase()) {
            case 'labd50': // LabD50
            case 'lab': // LabD50
                this.type = eProfileType.Lab;
                this.name = this.description = 'Lab D50 Profile';
                this.PCSWhitepoint = convert.d50;
                this.mediaWhitePoint = convert.d50;
                this.pcs = 'LAB';
                this.colorSpace = 'LAB';
                this.header = {
                    profileSize: 0,
                    cmmType: 0,
                    version: 4,
                    pClass: 'abst',
                    space: 'Lab',
                    pcs: 'LAB',
                    date: new Date(),
                    signature: '',
                    platform: '',
                    flags: 0,
                    attributes: 0,
                    intent: 3,
                    PCSilluminant: convert.d50
                }
                return true;

            case 'labd65': // LabD50
                this.type = eProfileType.Lab;
                this.name = this.description = 'Lab D65 Profile';
                this.PCSWhitepoint = convert.d50;
                this.mediaWhitePoint = convert.d65;
                this.pcs = 'LAB';
                this.colorSpace = 'LAB';
                this.header = {
                    profileSize: 0,
                    cmmType: 0,
                    version: 4,
                    pClass: 'abst',
                    space: 'Lab',
                    pcs: 'LAB',
                    date: new Date(),
                    signature: '',
                    platform: '',
                    flags: 0,
                    attributes: 0,
                    intent: 3,
                    PCSilluminant: convert.d50
                }
                return true;

            case 'srgb':

                if(this.virutalProfileUsesD50AdaptedPrimaries){
                    redxxY = convert.xyY(0.648431, 0.330856,0.222491);
                    greenxyY = convert.xyY(0.321152, 0.597871,0.716888);
                    bluexyY = convert.xyY(0.155886, 0.066044,0.060621);
                    mediaWhitePoint = convert.d50;
                } else {
                    redxxY = convert.xyY(0.64, 0.33,0.212656);
                    greenxyY = convert.xyY(0.30, 0.60,0.715158);
                    bluexyY = convert.xyY(0.15, 0.06,0.072186);
                    mediaWhitePoint = convert.d65;
                }

                this.name = 'sRGB';
                this.description = "RGB is a standard RGB color space created cooperatively by HP and Microsoft in 1996 for use on monitors, printers and the Internet<br><br>Note that sRGB's small Gamut is not suitable for graphic production.<br><br>Encompasses roughly 35% of the visible colors specified by the Lab color space";
                this.mediaWhitePoint = mediaWhitePoint;
                computeRGBProfile(this,2.2, redxxY, greenxyY, bluexyY, true);

                return true;

            case 'adobe1998':
            case 'adobe':
            case 'adobergb':
            case 'adobe1998rgb':
                if(this.virutalProfileUsesD50AdaptedPrimaries){
                    redxxY = convert.xyY(0.648431, 0.330856,0.311114);
                    greenxyY = convert.xyY(0.230154, 0.701572,0.625662);
                    bluexyY = convert.xyY(0.155886, 0.066044,0.063224);
                    mediaWhitePoint = convert.d50;
                } else {
                    redxxY = convert.xyY(0.64, 0.33,0.297361);
                    greenxyY = convert.xyY(0.21, 0.71,0.627355);
                    bluexyY = convert.xyY(0.15, 0.06,0.075285);
                    mediaWhitePoint = convert.d65;
                }
                this.name = 'Adobe RGB (1998)';
                this.description = 'Developed by Adobe Systems, Inc. in 1998. It was designed to encompass most of the colors achievable on CMYK color printers, but by using RGB primary colors on a device such as a computer display. The Adobe RGB (1998) improves upon the gamut of the sRGB color space, primarily in cyan-green hues<br>Encompasses roughly 50% of the visible colors specified by the Lab color space';
                this.mediaWhitePoint = mediaWhitePoint;
                computeRGBProfile(this,2.2, redxxY, greenxyY, bluexyY, false);
                return true;

            case 'apple':
            case 'applergb':
                if(this.virutalProfileUsesD50AdaptedPrimaries){
                    redxxY = convert.xyY(0.634756, 0.340596,0.255166);
                    greenxyY = convert.xyY(0.301775, 0.597511,0.672578);
                    bluexyY = convert.xyY(0.162897, 0.079001,0.072256);
                    mediaWhitePoint = convert.d50;
                } else {
                    redxxY = convert.xyY(0.6250, 0.3400,0.244634);
                    greenxyY = convert.xyY(0.2800, 0.5950,0.672034);
                    bluexyY = convert.xyY(0.1550, 0.0700,0.083332);
                    mediaWhitePoint = convert.d65;
                }

                this.name = 'Apple RGB';
                this.description = 'Apple RGB is based on the classic Apple 13" RGB monitor. Because of its popularity and similar Trinitronbased monitors that followed, many key publishing applications, including Adobe Photoshop and Illustrator, used it as the default RGB space in the past.<br>Encompasses roughly 33.5% of the visible colors specified by the Lab color space';
                this.mediaWhitePoint = mediaWhitePoint;
                computeRGBProfile(this,1.8, redxxY, greenxyY,  bluexyY, false);
                return true;

            case 'colormatchrgb':
            case 'colormatch':

                // Colormatch is D50
                redxxY = convert.xyY(0.6300, 0.3400,0.274884);
                greenxyY = convert.xyY(0.2950, 0.6050,0.658132);
                bluexyY = convert.xyY(0.1500, 0.0750,0.066985);

                this.name = 'ColorMatch RGB';
                this.description = 'An RGB profile with a D50 whitepoint used for prepress<br>Encompasses roughly 35.2% of the visible colors specified by the Lab color space';
                this.mediaWhitePoint = convert.d50;
                computeRGBProfile(this,1.8,  redxxY, greenxyY,  bluexyY, false);
                return true;

            case 'prophoto':
            case 'prophotorgb':

                redxxY = convert.xyY(0.7347, 0.2653,0.288040);
                greenxyY = convert.xyY(0.1596, 0.8404,0.711874);
                bluexyY = convert.xyY(0.0366, 0.0001,0.000086);

                this.name = 'ProPhoto RGB';
                this.description = 'The ProPhoto RGB color space, also known as ROMM RGB (Reference Output Medium Metric), is an output referred RGB color space developed by Kodak. It offers an especially large gamut designed for use with photographic output in mind.<br>Encompasses roughly 91.2% of the visible colors specified by the Lab color space';
                this.mediaWhitePoint = convert.d50;
                computeRGBProfile(this,1.8,  redxxY, greenxyY,  bluexyY, false);
                return true;

            default:
                this.lastError = {err: 100, text: 'Unsupported Virtual Profile [' + name + ']'};
                return false;
        }

        function computeRGBProfile(profile, gamma, redxxY, greenxyY, bluexyY, isSRGB) {

            profile.type = eProfileType.RGBMatrix;

            profile.PCSWhitepoint = convert.d50;

            profile.rgb.rXYZ = convert.xyY2XYZ(redxxY)
            profile.rgb.gXYZ = convert.xyY2XYZ(greenxyY)
            profile.rgb.bXYZ = convert.xyY2XYZ(bluexyY);

            profile.RGBMatrix = {
                gamma: gamma,
                issRGB: isSRGB === true, // uses special sRGB Gamma formula
                cRx: redxxY.x,
                cRy: redxxY.y,
                cGx: greenxyY.x,
                cGy: greenxyY.y,
                cBx: bluexyY.x,
                cBy: bluexyY.y,
            };

            //
            // TODO remove this code and just use XYZMatrix
            //
            // Note, these compute the XYZ <> RGB Matrix
            // http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html
            //

            var m = {
                m00: profile.RGBMatrix.cRx / profile.RGBMatrix.cRy,
                m01: profile.RGBMatrix.cGx / profile.RGBMatrix.cGy,
                m02: profile.RGBMatrix.cBx / profile.RGBMatrix.cBy,

                m10:1.0,
                m11:1.0,
                m12:1.0,

                m20:(1.0 - profile.RGBMatrix.cRx - profile.RGBMatrix.cRy) / profile.RGBMatrix.cRy,
                m21:(1.0 - profile.RGBMatrix.cGx - profile.RGBMatrix.cGy) / profile.RGBMatrix.cGy,
                m22:(1.0 - profile.RGBMatrix.cBx - profile.RGBMatrix.cBy) / profile.RGBMatrix.cBy
            };

            var mi = convert.invertMatrix(m);

            // Y = 1
            // var sr = whitePoint.X * mi.m00 + whitePoint.Y * mi.m01 + whitePoint.Z * mi.m02;
            var sR = (profile.mediaWhitePoint.X * mi.m00) + (profile.mediaWhitePoint.Y * mi.m01) + (profile.mediaWhitePoint.Z * mi.m02);
            var sG = (profile.mediaWhitePoint.X * mi.m10) + (profile.mediaWhitePoint.Y * mi.m11) + (profile.mediaWhitePoint.Z * mi.m12);
            var sB = (profile.mediaWhitePoint.X * mi.m20) + (profile.mediaWhitePoint.Y * mi.m21) + (profile.mediaWhitePoint.Z * mi.m22);

            // Matrix from primaries - (Needed for Legacy Code)
            profile.RGBMatrix.matrixV4 = {
                m00 : sR * m.m00,    m01 : sG * m.m01,   m02 : sB * m.m02,
                m10 : sR * m.m10,    m11 : sG * m.m11,   m12 : sB * m.m12,
                m20 : sR * m.m20,    m21 : sG * m.m21,   m22 : sB * m.m22
            };
            profile.RGBMatrix.matrixInv = convert.invertMatrix(profile.RGBMatrix.matrixV4);

            // Matrix from XYZ values
            // Used in Transforms
            profile.RGBMatrix.XYZMatrix = {
                m00 : profile.rgb.rXYZ.X,   m01 : profile.rgb.gXYZ.X,  m02 : profile.rgb.bXYZ.X,
                m10 : profile.rgb.rXYZ.Y,   m11 : profile.rgb.gXYZ.Y,  m12 : profile.rgb.bXYZ.Y,
                m20 : profile.rgb.rXYZ.Z,   m21 : profile.rgb.gXYZ.Z,  m22 : profile.rgb.bXYZ.Z,
            };
            profile.RGBMatrix.XYZMatrixInv = convert.invertMatrix(profile.RGBMatrix.XYZMatrix);
        }
    };



    // ========================================================================
    //  ICC DECODE — top-level decode + RGB-matrix auto-promotion
    // ========================================================================

    /**
     * Top-level ICC decode. Validates the header signature (`'acsp'`),
     * dispatches to `decodeFile` for tag-by-tag decode, then derives a
     * couple of cached values used by `Transform.js`:
     *
     *   - `PCSWhitepoint`            from header PCS illuminant
     *   - `absoluteAdaptationIn/Out` ratios for absolute-colorimetric
     *
     * If the resulting profile is RGB with NO AtoB/BtoA LUTs but a
     * complete set of primaries + TRCs, it is AUTO-PROMOTED to the
     * fast `RGBMatrix` type (same internal shape as a virtual profile)
     * — see the file header for why this matters.
     *
     * `searchForProfile` first scans the byte stream for an embedded
     * `ICC_PROFILE` marker (e.g. inside a JPEG APP2 segment).
     *
     * @param {Uint8Array|Buffer} data
     * @param {boolean} [searchForProfile]
     * @returns {boolean}  true on success, false on any decode failure.
     */
    readICCProfile(data, searchForProfile) {

        if(isInNode()){
            if(data instanceof Buffer){
                data = new Uint8Array(data);
            }
        }

        // Typed-array view into a larger file (TIFF tag, JPEG APP2, Node
        // Buffer.subarray). Indexing is view-relative; buffer.slice() is
        // not. Compact-copy so decodeICC never reads the host file.
        data = _compactIccBytes(data);

        var _this = this;
        var start = 0;
        if (searchForProfile){
            //Search for text "ICC_PROFILE" in an Image
            var ICC_PROFILE = [73 ,67 ,67 ,95 ,80 ,82 ,79 ,70 ,73 ,76 ,69 ];
            start = scan(data,0, ICC_PROFILE);
            if(start === -1){
                return false;
            }
        }

        // Search for text "acsp" in the profile header
        var acsp = [97, 99, 115, 112];
        var ascpPos = scan(data, start, acsp);
        if (ascpPos === -1) {
            this.lastError = {err: 121, text: 'No ICC profile signature found'};
            return false;
        }

        if (searchForProfile) { data = _compactIccBytes(data.subarray(ascpPos - 36)); }
        // extract the core profile data
        var result;
        try {
            result = this.decodeFile(data);
        } catch (decodeError) {
            this.lastError = {err: 120, text: 'Profile decode failed: ' + (decodeError && decodeError.message || decodeError)};
            result = false;
        }

        if (result === true) {
            // update whitepoint
            this.PCSWhitepoint = convert.getWhitePointFromIlluminant(this.header.PCSilluminant);

            // this.mediaWhitePoint = convert.getWhitePointFromIlluminant(this.mediaWhitePoint);

            // pre-calculate adaptation matrixV4 values.
            // DeviceLink profiles have no wtpt tag — mediaWhitePoint stays
            // null and absolute adaptation does not apply (no PCS).
            if (this.mediaWhitePoint) {
                // A v2 display profile's wtpt is the unadapted monitor white,
                // not a media white relative to D50, so absolute does not
                // scale by it. Little CMS treats those as D50 for this reason.
                var v2Display = this.version === 2 && this.header.pClass === 'mntr';
                var white = v2Display ? this.header.PCSilluminant : this.mediaWhitePoint;

                this.absoluteAdaptationIn = {
                    Xa: white.X / this.header.PCSilluminant.X,
                    Ya: white.Y / this.header.PCSilluminant.Y,
                    Za: white.Z / this.header.PCSilluminant.Z
                };

                this.absoluteAdaptationOut = {
                    Xa: this.header.PCSilluminant.X / white.X,
                    Ya: this.header.PCSilluminant.Y / white.Y,
                    Za: this.header.PCSilluminant.Z / white.Z
                };
            }

            //TODO check for required tags for all profile types...

            // determine the encoding on the A2b Tables
            //this.PCSDecode = this.findA2BEncoding(this.A2B[eIntent.relative]);
            if (_this.header.space === 'RGB ' &&
                _this.A2B[eIntent.relative] === null &&
                _this.B2A[eIntent.relative] === null &&
                _this.rgb.gXYZ &&
                _this.rgb.rXYZ &&
                _this.rgb.bXYZ &&
                _this.rgb.rTRC &&
                _this.rgb.gTRC &&
                _this.rgb.bTRC
            ) {
                if (!this.mediaWhitePoint) {
                    this.lastError = {err: 120, text: 'Profile decode failed: RGB matrix profile has no wtpt tag'};
                    this.loaded = false;
                    return false;
                }

                // Convert to an RGBMatrix type profile.
                this.createRGBMatrix();
            }

            this.loaded = true;
            return true;
        }

        this.loaded = false;
        return false;

        function scan(outerArray, start, innerArray) {
            for (var i = start; i < outerArray.length - innerArray.length; i++) {
                var found = true;
                for (var j = 0; j < innerArray.length; j++) {
                    if (outerArray[i + j] !== innerArray[j]) {
                        found = false;
                        break;
                    }
                }
                if (found) {
                    return i;
                }
            }
            return -1;
        }
    };

    // ========================================================================
    //  RGB-MATRIX PROMOTION — make decoded RGB matrix profiles fast
    // ========================================================================

    /**
     * Convert a freshly-decoded RGB profile (one that has primary XYZs +
     * three TRC curves and no LUT) into the same internal `RGBMatrix`
     * shape that virtual profiles use. After this call, downstream
     * transforms hit the same inlined matrix-and-gamma kernel for both
     * sources — there is no runtime cost difference between
     * `'*sRGB'` and a decoded sRGB.icc.
     *
     * The primaries are adapted from the ICC PCS D50 reference to the
     * profile's actual `mediaWhitePoint` before the matrix is computed.
     *
     * @return {boolean}
     */
    createRGBMatrix() {
        //this.PCSWhitepoint = convert.getWhitePointFromIlluminant(this.header.PCSilluminant);
        this.PCSWhitepoint = this.header.PCSilluminant;
        var d50 = convert.d50;

        // adapt primaries from D50 as per the ICC spec to the whitepoint of the profile
        //
        //
        var rxy = convert.XYZ2xyY(convert.adaptation(this.rgb.rXYZ, d50, this.mediaWhitePoint), this.PCSWhitepoint);
        var gxy = convert.XYZ2xyY(convert.adaptation(this.rgb.gXYZ, d50, this.mediaWhitePoint), this.PCSWhitepoint);
        var bxy = convert.XYZ2xyY(convert.adaptation(this.rgb.bXYZ, d50, this.mediaWhitePoint), this.PCSWhitepoint);
        this.type = eProfileType.RGBMatrix;
        this.RGBMatrix = {
            gamma: this.rgb.rTRC.gamma,
            issRGB: (this.name.substr(0, 4) === 'sRGB'),

            cRx: rxy.x,
            cRy: rxy.y,

            cGx: gxy.x,
            cGy: gxy.y,

            cBx: bxy.x,
            cBy: bxy.y
        };
        convert.computeMatrix(this);
    };


    /**
     * Decode the 128-byte ICC profile header into a plain object. Reads
     * profile size, CMM signature, version bytes, profile/colour-space
     * codes, render intent and the PCS illuminant XYZ.
     *
     * @param {Uint8Array} binary
     * @returns {object}
     */
    decodeHeader(binary) {
        var header = {};
        header.profileSize = decode.uint32(binary, 0);
        header.cmmType = decode.chars(binary, 4, 4);
        // ICC version — 4 bytes at offset 8. ICC v4 §7.2.4:
        //   byte[0]: major version (binary)
        //   byte[1]: minor (high nibble) + bug fix (low nibble) — packed BCD
        //   byte[2..3]: reserved (zero)
        // Stored as a "M.m.b" string for human/JSON readability. The integer
        // major is also exposed as `header.versionMajor` for engine routing
        // (v2 vs v4 PCS encoding).
        header.versionMajor = binary[8];
        var _vb = binary[9];
        header.version = header.versionMajor + '.' + ((_vb >> 4) & 0x0F) + '.' + (_vb & 0x0F);
        header.pClass = decode.chars(binary, 12, 4);
        header.space = decode.chars(binary, 16, 4);
        header.pcs = decode.chars(binary, 20, 4);
        // ICC date — 12 bytes at offset 24, six big-endian u16 fields:
        //   [year][month][day][hour][minute][second]   (UTC, ICC v4 §7.2.10)
        // Older code stored the raw byte array, which serialised to JSON as
        // unreadable [7,217,0,6,...]. Now: parse to a JS Date — JSON.stringify
        // emits an ISO string. Year 0 → null (some profiles leave date unset).
        var _dY = decode.uint16(binary, 24);
        if(_dY === 0){
            header.date = null;
        } else {
            header.date = new Date(Date.UTC(
                _dY,
                decode.uint16(binary, 26) - 1,   // month 0-indexed in JS
                decode.uint16(binary, 28),
                decode.uint16(binary, 30),
                decode.uint16(binary, 32),
                decode.uint16(binary, 34)
            ));
        }
        header.signature = decode.chars(binary, 36, 4);
        header.platform = decode.chars(binary, 40, 4);
        header.flags = decode.array(binary, 44, 4);
        header.attributes = decode.array(binary, 56, 8);
        header.intent = decode.uint32(binary, 64);
        header.PCSilluminant = decode.XYZNumber(binary, 68);
        return header;
    };

    /**
     * Read the ICC tag table at byte 128 and return an array of
     * `{ sig, offset, length }` records (one per tag). Does not
     * dereference the tag bodies — that's `decodeFile`'s job.
     *
     * @param {Uint8Array} binary
     * @returns {Array<{sig:string, offset:number, length:number}>}
     */
    decodeTags(binary) {
        var tags = [];
        var tagCount = decode.uint32(binary, 128);
        var pos = 128 + 4;
        for (var i = 0; i < tagCount; i++) {
            tags.push({
                sig: decode.chars(binary, pos, 4),
                offset: decode.uint32(binary, pos + 4),
                length: decode.uint32(binary, pos + 8)
            });
            pos += 12;
        }
        return tags;
    };

    /**
     * Refuse a profile that ends before its own header or tag table says it
     * should. Without this a truncated file loads, and the tags past the cut
     * decode from `undefined` bytes into a LUT of zeros.
     *
     * The ICC size field is exact, pad bytes included (ICC.1:2022 7.2.2), and
     * the last tag may carry up to three of them. Writers disagree about
     * counting those, so three bytes short is tolerated. Bytes PAST the
     * declared size are not checked at all: hosts pad embedded profiles.
     *
     * @param {Uint8Array} binary
     * @returns {boolean}
     */
    checkProfileExtent(binary) {
        var padTolerance = 3;
        var truncated = function(profile, detail) {
            profile.lastError = {err: 130, text: 'Truncated profile: ' + detail};
            return false;
        };

        if (binary.length < 132) {
            return truncated(this, binary.length + ' bytes is smaller than a header and tag count');
        }

        var declaredSize = decode.uint32(binary, 0) >>> 0;
        if (declaredSize > binary.length + padTolerance) {
            return truncated(this, 'header declares ' + declaredSize + ' bytes, got ' + binary.length);
        }

        var tagCount = decode.uint32(binary, 128) >>> 0;
        if (132 + tagCount * 12 > binary.length) {
            return truncated(this, 'tag table of ' + tagCount + ' tags does not fit');
        }

        for (var i = 0; i < tagCount; i++) {
            var entry = 132 + i * 12;
            var tagEnd = (decode.uint32(binary, entry + 4) >>> 0) + (decode.uint32(binary, entry + 8) >>> 0);
            if (tagEnd > binary.length + padTolerance) {
                return truncated(this, 'tag ' + decode.chars(binary, entry, 4) + ' ends at ' + tagEnd
                    + ', got ' + binary.length + ' bytes');
            }
        }
        return true;
    };

    /**
     * Walk the ICC tag table and dispatch each tag signature to the
     * appropriate `decodeICC.js` reader, populating `this.rgb`,
     * `this.A2B`, `this.B2A`, `this.Gray`, `this.B2D`, `this.D2B`,
     * metadata fields, etc.
     *
     * Performs the up-front validation that the engine cares about:
     *   - PCS must be Lab or XYZ
     *   - version must be 2 or 4
     *   - colour space must be one of GRAY / 2CLR / 3CLR / CMY / RGB /
     *     4CLR / CMYK
     *   - profile class must be prtr / mntr / scnr / spac / abst
     *
     * Unknown tag signatures are not an error — they are pushed onto
     * `this.unsuportedTags` (sic — Pr3) for diagnostic inspection.
     *
     * Per-intent fallbacks: a missing perceptual or saturation B2A/A2B
     * falls back to the colorimetric (relative) entry, and a missing
     * relative one to perceptual. A2B0 alone is a complete input profile.
     *
     * @param {Uint8Array} binary
     * @returns {boolean}  true if the profile is structurally valid.
     */
    decodeFile(binary) {
        if (!this.checkProfileExtent(binary)) {
            return false;
        }

        this.header = this.decodeHeader(binary);
        this.unsuportedTags = [];
        // Keep the corrected-name alias pointing at the fresh array so
        // both `unsuportedTags` (legacy) and `unsupportedTags` (new)
        // reflect the same `.push()`es from the tag dispatch loop.
        this.unsupportedTags = this.unsuportedTags;

        // copy down important header values
        this.version   = this.header.versionMajor;
        this.sizeBytes = this.header.profileSize;   // declared profile size in bytes
        this.pcs = this.header.pcs.trim().toUpperCase();
        this.colorSpace = this.header.space.trim().toUpperCase();

        // DeviceLink (pClass 'link') has no real PCS — the header PCS field
        // carries the OUTPUT device colour space (e.g. 'CMYK' for a
        // CMYK→CMYK link). Skip the PCS gate for links; the output space is
        // validated below when the output channel count is resolved.
        var isDeviceLink = this.header.pClass === 'link';
        if (!isDeviceLink && !(this.pcs === 'LAB' || this.pcs === 'XYZ')) {
            this.lastError = {err: 100, text: 'Unsupported PCS [' + this.pcs + ']'};
            return false;
        }

        // v3 is the v2 tag set and Lab encoding under another number.
        if (this.version === 3) { this.version = 2; }
        if (!(this.version === 2 || this.version === 4)) {
            this.lastError = {err: 101, text: 'Unsupported Profile Version [' + this.version + ']'};
            return false;
        }

        switch (this.header.space) {
            case 'GRAY':
                this.outputChannels = 1;
                this.type = eProfileType.Gray;
                break;

            case '2CLR':
                this.outputChannels = 2;
                this.type = eProfileType.Duo;
                break;

            case '3CLR':
            case 'CMY ':
            case 'RGB ':
                this.outputChannels = 3;
                // test LUTs then this will change to RGBMatrix
                this.type = eProfileType.RGBLut;
                break;

            case '4CLR':
            case 'CMYK':
                this.outputChannels = 4;
                this.type = eProfileType.CMYK; // cmyk
                break;

            case '5CLR':  this.outputChannels = 5;  this.type = eProfileType.NChannel; break;
            case '6CLR':  this.outputChannels = 6;  this.type = eProfileType.NChannel; break;
            case '7CLR':  this.outputChannels = 7;  this.type = eProfileType.NChannel; break;
            case '8CLR':  this.outputChannels = 8;  this.type = eProfileType.NChannel; break;
            case '9CLR':  this.outputChannels = 9;  this.type = eProfileType.NChannel; break;
            case 'ACLR':  this.outputChannels = 10; this.type = eProfileType.NChannel; break;
            case 'BCLR':  this.outputChannels = 11; this.type = eProfileType.NChannel; break;
            case 'CCLR':  this.outputChannels = 12; this.type = eProfileType.NChannel; break;
            case 'DCLR':  this.outputChannels = 13; this.type = eProfileType.NChannel; break;
            case 'ECLR':  this.outputChannels = 14; this.type = eProfileType.NChannel; break;
            case 'FCLR':  this.outputChannels = 15; this.type = eProfileType.NChannel; break;

            default:
                this.lastError = {err: 110, text: 'Unsupported Profile Colorspace [' + this.header.space + ']'};
                return false;
        }

        if (isDeviceLink) {
            // The space switch above resolved the INPUT side (a DeviceLink's
            // space field is its input device space). Record it, then resolve
            // the OUTPUT side from the PCS field.
            this.deviceLinkInputChannels = this.outputChannels;
            var linkOutputChannels = {
                'GRAY': 1, '2CLR': 2,
                'RGB': 3, 'CMY': 3, '3CLR': 3,
                'CMYK': 4, '4CLR': 4,
                '5CLR': 5, '6CLR': 6, '7CLR': 7, '8CLR': 8, '9CLR': 9,
                'ACLR': 10, 'BCLR': 11, 'CCLR': 12, 'DCLR': 13, 'ECLR': 14, 'FCLR': 15,
            }[this.pcs];
            if (linkOutputChannels === undefined) {
                this.lastError = {err: 111, text: 'Unsupported DeviceLink output space [' + this.pcs + ']'};
                return false;
            }
            this.outputChannels = linkOutputChannels;
            // this.type stays as resolved from the input space — Transform
            // branches on header.pClass === 'link', not on type.
        }

        this.tags = this.decodeTags(binary);

        // process common tags
        for (var i = 0; i < this.tags.length; i++) {
            var tag = this.tags[i];
            switch (tag.sig) {
                case 'rXYZ':
                    this.rgb.rXYZ = decode.XYZType(binary, tag.offset);
                    break;
                case 'gXYZ':
                    this.rgb.gXYZ = decode.XYZType(binary, tag.offset);
                    break;
                case 'bXYZ':
                    this.rgb.bXYZ = decode.XYZType(binary, tag.offset);
                    break;

                case 'rTRC':
                    this.rgb.rTRC = decode.curve(binary, tag.offset);
                    this.rgb.rTRCInv = decode.curve(binary, tag.offset, true);
                    break;
                case 'gTRC':
                    this.rgb.gTRC = decode.curve(binary, tag.offset);
                    this.rgb.gTRCInv = decode.curve(binary, tag.offset, true);
                    break;
                case 'bTRC':
                    this.rgb.bTRC = decode.curve(binary, tag.offset);
                    this.rgb.bTRCInv = decode.curve(binary, tag.offset, true);
                    break;

                case 'kTRC':
                    this.Gray.kTRC = decode.curve(binary, tag.offset);
                    this.Gray.inv_kTRC = decode.curve(binary, tag.offset, true);
                    break;

                case 'wtpt':
                    this.mediaWhitePoint = decode.XYZType(binary, tag.offset);
                    break;

                case 'A2B0': //perceptual
                    this.A2B[0] = decode.lut(binary, tag.offset);
                    break;

                case 'A2B1': //relative colorimetric
                    this.A2B[1] = decode.lut(binary, tag.offset);
                    break;

                case 'A2B2': //saturation
                    this.A2B[2] = decode.lut(binary, tag.offset);
                    break;

                case 'B2A0': //perceptual
                    this.B2A[0] = decode.lut(binary, tag.offset);
                    break;
                case 'B2A1': //relative colorimetric
                    this.B2A[1] = decode.lut(binary, tag.offset);
                    break;
                case 'B2A2': //saturation
                    this.B2A[2] = decode.lut(binary, tag.offset);
                    break;

                case 'desc':
                    this.name = decode.text(binary, tag.offset).text;
                    break;

                case 'cprt':
                    this.copyright = decode.text(binary, tag.offset).text;
                    break;
                case 'tech':
                    this.technology = this.techSignatureString(decode.chars(binary, tag.offset, 4));
                    break;
                case 'vued':
                    this.viewingConditions = decode.text(binary, tag.offset);
                    break;
                case 'targ':
                    this.characterizationTarget = decode.text(binary, tag.offset);
                    break;
                case 'bkpt':
                    this.blackPoint = decode.XYZType(binary, tag.offset);
                    break;
                case 'lumi':
                    this.luminance = decode.XYZType(binary, tag.offset);
                    break;
                case 'chad': //chromaticAdaptationTag
                    this.chromaticAdaptation = decode.s15Array(binary, tag.offset, tag.length);
                    break;
                case 'view': //viewingConditionsType
                    this.viewingConditions = decode.viewingConditions(binary, tag.offset);
                    break;
                case 'gamt':
                    // 'Gamut Tag Ignored' for now
                    break;
                case 'calt':
                    // 'Calibration Date Time Tag Ignored' for now
                    break;
                case 'chrm':
                    // chromaticityType Tag Ignored for now
                    break;
                case 'cicp':
                    // Coding-Independent Code Points (CICP) for video signal type identification Ignored for now
                    break;
                case 'clro':
                    // Colorant Order Ignored for now
                    break;
                case 'clrt':
                    // Colorant Table Ignored for now
                    break;
                case 'ciis':
                    // Colorant Table Out of Range Indicator Ignored for now
                    break;
                case 'dmnd':
                    // Device Manufacturer Description Ignored for now
                    break;
                case 'dmdd':
                    // Device Model Description Ignored for now
                    break;
                case 'meas':
                    // Measurement Type Ignored for now
                    break;
                case 'meta':
                    // Metadata Ignored for now
                    break;
                case 'ncl2':
                    // Named Color 2 Ignored for now
                    break;
                case 'resp':
                    // Output Response Ignored for now
                    break;
                case 'rig0':
                    // Perceptual Rendering Intent Gamut Ignored for now
                    break;
                case 'pre0':
                case 'pre1':
                case 'pre2':
                    // Preview 0,1,2 Ignored for now
                    break;
                case 'pseq':
                    // Profile Sequence Description Ignored for now
                    break;
                case 'psid':
                    // Profile Sequence Identifier Ignored for now
                    break;
                case 'rig2':
                    // saturationRenderingIntentGamut Ignored for now
                    break;

                case 'B2D0': //perceptual
                    this.B2D[0] = decode.multiProcessElement(binary, tag.offset);
                    break;

                case 'B2D1': //relative colorimetric
                    this.B2D[1] = decode.multiProcessElement(binary, tag.offset);
                    break;

                case 'B2D2': //saturation
                    this.B2D[2] = decode.multiProcessElement(binary, tag.offset);
                    break;

                case 'B2D3': //absolute colorimetric
                    this.B2D[3] = decode.multiProcessElement(binary, tag.offset);
                    break;

                case 'D2B0': //perceptual
                    this.D2B[0] = decode.multiProcessElement(binary, tag.offset);
                    break;

                case 'D2B1': //relative colorimetric
                    this.D2B[1] = decode.multiProcessElement(binary, tag.offset);
                    break;

                case 'D2B2': //saturation
                    this.D2B[2] = decode.multiProcessElement(binary, tag.offset);
                    break;

                case 'D2B3': //absolute colorimetric
                    this.D2B[3] = decode.multiProcessElement(binary, tag.offset);
                    break;

                case 'Info':
                    this.info = decode.text(binary, tag.offset);
                    break;

                default:
                    //console.log('Unsupported Tag [' + tag.sig + ']');
                    this.unsuportedTags.push(tag);
            }
        }

        if (this.B2A[eIntent.perceptual] === null) {
            this.B2A[eIntent.perceptual] = this.B2A[eIntent.relative];
        } // No Perceptual, use Colorimetric
        // Tag 0 alone is legal, and relative is what absolute reads too.
        if (this.B2A[eIntent.relative] === null) {
            this.B2A[eIntent.relative] = this.B2A[eIntent.perceptual];
        }
        if (this.A2B[eIntent.relative] === null) {
            this.A2B[eIntent.relative] = this.A2B[eIntent.perceptual];
        }
        if (this.B2A[eIntent.saturation] === null) {
            this.B2A[eIntent.saturation] = this.B2A[eIntent.perceptual];
        } // No Saturation - use Perceptual

        if (this.A2B[eIntent.perceptual] === null) {
            this.A2B[eIntent.perceptual] = this.A2B[eIntent.relative];
        } // No Perceptual, use Colorimetric
        if (this.A2B[eIntent.saturation] === null) {
            this.A2B[eIntent.saturation] = this.A2B[eIntent.perceptual];
        } // No Saturation - use Perceptual

        // decode.lut() returns a zero-filled sentinel for a type it cannot
        // read, which would convert every colour to black.
        var luts = this.A2B.concat(this.B2A);
        for (i = 0; i < luts.length; i++) {
            if (luts[i] && luts[i].invalid) {
                this.lastError = {err: 132, text: 'Unreadable LUT tag: ' + luts[i].errorReason};
                return false;
            }
        }

        if (!(this.header.pClass === 'prtr' ||
            this.header.pClass === 'mntr' ||
            this.header.pClass === 'scnr' ||
            this.header.pClass === 'link' ||
            this.header.pClass === 'spac' ||
            this.header.pClass === 'abst'
        )) {
            this.lastError = {err: 100, text: 'profile class not ' + this.header.pClass + ' supported'};
            return false;
        }

        return true;

    };

    // ========================================================================
    //  METADATA HELPERS
    // ========================================================================

    /**
     * Translate an ICC `tech` tag four-byte signature (e.g. `'fscn'`)
     * into a human-readable description (`'Film Scanner'`). Returns
     * `'<Unknown Technology Signature>'` if no match.
     *
     * @param {string} sig
     * @returns {string}
     */
    techSignatureString(sig) {
        var TechnologySignatures =
            [{desc: 'Film Scanner', sig: 'fscn'},
                {desc: 'Digital Camera', sig: 'dcam'},
                {desc: 'Reflective Scanner', sig: 'rscn'},
                {desc: 'Ink Jet Printer', sig: 'ijet'},
                {desc: 'Thermal Wax Printer', sig: 'twax'},
                {desc: 'Electrophotographic Printer', sig: 'epho'},
                {desc: 'Electrostatic Printer', sig: 'esta'},
                {desc: 'Dye Sublimation Printer', sig: 'dsub'},
                {desc: 'Photographic Paper Printer', sig: 'rpho'},
                {desc: 'Film Writer', sig: 'fprn'},
                {desc: 'Video Monitor', sig: 'vidm'},
                {desc: 'Video Camera', sig: 'vidc'},
                {desc: 'Projection Television', sig: 'pjtv'},
                {desc: 'Cathode Ray Tube Display', sig: 'CRT '},
                {desc: 'Passive Matrix Display', sig: 'PMD '},
                {desc: 'Active Matrix Display', sig: 'AMD '},
                {desc: 'Photo CD', sig: 'KPCD'},
                {desc: 'PhotoImageSetter', sig: 'imgs'},
                {desc: 'Gravure', sig: 'grav'},
                {desc: 'Offset Lithography', sig: 'offs'},
                {desc: 'Silkscreen', sig: 'silk'},
                {desc: 'Flexography', sig: 'flex'}];

        for (var i = 0; i < TechnologySignatures.length; i++) {
            if (TechnologySignatures[i].sig === sig) {
                return TechnologySignatures[i].desc;
            }
        }
        return '<Unknown Technology Signature>';
    };

    // ========================================================================
    //  WRITING
    // ========================================================================

    /**
     * Encode this profile as ICC bytes.
     *
     * WHAT THIS IS FOR. Until now the engine could read a profile and never
     * write one, so the only profiles it could be tested against were the ones
     * somebody shipped it -- fine for RGB and CMYK, useless above four
     * channels, where there is nothing to hand Little CMS and therefore no
     * oracle for Kernel1D, Kernel2D or KernelND at all. It also makes profile
     * editing possible: decode, change a TRC or a CLUT cell, write it back.
     *
     * SCOPE. Gray only, as ICC v2.4 with an XYZ PCS. Everything else throws
     * rather than writing a profile that silently drops the tag doing the
     * work.
     *
     * Two reasons it starts here rather than with RGB. Gray is the smallest
     * valid profile there is -- white point, one tone curve, two text tags --
     * so it proves the header, tag table and alignment with nothing else in
     * the way. And it is the one that closes a real gap: 1-channel input has
     * no oracle today.
     *
     * RGB is deliberately NOT next-by-default. The rXYZ/gXYZ/bXYZ tags hold
     * D50-ADAPTED colourants, while `RGBMatrix.matrixV4` decodes to the
     * unadapted matrix, and the decoder does not keep the tag values
     * themselves. Writing matrixV4 into those tags would produce a profile
     * that looks right, opens cleanly, and is wrong by a chromatic adaptation
     * -- which is exactly the class of bug worth refusing to guess at.
     *
     * @param {object} [opts]
     * @param {string} [opts.description]  overrides the profile description
     * @param {string} [opts.copyright]    overrides the copyright text
     * @returns {Uint8Array} ICC bytes
     */
    toICC(opts) {
        opts = opts || {};
        const space = (this.header && this.header.space || '').trim();

        if (space !== 'GRAY') {
            throw new Error('Profile.toICC: only GRAY profiles can be written so far'
                + (space ? ' (this one is "' + space + '")' : '')
                + '. Matrix and LUT-based profiles need colourant and mft2/mAB'
                + ' encoding, which is not built yet.');
        }
        // A2B/B2A are always three-element arrays, one slot per intent, and a
        // profile with no LUT tags carries [null, null, null]. Testing the
        // array itself is testing that it exists.
        const hasLut = (this.A2B || []).some(Boolean) || (this.B2A || []).some(Boolean);
        if (hasLut) {
            throw new Error('Profile.toICC: this profile carries an A2B/B2A LUT and'
                + ' LUT encoding is not built yet -- writing it would drop the tag'
                + ' that does the work.');
        }
        if (!this.Gray || !this.Gray.kTRC) {
            throw new Error('Profile.toICC: a GRAY profile needs a kTRC tone curve.');
        }

        const wtpt = this.mediaWhitePoint || encode.D50;

        // Tag order follows the ICC recommendation (alphabetical by signature),
        // which is what most writers emit and what makes two profiles of the
        // same content compare byte-for-byte.
        const tags = [
            ['cprt', encode.textType(opts.copyright || this.copyright
                || 'No copyright, generated by jsColorEngine')],
            // `desc` decodes to .name -- .description is a hand-written blurb
            // the virtual profiles carry and a loaded profile never has.
            ['desc', encode.textDescriptionType(opts.description || this.name || 'Gray')],
            ['kTRC', encode.curveType(this.Gray.kTRC)],
            ['wtpt', encode.XYZType(wtpt)],
        ];

        return encode.assemble({
            colorSpace: 'GRAY',
            profileClass: (this.header && this.header.pClass) || 'mntr',
            intent: this.intent || 0,
        }, tags);
    }

    /**
     * Build a synthetic gray profile in memory.
     *
     * FOR TESTING, AND SAYING SO. There is no virtual gray profile in
     * createVirtualProfile(), which is why 1-channel input has never had an
     * end-to-end oracle: nothing could be handed to Little CMS. This makes one
     * -- a white point and a gamma -- so both engines can be pointed at the
     * same file.
     *
     * @param {object}  [opts]
     * @param {number}  [opts.gamma=2.2]     tone curve gamma
     * @param {number[]}[opts.samples]       sampled curve instead of a gamma
     * @param {string}  [opts.description]
     * @returns {Uint8Array} ICC bytes
     */
    static createGrayICC(opts) {
        opts = opts || {};
        const kTRC = opts.samples
            ? { use: true, count: opts.samples.length, passThrough: false,
                data: opts.samples, gamma: 0, params: false, curveFn: false }
            : { use: false, count: 1, passThrough: false,
                data: false, gamma: (opts.gamma === undefined ? 2.2 : opts.gamma),
                params: false, curveFn: false };

        // SAY WHAT IT IS, IN THE FILE. These end up on disk and get opened in
        // profile inspectors; nothing about the bytes distinguishes a test
        // fixture from a profile somebody should actually assign to an image.
        // The description and copyright do.
        const tags = [
            ['cprt', encode.textType(opts.copyright || SYNTHETIC_COPYRIGHT)],
            ['desc', encode.textDescriptionType(opts.description
                || ('jsColorEngine synthetic Gray g'
                    + (opts.gamma === undefined ? 2.2 : opts.gamma)
                    + ' - test profile, not for production'))],
            ['kTRC', encode.curveType(kTRC)],
            ['wtpt', encode.XYZType(encode.D50)],
        ];

        return encode.assemble({ colorSpace: 'GRAY', profileClass: 'mntr', intent: 0 }, tags);
    }


    /**
     * Build a synthetic n-channel device profile (device -> PCS) in memory.
     *
     * FOR TESTING, AND SAYING SO. There are no 2-channel or 5-to-15-channel
     * profiles this repo can legally ship, so those kernels have never been
     * compared against another CMS. This makes one so both engines can be
     * pointed at the same file.
     *
     * WHY THE TABLE IS SMOOTH, AND WHY THAT WAS NOT THE FIRST ANSWER.
     *
     * The first version filled it with noise, on the reasoning already in
     * __tests__/interp_reference.tests.js: a smooth ramp is the worst possible
     * test of an interpolator, because getting a grid index wrong lands on a
     * neighbour holding nearly the right answer and nothing fails.
     *
     * That reasoning is correct for comparing an implementation against a
     * REFERENCE OF THE SAME SCHEME. It is wrong for comparing across ENGINES.
     * jsColorEngine interpolates n-channel input with a tetrahedral base;
     * Little CMS interpolates multilinearly on the extra axes. Both are valid
     * -- ICC does not mandate one -- and on a noise table they disagree
     * enormously, because unrelated neighbours mean there is no answer for the
     * two schemes to converge on. Measured: max 144 LSB on noise, max 6 on a
     * smooth table built from the same code.
     *
     * So the table is a plausible ink model: coverage darkens, the first two
     * channels rotate hue, and chroma falls toward black as coverage rises. It
     * is not a characterisation of anything real, but it is SMOOTH, which is
     * the property that makes a cross-engine comparison mean something.
     *
     * `opts.noise` restores the old behaviour for self-consistency testing --
     * comparing jsColorEngine's own single-colour path against its own array
     * loop, where the scheme is identical on both sides and noise is once
     * again the better choice.
     *
     * Seeded either way, so the bytes are identical on every run and every
     * machine -- these files are committed.
     *
     * L is 0..100 and a/b are held to +/-50 rather than the full +/-128:
     * outside a plausible gamut both engines are extrapolating into a corner
     * nobody ships, and a disagreement there would say nothing useful.
     *
     * GRID SIZE IS THE CALLER'S PROBLEM, and it has to be. The CLUT is
     * gridPoints^inputChannels cells, so the practical ceiling falls fast:
     * 33 points at 4 channels is 3.5M cells, but 3 points at 15 channels is
     * 43M. Pass something sane -- gridFor() below gives a default.
     *
     * @param {object}  opts
     * @param {number}  opts.channels          input channels, 2..15
     * @param {number}  [opts.gridPoints]      per axis; gridFor(channels) if omitted
     * @param {number}  [opts.seed]
     * @param {string}  [opts.description]
     * @returns {Uint8Array} ICC bytes
     */
    static createNChannelICC(opts) {
        opts = opts || {};
        const inCh = opts.channels;
        if (!(inCh >= 1 && inCh <= 15)) {
            throw new Error('Profile.createNChannelICC: channels must be 1-15, got ' + inCh);
        }
        const grid = opts.gridPoints || Profile.gridFor(inCh);
        const cells = Math.pow(grid, inCh);
        if (cells * 3 > 4e6) {
            throw new Error('Profile.createNChannelICC: ' + grid + '^' + inCh + ' x 3 = '
                + Math.round(cells * 3 / 1e6) + 'M cells is too large to be useful.'
                + ' Lower gridPoints -- see Profile.gridFor().');
        }

        // A plain LCG. Deterministic across machines and Node versions, which
        // Math.random() is not, and these files are committed.
        let state = (opts.seed === undefined ? 20260821 : opts.seed) >>> 0;
        const rnd = () => {
            state = (Math.imul(state, 1103515245) + 12345) & 0x7fffffff;
            return state / 0x7fffffff;
        };

        const CLUT = new Uint16Array(cells * 3);
        const idx = new Array(inCh);
        for (let i = 0, w = 0; i < cells; i++) {
            let L, a, b;
            if (opts.noise) {
                L = rnd() * 100; a = rnd() * 100 - 50; b = rnd() * 100 - 50;
            } else {
                // Unpack the cell index into grid coordinates. ICC order:
                // channel 0 varies SLOWEST, the last channel fastest.
                let rem = i;
                for (let d = inCh - 1; d >= 0; d--) { idx[d] = rem % grid; rem = (rem / grid) | 0; }

                // A plausible ink model. Coverage darkens; the first two
                // channels rotate hue; chroma collapses toward black as
                // coverage rises, so the far corner is dense and neutral the
                // way a real n-colour press is.
                let cov = 0;
                for (let d = 0; d < inCh; d++) cov += idx[d];
                cov /= inCh * (grid - 1);
                L = 100 * (1 - cov);
                a = 50 * Math.cos(idx[0] / (grid - 1) * Math.PI * 0.5) * (1 - cov);
                b = 50 * Math.sin(idx[1] / (grid - 1) * Math.PI * 0.5) * (1 - cov);
            }
            const lab = encode.labToU16v2(L, a, b);
            CLUT[w++] = lab[0]; CLUT[w++] = lab[1]; CLUT[w++] = lab[2];
        }

        const a2b = encode.lut16Type({
            inputChannels: inCh, outputChannels: 3, gridPoints: grid, CLUT,
        });

        // ALL THREE INTENTS, ONE TABLE. A2B0/1/2 are perceptual, relative
        // colorimetric and saturation; absolute is not a tag at all, it is
        // derived from A2B1 and the media white point at transform time.
        // Passing the same array three times makes assemble() write it once
        // and point at it three times, so no requested intent can miss and the
        // file does not triple in size.
        const tags = [
            ['A2B0', a2b],
            ['A2B1', a2b],
            ['A2B2', a2b],
        ];

        // BOTH DIRECTIONS IN ONE FILE, which is what a real device profile is.
        // It also collapses the test matrix: fifteen profiles carrying both
        // tables give every input width paired with every output width -- 225
        // combinations -- by running profile A's A2B into profile B's B2A.
        // Fifteen files, not two hundred and twenty five.
        if (opts.withB2A !== false) {
            const b2a = Profile._b2aTable(inCh, opts.b2aGrid || 17);
            tags.push(['B2A0', b2a], ['B2A1', b2a], ['B2A2', b2a]);
        }

        tags.push(
            ['cprt', encode.textType(SYNTHETIC_COPYRIGHT)],
            ['desc', encode.textDescriptionType(opts.description
                || ('jsColorEngine synthetic ' + inCh + 'CLR grid' + grid
                    + ' - test profile, not for production'))],
            ['wtpt', encode.XYZType(encode.D50)],
        );

        return encode.assemble({
            colorSpace: encode.COLOUR_SPACE_SIG[inCh],
            profileClass: 'prtr',
            pcs: 'Lab ',
            intent: 0,
        }, tags);
    }

    /**
     * A grid size that keeps the CLUT usable at this channel count.
     *
     * The table is gridPoints^channels cells, so this cannot be one number.
     * These are chosen to land between roughly 0.2M and 4M cells: fine enough
     * that the interpolator has real interior to work in, small enough to
     * commit.
     *
     * Ten channels is the honest ceiling for device -> PCS. At 15 the only
     * legal grid is 2 points per axis -- a table with no interior at all,
     * which would exercise the plumbing and say nothing about interpolation.
     * That direction is what PCS -> device (B2A, a 3-D grid with a long output
     * stride) is for.
     */
    static gridFor(channels) {
        // Fixture budget, not an industry recommendation. Real 5/6/7 A2B
        // tables are typically 9 / 7-9 / 5 pts/axis; 2-pt at 11+ is ours.
        // See docs/deepdive/SyntheticProfiles.md#what-real-profiles-actually-use
        //
        // Chosen so every file lands under ~700 KB -- these are committed, and
        // a 6 MB fixture is its own problem. grid^channels grows fast enough
        // that one step of grid is the difference between 354 KB and 6.3 MB at
        // ten channels.
        //
        // 11 AND UP GET 2 POINTS PER AXIS, which is a table with no interior:
        // every point is a corner and the interpolator has nothing to
        // interpolate. That is not a useful profile and it is not pretending
        // to be one -- it exists so the 11-to-15-channel INPUT path can be
        // exercised end to end. Accuracy at those widths is measured through
        // B2A, where the grid is 3-D and stays 17^3 however many inks there
        // are.
        const GRID = { 1: 255, 2: 33, 3: 33, 4: 17, 5: 9, 6: 7, 7: 5, 8: 4,
                       9: 3, 10: 3, 11: 2, 12: 2, 13: 2, 14: 2, 15: 2 };
        const g = GRID[channels];
        if (!g) {
            throw new Error('Profile.gridFor: no grid for ' + channels + ' channels');
        }
        return g;
    }


    /**
     * Build a synthetic n-channel profile with a PCS -> device table (B2A).
     *
     * THE DIRECTION THAT ACTUALLY MATTERS AT HIGH CHANNEL COUNTS, and the one
     * real 10-to-15-colour profiles are built for.
     *
     * A2B is device -> PCS, so its grid is gridPoints^channels and the table
     * becomes impossible above about ten channels: a 15-D A2B is only
     * encodable at 2 points per axis, which is a table with no interior. B2A
     * is the other way round -- a 3-D Lab grid with an n-channel output -- so
     * the grid stays 17^3 or 33^3 however many inks there are and only the
     * output stride grows. 33^3 x 15 is 538K cells.
     *
     * That distinction is not an implementation detail. The Lab gamut is a
     * lobed solid rather than a box, so a 3- or 4-point grid cannot describe
     * it at all, let alone resolve a gamut boundary. A2B at high channel
     * counts is preview-grade by construction; B2A is not.
     *
     * IT ALSO EXERCISES DIFFERENT CODE. 3-channel input with n-channel output
     * lands on Kernel3D's wide-output runs (fl_3_n, i_3_n) -- the same path
     * where the u16 wide-output gap was found during the v1.6 kernel work,
     * where CMYK -> 5CLR worked at 8 bits and threw at 16.
     *
     * THE TABLE IS A SMOOTH INK MODEL: darkness sets total ink, chroma and hue
     * distribute it across the channels through a cosine bump per colourant.
     * Not a characterisation of any press, but smooth in L, a and b, which is
     * the property that makes a cross-engine comparison mean anything. See
     * docs/deepdive/SyntheticProfiles.md for why smooth rather than noise.
     *
     * @param {object}  opts
     * @param {number}  opts.channels          output channels, 2..15
     * @param {number}  [opts.gridPoints=17]   per Lab axis
     * @param {boolean} [opts.withA2B]         also emit the device->PCS table
     * @param {string}  [opts.description]
     * @returns {Uint8Array} ICC bytes
     */
    static createNChannelB2AICC(opts) {
        opts = opts || {};
        const outCh = opts.channels;
        if (!(outCh >= 2 && outCh <= 15)) {
            throw new Error('Profile.createNChannelB2AICC: channels must be 2-15, got ' + outCh);
        }
        const grid = opts.gridPoints || 17;
        const cells = grid * grid * grid;

        const b2a = Profile._b2aTable(outCh, grid);

        const tags = [
            ['B2A0', b2a],
            ['B2A1', b2a],
            ['B2A2', b2a],
            ['cprt', encode.textType(SYNTHETIC_COPYRIGHT)],
            ['desc', encode.textDescriptionType(opts.description
                || ('jsColorEngine synthetic ' + outCh + 'CLR B2A grid' + grid
                    + ' - test profile, not for production'))],
            ['wtpt', encode.XYZType(encode.D50)],
        ];

        return encode.assemble({
            colorSpace: encode.COLOUR_SPACE_SIG[outCh],
            profileClass: 'prtr',
            pcs: 'Lab ',
            intent: 0,
        }, tags);
    }

    /**
     * The PCS -> device table itself, shared by both builders.
     *
     * A smooth ink model: darkness sets total ink, chroma and hue distribute
     * it across the colourants through one cosine bump each. Not a
     * characterisation of any press -- smooth in L, a and b, which is the
     * property that makes a cross-engine comparison mean anything.
     *
     * @param {number} outCh  device channels
     * @param {number} grid   per Lab axis
     * @returns {number[]} mft2 tag bytes
     */
    static _b2aTable(outCh, grid) {
        const cells = grid * grid * grid;
        const CLUT = new Uint16Array(cells * outCh);
        let w = 0;
        for (let li = 0; li < grid; li++) {
            const L = li / (grid - 1) * 100;
            for (let ai = 0; ai < grid; ai++) {
                const a = ai / (grid - 1) * 255 - 128;
                for (let bi = 0; bi < grid; bi++) {
                    const b = bi / (grid - 1) * 255 - 128;

                    // Total ink rises as the colour darkens; chroma and hue
                    // decide how it is split between the colourants.
                    const dark   = 1 - L / 100;
                    const chroma = Math.min(1, Math.sqrt(a * a + b * b) / 128);
                    const hue    = Math.atan2(b, a);

                    for (let c = 0; c < outCh; c++) {
                        // One colourant per hue, evenly spaced round the wheel,
                        // each a cosine bump so the result is smooth in a and b
                        // rather than piecewise.
                        const centre = (c / outCh) * 2 * Math.PI - Math.PI;
                        const bump   = 0.5 + 0.5 * Math.cos(hue - centre);
                        const v      = dark * (0.3 + 0.7 * chroma * bump);
                        CLUT[w++] = Math.max(0, Math.min(65535, Math.round(v * 65535)));
                    }
                }
            }
        }

        return encode.lut16Type({
            inputChannels: 3, outputChannels: outCh, gridPoints: grid, CLUT,
        });
    }

}



// ============================================================================
//  ENVIRONMENT HELPERS — module-level utilities (browser / Node / CEP)
// ============================================================================

/**
 * Node.js HTTP fetch backing `loadURL` when running outside a browser.
 * Concatenates response chunks, hands the resulting `Uint8Array` to
 * `callback(bytes, '')` on success or `callback(false, errorMsg)` on
 * failure.
 */
function nodeLoadFileFromURL(url, callback) {
    const http = require('http');
    http.get(url, (response) => {
        // Check if the request was successful
        if (response.statusCode < 200 || response.statusCode >= 300) {
            return callback(false, 'Response status was ' + response.statusCode);
        }

        const chunks = [];

        // Listen for data events
        response.on('data', (chunk) => {
            chunks.push(chunk);
        });

        // Once all the data has been received
        response.on('end', () => {
            const buffer = Buffer.concat(chunks);
            callback(new Uint8Array(buffer), '');
        });
    }).on('error', (err) => {
        callback(false, err.message);
    });
}


/**
 * Browser XHR fetch backing `loadURL`. Same callback contract as
 * `nodeLoadFileFromURL`.
 */
function XHRLoadBinary(url, onComplete) {
    var xhr = new XMLHttpRequest();
    xhr.open('GET', url, true);
    xhr.responseType = 'arraybuffer';

    xhr.onload = function(){
        if (this.status === 200) {
            // get binary data as a response
            var arrayBuffer = xhr.response;
            if (arrayBuffer) {
                var byteArray = new Uint8Array(arrayBuffer);
                onComplete(byteArray, '');
            } else {
                onComplete(false, 'Invalid arrayBuffer');
            }
        } else {
            onComplete(false, 'Server Status ' + this.status);
        }
    };

    // FIX (Pr1): the original code assigned arbitrary properties named
    // `xhr.timeout` and `xhr.error`, which the XHR API does not call
    // back into. The real handlers are `ontimeout` and `onerror`.
    // The previous wiring meant network failures and timeouts silently
    // dropped the load callback (caller hangs); also assigning a
    // function to `xhr.timeout` (which is a NUMBER property — the
    // request-timeout in ms) coerces to NaN and disables the timeout.
    xhr.ontimeout = function() {
        onComplete(false, 'Timeout');
    };

    xhr.onerror = function() {
        onComplete(false, 'XHR Error');
    };

    xhr.send();
}

/**
 * True if running inside an Adobe CEP host (Photoshop, Illustrator,
 * InDesign panels). Detected by the presence of the `window.cep`
 * global. Wrapped in try/catch because `window` itself may not exist
 * in headless / Node contexts.
 */
function isInCep(){
    try {
        if (window.cep) {
             return true;
        }
    } catch (e) {
    }
    return false;
}

/**
 * True if running under Node.js (and not via Electron's renderer or
 * similar hybrid). Detected via `process.versions.node`. Wrapped in
 * try/catch because `process` is not defined in vanilla browsers.
 */
function isInNode(){
    try {
        // Check if 'process' is defined
        if (process && process.versions && process.versions.node) {
             return true;
        }
    } catch (e) {
    }
    return false;
}

/**
 * Decode a base64 string to a `Uint8Array`. Uses Node's `Buffer` when
 * available, falls back to `window.atob` + manual byte copy in the
 * browser.
 */
function base64ToUint8Array(base64) {
    if(isInNode()){
        // In node, we can use the Buffer class
        const buffer = Buffer.from(base64, 'base64');
        return new Uint8Array(buffer);
    }
    // Decode the Base64 string to a binary string
    let binary_string = window.atob(base64);

    // Create a new Uint8Array with the same length as the binary string
    let len = binary_string.length;
    let bytes = new Uint8Array(len);

    // Convert each character in the binary string to a byte
    for (let i = 0; i < len; i++) {
        bytes[i] = binary_string.charCodeAt(i);
    }

    return bytes;
}

// FNV-1a 32-bit hash over a Uint8Array (or any byte-indexable array).
// Used to fingerprint raw ICC binary for profile equality comparison.
// Intentionally duplicated from the copy in Transform.js — Profile.js
// does not import Transform, and the function is too small to extract
// into a shared module.
//
// Only hashes bytes[0 .. declaredSize-1] where declaredSize is the
// big-endian uint32 in the first 4 bytes of every ICC profile. This
// makes the hash stable regardless of trailing null padding — a profile
// embedded in a JPEG APP2 or TIFF tag may be padded to a block boundary
// by the host application, so naively hashing the whole buffer would
// produce a different fingerprint for the same logical profile.
function _compactIccBytes(bytes) {
    if (!bytes || typeof bytes.byteOffset !== 'number' || !bytes.buffer) {
        return bytes;
    }
    if (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
        return bytes;
    }
    return new Uint8Array(bytes);
}

function _profileFnv1a32(bytes, declaredSize) {
    // ICC headers are at least 128 bytes. If declaredSize is 0, corrupted, or
    // claims more bytes than we have, fall back to hashing the whole buffer.
    var hashLength = (declaredSize >= 128 && declaredSize <= bytes.length)
        ? declaredSize
        : bytes.length;
    var hash  = 0x811c9dc5;
    var prime = 0x01000193;
    for(var byteIndex = 0; byteIndex < hashLength; byteIndex++){
        hash = Math.imul(hash ^ bytes[byteIndex], prime);
    }
    return (hash >>> 0).toString(16).padStart(8, '0');
}

module.exports = Profile;