@jgengine/shell 0.10.0 → 0.12.0

package/dist/diagnostics/RuntimeDiagnostics.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component, useState } from "react";
+import { VERSION } from "@jgengine/core/meta/changelog";
+function errorToDiagnostic(error, phase, componentStack) {
+    const capturedAt = new Date().toISOString();
+    if (error instanceof Error) {
+        return { phase, message: error.message, stack: error.stack, componentStack, capturedAt };
+    }
+    return { phase, message: typeof error === "string" ? error : JSON.stringify(error), componentStack, capturedAt };
+}
+export function logRuntimeError(error, phase, componentStack) {
+    const diagnostic = errorToDiagnostic(error, phase, componentStack);
+    console.error(`[jgengine:${phase}] ${diagnostic.message}`, error);
+    return diagnostic;
+}
+export class GameUiErrorBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error, info) {
+        this.props.onRuntimeError(error, "ui-render", info.componentStack ?? undefined);
+    }
+    render() {
+        if (this.state.failed)
+            return null;
+        return this.props.children;
+    }
+}
+function expandedReactError(message) {
+    return /Minified React error #185\b/.test(message)
+        ? "Maximum update depth exceeded. A component is repeatedly updating state during render or after every update."
+        : null;
+}
+const ISSUES_NEW_URL = "https://github.com/Noisemaker111/jgengine/issues/new";
+/** Standalone error footer text (page, browser, engine) shared by every error surface. */
+export function errorReportContext() {
+    return [
+        `Engine: ${VERSION}`,
+        `Page: ${window.location.origin}${window.location.pathname}`,
+        `Browser: ${navigator.userAgent}`,
+    ].join("\n");
+}
+/** "Copy error" + "File issue" buttons for any error surface. `report` is the full text to copy / prefill. */
+export function ErrorReportActions({ report, issueTitle }) {
+    const [copied, setCopied] = useState(false);
+    const issueBody = report.length > 8000 ? `${report.slice(0, 8000)}\n\n[Report truncated; use Copy error for the full report.]` : report;
+    const issueUrl = `${ISSUES_NEW_URL}?title=${encodeURIComponent(`[BUG] ${issueTitle.slice(0, 120)}`)}&body=${encodeURIComponent(issueBody)}`;
+    return (_jsxs("div", { className: "flex gap-2", children: [_jsx("button", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 text-xs font-semibold text-red-50 hover:bg-red-800", type: "button", onClick: () => {
+                    void navigator.clipboard.writeText(report).then(() => {
+                        setCopied(true);
+                        window.setTimeout(() => setCopied(false), 2000);
+                    });
+                }, children: copied ? "Copied" : "Copy error" }), _jsx("a", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 text-xs font-semibold text-red-50 hover:bg-red-800", href: issueUrl, rel: "noreferrer", target: "_blank", children: "File issue" })] }));
+}
+function diagnosticReport(diagnostic, gameName) {
+    const explanation = expandedReactError(diagnostic.message);
+    return [
+        "JGengine runtime error",
+        `Game: ${gameName}`,
+        `Phase: ${diagnostic.phase}`,
+        `Time: ${diagnostic.capturedAt}`,
+        errorReportContext(),
+        explanation === null ? null : `Explanation: ${explanation}`,
+        "",
+        `Message: ${diagnostic.message}`,
+        diagnostic.stack === undefined ? null : `JavaScript stack:\n${diagnostic.stack}`,
+        diagnostic.componentStack === undefined ? null : `React component stack:\n${diagnostic.componentStack}`,
+    ]
+        .filter((line) => line !== null)
+        .join("\n");
+}
+export function DiagnosticOverlay({ diagnostics, gameName }) {
+    if (diagnostics.length === 0)
+        return null;
+    const latest = diagnostics[diagnostics.length - 1];
+    const explanation = expandedReactError(latest.message);
+    const report = diagnosticReport(latest, gameName);
+    return (_jsxs("div", { className: "pointer-events-auto absolute right-4 top-4 z-50 max-w-lg select-text rounded border border-red-400/60 bg-red-950/95 p-3 text-xs text-red-50 shadow-2xl", children: [_jsx("div", { className: "mb-1 font-semibold uppercase tracking-wide text-red-200", children: "JG engine error" }), _jsxs("div", { className: "font-mono text-[11px] text-red-100", children: ["[", latest.phase, "] ", latest.message] }), explanation !== null ? _jsx("div", { className: "mt-2 text-red-100", children: explanation }) : null, latest.stack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.stack })) : null, latest.componentStack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.componentStack })) : null, _jsx("div", { className: "mt-3", children: _jsx(ErrorReportActions, { report: report, issueTitle: `${latest.phase}: ${latest.message.slice(0, 100)}` }) })] }));
+}

package/dist/drivers/FrameDriver.d.ts

@@ -0,0 +1,37 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
+import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { PointerService } from "../pointer/pointerService.js";
+import type { ShellMultiplayer } from "../multiplayer.js";
+import type { PlayableGame } from "../registry.js";
+export declare const POSTER_SETTLE_SECONDS = 1.6;
+export declare function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, }: {
+    ctx: GameContext;
+    playable: PlayableGame;
+    tracker: ActionStateTracker<string>;
+    yawRef: {
+        current: number;
+    };
+    pitchRef: {
+        current: number;
+    };
+    primaryClickRef: {
+        current: boolean;
+    };
+    pointerAxisRef: {
+        current: PointerAxisState | null;
+    };
+    gateRef: {
+        current: boolean;
+    };
+    onRuntimeError: (error: unknown, phase: string) => void;
+    multiplayer: ShellMultiplayer | null;
+    serverIdRef: {
+        current: string | null;
+    };
+    pointerService: PointerService;
+    pointerAim: boolean;
+    pingCommand: string | undefined;
+    poster: boolean;
+    onPosterSettled: () => void;
+}): null;

package/dist/drivers/FrameDriver.js

@@ -0,0 +1,232 @@
+import { useFrame } from "@react-three/fiber";
+import { useMemo, useRef } from "react";
+import { RESERVED_INPUT_ACTIONS, dispatchBoundAction, heldActionsFor, shouldFireBoundAction } from "../boundActionDispatch.js";
+import { executeHotbarSlot, findHotbarSlotActions, hotbarIdFor } from "../hotbarActions.js";
+import { pointerAimFor } from "../shellPointer.js";
+import { shellDrivesPlayerPose } from "../shellMovement.js";
+import { steerYaw } from "@jgengine/core/movement/steering";
+import { stepPlayerMovement, resolvePlayerMovementTuning } from "@jgengine/core/movement/playerMovement";
+import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { resolveCommandSink } from "../commandSink.js";
+import { inputFramesEqual, resolveInputSink } from "../inputSink.js";
+import { advanceBehaviors } from "@jgengine/core/scene/behaviorRuntime";
+import { resolveActivePrompt } from "@jgengine/core/interaction/proximityPrompt";
+import { DEFAULT_PICKUP_RADIUS } from "@jgengine/core/game/worldItem";
+import { playControlsActive } from "@jgengine/core/game/controlGate";
+import { devtools } from "@jgengine/core/devtools/devtools";
+import { collisionDebug } from "../devtools/collisionDebug.js";
+import { GAME_SIM_FRAME_PRIORITY } from "../camera/index.js";
+import { NO_ACTIONS } from "../shellConstants.js";
+const TURN_SPEED = 2.4;
+export const POSTER_SETTLE_SECONDS = 1.6;
+export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, }) {
+    const posterElapsedRef = useRef(0);
+    const posterDoneRef = useRef(false);
+    const hasReportedTickError = useRef(false);
+    const repeatFiredAtRef = useRef(new Map());
+    const slotActions = useMemo(() => findHotbarSlotActions(playable.game.input), [playable]);
+    const hotbarId = useMemo(() => hotbarIdFor(playable), [playable]);
+    const movementTuning = useMemo(() => resolvePlayerMovementTuning({
+        collision: playable.collision,
+        movement: playable.movement,
+        physics: playable.game.physics,
+        world: playable.game.world,
+    }), [playable]);
+    const autoPickupRadius = useMemo(() => {
+        const cfg = playable.worldItem?.autoPickup;
+        if (cfg === undefined || cfg === false)
+            return null;
+        const fallback = playable.worldItem?.pickupRadius ?? DEFAULT_PICKUP_RADIUS;
+        return cfg === true ? fallback : cfg.radius ?? fallback;
+    }, [playable]);
+    const drivesPose = useMemo(() => shellDrivesPlayerPose(playable.game.input), [playable]);
+    const serverAuthoritative = useMemo(() => isServerAuthoritative(playable.game.multiplayer) && multiplayer !== null, [playable, multiplayer]);
+    const commandSink = useMemo(() => ({
+        run: (name, input) => resolveCommandSink(ctx, {
+            serverAuthoritative,
+            backend: multiplayer?.backend ?? null,
+            serverId: serverIdRef.current,
+        }).run(name, input),
+    }), [ctx, multiplayer, serverAuthoritative, serverIdRef]);
+    const inputSink = useMemo(() => ({
+        send: (frame) => resolveInputSink({
+            serverAuthoritative,
+            backend: multiplayer?.backend ?? null,
+            serverId: serverIdRef.current,
+        }).send(frame),
+    }), [multiplayer, serverAuthoritative, serverIdRef]);
+    const lastSentInputRef = useRef(null);
+    const inputActions = useMemo(() => Object.keys(playable.game.input ?? {}), [playable]);
+    useFrame((_state, rawDt) => {
+        if (poster) {
+            if (posterDoneRef.current)
+                return;
+            posterElapsedRef.current += Math.min(rawDt, 0.05);
+            if (posterElapsedRef.current >= POSTER_SETTLE_SECONDS) {
+                posterDoneRef.current = true;
+                onPosterSettled();
+                return;
+            }
+        }
+        const sendInput = () => {
+            if (!serverAuthoritative)
+                return;
+            const frame = { held: ctx.input.held(), pointer: ctx.input.pointer() };
+            const last = lastSentInputRef.current;
+            if (last !== null && inputFramesEqual(last, frame))
+                return;
+            lastSentInputRef.current = frame;
+            inputSink.send(frame);
+        };
+        if (gateRef.current || !playControlsActive(ctx)) {
+            ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS));
+            sendInput();
+            return;
+        }
+        const simStart = performance.now();
+        try {
+            let endPhase = devtools.profile.begin("time+input");
+            const dt = Math.min(rawDt, 0.05);
+            const gameDt = ctx.time.advance(dt);
+            ctx.input.publish(heldActionsFor(tracker, inputActions));
+            ctx.input.publishPointer(pointerAxisRef.current);
+            sendInput();
+            const turnInput = (tracker.isDown("turnRight") ? 1 : 0) - (tracker.isDown("turnLeft") ? 1 : 0);
+            if (turnInput !== 0)
+                yawRef.current = steerYaw(yawRef.current, turnInput, TURN_SPEED, dt);
+            endPhase();
+            const playerId = ctx.player.possession.active(ctx.player.userId);
+            const player = ctx.scene.entity.get(playerId);
+            if (player !== null && drivesPose && !serverAuthoritative) {
+                endPhase = devtools.profile.begin("pose");
+                stepPlayerMovement(ctx, ctx.player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer() }, rawDt, movementTuning, yawRef.current);
+                endPhase();
+            }
+            if (autoPickupRadius !== null && !serverAuthoritative) {
+                endPhase = devtools.profile.begin("pickup");
+                const self = ctx.scene.entity.get(playerId);
+                if (self !== null) {
+                    const nearest = ctx.scene.worldItem.nearestInRadius(self.position, autoPickupRadius);
+                    if (nearest !== null)
+                        ctx.scene.worldItem.pickup(nearest, ctx.player.userId);
+                }
+                endPhase();
+            }
+            if (!serverAuthoritative) {
+                devtools.profile.measure("onTick", () => {
+                    playable.loop.onTick(ctx, gameDt);
+                });
+                advanceBehaviors(ctx, gameDt);
+            }
+            endPhase = devtools.profile.begin("actions");
+            if (tracker.wasPressed("tabTarget")) {
+                if (ctx.game.commands.has("target.cycle"))
+                    ctx.game.commands.run("target.cycle", {});
+                else
+                    ctx.scene.entity.cycleTarget(playerId, { filter: "hostile" });
+            }
+            if (tracker.wasPressed("clearTarget")) {
+                if (ctx.game.commands.has("target.clear"))
+                    ctx.game.commands.run("target.clear", {});
+                else
+                    ctx.scene.entity.setTarget(playerId, null);
+            }
+            if (pingCommand !== undefined && tracker.wasPressed("ping")) {
+                const hit = pointerService.worldHit();
+                if (hit !== null && ctx.game.commands.has(pingCommand)) {
+                    commandSink.run(pingCommand, {
+                        point: hit.point,
+                        entity: hit.entity,
+                        object: hit.object,
+                        normal: hit.normal,
+                    });
+                }
+            }
+            const aimOverride = pointerAim ? pointerAimFor(ctx, pointerService) : undefined;
+            const commandAim = aimOverride ?? { yaw: yawRef.current, pitch: pitchRef.current };
+            if (collisionDebug.getState().layers.aimLaser) {
+                const aimFrom = ctx.player.possession.active(playerId) ?? playerId;
+                collisionDebug.setAimProbe({
+                    from: aimFrom,
+                    aim: commandAim,
+                    originPolicy: { kind: "converge" },
+                    maxDistance: 100,
+                });
+            }
+            else if (collisionDebug.getAimProbe() !== null) {
+                collisionDebug.setAimProbe(null);
+            }
+            const nowMs = performance.now();
+            for (const action of Object.keys(playable.game.input ?? {})) {
+                const pressed = tracker.wasPressed(action);
+                if (action === "ping" && pingCommand !== undefined)
+                    continue;
+                if (action === "interact") {
+                    if (!pressed)
+                        continue;
+                    const prompts = playable.prompts?.(ctx);
+                    const focus = prompts === undefined ? null : ctx.scene.entity.get(playerId);
+                    if (prompts !== undefined && focus !== null) {
+                        const active = resolveActivePrompt({ x: focus.position[0], z: focus.position[2] }, prompts);
+                        if (active !== null && active.prompt.invoke !== null) {
+                            commandSink.run(active.prompt.invoke.name, active.prompt.invoke.input);
+                        }
+                    }
+                    continue;
+                }
+                if (!shouldFireBoundAction(tracker, action, playable.game.input, repeatFiredAtRef.current, nowMs))
+                    continue;
+                repeatFiredAtRef.current.set(action, nowMs);
+                dispatchBoundAction(ctx, action, yawRef.current, pitchRef.current, commandAim, RESERVED_INPUT_ACTIONS, commandSink);
+            }
+            if (hotbarId !== null) {
+                for (const { action, slot } of slotActions) {
+                    if (!tracker.wasPressed(action))
+                        continue;
+                    const result = executeHotbarSlot(ctx, playerId, hotbarId, slot, yawRef.current, pitchRef.current, aimOverride);
+                    if (!result.ok)
+                        console.warn(`[jgengine:item-use] ${result.error}`);
+                }
+                const usePrimary = tracker.wasPressed("useAbility") || (primaryClickRef.current && hotbarId !== null);
+                if (usePrimary) {
+                    primaryClickRef.current = false;
+                    const slots = ctx.player.inventory.state(hotbarId).slots;
+                    const preferred = playable.hotbarSelection?.() ?? -1;
+                    const slot = preferred >= 0 && slots[preferred] !== null && slots[preferred] !== undefined
+                        ? preferred
+                        : slots.findIndex((stack) => stack !== null);
+                    if (slot >= 0) {
+                        const result = executeHotbarSlot(ctx, playerId, hotbarId, slot, yawRef.current, pitchRef.current, aimOverride);
+                        if (!result.ok)
+                            console.warn(`[jgengine:item-use] ${result.error}`);
+                    }
+                }
+            }
+            tracker.endFrame();
+            endPhase();
+            const serverId = serverIdRef.current;
+            if (multiplayer !== null && serverId !== null) {
+                endPhase = devtools.profile.begin("presence");
+                const focus = ctx.scene.entity.get(playerId);
+                if (focus !== null) {
+                    multiplayer.backend.presenceSync.syncPose(serverId, {
+                        x: focus.position[0],
+                        y: focus.position[1],
+                        z: focus.position[2],
+                        rotationY: focus.rotationY,
+                        rotationPitch: pitchRef.current,
+                    });
+                }
+                endPhase();
+            }
+        }
+        catch (error) {
+            if (!hasReportedTickError.current) {
+                hasReportedTickError.current = true;
+                onRuntimeError(error, "tick");
+            }
+        }
+        devtools.frame.record({ frameMs: rawDt * 1000, simMs: performance.now() - simStart });
+    }, GAME_SIM_FRAME_PRIORITY);
+    return null;
+}

package/dist/drivers/HudOnlyDriver.d.ts

@@ -0,0 +1,16 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
+import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { PlayableGame } from "../registry.js";
+export declare function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, }: {
+    ctx: GameContext;
+    playable: PlayableGame;
+    tracker: ActionStateTracker<string>;
+    pointerAxisRef: {
+        current: PointerAxisState | null;
+    };
+    gateRef: {
+        current: boolean;
+    };
+    onRuntimeError: (error: unknown, phase: string) => void;
+}): null;

package/dist/drivers/HudOnlyDriver.js

@@ -0,0 +1,60 @@
+import { useEffect, useMemo, useRef } from "react";
+import { dispatchBoundAction, heldActionsFor, shouldFireBoundAction } from "../boundActionDispatch.js";
+import { advanceBehaviors } from "@jgengine/core/scene/behaviorRuntime";
+import { playControlsActive } from "@jgengine/core/game/controlGate";
+import { devtools } from "@jgengine/core/devtools/devtools";
+import { EMPTY_RESERVED, NO_ACTIONS } from "../shellConstants.js";
+export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, }) {
+    const hasReportedTickError = useRef(false);
+    const repeatFiredAtRef = useRef(new Map());
+    const lastFrameRef = useRef(null);
+    const inputActions = useMemo(() => Object.keys(playable.game.input ?? {}), [playable]);
+    useEffect(() => {
+        let frameId;
+        const tick = (now) => {
+            frameId = requestAnimationFrame(tick);
+            const last = lastFrameRef.current;
+            lastFrameRef.current = now;
+            if (last === null)
+                return;
+            if (gateRef.current || !playControlsActive(ctx)) {
+                ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS));
+                return;
+            }
+            const rawDt = (now - last) / 1000;
+            const simStart = performance.now();
+            try {
+                let endPhase = devtools.profile.begin("time+input");
+                const dt = Math.min(rawDt, 0.05);
+                const gameDt = ctx.time.advance(dt);
+                ctx.input.publish(heldActionsFor(tracker, inputActions));
+                ctx.input.publishPointer(pointerAxisRef.current);
+                endPhase();
+                devtools.profile.measure("onTick", () => {
+                    playable.loop.onTick(ctx, gameDt);
+                });
+                advanceBehaviors(ctx, gameDt);
+                endPhase = devtools.profile.begin("actions");
+                const nowMs = performance.now();
+                for (const action of inputActions) {
+                    if (!shouldFireBoundAction(tracker, action, playable.game.input, repeatFiredAtRef.current, nowMs))
+                        continue;
+                    repeatFiredAtRef.current.set(action, nowMs);
+                    dispatchBoundAction(ctx, action, 0, 0, { yaw: 0, pitch: 0 }, EMPTY_RESERVED);
+                }
+                tracker.endFrame();
+                endPhase();
+            }
+            catch (error) {
+                if (!hasReportedTickError.current) {
+                    hasReportedTickError.current = true;
+                    onRuntimeError(error, "tick");
+                }
+            }
+            devtools.frame.record({ frameMs: rawDt * 1000, simMs: performance.now() - simStart });
+        };
+        frameId = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(frameId);
+    }, [ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, inputActions]);
+    return null;
+}

package/dist/environment/Daylight.d.ts

@@ -1,6 +1,7 @@
 import { type MutableRefObject } from "react";
 import * as THREE from "three";
-import type { SkyEnvironmentDescriptor } from "@jgengine/core/world/features";
+import type { BiomeBand, SkyEnvironmentDescriptor } from "@jgengine/core/world/features";
+import { type VolumetricCloudsConfig } from "@jgengine/core/world/volumetricClouds";
 export interface SkyDomeProps {
     topColor?: string;
     horizonColor?: string;
@@ -13,10 +14,15 @@ export interface SkyDomeProps {
     sunColor?: string;
     /** Sun disc/glow intensity multiplier. Default 1. */
     sunIntensity?: number;
+    /** Horizon haze-band strength: 0 removes the dusty band, ~1 makes it heavy. Default 0.5. */
+    hazeStrength?: number;
+    /** Sun-glow brightness multiplier around the sun disc. Default 1. */
+    sunGlowStrength?: number;
     /** Exposes the created shader material so a time-of-day driver can mutate its uniforms per frame without recreating it. */
     materialRef?: MutableRefObject<THREE.ShaderMaterial | null>;
 }
-export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, sunDirection, sunColor, sunIntensity, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
+/** @internal */
+export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, sunDirection, sunColor, sunIntensity, hazeStrength, sunGlowStrength, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
 export interface DaylightProps {
     sky?: SkyDomeProps | false;
     fog?: {
@@ -36,14 +42,21 @@ export interface DaylightProps {
     };
     /** When false, only the sky dome and fog mount — use with authored `PlayableGame.lighting`. Default true. */
     lights?: boolean;
+    /** Raymarched volumetric cloud layer over the sky dome. Omit for no clouds — off by default. */
+    clouds?: VolumetricCloudsConfig;
 }
-export declare function Daylight({ sky, fog, sun, ambient, lights }?: DaylightProps): import("react").JSX.Element;
+/** @internal */
+export declare function Daylight({ sky, fog, sun, ambient, lights, clouds }?: DaylightProps): import("react").JSX.Element;
 export interface SkyDaylightProps {
     sky: SkyEnvironmentDescriptor;
     lights?: boolean;
+    /** Terrain `biomeBands`; when any carries `fog`/`sky`, fog and dome cross-fade per camera z. */
+    bands?: readonly BiomeBand[];
 }
-/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates. */
-export declare function SkyDaylight({ sky, lights }: SkyDaylightProps): import("react").JSX.Element;
+/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates.
+ * @internal
+ */
+export declare function SkyDaylight({ sky, lights, bands }: SkyDaylightProps): import("react").JSX.Element;
 export interface TimeOfDayDaylightProps {
     sky: SkyEnvironmentDescriptor;
     /** The world's `SimClock` (or a stub exposing `calendar().dayFraction`). Absent means static rendering. */
@@ -53,10 +66,13 @@ export interface TimeOfDayDaylightProps {
         };
     };
     lights?: boolean;
+    /** Terrain `biomeBands`; when any carries `fog`/`sky`, fog and dome cross-fade per camera z. */
+    bands?: readonly BiomeBand[];
 }
 /**
  * Drives sky/fog (and optional default lights) from the world clock when `sky.timeOfDay` and `clock`
  * are both present. Authored `PlayableGame.lighting` is never rewritten — pass `lights={false}` so
  * only dome colors and fog track the day fraction.
- */
-export declare function TimeOfDayDaylight({ sky, clock, lights }: TimeOfDayDaylightProps): import("react").JSX.Element;
+  * @internal
+  */
+export declare function TimeOfDayDaylight({ sky, clock, lights, bands }: TimeOfDayDaylightProps): import("react").JSX.Element;