@3driseai/3drise-viewer 0.1.27 → 0.1.29

package/dist/ui/uiBinder.js

@@ -0,0 +1,344 @@
+// =============================================================================
+// UI binder — turns a layer's data attributes into SceneHandle calls
+// =============================================================================
+//
+// Pure DOM + SceneHandle: no three.js and no React, so it runs (and is tested) on
+// its own. One binder per rendered layer. It
+//   - runs data-click / data-hover-in / data-hover-out commands,
+//   - scrubs data-bind ranges and keeps them in step with a playing sequence,
+//   - reflects scene state (data-state → data-on, data-show-when → hidden),
+//   - writes data-set controls (sliders, colour pickers, switches, preset buttons) to live
+//     scene properties and keeps them in step with the scene,
+//   - registers data-anchor elements with the anchor registry (positioned by
+//     UiAnchorUpdater inside the canvas, through refs — never React state).
+//
+// State is refreshed on SceneHandle events plus a slow poll, because a reset or an
+// object click can change state without an event this layer subscribes to.
+//
+import { UI_ATTR, UI_TRIGGER_ATTRS, collectUiBindings, resolveUiRef, } from '@3driseai/3drise-core';
+import { uiAnchors } from './uiAnchors.js';
+const NATIVE_INTERACTIVE = new Set(['button', 'a', 'input', 'select', 'textarea', 'summary']);
+const GROUPS = { sequence: 'sequences', clip: 'clips' };
+export function bindUiLayer(root, scene, options = {}) {
+    const warn = options.onWarn ?? (() => { });
+    const anchors = options.anchors ?? uiAnchors;
+    const cleanups = [];
+    const toggled = new Set(); // sequence / clip refs whose last toggle went forward
+    const listen = (el, type, fn) => {
+        el.addEventListener(type, fn);
+        cleanups.push(() => el.removeEventListener(type, fn));
+    };
+    const uses = collectUiBindings(root);
+    for (const use of uses)
+        for (const e of use.errors)
+            warn(`${use.label}: ${e}`);
+    // ----- ref resolution (for inspect and warnings) --------------------------------
+    const listOf = (kind) => (kind === 'action' ? scene.actions.list() : kind === 'clip' ? scene.clips.list() : scene.sequences.list());
+    const exists = (kind, ref) => !!resolveUiRef(listOf(kind), ref);
+    const layerEl = (ref) => root.querySelector(ref); // '#id'
+    // ----- commands -------------------------------------------------------------------
+    function run(c, source) {
+        if (c.kind === 'ui') {
+            const el = layerEl(c.ref);
+            if (!el) {
+                warn(`${source}: no element ${c.ref} in this layer.`);
+                return;
+            }
+            if (c.verb === 'show')
+                el.hidden = false;
+            else if (c.verb === 'hide')
+                el.hidden = true;
+            else
+                el.hidden = !el.hidden;
+            refresh();
+            return;
+        }
+        if (c.kind === 'action') {
+            const a = scene.actions;
+            const ok = c.verb === 'apply' ? a.apply(c.ref) : c.verb === 'revert' ? a.revert(c.ref) : (a.toggle(c.ref), exists('action', c.ref));
+            if (!ok)
+                warn(`${source}: no action "${c.ref}".`);
+            return;
+        }
+        const g = scene[GROUPS[c.kind]];
+        let ok = true;
+        switch (c.verb) {
+            case 'play':
+                ok = g.play(c.ref);
+                break;
+            case 'reverse':
+                ok = g.play(c.ref, { reverse: true });
+                break;
+            case 'pause':
+                ok = g.pause(c.ref);
+                break;
+            case 'resume':
+                ok = g.resume(c.ref);
+                break;
+            case 'stop':
+                ok = g.stop(c.ref);
+                break;
+            case 'toggle': {
+                const key = `${c.kind}:${c.ref}`;
+                const back = toggled.has(key);
+                if (back)
+                    toggled.delete(key);
+                else
+                    toggled.add(key);
+                ok = g.play(c.ref, { reverse: back });
+                break;
+            }
+        }
+        if (!ok)
+            warn(`${source}: no ${c.kind} "${c.ref}".`);
+    }
+    function wireTriggers(use) {
+        const el = use.el;
+        for (const group of use.commands) {
+            if (!group.items.length)
+                continue;
+            const source = `${use.label} ${UI_TRIGGER_ATTRS[group.trigger]}`;
+            const fire = () => { for (const c of group.items)
+                run(c, source); };
+            if (group.trigger === 'click') {
+                listen(el, 'click', (e) => { if (el.localName !== 'a')
+                    e.preventDefault(); fire(); });
+                if (!NATIVE_INTERACTIVE.has(el.localName)) {
+                    if (!el.hasAttribute('tabindex'))
+                        el.setAttribute('tabindex', '0');
+                    if (!el.hasAttribute('role'))
+                        el.setAttribute('role', 'button');
+                    listen(el, 'keydown', (e) => { if (e.key === 'Enter' || e.key === ' ') {
+                        e.preventDefault();
+                        fire();
+                    } });
+                }
+            }
+            else {
+                // Hover is for pointers; on touch a tap must go through data-click.
+                const type = group.trigger === 'hoverIn' ? 'pointerenter' : 'pointerleave';
+                listen(el, type, (e) => { if (e.pointerType !== 'touch')
+                    fire(); });
+            }
+        }
+    }
+    // ----- scene state → DOM ----------------------------------------------------------
+    function holds(c) {
+        let on = false;
+        if (c.kind === 'action')
+            on = scene.actions.isApplied(c.ref);
+        else if (c.kind === 'sequence')
+            on = scene.sequences.isPlaying(c.ref);
+        else if (c.kind === 'clip')
+            on = scene.clips.isPlaying(c.ref);
+        else {
+            const el = layerEl(c.ref);
+            on = !!el && !el.hidden;
+        }
+        return c.negate ? !on : on;
+    }
+    function refresh() {
+        for (const use of uses) {
+            if (use.state.length)
+                use.el.setAttribute('data-on', String(use.state.every(holds)));
+            if (use.showWhen.length)
+                use.el.hidden = !use.showWhen.every(holds);
+            if (use.set)
+                syncSet(use);
+        }
+    }
+    // ----- data-set: controls that write live scene properties ---------------------------
+    const targetOf = (use) => `${use.set.target}${use.set.node ? '/' + use.set.node : ''}`;
+    const active = (el) => root.activeElement === el;
+    const dragging = new Set();
+    const warned = new Set();
+    const same = (a, b) => {
+        if (typeof a === 'number' && typeof b === 'number')
+            return Math.abs(a - b) < 1e-6 * Math.max(1, Math.abs(a), Math.abs(b));
+        if (Array.isArray(a) && Array.isArray(b))
+            return a.length === b.length && a.every((v, i) => same(v, b[i]));
+        if (typeof a === 'string' && typeof b === 'string')
+            return a.toLowerCase() === b.toLowerCase();
+        return a === b;
+    };
+    function write(use, value) {
+        const ok = scene.values.set(targetOf(use), use.set.path, value);
+        if (!ok && !warned.has(use.el)) {
+            warned.add(use.el);
+            warn(`${use.label} ${UI_ATTR.set}: cannot write ${use.set.path} on ${targetOf(use)}${scene.values.check(targetOf(use), use.set.path) ? ' — ' + scene.values.check(targetOf(use), use.set.path) : ''}.`);
+        }
+        refresh();
+    }
+    function syncSet(use) {
+        const el = use.el;
+        const current = scene.values.get(targetOf(use), use.set.path);
+        if (use.setValue !== undefined) {
+            el.setAttribute('data-on', String(current !== undefined && same(current, use.setValue)));
+            return;
+        }
+        if (current === undefined || dragging.has(el) || active(el))
+            return;
+        if (el.localName === 'select') {
+            el.value = String(current);
+            return;
+        }
+        if (el.localName !== 'input')
+            return;
+        if (el.type === 'checkbox')
+            el.checked = !!current;
+        else if (el.type === 'color') {
+            if (typeof current === 'string' && /^#[0-9a-f]{6}$/i.test(current))
+                el.value = current.toLowerCase();
+        }
+        else if (typeof current === 'number' || typeof current === 'string')
+            el.value = String(current);
+    }
+    for (const use of uses) {
+        if (!use.set)
+            continue;
+        const el = use.el;
+        if (use.setValue !== undefined) {
+            listen(el, 'click', (e) => { e.preventDefault(); write(use, use.setValue); });
+            if (!NATIVE_INTERACTIVE.has(el.localName)) {
+                if (!el.hasAttribute('tabindex'))
+                    el.setAttribute('tabindex', '0');
+                if (!el.hasAttribute('role'))
+                    el.setAttribute('role', 'button');
+                listen(el, 'keydown', (e) => { if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault();
+                    write(use, use.setValue);
+                } });
+            }
+        }
+        else if (el.localName === 'select') {
+            listen(el, 'change', () => {
+                const raw = el.value;
+                const current = scene.values.get(targetOf(use), use.set.path);
+                write(use, typeof current === 'number' && raw.trim() !== '' && Number.isFinite(Number(raw)) ? Number(raw) : raw);
+            });
+        }
+        else if (el.localName === 'input') {
+            if (el.type === 'checkbox')
+                listen(el, 'change', () => write(use, el.checked));
+            else if (el.type === 'range' || el.type === 'number') {
+                listen(el, 'input', () => { if (el.value !== '' && Number.isFinite(Number(el.value)))
+                    write(use, Number(el.value)); });
+                listen(el, 'pointerdown', () => { dragging.add(el); });
+                const up = () => { dragging.delete(el); };
+                window.addEventListener('pointerup', up);
+                cleanups.push(() => window.removeEventListener('pointerup', up));
+            }
+            else
+                listen(el, 'input', () => write(use, el.value)); // color, text
+        }
+    }
+    // ----- data-bind ranges -------------------------------------------------------------
+    const followed = [];
+    for (const use of uses) {
+        if (!use.bind)
+            continue;
+        const input = use.el;
+        if (input.localName !== 'input' || input.type !== 'range')
+            continue;
+        const { kind, ref } = use.bind;
+        const span = () => { const lo = Number(input.min || 0); const hi = Number(input.max || 1); return { lo, hi: hi === lo ? lo + 1 : hi }; };
+        const f = { input, ref, dragging: false };
+        listen(input, 'input', () => {
+            const { lo, hi } = span();
+            const p = Math.min(1, Math.max(0, (Number(input.value) - lo) / (hi - lo)));
+            const ok = kind === 'sequence' ? scene.sequences.setProgress(ref, p) : scene.clips.seek(ref, p);
+            if (!ok)
+                warn(`${use.label}: no ${kind} "${ref}".`);
+        });
+        if (kind === 'sequence') {
+            listen(input, 'pointerdown', () => { f.dragging = true; });
+            const up = () => { f.dragging = false; };
+            window.addEventListener('pointerup', up);
+            cleanups.push(() => window.removeEventListener('pointerup', up));
+            followed.push(f);
+        }
+    }
+    let raf = 0;
+    const follow = () => {
+        for (const f of followed) {
+            if (f.dragging || !scene.sequences.isPlaying(f.ref))
+                continue;
+            const lo = Number(f.input.min || 0);
+            const hi = Number(f.input.max || 1);
+            f.input.value = String(lo + (hi - lo) * scene.sequences.getProgress(f.ref));
+        }
+        raf = requestAnimationFrame(follow);
+    };
+    if (followed.length) {
+        raf = requestAnimationFrame(follow);
+        cleanups.push(() => cancelAnimationFrame(raf));
+    }
+    // ----- anchors ------------------------------------------------------------------------
+    for (const use of uses) {
+        if (!use.anchor)
+            continue;
+        const el = use.el;
+        el.style.position = 'absolute';
+        el.style.left = '0';
+        el.style.top = '0';
+        el.style.willChange = 'transform';
+        el.setAttribute('data-offscreen', ''); // hidden until the first projection places it
+        const entry = { el, object: use.anchor.object, node: use.anchor.node, occlude: use.anchorOcclude, offset: use.anchorOffset ?? [0, 0] };
+        cleanups.push(anchors.register(entry));
+    }
+    // ----- wire up ---------------------------------------------------------------------------
+    for (const use of uses)
+        wireTriggers(use);
+    refresh();
+    for (const type of ['actionApplied', 'actionReverted', 'animationStart', 'animationEnd']) {
+        cleanups.push(scene.on(type, () => { refresh(); requestAnimationFrame(refresh); }));
+    }
+    const poll = options.pollMs ?? 250;
+    if (poll > 0 && uses.some(u => u.state.length || u.showWhen.length || u.set)) {
+        const id = setInterval(refresh, poll);
+        cleanups.push(() => clearInterval(id));
+    }
+    return {
+        dispose() { while (cleanups.length)
+            cleanups.pop()(); },
+        refresh,
+        inspect() {
+            const rows = [];
+            const resolvedUi = (ref) => !!layerEl(ref);
+            const push = (use, trigger, kind, text, ref) => rows.push({
+                element: use.label, trigger, command: text,
+                resolved: kind === 'ui' ? resolvedUi(ref) : exists(kind, ref),
+            });
+            for (const use of uses) {
+                for (const g of use.commands)
+                    for (const c of g.items)
+                        push(use, g.trigger, c.kind, `${c.kind}.${c.verb}:${c.ref}`, c.ref);
+                for (const c of use.state)
+                    push(use, UI_ATTR.state, c.kind, `${c.negate ? '!' : ''}${c.kind}:${c.ref}`, c.ref);
+                for (const c of use.showWhen)
+                    push(use, UI_ATTR.showWhen, c.kind, `${c.negate ? '!' : ''}${c.kind}:${c.ref}`, c.ref);
+                if (use.bind)
+                    push(use, UI_ATTR.bind, use.bind.kind, `${use.bind.kind}:${use.bind.ref}`, use.bind.ref);
+                if (use.set)
+                    rows.push({
+                        element: use.label, trigger: UI_ATTR.set,
+                        command: `${targetOf(use)}:${use.set.path}${use.setValue !== undefined ? ' = ' + JSON.stringify(use.setValue) : ''}`,
+                        resolved: !scene.values.check(targetOf(use), use.set.path),
+                    });
+                if (use.anchor)
+                    rows.push({ element: use.label, trigger: UI_ATTR.anchor, command: `object:${use.anchor.object}${use.anchor.node ? '/' + use.anchor.node : ''}`, resolved: true });
+            }
+            return rows;
+        },
+        press(selector, trigger = 'click') {
+            const el = root.querySelector(selector);
+            if (!el)
+                return false;
+            if (trigger === 'click')
+                el.click();
+            else
+                el.dispatchEvent(new PointerEvent(trigger === 'hoverIn' ? 'pointerenter' : 'pointerleave', { pointerType: 'mouse', bubbles: false }));
+            return true;
+        },
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"configAnimations.d.ts","sourceRoot":"","sources":["../../src/utils/configAnimations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAEjF;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAE7D,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAEhE;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CACzC,UAAU,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAC1C,WAAW,EAAE,iBAAiB,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,cAAc,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,IAAI,CAqBN;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAChC,UAAU,EAAE,iBAAiB,EAAE,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACjC,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,IAAI,CAYN;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAGpE;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,cAAc,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,CAK1G;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAMvH"}
+{"version":3,"file":"configAnimations.d.ts","sourceRoot":"","sources":["../../src/utils/configAnimations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAGjF;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAE7D,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAEhE;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CACzC,UAAU,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAC1C,WAAW,EAAE,iBAAiB,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,cAAc,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,IAAI,CAqBN;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAChC,UAAU,EAAE,iBAAiB,EAAE,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACjC,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,IAAI,CAeN;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAGpE;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,cAAc,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,CAK1G;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAMvH"}

package/dist/utils/configAnimations.js

@@ -1,4 +1,5 @@
 import { calculateTimeProgress, applyEasing, gsapEasingMap, interpolateValue, interpolateMouseMoveProperty } from '@3driseai/3drise-core';
+import { Color } from 'three';
 /**
  * @param elapsedMs Milliseconds since this animation set started — NOT `Date.now()`,
  *        and not seconds. `calculateTimeProgress` divides by `duration`, so a wall
@@ -49,7 +50,10 @@ export function applyConfigMouseMove(properties, config, override, pointer, allo
         const base = override[property] ?? config[property];
         if (base === undefined)
             continue;
-        override[property] = interpolateMouseMoveProperty(base, min, max, pointer, axis, sensitivity, inverted);
+        const value = interpolateMouseMoveProperty(base, min, max, pointer, axis, sensitivity, inverted);
+        // A colour binding comes back as a THREE.Color; configs store hex, and some
+        // appliers (terrain's setStyle) only take a string.
+        override[property] = value instanceof Color ? `#${value.getHexString()}` : value;
     }
 }
 /** True when anything is currently being driven. */

package/dist/utils/gridConfig.d.ts

@@ -8,7 +8,7 @@ export declare const GRID_SURFACE_COLORS: readonly ["lineColor", "sectionColor",
  * is here because the plane is only subdivided when it is > 0 at commit time, and
  * `sectionSize` because it is a whole number of cells per accent group.
  */
-export declare const GRID_STRUCTURAL: readonly ["size", "flat", "segments", "displace", "lineMode", "cellMode", "sectionSize"];
+export declare const GRID_STRUCTURAL: readonly ["size", "segments", "displace", "lineMode", "cellMode", "sectionSize"];
 /** A uniform computed from the config (a clamp, a rounding, an enum index, a bool as 0/1). */
 export type GridDerive = Readonly<Record<string, (c: Record<string, any>) => number>>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"gridConfig.d.ts","sourceRoot":"","sources":["../../src/utils/gridConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAkBpC,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,+KAGvB,CAAC;AAEX,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,6EAA8E,CAAC;AAE/G;;;;GAIG;AACH,eAAO,MAAM,eAAe,0FAA2F,CAAC;AAIxH,8FAA8F;AAC9F,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC;AAEtF;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,IAAI,GAAG,SAAS,EACjD,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACtB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,MAAM,GAAE,UAAe,GACxB,IAAI,CASN"}
+{"version":3,"file":"gridConfig.d.ts","sourceRoot":"","sources":["../../src/utils/gridConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAkBpC,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,+KAGvB,CAAC;AAEX,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,6EAA8E,CAAC;AAE/G;;;;GAIG;AACH,eAAO,MAAM,eAAe,kFAAmF,CAAC;AAIhH,8FAA8F;AAC9F,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC;AAEtF;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,IAAI,GAAG,SAAS,EACjD,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACtB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,MAAM,GAAE,UAAe,GACxB,IAAI,CASN"}

package/dist/utils/gridConfig.js

@@ -25,7 +25,7 @@ export const GRID_SURFACE_COLORS = ['lineColor', 'sectionColor', 'cellColor', 'g
  * is here because the plane is only subdivided when it is > 0 at commit time, and
  * `sectionSize` because it is a whole number of cells per accent group.
  */
-export const GRID_STRUCTURAL = ['size', 'flat', 'segments', 'displace', 'lineMode', 'cellMode', 'sectionSize'];
+export const GRID_STRUCTURAL = ['size', 'segments', 'displace', 'lineMode', 'cellMode', 'sectionSize'];
 /**
  * @param variant the grid's own numeric knobs, each pushed as-is to u_<key>
  * @param derive  the grid's computed uniforms: u_<key> = derive[key](config)

package/dist/utils/landPatch.d.ts

@@ -0,0 +1,33 @@
+import * as THREE from 'three';
+import type { LandObjectConfig, LandQuality, TerrainConfig, TerrainQualityConfig } from '@3driseai/3drise-core';
+export declare const LAND_SEGMENTS: Record<LandQuality, number>;
+/** The seed's offset into the field, in metres. Deterministic, far apart. */
+export declare function landSeedOffset(seed: number, out?: THREE.Vector2): THREE.Vector2;
+/** The land object's config as the shared terrain renderer reads it. Base 0: the
+ *  object's position is the base. */
+export declare function landToTerrainConfig(cfg: LandObjectConfig): TerrainConfig;
+/** The renderer's quality block for a patch: no clipmap, no curvature. */
+export declare function landQuality(cfg: LandObjectConfig): TerrainQualityConfig;
+/** The object's world transform, split the way the patch needs it. */
+export interface LandFrame {
+    position: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+    scale: THREE.Vector3;
+    inverseQuaternion: THREE.Quaternion;
+}
+export declare function landFrame(object: THREE.Object3D, out?: LandFrame): LandFrame;
+/**
+ * The per-object uniforms: footprint, seed offset, edge band, height scale, and
+ * the camera and sun brought into terrain space. Call after applyTerrainUniforms
+ * and applySunUniforms (both of which write world-space or unscaled values).
+ */
+export declare function applyLandPatchUniforms(material: THREE.ShaderMaterial, cfg: LandObjectConfig, frame: LandFrame, camera: THREE.Camera): void;
+/**
+ * Height of the land above the object's base, in terrain metres, at terrain-space
+ * (tx, tz) measured from the object's centre (before rotation). Multiply nothing:
+ * scale.y is already in (elevation x scale.y).
+ */
+export declare function landHeightAt(cfg: LandObjectConfig, scale: THREE.Vector3, tx: number, tz: number, lodCell?: number): number;
+/** World-space height of a land object's surface under world (x, z), or null off the patch. */
+export declare function landWorldHeightAt(object: THREE.Object3D, cfg: LandObjectConfig, x: number, z: number): number | null;
+//# sourceMappingURL=landPatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"landPatch.d.ts","sourceRoot":"","sources":["../../src/utils/landPatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAgBhH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAwC,CAAC;AAE/F,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAsB,GAAG,KAAK,CAAC,OAAO,CAKrF;AAED;qCACqC;AACrC,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,GAAG,aAAa,CAExE;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,oBAAoB,CAevE;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACtB,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC;IACxB,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC;IAC7B,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;IACrB,iBAAiB,EAAE,KAAK,CAAC,UAAU,CAAC;CACvC;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,CAM5E;AAKD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAClC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAC9B,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,KAAK,CAAC,MAAM,GACrB,IAAI,CAiBN;AAaD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,MAAM,CAOrH;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,gBAAgB,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWpH"}

package/dist/utils/landPatch.js

@@ -0,0 +1,114 @@
+import * as THREE from 'three';
+import { terrainHeightAt } from './terrainHeight.js';
+// =============================================================================
+// Land objects — a bounded patch of the terrain height field
+// =============================================================================
+//
+// The patch is a unit grid on XZ that the object's transform places, rotates and
+// sizes. The field is sampled in TERRAIN SPACE: metres from the object's origin,
+// unrotated, plus the seed's offset into the endless field. So:
+//   footprint  = scale.x / scale.z (metres) — a window: wider shows more land
+//   height     = elevation x scale.y, above the object's base (position.y)
+// The GPU side is TerrainMaterial's TERRAIN_PATCH path; the CPU side below is the
+// same maths, for picking and placing things on the land.
+//
+export const LAND_SEGMENTS = { low: 128, medium: 256, high: 384 };
+/** The seed's offset into the field, in metres. Deterministic, far apart. */
+export function landSeedOffset(seed, out = new THREE.Vector2()) {
+    const s = Math.max(1, Math.round(seed || 1));
+    const fx = Math.sin(s * 12.9898) * 43758.5453;
+    const fz = Math.sin(s * 78.233) * 12345.6789;
+    return out.set((fx - Math.floor(fx) - 0.5) * 80000, (fz - Math.floor(fz) - 0.5) * 80000);
+}
+/** The land object's config as the shared terrain renderer reads it. Base 0: the
+ *  object's position is the base. */
+export function landToTerrainConfig(cfg) {
+    return { ...cfg, type: 'terrain', terrainType: cfg.type, seaLevel: 0 };
+}
+/** The renderer's quality block for a patch: no clipmap, no curvature. */
+export function landQuality(cfg) {
+    return {
+        levels: 1,
+        segments: LAND_SEGMENTS[cfg.quality] ?? 256,
+        // The fragment's shading floor. The patch's own cell (u_patchCell, scaled to
+        // the footprint) is what limits detail; a fixed 1 m floor would blur a 5 m patch.
+        cellSize: 0.001,
+        curvature: 0,
+        shadowSteps: 12,
+        shadowDistance: 5000,
+        detailFadeDistance: 1200,
+        receiveShadows: true,
+        exposure: 1,
+        wireframe: false,
+    };
+}
+export function landFrame(object, out) {
+    const f = out ?? { position: new THREE.Vector3(), quaternion: new THREE.Quaternion(), scale: new THREE.Vector3(), inverseQuaternion: new THREE.Quaternion() };
+    object.matrixWorld.decompose(f.position, f.quaternion, f.scale);
+    f.scale.set(Math.max(Math.abs(f.scale.x), 1e-3), Math.max(Math.abs(f.scale.y), 1e-4), Math.max(Math.abs(f.scale.z), 1e-3));
+    f.inverseQuaternion.copy(f.quaternion).invert();
+    return f;
+}
+const _v = new THREE.Vector3();
+const _off = new THREE.Vector2();
+/**
+ * The per-object uniforms: footprint, seed offset, edge band, height scale, and
+ * the camera and sun brought into terrain space. Call after applyTerrainUniforms
+ * and applySunUniforms (both of which write world-space or unscaled values).
+ */
+export function applyLandPatchUniforms(material, cfg, frame, camera) {
+    const u = material.uniforms;
+    const { scale } = frame;
+    landSeedOffset(cfg.seed, _off);
+    u.u_patchSize.value.set(scale.x, scale.z);
+    u.u_patchOffset.value.copy(_off);
+    u.u_edgeWidth.value = Math.max(0, cfg.edgeFade ?? 0) * Math.min(scale.x, scale.z);
+    u.u_scaleY.value = scale.y;
+    u.u_elevation.value = Math.max(cfg.elevation, 0.01) * scale.y;
+    u.u_seaLevel.value = 0;
+    u.u_patchCell.value = Math.max(scale.x, scale.z) / (LAND_SEGMENTS[cfg.quality] ?? 256);
+    camera.getWorldPosition(_v).sub(frame.position).applyQuaternion(frame.inverseQuaternion);
+    u.u_camTerrain.value.set(_v.x + _off.x, _v.y, _v.z + _off.y);
+    // World sun -> terrain space. A tilted patch is lit as tilted ground.
+    u.u_sunDir.value.applyQuaternion(frame.inverseQuaternion).normalize();
+}
+/** The edge band, exactly as terrainPatchMask in the shader. */
+function patchMask(tx, tz, sizeX, sizeZ, edge) {
+    const dx = (0.5 - Math.abs(tx / sizeX)) * sizeX;
+    const dz = (0.5 - Math.abs(tz / sizeZ)) * sizeZ;
+    const d = Math.min(dx, dz);
+    if (d <= 0)
+        return 0;
+    if (edge <= 1e-3)
+        return 1;
+    const x = Math.min(Math.max(d / edge, 0), 1);
+    return x * x * (3 - 2 * x);
+}
+/**
+ * Height of the land above the object's base, in terrain metres, at terrain-space
+ * (tx, tz) measured from the object's centre (before rotation). Multiply nothing:
+ * scale.y is already in (elevation x scale.y).
+ */
+export function landHeightAt(cfg, scale, tx, tz, lodCell = 2) {
+    const m = patchMask(tx, tz, scale.x, scale.z, Math.max(0, cfg.edgeFade ?? 0) * Math.min(scale.x, scale.z));
+    if (m <= 0)
+        return 0;
+    const off = landSeedOffset(cfg.seed, _off);
+    const t = landToTerrainConfig(cfg);
+    t.elevation = Math.max(cfg.elevation, 0.01) * scale.y;
+    return terrainHeightAt(t, tx + off.x, tz + off.y, lodCell) * m;
+}
+/** World-space height of a land object's surface under world (x, z), or null off the patch. */
+export function landWorldHeightAt(object, cfg, x, z) {
+    object.updateWorldMatrix(true, false);
+    const f = landFrame(object);
+    // A vertical line through (x, z) in terrain space: assume the patch is not
+    // tilted (the common case); for a tilted patch this is the nearest reading.
+    _v.set(x, f.position.y, z).sub(f.position).applyQuaternion(f.inverseQuaternion);
+    if (Math.abs(_v.x) > f.scale.x / 2 || Math.abs(_v.z) > f.scale.z / 2)
+        return null;
+    const h = landHeightAt(cfg, f.scale, _v.x, _v.z);
+    _v.y = h;
+    _v.applyQuaternion(f.quaternion).add(f.position);
+    return _v.y;
+}

package/dist/utils/renderedSky.d.ts

@@ -0,0 +1,32 @@
+import { Vector3 } from 'three';
+import type { Object3D } from 'three';
+/**
+ * The sky as it was actually drawn this frame — stored, time-driven, keyframed,
+ * clip-driven, pointer-driven or mid-drag, whichever won. This is the scene's
+ * shared sky state: everything lit by the sky (the key light, volumetric clouds,
+ * ocean, terrain — through useCloudSun) reads it before falling back to stored
+ * settings, so the sun that is drawn and the sun that lights cannot disagree.
+ *
+ * Keyed by the R3F scene, so a second canvas (market preview, thumbnail) never
+ * reads the editor's sky.
+ */
+export interface RenderedSky {
+    turbidity: number;
+    rayleigh: number;
+    mieCoefficient: number;
+    mieDirectionalG: number;
+    elevation: number;
+    azimuth: number;
+    /** Unit vector toward the sun, derived from elevation/azimuth here and
+     *  nowhere else (core sunUtils convention). Read-only for consumers. */
+    sunDirection: Vector3;
+}
+export type RenderedSkyValues = Omit<RenderedSky, 'sunDirection'>;
+export declare function publishRenderedSky(scene: Object3D, values: RenderedSkyValues): void;
+export declare function clearRenderedSky(scene: Object3D): void;
+export declare function getRenderedSky(scene: Object3D): RenderedSky | undefined;
+export declare function claimSceneSun(scene: Object3D): () => void;
+export declare function skyOwnsSun(scene: Object3D): boolean;
+/** The scene an object lives in (its top-most ancestor). */
+export declare function sceneOf(object: Object3D): Object3D;
+//# sourceMappingURL=renderedSky.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderedSky.d.ts","sourceRoot":"","sources":["../../src/utils/renderedSky.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;4EACwE;IACxE,YAAY,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;AAIlE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAanF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEtD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAEvE;AAaD,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,IAAI,CAUzD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAEnD;AAED,4DAA4D;AAC5D,wBAAgB,OAAO,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAIlD"}

package/dist/utils/renderedSky.js

@@ -0,0 +1,57 @@
+import { Vector3 } from 'three';
+import { sunDirectionFromAngles } from '@3driseai/3drise-core';
+const rendered = new WeakMap();
+export function publishRenderedSky(scene, values) {
+    let out = rendered.get(scene);
+    if (!out) {
+        out = { ...values, sunDirection: new Vector3() };
+        rendered.set(scene, out);
+    }
+    out.turbidity = values.turbidity;
+    out.rayleigh = values.rayleigh;
+    out.mieCoefficient = values.mieCoefficient;
+    out.mieDirectionalG = values.mieDirectionalG;
+    out.elevation = values.elevation;
+    out.azimuth = values.azimuth;
+    sunDirectionFromAngles(values.elevation, values.azimuth, out.sunDirection);
+}
+export function clearRenderedSky(scene) {
+    rendered.delete(scene);
+}
+export function getRenderedSky(scene) {
+    return rendered.get(scene);
+}
+/**
+ * Who owns the sun light. While a sky is active, SkySystem's key light (SunLight)
+ * is the scene's sun; the general lighting rig (LightsManager) keeps its ambient
+ * but turns its own `sun` off, so a scene never has two shadow-casting suns
+ * pointing different ways. A scene with no sky keeps LightsManager's sun as is.
+ *
+ * Counted, not a flag: a remount (the sky mode switching) claims before the old
+ * light releases.
+ */
+const sunClaims = new WeakMap();
+export function claimSceneSun(scene) {
+    sunClaims.set(scene, (sunClaims.get(scene) ?? 0) + 1);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        const n = (sunClaims.get(scene) ?? 1) - 1;
+        if (n > 0)
+            sunClaims.set(scene, n);
+        else
+            sunClaims.delete(scene);
+    };
+}
+export function skyOwnsSun(scene) {
+    return (sunClaims.get(scene) ?? 0) > 0;
+}
+/** The scene an object lives in (its top-most ancestor). */
+export function sceneOf(object) {
+    let o = object;
+    while (o.parent)
+        o = o.parent;
+    return o;
+}