Function parseTransformMatrix

packages/engine/src/utils/alphaBlit.ts:920–960

(css: string)

 * flattening their scene rather than failing it.
 */
export function parseTransformMatrix(css: string): number[] | null {
  if (!css || css === "none") return null;

  const match2d = css.match(
    /^matrix\(\s*([^,]+),\s*([^,]+),\s*([^,]+),\s*([^,]+),\s*([^,]+),\s*([^,)]+)\s*\)$/,
  );
  if (match2d) {
    const values = match2d.slice(1, 7).map(Number);
    if (!values.every(Number.isFinite)) return null;
    return values;
  }

  const match3d = css.match(/^matrix3d\(\s*([^)]+)\)$/);
  if (match3d) {
    const raw = match3d[1];
    if (!raw) return null;
    const parts = raw.split(",").map((s) => Number(s.trim()));
    if (parts.length !== 16 || !parts.every(Number.isFinite)) return null;
    // 3D-significance check: a flat 2D transform expressed as matrix3d has
    // a3=b3=c1=c2=d1=d2=d3=0, c3=1, d4=1. Any deviation means the composition
    // is using real 3D (perspective, rotateX/Y) which the engine path can't
    // represent — we project to 2D and the visual will silently drop depth.
    // Warn once per process so authors don't get a misleading "looks fine in
    // studio, broken in render" experience without any signal. Z translation
    // (c4 = parts[14]) is intentionally dropped by the 2D projection below
    // and does NOT trigger this warning — that's the GSAP `force3D: true`
    // happy path.
    warnIfZSignificant(parts);
    // Extract column-major 2D affine: m11, m12, m21, m22, m41, m42.
    return [
      parts[0] as number,
      parts[1] as number,
      parts[4] as number,
      parts[5] as number,
      parts[12] as number,
      parts[13] as number,
    ];
  }

  return null;
}

let warnedZSignificant = false;
const Z_EPSILON = 1e-6;