@aura3d/engine 1.4.4 → 1.5.0

package/dist/rendering/cartoon/CartoonRenderPreset.d.ts

@@ -0,0 +1,36 @@
+import { type CartoonMaterialStyle, type CartoonMaterialStyleOptions } from "./CartoonMaterialStyle.js";
+export interface CartoonRenderPresetOptions {
+    readonly name?: string | undefined;
+    readonly resolution?: {
+        readonly width: number;
+        readonly height: number;
+    } | undefined;
+    readonly materialStyle?: CartoonMaterialStyleOptions | undefined;
+    readonly reducedMotion?: boolean | undefined;
+    readonly reducedFlash?: boolean | undefined;
+}
+export interface CartoonRenderPresetEvidence {
+    readonly kind: "cartoon-render-preset-evidence";
+    readonly name: string;
+    readonly resolution: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly lights: readonly string[];
+    readonly shadows: {
+        readonly soft: boolean;
+        readonly contact: boolean;
+    };
+    readonly postprocess: {
+        readonly bloom: number;
+        readonly colorGrade: string;
+        readonly fogDepthCue: boolean;
+    };
+    readonly materialStyle: CartoonMaterialStyle;
+    readonly frameBudgetMs: number;
+    readonly debugOverlaysAllowedInExport: false;
+    readonly reducedMotion: boolean;
+    readonly reducedFlash: boolean;
+}
+export declare function createCartoonRenderPreset(options?: CartoonRenderPresetOptions): CartoonRenderPresetEvidence;
+//# sourceMappingURL=CartoonRenderPreset.d.ts.map

package/dist/rendering/cartoon/CartoonRenderPreset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartoonRenderPreset.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/cartoon/CartoonRenderPreset.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAEpI,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,2BAA2B,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,gCAAgC,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACxE,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7G,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,4BAA4B,EAAE,KAAK,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,0BAA+B,GAAG,2BAA2B,CAoB/G"}

package/dist/rendering/cartoon/CartoonRenderPreset.js

@@ -0,0 +1,23 @@
+import { createCartoonMaterialStyle } from "./CartoonMaterialStyle.js";
+export function createCartoonRenderPreset(options = {}) {
+    const reducedMotion = options.reducedMotion ?? false;
+    const reducedFlash = options.reducedFlash ?? false;
+    return {
+        kind: "cartoon-render-preset-evidence",
+        name: options.name ?? "moon-garden-cartoon",
+        resolution: options.resolution ?? { width: 1280, height: 720 },
+        lights: ["soft-key", "cool-rim", "set-fill", "emissive-practicals"],
+        shadows: { soft: true, contact: true },
+        postprocess: {
+            bloom: reducedFlash ? 0.08 : 0.18,
+            colorGrade: "storybook-night",
+            fogDepthCue: true
+        },
+        materialStyle: createCartoonMaterialStyle(options.materialStyle),
+        frameBudgetMs: 16.7,
+        debugOverlaysAllowedInExport: false,
+        reducedMotion,
+        reducedFlash
+    };
+}
+//# sourceMappingURL=CartoonRenderPreset.js.map

package/dist/rendering/cartoon/CartoonRenderPreset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartoonRenderPreset.js","sourceRoot":"","sources":["../../../../../packages/rendering/src/cartoon/CartoonRenderPreset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAA+D,MAAM,2BAA2B,CAAC;AAwBpI,MAAM,UAAU,yBAAyB,CAAC,UAAsC,EAAE;IAChF,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,KAAK,CAAC;IACrD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,KAAK,CAAC;IACnD,OAAO;QACL,IAAI,EAAE,gCAAgC;QACtC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,qBAAqB;QAC3C,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;QAC9D,MAAM,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,qBAAqB,CAAC;QACnE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE;QACtC,WAAW,EAAE;YACX,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;YACjC,UAAU,EAAE,iBAAiB;YAC7B,WAAW,EAAE,IAAI;SAClB;QACD,aAAa,EAAE,0BAA0B,CAAC,OAAO,CAAC,aAAa,CAAC;QAChE,aAAa,EAAE,IAAI;QACnB,4BAA4B,EAAE,KAAK;QACnC,aAAa;QACb,YAAY;KACb,CAAC;AACJ,CAAC"}

package/dist/rendering/cartoon/CartoonToonMaterial.d.ts

@@ -0,0 +1,130 @@
+import { Material, type RenderState } from "../Material.js";
+/**
+ * CartoonToonMaterial — a REAL toon / cel material for the Aura3D rendering engine.
+ *
+ * Unlike `CartoonMaterialStyle` (which is descriptive metadata consumed by nothing),
+ * this module defines an actual material that drives a dedicated GLSL program:
+ *
+ *  - It quantizes the diffuse lighting term (N·L) into a small number of discrete
+ *    bands ("ramp steps") instead of smoothly shading — the defining trait of cel
+ *    shading.
+ *  - It adds a Fresnel-style rim light that brightens silhouette edges.
+ *  - It is wired into the engine the same way `PBRMaterial` / `UnlitMaterial` are:
+ *    it extends `Material`, references a `shaderKey`, declares a `uniformSchema`, and
+ *    seeds `parameters`. The matching shader source is registered into the default
+ *    `ShaderLibrary` via `registerCartoonToonShader` (called from
+ *    `createDefaultShaderLibrary`), so any renderer that resolves materials through
+ *    the shader library can compile and bind this program.
+ *
+ * WHAT IS WIRED TO PIXELS:
+ *  - The TS ramp/quantize math (`quantizeToonBand`, `toonDiffuseRamp`, `toonRimTerm`,
+ *    `toonShadeColor`) is pure, tested, and is the exact same math the GLSL fragment
+ *    shader performs (mirrored line-for-line). Any renderer that runs the
+ *    `aura3d/cartoon-toon` program gets banded lighting + rim light on real fragments.
+ *  - The material's uniforms (band count, rim color/power, light direction, colors)
+ *    flow through the standard `Material` parameter system, so they reach the GPU
+ *    through whatever uniform-binding path the active `RenderDevice` uses for other
+ *    materials.
+ *
+ * WHAT IS NOT (yet) WIRED:
+ *  - The cartoon shader is a single-directional-light forward program. It does NOT
+ *    consume the full `u_lightData[]` array / shadow maps / IBL that the PBR shader
+ *    does. It is intentionally a focused NPR program, not a PBR superset.
+ *  - Outlines are NOT drawn by this material. Outlines come from the existing Sobel
+ *    `outlinePixels()` post-pass, which `applyCartoonRenderPreset` enables separately.
+ */
+export declare const CARTOON_TOON_SHADER_NAME = "aura3d/cartoon-toon";
+export declare const CARTOON_TOON_SHADER_MARKER = "@aura3d-shader:cartoon-toon";
+export declare const CARTOON_TOON_MIN_BANDS = 2;
+export declare const CARTOON_TOON_MAX_BANDS = 16;
+export interface CartoonToonMaterialOptions {
+    readonly name?: string;
+    /** Base albedo (RGBA), each channel in [0, 1]. */
+    readonly baseColor?: readonly [number, number, number, number];
+    /** Number of discrete lighting bands. Integer in [2, 16]. */
+    readonly bands?: number;
+    /**
+     * Ambient floor in [0, 1] — the darkest band is never fully black, so cel art
+     * keeps readable shapes in shadow. Multiplies base color in the lowest band.
+     */
+    readonly shadowFloor?: number;
+    /** Direction the key light travels FROM the surface toward the light (world space). */
+    readonly lightDirection?: readonly [number, number, number];
+    /** Key light color (RGB), each channel in [0, 1]. */
+    readonly lightColor?: readonly [number, number, number];
+    /** Rim light color (RGB), each channel in [0, 1]. */
+    readonly rimColor?: readonly [number, number, number];
+    /** Rim falloff exponent (higher = tighter rim). Finite and >= 0. */
+    readonly rimPower?: number;
+    /** Rim contribution strength in [0, 1]. */
+    readonly rimIntensity?: number;
+    /** Alpha discard threshold in [0, 1]. */
+    readonly alphaCutoff?: number;
+    readonly renderState?: Partial<RenderState>;
+}
+/**
+ * Quantize a continuous lighting term `t` in [0, 1] into one of `bands` discrete
+ * levels, returning the band's representative value in [0, 1].
+ *
+ * With `bands = 4` the output can only be 0, 1/3, 2/3, or 1 — hard stepped shading.
+ * This mirrors GLSL `floor(t * bands) / (bands - 1)` clamped so the brightest band
+ * reaches full strength.
+ */
+export declare function quantizeToonBand(t: number, bands: number): number;
+/**
+ * Toon diffuse ramp: take raw N·L (already clamped to [0, 1]), quantize it into
+ * bands, then lift the darkest band off zero by `shadowFloor` so shadows stay
+ * readable. Returns a multiplier in [shadowFloor, 1].
+ */
+export declare function toonDiffuseRamp(ndotl: number, bands: number, shadowFloor: number): number;
+/**
+ * Fresnel-style rim term: bright at grazing angles (N·V small), dark facing the
+ * camera. `ndotv` is clamped N·V. Returns rim strength in [0, rimIntensity].
+ */
+export declare function toonRimTerm(ndotv: number, rimPower: number, rimIntensity: number): number;
+export interface ToonShadeInputs {
+    readonly baseColor: readonly [number, number, number];
+    readonly ndotl: number;
+    readonly ndotv: number;
+    readonly bands: number;
+    readonly shadowFloor: number;
+    readonly lightColor: readonly [number, number, number];
+    readonly rimColor: readonly [number, number, number];
+    readonly rimPower: number;
+    readonly rimIntensity: number;
+}
+/**
+ * Full toon shade for one fragment: banded diffuse * base * light, plus additive
+ * rim. Returns linear RGB (unclamped channels are clamped to [0, 1] for output
+ * parity with the shader's final clamp). This is exactly what the GLSL `main()`
+ * computes per pixel.
+ */
+export declare function toonShadeColor(inputs: ToonShadeInputs): [number, number, number];
+export declare const CARTOON_TOON_VERTEX_SOURCE = "#version 300 es\n// @aura3d-shader:cartoon-toon\nprecision highp float;\nlayout(location = 0) in vec3 a_position;\nlayout(location = 1) in vec3 a_normal;\nlayout(location = 4) in vec4 a_color;\nuniform mat4 u_modelViewProjection;\nuniform mat4 u_modelMatrix;\nuniform mat4 u_normalMatrix;\nout vec3 v_normal;\nout vec3 v_worldPosition;\nout vec4 v_vertexColor;\nvoid main() {\n  v_normal = mat3(u_normalMatrix) * a_normal;\n  v_worldPosition = (u_modelMatrix * vec4(a_position, 1.0)).xyz;\n  v_vertexColor = a_color;\n  gl_Position = u_modelViewProjection * vec4(a_position, 1.0);\n}\n";
+export declare const CARTOON_TOON_FRAGMENT_SOURCE = "#version 300 es\n// @aura3d-shader:cartoon-toon\nprecision highp float;\nuniform vec4 u_baseColor;\nuniform float u_alphaCutoff;\nuniform float u_toonBands;\nuniform float u_toonShadowFloor;\nuniform vec3 u_toonLightDirection;\nuniform vec3 u_toonLightColor;\nuniform vec3 u_toonRimColor;\nuniform float u_toonRimPower;\nuniform float u_toonRimIntensity;\nuniform vec3 u_cameraPosition;\nin vec3 v_normal;\nin vec3 v_worldPosition;\nin vec4 v_vertexColor;\nout vec4 outColor;\n\n// Quantize t in [0,1] into u_toonBands discrete levels \u2014 mirrors quantizeToonBand().\nfloat a3dToonQuantize(float t, float bands) {\n  float steps = clamp(floor(bands + 0.5), 2.0, 16.0);\n  float clamped = clamp(t, 0.0, 1.0);\n  float level = min(steps - 1.0, floor(clamped * steps));\n  return level / (steps - 1.0);\n}\n\nvoid main() {\n  vec3 normal = normalize(v_normal);\n  if (!gl_FrontFacing) normal = -normal;\n  vec3 lightDir = normalize(u_toonLightDirection);\n  vec3 viewDir = normalize(u_cameraPosition - v_worldPosition);\n\n  float ndotl = max(dot(normal, lightDir), 0.0);\n  float ndotv = clamp(dot(normal, viewDir), 0.0, 1.0);\n\n  // Banded diffuse ramp lifted off zero by the shadow floor \u2014 mirrors toonDiffuseRamp().\n  float floorTerm = clamp(u_toonShadowFloor, 0.0, 1.0);\n  float banded = a3dToonQuantize(ndotl, u_toonBands);\n  float ramp = floorTerm + (1.0 - floorTerm) * banded;\n\n  // Fresnel rim \u2014 mirrors toonRimTerm().\n  float rim = clamp(pow(1.0 - ndotv, max(u_toonRimPower, 0.0)), 0.0, 1.0) * clamp(u_toonRimIntensity, 0.0, 1.0);\n\n  vec3 base = u_baseColor.rgb * v_vertexColor.rgb;\n  vec3 lit = base * ramp * u_toonLightColor;\n  vec3 color = clamp(lit + u_toonRimColor * rim, 0.0, 1.0);\n\n  float alpha = u_baseColor.a * v_vertexColor.a;\n  if (alpha < u_alphaCutoff) discard;\n  outColor = vec4(color, alpha);\n}\n";
+/**
+ * Register the cartoon toon shader program into a ShaderLibrary-like object.
+ * Typed structurally to avoid an import cycle with ShaderLibrary; the real
+ * `ShaderLibrary.register` matches this signature.
+ */
+export interface CartoonToonShaderRegistrar {
+    register(shader: {
+        readonly name: string;
+        readonly marker: string;
+        readonly vertex: string;
+        readonly fragment: string;
+    }): void;
+}
+export declare function registerCartoonToonShader(library: CartoonToonShaderRegistrar): void;
+export declare class CartoonToonMaterial extends Material {
+    constructor(options?: CartoonToonMaterialOptions);
+    set baseColor(value: readonly [number, number, number, number]);
+    get baseColor(): readonly [number, number, number, number];
+    set bands(value: number);
+    get bands(): number;
+    set shadowFloor(value: number);
+    get shadowFloor(): number;
+    set rimIntensity(value: number);
+    get rimIntensity(): number;
+}
+//# sourceMappingURL=CartoonToonMaterial.d.ts.map

package/dist/rendering/cartoon/CartoonToonMaterial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartoonToonMaterial.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/cartoon/CartoonToonMaterial.ts"],"names":[],"mappings":"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"}

package/dist/rendering/cartoon/CartoonToonMaterial.js

@@ -0,0 +1,303 @@
+import { Material } from "../Material.js";
+/**
+ * CartoonToonMaterial — a REAL toon / cel material for the Aura3D rendering engine.
+ *
+ * Unlike `CartoonMaterialStyle` (which is descriptive metadata consumed by nothing),
+ * this module defines an actual material that drives a dedicated GLSL program:
+ *
+ *  - It quantizes the diffuse lighting term (N·L) into a small number of discrete
+ *    bands ("ramp steps") instead of smoothly shading — the defining trait of cel
+ *    shading.
+ *  - It adds a Fresnel-style rim light that brightens silhouette edges.
+ *  - It is wired into the engine the same way `PBRMaterial` / `UnlitMaterial` are:
+ *    it extends `Material`, references a `shaderKey`, declares a `uniformSchema`, and
+ *    seeds `parameters`. The matching shader source is registered into the default
+ *    `ShaderLibrary` via `registerCartoonToonShader` (called from
+ *    `createDefaultShaderLibrary`), so any renderer that resolves materials through
+ *    the shader library can compile and bind this program.
+ *
+ * WHAT IS WIRED TO PIXELS:
+ *  - The TS ramp/quantize math (`quantizeToonBand`, `toonDiffuseRamp`, `toonRimTerm`,
+ *    `toonShadeColor`) is pure, tested, and is the exact same math the GLSL fragment
+ *    shader performs (mirrored line-for-line). Any renderer that runs the
+ *    `aura3d/cartoon-toon` program gets banded lighting + rim light on real fragments.
+ *  - The material's uniforms (band count, rim color/power, light direction, colors)
+ *    flow through the standard `Material` parameter system, so they reach the GPU
+ *    through whatever uniform-binding path the active `RenderDevice` uses for other
+ *    materials.
+ *
+ * WHAT IS NOT (yet) WIRED:
+ *  - The cartoon shader is a single-directional-light forward program. It does NOT
+ *    consume the full `u_lightData[]` array / shadow maps / IBL that the PBR shader
+ *    does. It is intentionally a focused NPR program, not a PBR superset.
+ *  - Outlines are NOT drawn by this material. Outlines come from the existing Sobel
+ *    `outlinePixels()` post-pass, which `applyCartoonRenderPreset` enables separately.
+ */
+export const CARTOON_TOON_SHADER_NAME = "aura3d/cartoon-toon";
+export const CARTOON_TOON_SHADER_MARKER = "@aura3d-shader:cartoon-toon";
+export const CARTOON_TOON_MIN_BANDS = 2;
+export const CARTOON_TOON_MAX_BANDS = 16;
+/* ------------------------------------------------------------------------- *
+ * Pure ramp / quantize math.
+ *
+ * These functions are the single source of truth for the toon lighting model.
+ * The GLSL fragment shader below performs the identical computation, so testing
+ * these functions validates the actual pixel math (modulo float precision).
+ * ------------------------------------------------------------------------- */
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/**
+ * Quantize a continuous lighting term `t` in [0, 1] into one of `bands` discrete
+ * levels, returning the band's representative value in [0, 1].
+ *
+ * With `bands = 4` the output can only be 0, 1/3, 2/3, or 1 — hard stepped shading.
+ * This mirrors GLSL `floor(t * bands) / (bands - 1)` clamped so the brightest band
+ * reaches full strength.
+ */
+export function quantizeToonBand(t, bands) {
+    const steps = Math.max(CARTOON_TOON_MIN_BANDS, Math.min(CARTOON_TOON_MAX_BANDS, Math.floor(bands)));
+    const clamped = clamp01(t);
+    // floor into [0, steps-1], then normalize so the top band maps to exactly 1.
+    const level = Math.min(steps - 1, Math.floor(clamped * steps));
+    return level / (steps - 1);
+}
+/**
+ * Toon diffuse ramp: take raw N·L (already clamped to [0, 1]), quantize it into
+ * bands, then lift the darkest band off zero by `shadowFloor` so shadows stay
+ * readable. Returns a multiplier in [shadowFloor, 1].
+ */
+export function toonDiffuseRamp(ndotl, bands, shadowFloor) {
+    const floor = clamp01(shadowFloor);
+    const banded = quantizeToonBand(clamp01(ndotl), bands);
+    return floor + (1 - floor) * banded;
+}
+/**
+ * Fresnel-style rim term: bright at grazing angles (N·V small), dark facing the
+ * camera. `ndotv` is clamped N·V. Returns rim strength in [0, rimIntensity].
+ */
+export function toonRimTerm(ndotv, rimPower, rimIntensity) {
+    const power = Number.isFinite(rimPower) && rimPower >= 0 ? rimPower : 2;
+    const intensity = clamp01(rimIntensity);
+    const fresnel = Math.pow(1 - clamp01(ndotv), power);
+    return clamp01(fresnel) * intensity;
+}
+/**
+ * Full toon shade for one fragment: banded diffuse * base * light, plus additive
+ * rim. Returns linear RGB (unclamped channels are clamped to [0, 1] for output
+ * parity with the shader's final clamp). This is exactly what the GLSL `main()`
+ * computes per pixel.
+ */
+export function toonShadeColor(inputs) {
+    const ramp = toonDiffuseRamp(inputs.ndotl, inputs.bands, inputs.shadowFloor);
+    const rim = toonRimTerm(inputs.ndotv, inputs.rimPower, inputs.rimIntensity);
+    const out = [0, 0, 0];
+    for (let i = 0; i < 3; i += 1) {
+        const lit = inputs.baseColor[i] * ramp * inputs.lightColor[i];
+        const rimContribution = inputs.rimColor[i] * rim;
+        out[i] = clamp01(lit + rimContribution);
+    }
+    return out;
+}
+/* ------------------------------------------------------------------------- *
+ * GLSL program. The fragment shader mirrors the TS math above.
+ * Registered into the default ShaderLibrary by `registerCartoonToonShader`.
+ * ------------------------------------------------------------------------- */
+export const CARTOON_TOON_VERTEX_SOURCE = `#version 300 es
+// ${CARTOON_TOON_SHADER_MARKER}
+precision highp float;
+layout(location = 0) in vec3 a_position;
+layout(location = 1) in vec3 a_normal;
+layout(location = 4) in vec4 a_color;
+uniform mat4 u_modelViewProjection;
+uniform mat4 u_modelMatrix;
+uniform mat4 u_normalMatrix;
+out vec3 v_normal;
+out vec3 v_worldPosition;
+out vec4 v_vertexColor;
+void main() {
+  v_normal = mat3(u_normalMatrix) * a_normal;
+  v_worldPosition = (u_modelMatrix * vec4(a_position, 1.0)).xyz;
+  v_vertexColor = a_color;
+  gl_Position = u_modelViewProjection * vec4(a_position, 1.0);
+}
+`;
+export const CARTOON_TOON_FRAGMENT_SOURCE = `#version 300 es
+// ${CARTOON_TOON_SHADER_MARKER}
+precision highp float;
+uniform vec4 u_baseColor;
+uniform float u_alphaCutoff;
+uniform float u_toonBands;
+uniform float u_toonShadowFloor;
+uniform vec3 u_toonLightDirection;
+uniform vec3 u_toonLightColor;
+uniform vec3 u_toonRimColor;
+uniform float u_toonRimPower;
+uniform float u_toonRimIntensity;
+uniform vec3 u_cameraPosition;
+in vec3 v_normal;
+in vec3 v_worldPosition;
+in vec4 v_vertexColor;
+out vec4 outColor;
+
+// Quantize t in [0,1] into u_toonBands discrete levels — mirrors quantizeToonBand().
+float a3dToonQuantize(float t, float bands) {
+  float steps = clamp(floor(bands + 0.5), 2.0, 16.0);
+  float clamped = clamp(t, 0.0, 1.0);
+  float level = min(steps - 1.0, floor(clamped * steps));
+  return level / (steps - 1.0);
+}
+
+void main() {
+  vec3 normal = normalize(v_normal);
+  if (!gl_FrontFacing) normal = -normal;
+  vec3 lightDir = normalize(u_toonLightDirection);
+  vec3 viewDir = normalize(u_cameraPosition - v_worldPosition);
+
+  float ndotl = max(dot(normal, lightDir), 0.0);
+  float ndotv = clamp(dot(normal, viewDir), 0.0, 1.0);
+
+  // Banded diffuse ramp lifted off zero by the shadow floor — mirrors toonDiffuseRamp().
+  float floorTerm = clamp(u_toonShadowFloor, 0.0, 1.0);
+  float banded = a3dToonQuantize(ndotl, u_toonBands);
+  float ramp = floorTerm + (1.0 - floorTerm) * banded;
+
+  // Fresnel rim — mirrors toonRimTerm().
+  float rim = clamp(pow(1.0 - ndotv, max(u_toonRimPower, 0.0)), 0.0, 1.0) * clamp(u_toonRimIntensity, 0.0, 1.0);
+
+  vec3 base = u_baseColor.rgb * v_vertexColor.rgb;
+  vec3 lit = base * ramp * u_toonLightColor;
+  vec3 color = clamp(lit + u_toonRimColor * rim, 0.0, 1.0);
+
+  float alpha = u_baseColor.a * v_vertexColor.a;
+  if (alpha < u_alphaCutoff) discard;
+  outColor = vec4(color, alpha);
+}
+`;
+export function registerCartoonToonShader(library) {
+    library.register({
+        name: CARTOON_TOON_SHADER_NAME,
+        marker: CARTOON_TOON_SHADER_MARKER,
+        vertex: CARTOON_TOON_VERTEX_SOURCE,
+        fragment: CARTOON_TOON_FRAGMENT_SOURCE
+    });
+}
+function identityMatrix() {
+    return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+}
+function validateUnit(value, label) {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new RangeError(`CartoonToonMaterial ${label} must be finite and within [0, 1]`);
+    }
+}
+function validateColor4(value, label) {
+    if (value.length !== 4 || value.some((c) => !Number.isFinite(c) || c < 0 || c > 1)) {
+        throw new RangeError(`CartoonToonMaterial ${label} must contain four finite values in [0, 1]`);
+    }
+}
+function validateColor3(value, label) {
+    if (value.length !== 3 || value.some((c) => !Number.isFinite(c) || c < 0 || c > 1)) {
+        throw new RangeError(`CartoonToonMaterial ${label} must contain three finite values in [0, 1]`);
+    }
+}
+function validateFiniteVec3(value, label) {
+    if (value.length !== 3 || value.some((c) => !Number.isFinite(c))) {
+        throw new RangeError(`CartoonToonMaterial ${label} must contain three finite values`);
+    }
+}
+export class CartoonToonMaterial extends Material {
+    constructor(options = {}) {
+        const baseColor = options.baseColor ?? [0.92, 0.58, 0.16, 1];
+        const lightDirection = options.lightDirection ?? [0.3, 0.8, 0.5];
+        const lightColor = options.lightColor ?? [1, 1, 1];
+        const rimColor = options.rimColor ?? [0.6, 0.7, 1];
+        const bands = options.bands ?? 4;
+        const shadowFloor = options.shadowFloor ?? 0.35;
+        const rimPower = options.rimPower ?? 3;
+        const rimIntensity = options.rimIntensity ?? 0.5;
+        const alphaCutoff = options.alphaCutoff ?? 0;
+        validateColor4(baseColor, "baseColor");
+        validateFiniteVec3(lightDirection, "lightDirection");
+        if (Math.hypot(...lightDirection) <= 0) {
+            throw new RangeError("CartoonToonMaterial lightDirection must be non-zero");
+        }
+        validateColor3(lightColor, "lightColor");
+        validateColor3(rimColor, "rimColor");
+        if (!Number.isInteger(bands) || bands < CARTOON_TOON_MIN_BANDS || bands > CARTOON_TOON_MAX_BANDS) {
+            throw new RangeError(`CartoonToonMaterial bands must be an integer in [${CARTOON_TOON_MIN_BANDS}, ${CARTOON_TOON_MAX_BANDS}]`);
+        }
+        validateUnit(shadowFloor, "shadowFloor");
+        if (!Number.isFinite(rimPower) || rimPower < 0) {
+            throw new RangeError("CartoonToonMaterial rimPower must be finite and non-negative");
+        }
+        validateUnit(rimIntensity, "rimIntensity");
+        validateUnit(alphaCutoff, "alphaCutoff");
+        super({
+            name: options.name ?? "cartoon-toon",
+            shaderKey: CARTOON_TOON_SHADER_NAME,
+            renderState: options.renderState,
+            parameters: {
+                u_baseColor: baseColor,
+                u_alphaCutoff: alphaCutoff,
+                u_toonBands: bands,
+                u_toonShadowFloor: shadowFloor,
+                u_toonLightDirection: lightDirection,
+                u_toonLightColor: lightColor,
+                u_toonRimColor: rimColor,
+                u_toonRimPower: rimPower,
+                u_toonRimIntensity: rimIntensity,
+                u_cameraPosition: [0, 0, 0],
+                u_modelViewProjection: identityMatrix(),
+                u_modelMatrix: identityMatrix(),
+                u_normalMatrix: identityMatrix()
+            },
+            requiredAttributes: ["a_position", "a_normal"],
+            uniformSchema: [
+                { name: "u_baseColor", kind: "vec4" },
+                { name: "u_alphaCutoff", kind: "float" },
+                { name: "u_toonBands", kind: "float" },
+                { name: "u_toonShadowFloor", kind: "float" },
+                { name: "u_toonLightDirection", kind: "vec3" },
+                { name: "u_toonLightColor", kind: "vec3" },
+                { name: "u_toonRimColor", kind: "vec3" },
+                { name: "u_toonRimPower", kind: "float" },
+                { name: "u_toonRimIntensity", kind: "float" },
+                { name: "u_cameraPosition", kind: "vec3" },
+                { name: "u_modelViewProjection", kind: "mat4" },
+                { name: "u_modelMatrix", kind: "mat4" },
+                { name: "u_normalMatrix", kind: "mat4" }
+            ]
+        });
+    }
+    set baseColor(value) {
+        validateColor4(value, "baseColor");
+        this.setParameter("u_baseColor", value);
+    }
+    get baseColor() {
+        return this.getParameter("u_baseColor");
+    }
+    set bands(value) {
+        if (!Number.isInteger(value) || value < CARTOON_TOON_MIN_BANDS || value > CARTOON_TOON_MAX_BANDS) {
+            throw new RangeError(`CartoonToonMaterial bands must be an integer in [${CARTOON_TOON_MIN_BANDS}, ${CARTOON_TOON_MAX_BANDS}]`);
+        }
+        this.setParameter("u_toonBands", value);
+    }
+    get bands() {
+        return this.getParameter("u_toonBands");
+    }
+    set shadowFloor(value) {
+        validateUnit(value, "shadowFloor");
+        this.setParameter("u_toonShadowFloor", value);
+    }
+    get shadowFloor() {
+        return this.getParameter("u_toonShadowFloor");
+    }
+    set rimIntensity(value) {
+        validateUnit(value, "rimIntensity");
+        this.setParameter("u_toonRimIntensity", value);
+    }
+    get rimIntensity() {
+        return this.getParameter("u_toonRimIntensity");
+    }
+}
+//# sourceMappingURL=CartoonToonMaterial.js.map

package/dist/rendering/cartoon/CartoonToonMaterial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartoonToonMaterial.js","sourceRoot":"","sources":["../../../../../packages/rendering/src/cartoon/CartoonToonMaterial.ts"],"names":[],"mappings":"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"}

package/dist/rendering/cartoon/CartoonVisualQuality.d.ts

@@ -0,0 +1,28 @@
+import { type FrameVisualMetrics, type FrameVisualQualityThresholds } from "../FrameVisualMetrics.js";
+export interface CartoonFrameVisualInput {
+    readonly id: string;
+    readonly metrics: FrameVisualMetrics;
+    readonly characterCount?: number | undefined;
+    readonly captionOccluded?: boolean | undefined;
+    readonly routeChromeVisible?: boolean | undefined;
+    readonly debugOverlayVisible?: boolean | undefined;
+}
+export interface CartoonFrameVisualQuality {
+    readonly id: string;
+    readonly ok: boolean;
+    readonly failures: readonly string[];
+}
+export interface CartoonVisualQualityReport {
+    readonly kind: "cartoon-visual-quality";
+    readonly ok: boolean;
+    readonly frames: readonly CartoonFrameVisualQuality[];
+    readonly visibleCharacterCount: number;
+    readonly blockers: readonly string[];
+}
+export interface CartoonVisualQualityOptions {
+    readonly thresholds?: FrameVisualQualityThresholds | undefined;
+    readonly minVisibleCharacters?: number | undefined;
+}
+export declare function createCartoonVisualQualityReport(frames: readonly CartoonFrameVisualInput[], options?: CartoonVisualQualityOptions): CartoonVisualQualityReport;
+export declare const defaultCartoonVisualQualityThresholds: FrameVisualQualityThresholds;
+//# sourceMappingURL=CartoonVisualQuality.d.ts.map

package/dist/rendering/cartoon/CartoonVisualQuality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartoonVisualQuality.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/cartoon/CartoonVisualQuality.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,kBAAkB,EAAE,KAAK,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAElI,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACpD;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACtD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,4BAA4B,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpD;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,SAAS,uBAAuB,EAAE,EAC1C,OAAO,GAAE,2BAAgC,GACxC,0BAA0B,CA0B5B;AAED,eAAO,MAAM,qCAAqC,EAAE,4BASnD,CAAC"}

package/dist/rendering/cartoon/CartoonVisualQuality.js

@@ -0,0 +1,39 @@
+import { evaluateFrameVisualQuality } from "../FrameVisualMetrics.js";
+export function createCartoonVisualQualityReport(frames, options = {}) {
+    const thresholds = options.thresholds ?? defaultCartoonVisualQualityThresholds;
+    const frameResults = frames.map((frame) => {
+        const base = evaluateFrameVisualQuality(frame.metrics, thresholds);
+        const failures = [
+            ...base.failures,
+            frame.captionOccluded ? "caption occludes important action" : undefined,
+            frame.routeChromeVisible ? "route chrome is visible" : undefined,
+            frame.debugOverlayVisible ? "debug overlay is visible" : undefined
+        ].filter((failure) => Boolean(failure));
+        return { id: frame.id, ok: failures.length === 0, failures };
+    });
+    const visibleCharacterCount = Math.max(0, ...frames.map((frame) => frame.characterCount ?? 0));
+    const blockers = [
+        ...frameResults.flatMap((frame) => frame.failures.map((failure) => `${frame.id}: ${failure}`)),
+        visibleCharacterCount < (options.minVisibleCharacters ?? 2)
+            ? `visibleCharacterCount ${visibleCharacterCount} < ${options.minVisibleCharacters ?? 2}`
+            : undefined
+    ].filter((blocker) => Boolean(blocker));
+    return {
+        kind: "cartoon-visual-quality",
+        ok: blockers.length === 0,
+        frames: frameResults,
+        visibleCharacterCount,
+        blockers
+    };
+}
+export const defaultCartoonVisualQualityThresholds = {
+    minNonDarkRatio: 0.08,
+    minSalientRatio: 0.035,
+    minOccupiedAreaRatio: 0.08,
+    minOccupiedQuadrants: 2,
+    minColorBuckets: 6,
+    maxDominantBucketRatio: 0.92,
+    maxFlatPixelRatio: 0.98,
+    minLocalContrastRatio: 0.002
+};
+//# sourceMappingURL=CartoonVisualQuality.js.map

package/dist/rendering/cartoon/CartoonVisualQuality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartoonVisualQuality.js","sourceRoot":"","sources":["../../../../../packages/rendering/src/cartoon/CartoonVisualQuality.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAA8D,MAAM,0BAA0B,CAAC;AA8BlI,MAAM,UAAU,gCAAgC,CAC9C,MAA0C,EAC1C,UAAuC,EAAE;IAEzC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,qCAAqC,CAAC;IAC/E,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAA6B,EAAE;QACnE,MAAM,IAAI,GAAG,0BAA0B,CAAC,KAAK,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACnE,MAAM,QAAQ,GAAG;YACf,GAAG,IAAI,CAAC,QAAQ;YAChB,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,mCAAmC,CAAC,CAAC,CAAC,SAAS;YACvE,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,SAAS;YAChE,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,SAAS;SACnE,CAAC,MAAM,CAAC,CAAC,OAAO,EAAqB,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3D,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC/D,CAAC,CAAC,CAAC;IACH,MAAM,qBAAqB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/F,MAAM,QAAQ,GAAG;QACf,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,EAAE,KAAK,OAAO,EAAE,CAAC,CAAC;QAC9F,qBAAqB,GAAG,CAAC,OAAO,CAAC,oBAAoB,IAAI,CAAC,CAAC;YACzD,CAAC,CAAC,yBAAyB,qBAAqB,MAAM,OAAO,CAAC,oBAAoB,IAAI,CAAC,EAAE;YACzF,CAAC,CAAC,SAAS;KACd,CAAC,MAAM,CAAC,CAAC,OAAO,EAAqB,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3D,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,EAAE,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC;QACzB,MAAM,EAAE,YAAY;QACpB,qBAAqB;QACrB,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,qCAAqC,GAAiC;IACjF,eAAe,EAAE,IAAI;IACrB,eAAe,EAAE,KAAK;IACtB,oBAAoB,EAAE,IAAI;IAC1B,oBAAoB,EAAE,CAAC;IACvB,eAAe,EAAE,CAAC;IAClB,sBAAsB,EAAE,IAAI;IAC5B,iBAAiB,EAAE,IAAI;IACvB,qBAAqB,EAAE,KAAK;CAC7B,CAAC"}