@3driseai/3drise-viewer 0.1.40 → 0.1.42

package/dist/keyPad/KeyPadControls.js

@@ -0,0 +1,176 @@
+// =============================================================================
+// KeyPadControls — keyboard → camera / animations (headless)
+// =============================================================================
+//
+// Mounted by SceneBuilder (published / saved projects) and by the studio. Listens
+// to the real keyboard (unless the mode is 'none') and runs the motion for whatever
+// is held — from the keyboard or an on-screen pad (keyPadStore).
+//
+// Control modes (KeyPadSettings.mode, see keyPadMotion):
+//   none / orbit / fly  → camera (fly: ↑↓ forward / back, ←→ turn; Alt flips the style)
+//   animation           → ←/→ run the chosen animations / clips, ↑/↓ held speed
+//                         them up / down (back to normal when let go)
+// + / − zoom and Home (main view) work in every mode but 'none'. The general speed
+// (KeyPadSettings.speed) scales every mode.
+//
+// Key bindings (KeyPadSettings.bindings, see keyBindings) run in every mode, 'none'
+// included: a key that plays, applies, glides to a view or switches the mode. A
+// binding's mode switch is live (keyPadStore.modeOverride), never saved.
+//
+import { useEffect, useMemo, useRef } from 'react';
+import { HELD_MOVE_KEYS, KEYBOARD_MAP, goToMainView, isFlying, isTypingTarget, stepKeyPad } from './keyPadMotion.js';
+import { getBoost, releaseAnimations, resolveTargets, settleBoost, stepAnimations, stepBoost } from './keyPadAnimation.js';
+import { keyPadStore, useKeyPadHeld, useKeyPadState } from './keyPadStore.js';
+import { bindingDown, bindingUp, comboFromEvent } from './keyBindings.js';
+import { resolveKeyPadSettings } from './types.js';
+const NO_CLIPS = [];
+const NO_SEQUENCES = [];
+const KeyPadControls = ({ settings, clips = NO_CLIPS, sequences = NO_SEQUENCES, homePosition }) => {
+    const resolved = resolveKeyPadSettings(settings);
+    const { speed, animations, bindings } = resolved;
+    // A key binding may have switched the mode (live); otherwise the saved one.
+    const { modeOverride } = useKeyPadState();
+    const mode = modeOverride ?? resolved.mode;
+    const animating = mode === 'animation';
+    const homeRef = useRef(homePosition);
+    homeRef.current = homePosition;
+    // A mode change drops held keys and latched modifiers (they meant something else).
+    useEffect(() => { keyPadStore.reset(); }, [mode]);
+    // --- Real keyboard → the same keys as an on-screen pad ------------------------
+    useEffect(() => {
+        if (mode === 'none')
+            return;
+        const onDown = (e) => {
+            const k = KEYBOARD_MAP[e.key];
+            if (!k || isTypingTarget(e))
+                return;
+            if (animating && (k === 'pan' || k === 'alt'))
+                return; // no camera modifiers here
+            // No page scroll, browser zoom (Ctrl ±), back / forward (Alt ←/→), menu bar (Alt).
+            e.preventDefault();
+            if (e.repeat)
+                return;
+            if (k === 'home') {
+                if (homeRef.current)
+                    goToMainView(homeRef.current);
+            }
+            else
+                keyPadStore.press(k);
+        };
+        // Release is never filtered: a key pressed on the canvas and let go in a
+        // text field must still come up.
+        const onUp = (e) => {
+            const k = KEYBOARD_MAP[e.key];
+            if (!k || k === 'home')
+                return;
+            if (k === 'alt' && !animating)
+                e.preventDefault(); // Alt released alone would focus the browser menu
+            keyPadStore.release(k);
+        };
+        const onBlur = () => keyPadStore.releaseAll();
+        window.addEventListener('keydown', onDown);
+        window.addEventListener('keyup', onUp);
+        window.addEventListener('blur', onBlur);
+        return () => {
+            window.removeEventListener('keydown', onDown);
+            window.removeEventListener('keyup', onUp);
+            window.removeEventListener('blur', onBlur);
+            keyPadStore.releaseAll();
+        };
+    }, [mode, animating]);
+    // --- Key bindings ------------------------------------------------------------------
+    const bindingsRef = useRef(bindings);
+    bindingsRef.current = bindings;
+    const modeRef = useRef(mode);
+    modeRef.current = mode;
+    const savedModeRef = useRef(resolved.mode);
+    savedModeRef.current = resolved.mode;
+    useEffect(() => {
+        const ctx = {
+            getControlMode: () => modeRef.current,
+            // Back to the saved mode = no override.
+            setControlMode: (m) => keyPadStore.setModeOverride(m === savedModeRef.current ? null : m),
+        };
+        const held = new Map(); // by KeyboardEvent.code
+        const onDown = (e) => {
+            if (e.ctrlKey || e.metaKey || isTypingTarget(e))
+                return;
+            const combo = comboFromEvent(e);
+            const b = bindingsRef.current.find(x => x.enabled !== false && x.combo === combo);
+            if (!b)
+                return;
+            e.preventDefault();
+            if (e.repeat || held.has(e.code))
+                return;
+            const h = bindingDown(b, ctx);
+            if (h)
+                held.set(e.code, h);
+        };
+        const onUp = (e) => {
+            const h = held.get(e.code);
+            if (!h)
+                return;
+            held.delete(e.code);
+            bindingUp(h, ctx);
+        };
+        const releaseAll = () => { for (const h of held.values())
+            bindingUp(h, ctx); held.clear(); };
+        window.addEventListener('keydown', onDown);
+        window.addEventListener('keyup', onUp);
+        window.addEventListener('blur', releaseAll);
+        return () => {
+            window.removeEventListener('keydown', onDown);
+            window.removeEventListener('keyup', onUp);
+            window.removeEventListener('blur', releaseAll);
+            releaseAll();
+        };
+    }, []);
+    // The saved mode changed (studio dropdown): it wins over a key's switch.
+    useEffect(() => { keyPadStore.setModeOverride(null); }, [resolved.mode]);
+    // --- Animation targets; let go of the ones that stop being targets -------------
+    const targets = useMemo(() => resolveTargets(animations, clips, sequences), [animations, clips, sequences]);
+    const animKey = animations.join('|');
+    useEffect(() => {
+        releaseAnimations(new Set(animating ? animKey.split('|').filter(Boolean) : []));
+    }, [animating, animKey]);
+    useEffect(() => () => releaseAnimations(), []);
+    // --- Held keys → motion --------------------------------------------------------
+    const held = useKeyPadHeld();
+    const zoom = (held.has('zoomIn') ? 1 : 0) - (held.has('zoomOut') ? 1 : 0);
+    const timeDir = animating ? (held.has('right') ? 1 : 0) - (held.has('left') ? 1 : 0) : 0;
+    const boostDir = animating ? (held.has('up') ? 1 : 0) - (held.has('down') ? 1 : 0) : 0;
+    const moving = animating
+        ? zoom !== 0 || timeDir !== 0 || boostDir !== 0
+        : HELD_MOVE_KEYS.some(k => held.has(k));
+    const live = useRef({ held, zoom, speed, mode, timeDir, boostDir, targets });
+    live.current = { held, zoom, speed, mode, timeDir, boostDir, targets };
+    useEffect(() => {
+        if (!moving)
+            return;
+        let raf = 0;
+        let last = performance.now();
+        const tick = (now) => {
+            const dt = Math.min((now - last) / 1000, 0.05); // no jump after a stalled frame
+            last = now;
+            const l = live.current;
+            if (l.mode === 'animation') {
+                stepBoost(l.boostDir, dt);
+                if (l.timeDir)
+                    stepAnimations(l.targets, l.timeDir, dt, l.speed * getBoost());
+                if (l.zoom)
+                    stepKeyPad(l.held, l.zoom, dt, l.speed, false, false);
+            }
+            else {
+                stepKeyPad(l.held, l.zoom, dt, l.speed, isFlying(l.mode, l.held));
+            }
+            raf = requestAnimationFrame(tick);
+        };
+        raf = requestAnimationFrame(tick);
+        return () => {
+            cancelAnimationFrame(raf);
+            settleBoost(); // let go of ↑ / ↓: ease back to 1× after the loop stops
+        };
+    }, [moving]);
+    return null;
+};
+export default KeyPadControls;

package/dist/keyPad/index.d.ts

@@ -0,0 +1,16 @@
+export { default as KeyPadControls } from './KeyPadControls';
+export type { KeyPadControlsProps } from './KeyPadControls';
+export { keyPadStore, useKeyPadState, useKeyPadHeld } from './keyPadStore';
+export type { KeyPadLiveState } from './keyPadStore';
+export { DEFAULT_KEYPAD_SETTINGS, resolveKeyPadSettings } from './types';
+export type { KeyPadSettings } from './types';
+export { CONTROL_MODES, KEY_HINTS, KEYBOARD_MAP, HELD_MOVE_KEYS, isFlying, goToMainView, zoomRange, distanceToT, tToDistance, setOrbitDistance, } from './keyPadMotion';
+export type { KeyPadKey, KeyPadModifier, KeyPadControlMode, ZoomRange } from './keyPadMotion';
+export { clipRef as keyPadClipRef, seqRef as keyPadSeqRef, formatSpeed as formatKeyPadSpeed, getBoost as getKeyPadBoost, subscribeBoost as subscribeKeyPadBoost } from './keyPadAnimation';
+export { comboFromEvent, comboProblem, comboKeys, comboCode, keyName, isModifierCode } from './keyBindings';
+export type { KeyBinding, KeyBindingTrigger } from './keyBindings';
+export { captureView, glideToView } from './keyPadMotion';
+export type { CameraView } from './keyPadMotion';
+export { bindingDown, bindingUp } from './keyBindings';
+export type { HeldKey, KeyBindingContext } from './keyBindings';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keyPad/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC3E,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EACH,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAC9E,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,GACxD,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC9F,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,IAAI,YAAY,EAAE,WAAW,IAAI,iBAAiB,EAAE,QAAQ,IAAI,cAAc,EAAE,cAAc,IAAI,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC3L,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC5G,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/keyPad/index.js

@@ -0,0 +1,8 @@
+export { default as KeyPadControls } from './KeyPadControls.js';
+export { keyPadStore, useKeyPadState, useKeyPadHeld } from './keyPadStore.js';
+export { DEFAULT_KEYPAD_SETTINGS, resolveKeyPadSettings } from './types.js';
+export { CONTROL_MODES, KEY_HINTS, KEYBOARD_MAP, HELD_MOVE_KEYS, isFlying, goToMainView, zoomRange, distanceToT, tToDistance, setOrbitDistance, } from './keyPadMotion.js';
+export { clipRef as keyPadClipRef, seqRef as keyPadSeqRef, formatSpeed as formatKeyPadSpeed, getBoost as getKeyPadBoost, subscribeBoost as subscribeKeyPadBoost } from './keyPadAnimation.js';
+export { comboFromEvent, comboProblem, comboKeys, comboCode, keyName, isModifierCode } from './keyBindings.js';
+export { captureView, glideToView } from './keyPadMotion.js';
+export { bindingDown, bindingUp } from './keyBindings.js';

package/dist/keyPad/keyBindings.d.ts

@@ -0,0 +1,43 @@
+import type { SceneCommand } from '@3driseai/3drise-core';
+import { type CameraView, type KeyPadControlMode } from './keyPadMotion';
+export type KeyBindingTrigger = 'press' | 'hold';
+export interface KeyBinding {
+    id: string;
+    /** `[Alt+][Shift+]<KeyboardEvent.code>`, e.g. `Digit1`, `Shift+KeyL`. */
+    combo: string;
+    trigger: KeyBindingTrigger;
+    /** Optional name shown in the list. */
+    label?: string;
+    /** Off: kept but never runs. */
+    enabled?: boolean;
+    commands: SceneCommand[];
+    view?: CameraView | null;
+    controlMode?: KeyPadControlMode | null;
+}
+export declare const isModifierCode: (code: string) => boolean;
+/** The combo a key event makes (Alt / Shift kept; Ctrl / ⌘ combos are not bindable). */
+export declare function comboFromEvent(e: Pick<KeyboardEvent, 'code' | 'altKey' | 'shiftKey'>): string;
+/** Why a key can't be bound (null = it can). */
+export declare function comboProblem(e: Pick<KeyboardEvent, 'code' | 'ctrlKey' | 'metaKey'>): string | null;
+/** One key's display name: KeyA → A, Digit1 → 1, Numpad1 → Num 1, F5 → F5. */
+export declare function keyName(code: string): string;
+/** A combo as keycaps: `Shift+Digit1` → ['Shift', '1']. */
+export declare function comboKeys(combo: string): string[];
+/** The key part of a combo (its KeyboardEvent.code). */
+export declare const comboCode: (combo: string) => string;
+/** What a key binding needs from where it runs (the mode lives in the host's state). */
+export interface KeyBindingContext {
+    getControlMode(): KeyPadControlMode;
+    setControlMode(mode: KeyPadControlMode): void;
+}
+/** Undo info for a held key. */
+export interface HeldKey {
+    binding: KeyBinding;
+    prevView: CameraView | null;
+    prevMode: KeyPadControlMode | null;
+}
+/** Key down. Returns what to undo on key up for a hold binding (null for a press). */
+export declare function bindingDown(b: KeyBinding, ctx: KeyBindingContext): HeldKey | null;
+/** Key up of a hold binding: switch off what it switched on, put view / mode back. */
+export declare function bindingUp(h: HeldKey, ctx: KeyBindingContext): void;
+//# sourceMappingURL=keyBindings.d.ts.map

package/dist/keyPad/keyBindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyBindings.d.ts","sourceRoot":"","sources":["../../src/keyPad/keyBindings.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,EAA4B,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnG,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,iBAAiB,CAAC;IAC3B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC1C;AAQD,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,YAA6B,CAAC;AAEzE,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC,GAAG,MAAM,CAE7F;AAED,gDAAgD;AAChD,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,CAMlG;AASD,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK5C;AAED,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIjD;AAED,wDAAwD;AACxD,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,WAAiC,CAAC;AAIzE,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAC9B,cAAc,IAAI,iBAAiB,CAAC;IACpC,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACjD;AAiBD,gCAAgC;AAChC,MAAM,WAAW,OAAO;IACpB,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACtC;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,GAAG,IAAI,CAgBjF;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAQlE"}

package/dist/keyPad/keyBindings.js

@@ -0,0 +1,92 @@
+import { runCommand } from '../triggers/engine.js';
+import { captureView, glideToView } from './keyPadMotion.js';
+// --- Combos ----------------------------------------------------------------------
+const MODIFIER_CODES = new Set(['ShiftLeft', 'ShiftRight', 'AltLeft', 'AltRight', 'ControlLeft', 'ControlRight', 'MetaLeft', 'MetaRight', 'OSLeft', 'OSRight']);
+const CAMERA_CODES = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Equal', 'Minus', 'NumpadAdd', 'NumpadSubtract', 'Home']);
+const STUDIO_CODES = new Set(['Escape', 'Tab', 'Backspace', 'Delete', 'CapsLock', 'ContextMenu', 'NumLock', 'ScrollLock', 'Pause', 'PrintScreen']);
+export const isModifierCode = (code) => MODIFIER_CODES.has(code);
+/** The combo a key event makes (Alt / Shift kept; Ctrl / ⌘ combos are not bindable). */
+export function comboFromEvent(e) {
+    return `${e.altKey ? 'Alt+' : ''}${e.shiftKey ? 'Shift+' : ''}${e.code}`;
+}
+/** Why a key can't be bound (null = it can). */
+export function comboProblem(e) {
+    if (e.ctrlKey || e.metaKey)
+        return 'Ctrl / ⌘ shortcuts belong to the browser and the studio — try the key alone, or with Shift / Alt.';
+    if (CAMERA_CODES.has(e.code))
+        return 'This key moves the camera (arrows, + / −, Home). Pick another one.';
+    if (STUDIO_CODES.has(e.code))
+        return 'This key is used by the studio. Pick another one.';
+    if (!e.code)
+        return 'This key can\'t be told apart. Pick another one.';
+    return null;
+}
+const CODE_NAMES = {
+    Space: 'Space', Enter: 'Enter', NumpadEnter: 'Num Enter', Backquote: '`', BracketLeft: '[', BracketRight: ']',
+    Semicolon: ';', Quote: "'", Comma: ',', Period: '.', Slash: '/', Backslash: '\\', IntlBackslash: '\\',
+    PageUp: 'Page Up', PageDown: 'Page Down', End: 'End', Insert: 'Insert',
+    NumpadMultiply: 'Num *', NumpadDivide: 'Num /', NumpadDecimal: 'Num .',
+};
+/** One key's display name: KeyA → A, Digit1 → 1, Numpad1 → Num 1, F5 → F5. */
+export function keyName(code) {
+    if (/^Key[A-Z]$/.test(code))
+        return code.slice(3);
+    if (/^Digit\d$/.test(code))
+        return code.slice(5);
+    if (/^Numpad\d$/.test(code))
+        return `Num ${code.slice(6)}`;
+    return CODE_NAMES[code] ?? code;
+}
+/** A combo as keycaps: `Shift+Digit1` → ['Shift', '1']. */
+export function comboKeys(combo) {
+    const parts = combo.split('+');
+    const code = parts.pop() ?? '';
+    return [...parts, keyName(code)];
+}
+/** The key part of a combo (its KeyboardEvent.code). */
+export const comboCode = (combo) => combo.split('+').pop() ?? '';
+/** A command for a held key: on (down) or off (up); null = nothing to do that way. */
+function heldCommand(c, on) {
+    switch (c.kind) {
+        case 'animationClip':
+        case 'animationSequence':
+            return { ...c, command: on ? 'play' : 'stop' };
+        case 'gallery':
+            return on ? c : null; // an event: fires on the press only
+        default:
+            return { ...c, command: on ? 'apply' : 'revert' };
+    }
+}
+const run = (b, c) => runCommand(c, { source: { host: 'key', id: b.id }, chain: [] });
+/** Key down. Returns what to undo on key up for a hold binding (null for a press). */
+export function bindingDown(b, ctx) {
+    const hold = b.trigger === 'hold';
+    const held = { binding: b, prevView: null, prevMode: null };
+    if (b.controlMode) {
+        held.prevMode = ctx.getControlMode();
+        ctx.setControlMode(b.controlMode);
+    }
+    if (b.view) {
+        held.prevView = hold ? captureView() : null;
+        glideToView(b.view);
+    }
+    for (const c of b.commands ?? []) {
+        const cmd = hold ? heldCommand(c, true) : c;
+        if (cmd)
+            run(b, cmd);
+    }
+    return hold ? held : null;
+}
+/** Key up of a hold binding: switch off what it switched on, put view / mode back. */
+export function bindingUp(h, ctx) {
+    const b = h.binding;
+    for (const c of [...(b.commands ?? [])].reverse()) {
+        const cmd = heldCommand(c, false);
+        if (cmd)
+            run(b, cmd);
+    }
+    if (h.prevView)
+        glideToView(h.prevView);
+    if (h.prevMode)
+        ctx.setControlMode(h.prevMode);
+}

package/dist/keyPad/keyPadAnimation.d.ts

@@ -0,0 +1,28 @@
+import { type ClipLookup } from '../animationsV2/sequenceUtils';
+import type { AnimationClip, AnimationSequence } from '../animationsV2/types';
+/** Stored ids: `seq:<id>` for an animation (sequence), `clip:<id>` for a clip. */
+export type KeyPadAnimationRef = string;
+export declare const seqRef: (id: string) => KeyPadAnimationRef;
+export declare const clipRef: (id: string) => KeyPadAnimationRef;
+export declare const getBoost: () => number;
+export declare function subscribeBoost(fn: () => void): () => void;
+/** One frame: dir +1 accelerate, −1 slow down, 0 ease back to 1×. */
+export declare function stepBoost(dir: number, dt: number): void;
+/** Nothing held any more: ease the boost back to 1× on its own frames. */
+export declare function settleBoost(): void;
+export declare const formatSpeed: (s: number) => string;
+export interface AnimationTargets {
+    clips: AnimationClip[];
+    seqs: {
+        seq: AnimationSequence;
+        duration: number;
+    }[];
+    lookup: ClipLookup;
+}
+/** The chosen refs → live clips / sequences (missing ones dropped). */
+export declare function resolveTargets(refs: readonly KeyPadAnimationRef[], clips: readonly AnimationClip[], sequences: readonly AnimationSequence[]): AnimationTargets;
+/** One frame: run every target `dir` (±1) × `speed` × dt seconds along its timeline. */
+export declare function stepAnimations(t: AnimationTargets, dir: number, dt: number, speed: number): void;
+/** Stop everything the pad posed that is not in `keep` (authored values back). */
+export declare function releaseAnimations(keep?: ReadonlySet<KeyPadAnimationRef>): void;
+//# sourceMappingURL=keyPadAnimation.d.ts.map

package/dist/keyPad/keyPadAnimation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyPadAnimation.d.ts","sourceRoot":"","sources":["../../src/keyPad/keyPadAnimation.ts"],"names":[],"mappings":"AAgBA,OAAO,EAA4B,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,kFAAkF;AAClF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACxC,eAAO,MAAM,MAAM,GAAI,IAAI,MAAM,KAAG,kBAAiC,CAAC;AACtE,eAAO,MAAM,OAAO,GAAI,IAAI,MAAM,KAAG,kBAAkC,CAAC;AAmBxE,eAAO,MAAM,QAAQ,cAAc,CAAC;AACpC,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGzD;AAQD,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAShD;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,SAW1B;AAED,eAAO,MAAM,WAAW,GAAI,GAAG,MAAM,WAA8C,CAAC;AAEpF,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,IAAI,EAAE;QAAE,GAAG,EAAE,iBAAiB,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD,MAAM,EAAE,UAAU,CAAC;CACtB;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,kBAAkB,EAAE,EAAE,KAAK,EAAE,SAAS,aAAa,EAAE,EAAE,SAAS,EAAE,SAAS,iBAAiB,EAAE,GAAG,gBAAgB,CAiB9J;AAOD,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,CAAC,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAYzF;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,WAAW,CAAC,kBAAkB,CAAa,QAQlF"}

package/dist/keyPad/keyPadAnimation.js

@@ -0,0 +1,131 @@
+// =============================================================================
+// keyPadAnimation — animation control mode
+// =============================================================================
+//
+// The chosen animations (sequences) and clips are driven by hand:
+//   ← / → held  → their timelines run back / forward at the current speed
+//                 (each is posed at its new time every frame — ClipsRuntime.pose /
+//                 poseSequence — so letting go holds the frame)
+//   ↑ / ↓ held  → accelerate / slow down; back to 1× when let go (see Boost)
+//   the general speed (keyPadSettings.speed) scales it all
+//
+// Each target is clamped to its own [0, duration]. Targets the pad posed are
+// stopped (authored values back) when they stop being targets — mode changed or
+// unselected — so nothing stays frozen mid-animation.
+//
+import ClipsRuntime from '../animationsV2/ClipsRuntime.js';
+import { clipMap, resolveSequence } from '../animationsV2/sequenceUtils.js';
+export const seqRef = (id) => `seq:${id}`;
+export const clipRef = (id) => `clip:${id}`;
+// --- Boost: ↑ / ↓ accelerate / slow down while held, ease back to 1× on release ----
+//
+// Per-frame, so it lives here (with a subscribe for the label), not in Redux: a
+// sceneSlice write every frame would re-render everything that reads state.scene.
+// The rate the timelines run at = general speed (keyPadSettings.speed) × boost.
+const BOOST_MAX = 4;
+const BOOST_MIN = 0.1;
+/** Held ↑ reaches 4× in ~1.5 s (and ↓ 0.1× in ~2.5 s). */
+const BOOST_RATE = Math.log(BOOST_MAX) / 1.5;
+/** Release: back to 1× with this time constant (s). */
+const BOOST_RETURN = 0.25;
+let boost = 1;
+let settleRaf = 0;
+const boostListeners = new Set();
+export const getBoost = () => boost;
+export function subscribeBoost(fn) {
+    boostListeners.add(fn);
+    return () => { boostListeners.delete(fn); };
+}
+function setBoost(v) {
+    if (v === boost)
+        return;
+    boost = v;
+    boostListeners.forEach(fn => fn());
+}
+/** One frame: dir +1 accelerate, −1 slow down, 0 ease back to 1×. */
+export function stepBoost(dir, dt) {
+    cancelAnimationFrame(settleRaf);
+    settleRaf = 0;
+    if (dir > 0)
+        setBoost(Math.min(BOOST_MAX, boost * Math.exp(BOOST_RATE * dt)));
+    else if (dir < 0)
+        setBoost(Math.max(BOOST_MIN, boost * Math.exp(-BOOST_RATE * dt)));
+    else {
+        const next = 1 + (boost - 1) * Math.exp(-dt / BOOST_RETURN);
+        setBoost(Math.abs(next - 1) < 0.005 ? 1 : next);
+    }
+}
+/** Nothing held any more: ease the boost back to 1× on its own frames. */
+export function settleBoost() {
+    if (boost === 1 || settleRaf)
+        return;
+    let last = performance.now();
+    const tick = (now) => {
+        const dt = Math.min((now - last) / 1000, 0.05);
+        last = now;
+        const next = 1 + (boost - 1) * Math.exp(-dt / BOOST_RETURN);
+        setBoost(Math.abs(next - 1) < 0.005 ? 1 : next);
+        settleRaf = boost === 1 ? 0 : requestAnimationFrame(tick);
+    };
+    settleRaf = requestAnimationFrame(tick);
+}
+export const formatSpeed = (s) => `${s < 1 ? s.toFixed(2) : s.toFixed(1)}×`;
+/** The chosen refs → live clips / sequences (missing ones dropped). */
+export function resolveTargets(refs, clips, sequences) {
+    const lookup = clipMap(clips);
+    const out = { clips: [], seqs: [], lookup };
+    for (const ref of refs) {
+        const [kind, id] = [ref.slice(0, ref.indexOf(':')), ref.slice(ref.indexOf(':') + 1)];
+        if (kind === 'clip') {
+            const c = lookup.get(id);
+            if (c)
+                out.clips.push(c);
+        }
+        else if (kind === 'seq') {
+            const seq = sequences.find(s => s.id === id);
+            if (!seq)
+                continue;
+            let duration = 0;
+            try {
+                duration = resolveSequence(seq, lookup).duration;
+            }
+            catch {
+                continue;
+            } // missing clips
+            out.seqs.push({ seq, duration });
+        }
+    }
+    return out;
+}
+const clamp = (v, max) => Math.max(0, Math.min(max, v));
+/** Refs the pad has posed and not yet let go. */
+const touched = new Set();
+/** One frame: run every target `dir` (±1) × `speed` × dt seconds along its timeline. */
+export function stepAnimations(t, dir, dt, speed) {
+    const d = dir * speed * dt;
+    for (const clip of t.clips) {
+        if (ClipsRuntime.isPlaying(clip.id))
+            ClipsRuntime.pause(clip.id);
+        ClipsRuntime.pose(clip, clamp(ClipsRuntime.getTime(clip.id) + d, clip.duration));
+        touched.add(clipRef(clip.id));
+    }
+    for (const { seq, duration } of t.seqs) {
+        if (ClipsRuntime.isSequencePlaying(seq.id))
+            ClipsRuntime.pauseSequence(seq.id);
+        ClipsRuntime.poseSequence(seq, t.lookup, clamp(ClipsRuntime.getSequenceTime(seq.id) + d, duration));
+        touched.add(seqRef(seq.id));
+    }
+}
+/** Stop everything the pad posed that is not in `keep` (authored values back). */
+export function releaseAnimations(keep = new Set()) {
+    for (const ref of [...touched]) {
+        if (keep.has(ref))
+            continue;
+        const id = ref.slice(ref.indexOf(':') + 1);
+        if (ref.startsWith('clip:'))
+            ClipsRuntime.stop(id);
+        else
+            ClipsRuntime.stopSequence(id);
+        touched.delete(ref);
+    }
+}

package/dist/keyPad/keyPadMotion.d.ts

@@ -0,0 +1,68 @@
+import type { Vector3Array } from '@3driseai/3drise-core';
+export type KeyPadKey = 'up' | 'down' | 'left' | 'right' | 'zoomIn' | 'zoomOut' | 'pan' | 'alt' | 'home';
+/** Modifier keys: held on the keyboard, or latched by a KeyPad click. */
+export type KeyPadModifier = 'pan' | 'alt';
+/**
+ * What the keyboard (and the KeyPad's arrows) drive:
+ *   none       no keyboard control (the KeyPad's buttons still orbit)
+ *   orbit      orbit first, Alt = fly
+ *   fly        fly first, Alt = orbit
+ *   animation  ← / → play the chosen animations / clips back / forward, ↑ / ↓ speed
+ */
+export type KeyPadControlMode = 'none' | 'orbit' | 'fly' | 'animation';
+export declare const CONTROL_MODES: {
+    value: KeyPadControlMode;
+    label: string;
+}[];
+/** Fly style right now: the mode's default, flipped while Alt is held / latched. */
+export declare const isFlying: (mode: KeyPadControlMode, held: ReadonlySet<KeyPadKey>) => boolean;
+/** Keys that move the camera while held (home is one-shot, pan is a modifier). */
+export declare const HELD_MOVE_KEYS: KeyPadKey[];
+/** Real keyboard → KeyPad key. Matched on KeyboardEvent.key. */
+export declare const KEYBOARD_MAP: Record<string, KeyPadKey>;
+/** Shown on the KeyPad buttons' tooltips. */
+export declare const KEY_HINTS: Record<KeyPadKey, string>;
+/** Orbit around the orbit point by (theta, phi) radians; the controls' limits clamp in update(). */
+export declare function orbitBy(dTheta: number, dPhi: number): void;
+/** Slide camera + orbit point together in the view plane (x right, y up), in metres. */
+export declare function panBy(dx: number, dy: number): void;
+/** Walk camera + orbit point along the view direction flattened onto the ground
+ *  (height kept). Looking straight down, "forward" is the top of the screen. */
+export declare function moveBy(d: number): void;
+export interface ZoomRange {
+    near: number;
+    far: number;
+    distance: number;
+    enabled: boolean;
+}
+export declare function zoomRange(): ZoomRange | null;
+export declare function distanceToT(d: number, r: ZoomRange): number;
+export declare function tToDistance(t: number, r: ZoomRange): number;
+/** Put the camera at `d` from the orbit point, same direction. Limits clamp in update(). */
+export declare function setOrbitDistance(d: number): void;
+/** Turn in place: swing the orbit point around the camera about world up (+ = right). */
+export declare function turnBy(a: number): void;
+/** Scale the distance to the orbit point (<1 = closer). Limits clamp in update(). */
+export declare function dollyBy(scale: number): void;
+/**
+ * One frame of camera motion.
+ * @param held   keys down (modifiers included, latched or held)
+ * @param zoom   zoom rate -1 … 1 (±1 from the +/− keys)
+ * @param fly    fly style (else orbit) — see isFlying
+ * @param arrows false: the arrows drive something else (animation mode); zoom only
+ */
+export declare function stepKeyPad(held: ReadonlySet<KeyPadKey>, zoom: number, dt: number, speed: number, fly: boolean, arrows?: boolean): void;
+/** Where the camera is and what it looks at (the orbit point). */
+export interface CameraView {
+    position: Vector3Array;
+    target: Vector3Array;
+}
+/** The live camera as a view, or null before the camera is up. */
+export declare function captureView(): CameraView | null;
+/** Glide camera and orbit point together to a view (a new glide replaces one in flight). */
+export declare function glideToView(view: CameraView, duration?: number): void;
+/** Main view: glide the camera to the project's saved camera position. */
+export declare function goToMainView(position: Vector3Array): Promise<void>;
+/** Is this keyboard event aimed at a text field / editor, or already handled? */
+export declare function isTypingTarget(e: KeyboardEvent): boolean;
+//# sourceMappingURL=keyPadMotion.d.ts.map

package/dist/keyPad/keyPadMotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyPadMotion.d.ts","sourceRoot":"","sources":["../../src/keyPad/keyPadMotion.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1D,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAEzG,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,KAAK,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,WAAW,CAAC;AAEvE,eAAO,MAAM,aAAa,EAAE;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAKtE,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,QAAQ,GAAI,MAAM,iBAAiB,EAAE,MAAM,WAAW,CAAC,SAAS,CAAC,YACtC,CAAC;AAEzC,kFAAkF;AAClF,eAAO,MAAM,cAAc,EAAE,SAAS,EAAyD,CAAC;AAEhG,gEAAgE;AAChE,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAYlD,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAU/C,CAAC;AAoBF,oGAAoG;AACpG,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAUnD;AAED,wFAAwF;AACxF,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAU3C;AAED;gFACgF;AAChF,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,QAe/B;AAaD,MAAM,WAAW,SAAS;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE;AAE5F,wBAAgB,SAAS,IAAI,SAAS,GAAG,IAAI,CAS5C;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAG3D;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAE3D;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,QAQzC;AAED,yFAAyF;AACzF,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,QAO/B;AAED,qFAAqF;AACrF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,QAOpC;AAQD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,UAAO,QA2B5H;AAID,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACxB;AAED,kEAAkE;AAClE,wBAAgB,WAAW,IAAI,UAAU,GAAG,IAAI,CAS/C;AASD,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,SAAM,QAuB3D;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,iBAElD;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAMxD"}