@3driseai/3drise-viewer 0.1.26 → 0.1.28

package/dist/components/GridsGenerator.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useRef } from 'react';
 import { useObjectReady } from '../hooks/useObjectReady.js';
 import GridHelper from "./GridHelper.js";
-import AdvanvcedGrid from "./AdvancedGrid.js";
+import AdvancedGrid from "./AdvancedGrid.js";
 import CircuitGrid from "./CircuitGrid.js";
 import ContourGrid from "./ContourGrid.js";
 import FractalGrid from "./FractalGrid.js";
@@ -18,48 +18,71 @@ import GravWaveGrid from "./GravWaveGrid.js";
 import GirihGrid from "./GirihGrid.js";
 import WallpaperGrid from "./WallpaperGrid.js";
 import ReactionDiffusionGrid from "./ReactionDiffusionGrid.js";
-const GridGenerator = ({ config, onObjectReady, onObjectDispose }) => {
+import LensingGrid from "./LensingGrid.js";
+import ConformalGrid from "./ConformalGrid.js";
+import TruchetGrid from "./TruchetGrid.js";
+import PhyllotaxisGrid from "./PhyllotaxisGrid.js";
+import ParastichyGrid from "./ParastichyGrid.js";
+import ApollonianGrid from "./ApollonianGrid.js";
+import HilbertGrid from "./HilbertGrid.js";
+const GridGenerator = ({ config, id, keyframes, mouseMove, onObjectReady, onObjectDispose }) => {
     // The other branches render components that report themselves; the
     // native <gridHelper> is a plain three object, so this component holds its
     // ref and reports on its behalf. The ref stays null on the other branches,
     // which the hook treats as nothing to report.
     const nativeGridRef = useRef(null);
     useObjectReady(nativeGridRef, config, onObjectReady, onObjectDispose);
+    // Grids on the config pattern (listed in GRIDS_ANIMATABLE) take the domain drivers.
+    const driven = { id, keyframes, mouseMove };
     switch (config.type) {
         case "basic":
             return _jsx(GridHelper, { ...config, side: 2, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "advancedGrid":
-            return _jsx(AdvanvcedGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(AdvancedGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "hexGrid":
-            return _jsx(HexGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(HexGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "circuitGrid":
-            return _jsx(CircuitGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(CircuitGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "voronoiGrid":
-            return _jsx(VoronoiGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(VoronoiGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "radarGrid":
-            return _jsx(RadarGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(RadarGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "moireGrid":
-            return _jsx(MoireGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(MoireGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "fractalGrid":
-            return _jsx(FractalGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(FractalGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "contourGrid":
-            return _jsx(ContourGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(ContourGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "quasiGrid":
-            return _jsx(QuasiGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(QuasiGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "flowNetGrid":
-            return _jsx(FlowNetGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(FlowNetGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "chladniGrid":
-            return _jsx(ChladniGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(ChladniGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "hyperbolicGrid":
-            return _jsx(HyperbolicGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(HyperbolicGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "gravWaveGrid":
-            return _jsx(GravWaveGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(GravWaveGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "girihGrid":
-            return _jsx(GirihGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(GirihGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "wallpaperGrid":
-            return _jsx(WallpaperGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(WallpaperGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         case "reactionDiffusionGrid":
-            return _jsx(ReactionDiffusionGrid, { config: config, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+            return _jsx(ReactionDiffusionGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+        case "lensingGrid":
+            return _jsx(LensingGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+        case "conformalGrid":
+            return _jsx(ConformalGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+        case "truchetGrid":
+            return _jsx(TruchetGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+        case "phyllotaxisGrid":
+            return _jsx(PhyllotaxisGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+        case "parastichyGrid":
+            return _jsx(ParastichyGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+        case "apollonianGrid":
+            return _jsx(ApollonianGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
+        case "hilbertGrid":
+            return _jsx(HilbertGrid, { config: config, ...driven, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose });
         default:
             return _jsx("gridHelper", { ...config, ref: nativeGridRef });
     }

package/dist/components/HexGrid.d.ts

@@ -1,9 +1,16 @@
 import type { ThreeElements } from '@react-three/fiber';
 import type { ObjectReadyProps } from '../types/objectReady';
 import type { HexGridConfig } from '../types/gridConfigs';
+import type { AnimationOptions, MouseMoveDomain } from '@3driseai/3drise-core';
 export interface HexGridProps extends ObjectReadyProps {
     config?: HexGridConfig;
     groupProps?: ThreeElements['group'];
+    /** Scene object id: the live-edit handle is found by it. */
+    id?: string;
+    /** Keyframes on this grid's config knobs (animations.grid.animations). */
+    keyframes?: AnimationOptions[];
+    /** Pointer bindings on this grid's config knobs (mouseMove.grid). */
+    mouseMove?: MouseMoveDomain;
 }
 /**
  * HexGridConfig — the single source of truth for a honeycomb grid instance.
@@ -11,15 +18,6 @@ export interface HexGridProps extends ObjectReadyProps {
  * any preset/serialisation layer, matching `defaultMyGridConfig`.
  */
 export declare const defaultHexGridConfig: HexGridConfig;
-/**
- * A honeycomb grid on a shader plane.
- *
- * Same knobs as `AdvancedGrid` — `lineMode` / `cellMode` run 0..4 through
- * static, ripple, flow, scan and pulse — applied to a hex lattice instead of a
- * square one, so ripples propagate as hexagons rather than circles. With
- * `displace > 0` and `plateau` on, every hex lifts to its own height and the
- * surface breaks into plates.
- */
-export declare function HexGrid({ config, groupProps, onObjectReady, onObjectDispose }: HexGridProps): import("react").JSX.Element;
+export declare function HexGrid({ config, groupProps, id, keyframes, mouseMove, onObjectReady, onObjectDispose }: HexGridProps): import("react").JSX.Element;
 export default HexGrid;
 //# sourceMappingURL=HexGrid.d.ts.map

package/dist/components/HexGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HexGrid.d.ts","sourceRoot":"","sources":["../../src/components/HexGrid.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IAClD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACvC;AAKD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,aA0BlC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,EAAE,MAA6B,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,YAAY,+BAiElH;AAED,eAAe,OAAO,CAAC"}
+{"version":3,"file":"HexGrid.d.ts","sourceRoot":"","sources":["../../src/components/HexGrid.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAOxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE/E,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IAClD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAKD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,aA0BlC,CAAC;AAoBF,wBAAgB,OAAO,CAAC,EAAE,MAA6B,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,YAAY,+BA+C5I;AAED,eAAe,OAAO,CAAC"}

package/dist/components/HexGrid.js

@@ -1,9 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useRef } from 'react';
+import { useCallback, useLayoutEffect, useMemo, useRef } from 'react';
 import * as THREE from 'three';
 import { useObjectReady } from '../hooks/useObjectReady.js';
 import { useGridSurface } from '../hooks/useGridSurface.js';
-import { HexGridMaterial } from '@3driseai/3drise-core';
+import { useConfigDriver } from '../hooks/useConfigDriver.js';
+import { withConfigDefaults } from '../utils/configAnimations.js';
+import { applyGridConfig, GRID_STRUCTURAL } from '../utils/gridConfig.js';
+import { HexGridMaterial, GRIDS_ANIMATABLE } from '@3driseai/3drise-core';
 // Side-effect import registers <hexGridMaterial> via extend() in HexGridMaterial.ts.
 void HexGridMaterial;
 /**
@@ -47,26 +50,41 @@ export const defaultHexGridConfig = {
  * `displace > 0` and `plateau` on, every hex lifts to its own height and the
  * surface breaks into plates.
  */
-export function HexGrid({ config = defaultHexGridConfig, groupProps, onObjectReady, onObjectDispose }) {
+/** This grid's own uniforms (u_<key>), pushed by applyGridConfig beside the shared surface knobs. */
+const VARIANT = [];
+/** Computed uniforms (clamps, enum indices, booleans as 0/1). */
+const DERIVE = { plateau: (c) => c.plateau ? 1 : 0 };
+/** Knobs that rebuild the plane or pick a mode: they change on commit, never through the live path. */
+const STRUCTURAL = [...GRID_STRUCTURAL, 'plateau'];
+/** Knobs a keyframe or pointer binding may drive per frame — exactly what applyGridConfig pushes. */
+const ANIMATABLE = new Set((GRIDS_ANIMATABLE.hexGrid ?? []).map((p) => p.value));
+export function HexGrid({ config = defaultHexGridConfig, groupProps, id, keyframes, mouseMove, onObjectReady, onObjectDispose }) {
     const matRef = useRef(null);
     const rootRef = useRef(null);
     const meshRef = useRef(null);
     useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
-    const { cellSize, size, segments, flat, lineMode, cellMode, lineWidth, sectionSize, sectionWidth, animSpeed, animScale, animIntensity, fadeDistance, fadeStrength, displace, plateau, lineColor, sectionColor, cellColor, glowColor, bgColor, bgOpacity, followMouse, reveal, revealDuration, } = config;
+    // The committed config over this grid's defaults: every knob has a value to render
+    // and for a keyframe or pointer binding to start from.
+    const base = useMemo(() => withConfigDefaults(defaultHexGridConfig, config), [config]);
+    const { cellSize, size, segments, flat, displace, followMouse, reveal, revealDuration } = base;
     // Plateaus need a dense mesh: the vertical walls between hexes are only as
     // crisp as the tessellation that has to fake them.
     const segs = segments ?? (displace > 0
         ? Math.min(512, Math.max(96, Math.ceil(size / Math.max(cellSize, 1e-4)) * 4))
         : 1);
-    const fade = fadeDistance ?? size * 0.5;
-    const colors = useMemo(() => ({
-        line: new THREE.Color(lineColor),
-        section: new THREE.Color(sectionColor),
-        cell: new THREE.Color(cellColor),
-        glow: new THREE.Color(glowColor),
-        bg: new THREE.Color(bgColor),
-    }), [lineColor, sectionColor, cellColor, glowColor, bgColor]);
     useGridSurface(matRef, meshRef, { followMouse, reveal, revealDuration });
-    return (_jsx("group", { ref: rootRef, ...groupProps, children: _jsxs("mesh", { ref: meshRef, rotation: flat ? [-Math.PI / 2, 0, 0] : [0, 0, 0], children: [_jsx("planeGeometry", { args: [size, size, segs, segs] }), _jsx("hexGridMaterial", { ref: matRef, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide, u_cellSize: cellSize, u_lineWidth: lineWidth, u_sectionSize: sectionSize, u_sectionWidth: sectionWidth, u_lineMode: lineMode, u_cellMode: cellMode, u_animSpeed: animSpeed, u_animScale: animScale, u_animIntensity: animIntensity, u_fadeDistance: fade, u_fadeStrength: fadeStrength, u_displace: displace, u_plateau: plateau ? 1 : 0, u_lineColor: colors.line, u_sectionColor: colors.section, u_cellColor: colors.cell, u_glowColor: colors.glow, u_bgColor: colors.bg, u_bgOpacity: bgOpacity }, HexGridMaterial.key)] }) }));
+    // One push point for every uniform the config owns: the committed config when the
+    // material mounts or the config commits, the merged one while anything overrides it.
+    const baseRef = useRef(base);
+    baseRef.current = base;
+    const setMaterial = useCallback((m) => {
+        matRef.current = m;
+        if (m)
+            applyGridConfig(m, baseRef.current, VARIANT, DERIVE);
+    }, []);
+    useLayoutEffect(() => { applyGridConfig(matRef.current, base, VARIANT, DERIVE); }, [base]);
+    const push = useCallback((merged) => applyGridConfig(matRef.current, merged, VARIANT, DERIVE), []);
+    useConfigDriver({ rootRef, id, family: 'grids', base, structural: STRUCTURAL, allowed: ANIMATABLE, keyframes, mouseMove, push });
+    return (_jsx("group", { ref: rootRef, ...groupProps, children: _jsxs("mesh", { ref: meshRef, rotation: flat ? [-Math.PI / 2, 0, 0] : [0, 0, 0], children: [_jsx("planeGeometry", { args: [size, size, segs, segs] }), _jsx("hexGridMaterial", { ref: setMaterial, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide }, HexGridMaterial.key)] }) }));
 }
 export default HexGrid;

package/dist/components/HilbertGrid.d.ts

@@ -0,0 +1,25 @@
+import type { ThreeElements } from '@react-three/fiber';
+import type { ObjectReadyProps } from '../types/objectReady';
+import type { HilbertGridConfig } from '../types/gridConfigs';
+import type { AnimationOptions, MouseMoveDomain } from '@3driseai/3drise-core';
+export interface HilbertGridProps extends ObjectReadyProps {
+    config?: HilbertGridConfig;
+    groupProps?: ThreeElements['group'];
+    /** Scene object id: the live-edit handle is found by it. */
+    id?: string;
+    /** Keyframes on this grid's config knobs (animations.grid.animations). */
+    keyframes?: AnimationOptions[];
+    /** Pointer bindings on this grid's config knobs (mouseMove.grid). */
+    mouseMove?: MouseMoveDomain;
+}
+/** HilbertGridConfig defaults. Must match the catalog entry in grid-defaults.json exactly. */
+export declare const defaultHilbertGridConfig: HilbertGridConfig;
+/**
+ * A closed Moore curve — four Hilbert curves joined into one loop — threads every cell once while keeping neighbours on the line neighbours on the plane. Signals with exponential trails circulate along it; the accent is the same curve one level coarser.
+ *
+ * The grid always lies flat: any other orientation, and any movement of the
+ * whole, is the parent object's transform. Only what happens inside it animates.
+ */
+export declare function HilbertGrid({ config, groupProps, id, keyframes, mouseMove, onObjectReady, onObjectDispose }: HilbertGridProps): import("react").JSX.Element;
+export default HilbertGrid;
+//# sourceMappingURL=HilbertGrid.d.ts.map

package/dist/components/HilbertGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HilbertGrid.d.ts","sourceRoot":"","sources":["../../src/components/HilbertGrid.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAQxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE/E,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACtD,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAKD,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,EAAE,iBA2BtC,CAAC;AAWF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,MAAiC,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,gBAAgB,+BAsDxJ;AAED,eAAe,WAAW,CAAC"}

package/dist/components/HilbertGrid.js

@@ -0,0 +1,93 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { useObjectReady } from '../hooks/useObjectReady.js';
+import { useGridSurface } from '../hooks/useGridSurface.js';
+import { useConfigDriver } from '../hooks/useConfigDriver.js';
+import { withConfigDefaults } from '../utils/configAnimations.js';
+import { applyGridConfig, GRID_STRUCTURAL } from '../utils/gridConfig.js';
+import { HilbertGridMaterial, GRIDS_ANIMATABLE } from '@3driseai/3drise-core';
+// Side-effect import registers <hilbertGridMaterial> via extend().
+void HilbertGridMaterial;
+/** HilbertGridConfig defaults. Must match the catalog entry in grid-defaults.json exactly. */
+export const defaultHilbertGridConfig = {
+    cellSize: 0.8,
+    size: 50,
+    segments: undefined,
+    lineMode: 0,
+    cellMode: 0,
+    lineWidth: 1.2,
+    sectionSize: 8,
+    sectionWidth: 3,
+    animSpeed: 1,
+    animScale: 0.5,
+    animIntensity: 0.6,
+    fadeDistance: undefined,
+    fadeStrength: 0.7,
+    displace: 0,
+    order: 6,
+    signals: 12,
+    trail: 40,
+    signalSpeed: 10,
+    lineColor: '#2a8a5c',
+    sectionColor: '#1d4d37',
+    cellColor: '#082016',
+    glowColor: '#5dffb0',
+    bgColor: '#020805',
+    bgOpacity: 0,
+    reveal: 1,
+    revealDuration: 0,
+};
+/** This grid's own uniforms (u_<key>), pushed by applyGridConfig beside the shared surface knobs. */
+const VARIANT = ['order', 'signals', 'trail', 'signalSpeed'];
+/** No computed uniforms: every knob maps straight to its u_<key>. */
+const DERIVE = {};
+/** Knobs that reshape the plane or pick a mode: they change on commit, never through the live path. */
+const STRUCTURAL = [...GRID_STRUCTURAL, 'order', 'signals'];
+/** Knobs a keyframe or pointer binding may drive per frame — exactly what applyGridConfig pushes. */
+const ANIMATABLE = new Set((GRIDS_ANIMATABLE.hilbertGrid ?? []).map((p) => p.value));
+/**
+ * A closed Moore curve — four Hilbert curves joined into one loop — threads every cell once while keeping neighbours on the line neighbours on the plane. Signals with exponential trails circulate along it; the accent is the same curve one level coarser.
+ *
+ * The grid always lies flat: any other orientation, and any movement of the
+ * whole, is the parent object's transform. Only what happens inside it animates.
+ */
+export function HilbertGrid({ config = defaultHilbertGridConfig, groupProps, id, keyframes, mouseMove, onObjectReady, onObjectDispose }) {
+    const matRef = useRef(null);
+    const rootRef = useRef(null);
+    const meshRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    // The committed config over this grid's defaults: every knob has a value to render
+    // and for a keyframe or pointer binding to start from.
+    const base = useMemo(() => withConfigDefaults(defaultHilbertGridConfig, config), [config]);
+    const { cellSize, size, segments, displace, reveal, revealDuration } = base;
+    const segs = segments ?? (displace > 0
+        ? Math.min(256, Math.max(64, Math.ceil(size / Math.max(cellSize, 1e-4)) * 2))
+        : 1);
+    useGridSurface(matRef, meshRef, { reveal, revealDuration });
+    // One push point for every uniform the config owns: the committed config when the
+    // material mounts or the config commits, the merged one while anything overrides it.
+    const baseRef = useRef(base);
+    baseRef.current = base;
+    const setMaterial = useCallback((m) => {
+        matRef.current = m;
+        if (m)
+            applyGridConfig(m, baseRef.current, VARIANT, DERIVE);
+    }, []);
+    useLayoutEffect(() => { applyGridConfig(matRef.current, base, VARIANT, DERIVE); }, [base]);
+    const push = useCallback((merged) => applyGridConfig(matRef.current, merged, VARIANT, DERIVE), []);
+    useConfigDriver({ rootRef, id, family: 'grids', base, structural: STRUCTURAL, allowed: ANIMATABLE, keyframes, mouseMove, push });
+    // Rate knobs are integrated here, never multiplied by time in the shader, so a
+    // keyframed or pointer-driven rate changes the speed without making the pattern
+    // jump. The knob is read from the material, i.e. the merged (driven) value.
+    useFrame((_, delta) => {
+        const u = matRef.current?.uniforms;
+        if (!u)
+            return;
+        const dt = Math.min(delta, 0.1) * u.u_animSpeed.value;
+        u.u_signalPhase.value += dt * u.u_signalSpeed.value;
+    });
+    return (_jsx("group", { ref: rootRef, ...groupProps, children: _jsxs("mesh", { ref: meshRef, rotation: [-Math.PI / 2, 0, 0], children: [_jsx("planeGeometry", { args: [size, size, segs, segs] }), _jsx("hilbertGridMaterial", { ref: setMaterial, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide }, HilbertGridMaterial.key)] }) }));
+}
+export default HilbertGrid;

package/dist/components/HyperbolicGrid.d.ts

@@ -1,15 +1,19 @@
 import type { ThreeElements } from '@react-three/fiber';
 import type { ObjectReadyProps } from '../types/objectReady';
 import type { HyperbolicGridConfig } from '../types/gridConfigs';
+import type { AnimationOptions, MouseMoveDomain } from '@3driseai/3drise-core';
 export interface HyperbolicGridProps extends ObjectReadyProps {
     config?: HyperbolicGridConfig;
     groupProps?: ThreeElements['group'];
+    /** Scene object id: the live-edit handle is found by it. */
+    id?: string;
+    /** Keyframes on this grid's config knobs (animations.grid.animations). */
+    keyframes?: AnimationOptions[];
+    /** Pointer bindings on this grid's config knobs (mouseMove.grid). */
+    mouseMove?: MouseMoveDomain;
 }
 /** HyperbolicGridConfig defaults. Must match the catalog entry in grid-defaults.json exactly. */
 export declare const defaultHyperbolicGridConfig: HyperbolicGridConfig;
-/**
- * An Escher-style {p,q} tiling of the Poincare disk. A slow Mobius translation glides the tiling through itself, and the tiles shrink without end toward the rim.
- */
-export declare function HyperbolicGrid({ config, groupProps, onObjectReady, onObjectDispose }: HyperbolicGridProps): import("react").JSX.Element;
+export declare function HyperbolicGrid({ config, groupProps, id, keyframes, mouseMove, onObjectReady, onObjectDispose }: HyperbolicGridProps): import("react").JSX.Element;
 export default HyperbolicGrid;
 //# sourceMappingURL=HyperbolicGrid.d.ts.map

package/dist/components/HyperbolicGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HyperbolicGrid.d.ts","sourceRoot":"","sources":["../../src/components/HyperbolicGrid.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGjE,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IACzD,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACvC;AAKD,iGAAiG;AACjG,eAAO,MAAM,2BAA2B,EAAE,oBA4BzC,CAAC;AAEF;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,MAAoC,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,mBAAmB,+BAgEvI;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"HyperbolicGrid.d.ts","sourceRoot":"","sources":["../../src/components/HyperbolicGrid.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAOxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE/E,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IACzD,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAKD,iGAAiG;AACjG,eAAO,MAAM,2BAA2B,EAAE,oBA4BzC,CAAC;AAcF,wBAAgB,cAAc,CAAC,EAAE,MAAoC,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,mBAAmB,+BA4CjK;AAED,eAAe,cAAc,CAAC"}

package/dist/components/HyperbolicGrid.js

@@ -1,9 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useRef } from 'react';
+import { useCallback, useLayoutEffect, useMemo, useRef } from 'react';
 import * as THREE from 'three';
 import { useObjectReady } from '../hooks/useObjectReady.js';
 import { useGridSurface } from '../hooks/useGridSurface.js';
-import { HyperbolicGridMaterial } from '@3driseai/3drise-core';
+import { useConfigDriver } from '../hooks/useConfigDriver.js';
+import { withConfigDefaults } from '../utils/configAnimations.js';
+import { applyGridConfig, GRID_STRUCTURAL } from '../utils/gridConfig.js';
+import { HyperbolicGridMaterial, GRIDS_ANIMATABLE } from '@3driseai/3drise-core';
 // Side-effect import registers <hyperbolicGridMaterial> via extend().
 void HyperbolicGridMaterial;
 /** HyperbolicGridConfig defaults. Must match the catalog entry in grid-defaults.json exactly. */
@@ -39,23 +42,38 @@ export const defaultHyperbolicGridConfig = {
 /**
  * An Escher-style {p,q} tiling of the Poincare disk. A slow Mobius translation glides the tiling through itself, and the tiles shrink without end toward the rim.
  */
-export function HyperbolicGrid({ config = defaultHyperbolicGridConfig, groupProps, onObjectReady, onObjectDispose }) {
+/** This grid's own uniforms (u_<key>), pushed by applyGridConfig beside the shared surface knobs. */
+const VARIANT = ['sides', 'valence', 'drift'];
+/** No computed uniforms: every knob maps straight to its u_<key>. */
+const DERIVE = {};
+/** Knobs that rebuild the plane or pick a mode: they change on commit, never through the live path. */
+const STRUCTURAL = [...GRID_STRUCTURAL, 'sides', 'valence'];
+/** Knobs a keyframe or pointer binding may drive per frame — exactly what applyGridConfig pushes. */
+const ANIMATABLE = new Set((GRIDS_ANIMATABLE.hyperbolicGrid ?? []).map((p) => p.value));
+export function HyperbolicGrid({ config = defaultHyperbolicGridConfig, groupProps, id, keyframes, mouseMove, onObjectReady, onObjectDispose }) {
     const matRef = useRef(null);
     const rootRef = useRef(null);
     const meshRef = useRef(null);
     useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
-    const { cellSize, size, segments, flat, lineMode, cellMode, lineWidth, sectionSize, sectionWidth, animSpeed, animScale, animIntensity, fadeDistance, fadeStrength, displace, sides, valence, drift, lineColor, sectionColor, cellColor, glowColor, bgColor, bgOpacity, followMouse, reveal, revealDuration, } = config;
+    // The committed config over this grid's defaults: every knob has a value to render
+    // and for a keyframe or pointer binding to start from.
+    const base = useMemo(() => withConfigDefaults(defaultHyperbolicGridConfig, config), [config]);
+    const { cellSize, size, segments, flat, displace, followMouse, reveal, revealDuration } = base;
     // the ripple is fine-grained relative to the disk
     const segs = segments ?? (displace > 0 ? Math.min(512, Math.max(96, Math.ceil(size / Math.max(cellSize, 1e-4)) * 64)) : 1);
-    const fade = fadeDistance ?? size * 0.5;
-    const colors = useMemo(() => ({
-        line: new THREE.Color(lineColor),
-        section: new THREE.Color(sectionColor),
-        cell: new THREE.Color(cellColor),
-        glow: new THREE.Color(glowColor),
-        bg: new THREE.Color(bgColor),
-    }), [lineColor, sectionColor, cellColor, glowColor, bgColor]);
     useGridSurface(matRef, meshRef, { followMouse, reveal, revealDuration });
-    return (_jsx("group", { ref: rootRef, ...groupProps, children: _jsxs("mesh", { ref: meshRef, rotation: flat ? [-Math.PI / 2, 0, 0] : [0, 0, 0], children: [_jsx("planeGeometry", { args: [size, size, segs, segs] }), _jsx("hyperbolicGridMaterial", { ref: matRef, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide, u_cellSize: cellSize, u_lineWidth: lineWidth, u_sectionSize: sectionSize, u_sectionWidth: sectionWidth, u_lineMode: lineMode, u_cellMode: cellMode, u_animSpeed: animSpeed, u_animScale: animScale, u_animIntensity: animIntensity, u_fadeDistance: fade, u_fadeStrength: fadeStrength, u_displace: displace, u_sides: sides, u_valence: valence, u_drift: drift, u_lineColor: colors.line, u_sectionColor: colors.section, u_cellColor: colors.cell, u_glowColor: colors.glow, u_bgColor: colors.bg, u_bgOpacity: bgOpacity }, HyperbolicGridMaterial.key)] }) }));
+    // One push point for every uniform the config owns: the committed config when the
+    // material mounts or the config commits, the merged one while anything overrides it.
+    const baseRef = useRef(base);
+    baseRef.current = base;
+    const setMaterial = useCallback((m) => {
+        matRef.current = m;
+        if (m)
+            applyGridConfig(m, baseRef.current, VARIANT, DERIVE);
+    }, []);
+    useLayoutEffect(() => { applyGridConfig(matRef.current, base, VARIANT, DERIVE); }, [base]);
+    const push = useCallback((merged) => applyGridConfig(matRef.current, merged, VARIANT, DERIVE), []);
+    useConfigDriver({ rootRef, id, family: 'grids', base, structural: STRUCTURAL, allowed: ANIMATABLE, keyframes, mouseMove, push });
+    return (_jsx("group", { ref: rootRef, ...groupProps, children: _jsxs("mesh", { ref: meshRef, rotation: flat ? [-Math.PI / 2, 0, 0] : [0, 0, 0], children: [_jsx("planeGeometry", { args: [size, size, segs, segs] }), _jsx("hyperbolicGridMaterial", { ref: setMaterial, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide }, HyperbolicGridMaterial.key)] }) }));
 }
 export default HyperbolicGrid;

package/dist/components/LandscapeBuilder.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import type { ObjectReadyProps } from '../types/objectReady';
-import type { LandscapeSettings } from '../types/landscapeConfigs';
+import type { LandscapeSettings } from '@3driseai/3drise-core';
 export interface LandscapeBuilderProps extends ObjectReadyProps {
     /** Accepts a partial or older-shaped blob. A blob with no `heightMap`
      *  normalises to nothing — a landscape without one is not a landscape, and

package/dist/components/LandscapeBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LandscapeBuilder.d.ts","sourceRoot":"","sources":["../../src/components/LandscapeBuilder.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAkB,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAIlE,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC3D;;8EAE0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAA;CAC/C;AAED;;;;;;;;;;GAUG;AACH,QAAA,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAqBrD,CAAA;AAED,eAAe,gBAAgB,CAAA"}
+{"version":3,"file":"LandscapeBuilder.d.ts","sourceRoot":"","sources":["../../src/components/LandscapeBuilder.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAkB,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAI9D,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC3D;;8EAE0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAA;CAC/C;AAED;;;;;;;;;;GAUG;AACH,QAAA,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAqBrD,CAAA;AAED,eAAe,gBAAgB,CAAA"}

package/dist/components/LandscapeBuilder.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from 'react';
-import { normalizeLandscape, normalizeLandscapeQuality } from '../types/landscapeConfigs.js';
+import { normalizeLandscape, normalizeLandscapeQuality } from '@3driseai/3drise-core';
 import LandscapeMesh from './landscape/LandscapeMesh.js';
 /**
  * The world ground.

package/dist/components/LandscapeObject.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import type { ObjectReadyProps } from '../types/objectReady';
-import type { LandscapeSettings } from '../types/landscapeConfigs';
+import type { LandscapeSettings } from '@3driseai/3drise-core';
 export interface LandscapeObjectProps extends ObjectReadyProps {
     settings: Partial<LandscapeSettings> & {
         id?: string;

package/dist/components/LandscapeObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LandscapeObject.d.ts","sourceRoot":"","sources":["../../src/components/LandscapeObject.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAkB,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAIlE,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC1D,QAAQ,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACzD;AAED;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CAqBnD,CAAA;AAED,eAAe,eAAe,CAAA"}
+{"version":3,"file":"LandscapeObject.d.ts","sourceRoot":"","sources":["../../src/components/LandscapeObject.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAkB,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAI9D,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC1D,QAAQ,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACzD;AAED;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CAqBnD,CAAA;AAED,eAAe,eAAe,CAAA"}

package/dist/components/LandscapeObject.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from 'react';
-import { normalizeLandscape, normalizeLandscapeQuality } from '../types/landscapeConfigs.js';
+import { normalizeLandscape, normalizeLandscapeQuality } from '@3driseai/3drise-core';
 import LandscapeMesh from './landscape/LandscapeMesh.js';
 /**
  * A placed landscape — a floating island, a diorama, a game tile, a table-top

package/dist/components/LensingGrid.d.ts

@@ -0,0 +1,25 @@
+import type { ThreeElements } from '@react-three/fiber';
+import type { ObjectReadyProps } from '../types/objectReady';
+import type { LensingGridConfig } from '../types/gridConfigs';
+import type { AnimationOptions, MouseMoveDomain } from '@3driseai/3drise-core';
+export interface LensingGridProps extends ObjectReadyProps {
+    config?: LensingGridConfig;
+    groupProps?: ThreeElements['group'];
+    /** Scene object id: the live-edit handle is found by it. */
+    id?: string;
+    /** Keyframes on this grid's config knobs (animations.grid.animations). */
+    keyframes?: AnimationOptions[];
+    /** Pointer bindings on this grid's config knobs (mouseMove.grid). */
+    mouseMove?: MouseMoveDomain;
+}
+/** LensingGridConfig defaults. Must match the catalog entry in grid-defaults.json exactly. */
+export declare const defaultLensingGridConfig: LensingGridConfig;
+/**
+ * A square lattice seen through a point-mass gravitational lens: the thin-lens equation bends it into an Einstein ring, an inverted inner image and a dark shadow at the core.
+ *
+ * The grid always lies flat: any other orientation, and any movement of the
+ * whole, is the parent object's transform. Only what happens inside it animates.
+ */
+export declare function LensingGrid({ config, groupProps, id, keyframes, mouseMove, onObjectReady, onObjectDispose }: LensingGridProps): import("react").JSX.Element;
+export default LensingGrid;
+//# sourceMappingURL=LensingGrid.d.ts.map

package/dist/components/LensingGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LensingGrid.d.ts","sourceRoot":"","sources":["../../src/components/LensingGrid.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAOxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE/E,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACtD,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAKD,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,EAAE,iBA0BtC,CAAC;AAWF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,MAAiC,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,gBAAgB,+BA4CxJ;AAED,eAAe,WAAW,CAAC"}

package/dist/components/LensingGrid.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useObjectReady } from '../hooks/useObjectReady.js';
+import { useGridSurface } from '../hooks/useGridSurface.js';
+import { useConfigDriver } from '../hooks/useConfigDriver.js';
+import { withConfigDefaults } from '../utils/configAnimations.js';
+import { applyGridConfig, GRID_STRUCTURAL } from '../utils/gridConfig.js';
+import { LensingGridMaterial, GRIDS_ANIMATABLE } from '@3driseai/3drise-core';
+// Side-effect import registers <lensingGridMaterial> via extend().
+void LensingGridMaterial;
+/** LensingGridConfig defaults. Must match the catalog entry in grid-defaults.json exactly. */
+export const defaultLensingGridConfig = {
+    cellSize: 2,
+    size: 50,
+    segments: undefined,
+    lineMode: 1,
+    cellMode: 2,
+    lineWidth: 1.1,
+    sectionSize: 5,
+    sectionWidth: 1.8,
+    animSpeed: 1,
+    animScale: 0.6,
+    animIntensity: 0.6,
+    fadeDistance: undefined,
+    fadeStrength: 0.7,
+    displace: 0,
+    mass: 4,
+    orbit: 0,
+    ringGlow: 0.8,
+    lineColor: '#2b4f80',
+    sectionColor: '#9fd0ff',
+    cellColor: '#0b1a33',
+    glowColor: '#ffcf8a',
+    bgColor: '#02040a',
+    bgOpacity: 0,
+    reveal: 1,
+    revealDuration: 0,
+};
+/** This grid's own uniforms (u_<key>), pushed by applyGridConfig beside the shared surface knobs. */
+const VARIANT = ['mass', 'orbit', 'ringGlow'];
+/** No computed uniforms: every knob maps straight to its u_<key>. */
+const DERIVE = {};
+/** Knobs that reshape the plane or pick a mode: they change on commit, never through the live path. */
+const STRUCTURAL = [...GRID_STRUCTURAL];
+/** Knobs a keyframe or pointer binding may drive per frame — exactly what applyGridConfig pushes. */
+const ANIMATABLE = new Set((GRIDS_ANIMATABLE.lensingGrid ?? []).map((p) => p.value));
+/**
+ * A square lattice seen through a point-mass gravitational lens: the thin-lens equation bends it into an Einstein ring, an inverted inner image and a dark shadow at the core.
+ *
+ * The grid always lies flat: any other orientation, and any movement of the
+ * whole, is the parent object's transform. Only what happens inside it animates.
+ */
+export function LensingGrid({ config = defaultLensingGridConfig, groupProps, id, keyframes, mouseMove, onObjectReady, onObjectDispose }) {
+    const matRef = useRef(null);
+    const rootRef = useRef(null);
+    const meshRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    // The committed config over this grid's defaults: every knob has a value to render
+    // and for a keyframe or pointer binding to start from.
+    const base = useMemo(() => withConfigDefaults(defaultLensingGridConfig, config), [config]);
+    const { cellSize, size, segments, displace, reveal, revealDuration } = base;
+    const segs = segments ?? (displace > 0
+        ? Math.min(256, Math.max(64, Math.ceil(size / Math.max(cellSize, 1e-4)) * 2))
+        : 1);
+    useGridSurface(matRef, meshRef, { reveal, revealDuration });
+    // One push point for every uniform the config owns: the committed config when the
+    // material mounts or the config commits, the merged one while anything overrides it.
+    const baseRef = useRef(base);
+    baseRef.current = base;
+    const setMaterial = useCallback((m) => {
+        matRef.current = m;
+        if (m)
+            applyGridConfig(m, baseRef.current, VARIANT, DERIVE);
+    }, []);
+    useLayoutEffect(() => { applyGridConfig(matRef.current, base, VARIANT, DERIVE); }, [base]);
+    const push = useCallback((merged) => applyGridConfig(matRef.current, merged, VARIANT, DERIVE), []);
+    useConfigDriver({ rootRef, id, family: 'grids', base, structural: STRUCTURAL, allowed: ANIMATABLE, keyframes, mouseMove, push });
+    return (_jsx("group", { ref: rootRef, ...groupProps, children: _jsxs("mesh", { ref: meshRef, rotation: [-Math.PI / 2, 0, 0], children: [_jsx("planeGeometry", { args: [size, size, segs, segs] }), _jsx("lensingGridMaterial", { ref: setMaterial, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide }, LensingGridMaterial.key)] }) }));
+}
+export default LensingGrid;