sim_materialRegistry.js

/**
 * Neptune Environmental Simulation - Material Registry & Interaction System
 * SIM-01 implementation.
 */

/**
 * Standard material interaction states.
 */
export const MaterialState = Object.freeze({
    DRY: "dry",
    WET: "wet",
    BURNING: "burning",
    CHARRED: "charred",
    EXTINGUISHED: "extinguished",
});

/**
 * Interaction types applicable to materials.
 */
export const InteractionType = Object.freeze({
    IGNITE: "IGNITE",
    DOUSE: "DOUSE",
    COOL: "COOL",
    DRY: "DRY",
    BURN: "BURN",
    BURNOUT: "BURNOUT",
    CHAR: "CHAR",
});

/**
 * Standard built-in material definitions.
 */
export const BUILTIN_MATERIALS = Object.freeze({
    wood: Object.freeze({
        id: "wood",
        flammability: 0.6,
        conductivity: 0.1,
        viscosity: 0.0,
        traversalCost: 1.0,
        isSolid: true,
        burnDuration: 10,
    }),
    stone: Object.freeze({
        id: "stone",
        flammability: 0.0,
        conductivity: 0.1,
        viscosity: 0.0,
        traversalCost: 1.0,
        isSolid: true,
        burnDuration: 0,
    }),
    water: Object.freeze({
        id: "water",
        flammability: 0.0,
        conductivity: 0.8,
        viscosity: 1.0,
        traversalCost: 2.0,
        isSolid: false,
        burnDuration: 0,
    }),
    grass: Object.freeze({
        id: "grass",
        flammability: 0.8,
        conductivity: 0.1,
        viscosity: 0.0,
        traversalCost: 1.0,
        isSolid: false,
        burnDuration: 4,
    }),
    iron: Object.freeze({
        id: "iron",
        flammability: 0.0,
        conductivity: 1.0,
        viscosity: 0.0,
        traversalCost: 1.0,
        isSolid: true,
        burnDuration: 0,
    }),
    cloth: Object.freeze({
        id: "cloth",
        flammability: 0.9,
        conductivity: 0.05,
        viscosity: 0.0,
        traversalCost: 1.0,
        isSolid: false,
        burnDuration: 5,
    }),
    dirt: Object.freeze({
        id: "dirt",
        flammability: 0.0,
        conductivity: 0.1,
        viscosity: 0.0,
        traversalCost: 1.0,
        isSolid: false,
        burnDuration: 0,
    }),
});

/**
 * Fallback material used when an unknown material is queried.
 */
export const FALLBACK_MATERIAL = Object.freeze({
    id: "dirt",
    flammability: 0.0,
    conductivity: 0.1,
    viscosity: 0.0,
    traversalCost: 1.0,
    isSolid: false,
    burnDuration: 0,
    isFallback: true,
});

/**
 * Validates a material definition object.
 * @param {string} id - The material ID.
 * @param {object} def - The material definition.
 * @returns {object} Normalized and frozen material definition.
 */
function validateMaterialDefinition(id, def) {
    if (typeof id !== "string" || !id.trim()) {
        throw new TypeError("Material ID must be a non-empty string");
    }
    if (!def || typeof def !== "object") {
        throw new TypeError(`Material definition for "${id}" must be an object`);
    }

    const flammability = Number(def.flammability ?? 0);
    if (!Number.isFinite(flammability) || flammability < 0 || flammability > 1) {
        throw new RangeError(`Material "${id}" flammability must be a number between 0 and 1, got ${def.flammability}`);
    }

    const conductivity = Number(def.conductivity ?? 0);
    if (!Number.isFinite(conductivity) || conductivity < 0 || conductivity > 1) {
        throw new RangeError(`Material "${id}" conductivity must be a number between 0 and 1, got ${def.conductivity}`);
    }

    const viscosity = Number(def.viscosity ?? 0);
    if (!Number.isFinite(viscosity) || viscosity < 0) {
        throw new RangeError(`Material "${id}" viscosity must be a non-negative number, got ${def.viscosity}`);
    }

    const traversalCost = Number(def.traversalCost ?? 1.0);
    if (!Number.isFinite(traversalCost) || traversalCost < 1) {
        throw new RangeError(`Material "${id}" traversalCost must be a number >= 1, got ${def.traversalCost}`);
    }

    const isSolid = Boolean(def.isSolid);

    const burnDuration = Number(def.burnDuration ?? 0);
    if (!Number.isFinite(burnDuration) || burnDuration < 0) {
        throw new RangeError(`Material "${id}" burnDuration must be a non-negative number, got ${def.burnDuration}`);
    }

    return Object.freeze({
        id,
        flammability,
        conductivity,
        viscosity,
        traversalCost,
        isSolid,
        burnDuration,
        ...(def.tags ? { tags: Object.freeze([...def.tags]) } : {}),
        ...(def.description ? { description: String(def.description) } : {}),
    });
}

/**
 * Registry storing material definitions and providing fallback handling.
 */
export class MaterialRegistry {
    static _defaultInstance = null;

    /**
     * Get the default singleton instance of MaterialRegistry.
     * @returns {MaterialRegistry}
     */
    static getDefault() {
        if (!MaterialRegistry._defaultInstance) {
            MaterialRegistry._defaultInstance = new MaterialRegistry();
        }
        return MaterialRegistry._defaultInstance;
    }

    /**
     * Static helper to register a material definition on the default registry.
     */
    static register(id, def) {
        return MaterialRegistry.getDefault().register(id, def);
    }

    /**
     * Static helper to get a material definition from the default registry.
     */
    static get(id, options) {
        return MaterialRegistry.getDefault().get(id, options);
    }

    /**
     * Static helper to check if a material definition exists in the default registry.
     */
    static has(id) {
        return MaterialRegistry.getDefault().has(id);
    }

    /**
     * Static helper to reset the default registry to built-ins.
     */
    static reset() {
        return MaterialRegistry.getDefault().reset();
    }

    /**
     * Static access to the default registry's diagnostic log.
     */
    static get diagnostics() {
        return MaterialRegistry.getDefault().diagnostics;
    }

    constructor() {
        /** @type {Map<string, object>} */
        this._materials = new Map();
        /** @type {Array<object>} */
        this.diagnostics = [];
        /** @type {string} */
        this._fallbackId = "dirt";
        /** @type {object|null} */
        this._customFallback = null;
        /** @type {Function|null} */
        this.onDiagnostic = null;

        this._registerBuiltins();
    }

    _registerBuiltins() {
        for (const [id, def] of Object.entries(BUILTIN_MATERIALS)) {
            this._materials.set(id, def);
        }
    }

    /**
     * Register or update a material definition.
     * @param {string} id - Unique material identifier.
     * @param {object} def - Material properties.
     * @returns {object} The registered material definition.
     */
    register(id, def) {
        const validated = validateMaterialDefinition(id, def);
        this._materials.set(id, validated);
        return validated;
    }

    /**
     * Check if a material is registered.
     * @param {string} id - Material identifier.
     * @returns {boolean}
     */
    has(id) {
        if (typeof id !== "string") return false;
        return this._materials.has(id);
    }

    /**
     * Query a material definition by ID with fallback handling and diagnostic warning.
     * @param {string} id - Material identifier.
     * @param {object} [options]
     * @param {boolean} [options.suppressWarning=false] - Whether to suppress console warning.
     * @returns {object} The material definition or fallback.
     */
    get(id, { suppressWarning = false } = {}) {
        if (typeof id === "string" && this._materials.has(id)) {
            return this._materials.get(id);
        }

        // Handle missing material: log diagnostic warning and return fallback
        const fallbackDef = this._getFallbackDefinition();
        const message = `[MaterialRegistry] Material "${id}" not found. Falling back to default material "${fallbackDef.id}".`;

        const diagnosticEntry = {
            type: "MISSING_MATERIAL",
            materialId: id,
            fallbackId: fallbackDef.id,
            message,
            timestamp: Date.now(),
        };
        this.diagnostics.push(diagnosticEntry);

        if (typeof this.onDiagnostic === "function") {
            try {
                this.onDiagnostic(diagnosticEntry);
            } catch (err) {
                console.error("[MaterialRegistry] Error in diagnostic listener:", err);
            }
        }

        if (!suppressWarning) {
            console.warn(message);
        }

        return fallbackDef;
    }

    /**
     * Get fallback definition.
     * @private
     */
    _getFallbackDefinition() {
        if (this._customFallback) return this._customFallback;
        if (this._materials.has(this._fallbackId)) {
            return this._materials.get(this._fallbackId);
        }
        return FALLBACK_MATERIAL;
    }

    /**
     * Configure the fallback material.
     * @param {string|object} fallback - Material ID or definition.
     */
    setFallback(fallback) {
        if (typeof fallback === "string") {
            this._fallbackId = fallback;
            this._customFallback = null;
        } else if (fallback && typeof fallback === "object") {
            this._customFallback = validateMaterialDefinition(fallback.id || "custom_fallback", fallback);
        }
    }

    /**
     * Unregister a material definition.
     * @param {string} id
     * @returns {boolean}
     */
    unregister(id) {
        return this._materials.delete(id);
    }

    /**
     * Reset registry to default built-in materials and clear diagnostics.
     */
    reset() {
        this._materials.clear();
        this.diagnostics.length = 0;
        this._fallbackId = "dirt";
        this._customFallback = null;
        this._registerBuiltins();
    }

    /**
     * Get all registered material definitions as an array.
     * @returns {Array<object>}
     */
    getAll() {
        return Array.from(this._materials.values());
    }

    /**
     * Get all registered material IDs.
     * @returns {Array<string>}
     */
    getIds() {
        return Array.from(this._materials.keys());
    }
}

/**
 * Result object returned by MaterialInteraction.applyInteraction.
 */
export class InteractionResult {
    constructor({ state, previousState, materialId, material, intensity, interactions, applied }) {
        this.state = state;
        this.previousState = previousState;
        this.materialId = materialId;
        this.material = material;
        this.intensity = intensity;
        this.interactions = Object.freeze([...interactions]);
        this.applied = applied;

        const traversal = MaterialInteraction.getEffectiveTraversalCost({ materialId, state, material });
        this.traversalCost = traversal;

        const hazard = MaterialInteraction.getHazardStatus({ materialId, state, material });
        this.hazard = hazard;
        this.isHazard = hazard.isHazard;
    }

    toString() {
        return this.state;
    }

    valueOf() {
        return this.state;
    }

    [Symbol.toPrimitive](hint) {
        if (hint === "number") return NaN;
        return this.state;
    }
}

/**
 * Material interaction and state transition engine.
 */
export class MaterialInteraction {
    /**
     * Query effective traversal cost based on material attributes and current state.
     * Supports both getEffectiveTraversalCost(materialId, state) and getEffectiveTraversalCost({ materialId, state }).
     *
     * @param {string|object} arg1 - materialId or options object.
     * @param {string} [arg2] - state if arg1 is materialId.
     * @returns {number} Effective traversal cost (>= 1.0).
     */
    static getEffectiveTraversalCost(arg1, arg2) {
        let materialId;
        let state;
        let material = null;
        let registry = MaterialRegistry.getDefault();

        if (typeof arg1 === "object" && arg1 !== null) {
            materialId = arg1.materialId;
            state = arg1.state;
            material = arg1.material ?? null;
            if (arg1.registry) registry = arg1.registry;
        } else {
            materialId = arg1;
            state = arg2;
        }

        const normalizedState = (state || MaterialState.DRY).toLowerCase();
        const mat = material || (typeof materialId === "object" && materialId !== null ? materialId : registry.get(materialId));
        const baseCost = mat.traversalCost ?? 1.0;

        switch (normalizedState) {
            case MaterialState.BURNING:
                // Burning terrain is hazardous and heavily impedes traversal
                return Math.max(1.0, baseCost + 2.0);

            case MaterialState.WET:
                // Water has inherent traversal cost; wet ground becomes muddy / slippery
                if (mat.id === "water") {
                    return Math.max(1.0, baseCost);
                }
                return Math.max(1.0, baseCost * 1.5);

            case MaterialState.CHARRED:
                // Ash/charred rubble slightly increases traversal effort
                return Math.max(1.0, baseCost * 1.2);

            case MaterialState.EXTINGUISHED:
                // Soggy extinguished remains
                return Math.max(1.0, baseCost * 1.3);

            case MaterialState.DRY:
            default:
                return Math.max(1.0, baseCost);
        }
    }

    /**
     * Query hazard status based on material attributes and current state.
     * Supports both getHazardStatus(materialId, state) and getHazardStatus({ materialId, state }).
     *
     * @param {string|object} arg1 - materialId or options object.
     * @param {string} [arg2] - state if arg1 is materialId.
     * @returns {{ isHazard: boolean, type: string|null, severity: number, description: string }}
     */
    static getHazardStatus(arg1, arg2) {
        let materialId;
        let state;
        let material = null;
        let registry = MaterialRegistry.getDefault();

        if (typeof arg1 === "object" && arg1 !== null) {
            materialId = arg1.materialId;
            state = arg1.state;
            material = arg1.material ?? null;
            if (arg1.registry) registry = arg1.registry;
        } else {
            materialId = arg1;
            state = arg2;
        }

        const normalizedState = (state || MaterialState.DRY).toLowerCase();
        const mat = material || (typeof materialId === "object" && materialId !== null ? materialId : registry.get(materialId));

        if (normalizedState === MaterialState.BURNING) {
            return Object.freeze({
                isHazard: true,
                type: "fire",
                severity: 2,
                description: `Burning ${mat.id || "material"} deals fire damage to occupants`,
            });
        }

        return Object.freeze({
            isHazard: false,
            type: null,
            severity: 0,
            description: "Safe",
        });
    }

    /**
     * Check if the material and state combination constitutes a hazard.
     * @param {string|object} arg1 - materialId or options object.
     * @param {string} [arg2] - state.
     * @returns {boolean}
     */
    static isHazard(arg1, arg2) {
        return MaterialInteraction.getHazardStatus(arg1, arg2).isHazard;
    }

    /**
     * Query traversal cost and hazard status together.
     * @param {object} query - Query parameters { materialId, state }.
     * @returns {object}
     */
    static query({ materialId, state, registry = MaterialRegistry.getDefault() }) {
        const mat = registry.get(materialId);
        return {
            materialId: mat.id,
            state: (state || MaterialState.DRY).toLowerCase(),
            traversalCost: MaterialInteraction.getEffectiveTraversalCost({ materialId: mat.id, state, material: mat, registry }),
            hazard: MaterialInteraction.getHazardStatus({ materialId: mat.id, state, material: mat, registry }),
            isHazard: MaterialInteraction.isHazard({ materialId: mat.id, state, material: mat, registry }),
        };
    }

    /**
     * Compute next state and apply interaction rules.
     *
     * @param {object} params
     * @param {string} params.state - Current state: 'dry', 'wet', 'burning', 'charred', 'extinguished'.
     * @param {string|Array<string>} [params.interaction] - Single interaction or list of interactions.
     * @param {Array<string>} [params.interactions] - Alternative array of interactions.
     * @param {string|object} params.materialId - Material identifier or definition object.
     * @param {number} [params.intensity=1] - Intensity of interaction (>= 0).
     * @param {number} [params.moistureThreshold=1.0] - Threshold that intensity must exceed to ignite wet material.
     * @param {MaterialRegistry} [params.registry] - Optional custom MaterialRegistry.
     * @param {number} [params.elapsedTicks] - Optional elapsed burn duration ticks.
     * @param {boolean} [params.returnStateOnly=false] - If true, returns only the state string.
     * @returns {InteractionResult|string}
     */
    static applyInteraction({
        state = MaterialState.DRY,
        interaction,
        interactions,
        materialId,
        intensity = 1,
        moistureThreshold = 1.0,
        registry = MaterialRegistry.getDefault(),
        elapsedTicks,
        returnStateOnly = false,
    } = {}) {
        const normalizedCurrentState = (state || MaterialState.DRY).toLowerCase();
        const mat = typeof materialId === "object" && materialId !== null
            ? materialId
            : registry.get(materialId);

        // Normalize requested interactions into an array of uppercase strings
        const requestedList = [];
        if (Array.isArray(interaction)) {
            requestedList.push(...interaction);
        } else if (typeof interaction === "string") {
            // Support combined strings like "IGNITE_AND_DOUSE" or "IGNITE, DOUSE"
            const tokens = interaction.split(/[,_+&|\s]+/).map(t => t.trim().toUpperCase()).filter(Boolean);
            requestedList.push(...tokens);
        }
        if (Array.isArray(interactions)) {
            requestedList.push(...interactions);
        }

        const normalizedInteractions = requestedList.map(i => String(i).toUpperCase());

        const hasIgnite = normalizedInteractions.includes(InteractionType.IGNITE);
        const hasDouse = normalizedInteractions.includes(InteractionType.DOUSE) || normalizedInteractions.includes("EXTINGUISH");
        const hasCool = normalizedInteractions.includes(InteractionType.COOL);
        const hasDry = normalizedInteractions.includes(InteractionType.DRY);
        const hasBurnOut = normalizedInteractions.includes(InteractionType.BURN) ||
            normalizedInteractions.includes(InteractionType.BURNOUT) ||
            normalizedInteractions.includes(InteractionType.CHAR);

        let nextState = normalizedCurrentState;
        const effectiveInteractions = [...normalizedInteractions];

        // RULE: Conflicting simultaneous ignite & douse: extinguishing takes precedence.
        if (hasIgnite && (hasDouse || hasCool)) {
            // Extinguishing suppresses ignition
            const igniteIndex = effectiveInteractions.indexOf(InteractionType.IGNITE);
            if (igniteIndex !== -1) {
                effectiveInteractions.splice(igniteIndex, 1);
            }
        }

        // Apply extinguishing / dousing (precedence over ignition)
        if (hasDouse) {
            if (normalizedCurrentState === MaterialState.BURNING) {
                // RULE: Dousing burning material transitions to extinguished (or wet), quenching fire.
                nextState = MaterialState.EXTINGUISHED;
            } else if (normalizedCurrentState === MaterialState.DRY) {
                nextState = MaterialState.WET;
            } else if (normalizedCurrentState === MaterialState.WET) {
                nextState = MaterialState.WET;
            } else if (normalizedCurrentState === MaterialState.EXTINGUISHED) {
                nextState = MaterialState.EXTINGUISHED;
            } else if (normalizedCurrentState === MaterialState.CHARRED) {
                nextState = MaterialState.CHARRED;
            }
        } else if (hasCool) {
            if (normalizedCurrentState === MaterialState.BURNING) {
                nextState = MaterialState.EXTINGUISHED;
            }
        } else if (hasIgnite) {
            // RULE: Non-flammable materials (flammability === 0) cannot ignite.
            if ((mat.flammability ?? 0) === 0) {
                nextState = normalizedCurrentState;
            }
            // RULE: Charred materials cannot re-ignite.
            else if (normalizedCurrentState === MaterialState.CHARRED) {
                nextState = MaterialState.CHARRED;
            }
            // RULE: Wet materials resist ignition unless intensity exceeds moisture threshold.
            else if (normalizedCurrentState === MaterialState.WET) {
                if (intensity > moistureThreshold) {
                    nextState = MaterialState.BURNING;
                } else {
                    // Resists ignition
                    nextState = MaterialState.WET;
                }
            }
            // Extinguished materials are also damp from dousing
            else if (normalizedCurrentState === MaterialState.EXTINGUISHED) {
                if (intensity > moistureThreshold) {
                    nextState = MaterialState.BURNING;
                } else {
                    nextState = MaterialState.EXTINGUISHED;
                }
            }
            else if (normalizedCurrentState === MaterialState.DRY) {
                nextState = MaterialState.BURNING;
            }
            else if (normalizedCurrentState === MaterialState.BURNING) {
                nextState = MaterialState.BURNING;
            }
        } else if (hasDry) {
            if (normalizedCurrentState === MaterialState.WET || normalizedCurrentState === MaterialState.EXTINGUISHED) {
                nextState = MaterialState.DRY;
            }
        } else if (hasBurnOut) {
            if (normalizedCurrentState === MaterialState.BURNING) {
                nextState = MaterialState.CHARRED;
            }
        }

        // Check burn duration elapsed ticks
        if (nextState === MaterialState.BURNING && Number.isFinite(elapsedTicks)) {
            if (elapsedTicks >= (mat.burnDuration ?? 0)) {
                nextState = MaterialState.CHARRED;
            }
        }

        if (returnStateOnly) {
            return nextState;
        }

        return new InteractionResult({
            state: nextState,
            previousState: normalizedCurrentState,
            materialId: mat.id,
            material: mat,
            intensity,
            interactions: effectiveInteractions,
            applied: nextState !== normalizedCurrentState,
        });
    }

    /**
     * Helper to compute only the next state string.
     * @param {object} params - Same parameters as applyInteraction.
     * @returns {string} The next state string.
     */
    static transition(params) {
        return MaterialInteraction.applyInteraction({ ...params, returnStateOnly: true });
    }

    /**
     * Advance burning progression. Transitions to CHARRED when duration met.
     * @param {object} params
     * @param {string} params.state - Current state.
     * @param {string|object} params.materialId - Material identifier or definition.
     * @param {number} [params.elapsedTicks=1] - Ticks to advance or total elapsed ticks.
     * @param {number} [params.currentBurnTicks=0] - Ticks already burned.
     * @param {MaterialRegistry} [params.registry]
     * @returns {InteractionResult}
     */
    static advanceBurn({
        state = MaterialState.BURNING,
        materialId,
        elapsedTicks = 1,
        currentBurnTicks = 0,
        registry = MaterialRegistry.getDefault(),
    } = {}) {
        const mat = typeof materialId === "object" && materialId !== null
            ? materialId
            : registry.get(materialId);

        const totalTicks = currentBurnTicks + elapsedTicks;
        const shouldChar = state === MaterialState.BURNING && totalTicks >= (mat.burnDuration ?? 0);

        return MaterialInteraction.applyInteraction({
            state,
            interaction: shouldChar ? InteractionType.BURNOUT : undefined,
            materialId: mat.id,
            elapsedTicks: totalTicks,
            registry,
        });
    }
}

/**
 * Default export providing the complete Sim Material API.
 */
export default {
    MaterialRegistry,
    MaterialInteraction,
    MaterialState,
    InteractionType,
    BUILTIN_MATERIALS,
    FALLBACK_MATERIAL,
};