@jgengine/core 0.18.0 → 0.19.0

package/dist/combat/weaponPresentation.d.ts

@@ -0,0 +1,115 @@
+import type { WeaponHandlingFrame } from "./weaponHandling.js";
+/** Camera-space position `[x, y, z]` in metres: `+x` right, `+y` up, `-z` forward. */
+export type ViewmodelOffset = readonly [number, number, number];
+/**
+ * How one weapon sits in first person. Offsets are camera-space metres, angles are radians, FOVs are
+ * degrees. Every field is optional; two weapons differ by the ones they set.
+ */
+export interface WeaponPresentationTuning {
+    /** Viewmodel anchor at the hip (default `[0.34, -0.26, -0.72]`). */
+    hip?: ViewmodelOffset;
+    /** Viewmodel anchor fully aimed; put the sight on the camera axis (default `[0, -0.07, -0.55]`). */
+    ads?: ViewmodelOffset;
+    /** Viewmodel FOV in degrees, independent of the world FOV; omit to draw the viewmodel at the world FOV. */
+    viewmodelFov?: {
+        hip?: number;
+        ads?: number;
+    };
+    /** World FOV multiplier at full ADS, e.g. `0.8` for a light zoom (default `1`). */
+    adsZoom?: number;
+    /** Viewmodel lag behind look motion. */
+    sway?: {
+        /** Radians of lag per rad/s of look speed (default `0.02`). */
+        perRadPerSec?: number;
+        /** Largest lag, rad (default `0.08`). */
+        max?: number;
+        /** How fast lag follows its target, 1/s (default `12`). */
+        response?: number;
+        /** Lag multiplier at full ADS (default `0.3`). */
+        adsScale?: number;
+    };
+    /** Walk bob driven by the movement probe's speed and `bobPhase`. */
+    bob?: {
+        /** Side and vertical amplitude in metres at `fullSpeed` (default `[0.012, 0.01]`). */
+        amplitude?: readonly [number, number];
+        /** Ground speed that gives the full amplitude, m/s (default `4`). */
+        fullSpeed?: number;
+        /** Bob multiplier at full ADS (default `0.25`). */
+        adsScale?: number;
+    };
+    /** Viewmodel reaction to the handling's recoil offset. */
+    kick?: {
+        /** Metres pushed back per radian of recoil (default `1.2`). */
+        back?: number;
+        /** Viewmodel muzzle rise per radian of recoil (default `1.5`). */
+        rise?: number;
+    };
+}
+/** One frame of inputs: look motion, the movement probe, and the weapon's handling readout. */
+export interface WeaponPresentationInput {
+    /** Look yaw speed, rad/s, positive turning left (the same sign as a camera yaw that grows left). */
+    lookYawRate: number;
+    /** Look pitch speed, rad/s, positive looking up. */
+    lookPitchRate: number;
+    /** Horizontal ground speed, m/s (e.g. `EntityRenderCues.speed`). */
+    speed: number;
+    /** `0..1` walk-cycle phase (e.g. `EntityRenderCues.bobPhase`). */
+    bobPhase: number;
+    handling: WeaponHandlingFrame;
+}
+/**
+ * Where the viewmodel and camera go this frame. First person applies all of it; third person and
+ * over-the-shoulder read `lookPitch`/`lookYaw`, `aimPitch`/`aimYaw` and `adsProgress` from the same frame.
+ */
+export interface WeaponPose {
+    /** Viewmodel anchor, camera-space metres. */
+    offset: [number, number, number];
+    /** Viewmodel rotation about its anchor, rad: `pitch > 0` muzzle up, `yaw > 0` muzzle left, `roll > 0` tilts left. */
+    pitch: number;
+    yaw: number;
+    roll: number;
+    /** Viewmodel FOV in degrees, or `null` to use the world FOV. */
+    viewmodelFov: number | null;
+    /** Multiplier for the world FOV (ADS zoom). */
+    fovScale: number;
+    /** Offset to add to the camera look, rad: aim kick plus view punch. `lookYaw > 0` pulls right. */
+    lookPitch: number;
+    lookYaw: number;
+    /** Offset shots follow, rad; a third-person rig or upper-body aim reads this. */
+    aimPitch: number;
+    aimYaw: number;
+    /** `0` hip … `1` fully aimed. */
+    adsProgress: number;
+}
+/** Serializable presentation state: the current sway lag. */
+export interface WeaponPresentationState {
+    swayPitch: number;
+    swayYaw: number;
+}
+/** Turns a {@link WeaponHandlingFrame} plus look and movement into a viewmodel and camera pose. */
+export interface WeaponPresentation {
+    /** Advance sway by `dt` and return the pose. The returned object is reused between calls. */
+    update(dt: number, input: WeaponPresentationInput): WeaponPose;
+    pose(): WeaponPose;
+    retune(next: WeaponPresentationTuning): void;
+    snapshot(): WeaponPresentationState;
+    restore(state: WeaponPresentationState): void;
+    reset(): void;
+}
+/** Default hip anchor, matching the shell's built-in viewmodel. */
+export declare const DEFAULT_VIEWMODEL_HIP: ViewmodelOffset;
+/** Default ADS anchor: the built-in viewmodel's top rail on the camera axis. */
+export declare const DEFAULT_VIEWMODEL_ADS: ViewmodelOffset;
+/**
+ * Creates a {@link WeaponPresentation}: per-weapon viewmodel offset, ADS pose and viewmodel FOV, sway
+ * and inertia from look speed, bob from the movement probe, and a recoil kick, all driven by the same
+ * handling frame third-person and over-the-shoulder rigs read. Deterministic and allocation-free per update.
+ * @capability weapon-presentation per-weapon viewmodel offset, ADS pose, viewmodel FOV, sway, bob and recoil kick from a weapon handling frame
+ */
+export declare function createWeaponPresentation(initial?: WeaponPresentationTuning): WeaponPresentation;
+/**
+ * Scale for a viewmodel drawn at `viewmodelFov` through a camera at `worldFov` (both degrees): multiply
+ * the viewmodel's camera-space x and y by this and it projects as if rendered with its own FOV, without
+ * a second camera or render pass.
+ */
+export declare function viewmodelFovScale(worldFov: number, viewmodelFov: number): number;

package/dist/combat/weaponPresentation.js

@@ -0,0 +1,96 @@
+/** Default hip anchor, matching the shell's built-in viewmodel. */
+export const DEFAULT_VIEWMODEL_HIP = [0.34, -0.26, -0.72];
+/** Default ADS anchor: the built-in viewmodel's top rail on the camera axis. */
+export const DEFAULT_VIEWMODEL_ADS = [0, -0.07, -0.55];
+const TAU = Math.PI * 2;
+const DEFAULT_BOB = [0.012, 0.01];
+function lerp(hip, aimed, ads) {
+    return hip * (1 - ads) + aimed * ads;
+}
+function clamp(value, limit) {
+    return Math.max(-limit, Math.min(limit, value));
+}
+/**
+ * Creates a {@link WeaponPresentation}: per-weapon viewmodel offset, ADS pose and viewmodel FOV, sway
+ * and inertia from look speed, bob from the movement probe, and a recoil kick, all driven by the same
+ * handling frame third-person and over-the-shoulder rigs read. Deterministic and allocation-free per update.
+ * @capability weapon-presentation per-weapon viewmodel offset, ADS pose, viewmodel FOV, sway, bob and recoil kick from a weapon handling frame
+ */
+export function createWeaponPresentation(initial = {}) {
+    let tuning = initial;
+    const state = { swayPitch: 0, swayYaw: 0 };
+    const out = {
+        offset: [...(tuning.hip ?? DEFAULT_VIEWMODEL_HIP)],
+        pitch: 0,
+        yaw: 0,
+        roll: 0,
+        viewmodelFov: tuning.viewmodelFov?.hip ?? null,
+        fovScale: 1,
+        lookPitch: 0,
+        lookYaw: 0,
+        aimPitch: 0,
+        aimYaw: 0,
+        adsProgress: 0,
+    };
+    return {
+        update(dt, input) {
+            const step = Math.max(0, dt);
+            const handling = input.handling;
+            const ads = Math.max(0, Math.min(1, handling.adsProgress));
+            const sway = tuning.sway;
+            const swayMax = sway?.max ?? 0.08;
+            const swayScale = lerp(1, sway?.adsScale ?? 0.3, ads);
+            const per = sway?.perRadPerSec ?? 0.02;
+            const targetYaw = clamp(-input.lookYawRate * per, swayMax) * swayScale;
+            const targetPitch = clamp(-input.lookPitchRate * per, swayMax) * swayScale;
+            const follow = 1 - Math.exp(-(sway?.response ?? 12) * step);
+            state.swayYaw += (targetYaw - state.swayYaw) * follow;
+            state.swayPitch += (targetPitch - state.swayPitch) * follow;
+            const bob = tuning.bob;
+            const [bobX, bobY] = bob?.amplitude ?? DEFAULT_BOB;
+            const bobScale = Math.min(1, Math.max(0, input.speed) / Math.max(1e-6, bob?.fullSpeed ?? 4)) * lerp(1, bob?.adsScale ?? 0.25, ads);
+            const phase = input.bobPhase * TAU;
+            const recoil = Math.hypot(handling.aimPitch + handling.cameraPitch, handling.aimYaw + handling.cameraYaw);
+            const hip = tuning.hip ?? DEFAULT_VIEWMODEL_HIP;
+            const aimed = tuning.ads ?? DEFAULT_VIEWMODEL_ADS;
+            out.offset[0] = lerp(hip[0], aimed[0], ads) + Math.sin(phase) * bobX * bobScale;
+            out.offset[1] = lerp(hip[1], aimed[1], ads) - Math.abs(Math.sin(phase)) * bobY * bobScale;
+            out.offset[2] = lerp(hip[2], aimed[2], ads) + recoil * (tuning.kick?.back ?? 1.2);
+            out.pitch = state.swayPitch + recoil * (tuning.kick?.rise ?? 1.5);
+            out.yaw = state.swayYaw;
+            out.roll = state.swayYaw * 0.5;
+            const hipFov = tuning.viewmodelFov?.hip ?? tuning.viewmodelFov?.ads;
+            const adsFov = tuning.viewmodelFov?.ads ?? hipFov;
+            out.viewmodelFov = hipFov === undefined || adsFov === undefined ? null : lerp(hipFov, adsFov, ads);
+            out.fovScale = lerp(1, tuning.adsZoom ?? 1, ads);
+            out.lookPitch = handling.aimPitch + handling.cameraPitch;
+            out.lookYaw = handling.aimYaw + handling.cameraYaw;
+            out.aimPitch = handling.aimPitch;
+            out.aimYaw = handling.aimYaw;
+            out.adsProgress = ads;
+            return out;
+        },
+        pose: () => out,
+        retune(next) {
+            tuning = next;
+        },
+        snapshot: () => ({ ...state }),
+        restore(next) {
+            state.swayPitch = next.swayPitch;
+            state.swayYaw = next.swayYaw;
+        },
+        reset() {
+            state.swayPitch = 0;
+            state.swayYaw = 0;
+        },
+    };
+}
+/**
+ * Scale for a viewmodel drawn at `viewmodelFov` through a camera at `worldFov` (both degrees): multiply
+ * the viewmodel's camera-space x and y by this and it projects as if rendered with its own FOV, without
+ * a second camera or render pass.
+ */
+export function viewmodelFovScale(worldFov, viewmodelFov) {
+    const toHalf = (deg) => Math.tan((Math.max(1, Math.min(179, deg)) * Math.PI) / 360);
+    return toHalf(worldFov) / toHalf(viewmodelFov);
+}

package/dist/devtools/warnOnce.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Logs a dev-mode `console.warn` once per `site`, and never in a production build. Reach for it
+ * where a permissive config would otherwise fail silently — a clipped sky dome, an ignored tint.
+ * @capability warn-once emit a dev-only warning a single time per call site
+ */
+export declare function warnOnce(site: string, message: string): void;
+/** Clears the once-per-site record so a test can observe the warning again. @internal */
+export declare function resetWarnOnce(): void;

package/dist/devtools/warnOnce.js

@@ -0,0 +1,18 @@
+import { isProductionEnvironment } from "./saveEndpoint.js";
+const warned = new Set();
+/**
+ * Logs a dev-mode `console.warn` once per `site`, and never in a production build. Reach for it
+ * where a permissive config would otherwise fail silently — a clipped sky dome, an ignored tint.
+ * @capability warn-once emit a dev-only warning a single time per call site
+ */
+export function warnOnce(site, message) {
+    if (warned.has(site) || isProductionEnvironment())
+        return;
+    warned.add(site);
+    const host = globalThis;
+    host.console?.warn?.(message);
+}
+/** Clears the once-per-site record so a test can observe the warning again. @internal */
+export function resetWarnOnce() {
+    warned.clear();
+}

package/dist/economy/currency.d.ts

@@ -1,6 +1,8 @@
 export interface CurrencyDefinition<TCurrencyId extends string = string> {
     id: TCurrencyId;
     name: string;
+    /** Fractional digits in major-unit amounts; defaults to 0. */
+    decimals?: number;
     /** Prepended when formatting amounts (e.g. "$"). */
     symbol?: string;
     /** Appended when formatting amounts (e.g. "tokens"). */
@@ -16,7 +18,19 @@ export type CurrencyAdjustment = {
     reason: string;
 };
 /** @internal */
-export declare function sanitizeCurrencyAmount(amount: number): number;
+export declare function sanitizeCurrencyAmount(amount: number, currency?: CurrencyDefinition): number;
+/** Convert major units to integer minor units, rounding once at the write boundary.
+ * @capability currency-minor-units round decimal currency into safe integer minor units
+ */
+export declare function toMinorUnits(currency: Pick<CurrencyDefinition, "decimals"> | undefined, value: number): number;
+/** Convert stored integer minor units to major units for display or existing balance records.
+ * @capability currency-major-units convert safe minor-unit integers into currency amounts
+ */
+export declare function fromMinorUnits(currency: Pick<CurrencyDefinition, "decimals"> | undefined, value: number): number;
+/** Format a major-unit value using the currency's declared precision.
+ * @capability currency-precision-format display a currency using its declared decimal precision
+ */
+export declare function formatCurrency(currency: CurrencyDefinition, value: number): string;
 /**
  * Format a currency amount with its symbol and grouping for HUD display.
  *
@@ -31,7 +45,7 @@ export declare function applyCurrencyOperation(currency: CurrencyDefinition, cur
 /** Deducts clamp to the available balance (a delta can never overdraw); adds apply in full.
  * @internal
  */
-export declare function resolveCurrencyDelta(current: number, delta: number): {
+export declare function resolveCurrencyDelta(current: number, delta: number, currency?: CurrencyDefinition): {
     operation: CurrencyOperation;
     amount: number;
 };

package/dist/economy/currency.js

@@ -1,6 +1,43 @@
 /** @internal */
-export function sanitizeCurrencyAmount(amount) {
-    return Math.max(0, Math.floor(amount));
+export function sanitizeCurrencyAmount(amount, currency) {
+    if (!Number.isFinite(amount))
+        throw new RangeError("Currency amount must be finite");
+    return fromMinorUnits(currency, toMinorUnits(currency, Math.max(0, amount)));
+}
+function currencyScale(currency) {
+    const decimals = currency?.decimals ?? 0;
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 9) {
+        throw new RangeError("Currency decimals must be an integer between 0 and 9");
+    }
+    return 10 ** decimals;
+}
+/** Convert major units to integer minor units, rounding once at the write boundary.
+ * @capability currency-minor-units round decimal currency into safe integer minor units
+ */
+export function toMinorUnits(currency, value) {
+    if (!Number.isFinite(value))
+        throw new RangeError("Currency amount must be finite");
+    const scaled = value * currencyScale(currency);
+    const result = Math.sign(scaled) * Math.round(Math.abs(scaled) + Math.min(1e-7, Number.EPSILON * Math.abs(scaled)));
+    if (!Number.isSafeInteger(result))
+        throw new RangeError("Currency amount exceeds safe integer precision");
+    return result;
+}
+/** Convert stored integer minor units to major units for display or existing balance records.
+ * @capability currency-major-units convert safe minor-unit integers into currency amounts
+ */
+export function fromMinorUnits(currency, value) {
+    if (!Number.isSafeInteger(value))
+        throw new RangeError("Minor units must be a safe integer");
+    return value / currencyScale(currency);
+}
+/** Format a major-unit value using the currency's declared precision.
+ * @capability currency-precision-format display a currency using its declared decimal precision
+ */
+export function formatCurrency(currency, value) {
+    const decimals = currency.decimals ?? 0;
+    const rounded = fromMinorUnits(currency, toMinorUnits(currency, value));
+    return `${currency.symbol ?? ""}${rounded.toFixed(decimals)}${currency.unit ? ` ${currency.unit}` : ""}`;
 }
 /**
  * Format a currency amount with its symbol and grouping for HUD display.
@@ -9,9 +46,7 @@ export function sanitizeCurrencyAmount(amount) {
   * @internal
   */
 export function formatCurrencyAmount(currency, amount) {
-    const prefix = currency.symbol ?? "";
-    const suffix = currency.unit ? ` ${currency.unit}` : "";
-    return `${prefix}${amount}${suffix}`;
+    return formatCurrency(currency, amount);
 }
 /** @internal */
 export function insufficientCurrencyReason(currency, needed, current) {
@@ -19,20 +54,26 @@ export function insufficientCurrencyReason(currency, needed, current) {
 }
 /** @internal */
 export function applyCurrencyOperation(currency, current, operation, amount) {
-    const safeAmount = sanitizeCurrencyAmount(amount);
-    if (safeAmount === 0)
-        return { success: true, newBalance: current, appliedDelta: 0 };
-    if (operation === "deduct" && current < safeAmount) {
-        return { success: false, reason: insufficientCurrencyReason(currency, safeAmount, current) };
+    if (!Number.isFinite(amount) || amount < 0 || !Number.isFinite(current)) {
+        return { success: false, reason: "Invalid currency amount" };
+    }
+    const currentMinor = toMinorUnits(currency, current);
+    const amountMinor = toMinorUnits(currency, amount);
+    if (operation === "deduct" && currentMinor < amountMinor) {
+        return { success: false, reason: insufficientCurrencyReason(currency, fromMinorUnits(currency, amountMinor), current) };
     }
-    const appliedDelta = operation === "add" ? safeAmount : -safeAmount;
-    return { success: true, newBalance: current + appliedDelta, appliedDelta };
+    const deltaMinor = operation === "add" ? amountMinor : -amountMinor;
+    return {
+        success: true,
+        newBalance: fromMinorUnits(currency, currentMinor + deltaMinor),
+        appliedDelta: fromMinorUnits(currency, deltaMinor),
+    };
 }
 /** Deducts clamp to the available balance (a delta can never overdraw); adds apply in full.
  * @internal
  */
-export function resolveCurrencyDelta(current, delta) {
-    const safeDelta = Math.floor(delta);
+export function resolveCurrencyDelta(current, delta, currency) {
+    const safeDelta = fromMinorUnits(currency, toMinorUnits(currency, delta));
     if (safeDelta > 0)
         return { operation: "add", amount: safeDelta };
     return { operation: "deduct", amount: Math.min(Math.abs(safeDelta), current) };

package/dist/economy/wallet.d.ts

@@ -1,3 +1,4 @@
+import { type CurrencyDefinition } from "./currency.js";
 export interface WalletState {
     balances: Readonly<Record<string, number>>;
 }
@@ -31,16 +32,16 @@ export interface ChargeOptions {
  * @capability wallet hold currency balances with charge and affordability checks
  */
 export declare function createEmptyWallet(): WalletState;
-export declare function balance(state: WalletState, currency: string): number;
-export declare function grant(state: WalletState, currency: string, amount: number): WalletState;
+export declare function balance(state: WalletState, currency: string | CurrencyDefinition): number;
+export declare function grant(state: WalletState, currency: string | CurrencyDefinition, amount: number): WalletState;
 /**
  * Deduct `amount`, rejecting when it would leave the balance negative unless `options.overdraft`
  * opts into carrying debt (`true` unlimited, `{ max }` capped) — the strict same-tick affordability
  * check stays the default with `options` omitted.
  */
-export declare function charge(state: WalletState, currency: string, amount: number, options?: ChargeOptions): ChargeResult;
+export declare function charge(state: WalletState, currency: string | CurrencyDefinition, amount: number, options?: ChargeOptions): ChargeResult;
 /** True once `balance(state, currency)` has gone negative under an overdraft-enabled charge. */
-export declare function isOverdrawn(state: WalletState, currency: string): boolean;
+export declare function isOverdrawn(state: WalletState, currency: string | CurrencyDefinition): boolean;
 /** True when every currency in `costs` has at least that much balance (a pure, non-mutating check). */
 export declare function canAfford(state: WalletState, costs: Readonly<Record<string, number>>): boolean;
 export declare function chargeAll(state: WalletState, costs: Readonly<Record<string, number>>, options?: ChargeOptions): ChargeResult;

package/dist/economy/wallet.js

@@ -1,3 +1,4 @@
+import { fromMinorUnits, toMinorUnits } from "./currency.js";
 /**
  * Hold per-currency balances with affordability checks and charge/grant operations.
  *
@@ -12,14 +13,16 @@ function assertValidAmount(amount) {
     }
 }
 export function balance(state, currency) {
-    return state.balances[currency] ?? 0;
+    return state.balances[typeof currency === "string" ? currency : currency.id] ?? 0;
 }
 export function grant(state, currency, amount) {
     assertValidAmount(amount);
     return {
         balances: {
             ...state.balances,
-            [currency]: balance(state, currency) + amount,
+            [typeof currency === "string" ? currency : currency.id]: typeof currency === "string"
+                ? balance(state, currency) + amount
+                : fromMinorUnits(currency, toMinorUnits(currency, balance(state, currency)) + toMinorUnits(currency, amount)),
         },
     };
 }
@@ -40,7 +43,8 @@ function withinOverdraft(nextBalance, overdraft) {
 export function charge(state, currency, amount, options) {
     assertValidAmount(amount);
     const current = balance(state, currency);
-    const next = current - amount;
+    const next = typeof currency === "string" ? current - amount
+        : fromMinorUnits(currency, toMinorUnits(currency, current) - toMinorUnits(currency, amount));
     if (!withinOverdraft(next, options?.overdraft)) {
         return { status: "rejected", reason: "insufficient-funds" };
     }
@@ -49,7 +53,7 @@ export function charge(state, currency, amount, options) {
         state: {
             balances: {
                 ...state.balances,
-                [currency]: next,
+                [typeof currency === "string" ? currency : currency.id]: next,
             },
         },
     };

package/dist/editor/commandApply.js

@@ -447,6 +447,7 @@ const mutationHandlers = {
     }),
     setTerrain: (state, command) => ({ ...state, document: { ...state.document, terrain: command.terrain } }),
     setMinimapBake: (state, command) => ({ ...state, document: { ...state.document, minimap: command.minimap } }),
+    setBake: (state, command) => ({ ...state, document: { ...state.document, bakes: [...(state.document.bakes ?? []).filter((bake) => bake.id !== command.bake.id), command.bake] } }),
     setEnvironment: (state, command) => {
         if (command.environment === undefined) {
             const { environment: _removed, ...rest } = state.document;

package/dist/editor/commands.d.ts

@@ -2,7 +2,7 @@ import { type SurfaceDelta, type TerraformDelta, type TerrainMaterialLayer, type
 import type { EditorUiDocument, EditorUiPanelLayout } from "../ui/hudDocument.js";
 import type { EditorGridCellEdit, EditorGridLayer } from "./grid.js";
 import type { ParamSchema } from "../scene/sceneKinds.js";
-import type { EditorCatalogEntry, EditorDocument, EditorEnvironment, EditorMarker, EditorMinimapBake, EditorNote, EditorPath, EditorTerrain, EditorVec3, EditorVolume } from "./types.js";
+import type { EditorCatalogEntry, EditorBake, EditorDocument, EditorEnvironment, EditorMarker, EditorMinimapBake, EditorNote, EditorPath, EditorTerrain, EditorVec3, EditorVolume } from "./types.js";
 /** A single editor mutation — select, move, add, remove, undo/redo — dispatched to a session. */
 export type EditorCommand = {
     type: "select";
@@ -122,6 +122,9 @@ export type EditorCommand = {
 } | {
     type: "setMinimapBake";
     minimap: EditorMinimapBake;
+} | {
+    type: "setBake";
+    bake: EditorBake;
 }
 /**
  * Replace the scene-document environment/lighting bag. Pass `undefined` to clear authored sky/fog

package/dist/editor/document.d.ts

@@ -1,5 +1,5 @@
 import { type EditorGridLayer } from "./grid.js";
-import type { EditorCatalogData, EditorCatalogDefinition, EditorCatalogEntry, EditorCollection, EditorDirective, EditorDocument, EditorEnvironment, EditorFragmentContent, EditorLayersInput, EditorMarker, EditorMinimapBake, EditorNote, EditorPath, EditorPrefab, EditorTerrain, EditorVolume } from "./types.js";
+import type { EditorCatalogData, EditorBake, EditorCatalogDefinition, EditorCatalogEntry, EditorCollection, EditorDirective, EditorDocument, EditorEnvironment, EditorFragmentContent, EditorLayersInput, EditorMarker, EditorMinimapBake, EditorNote, EditorPath, EditorPrefab, EditorTerrain, EditorVolume } from "./types.js";
 /** Spread-ready non-placeable fields preserved across document rebuilds. @internal */
 export declare function editorDocumentExtras(doc: EditorDocument): {
     prefabs: EditorPrefab[];
@@ -10,6 +10,7 @@ export declare function editorDocumentExtras(doc: EditorDocument): {
     ui?: EditorDocument["ui"];
     directives?: EditorDirective[];
     minimap?: EditorMinimapBake;
+    bakes?: EditorBake[];
     environment?: EditorEnvironment;
 };
 /** Builds a fresh, empty editor document to start authoring a scene from scratch.

package/dist/editor/document.js

@@ -5,18 +5,28 @@ import { cloneGridLayer, migrateGridLayer, } from "./grid.js";
 function cloneMinimapBake(minimap) {
     return { background: minimap.background, bounds: { ...minimap.bounds } };
 }
+function cloneBakes(bakes) {
+    return bakes === undefined ? undefined : bakes.map((bake) => ({ ...bake, data: structuredClone(bake.data) }));
+}
 /** Deep-copies scene-document environment/lighting so edits never mutate history snapshots. */
 function cloneEnvironment(environment) {
     return {
+        ...(environment.source === undefined ? {} : { source: cloneEnvironmentSource(environment.source) }),
+        ...(environment.pointLights === undefined ? {} : { pointLights: environment.pointLights.map((light) => ({ ...light, position: [...light.position] })) }),
         ...(environment.preset === undefined ? {} : { preset: environment.preset }),
         ...(environment.timeOfDay === undefined ? {} : { timeOfDay: environment.timeOfDay }),
         ...(environment.horizonColor === undefined ? {} : { horizonColor: environment.horizonColor }),
         ...(environment.zenithColor === undefined ? {} : { zenithColor: environment.zenithColor }),
         ...(environment.sunIntensity === undefined ? {} : { sunIntensity: environment.sunIntensity }),
         ...(environment.ambientIntensity === undefined ? {} : { ambientIntensity: environment.ambientIntensity }),
+        ...(environment.sunAzimuth === undefined ? {} : { sunAzimuth: environment.sunAzimuth }),
+        ...(environment.sunElevation === undefined ? {} : { sunElevation: environment.sunElevation }),
         ...(environment.fog === undefined ? {} : { fog: { ...environment.fog } }),
     };
 }
+function cloneEnvironmentSource(source) {
+    return source.kind === "cube" ? { ...source, urls: [...source.urls] } : { ...source };
+}
 function cloneDirective(directive) {
     const area = directive.area === undefined
         ? undefined
@@ -66,6 +76,7 @@ export function editorDocumentExtras(doc) {
         ...(doc.ui === undefined ? {} : { ui: doc.ui }),
         ...(doc.directives === undefined ? {} : { directives: doc.directives }),
         ...(doc.minimap === undefined ? {} : { minimap: doc.minimap }),
+        ...(doc.bakes === undefined ? {} : { bakes: cloneBakes(doc.bakes) }),
         ...(doc.environment === undefined ? {} : { environment: doc.environment }),
     };
 }
@@ -147,6 +158,7 @@ export function cloneEditorDocument(doc) {
         ...(ui === undefined ? {} : { ui }),
         ...(directives === undefined ? {} : { directives }),
         ...(doc.minimap === undefined ? {} : { minimap: cloneMinimapBake(doc.minimap) }),
+        ...(doc.bakes === undefined ? {} : { bakes: cloneBakes(doc.bakes) }),
         ...(doc.environment === undefined ? {} : { environment: cloneEnvironment(doc.environment) }),
     };
 }
@@ -204,6 +216,7 @@ export function normalizeEditorLayers(input) {
         ...(ui === undefined ? {} : { ui }),
         ...(directives === undefined ? {} : { directives }),
         ...(resolved.minimap === undefined ? {} : { minimap: cloneMinimapBake(resolved.minimap) }),
+        ...(resolved.bakes === undefined ? {} : { bakes: cloneBakes(resolved.bakes) }),
         ...(resolved.environment === undefined ? {} : { environment: cloneEnvironment(resolved.environment) }),
     };
 }
@@ -949,6 +962,21 @@ function decodeMinimapBake(value, path, errors) {
         bounds: { minX: b.minX, minZ: b.minZ, maxX: b.maxX, maxZ: b.maxZ },
     };
 }
+function decodeBakes(value, path, errors) {
+    if (!Array.isArray(value)) {
+        errors.push({ path, message: "expected an array" });
+        return undefined;
+    }
+    const bakes = [];
+    value.forEach((item, index) => {
+        if (!isPlainObject(item) || (item.kind !== "nav" && item.kind !== "minimap") || typeof item.id !== "string" || item.data === undefined) {
+            errors.push({ path: `${path}[${index}]`, message: 'expected {kind: "nav" | "minimap", id, data}' });
+            return;
+        }
+        bakes.push({ kind: item.kind, id: item.id, data: structuredClone(item.data) });
+    });
+    return bakes;
+}
 const SKY_PRESETS = new Set(["day", "dusk", "night"]);
 /**
  * Validates scene-document environment/lighting. Unknown presets, non-finite intensities, and
@@ -962,6 +990,67 @@ function decodeEnvironment(value, path, errors) {
     }
     let failed = false;
     const env = {};
+    if (value.source !== undefined) {
+        const source = value.source;
+        if (!isPlainObject(source) || typeof source.kind !== "string") {
+            errors.push({ path: `${path}.source`, message: "expected an environment source object" });
+            failed = true;
+        }
+        else if (source.kind === "gradient") {
+            if (typeof source.sky !== "string") {
+                errors.push({ path: `${path}.source.sky`, message: "expected a string" });
+                failed = true;
+            }
+            if (typeof source.ground !== "string") {
+                errors.push({ path: `${path}.source.ground`, message: "expected a string" });
+                failed = true;
+            }
+            if (source.sun !== undefined && typeof source.sun !== "string") {
+                errors.push({ path: `${path}.source.sun`, message: "expected a string" });
+                failed = true;
+            }
+            if (source.intensity !== undefined && (typeof source.intensity !== "number" || !Number.isFinite(source.intensity))) {
+                errors.push({ path: `${path}.source.intensity`, message: "expected a finite number" });
+                failed = true;
+            }
+            if (!failed)
+                env.source = { kind: "gradient", sky: source.sky, ground: source.ground, ...(source.sun === undefined ? {} : { sun: source.sun }), ...(source.intensity === undefined ? {} : { intensity: source.intensity }) };
+        }
+        else if (source.kind === "hdri" && typeof source.url === "string") {
+            env.source = { kind: "hdri", url: source.url, ...(typeof source.rotation === "number" ? { rotation: source.rotation } : {}), ...(typeof source.intensity === "number" ? { intensity: source.intensity } : {}) };
+        }
+        else if (source.kind === "cube" && Array.isArray(source.urls) && source.urls.length === 6 && source.urls.every((url) => typeof url === "string")) {
+            env.source = { kind: "cube", urls: [...source.urls], ...(typeof source.intensity === "number" ? { intensity: source.intensity } : {}) };
+        }
+        else {
+            errors.push({ path: `${path}.source`, message: 'expected kind "gradient", "hdri", or "cube" with valid fields' });
+            failed = true;
+        }
+    }
+    if (value.pointLights !== undefined) {
+        if (!Array.isArray(value.pointLights)) {
+            errors.push({ path: `${path}.pointLights`, message: "expected an array" });
+            failed = true;
+        }
+        else if (value.pointLights.length > 64 || value.pointLights.some((light) => {
+            if (!isPlainObject(light) || !Array.isArray(light.position) || light.position.length !== 3 || light.position.some((n) => typeof n !== "number" || !Number.isFinite(n)))
+                return true;
+            return light.intensity !== undefined && (typeof light.intensity !== "number" || !Number.isFinite(light.intensity));
+        })) {
+            errors.push({ path: `${path}.pointLights`, message: "expected point lights with finite positions and intensities" });
+            failed = true;
+        }
+        else {
+            env.pointLights = value.pointLights.map((light) => ({
+                position: [...light.position],
+                ...(typeof light.color === "string" ? { color: light.color } : {}),
+                ...(typeof light.intensity === "number" ? { intensity: light.intensity } : {}),
+                ...(typeof light.distance === "number" ? { distance: light.distance } : {}),
+                ...(typeof light.decay === "number" ? { decay: light.decay } : {}),
+                ...(typeof light.castShadow === "boolean" ? { castShadow: light.castShadow } : {}),
+            }));
+        }
+    }
     if (value.preset !== undefined) {
         if (typeof value.preset === "string" && SKY_PRESETS.has(value.preset)) {
             env.preset = value.preset;
@@ -995,7 +1084,7 @@ function decodeEnvironment(value, path, errors) {
             failed = true;
         }
     }
-    for (const key of ["sunIntensity", "ambientIntensity"]) {
+    for (const key of ["sunIntensity", "ambientIntensity", "sunAzimuth", "sunElevation"]) {
         if (value[key] === undefined)
             continue;
         if (typeof value[key] === "number" && Number.isFinite(value[key]))
@@ -1152,6 +1241,7 @@ export function decodeEditorDocument(raw) {
         errors.push({ path: "$.terrain", message: "expected an object" });
     }
     const minimap = raw.minimap === undefined ? undefined : decodeMinimapBake(raw.minimap, "$.minimap", errors);
+    const bakes = raw.bakes === undefined ? undefined : decodeBakes(raw.bakes, "$.bakes", errors);
     const environment = raw.environment === undefined ? undefined : decodeEnvironment(raw.environment, "$.environment", errors);
     // Placeable object ids form one document-global namespace (selection, parenting, and removal all
     // treat them that way), so a document that reuses an id — even across two different collections —
@@ -1194,6 +1284,7 @@ export function decodeEditorDocument(raw) {
             ...(ui === undefined ? {} : { ui }),
             ...(directives === undefined ? {} : { directives }),
             ...(minimap === undefined ? {} : { minimap }),
+            ...(bakes === undefined && minimap === undefined ? {} : { bakes: bakes ?? [{ kind: "minimap", id: "minimap", data: minimap }] }),
             ...(environment === undefined ? {} : { environment }),
         },
     };