@jgengine/core 0.17.0 → 0.18.1

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,9 +5,14 @@ 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 }),
@@ -17,6 +22,9 @@ function cloneEnvironment(environment) {
         ...(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 +74,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 +156,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 +214,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 +960,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 +988,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;
@@ -1152,6 +1239,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 +1282,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 }),
         },
     };

package/dist/editor/environment.d.ts

@@ -3,6 +3,7 @@ import type { AvoidZone } from "../world/geometry.js";
 import { type ClearanceOptions } from "../world/scatterRegion.js";
 import type { TerraformSnapshot } from "../world/terraform.js";
 import type { EditorDocument, EditorEnvironment } from "./types.js";
+import type { LightingConfig } from "../game/playableGame.js";
 /**
  * World-authoring convergence (#1018, epic #1006 Phase 4): derive the **coordinate/placement**
  * content of an `environment()` world from the scene document, so a game with an authored document
@@ -46,6 +47,8 @@ export declare function skyFromDocument(doc: EditorDocument): SkyEnvironmentConf
  * @internal
  */
 export declare function skyConfigFromEnvironment(env: EditorEnvironment): SkyEnvironmentConfig;
+/** Converts authored `light` markers into the runtime lighting contract. */
+export declare function lightingFromDocument(doc: EditorDocument): LightingConfig | undefined;
 /**
  * The origin-centered terrain footprint that covers every authored object in a document, padded and
  * floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()`

package/dist/editor/environment.js

@@ -28,6 +28,22 @@ export function skyConfigFromEnvironment(env) {
         ...(env.fog === undefined ? {} : { fog: { ...env.fog } }),
     };
 }
+/** Converts authored `light` markers into the runtime lighting contract. */
+export function lightingFromDocument(doc) {
+    const points = [];
+    const spots = [];
+    for (const marker of doc.markers) {
+        if (marker.kind !== "light" || marker.position === undefined)
+            continue;
+        const meta = marker.meta ?? {};
+        const base = { position: [marker.position.x, marker.position.y, marker.position.z], color: typeof meta.color === "string" ? meta.color : "#ffd6a0", intensity: typeof meta.intensity === "number" ? meta.intensity : 2, distance: typeof meta.range === "number" ? meta.range : 12, castShadow: meta.castShadow === true };
+        if (meta.type === "spot")
+            spots.push({ ...base, angle: typeof meta.angle === "number" ? meta.angle : Math.PI / 6 });
+        else
+            points.push(base);
+    }
+    return points.length === 0 && spots.length === 0 ? undefined : { point: points, spot: spots };
+}
 /**
  * The origin-centered terrain footprint that covers every authored object in a document, padded and
  * floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()`

package/dist/editor/index.d.ts

@@ -5,7 +5,9 @@ export type { EditorTerrain } from "./types.js";
 /** A baked top-down minimap (PNG data URI + world bounds) persisted on the scene document. */
 export type { EditorMinimapBake } from "./types.js";
 /** Scene-document sky/fog/lighting bag edited by the lighting workspace. */
-export type { EditorEnvironment, EditorFogConfig, EditorSkyPreset } from "./types.js";
+export type { EditorEnvironment, EditorFogConfig, EditorSkyPreset, PointLightingConfig } from "./types.js";
+/** Declarative HDRI, cube, or gradient environment source used by the shell. */
+export type { EnvironmentSource } from "../render/environment.js";
 /** Per-kind show/hide flags for the editor's layer panel. */
 export type { EditorKindVisibility } from "./types.js";
 /** The four placeable-object collections a prefab fragment or clipboard fragment carries. */
@@ -62,7 +64,7 @@ export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWo
 export type { DecodeWorldManifestResult, SplitWorldOptions, SplitWorldResult, WorldGrid, WorldManifest, WorldManifestShard, WorldQuery, WorldShardBounds, WorldShardResidency, WorldShardResolver, WorldStreamingConfig, } from "./world.js";
 /** Result of {@link decodeEditorDocument}: a typed document, or every diagnostic collected while decoding it. */
 export type { DecodeEditorDocumentResult } from "./document.js";
-export { environmentContentFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+export { environmentContentFromDocument, lightingFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
 /** Coordinate/placement content of an `environment()` world derived from the scene document. */
 export type { EnvironmentContent, EnvironmentContentOptions } from "./environment.js";
 export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";

package/dist/editor/index.js

@@ -3,7 +3,7 @@ export { ENTITY_CATALOG_ID, entityDefinitionSchema, entityEntryFromCatalog, reso
 export { WELL_KNOWN_MARKER_KINDS, WELL_KNOWN_PATH_KINDS, WELL_KNOWN_VOLUME_KINDS, } from "./types.js";
 export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorMarkerPosition, editorMarkerXZ, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectCollectionLocked, isEditorObjectHidden, isEditorObjectLocked, isEditorObjectSelfLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, requireEditorMarker, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
 export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWorldManifestJson, loadWorldDocument, selectWorldShards, shardMatchesQuery, singleShardWorldManifest, splitEditorDocumentIntoShards, } from "./world.js";
-export { environmentContentFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+export { environmentContentFromDocument, lightingFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
 export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";
 export { createWorldStreamer, shardDistance } from "./streamer.js";
 export { applyDirectiveOverlay, materializeDirective, materializeDirectives, materializePopulationDirective, materializeScatterDirective, resolveDirectiveFootprint, } from "./directives.js";

package/dist/editor/types.d.ts

@@ -3,6 +3,10 @@ import type { EditorUiDocument } from "../ui/hudDocument.js";
 import type { MinimapBakeBounds } from "../world/minimapBake.js";
 import type { TerraformSnapshot } from "../world/terraform.js";
 import type { EditorGridLayer } from "./grid.js";
+import type { EnvironmentSource } from "../render/environment.js";
+import type { PointLightingConfig } from "../game/playableGame.js";
+/** Runtime point-light shape reused by authored editor light markers. */
+export type { PointLightingConfig } from "../game/playableGame.js";
 export type { EditorUiDocument, EditorUiPanelLayout, HudResizeAxes, HudPanelTypeDef } from "../ui/hudDocument.js";
 /** A world-space point used across editor markers, volumes, and paths. */
 export type EditorVec3 = {
@@ -177,6 +181,12 @@ export interface EditorMinimapBake {
     /** World-space rectangle the baked image spans. */
     bounds: MinimapBakeBounds;
 }
+/** A named baked artifact produced by an editor or build tool. */
+export interface EditorBake {
+    kind: "nav" | "minimap";
+    id: string;
+    data: unknown;
+}
 /** Named sky look stored on the scene document; matches runtime `SkyEnvironmentConfig.preset`. */
 export type EditorSkyPreset = "day" | "dusk" | "night";
 /**
@@ -197,6 +207,10 @@ export interface EditorFogConfig {
  * @capability editor-environment persist sky/fog/lighting knobs on the scene document
  */
 export interface EditorEnvironment {
+    /** Optional runtime environment map source; absent keeps the procedural gradient. */
+    source?: EnvironmentSource;
+    /** Authored local point lights; the runtime clamps these to its bounded light budget. */
+    pointLights?: readonly PointLightingConfig[];
     /** Fixed sky look when `timeOfDay` is off (or no clock is available). */
     preset?: EditorSkyPreset;
     /** Drive sun/sky from the world clock's day fraction instead of the fixed `preset`. */
@@ -246,6 +260,8 @@ export interface EditorDocument {
      * until baked, so old docs and unbaked games load unchanged.
      */
     minimap?: EditorMinimapBake;
+    /** Named baked artifacts; `minimap` remains as a compatible legacy alias. */
+    bakes?: EditorBake[];
     /**
      * Scene-document sky/fog/lighting (#1110). Absent until authored in the lighting workspace or
      * seeded via `editorLayers`, so old docs load unchanged and world.ts can keep a fallback sky.

package/dist/game/cameraConfig.d.ts

@@ -45,6 +45,12 @@ export interface FirstPersonCameraConfig {
 export type CameraRigKind = "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer" | "turntable" | "sideScroll" | "inspection" | "none";
 /** Canvas camera projection. "orthographic" renders a flat 2D-style view (side-scrollers, falling-block puzzles) — pair with `rig: "sideScroll"`; default "perspective". */
 export type CameraProjection = "perspective" | "orthographic";
+/** Pixel-art orthographic camera tuning. `pixelsPerUnit` is the authored pixel density. */
+export interface PixelPerfectCameraConfig {
+    pixelsPerUnit: number;
+    /** Increase density in whole-number steps to use the largest scale that fits the viewport. */
+    integerScale?: boolean;
+}
 /** Fixed lateral 2.5D follow (side-on platformer cam): the camera sits perpendicular to the travel axis, tracks the followed entity, and never reads player look input. */
 export interface SideScrollCameraConfig {
     /** World axis the action travels along; the camera watches from the perpendicular side. Default "x". */
@@ -378,6 +384,8 @@ export interface GameCameraConfig {
     rig?: CameraRigKind;
     /** Canvas camera projection. "orthographic" renders a flat 2D-style view (side-scrollers, falling-block puzzles) — pair with `rig: "sideScroll"`; default perspective. */
     projection?: CameraProjection;
+    /** Pixel-perfect orthographic rendering; ignored for perspective cameras. */
+    pixelPerfect?: PixelPerfectCameraConfig;
     /** Render frustum overrides applied to the canvas camera. `far` defaults to 300 — raise it for worlds whose content spans more than a few hundred units, or distant scenery silently clips. `zoom` is the orthographic zoom in canvas pixels per world unit, read only when `projection` is "orthographic"; default 50. */
     frustum?: {
         fov?: number;

package/dist/game/chat.d.ts

@@ -30,11 +30,18 @@ export type ChatSendResult = {
 export interface ChatSnapshot {
     messages: Record<string, ChatMessage[]>;
     counter: number;
+    rateWindows?: Record<string, Record<string, number[]>>;
 }
 export interface Chat {
     register(def: ChatChannelDef): void;
     channels(): ChatChannelDef[];
+    send(fromUserId: string, body: string): ChatSendResult;
     send(fromUserId: string, channelId: string, body: string): ChatSendResult;
+    recent(options?: {
+        limit?: number;
+        channelId?: string;
+        viewerUserId?: string;
+    }): ChatMessage[];
     whisper(fromUserId: string, toUserId: string, body: string): ChatSendResult;
     history(channelId: string, options?: {
         limit?: number;
@@ -57,12 +64,26 @@ export interface ChatDeps {
 }
 export declare const DEFAULT_CHAT_RATE_LIMIT: ChatRateLimit;
 export declare const DEFAULT_CHAT_HISTORY_LIMIT = 100;
-export declare const DEFAULT_CHAT_BODY_LENGTH = 500;
+export declare const DEFAULT_CHAT_BODY_LENGTH = 240;
 export declare const DEFAULT_PROXIMITY_CHAT_RADIUS = 20;
 export declare const WHISPER_CHANNEL_PREFIX = "whisper:";
 export declare function whisperChannelId(a: string, b: string): string;
 export interface ChatRateLimiter {
     allow(key: string, atMs: number): boolean;
+    snapshot(): Record<string, number[]>;
+    restore(state: Record<string, number[]>): void;
 }
 export declare function createChatRateLimiter(limit: ChatRateLimit): ChatRateLimiter;
 export declare function createChat(deps: ChatDeps): Chat;
+/** Sanitized chat text or a displayable validation failure. */
+export type ChatValidation = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Strip control characters and enforce the shared chat message policy before storage or broadcast. */
+export declare function validateChatMessage(value: unknown, options?: {
+    maxLength?: number;
+}): ChatValidation;