@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/shader-kits/index.mjs

@@ -0,0 +1,773 @@
+const CUSTOM_SHADER_SURFACE = Object.freeze([
+  'createCustom',
+  'setUniform',
+  'setCustomTexture',
+  'unload',
+]);
+
+const COMMON_SHADER_KIT_NON_GOALS = Object.freeze([
+  'shader graph authoring',
+  'imported shader asset pipelines',
+]);
+
+const SHADER_KIT_DEFINITIONS = Object.freeze({
+  hologram: createHologramDefinition(),
+  dissolve: createDissolveDefinition(),
+  foliageWind: createFoliageWindDefinition(),
+  rimAccent: createRimAccentDefinition(),
+});
+
+const SHADER_KIT_IDS = Object.freeze(Object.keys(SHADER_KIT_DEFINITIONS));
+
+export { SHADER_KIT_IDS };
+
+export function listShaderKitIds() {
+  return [...SHADER_KIT_IDS];
+}
+
+export function listShaderKitDefinitions() {
+  return SHADER_KIT_IDS.map((id) => getShaderKitDefinition(id));
+}
+
+export function getShaderKitDefinition(id) {
+  const definition = resolveShaderKitDefinition(id);
+  return definition ? toPublicShaderKitDefinition(definition) : null;
+}
+
+export function normalizeShaderKitMaterialSpec(spec) {
+  if (!isPlainObject(spec)) {
+    throw new TypeError('Shader kit material spec must be an object');
+  }
+  const presetId = typeof spec.preset === 'string'
+    ? spec.preset
+    : (typeof spec.presetId === 'string' ? spec.presetId : '');
+  const definition = resolveShaderKitDefinition(presetId);
+  if (!definition) {
+    throw new Error(`Unknown shader kit preset: ${presetId}`);
+  }
+  const normalizedUniforms = buildInitialState(definition, spec.uniforms);
+  const normalizedTextures = normalizeTextureBindings(definition, spec);
+  return {
+    preset: definition.id,
+    uniforms: cloneUniformObject(normalizedUniforms),
+    textures: cloneTextureBindings(normalizedTextures),
+  };
+}
+
+export function createShaderKitMaterial(aura, spec) {
+  const normalizedSpec = normalizeShaderKitMaterialSpec(spec);
+  const definition = resolveShaderKitDefinition(normalizedSpec.preset);
+  return createShaderKitFromNormalizedSpec(aura, definition, normalizedSpec);
+}
+
+export function createShaderKit(aura, presetId, options = {}) {
+  if (!isPlainObject(options)) {
+    throw new TypeError('Shader kit options must be an object when provided');
+  }
+  return createShaderKitMaterial(aura, {
+    preset: presetId,
+    ...options,
+  });
+}
+
+function createShaderKitFromNormalizedSpec(aura, definition, normalizedSpec) {
+  assertCustomMaterialSurface(aura);
+  const createOptions = {
+    vertex: definition.vertex,
+    fragment: definition.fragment,
+    uniforms: uniformTypeRecord(definition.uniformSchema),
+  };
+  if (definition.textureSlots.length === 1 && definition.textureSlots[0] === 'texture') {
+    createOptions.texture = true;
+  } else if (definition.textureSlots.length > 0) {
+    createOptions.textures = [...definition.textureSlots];
+  }
+
+  const handle = aura.material.createCustom(createOptions);
+  if (!Number.isInteger(handle) || handle <= 0) {
+    throw new Error(`Shader kit ${definition.id} did not return a valid material handle`);
+  }
+
+  const kit = createKitController(
+    aura,
+    definition,
+    handle,
+    normalizedSpec.uniforms,
+    normalizedSpec.textures,
+  );
+
+  try {
+    kit.apply(normalizedSpec.uniforms);
+    for (const [slotName, texturePath] of Object.entries(normalizedSpec.textures || {})) {
+      if (texturePath != null) {
+        kit.setTexture(slotName, texturePath);
+      }
+    }
+  } catch (error) {
+    safeUnload(aura, handle);
+    throw error;
+  }
+
+  return kit;
+}
+
+export function createHologramShaderKit(aura, options = {}) {
+  return createShaderKit(aura, 'hologram', options);
+}
+
+export function createDissolveShaderKit(aura, options = {}) {
+  return createShaderKit(aura, 'dissolve', options);
+}
+
+export function createFoliageWindShaderKit(aura, options = {}) {
+  return createShaderKit(aura, 'foliageWind', options);
+}
+
+export function createRimAccentShaderKit(aura, options = {}) {
+  return createShaderKit(aura, 'rimAccent', options);
+}
+
+function createKitController(aura, definition, handle, initialState, initialTextureBindings) {
+  let destroyed = false;
+  const state = { ...initialState };
+  const textureBindings = cloneTextureBindings(initialTextureBindings);
+
+  const controller = {
+    id: definition.id,
+    label: definition.label,
+    handle,
+    materialHandle: handle,
+    getDefinition() {
+      return toPublicShaderKitDefinition(definition);
+    },
+    apply(values = {}) {
+      ensureNotDestroyed(destroyed, definition.id);
+      if (!isPlainObject(values)) {
+        throw new TypeError(`Shader kit ${definition.id} apply(values) expects an object`);
+      }
+
+      for (const [name, value] of Object.entries(values)) {
+        const uniform = definition.uniformSchema[name];
+        if (!uniform) {
+          throw new Error(`Unknown shader kit uniform for ${definition.id}: ${name}`);
+        }
+        const normalized = uniform.normalize(value);
+        state[name] = cloneUniformValue(normalized);
+        assertMutationOk(
+          aura.material.setUniform(handle, name, normalized),
+          `setUniform(${name})`,
+        );
+      }
+      return controller.getState();
+    },
+    tick(dt) {
+      ensureNotDestroyed(destroyed, definition.id);
+      if (!definition.timeUniform) {
+        return controller.getState();
+      }
+      const step = Number.isFinite(dt) ? Number(dt) : 0;
+      const nextTime = Number(state[definition.timeUniform] || 0) + step;
+      controller.apply({ [definition.timeUniform]: nextTime });
+      return controller.getState();
+    },
+    setTexture(slotOrPath, maybePath) {
+      ensureNotDestroyed(destroyed, definition.id);
+      if (definition.textureSlots.length === 0) {
+        throw new Error(`Shader kit ${definition.id} does not declare custom textures`);
+      }
+      if (definition.textureSlots.length === 1 && arguments.length === 1) {
+        const slotName = definition.textureSlots[0];
+        const texturePath = normalizeTexturePath(slotOrPath);
+        assertMutationOk(
+          aura.material.setCustomTexture(handle, texturePath),
+          'setCustomTexture(texture)',
+        );
+        textureBindings[slotName] = texturePath;
+        return controller.getState();
+      }
+      if (arguments.length !== 2) {
+        throw new TypeError(
+          `Shader kit ${definition.id} setTexture(slot, path) requires an explicit slot and path`,
+        );
+      }
+      const slotName = String(slotOrPath || '').trim();
+      if (!slotName) {
+        throw new TypeError(`Shader kit ${definition.id} requires a non-empty texture slot`);
+      }
+      const texturePath = normalizeTexturePath(maybePath);
+      assertMutationOk(
+        aura.material.setCustomTexture(handle, slotName, texturePath),
+        `setCustomTexture(${slotName})`,
+      );
+      textureBindings[slotName] = texturePath;
+      return controller.getState();
+    },
+    getState() {
+      return {
+        id: definition.id,
+        label: definition.label,
+        preset: definition.id,
+        handle,
+        materialHandle: handle,
+        uniforms: cloneUniformObject(state),
+        textures: [...definition.textureSlots],
+        textureBindings: cloneTextureBindings(textureBindings),
+        destroyed,
+      };
+    },
+    toMaterialSpec() {
+      ensureNotDestroyed(destroyed, definition.id);
+      return {
+        preset: definition.id,
+        uniforms: cloneUniformObject(state),
+        textures: cloneTextureBindings(textureBindings),
+      };
+    },
+    destroy() {
+      if (destroyed) return false;
+      safeUnload(aura, handle);
+      destroyed = true;
+      return true;
+    },
+  };
+
+  if (definition.timeUniform) {
+    controller.setTime = (value) => controller.apply({ [definition.timeUniform]: value });
+  }
+  if (definition.id === 'dissolve') {
+    controller.setProgress = (value) => controller.apply({ progress: value });
+  }
+  if (definition.id === 'hologram') {
+    controller.setEdgeColor = (value) => controller.apply({ edgeColor: value });
+  }
+  if (definition.id === 'rimAccent') {
+    controller.setRim = (value) => controller.apply(value);
+  }
+
+  return controller;
+}
+
+function buildInitialState(definition, authoredUniforms) {
+  const overrides = isPlainObject(authoredUniforms) ? authoredUniforms : {};
+  const state = {};
+  for (const [name, uniform] of Object.entries(definition.uniformSchema)) {
+    const nextValue = Object.prototype.hasOwnProperty.call(overrides, name)
+      ? overrides[name]
+      : uniform.defaultValue;
+    state[name] = cloneUniformValue(uniform.normalize(nextValue));
+  }
+  return state;
+}
+
+function resolveShaderKitDefinition(id) {
+  const presetId = String(id || '').trim();
+  return SHADER_KIT_DEFINITIONS[presetId] || null;
+}
+
+function toPublicShaderKitDefinition(definition) {
+  return {
+    id: definition.id,
+    label: definition.label,
+    category: definition.category,
+    description: definition.description,
+    uniforms: Object.keys(definition.uniformSchema),
+    uniformDefinitions: Object.entries(definition.uniformSchema).map(([name, uniform]) => ({
+      name,
+      type: uniform.type,
+      defaultValue: cloneUniformValue(uniform.defaultValue),
+      min: Number.isFinite(uniform.min) ? uniform.min : null,
+      max: Number.isFinite(uniform.max) ? uniform.max : null,
+    })),
+    textures: [...definition.textureSlots],
+    nonGoals: [...definition.nonGoals],
+    supportsTime: Boolean(definition.timeUniform),
+  };
+}
+
+function uniformTypeRecord(schema) {
+  const out = {};
+  for (const [name, entry] of Object.entries(schema)) {
+    out[name] = entry.type;
+  }
+  return out;
+}
+
+function createHologramDefinition() {
+  const fields = [
+    ['baseColor', 'vec4<f32>'],
+    ['edgeColor', 'vec4<f32>'],
+    ['time', 'f32'],
+    ['fresnelPower', 'f32'],
+    ['scanlineDensity', 'f32'],
+    ['scanlineSpeed', 'f32'],
+  ];
+  return {
+    id: 'hologram',
+    label: 'Hologram / Fresnel',
+    category: 'surface-fx',
+    description: 'Animated fresnel shell with scanline modulation for stylized props and diegetic UI.',
+    vertex: buildStandardVertexWGSL(fields),
+    fragment: `
+${buildUniformStruct('KitUniforms', fields)}
+
+struct FragmentInput {
+  @builtin(position) clipPosition : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) worldPosition : vec3<f32>,
+};
+
+@group(2) @binding(0)
+var<uniform> kit : KitUniforms;
+
+@fragment
+fn fs_main(input : FragmentInput) -> @location(0) vec4<f32> {
+  let normal = normalize(input.normal);
+  let fresnel = pow(1.0 - clamp(normal.z * 0.5 + 0.5, 0.0, 1.0), max(kit.fresnelPower, 0.1));
+  let scanline = 0.55 + (0.45 * sin((input.worldPosition.y * kit.scanlineDensity) + (kit.time * kit.scanlineSpeed)));
+  let beam = 0.6 + (0.4 * sin((input.uv.y * 28.0) + (kit.time * 4.0)));
+  let color = mix(kit.baseColor.rgb, kit.edgeColor.rgb, clamp(fresnel + 0.18, 0.0, 1.0));
+  let brightness = (0.26 + fresnel + (scanline * 0.22) + (beam * 0.18));
+  let alpha = clamp(kit.baseColor.a * (0.42 + (fresnel * 0.85)) * (0.7 + (scanline * 0.3)), 0.05, 1.0);
+  return vec4<f32>(color * brightness, alpha);
+}
+`,
+    uniformSchema: {
+      baseColor: vec4Uniform([0.16, 0.88, 1.0, 0.72]),
+      edgeColor: vec4Uniform([0.92, 0.98, 1.0, 1.0]),
+      time: floatUniform(0),
+      fresnelPower: floatUniform(2.6, 0.2, 8),
+      scanlineDensity: floatUniform(18, 1, 80),
+      scanlineSpeed: floatUniform(2.4, -30, 30),
+    },
+    textureSlots: [],
+    timeUniform: 'time',
+    nonGoals: COMMON_SHADER_KIT_NON_GOALS,
+  };
+}
+
+function createDissolveDefinition() {
+  const fields = [
+    ['baseColor', 'vec4<f32>'],
+    ['edgeColor', 'vec4<f32>'],
+    ['progress', 'f32'],
+    ['edgeWidth', 'f32'],
+    ['noiseScale', 'vec2<f32>'],
+  ];
+  return {
+    id: 'dissolve',
+    label: 'Dissolve',
+    category: 'surface-fx',
+    description: 'Hash-based dissolve transition with authored edge color and progress controls.',
+    vertex: buildStandardVertexWGSL(fields),
+    fragment: `
+${buildUniformStruct('KitUniforms', fields)}
+
+struct FragmentInput {
+  @builtin(position) clipPosition : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) worldPosition : vec3<f32>,
+};
+
+@group(2) @binding(0)
+var<uniform> kit : KitUniforms;
+
+fn hash2(value : vec2<f32>) -> f32 {
+  return fract(sin(dot(value, vec2<f32>(12.9898, 78.233))) * 43758.5453);
+}
+
+@fragment
+fn fs_main(input : FragmentInput) -> @location(0) vec4<f32> {
+  let scaled = floor(input.uv * kit.noiseScale);
+  let noise = hash2(scaled + vec2<f32>(input.worldPosition.x, input.worldPosition.z));
+  let edge_start = clamp(kit.progress - kit.edgeWidth, 0.0, 1.0);
+  if (noise < edge_start) {
+    discard;
+  }
+  let normal = normalize(input.normal);
+  let lambert = max(dot(normal, normalize(vec3<f32>(0.38, 0.88, 0.26))), 0.2);
+  let edge_mix = clamp((noise - edge_start) / max(kit.edgeWidth, 0.0001), 0.0, 1.0);
+  let color = mix(kit.edgeColor.rgb, kit.baseColor.rgb, edge_mix) * (lambert + 0.12);
+  let alpha = mix(0.92, kit.baseColor.a, edge_mix);
+  return vec4<f32>(color, alpha);
+}
+`,
+    uniformSchema: {
+      baseColor: vec4Uniform([0.9, 0.92, 1.0, 1.0]),
+      edgeColor: vec4Uniform([1.0, 0.5, 0.12, 1.0]),
+      progress: floatUniform(0, 0, 1),
+      edgeWidth: floatUniform(0.14, 0.01, 0.4),
+      noiseScale: vec2Uniform([10, 10], 0.1, 128),
+    },
+    textureSlots: [],
+    timeUniform: null,
+    nonGoals: COMMON_SHADER_KIT_NON_GOALS,
+  };
+}
+
+function createFoliageWindDefinition() {
+  const fields = [
+    ['baseColor', 'vec4<f32>'],
+    ['tipColor', 'vec4<f32>'],
+    ['time', 'f32'],
+    ['windAmplitude', 'f32'],
+    ['windFrequency', 'f32'],
+    ['windScale', 'f32'],
+  ];
+  return {
+    id: 'foliageWind',
+    label: 'Foliage / Wind',
+    category: 'deformation',
+    description: 'Vertex-sway kit for grass, reeds, and simple foliage cards without a shader graph.',
+    vertex: `
+struct CameraUniform {
+  view : mat4x4<f32>,
+  projection : mat4x4<f32>,
+};
+
+struct ModelUniform {
+  model : mat4x4<f32>,
+};
+
+${buildUniformStruct('KitUniforms', fields)}
+
+struct VertexInput {
+  @location(0) position : vec3<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) uv : vec2<f32>,
+  @location(3) color : vec4<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) sway : f32,
+};
+
+@group(0) @binding(0)
+var<uniform> camera : CameraUniform;
+
+@group(1) @binding(0)
+var<uniform> model_uniform : ModelUniform;
+
+@group(2) @binding(0)
+var<uniform> kit : KitUniforms;
+
+@vertex
+fn vs_main(input : VertexInput) -> VertexOutput {
+  var out : VertexOutput;
+  let swayWeight = clamp(input.position.y * kit.windScale, 0.0, 1.0);
+  let phase = (input.position.x * 0.9) + (input.position.z * 0.6) + (input.uv.y * 4.0);
+  let sway = sin((phase * kit.windFrequency) + kit.time) * kit.windAmplitude * swayWeight;
+  let localPosition = vec3<f32>(
+    input.position.x + sway,
+    input.position.y,
+    input.position.z + (sway * 0.35),
+  );
+  let worldPosition = model_uniform.model * vec4<f32>(localPosition, 1.0);
+  out.clipPosition = camera.projection * camera.view * worldPosition;
+  out.uv = input.uv;
+  out.normal = normalize((model_uniform.model * vec4<f32>(input.normal, 0.0)).xyz);
+  out.sway = swayWeight;
+  return out;
+}
+`,
+    fragment: `
+${buildUniformStruct('KitUniforms', fields)}
+
+struct FragmentInput {
+  @builtin(position) clipPosition : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) sway : f32,
+};
+
+@group(2) @binding(0)
+var<uniform> kit : KitUniforms;
+
+@fragment
+fn fs_main(input : FragmentInput) -> @location(0) vec4<f32> {
+  let normal = normalize(input.normal);
+  let lambert = max(dot(normal, normalize(vec3<f32>(0.24, 0.92, 0.3))), 0.22);
+  let gradient = clamp((input.uv.y * 0.55) + (input.sway * 0.45), 0.0, 1.0);
+  let color = mix(kit.baseColor.rgb, kit.tipColor.rgb, gradient);
+  return vec4<f32>(color * (lambert + 0.16), mix(kit.baseColor.a, kit.tipColor.a, gradient));
+}
+`,
+    uniformSchema: {
+      baseColor: vec4Uniform([0.18, 0.58, 0.22, 1.0]),
+      tipColor: vec4Uniform([0.62, 0.88, 0.4, 1.0]),
+      time: floatUniform(0),
+      windAmplitude: floatUniform(0.18, 0, 2),
+      windFrequency: floatUniform(1.8, 0.1, 12),
+      windScale: floatUniform(1.1, 0.1, 6),
+    },
+    textureSlots: [],
+    timeUniform: 'time',
+    nonGoals: COMMON_SHADER_KIT_NON_GOALS,
+  };
+}
+
+function createRimAccentDefinition() {
+  const fields = [
+    ['baseColor', 'vec4<f32>'],
+    ['rimColor', 'vec4<f32>'],
+    ['rimPower', 'f32'],
+    ['rimIntensity', 'f32'],
+  ];
+  return {
+    id: 'rimAccent',
+    label: 'Rim / Emissive Accent',
+    category: 'surface-fx',
+    description: 'Rim-light accent pass for interactables, pickups, and stylized hero props.',
+    vertex: buildStandardVertexWGSL(fields),
+    fragment: `
+${buildUniformStruct('KitUniforms', fields)}
+
+struct FragmentInput {
+  @builtin(position) clipPosition : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) worldPosition : vec3<f32>,
+};
+
+@group(2) @binding(0)
+var<uniform> kit : KitUniforms;
+
+@fragment
+fn fs_main(input : FragmentInput) -> @location(0) vec4<f32> {
+  let normal = normalize(input.normal);
+  let lambert = max(dot(normal, normalize(vec3<f32>(0.44, 0.88, 0.24))), 0.18);
+  let rim = pow(1.0 - clamp(normal.z * 0.5 + 0.5, 0.0, 1.0), max(kit.rimPower, 0.1)) * kit.rimIntensity;
+  let color = (kit.baseColor.rgb * (lambert + 0.14)) + (kit.rimColor.rgb * rim);
+  let alpha = max(kit.baseColor.a, clamp(kit.rimColor.a * rim, 0.0, 1.0));
+  return vec4<f32>(color, alpha);
+}
+`,
+    uniformSchema: {
+      baseColor: vec4Uniform([0.2, 0.2, 0.24, 1.0]),
+      rimColor: vec4Uniform([1.0, 0.78, 0.24, 1.0]),
+      rimPower: floatUniform(2.2, 0.1, 8),
+      rimIntensity: floatUniform(1.3, 0, 6),
+    },
+    textureSlots: [],
+    timeUniform: null,
+    nonGoals: COMMON_SHADER_KIT_NON_GOALS,
+  };
+}
+
+function buildStandardVertexWGSL(fields) {
+  return `
+struct CameraUniform {
+  view : mat4x4<f32>,
+  projection : mat4x4<f32>,
+};
+
+struct ModelUniform {
+  model : mat4x4<f32>,
+};
+
+${buildUniformStruct('KitUniforms', fields)}
+
+struct VertexInput {
+  @location(0) position : vec3<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) uv : vec2<f32>,
+  @location(3) color : vec4<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) worldPosition : vec3<f32>,
+};
+
+@group(0) @binding(0)
+var<uniform> camera : CameraUniform;
+
+@group(1) @binding(0)
+var<uniform> model_uniform : ModelUniform;
+
+@group(2) @binding(0)
+var<uniform> kit : KitUniforms;
+
+@vertex
+fn vs_main(input : VertexInput) -> VertexOutput {
+  var out : VertexOutput;
+  let worldPosition = model_uniform.model * vec4<f32>(input.position, 1.0);
+  out.clipPosition = camera.projection * camera.view * worldPosition;
+  out.uv = input.uv;
+  out.normal = normalize((model_uniform.model * vec4<f32>(input.normal, 0.0)).xyz);
+  out.worldPosition = worldPosition.xyz;
+  return out;
+}
+`;
+}
+
+function buildUniformStruct(name, fields) {
+  const body = fields.map(([fieldName, type]) => `  ${fieldName} : ${type},`).join('\n');
+  return `struct ${name} {\n${body}\n};`;
+}
+
+function normalizeTextureBindings(definition, spec) {
+  const bindings = Object.fromEntries(definition.textureSlots.map((slotName) => [slotName, null]));
+  if (definition.textureSlots.length === 0) {
+    if (Object.prototype.hasOwnProperty.call(spec, 'texture')) {
+      throw new Error(`Shader kit ${definition.id} does not declare custom textures`);
+    }
+    if (spec.textures != null) {
+      if (!isPlainObject(spec.textures) || Object.keys(spec.textures).length > 0) {
+        throw new Error(`Shader kit ${definition.id} does not declare custom textures`);
+      }
+    }
+    return bindings;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(spec, 'texture')) {
+    if (!(definition.textureSlots.length === 1 && definition.textureSlots[0] === 'texture')) {
+      throw new Error(`Shader kit ${definition.id} requires explicit texture slots`);
+    }
+    bindings.texture = normalizeTexturePath(spec.texture);
+  }
+
+  if (spec.textures == null) {
+    return bindings;
+  }
+  if (!isPlainObject(spec.textures)) {
+    throw new TypeError(`Shader kit ${definition.id} textures must be an object`);
+  }
+  for (const [slotName, texturePath] of Object.entries(spec.textures)) {
+    if (!definition.textureSlots.includes(slotName)) {
+      throw new Error(`Unknown shader kit texture slot for ${definition.id}: ${slotName}`);
+    }
+    bindings[slotName] = normalizeTexturePath(texturePath);
+  }
+  return bindings;
+}
+
+function floatUniform(defaultValue, min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY) {
+  return {
+    type: 'float',
+    defaultValue,
+    min,
+    max,
+    normalize(value) {
+      const number = Number.isFinite(value) ? Number(value) : Number(defaultValue);
+      return clamp(number, min, max);
+    },
+  };
+}
+
+function vec2Uniform(defaultValue, min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY) {
+  return {
+    type: 'vec2',
+    defaultValue,
+    min,
+    max,
+    normalize(value) {
+      const [x, y] = normalizeVector(value, defaultValue, 2);
+      return {
+        x: clamp(x, min, max),
+        y: clamp(y, min, max),
+      };
+    },
+  };
+}
+
+function vec4Uniform(defaultValue) {
+  return {
+    type: 'vec4',
+    defaultValue,
+    min: null,
+    max: null,
+    normalize(value) {
+      const [x, y, z, w] = normalizeVector(value, defaultValue, 4);
+      return { x, y, z, w };
+    },
+  };
+}
+
+function normalizeVector(value, fallback, size) {
+  const values = Array.isArray(value)
+    ? value
+    : isPlainObject(value)
+      ? size === 2
+        ? [value.x, value.y]
+        : [value.x ?? value.r, value.y ?? value.g, value.z ?? value.b, value.w ?? value.a]
+      : [];
+  const out = [];
+  for (let i = 0; i < size; i += 1) {
+    const candidate = Number(values[i]);
+    out.push(Number.isFinite(candidate) ? candidate : Number(fallback[i]));
+  }
+  return out;
+}
+
+function normalizeTexturePath(value) {
+  if (value == null) return null;
+  if (typeof value !== 'string') {
+    throw new TypeError('Shader kit texture path must be a string or null');
+  }
+  return value;
+}
+
+function cloneUniformObject(state) {
+  const out = {};
+  for (const [name, value] of Object.entries(state)) {
+    out[name] = cloneUniformValue(value);
+  }
+  return out;
+}
+
+function cloneUniformValue(value) {
+  if (Array.isArray(value)) return value.slice();
+  if (isPlainObject(value)) return { ...value };
+  return value;
+}
+
+function cloneTextureBindings(bindings) {
+  return isPlainObject(bindings) ? { ...bindings } : {};
+}
+
+function assertCustomMaterialSurface(aura) {
+  if (!aura || typeof aura !== 'object' || !aura.material || typeof aura.material !== 'object') {
+    throw new Error('Shader kits require aura.material');
+  }
+  for (const name of CUSTOM_SHADER_SURFACE) {
+    if (typeof aura.material[name] !== 'function') {
+      throw new Error(`Shader kits require aura.material.${name}`);
+    }
+  }
+}
+
+function assertMutationOk(result, operation) {
+  if (result && result.ok === false) {
+    const reasonCode = typeof result.reasonCode === 'string'
+      ? result.reasonCode
+      : 'unknown_shader_kit_error';
+    throw new Error(`Shader kit mutation failed during ${operation}: ${reasonCode}`);
+  }
+}
+
+function safeUnload(aura, handle) {
+  try {
+    aura?.material?.unload?.(handle);
+  } catch (_) {}
+}
+
+function ensureNotDestroyed(destroyed, presetId) {
+  if (destroyed) {
+    throw new Error(`Shader kit ${presetId} has already been destroyed`);
+  }
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}