@mirage-engine/painter 0.4.0 → 1.0.0

package/src/Painter.ts

@@ -1,36 +1,40 @@
 import * as THREE from "three";
-import { BoxStyles, TextStyles, ShaderHooks} from "./types";
-import { createBoxMaterial, updateBoxMaterial } from "./BoxGenerator";
-import { createTextTexture } from "./TextGenerator";
+import { BoxStyles, TextStyles, ShaderHooks } from "./types";
+import {
+  createBoxMaterial,
+  updateBoxMaterial,
+  setBoxUniforms,
+  BoxUniformValues,
+} from "./Box/BoxGenerator";
+import { TextGenerator } from "./Text/TextGenerator";
 
 export const Painter = {
   create(
     type: "BOX" | "TEXT",
-    styles: any,
+    styles: BoxStyles | TextStyles,
     content: string,
     width: number,
     height: number,
     quality: number = 2,
     texture: THREE.Texture | null = null,
-    shaderHooks?: ShaderHooks
+    shaderHooks?: ShaderHooks,
   ): THREE.Material {
     if (type === "BOX") {
-      return createBoxMaterial(styles as BoxStyles, width, height, texture, shaderHooks);
+      return createBoxMaterial(
+        styles as BoxStyles,
+        width,
+        height,
+        texture,
+        shaderHooks,
+      );
     } else if (type === "TEXT") {
-      const texture = createTextTexture(
+      return new TextGenerator(
         content || "",
         styles as TextStyles,
         width,
         height,
         quality,
       );
-
-      return new THREE.MeshBasicMaterial({
-        map: texture,
-        transparent: true,
-        side: THREE.FrontSide,
-        color: 0xffffff,
-      });
     }
 
     return new THREE.MeshBasicMaterial({ visible: false });
@@ -39,12 +43,12 @@ export const Painter = {
   update(
     material: THREE.Material,
     type: "BOX" | "TEXT",
-    styles: any,
+    styles: BoxStyles | TextStyles,
     content: string,
     width: number,
     height: number,
     quality: number = 2,
-    texture?: THREE.Texture | null
+    texture?: THREE.Texture | null,
   ) {
     if (type === "BOX") {
       updateBoxMaterial(
@@ -52,25 +56,24 @@ export const Painter = {
         styles as BoxStyles,
         width,
         height,
-        texture
+        texture,
       );
     } else if (type === "TEXT") {
-      const basicMat = material as THREE.MeshBasicMaterial;
-
-      if (basicMat.map) {
-        basicMat.map.dispose();
-      }
-
-      const newTexture = createTextTexture(
+      const textMat = material as TextGenerator;
+      textMat.updateText(
         content || "",
         styles as TextStyles,
         width,
         height,
         quality,
       );
-
-      basicMat.map = newTexture;
-      basicMat.needsUpdate = true;
     }
   },
+
+  forceUpdateUniforms(
+    material: THREE.ShaderMaterial,
+    values: BoxUniformValues,
+  ) {
+    setBoxUniforms(material, values);
+  },
 };

package/src/Text/FontMetricsManager.ts

@@ -0,0 +1,62 @@
+export class FontMetricsManager {
+  private static cache: Map<string, number> = new Map();
+
+  /**
+   * Calculates or retrieves the exact alphabetic baseline (in pixels) for the given font.
+   * @param font CSS font shorthand string (e.g., "400 16px Inter")
+   * @returns Baseline Y offset in pixels
+   */
+  static getBaseline(font: string): number {
+    if (this.cache.has(font)) {
+      return this.cache.get(font)!;
+    }
+
+    const baseline = this.calculateBaselineFromDOM(font);
+    this.cache.set(font, baseline);
+    return baseline;
+  }
+
+  private static calculateBaselineFromDOM(font: string): number {
+    // Return 0 when running in a non‑DOM environment (e.g., server‑side rendering)
+    if (typeof document === "undefined") return 0;
+
+    const container = document.createElement("div");
+    const span = document.createElement("span");
+    const img = document.createElement("img"); // 1×1 transparent pixel
+
+    // Hide the helper elements and apply the target font
+    container.style.visibility = "hidden";
+    container.style.position = "absolute";
+    container.style.top = "0px";
+    container.style.left = "0px";
+    container.style.font = font;
+
+    // Reset padding/margin/border to isolate pure font metrics
+    container.style.margin = "0";
+    container.style.padding = "0";
+    container.style.border = "none";
+    span.style.margin = "0";
+    span.style.padding = "0";
+    span.style.border = "none";
+    span.style.lineHeight = "normal"; // Prevent line‑height interference
+
+    // Align the 1×1 image to the baseline of the span
+    img.width = 1;
+    img.height = 1;
+    img.style.verticalAlign = "baseline";
+
+    // Assemble the DOM structure
+    span.appendChild(document.createTextNode("Hidden Text"));
+    container.appendChild(span);
+    container.appendChild(img);
+
+    document.body.appendChild(container);
+
+    // Measure the distance from the top of the span to the top of the baseline‑aligned image
+    const baseline = img.offsetTop - span.offsetTop;
+
+    document.body.removeChild(container);
+
+    return baseline;
+  }
+}

package/src/Text/TextGenerator.ts

@@ -0,0 +1,123 @@
+import * as THREE from "three";
+import { TextStyles } from "../types";
+import { FontMetricsManager } from "./FontMetricsManager";
+
+export class TextGenerator extends THREE.MeshBasicMaterial {
+  private canvas: HTMLCanvasElement;
+  private ctx: CanvasRenderingContext2D;
+  private qualityFactor: number;
+
+  constructor(text: string, styles: TextStyles, rectWidth: number, rectHeight: number, qualityFactor: number = 2) {
+    super({
+      transparent: true,
+      side: THREE.FrontSide,
+      color: 0xffffff,
+    });
+
+    this.canvas = document.createElement("canvas");
+    this.ctx = this.canvas.getContext("2d")!;
+
+    if (!this.ctx) {
+      throw new Error("[Mirage] Failed to create canvas context");
+    }
+
+    this.qualityFactor = qualityFactor;
+
+    this.map = new THREE.CanvasTexture(this.canvas);
+    this.map.colorSpace = THREE.LinearSRGBColorSpace;
+    this.map.minFilter = THREE.LinearFilter;
+    this.map.magFilter = THREE.LinearFilter;
+
+    this.updateText(text, styles, rectWidth, rectHeight);
+  }
+
+  private wrapText(text: string, maxWidth: number): string[] {
+    const forcedLines = text.split("\n");
+    const resultLines: string[] = [];
+
+    forcedLines.forEach((line) => {
+      const words = line.match(/[^\s\-]+\-?|\-|\s+/g) || [];
+
+      if (words.length === 0) {
+        resultLines.push("");
+        return;
+      }
+
+      let currentLine = words[0];
+
+      for (let i = 1; i < words.length; i++) {
+        const word = words[i];
+        const width = this.ctx.measureText(currentLine + word).width;
+
+        if (width <= maxWidth + 2) {
+          currentLine += word;
+        } else {
+          if (currentLine) resultLines.push(currentLine);
+          currentLine = word.trimStart();
+        }
+      }
+
+      if (currentLine) {
+        resultLines.push(currentLine);
+      }
+    });
+
+    return resultLines;
+  }
+
+  public updateText(text: string, styles: TextStyles, rectWidth: number, rectHeight: number, qualityFactor?: number) {
+    if (qualityFactor !== undefined) {
+      this.qualityFactor = qualityFactor;
+    }
+
+    const pixelRatio = window.devicePixelRatio || 1;
+    const scale = pixelRatio * this.qualityFactor;
+
+    const newCanvasWidth = rectWidth * scale;
+    const newCanvasHeight = rectHeight * scale;
+
+    if (this.canvas.width !== newCanvasWidth || this.canvas.height !== newCanvasHeight) {
+      this.canvas.width = newCanvasWidth;
+      this.canvas.height = newCanvasHeight;
+    } else {
+      this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    }
+
+    // Reset transform and apply scale
+    this.ctx.setTransform(scale, 0, 0, scale, 0, 0);
+
+    this.ctx.font = styles.font;
+    this.ctx.fillStyle = styles.color;
+    this.ctx.textBaseline = "alphabetic";
+    this.ctx.globalAlpha = 1;
+
+    const lines = this.wrapText(text, rectWidth);
+    const lineHeight = styles.lineHeight;
+    const baseline = FontMetricsManager.getBaseline(styles.font);
+
+    lines.forEach((line, index) => {
+      const y = index * lineHeight + baseline;
+
+      let x = 0;
+      if (styles.textAlign === "center") {
+        x = rectWidth / 2;
+      } else if (styles.textAlign === "right") {
+        x = rectWidth;
+      }
+      
+      this.ctx.textAlign = styles.textAlign as CanvasTextAlign;
+      this.ctx.fillText(line, x, y);
+    });
+
+    if (this.map) {
+      this.map.needsUpdate = true;
+    }
+  }
+
+  public dispose() {
+    if (this.map) {
+      this.map.dispose();
+    }
+    super.dispose();
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,4 @@
+declare module "*?raw" {
+  const content: string;
+  export default content;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
-export * from "./TextGenerator";
+export * from "./Text/TextGenerator";
 export * from "./types";
-export * from "./BoxGenerator";
-export * from "./Painter";
+export * from "./Box/BoxGenerator";
+export * from "./Painter";
+export * from "./tools/parser";

package/src/shaders/base/box-fragment.glsl

@@ -0,0 +1,129 @@
+varying vec2 vUv;
+uniform vec2 uSize;
+uniform vec4 uBorderRadius;
+uniform float uBorderWidth;
+uniform vec4 uBgColor;
+uniform vec4 uBorderColor;
+uniform float uOpacity;
+
+uniform int uGradientCount;
+uniform float uGradientAngle;
+uniform vec4 uGradientColors[8];
+uniform float uGradientStops[8];
+
+#INJECT_DECLARATIONS
+
+vec3 linearToSrgb(vec3 linearColor) {
+    vec3 linearPart = 12.92 * linearColor;
+    vec3 curvePart = 1.055 * pow(linearColor, vec3(1.0 / 2.4)) - 0.055;
+    vec3 switchCondition = step(vec3(0.0031308), linearColor);
+    return mix(linearPart, curvePart, switchCondition);
+}
+
+vec3 srgbToLinear(vec3 srgbColor) {
+    vec3 linearPart = srgbColor / 12.92;
+    vec3 curvePart = pow((srgbColor + vec3(0.055)) / 1.055, vec3(2.4));
+    vec3 switchCondition = step(vec3(0.04045), srgbColor);
+    return mix(linearPart, curvePart, switchCondition);
+}
+
+vec4 blendSrcOverInLinear(vec4 front, vec4 back) {
+  front.rgb = srgbToLinear(front.rgb);
+  back.rgb  = srgbToLinear(back.rgb);
+  float aOut = front.a + back.a * (1.0 - front.a);
+  float safeAlpha = max(aOut, 0.0001);
+  vec3 cOut = (front.rgb * front.a + back.rgb * back.a * (1.0 - front.a)) / safeAlpha;
+  return vec4(linearToSrgb(cOut), aOut);
+}
+
+vec4 blendSrcOver(vec4 front, vec4 back) {
+  float aOut = front.a + back.a * (1.0 - front.a);
+  float safeAlpha = max(aOut, 0.0001);
+  vec3 cOut = (front.rgb * front.a + back.rgb * back.a * (1.0 - front.a)) / safeAlpha;
+  return vec4(cOut, aOut);
+}
+
+float sdRoundedBox(vec2 p, vec2 b, float r) {
+  vec2 q = abs(p) - b + r;
+  return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - r;
+}
+
+float sdVisualBox(vec2 p, vec2 b, float r) {
+  vec2 q = abs(p) - b + r;
+  float n = 2.01; 
+  float d = pow(pow(max(q.x, 0.0), n) + pow(max(q.y, 0.0), n), 1.0/n) - r;
+  return min(max(q.x, q.y), 0.0) + d;
+}
+
+vec4 calculateGradientLayer(vec2 uv) {
+  if (uGradientCount < 2) return uGradientColors[0];
+
+  vec2 dir = vec2(sin(uGradientAngle), cos(uGradientAngle));
+  vec2 p = (uv - 0.5) * uSize;
+  float proj = dot(p, dir);
+  float L = abs(uSize.x * dir.x) + abs(uSize.y * dir.y);
+  float t = clamp((proj / L) + 0.5, 0.0, 1.0);
+  
+  vec4 color = uGradientColors[0];
+  for (int i = 1; i < 8; i++) {
+    if (i >= uGradientCount) break;
+    float prevStop = uGradientStops[i-1];
+    float currStop = uGradientStops[i];
+    
+    float factor = clamp((t - prevStop) / (currStop - prevStop + 0.00001), 0.0, 1.0);
+    color = mix(color, uGradientColors[i], factor);
+  }
+  // return vec4(linearToSrgb(color.rgb), color.a);
+  return vec4(color);
+}
+
+void main() {
+  vec2 p = (vUv - 0.5) * uSize;
+  vec2 halfSize = uSize * 0.5;
+
+  #INJECT_UV_MODIFIER
+
+  // color decision pipeline
+  vec4 baseColor = vec4(uBgColor.rgb, uBgColor.a);
+
+  if (uGradientCount > 0) {
+    vec4 gradColor = calculateGradientLayer(vUv);
+    baseColor = blendSrcOver(gradColor, baseColor);
+  }
+
+  #INJECT_BASE_COLOR
+
+  // Hybrid SDF
+  vec2 xRadii = mix(uBorderRadius.xw, uBorderRadius.yz, step(0.0, p.x));
+  float r = mix(xRadii.y, xRadii.x, step(0.0, p.y));
+  r = min(r, min(halfSize.x, halfSize.y));
+
+  float d = sdRoundedBox(p, halfSize, r);
+
+  float d_smooth = sdVisualBox(p, halfSize, r);
+  float d_visual = d_smooth / fwidth(d_smooth);
+
+  // rendering pipeline
+  float bgMask = 1.0 - smoothstep(-0.5, 0.5, d_visual);
+
+  float halfBorder = uBorderWidth * 0.5;
+  float borderD = abs(d + halfBorder) - halfBorder;
+  float borderAlpha = (1.0 - smoothstep(0.0, 1.0, borderD)) * uBorderColor.a; 
+  if (uBorderWidth <= 0.01) {
+    borderAlpha = 0.0;
+  }
+
+  // final blending (border + background) using blendSrcOver
+  vec4 borderLayer = vec4(uBorderColor.rgb, borderAlpha);
+  vec4 finalColor = blendSrcOver(borderLayer, baseColor);
+  // final color control (Tint, Noise)
+  #INJECT_COLOR_MODIFIER
+
+  float finalOpacity = finalColor.a * bgMask * uOpacity;
+  if (finalOpacity < 0.001) discard;
+
+  gl_FragColor = vec4(finalColor.rgb, finalOpacity);
+
+
+  // #include <colorspace_fragment>
+}

package/src/shaders/base/box-vertex.glsl

@@ -0,0 +1,7 @@
+varying vec2 vUv;
+varying vec4 vScreenPos;
+void main() {
+  vUv = uv;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+  vScreenPos = gl_Position;
+}

package/src/shaders/chunk/base-color-chunk.glsl

@@ -0,0 +1,2 @@
+vec4 texColor = texture2D(uTexture, resultUv);
+baseColor = blendSrcOver(baseColor, texColor);

package/src/shaders/chunk/decl-chunk.glsl

@@ -0,0 +1,4 @@
+uniform sampler2D uTexture;
+varying vec4 vScreenPos;
+uniform vec2 uTextureRepeat;
+uniform vec2 uTextureOffset;

package/src/shaders/chunk/uv-chunk.glsl

@@ -0,0 +1,3 @@
+vec2 screenUv = (vScreenPos.xy / vScreenPos.w) * 0.5 + 0.5;
+vec2 resultUv = screenUv;
+

package/src/shaders/index.ts

@@ -0,0 +1,16 @@
+import vertexShader from "./base/box-vertex.glsl?raw";
+import fragmentShader from "./base/box-fragment.glsl?raw";
+import declChunk from "./chunk/decl-chunk.glsl?raw";
+import uvChunk from "./chunk/uv-chunk.glsl?raw";
+import baseColorChunk from "./chunk/base-color-chunk.glsl?raw";
+
+export const BoxShader = {
+  vertexShader,
+  fragmentShader,
+};
+
+export const BoxChunk = {
+  declChunk,
+  uvChunk,
+  baseColorChunk,
+};

package/src/tools/parser.ts

@@ -0,0 +1,148 @@
+import * as THREE from "three";
+
+export function parsePixelValue(value: string | number): number {
+  if (typeof value === "number") return value;
+  return parseFloat(value) || 0;
+}
+
+export function parseColor(colorStr: string) {
+  if (!colorStr || colorStr === "transparent") {
+    return { color: new THREE.Color(0xffffff), alpha: 0.0 };
+  }
+
+  const rgbaMatch = colorStr.match(
+    /rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/,
+  );
+
+  if (rgbaMatch) {
+    const r = parseInt(rgbaMatch[1], 10);
+    const g = parseInt(rgbaMatch[2], 10);
+    const b = parseInt(rgbaMatch[3], 10);
+    const a = rgbaMatch[4] !== undefined ? parseFloat(rgbaMatch[4]) : 1.0;
+    return { color: new THREE.Color(`rgb(${r}, ${g}, ${b})`), alpha: a };
+  }
+  return { color: new THREE.Color(colorStr), alpha: 1.0 };
+}
+
+export function splitByComma(str: string) {
+  const result = [];
+  let current = "";
+  let depth = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i];
+    if (char === "(") depth++;
+    else if (char === ")") depth--;
+    else if (char === "," && depth === 0) {
+      result.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) result.push(current.trim());
+  return result;
+}
+
+export function parseLinearGradient(value: string | null | undefined) {
+  if (!value || typeof value !== "string" || !value.includes("linear-gradient")) return null;
+
+  const match = value.match(/linear-gradient\((.*)\)/);
+  if (!match) return null;
+
+  const content = match[1];
+  const parts = splitByComma(content);
+
+  let angle = Math.PI; // default: to bottom
+  let firstStopIndex = 0;
+
+  const firstPart = parts[0].trim();
+  if (firstPart.startsWith("to ")) {
+    if (firstPart === "to top") angle = 0;
+    else if (firstPart === "to right") angle = Math.PI / 2;
+    else if (firstPart === "to bottom") angle = Math.PI;
+    else if (firstPart === "to left") angle = Math.PI * 1.5;
+    else if (firstPart === "to top right" || firstPart === "to right top")
+      angle = Math.PI / 4;
+    else if (
+      firstPart === "to bottom right" ||
+      firstPart === "to right bottom"
+    )
+      angle = Math.PI * 0.75;
+    else if (firstPart === "to bottom left" || firstPart === "to left bottom")
+      angle = Math.PI * 1.25;
+    else if (firstPart === "to top left" || firstPart === "to left top")
+      angle = Math.PI * 1.75;
+    firstStopIndex = 1;
+  } else if (
+    firstPart.endsWith("deg") ||
+    firstPart.endsWith("rad") ||
+    firstPart.endsWith("turn")
+  ) {
+    const num = parseFloat(firstPart);
+    if (firstPart.endsWith("deg")) angle = num * (Math.PI / 180);
+    else if (firstPart.endsWith("rad")) angle = num;
+    else if (firstPart.endsWith("turn")) angle = num * Math.PI * 2;
+    firstStopIndex = 1;
+  }
+
+  const stops = [];
+  for (let i = firstStopIndex; i < parts.length; i++) {
+    if (stops.length >= 8) break;
+    const part = parts[i].trim();
+    const lastSpace = part.lastIndexOf(" ");
+    let colorStr = part;
+    let stopPos = null;
+
+    if (lastSpace !== -1 && !part.endsWith(")")) {
+      const possiblePos = part.substring(lastSpace + 1);
+      if (
+        possiblePos.endsWith("%") ||
+        possiblePos.endsWith("px") ||
+        !isNaN(parseFloat(possiblePos))
+      ) {
+        colorStr = part.substring(0, lastSpace).trim();
+        stopPos = possiblePos;
+      }
+    }
+
+    const parsedColor = parseColor(colorStr);
+    stops.push({
+      color: parsedColor.color,
+      alpha: parsedColor.alpha,
+      rawStop: stopPos,
+      stop: 0,
+    });
+  }
+
+  if (stops.length > 0) {
+    for (let i = 0; i < stops.length; i++) {
+      if (stops[i].rawStop !== null) {
+        stops[i].stop = parseFloat(stops[i].rawStop!) / 100;
+      }
+    }
+
+    if (stops[0].rawStop === null) stops[0].stop = 0.0;
+
+    if (stops.length > 1) {
+      if (stops[stops.length - 1].rawStop === null) stops[stops.length - 1].stop = 1.0;
+    }
+
+    let lastKnownIndex = 0;
+    for (let i = 1; i < stops.length; i++) {
+      if (stops[i].rawStop !== null || i === stops.length - 1) {
+        const diff = i - lastKnownIndex;
+        if (diff > 1) {
+          const startVal = stops[lastKnownIndex].stop;
+          const endVal = stops[i].stop;
+          const step = (endVal - startVal) / diff;
+          for (let j = 1; j < diff; j++) {
+            stops[lastKnownIndex + j].stop = startVal + step * j;
+          }
+        }
+        lastKnownIndex = i;
+      }
+    }
+  }
+
+  return { angle, stops };
+}

package/src/types/common.ts

@@ -1,6 +1,7 @@
 // For CanvasRenderingContext2D
 export interface TextStyles {
   font: string;
+  fontSize :string;
   color: string;
   textAlign: CanvasTextAlign;
   textBaseline: CanvasTextBaseline;
@@ -11,9 +12,11 @@ export interface TextStyles {
 
 export interface BoxStyles {
   backgroundColor: string;
+  backgroundImage: string;
+  imageSrc?: string;
+  isTraveler?: boolean;
   opacity: number;
   zIndex: number;
-
   borderRadius: string;
   borderColor: string;
   borderWidth: string;

package/dist/src/BoxGenerator.d.ts

@@ -1,4 +0,0 @@
-import { BoxStyles, ShaderHooks } from './types';
-import * as THREE from "three";
-export declare function createBoxMaterial(styles: BoxStyles, width: number, height: number, texture?: THREE.Texture | null, hooks?: ShaderHooks): THREE.ShaderMaterial;
-export declare function updateBoxMaterial(material: THREE.ShaderMaterial, styles: BoxStyles, width: number, height: number, texture?: THREE.Texture | null): void;

package/dist/src/TextGenerator.d.ts

@@ -1,3 +0,0 @@
-import { TextStyles } from './types';
-import * as THREE from "three";
-export declare function createTextTexture(text: string, styles: TextStyles, rectWidth: number, rectHeight: number, qualityFactor?: number): THREE.CanvasTexture;

package/dist/src/dev/devShader.d.ts

@@ -1,5 +0,0 @@
-export declare const isTraveler = true;
-export declare const glassHooks: {
-    uvModifier: string;
-    colorModifier: string;
-};