@3driseai/3drise-core 1.0.21 → 1.0.22

package/dist/ui/uiSpec.d.ts

@@ -0,0 +1,116 @@
+export interface UiLayer {
+    id: string;
+    /** Stable, code-facing name; unique per project (see uiKeys). */
+    key: string;
+    name: string;
+    description?: string;
+    html: string;
+    css: string;
+    visible: boolean;
+    /** Position in the project's list (junction table `layerOrder`). */
+    layerOrder?: number;
+}
+export type UiRefKind = 'action' | 'sequence' | 'clip';
+/** `ui` addresses an element of the same layer by CSS id: `ui.toggle:#menu`. */
+export type UiCommandKind = UiRefKind | 'ui';
+/** Attributes that run commands. */
+export declare const UI_TRIGGER_ATTRS: {
+    readonly click: "data-click";
+    readonly hoverIn: "data-hover-in";
+    readonly hoverOut: "data-hover-out";
+};
+export type UiTrigger = keyof typeof UI_TRIGGER_ATTRS;
+export declare const UI_ATTR: {
+    readonly bind: "data-bind";
+    readonly state: "data-state";
+    readonly showWhen: "data-show-when";
+    readonly anchor: "data-anchor";
+    readonly anchorOcclude: "data-anchor-occlude";
+    readonly anchorOffset: "data-anchor-offset";
+    readonly set: "data-set";
+    readonly setValue: "data-set-value";
+    readonly click: "data-click";
+    readonly hoverIn: "data-hover-in";
+    readonly hoverOut: "data-hover-out";
+};
+/** Verbs per command kind. `toggle` for sequences and clips alternates forward / backward. */
+export declare const UI_VERBS: Record<UiCommandKind, readonly string[]>;
+export interface UiCommand {
+    kind: UiCommandKind;
+    verb: string;
+    ref: string;
+}
+/** A condition on scene state: `action:key`, `!sequence:key`, `ui:#panel`. */
+export interface UiCondition {
+    negate: boolean;
+    kind: UiCommandKind;
+    ref: string;
+}
+export interface UiBind {
+    kind: 'sequence' | 'clip';
+    ref: string;
+}
+export interface UiAnchor {
+    /** Object ref (id or name). */
+    object: string;
+    /** Name of a node inside a model. */
+    node?: string;
+}
+/** What `data-set` writes to: an object (or a node of a model), or one of the environment elements. */
+export declare const UI_SET_ENVIRONMENT: readonly ["camera", "sky", "clouds", "ocean", "terrain"];
+export interface UiSetTarget {
+    /** `camera` / `sky` / `clouds` / `ocean` / `terrain`, or an object ref (key, id or name). */
+    target: string;
+    /** Name of a node inside a model. */
+    node?: string;
+    /** Settings path, the same ones clip tracks use: `materialSettings.opacity`, `meshSettings.position.y`, `config.intensity`. */
+    path: string;
+}
+/** `engine:materialSettings.opacity`, `engine/Door_L:meshSettings.rotation.y`, `sky:elevation`. */
+export declare function parseSetTarget(value: string | null | undefined): {
+    set?: UiSetTarget;
+    error?: string;
+};
+/** The value of `data-set-value`: a number, true/false, a JSON array (`[1,0,0]`), or a string (`#ff0000`). */
+export declare function parseSetValue(value: string | null | undefined): number | boolean | string | number[] | undefined;
+/** `action.toggle:open-door sequence.play:intro` */
+export declare function parseCommands(value: string | null | undefined): {
+    commands: UiCommand[];
+    errors: string[];
+};
+/** `action:open-door !sequence:intro ui:#menu` — all must hold. */
+export declare function parseConditions(value: string | null | undefined): {
+    conditions: UiCondition[];
+    errors: string[];
+};
+/** `sequence:intro` or `clip:spin` (for <input type="range">). */
+export declare function parseBind(value: string | null | undefined): {
+    bind?: UiBind;
+    error?: string;
+};
+/** `object:engine` or `object:engine/Door_L` (the node name is everything after the first slash). */
+export declare function parseAnchor(value: string | null | undefined): {
+    anchor?: UiAnchor;
+    error?: string;
+};
+/** `12 -8` (px, from the projected point). */
+export declare function parseOffset(value: string | null | undefined): [number, number] | null;
+export declare const UI_CLASS_PREFIX = "rise-";
+export interface UiClassInfo {
+    name: string;
+    /** What it is for — shown in the agent docs. */
+    use: string;
+    /** Elements the validator expects it on (warns when a control has none of the generic classes). */
+    for?: string;
+}
+export declare const UI_CLASSES: readonly UiClassInfo[];
+export interface UiVariableInfo {
+    name: string;
+    default: string;
+    use: string;
+}
+/** Set on the page (or the host element) to restyle every layer at once. */
+export declare const UI_VARIABLES: readonly UiVariableInfo[];
+/** Class of the host element each layer is rendered in (target it from the page to override variables). */
+export declare const UI_HOST_CLASS = "rise-ui-layer";
+//# sourceMappingURL=uiSpec.d.ts.map

package/dist/ui/uiSpec.d.ts.map

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

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/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,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)));
+}