@3driseai/3drise-core 1.0.21 → 1.0.23

package/dist/ui/uiSpec.js

@@ -0,0 +1,173 @@
+// =============================================================================
+// UI layers — the spec (types, vocabulary, attribute grammar)
+// =============================================================================
+//
+// A UI layer is HTML + CSS written by the AI agent (or by hand) that controls the
+// scene through data attributes. The viewer's binder turns the attributes into calls
+// on the project's SceneHandle (actions, clips, sequences). This file is the single
+// source of the vocabulary: the binder, the validator, the agent docs and the base
+// stylesheet all read it, so they cannot drift apart.
+//
+//   <button class="rise-button" data-click="action.toggle:open-door">Open</button>
+//
+// Refs are an item's key, then its id, then its exact name (same as SceneHandle).
+// Commands are separated by spaces, so a ref used in an attribute cannot contain one:
+// address things by key.
+//
+/** Attributes that run commands. */
+export const UI_TRIGGER_ATTRS = {
+    click: 'data-click',
+    hoverIn: 'data-hover-in',
+    hoverOut: 'data-hover-out',
+};
+export const UI_ATTR = {
+    ...UI_TRIGGER_ATTRS,
+    bind: 'data-bind',
+    state: 'data-state',
+    showWhen: 'data-show-when',
+    anchor: 'data-anchor',
+    anchorOcclude: 'data-anchor-occlude',
+    anchorOffset: 'data-anchor-offset',
+    set: 'data-set',
+    setValue: 'data-set-value',
+};
+/** Verbs per command kind. `toggle` for sequences and clips alternates forward / backward. */
+export const UI_VERBS = {
+    action: ['apply', 'revert', 'toggle'],
+    sequence: ['play', 'reverse', 'pause', 'resume', 'stop', 'toggle'],
+    clip: ['play', 'reverse', 'pause', 'resume', 'stop', 'toggle'],
+    ui: ['show', 'hide', 'toggle'],
+};
+/** What `data-set` writes to: an object (or a node of a model), or one of the environment elements. */
+export const UI_SET_ENVIRONMENT = ['camera', 'sky', 'clouds', 'ocean', 'terrain'];
+/** `engine:materialSettings.opacity`, `engine/Door_L:meshSettings.rotation.y`, `sky:elevation`. */
+export function parseSetTarget(value) {
+    // One target per attribute, so (unlike the command lists) names may contain spaces.
+    const m = /^([^:/]+?)(?:\/([^:]+?))?:([A-Za-z_][\w.]*)$/.exec((value ?? '').trim());
+    return m
+        ? { set: { target: m[1].trim(), node: m[2]?.trim(), path: m[3] } }
+        : { error: `"${value ?? ''}" is not target:path (e.g. engine:materialSettings.opacity or sky:elevation).` };
+}
+/** The value of `data-set-value`: a number, true/false, a JSON array (`[1,0,0]`), or a string (`#ff0000`). */
+export function parseSetValue(value) {
+    if (value == null)
+        return undefined;
+    const t = value.trim();
+    if (t === 'true')
+        return true;
+    if (t === 'false')
+        return false;
+    if (/^-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i.test(t))
+        return Number(t);
+    if (t.startsWith('[')) {
+        try {
+            const a = JSON.parse(t);
+            if (Array.isArray(a) && a.every(n => typeof n === 'number'))
+                return a;
+        }
+        catch { /* fall through */ }
+    }
+    return t;
+}
+const KINDS = ['action', 'sequence', 'clip', 'ui'];
+const isKind = (k) => KINDS.includes(k);
+const tokens = (value) => (value ?? '').split(/\s+/).filter(Boolean);
+/** `action.toggle:open-door sequence.play:intro` */
+export function parseCommands(value) {
+    const commands = [];
+    const errors = [];
+    for (const token of tokens(value)) {
+        const m = /^([a-z]+)\.([a-z]+):(.+)$/.exec(token);
+        if (!m) {
+            errors.push(`"${token}" is not kind.verb:ref (e.g. action.toggle:open-door).`);
+            continue;
+        }
+        const [, kind, verb, ref] = m;
+        if (!isKind(kind)) {
+            errors.push(`"${token}": unknown kind "${kind}". Use ${KINDS.join(', ')}.`);
+            continue;
+        }
+        if (!UI_VERBS[kind].includes(verb)) {
+            errors.push(`"${token}": ${kind} has no verb "${verb}". Use ${UI_VERBS[kind].join(', ')}.`);
+            continue;
+        }
+        if (kind === 'ui' && !/^#[A-Za-z][\w-]*$/.test(ref)) {
+            errors.push(`"${token}": ui commands address an element id in this layer, like ui.toggle:#menu.`);
+            continue;
+        }
+        commands.push({ kind, verb, ref });
+    }
+    return { commands, errors };
+}
+/** `action:open-door !sequence:intro ui:#menu` — all must hold. */
+export function parseConditions(value) {
+    const conditions = [];
+    const errors = [];
+    for (const raw of tokens(value)) {
+        const negate = raw.startsWith('!');
+        const token = negate ? raw.slice(1) : raw;
+        const m = /^([a-z]+):(.+)$/.exec(token);
+        if (!m || !isKind(m[1])) {
+            errors.push(`"${raw}" is not [!]kind:ref (e.g. action:open-door).`);
+            continue;
+        }
+        if (m[1] === 'ui' && !/^#[A-Za-z][\w-]*$/.test(m[2])) {
+            errors.push(`"${raw}": ui conditions address an element id in this layer, like ui:#menu.`);
+            continue;
+        }
+        conditions.push({ negate, kind: m[1], ref: m[2] });
+    }
+    return { conditions, errors };
+}
+/** `sequence:intro` or `clip:spin` (for <input type="range">). */
+export function parseBind(value) {
+    const m = /^(sequence|clip):(.+)$/.exec((value ?? '').trim());
+    return m ? { bind: { kind: m[1], ref: m[2] } } : { error: `"${value ?? ''}" is not sequence:ref or clip:ref.` };
+}
+/** `object:engine` or `object:engine/Door_L` (the node name is everything after the first slash). */
+export function parseAnchor(value) {
+    const m = /^object:([^/]+)(?:\/(.+))?$/.exec((value ?? '').trim());
+    return m ? { anchor: { object: m[1], node: m[2] } } : { error: `"${value ?? ''}" is not object:ref or object:ref/NodeName.` };
+}
+/** `12 -8` (px, from the projected point). */
+export function parseOffset(value) {
+    const p = tokens(value).map(Number);
+    return p.length === 2 && p.every(Number.isFinite) ? [p[0], p[1]] : null;
+}
+// ---------------------------------------------------------------------------
+// Generic classes + variables (the base stylesheet in the viewer implements them)
+// ---------------------------------------------------------------------------
+//
+// The prefix is `rise-`, not `3drise-`: a CSS class cannot start with a digit
+// without escaping (`.3drise-button` is invalid; it has to be `.\33 drise-button`).
+export const UI_CLASS_PREFIX = 'rise-';
+export const UI_CLASSES = [
+    { name: 'rise-panel', use: 'A container grouping controls (a bar, a drawer, a side panel).' },
+    { name: 'rise-button', use: 'A button. Pressed / active state: [data-on="true"] when it has data-state.', for: 'button' },
+    { name: 'rise-toggle', use: 'A button showing an on/off state (use with data-state).', for: 'button' },
+    { name: 'rise-slider', use: 'A range input (<input type="range">), often with data-bind.', for: 'input[type=range]' },
+    { name: 'rise-input', use: 'A text or number input.', for: 'input' },
+    { name: 'rise-menu', use: 'A list of choices (a column of rise-menu-item).' },
+    { name: 'rise-menu-item', use: 'One choice in a rise-menu. Selected: [data-on="true"].' },
+    { name: 'rise-card', use: 'An info card.' },
+    { name: 'rise-card-title', use: 'The card heading.' },
+    { name: 'rise-card-body', use: 'The card text.' },
+    { name: 'rise-card-image', use: 'An <img> in a card.' },
+    { name: 'rise-hotspot', use: 'A marker anchored to an object or model part (data-anchor).' },
+    { name: 'rise-label', use: 'A small text label.' },
+];
+/** Set on the page (or the host element) to restyle every layer at once. */
+export const UI_VARIABLES = [
+    { name: '--rise-accent', default: '#6ea8ff', use: 'Accent colour: active states, slider thumb, hotspot.' },
+    { name: '--rise-accent-text', default: '#0b1220', use: 'Text on the accent colour.' },
+    { name: '--rise-bg', default: 'rgba(18, 22, 32, 0.72)', use: 'Control and card background.' },
+    { name: '--rise-text', default: '#f2f5fa', use: 'Text colour.' },
+    { name: '--rise-muted', default: 'rgba(242, 245, 250, 0.65)', use: 'Secondary text.' },
+    { name: '--rise-border', default: 'rgba(255, 255, 255, 0.16)', use: 'Border colour.' },
+    { name: '--rise-radius', default: '10px', use: 'Corner radius.' },
+    { name: '--rise-gap', default: '8px', use: 'Spacing between grouped controls.' },
+    { name: '--rise-font', default: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif', use: 'Font family (system fonts only).' },
+    { name: '--rise-blur', default: '12px', use: 'Backdrop blur of panels and cards.' },
+];
+/** Class of the host element each layer is rendered in (target it from the page to override variables). */
+export const UI_HOST_CLASS = 'rise-ui-layer';

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

@@ -1 +1 @@
-{"version":3,"file":"dataUtils.d.ts","sourceRoot":"","sources":["../../src/utils/dataUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dataUtils.d.ts","sourceRoot":"","sources":["../../src/utils/dataUtils.ts"],"names":[],"mappings":"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"}

package/dist/utils/dataUtils.js

@@ -379,9 +379,6 @@ export const getType = (property, value) => {
         return property === 'font';
         // && property.toLowerCase().includes('type');
     };
-    const isRenderMode = () => {
-        return property === 'renderMode';
-    };
     const isGeometry = () => {
         return property.toLowerCase().includes('geometry');
         // && property.toLowerCase().includes('type');
@@ -416,9 +413,6 @@ export const getType = (property, value) => {
     if (isAnchor(value)) {
         return "anchor";
     }
-    if (isRenderMode()) {
-        return "renderMode";
-    }
     if (isLayout()) {
         return "layout";
     }

package/dist/utils/environmentMigration.d.ts

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

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

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

package/dist/utils/environmentMigration.js

@@ -0,0 +1,50 @@
+// =============================================================================
+// Environment objects — load-time migration of the legacy rain
+// =============================================================================
+//
+// Rain used to sit outside the environment family, with its own animation domain:
+// its keyframes in `animations.rain`, its pointer bindings in `mouseMove.rain`.
+// It is a family member now, driven through `animations.environment` /
+// `mouseMove.environment` like every other environment object, so a saved rain's
+// tracks move over (appended to anything already there). The never-rendered
+// `splash` knob is dropped.
+//
+// Pure and idempotent: returns the same object when there is nothing to migrate.
+//
+export function migrateEnvironmentObject(obj) {
+    if (!obj || obj.type !== 'environment')
+        return obj;
+    const config = obj.config;
+    if (!config || config.type !== 'rain')
+        return obj;
+    const animations = obj.animations;
+    const mouseMove = obj.mouseMove;
+    const hasAnim = !!animations && 'rain' in animations;
+    const hasMouse = !!mouseMove && typeof mouseMove === 'object' && 'rain' in mouseMove;
+    if (!('splash' in config) && !hasAnim && !hasMouse)
+        return obj;
+    const next = { ...obj };
+    if ('splash' in config) {
+        const { splash: _splash, ...rest } = config;
+        next.config = rest;
+    }
+    if (hasAnim) {
+        const { rain, ...others } = animations;
+        const env = others.environment ?? {};
+        next.animations = {
+            ...others,
+            environment: { ...rain, ...env, animations: [...(env.animations ?? []), ...(rain?.animations ?? [])] },
+        };
+    }
+    if (hasMouse) {
+        const { rain, ...others } = mouseMove;
+        const env = others.environment;
+        next.mouseMove = {
+            ...others,
+            environment: env
+                ? { ...env, enabled: env.enabled || !!rain?.enabled, properties: [...(env.properties ?? []), ...(rain?.properties ?? [])] }
+                : rain,
+        };
+    }
+    return next;
+}

package/dist/utils/generativeAnimatable.d.ts

@@ -2,7 +2,7 @@ export interface AnimatableConfigProperty {
     value: string;
     label: string;
 }
-export type GenerativeFamily = 'particles' | 'lights' | 'effects' | 'grids';
+export type GenerativeFamily = 'particles' | 'lights' | 'effects' | 'grids' | 'environment' | 'space' | 'land' | 'text';
 /** The animatable knobs of one generative object, by family and config.type. */
 export declare function getGenerativeAnimatable(family: GenerativeFamily, config: {
     type?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"generativeAnimatable.d.ts","sourceRoot":"","sources":["../../src/utils/generativeAnimatable.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAY5E,gFAAgF;AAChF,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GAC7C,wBAAwB,EAAE,CAM5B;AAED,sFAAsF;AACtF,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GAC7C,OAAO,CAGT"}
+{"version":3,"file":"generativeAnimatable.d.ts","sourceRoot":"","sources":["../../src/utils/generativeAnimatable.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAoBxH,gFAAgF;AAChF,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GAC7C,wBAAwB,EAAE,CAM5B;AAED,sFAAsF;AACtF,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GAC7C,OAAO,CAGT"}

package/dist/utils/generativeAnimatable.js

@@ -2,6 +2,10 @@ import { GENERATIVE_PARTICLES_ANIMATABLE } from "../data/particlesDefaults.js";
 import { LIGHTS_ANIMATABLE } from "../data/lightsDefaults.js";
 import { EFFECTS_ANIMATABLE } from "../data/effectsDefaults.js";
 import { GRIDS_ANIMATABLE } from "../data/gridsDefaults.js";
+import { ENVIRONMENT_OBJECTS_ANIMATABLE } from "../data/environmentDefaults.js";
+import { SPACE_OBJECTS_ANIMATABLE } from "../data/spaceDefaults.js";
+import { LAND_OBJECTS_ANIMATABLE } from "../data/landDefaults.js";
+import { TEXT_OBJECTS_ANIMATABLE } from "../data/textDefaults.js";
 // Partial: grids list only the types converted to the config pattern so far (effects list all).
 const FAMILIES = {
     particles: GENERATIVE_PARTICLES_ANIMATABLE,
@@ -10,6 +14,14 @@ const FAMILIES = {
     lights: LIGHTS_ANIMATABLE,
     effects: EFFECTS_ANIMATABLE,
     grids: GRIDS_ANIMATABLE,
+    // Weather objects (type 'environment'): snow… The legacy rain is not in this table.
+    environment: ENVIRONMENT_OBJECTS_ANIMATABLE,
+    // Celestial bodies and backdrops (type 'space'): stars, earth, solarSystem, shootingStars.
+    space: SPACE_OBJECTS_ANIMATABLE,
+    // Placeable patches of terrain (type 'land'): mountains, hills, dunes, canyon.
+    land: LAND_OBJECTS_ANIMATABLE,
+    // Animated text looks (type 'text', config.type set): handwriting, neonTube, fourierSketch. The legacy bitmap / 3D text is not in this table.
+    text: TEXT_OBJECTS_ANIMATABLE,
 };
 /** The animatable knobs of one generative object, by family and config.type. */
 export function getGenerativeAnimatable(family, config) {

package/dist/utils/getAnimatableProperties.d.ts

@@ -1,6 +1,6 @@
 import type { MouseMoveInteraction, MouseMoveInteractions, ObjectAnimations } from "../types/objectSettings";
 import type { PropertyKind } from "../properties/types";
-export type AnimatableDomain = 'transform' | 'material' | 'edges' | 'light' | 'clouds' | 'rain' | 'particles' | 'effect' | 'grid';
+export type AnimatableDomain = 'transform' | 'material' | 'edges' | 'light' | 'clouds' | 'rain' | 'particles' | 'effect' | 'grid' | 'environment' | 'space' | 'land' | 'text' | 'sky' | 'ocean' | 'terrain';
 export interface AnimatableProperty {
     value: string;
     label: string;

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,11 @@ 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 './textMigration';
 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,iBAAiB,CAAC;AAChC,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,11 @@ 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 './textMigration.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 (3d text included) and models. Every other scene object (particles, grids, text, 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;AAEzG;;;;;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,31 @@
-/** The object effects of a stored object — entries of any older shape (generative effects) are dropped. */
+/**
+ * Visual effects layer GLSL onto three's standard materials, so they take only objects drawn with
+ * them: meshes (3d text included) and models. Every other scene object (particles, grids, text, 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';
+}
+/** 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;AAM9D;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,qBAAqB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAExE"}

package/dist/utils/objectMigration.js

@@ -0,0 +1,13 @@
+import { migrateSpaceObject } from './spaceMigration.js';
+import { migrateGridObject } from './gridMigration.js';
+import { migrateEnvironmentObject } from './environmentMigration.js';
+import { migrateTextObject } from './textMigration.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 migrateTextObject(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"}