@3driseai/3drise-core 1.0.20 → 1.0.22

package/dist/utils/getAnimatableProperties.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getAnimatableProperties.d.ts","sourceRoot":"","sources":["../../src/utils/getAnimatableProperties.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE7G,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,qBAAqB,CAAC;AAEtE,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;AAElI,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACvC,aAAa,CAAC,EAAE;QACZ,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC1C,CAAC;IACF,MAAM,CAAC,EAAE,CAAC;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACzB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,SAAS,CAAC,EAAE,qBAAqB,GAAG,oBAAoB,CAAC;CAC5D;AAmBD,4CAA4C;AAC5C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKrD;AAUD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,EAAE,CAMlH;AAKD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAUhH"}
+{"version":3,"file":"getAnimatableProperties.d.ts","sourceRoot":"","sources":["../../src/utils/getAnimatableProperties.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE7G,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,qBAAqB,CAAC;AAEtE,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5M,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACvC,aAAa,CAAC,EAAE;QACZ,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC1C,CAAC;IACF,MAAM,CAAC,EAAE,CAAC;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACzB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,SAAS,CAAC,EAAE,qBAAqB,GAAG,oBAAoB,CAAC;CAC5D;AAmBD,4CAA4C;AAC5C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKrD;AAUD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,EAAE,CAMlH;AAKD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAUhH"}

package/dist/utils/getAnimatableProperties.js

@@ -41,7 +41,7 @@ export function getAnimatableProperties(settings, domain) {
         .map(toAnimatable);
 }
 /** Domain priority when a name exists in more than one (edges before material: an edges key shadows the mesh's). */
-const DETECT_ORDER = ['edges', 'light', 'effect', 'grid', 'particles', 'clouds', 'rain', 'material'];
+const DETECT_ORDER = ['edges', 'light', 'effect', 'grid', 'environment', 'space', 'land', 'text', 'particles', 'clouds', 'rain', 'sky', 'ocean', 'terrain', 'material'];
 /**
  * Detect which domain a property name belongs to, for a given target. Used by
  * the runtime + UI to migrate flat MouseMove arrays into the new per-domain

package/dist/utils/gridMigration.d.ts

@@ -0,0 +1,3 @@
+import type { CreatedObjectSettings } from '../types/scene3d';
+export declare function migrateGridObject<T extends CreatedObjectSettings>(obj: T): T;
+//# sourceMappingURL=gridMigration.d.ts.map

package/dist/utils/gridMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gridMigration.d.ts","sourceRoot":"","sources":["../../src/utils/gridMigration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAoB9D,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,qBAAqB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAgB5E"}

package/dist/utils/gridMigration.js

@@ -0,0 +1,34 @@
+import { Euler, Quaternion } from 'three';
+// =============================================================================
+// Grids — load-time migration of the legacy surface knobs
+// =============================================================================
+//
+// Every grid now lies flat in its own frame (the plane on local XZ, facing +Y);
+// standing it up is the parent object's rotation, and pointer behaviour is a
+// Pointer-tab binding. Older grids carried two knobs for that:
+//   flat: false   the plane stood upright on local XY. Kept as it looked by
+//                 turning the object +90° about its own X axis, so the now-flat
+//                 plane ends up exactly where the upright one was.
+//   followMouse   the ripple focus tracked the cursor. Dropped: the focus stays
+//                 at the grid's centre.
+// Both keys are removed. Pure and idempotent: returns the same object when there
+// is nothing to migrate, so it can run on every load without marking anything dirty.
+//
+const UPRIGHT = new Quaternion().setFromEuler(new Euler(Math.PI / 2, 0, 0));
+export function migrateGridObject(obj) {
+    if (!obj || obj.type !== 'grid')
+        return obj;
+    const config = obj.config;
+    if (!config || (!('flat' in config) && !('followMouse' in config)))
+        return obj;
+    const { flat, followMouse: _followMouse, ...rest } = config;
+    const next = { ...obj, config: rest };
+    if (flat === false) {
+        const mesh = obj.meshSettings ?? {};
+        const r = Array.isArray(mesh.rotation) ? mesh.rotation : [0, 0, 0];
+        const q = new Quaternion().setFromEuler(new Euler(r[0] ?? 0, r[1] ?? 0, r[2] ?? 0)).multiply(UPRIGHT);
+        const e = new Euler().setFromQuaternion(q);
+        next.meshSettings = { ...mesh, rotation: [e.x, e.y, e.z] };
+    }
+    return next;
+}

package/dist/utils/index.d.ts

@@ -16,6 +16,7 @@ export * from './meshUtils';
 export * from './pathUtils';
 export * from './positionsCreatorUtils';
 export * from './sunUtils';
+export * from './skyPhase';
 export * from './utils';
 export * from './edgeUtils';
 export * from './surfaceUtils';
@@ -33,6 +34,10 @@ export * from './handleEdgesMouseMove';
 export * from './handleLightMouseMove';
 export * from './sceneQuery';
 export * from './shootingStarHelpers';
+export * from './spaceMigration';
+export * from './gridMigration';
+export * from './environmentMigration';
+export * from './objectMigration';
 export * from './environmentUtils';
 export * from './MaterialCompiler';
 export * from './nodeOverrides';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC"}

package/dist/utils/index.js

@@ -16,6 +16,7 @@ export * from './meshUtils.js';
 export * from './pathUtils.js';
 export * from './positionsCreatorUtils.js';
 export * from './sunUtils.js';
+export * from './skyPhase.js';
 export * from './utils.js';
 export * from './edgeUtils.js';
 export * from './surfaceUtils.js';
@@ -33,6 +34,10 @@ export * from './handleEdgesMouseMove.js';
 export * from './handleLightMouseMove.js';
 export * from './sceneQuery.js';
 export * from './shootingStarHelpers.js';
+export * from './spaceMigration.js';
+export * from './gridMigration.js';
+export * from './environmentMigration.js';
+export * from './objectMigration.js';
 export * from './environmentUtils.js';
 export * from './MaterialCompiler.js';
 export * from './nodeOverrides.js';

package/dist/utils/objectEffects.d.ts

@@ -1,6 +1,28 @@
-import type { ObjectEffect } from '../types/objectSettings';
-/** The object effects of a stored object — entries of any older shape (generative effects) are dropped. */
+import type { EffectSpread, EffectSteps, ObjectEffect, ObjectEffectClip } from '../types/objectSettings';
+/**
+ * Visual effects layer GLSL onto three's standard materials, so they take only objects drawn with
+ * them: meshes, models and the legacy 2d / 3d text. Every other scene object (particles, grids, text
+ * looks, lights, weather, space, generative effects…) takes physical (transform) effects only, for now —
+ * they move the object's group, whatever draws inside it.
+ */
+export declare function objectTakesVisualEffects(o: {
+    type?: string;
+    config?: unknown;
+} | null | undefined): boolean;
+/** A group's stagger when its clip sets none (see EffectSpread). */
+export declare const DEFAULT_EFFECT_SPREAD: Required<EffectSpread>;
+/** An object's effect clip (`effects`), or an empty one. The stored value itself — identity stays stable. */
+export declare function objectEffectClipOf(settings: {
+    effects?: unknown;
+} | null | undefined): ObjectEffectClip;
+/** The object's Base effects (well-formed entries only). */
 export declare function objectEffectsOf(settings: {
     effects?: unknown;
 } | null | undefined): ObjectEffect[];
+/** The steps of an effect clip as the effects controller takes them, or null when it has none. */
+export declare function objectEffectStepsOf(clip: ObjectEffectClip | null | undefined): EffectSteps | null;
+/** The object with its effect clip changed (Base effects normalised, the rest kept). */
+export declare function withObjectEffectClip<T extends {
+    effects?: unknown;
+}>(settings: T, patch: Partial<ObjectEffectClip>): T;
 //# sourceMappingURL=objectEffects.d.ts.map

package/dist/utils/objectEffects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"objectEffects.d.ts","sourceRoot":"","sources":["../../src/utils/objectEffects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,2GAA2G;AAC3G,wBAAgB,eAAe,CAAC,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,EAAE,CAGlG"}
+{"version":3,"file":"objectEffects.d.ts","sourceRoot":"","sources":["../../src/utils/objectEffects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGzG;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAG3G;AAED,oEAAoE;AACpE,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,YAAY,CAAiD,CAAC;AAI3G,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,gBAAgB,CAGvG;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,EAAE,CAGlG;AAED,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAEjG;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,CAAC,SAAS;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAEtH"}

package/dist/utils/objectEffects.js

@@ -1,5 +1,32 @@
-/** The object effects of a stored object — entries of any older shape (generative effects) are dropped. */
+import { isTextObjectConfig } from '../data/textDefaults.js';
+/**
+ * Visual effects layer GLSL onto three's standard materials, so they take only objects drawn with
+ * them: meshes, models and the legacy 2d / 3d text. Every other scene object (particles, grids, text
+ * looks, lights, weather, space, generative effects…) takes physical (transform) effects only, for now —
+ * they move the object's group, whatever draws inside it.
+ */
+export function objectTakesVisualEffects(o) {
+    // a group never draws an effect itself: its visual effects go to each child that takes them
+    return o?.type === 'mesh' || o?.type === 'model' || o?.type === 'group' || (o?.type === 'text' && !isTextObjectConfig(o.config));
+}
+/** A group's stagger when its clip sets none (see EffectSpread). */
+export const DEFAULT_EFFECT_SPREAD = { order: 'tree', total: 0.6, out: 'reverse' };
+const EMPTY = Object.freeze({ effects: [] });
+/** An object's effect clip (`effects`), or an empty one. The stored value itself — identity stays stable. */
+export function objectEffectClipOf(settings) {
+    const c = settings?.effects;
+    return c && typeof c === 'object' && !Array.isArray(c) ? c : EMPTY;
+}
+/** The object's Base effects (well-formed entries only). */
 export function objectEffectsOf(settings) {
-    const list = settings?.effects;
+    const list = objectEffectClipOf(settings).effects;
     return Array.isArray(list) ? list.filter((e) => e && typeof e.operation === 'string' && typeof e.id === 'string') : [];
 }
+/** The steps of an effect clip as the effects controller takes them, or null when it has none. */
+export function objectEffectStepsOf(clip) {
+    return clip?.steps?.length ? { steps: clip.steps, loop: clip.loop, yoyo: clip.yoyo } : null;
+}
+/** The object with its effect clip changed (Base effects normalised, the rest kept). */
+export function withObjectEffectClip(settings, patch) {
+    return { ...settings, effects: { ...objectEffectClipOf(settings), effects: objectEffectsOf(settings), ...patch } };
+}

package/dist/utils/objectMigration.d.ts

@@ -0,0 +1,9 @@
+import type { CreatedObjectSettings } from '../types/scene3d';
+/**
+ * Every load-time migration of saved scene objects, in one pass. Each step is
+ * pure, idempotent and returns the same object when there is nothing to change,
+ * so this runs on every load (objectsSlice, the viewer ProjectLoader). A family
+ * whose saved shape changes adds its step here.
+ */
+export declare function migrateObject<T extends CreatedObjectSettings>(obj: T): T;
+//# sourceMappingURL=objectMigration.d.ts.map

package/dist/utils/objectMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectMigration.d.ts","sourceRoot":"","sources":["../../src/utils/objectMigration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAK9D;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,qBAAqB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAExE"}

package/dist/utils/objectMigration.js

@@ -0,0 +1,12 @@
+import { migrateSpaceObject } from './spaceMigration.js';
+import { migrateGridObject } from './gridMigration.js';
+import { migrateEnvironmentObject } from './environmentMigration.js';
+/**
+ * Every load-time migration of saved scene objects, in one pass. Each step is
+ * pure, idempotent and returns the same object when there is nothing to change,
+ * so this runs on every load (objectsSlice, the viewer ProjectLoader). A family
+ * whose saved shape changes adds its step here.
+ */
+export function migrateObject(obj) {
+    return migrateEnvironmentObject(migrateGridObject(migrateSpaceObject(obj)));
+}

package/dist/utils/skyPhase.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Time-of-day phases, keyed by SUN ELEVATION — never by the clock.
+ *
+ * Everything that changes with the time of day (the Preetham atmosphere, star
+ * visibility, labels) reads these, so they all turn at the moment the sun
+ * actually crosses the horizon, whatever sunrise/sunset hours or sun model is in
+ * use. There used to be six hour tables that disagreed by up to 1.5 h.
+ *
+ * Keys, in degrees of sun elevation:
+ *   night     ≤ −12  (astronomical-ish: sky fully dark)
+ *   twilight    −4   (blue hour, sun just below the horizon)
+ *   golden       3   (sun on the horizon: reddest, haziest)
+ *   day       ≥ 15
+ * Between two keys the weights cross-fade with a smoothstep; they always sum to 1.
+ */
+export interface SkyPhaseWeights {
+    night: number;
+    twilight: number;
+    golden: number;
+    day: number;
+}
+export interface SkyAtmosphere {
+    turbidity: number;
+    rayleigh: number;
+    mieCoefficient: number;
+    mieDirectionalG: number;
+}
+export declare const SKY_PHASE_ELEVATIONS: {
+    readonly night: -12;
+    readonly twilight: -4;
+    readonly golden: 3;
+    readonly day: 15;
+};
+/** Built-in atmospheres for the non-day phases. The day look is the user's own
+ *  sky settings (see atmosphereForSunElevation). */
+export declare const SKY_PHASE_ATMOSPHERES: Record<'night' | 'twilight' | 'golden', SkyAtmosphere>;
+/** Phase weights for a sun elevation in degrees. Sum to 1. */
+export declare function skyPhaseWeights(sunElevation: number, out?: SkyPhaseWeights): SkyPhaseWeights;
+/**
+ * The Preetham atmosphere for a sun elevation: the user's `day` look by day,
+ * blended through golden hour and twilight into night as the sun goes down.
+ * The user's sliders, keyframes and pointer bindings keep working with the clock
+ * on — they shape the day, and time of day adds the evening around it.
+ */
+export declare function atmosphereForSunElevation(sunElevation: number, day: SkyAtmosphere, out?: SkyAtmosphere): SkyAtmosphere;
+/** How visible the night sky is (stars, moon halo): 0 by day, 1 once the sun is
+ *  12° down. */
+export declare function nightAmount(sunElevation: number): number;
+/**
+ * How bright the sky dome is drawn, 1 by day. Preetham alone never gets darker
+ * than a flat grey after sunset (its constant 0.1 base term), so the night reads
+ * as overcast dusk instead of night. SkyMesh multiplies its output by this.
+ */
+export declare const SKY_PHASE_BRIGHTNESS: {
+    readonly night: 0.08;
+    readonly twilight: 0.5;
+    readonly golden: 1;
+    readonly day: 1;
+};
+export declare function skyBrightnessForSunElevation(sunElevation: number): number;
+//# sourceMappingURL=skyPhase.d.ts.map

package/dist/utils/skyPhase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skyPhase.d.ts","sourceRoot":"","sources":["../../src/utils/skyPhase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,oBAAoB;;;;;CAA4D,CAAC;AAE9F;oDACoD;AACpD,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,OAAO,GAAG,UAAU,GAAG,QAAQ,EAAE,aAAa,CAIxF,CAAC;AAOF,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,eAAe,CAmB5F;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,aAAa,GAAG,aAAa,CAStH;AAED;gBACgB;AAChB,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;CAA6D,CAAC;AAE/F,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAIzE"}

package/dist/utils/skyPhase.js

@@ -0,0 +1,93 @@
+/**
+ * Time-of-day phases, keyed by SUN ELEVATION — never by the clock.
+ *
+ * Everything that changes with the time of day (the Preetham atmosphere, star
+ * visibility, labels) reads these, so they all turn at the moment the sun
+ * actually crosses the horizon, whatever sunrise/sunset hours or sun model is in
+ * use. There used to be six hour tables that disagreed by up to 1.5 h.
+ *
+ * Keys, in degrees of sun elevation:
+ *   night     ≤ −12  (astronomical-ish: sky fully dark)
+ *   twilight    −4   (blue hour, sun just below the horizon)
+ *   golden       3   (sun on the horizon: reddest, haziest)
+ *   day       ≥ 15
+ * Between two keys the weights cross-fade with a smoothstep; they always sum to 1.
+ */
+export const SKY_PHASE_ELEVATIONS = { night: -12, twilight: -4, golden: 3, day: 15 };
+/** Built-in atmospheres for the non-day phases. The day look is the user's own
+ *  sky settings (see atmosphereForSunElevation). */
+export const SKY_PHASE_ATMOSPHERES = {
+    night: { turbidity: 0.5, rayleigh: 0.1, mieCoefficient: 0.001, mieDirectionalG: 0.8 },
+    twilight: { turbidity: 2.5, rayleigh: 2.0, mieCoefficient: 0.008, mieDirectionalG: 0.86 },
+    golden: { turbidity: 4.5, rayleigh: 3.5, mieCoefficient: 0.012, mieDirectionalG: 0.92 },
+};
+const smooth = (t) => {
+    const c = Math.max(0, Math.min(1, t));
+    return c * c * (3 - 2 * c);
+};
+/** Phase weights for a sun elevation in degrees. Sum to 1. */
+export function skyPhaseWeights(sunElevation, out) {
+    const w = out ?? { night: 0, twilight: 0, golden: 0, day: 0 };
+    w.night = 0;
+    w.twilight = 0;
+    w.golden = 0;
+    w.day = 0;
+    const { night, twilight, golden, day } = SKY_PHASE_ELEVATIONS;
+    if (sunElevation <= night) {
+        w.night = 1;
+        return w;
+    }
+    if (sunElevation >= day) {
+        w.day = 1;
+        return w;
+    }
+    if (sunElevation < twilight) {
+        const t = smooth((sunElevation - night) / (twilight - night));
+        w.night = 1 - t;
+        w.twilight = t;
+    }
+    else if (sunElevation < golden) {
+        const t = smooth((sunElevation - twilight) / (golden - twilight));
+        w.twilight = 1 - t;
+        w.golden = t;
+    }
+    else {
+        const t = smooth((sunElevation - golden) / (day - golden));
+        w.golden = 1 - t;
+        w.day = t;
+    }
+    return w;
+}
+/**
+ * The Preetham atmosphere for a sun elevation: the user's `day` look by day,
+ * blended through golden hour and twilight into night as the sun goes down.
+ * The user's sliders, keyframes and pointer bindings keep working with the clock
+ * on — they shape the day, and time of day adds the evening around it.
+ */
+export function atmosphereForSunElevation(sunElevation, day, out) {
+    const w = skyPhaseWeights(sunElevation);
+    const { night: n, twilight: t, golden: g } = SKY_PHASE_ATMOSPHERES;
+    const o = out ?? { turbidity: 0, rayleigh: 0, mieCoefficient: 0, mieDirectionalG: 0 };
+    o.turbidity = w.night * n.turbidity + w.twilight * t.turbidity + w.golden * g.turbidity + w.day * day.turbidity;
+    o.rayleigh = w.night * n.rayleigh + w.twilight * t.rayleigh + w.golden * g.rayleigh + w.day * day.rayleigh;
+    o.mieCoefficient = w.night * n.mieCoefficient + w.twilight * t.mieCoefficient + w.golden * g.mieCoefficient + w.day * day.mieCoefficient;
+    o.mieDirectionalG = w.night * n.mieDirectionalG + w.twilight * t.mieDirectionalG + w.golden * g.mieDirectionalG + w.day * day.mieDirectionalG;
+    return o;
+}
+/** How visible the night sky is (stars, moon halo): 0 by day, 1 once the sun is
+ *  12° down. */
+export function nightAmount(sunElevation) {
+    const w = skyPhaseWeights(sunElevation);
+    return w.night + w.twilight * 0.5;
+}
+/**
+ * How bright the sky dome is drawn, 1 by day. Preetham alone never gets darker
+ * than a flat grey after sunset (its constant 0.1 base term), so the night reads
+ * as overcast dusk instead of night. SkyMesh multiplies its output by this.
+ */
+export const SKY_PHASE_BRIGHTNESS = { night: 0.08, twilight: 0.5, golden: 1, day: 1 };
+export function skyBrightnessForSunElevation(sunElevation) {
+    const w = skyPhaseWeights(sunElevation);
+    const b = SKY_PHASE_BRIGHTNESS;
+    return w.night * b.night + w.twilight * b.twilight + w.golden * b.golden + w.day * b.day;
+}

package/dist/utils/spaceMigration.d.ts

@@ -0,0 +1,3 @@
+import type { CreatedObjectSettings } from '../types/scene3d';
+export declare function migrateSpaceObject<T extends CreatedObjectSettings>(obj: T): T;
+//# sourceMappingURL=spaceMigration.d.ts.map

package/dist/utils/spaceMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaceMigration.d.ts","sourceRoot":"","sources":["../../src/utils/spaceMigration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAsB9D,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,qBAAqB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CA2B7E"}

package/dist/utils/spaceMigration.js

@@ -0,0 +1,46 @@
+// =============================================================================
+// Space objects — load-time migration of the legacy config
+// =============================================================================
+//
+// The old starfield spun itself through a `rotateSpeed` knob (rotation.y +=
+// rotateSpeed * 0.01 every frame). Spinning the whole object is the parent's
+// transform, so the knob is gone from the space family; a saved starfield that
+// had it gets the equivalent transform 'spin' effect instead (rad/s at 60 fps),
+// unless it already animates its transform (a rotation effect, or keyframes: an
+// enabled transform effect would switch those off). The dead `size` / `sep` keys (never
+// read by the renderer) are dropped too.
+//
+// Pure and idempotent: returns the same object when there is nothing to migrate,
+// so it can run on every load without marking anything dirty.
+//
+const ROTATION_EFFECTS = new Set(['rotate3d', 'spin', 'sway', 'flip']);
+/** The old per-frame step (0.01 rad per unit) at 60 frames per second. */
+const LEGACY_FRAMES_PER_SECOND = 60;
+export function migrateSpaceObject(obj) {
+    if (!obj || obj.type !== 'space')
+        return obj;
+    const config = obj.config;
+    if (!config || config.type !== 'stars')
+        return obj;
+    if (!('rotateSpeed' in config) && !('size' in config) && !('sep' in config))
+        return obj;
+    const { rotateSpeed, size: _size, sep: _sep, ...rest } = config;
+    const next = { ...obj, config: rest };
+    const speed = typeof rotateSpeed === 'number' ? rotateSpeed * 0.01 * LEGACY_FRAMES_PER_SECOND : 0;
+    if (speed > 0) {
+        const animations = obj.animations ?? {};
+        const transform = animations.transform ?? {};
+        const effects = transform.effects ?? [];
+        const keyframed = (transform.animations?.length ?? 0) > 0;
+        if (!keyframed && !effects.some(e => ROTATION_EFFECTS.has(e?.type))) {
+            const hasOther = Object.entries(animations).some(([k, v]) => k !== 'enabled' && v && ((v.animations?.length ?? 0) > 0 || (v.effects?.length ?? 0) > 0));
+            next.animations = {
+                ...animations,
+                // Switch the animations on only when nothing else is there that the user may have turned off.
+                enabled: hasOther ? (animations.enabled ?? true) : true,
+                transform: { ...transform, effects: [...effects, { type: 'spin', enabled: true, speed, options: { axis: 'y' } }] },
+            };
+        }
+    }
+    return next;
+}

package/dist/utils/sunUtils.d.ts

@@ -1,6 +1,31 @@
-export declare function createSunPosition(elevation: number, azimuth: number): {
+/**
+ * THE sun direction convention for 3drise. Every piece that turns an
+ * elevation/azimuth pair into a direction — the Preetham sky, the key light,
+ * the day-cycle clock, the clouds, the ocean, the terrain, the lighting rig —
+ * goes through `sunDirectionFromAngles`, so the sun that is drawn and the sun
+ * that lights the scene cannot disagree.
+ *
+ *   elevation  degrees above the horizon (90 = straight up, negative = below)
+ *   azimuth    degrees around +Y, measured from +X towards +Z
+ *              (0 → +X, 90 → +Z, 180 → −X, −90 → −Z)
+ *
+ * There used to be two conventions: this one (Preetham sky, LightsManager) and
+ * x = sin(az), z = cos(az) (the clock, the skybox shader, useCloudSun), which
+ * mirrored the lit sun across the x = z plane — up to 137° away from the disc.
+ */
+export interface Vec3Like {
     x: number;
     y: number;
     z: number;
+}
+/** Unit vector toward the sun. Writes into `out` when given (a THREE.Vector3
+ *  works), so per-frame callers allocate nothing. */
+export declare function sunDirectionFromAngles<T extends Vec3Like = Vec3Like>(elevation: number, azimuth: number, out?: T): T;
+/** Inverse of `sunDirectionFromAngles`. The vector need not be normalised. */
+export declare function sunAnglesFromDirection(dir: Vec3Like): {
+    elevation: number;
+    azimuth: number;
 };
+/** Kept for existing callers; same convention. */
+export declare function createSunPosition(elevation: number, azimuth: number): Vec3Like;
 //# sourceMappingURL=sunUtils.d.ts.map

package/dist/utils/sunUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sunUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sunUtils.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;IAC/D,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb,CAQJ"}
+{"version":3,"file":"sunUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sunUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,QAAQ;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAID;qDACqD;AACrD,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CASpH;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,QAAQ,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAM5F;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAE9E"}

package/dist/utils/sunUtils.js

@@ -1,9 +1,40 @@
-export function createSunPosition(elevation, azimuth) {
-    const phi = (90 - elevation) * (Math.PI / 180);
-    const theta = azimuth * (Math.PI / 180);
+/**
+ * THE sun direction convention for 3drise. Every piece that turns an
+ * elevation/azimuth pair into a direction — the Preetham sky, the key light,
+ * the day-cycle clock, the clouds, the ocean, the terrain, the lighting rig —
+ * goes through `sunDirectionFromAngles`, so the sun that is drawn and the sun
+ * that lights the scene cannot disagree.
+ *
+ *   elevation  degrees above the horizon (90 = straight up, negative = below)
+ *   azimuth    degrees around +Y, measured from +X towards +Z
+ *              (0 → +X, 90 → +Z, 180 → −X, −90 → −Z)
+ *
+ * There used to be two conventions: this one (Preetham sky, LightsManager) and
+ * x = sin(az), z = cos(az) (the clock, the skybox shader, useCloudSun), which
+ * mirrored the lit sun across the x = z plane — up to 137° away from the disc.
+ */
+const DEG = Math.PI / 180;
+/** Unit vector toward the sun. Writes into `out` when given (a THREE.Vector3
+ *  works), so per-frame callers allocate nothing. */
+export function sunDirectionFromAngles(elevation, azimuth, out) {
+    const el = elevation * DEG;
+    const az = azimuth * DEG;
+    const c = Math.cos(el);
+    const target = (out ?? { x: 0, y: 0, z: 0 });
+    target.x = c * Math.cos(az);
+    target.y = Math.sin(el);
+    target.z = c * Math.sin(az);
+    return target;
+}
+/** Inverse of `sunDirectionFromAngles`. The vector need not be normalised. */
+export function sunAnglesFromDirection(dir) {
+    const r = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z) || 1;
     return {
-        x: Math.sin(phi) * Math.cos(theta),
-        y: Math.cos(phi),
-        z: Math.sin(phi) * Math.sin(theta),
+        elevation: Math.asin(Math.max(-1, Math.min(1, dir.y / r))) / DEG,
+        azimuth: Math.atan2(dir.z, dir.x) / DEG,
     };
 }
+/** Kept for existing callers; same convention. */
+export function createSunPosition(elevation, azimuth) {
+    return sunDirectionFromAngles(elevation, azimuth);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3driseai/3drise-core",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",