@jgengine/shell 0.18.0 → 0.19.0

package/dist/render/TextureFiltering.js

@@ -0,0 +1,64 @@
+import { useThree } from "@react-three/fiber";
+import { useLayoutEffect } from "react";
+import * as THREE from "three";
+const TEXTURE_SLOTS = [
+    "map",
+    "normalMap",
+    "roughnessMap",
+    "metalnessMap",
+    "aoMap",
+    "emissiveMap",
+    "bumpMap",
+    "alphaMap",
+    "displacementMap",
+];
+/**
+ * Retune already-loaded textures that still carry the old default anisotropy. Textures a
+ * system set on purpose (pixel-art sprites pin 1) keep their value.
+ * @internal
+ */
+export function retuneTextureAnisotropy(root, from, to) {
+    const seen = new Set();
+    root.traverse((node) => {
+        const mesh = node;
+        if (mesh.material === undefined)
+            return;
+        const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const material of materials) {
+            const slots = material;
+            for (const slot of TEXTURE_SLOTS) {
+                const texture = slots[slot];
+                if (texture === null || texture === undefined || seen.has(texture))
+                    continue;
+                seen.add(texture);
+                if (texture.anisotropy !== from)
+                    continue;
+                texture.anisotropy = to;
+                texture.needsUpdate = true;
+            }
+        }
+    });
+    return seen.size;
+}
+/**
+ * Applies the player's texture-filtering choice. Sets three's construction-time default so
+ * every texture loaded afterwards (GLTF, texture loaders) samples anisotropically, and walks the
+ * scene once per change for textures loaded before. No per-frame work.
+ * @internal shell-internal; driven by `GraphicsProfile.anisotropy`.
+ */
+export function TextureFiltering({ anisotropy }) {
+    const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
+    useLayoutEffect(() => {
+        const target = Math.max(1, Math.min(anisotropy, gl.capabilities.getMaxAnisotropy()));
+        const previous = THREE.Texture.DEFAULT_ANISOTROPY;
+        if (previous === target)
+            return;
+        THREE.Texture.DEFAULT_ANISOTROPY = target;
+        retuneTextureAnisotropy(scene, previous, target);
+        return () => {
+            THREE.Texture.DEFAULT_ANISOTROPY = previous;
+        };
+    }, [gl, scene, anisotropy]);
+    return null;
+}

package/dist/render/displayColor.d.ts

@@ -0,0 +1,33 @@
+import { type Color, type ToneMapping } from "three";
+type Rgb = [number, number, number];
+/**
+ * three.js r182's tone-mapping curve for `mode`, applied to a linear scene color at `exposure`.
+ * Mirrors `tonemapping_pars_fragment`; `NoToneMapping` and custom curves pass through.
+ * @internal
+ */
+export declare function toneMapColor(color: readonly [number, number, number], mode: ToneMapping, exposure?: number): Rgb;
+/**
+ * The linear scene color that `mode` at `exposure` displays as `display` (linear sRGB, 0..1).
+ * Sky and fog colors are picked as on-screen swatches, but the output pass tone-maps them like
+ * lit surfaces, which turns a pale horizon grey. Solved by fixed-point iteration because AgX and
+ * ACES mix channels; a swatch a curve cannot reach (pure white, a saturated highlight under AgX)
+ * lands on the closest color it can show.
+ * @internal
+ */
+export declare function sceneColorForDisplay(display: readonly [number, number, number], mode: ToneMapping, exposure?: number): Rgb;
+/**
+ * Writes the scene color that displays as `display` into `target`, recomputing only when the
+ * swatch or the renderer's tone mapping changes, so per-frame sky drivers stay allocation-free.
+ * @internal
+ */
+export declare class DisplayColorWriter {
+    private hex;
+    private mode;
+    private exposure;
+    private scene;
+    write(target: Color, display: Color, renderer: {
+        toneMapping: ToneMapping;
+        toneMappingExposure: number;
+    }): void;
+}
+export {};

package/dist/render/displayColor.js

@@ -0,0 +1,138 @@
+import { ACESFilmicToneMapping, AgXToneMapping, CineonToneMapping, LinearToneMapping, NeutralToneMapping, ReinhardToneMapping, } from "three";
+const saturate = (x) => Math.min(1, Math.max(0, x));
+/** GLSL `mat3(c0, c1, c2) * v` with the columns three's tonemapping chunk declares. */
+function mat3(c, v) {
+    return [
+        c[0][0] * v[0] + c[1][0] * v[1] + c[2][0] * v[2],
+        c[0][1] * v[0] + c[1][1] * v[1] + c[2][1] * v[2],
+        c[0][2] * v[0] + c[1][2] * v[1] + c[2][2] * v[2],
+    ];
+}
+const ACES_IN = [[0.59719, 0.076, 0.0284], [0.35458, 0.90834, 0.13383], [0.04823, 0.01566, 0.83777]];
+const ACES_OUT = [[1.60475, -0.10208, -0.00327], [-0.53108, 1.10813, -0.07276], [-0.07367, -0.00605, 1.07602]];
+const REC2020_TO_SRGB = [[1.6605, -0.1246, -0.0182], [-0.5876, 1.1329, -0.1006], [-0.0728, -0.0083, 1.1187]];
+const SRGB_TO_REC2020 = [[0.6274, 0.0691, 0.0164], [0.3293, 0.9195, 0.088], [0.0433, 0.0113, 0.8956]];
+const AGX_INSET = [
+    [0.856627153315983, 0.137318972929847, 0.11189821299995],
+    [0.0951212405381588, 0.761241990602591, 0.0767994186031903],
+    [0.0482516061458583, 0.101439036467562, 0.811302368396859],
+];
+const AGX_OUTSET = [
+    [1.1271005818144368, -0.1413297634984383, -0.14132976349843826],
+    [-0.11060664309660323, 1.157823702216272, -0.11060664309660294],
+    [-0.016493938717834573, -0.016493938717834257, 1.2519364065950405],
+];
+const AGX_MIN_EV = -12.47393;
+const AGX_MAX_EV = 4.026069;
+function aces(c) {
+    const v = mat3(ACES_IN, [c[0] / 0.6, c[1] / 0.6, c[2] / 0.6]);
+    const fit = v.map((x) => (x * (x + 0.0245786) - 0.000090537) / (x * (0.983729 * x + 0.432951) + 0.238081));
+    return mat3(ACES_OUT, fit).map(saturate);
+}
+function agx(c) {
+    const inset = mat3(AGX_INSET, mat3(SRGB_TO_REC2020, c));
+    const curved = inset.map((x) => {
+        const t = saturate((Math.log2(Math.max(x, 1e-10)) - AGX_MIN_EV) / (AGX_MAX_EV - AGX_MIN_EV));
+        const t2 = t * t;
+        const t4 = t2 * t2;
+        return 15.5 * t4 * t2 - 40.14 * t4 * t + 31.96 * t4 - 6.868 * t2 * t + 0.4298 * t2 + 0.1191 * t - 0.00232;
+    });
+    const out = mat3(AGX_OUTSET, curved).map((x) => Math.pow(Math.max(0, x), 2.2));
+    return mat3(REC2020_TO_SRGB, out).map(saturate);
+}
+function neutral(input) {
+    const x = Math.min(input[0], input[1], input[2]);
+    const offset = x < 0.08 ? x - 6.25 * x * x : 0.04;
+    const c = input.map((v) => v - offset);
+    const peak = Math.max(c[0], c[1], c[2]);
+    const start = 0.76;
+    if (peak < start)
+        return c;
+    const d = 1 - start;
+    const newPeak = 1 - (d * d) / (peak + d - start);
+    const g = 1 - 1 / (0.15 * (peak - newPeak) + 1);
+    return c.map((v) => v * (newPeak / peak) * (1 - g) + newPeak * g);
+}
+/**
+ * three.js r182's tone-mapping curve for `mode`, applied to a linear scene color at `exposure`.
+ * Mirrors `tonemapping_pars_fragment`; `NoToneMapping` and custom curves pass through.
+ * @internal
+ */
+export function toneMapColor(color, mode, exposure = 1) {
+    const c = [color[0] * exposure, color[1] * exposure, color[2] * exposure];
+    switch (mode) {
+        case LinearToneMapping:
+            return c.map(saturate);
+        case ReinhardToneMapping:
+            return c.map((x) => saturate(x / (1 + x)));
+        case CineonToneMapping:
+            return c.map((v) => {
+                const x = Math.max(0, v - 0.004);
+                return Math.pow((x * (6.2 * x + 0.5)) / (x * (6.2 * x + 1.7) + 0.06), 2.2);
+            });
+        case ACESFilmicToneMapping:
+            return aces(c);
+        case AgXToneMapping:
+            return agx(c);
+        case NeutralToneMapping:
+            return neutral(c);
+        default:
+            return c;
+    }
+}
+const CURVED = new Set([ReinhardToneMapping, CineonToneMapping, ACESFilmicToneMapping, AgXToneMapping, NeutralToneMapping]);
+/** Keeps a compensated sky inside half-float range; the brightest pastel under AgX needs ~13. */
+const MAX_SCENE_VALUE = 32;
+/**
+ * The linear scene color that `mode` at `exposure` displays as `display` (linear sRGB, 0..1).
+ * Sky and fog colors are picked as on-screen swatches, but the output pass tone-maps them like
+ * lit surfaces, which turns a pale horizon grey. Solved by fixed-point iteration because AgX and
+ * ACES mix channels; a swatch a curve cannot reach (pure white, a saturated highlight under AgX)
+ * lands on the closest color it can show.
+ * @internal
+ */
+export function sceneColorForDisplay(display, mode, exposure = 1) {
+    const target = [saturate(display[0]), saturate(display[1]), saturate(display[2])];
+    if (mode === LinearToneMapping)
+        return target.map((v) => v / Math.max(exposure, 1e-6));
+    if (!CURVED.has(mode))
+        return target;
+    const scene = [...target];
+    let best = [...target];
+    let bestError = Number.POSITIVE_INFINITY;
+    for (let iteration = 0; iteration < 48; iteration += 1) {
+        const shown = toneMapColor(scene, mode, exposure);
+        const error = Math.abs(shown[0] - target[0]) + Math.abs(shown[1] - target[1]) + Math.abs(shown[2] - target[2]);
+        if (error < bestError) {
+            bestError = error;
+            best = [scene[0], scene[1], scene[2]];
+        }
+        for (let channel = 0; channel < 3; channel += 1) {
+            // Clamped so a channel a curve's toe or shoulder cannot reach does not blow up its neighbors.
+            const ratio = Math.min(2, Math.max(0.5, Math.max(target[channel], 1e-5) / Math.max(shown[channel], 1e-5)));
+            scene[channel] = Math.min(MAX_SCENE_VALUE, Math.max(1e-5, scene[channel] * Math.pow(ratio, 0.8)));
+        }
+    }
+    return best;
+}
+/**
+ * Writes the scene color that displays as `display` into `target`, recomputing only when the
+ * swatch or the renderer's tone mapping changes, so per-frame sky drivers stay allocation-free.
+ * @internal
+ */
+export class DisplayColorWriter {
+    hex = -1;
+    mode = -1;
+    exposure = Number.NaN;
+    scene = [0, 0, 0];
+    write(target, display, renderer) {
+        const hex = display.getHex();
+        if (hex !== this.hex || renderer.toneMapping !== this.mode || renderer.toneMappingExposure !== this.exposure) {
+            this.hex = hex;
+            this.mode = renderer.toneMapping;
+            this.exposure = renderer.toneMappingExposure;
+            this.scene = sceneColorForDisplay([display.r, display.g, display.b], this.mode, this.exposure);
+        }
+        target.setRGB(this.scene[0], this.scene[1], this.scene[2]);
+    }
+}

package/dist/render/modelLoad.d.ts

@@ -1,3 +1,4 @@
+import * as THREE from "three";
 import { GLTFLoader, type GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { type AssetLoadDiagnosis } from "@jgengine/core/scene/assetDiagnostics";
 /**
@@ -60,6 +61,35 @@ export declare function modelLoadFallbacks(): readonly {
 }[];
 /** Drops the recorded placeholder list. For tests and between capture runs. @internal */
 export declare function clearModelLoadFallbacks(): void;
+/** Per-model triangle ceiling before the loader warns. A prop is a few thousand triangles; a hero rig tens of thousands. */
+export declare const DEFAULT_MODEL_TRIANGLE_BUDGET = 100000;
+/** Retune the per-model triangle budget (a cinematic game may raise it; a mobile target lowers it). Non-finite or non-positive values restore the default. */
+export declare function setModelTriangleBudget(triangles: number): void;
+/** Triangles a loaded model contributes per draw, summing every mesh (instanced meshes count once per instance). @internal */
+export declare function countSceneTriangles(root: THREE.Object3D): number;
+/** One over-budget model as {@link heavyModels} reports it: the URL the loader fetched, its triangle count, and the budget it exceeded. */
+export interface HeavyModelRecord {
+    url: string;
+    triangles: number;
+    budget: number;
+}
+/**
+ * Record a loaded model's triangle count against the budget: over budget warns once per URL and lands in
+ * {@link heavyModels}; under budget is silent. Split out so the wiring is unit-testable without a GL context.
+ * @internal
+ */
+export declare function recordModelTriangles(url: string, triangles: number, overrides?: {
+    warn?: (record: HeavyModelRecord) => void;
+}): void;
+/**
+ * Every model the shared loader resolved whose triangle count exceeds the budget, in load order. A heavy
+ * prop is invisible in a screenshot and only shows up as a slow frame, so the loader measures each GLB as it
+ * lands and this exposes the verdict for `debug_snapshot` probes and smoke tests to assert against.
+ * @capability heavy-models models over the per-model triangle budget, for perf probes and smoke assertions
+ */
+export declare function heavyModels(): readonly HeavyModelRecord[];
+/** Drops the heavy-model list and the once-per-URL warning memory. For tests and between capture runs. @internal */
+export declare function clearHeavyModels(): void;
 /**
  * A {@link GLTFLoader} whose success path is unchanged but whose failures degrade
  * gracefully: when a load errors, it probes the URL and — for a diagnosed broken
@@ -72,6 +102,15 @@ export declare function clearModelLoadFallbacks(): void;
 export declare class DiagnosticGLTFLoader extends GLTFLoader {
     load(url: string, onLoad: (gltf: GLTF) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: unknown) => void): void;
 }
+/** CDN-backed decoder configuration for compressed model and texture assets. */
+export interface ModelLoaderConfig {
+    dracoDecoderPath?: string;
+    ktx2TranscoderPath?: string;
+}
+/** Configures shared Draco and KTX2 loaders. Repeated calls with the same paths are no-ops. */
+export declare function configureModelLoaders(options?: ModelLoaderConfig): Readonly<Required<ModelLoaderConfig>>;
+/** Detects GPU support for the configured KTX2 transcoder after a renderer exists. */
+export declare function detectKtx2Support(renderer: THREE.WebGLRenderer): void;
 /**
  * How long the shared GLB loader has been idle, in ms — `0` while any model is still
  * in flight. A capture host reads this to wait for streaming to finish instead of

package/dist/render/modelLoad.js

@@ -1,5 +1,7 @@
 import * as THREE from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { DRACOLoader } from "three/examples/jsm/loaders/DRACOLoader.js";
+import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
 import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
 import { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
 import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors";
@@ -138,6 +140,63 @@ export function modelLoadFallbacks() {
 export function clearModelLoadFallbacks() {
     servedFallbacks.length = 0;
 }
+/** Per-model triangle ceiling before the loader warns. A prop is a few thousand triangles; a hero rig tens of thousands. */
+export const DEFAULT_MODEL_TRIANGLE_BUDGET = 100_000;
+let modelTriangleBudget = DEFAULT_MODEL_TRIANGLE_BUDGET;
+/** Retune the per-model triangle budget (a cinematic game may raise it; a mobile target lowers it). Non-finite or non-positive values restore the default. */
+export function setModelTriangleBudget(triangles) {
+    modelTriangleBudget = Number.isFinite(triangles) && triangles > 0 ? triangles : DEFAULT_MODEL_TRIANGLE_BUDGET;
+}
+/** Triangles a loaded model contributes per draw, summing every mesh (instanced meshes count once per instance). @internal */
+export function countSceneTriangles(root) {
+    let total = 0;
+    root.traverse((node) => {
+        const mesh = node;
+        if (mesh.isMesh !== true || mesh.geometry === undefined)
+            return;
+        const geometry = mesh.geometry;
+        const vertices = geometry.index !== null ? geometry.index.count : geometry.attributes.position?.count ?? 0;
+        const instances = mesh.isInstancedMesh === true && typeof mesh.count === "number" ? mesh.count : 1;
+        total += Math.floor(vertices / 3) * instances;
+    });
+    return total;
+}
+const heavyModelRecords = [];
+const warnedHeavyUrls = new Set();
+function warnHeavyModel(record) {
+    if (typeof console === "undefined")
+        return;
+    console.warn(`[jgengine] model ${record.url} has ${record.triangles.toLocaleString()} triangles (budget ${record.budget.toLocaleString()}). A game prop should be a few thousand — pick a lighter asset or decimate it.`);
+}
+/**
+ * Record a loaded model's triangle count against the budget: over budget warns once per URL and lands in
+ * {@link heavyModels}; under budget is silent. Split out so the wiring is unit-testable without a GL context.
+ * @internal
+ */
+export function recordModelTriangles(url, triangles, overrides = {}) {
+    if (triangles <= modelTriangleBudget)
+        return;
+    const record = { url, triangles, budget: modelTriangleBudget };
+    heavyModelRecords.push(record);
+    if (warnedHeavyUrls.has(url))
+        return;
+    warnedHeavyUrls.add(url);
+    (overrides.warn ?? warnHeavyModel)(record);
+}
+/**
+ * Every model the shared loader resolved whose triangle count exceeds the budget, in load order. A heavy
+ * prop is invisible in a screenshot and only shows up as a slow frame, so the loader measures each GLB as it
+ * lands and this exposes the verdict for `debug_snapshot` probes and smoke tests to assert against.
+ * @capability heavy-models models over the per-model triangle budget, for perf probes and smoke assertions
+ */
+export function heavyModels() {
+    return heavyModelRecords;
+}
+/** Drops the heavy-model list and the once-per-URL warning memory. For tests and between capture runs. @internal */
+export function clearHeavyModels() {
+    heavyModelRecords.length = 0;
+    warnedHeavyUrls.clear();
+}
 /**
  * A {@link GLTFLoader} whose success path is unchanged but whose failures degrade
  * gracefully: when a load errors, it probes the URL and — for a diagnosed broken
@@ -149,7 +208,10 @@ export function clearModelLoadFallbacks() {
  */
 export class DiagnosticGLTFLoader extends GLTFLoader {
     load(url, onLoad, onProgress, onError) {
-        super.load(url, onLoad, onProgress, (event) => {
+        super.load(url, (gltf) => {
+            recordModelTriangles(url, countSceneTriangles(gltf.scene));
+            onLoad(gltf);
+        }, onProgress, (event) => {
             if (onError === undefined)
                 return;
             // Probe the URL the loader actually fetched (base-resolved), not the raw input.
@@ -157,6 +219,31 @@ export class DiagnosticGLTFLoader extends GLTFLoader {
         });
     }
 }
+const DEFAULT_DRACO_DECODER_PATH = "https://cdn.jsdelivr.net/npm/three@0.182.0/examples/jsm/libs/draco/";
+const DEFAULT_KTX2_TRANSCODER_PATH = "https://cdn.jsdelivr.net/npm/three@0.182.0/examples/jsm/libs/basis/";
+let configuredModelLoaders;
+let ktx2Loader;
+/** Configures shared Draco and KTX2 loaders. Repeated calls with the same paths are no-ops. */
+export function configureModelLoaders(options = {}) {
+    const next = {
+        dracoDecoderPath: options.dracoDecoderPath ?? DEFAULT_DRACO_DECODER_PATH,
+        ktx2TranscoderPath: options.ktx2TranscoderPath ?? DEFAULT_KTX2_TRANSCODER_PATH,
+    };
+    if (configuredModelLoaders?.dracoDecoderPath === next.dracoDecoderPath && configuredModelLoaders.ktx2TranscoderPath === next.ktx2TranscoderPath) {
+        return configuredModelLoaders;
+    }
+    const draco = new DRACOLoader().setDecoderPath(next.dracoDecoderPath);
+    ktx2Loader = new KTX2Loader().setTranscoderPath(next.ktx2TranscoderPath);
+    sharedGltfLoader.setDRACOLoader(draco);
+    sharedGltfLoader.setKTX2Loader(ktx2Loader);
+    configuredModelLoaders = next;
+    return configuredModelLoaders;
+}
+/** Detects GPU support for the configured KTX2 transcoder after a renderer exists. */
+export function detectKtx2Support(renderer) {
+    configureModelLoaders();
+    ktx2Loader?.detectSupport(renderer);
+}
 // LoadingManager reports queue transitions, not per-item events: `onStart` fires when the
 // queue goes busy and `onLoad` when it drains (errors included, via itemEnd), so a flag plus
 // a drain timestamp is the whole state.
@@ -187,3 +274,4 @@ export function modelLoadIdleMs() {
 /** Shared GLTF loader used by shell entity/object model mounts. @internal */
 export const sharedGltfLoader = new DiagnosticGLTFLoader(modelLoadingManager);
 sharedGltfLoader.setMeshoptDecoder(MeshoptDecoder);
+configureModelLoaders();

package/dist/render/modelRender.d.ts

@@ -1,9 +1,12 @@
 import * as THREE from "three";
 import type { PaintStroke } from "@jgengine/core/scene/paintLayer";
 export declare const PAINT_TEXTURE_SIZE = 512;
+/** Shadow participation applied to every mesh of a cloned model; mirrors `ModelConfig.shadows`. */
+export type ModelShadowMode = "cast" | "receive" | "both" | "none";
 /** @internal */
 export declare function cloneModelScene(source: THREE.Object3D, options?: {
     cloneMaterials?: boolean;
+    shadows?: ModelShadowMode;
 }): THREE.Object3D;
 /** @internal */
 export declare function disposeClonedMaterials(root: THREE.Object3D): void;

package/dist/render/modelRender.js

@@ -4,12 +4,16 @@ export const PAINT_TEXTURE_SIZE = 512;
 /** @internal */
 export function cloneModelScene(source, options) {
     const clone = cloneSkinned(source);
-    if (options?.cloneMaterials === false)
-        return clone;
+    const shadows = options?.shadows ?? "both";
+    const cloneMaterials = options?.cloneMaterials !== false;
     clone.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
+        mesh.castShadow = shadows === "cast" || shadows === "both";
+        mesh.receiveShadow = shadows === "receive" || shadows === "both";
+        if (!cloneMaterials)
+            return;
         mesh.material = Array.isArray(mesh.material)
             ? mesh.material.map((material) => material.clone())
             : mesh.material.clone();

package/dist/render/resolveModel.js

@@ -1,3 +1,4 @@
+import { warnOnce } from "@jgengine/core/devtools/warnOnce";
 /**
  * The `ModelConfig` a resolved catalog ref renders as. Stamps `animation: "auto"` so any rigged
  * catalog asset animates by default — the shell derives idle/walk/run states and one-shots from
@@ -74,6 +75,9 @@ export function resolveEntityModel(value, assets, key) {
  * @internal
  */
 export function pickModel(assets, pick) {
+    if (pick.fallbackModel !== undefined && !assets.has(pick.fallbackModel)) {
+        warnOnce(`pickModel:fallback:${pick.fallbackModel}`, `[jgengine] fallbackModel "${pick.fallbackModel}" is not in the asset catalog, so it can never stand in for "${pick.model ?? "(none)"}" — fix the id or declare its pack in the catalog sources.`);
+    }
     for (const id of [pick.model, pick.fallbackModel]) {
         if (id === undefined)
             continue;

package/dist/render/useFootIk.d.ts

@@ -0,0 +1,58 @@
+import * as THREE from "three";
+import type { GameContext } from "@jgengine/core/runtime/gameContextTypes";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import type { SceneRaycastHit, SceneRaycastInput } from "@jgengine/core/scene/sceneRaycast";
+type FootIkConfig = NonNullable<ModelConfig["ik"]>;
+type GroundProbe = (input: SceneRaycastInput) => SceneRaycastHit | null;
+interface IkLeg {
+    root: THREE.Object3D;
+    mid: THREE.Object3D;
+    tip: THREE.Object3D;
+    /** Rest-pose ankle height above the sole divided by rest leg length, so it survives any scale. */
+    ankleRatio: number;
+}
+interface PoseRecord {
+    bone: THREE.Object3D;
+    animated: {
+        q: THREE.Quaternion;
+        p: THREE.Vector3;
+    };
+    written: {
+        q: THREE.Quaternion;
+        p: THREE.Vector3;
+    };
+}
+/** Bones resolved once per loaded scene for {@link applyFootIk}. */
+export interface FootIkRig {
+    legs: IkLeg[];
+    pelvis: THREE.Object3D | null;
+    head: THREE.Object3D | null;
+    maxAdjust: number;
+    alignToGround: number;
+    /** Pose before and after last frame's correction, so a bone no clip animates never accumulates it. */
+    poses: PoseRecord[];
+}
+/** Per-model state carried between frames: the faded weight and the smoothed pelvis drop. */
+export interface FootIkState {
+    weight: number;
+    pelvis: number;
+}
+/**
+ * Resolves foot-IK bones on a loaded rig: explicit chains, or legs found by bone name for `"auto"`
+ * and configs without `feet`. Returns `null` when no leg resolves.
+ */
+export declare function resolveFootIkRig(scene: THREE.Object3D, config: FootIkConfig): FootIkRig | null;
+/**
+ * Applies one frame of foot IK after the animation mixer: probes the ground under each foot,
+ * resolves targets with `placeFeet`, lowers the pelvis, solves each leg with `solveTwoBone` bending
+ * toward the animated knee, and tilts planted feet to the ground. Returns whether the feet are
+ * grounded; `state` carries the faded weight between frames. Exported for tests and custom hosts.
+ */
+export declare function applyFootIk(rig: FootIkRig, originY: number, probe: GroundProbe, state: FootIkState, delta: number, cameraTarget?: readonly [number, number, number]): boolean;
+/**
+ * Runs foot IK after the model's animation mixer for `ModelConfig.ik`. Ground probes hit terrain and
+ * blocking physical objects, never the model's own entity. `groundOffset` is the model-space height
+ * its soles rest on (`ModelConfig.y`).
+ */
+export declare function useFootIk(scene: THREE.Object3D, config: FootIkConfig | undefined, ctx: GameContext | null, instanceId?: string, groundOffset?: number): void;
+export {};