@3driseai/3drise-viewer 0.1.41 → 0.1.43

package/dist/utils/landPatch.d.ts

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import type { LandObjectConfig, LandQuality, TerrainConfig, TerrainQualityConfig } from '@3driseai/3drise-core';
+import type { LandObjectConfig, LandQuality, ShapeLayoutField, 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;
@@ -21,13 +21,34 @@ export declare function landFrame(object: THREE.Object3D, out?: LandFrame): Land
  * 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;
+export declare function applyLandPatchUniforms(material: THREE.ShaderMaterial, cfg: LandObjectConfig, frame: LandFrame, camera: THREE.Camera, 
+/** The grid is a layout's (landLayoutGeometry): its per-vertex band replaces the rectangle's. */
+layoutActive?: boolean): void;
+/**
+ * A land that keeps to a layout, as geometry: the field (core shapeLayoutField) stretched over the
+ * patch's unit grid (-0.5…0.5 on x / z), so the object's scale stretches the island with the grid —
+ * live while dragging, no rebuild — while the terrain inside stays a window in metres. `edge`: the
+ * band at the layout's edge in unit-grid units (edgeFade, a fraction of the side).
+ */
+export interface LandLayout {
+    field: ShapeLayoutField;
+    edge: number;
+}
+/**
+ * The patch grid for a land on a layout — independent of the object's scale. The unit grid with the
+ * cells that touch the layout kept, and every kept point that lies off it moved onto the layout's
+ * edge (the outline follows the layout, not the cells). Per vertex, for TerrainMaterial's
+ * LAND_LAYOUT path: the mask with its slope (per unit) and the lift (metres) with its slope.
+ * null: nothing of the grid is on the layout.
+ */
+export declare function landLayoutGeometry(segments: number, layout: LandLayout): THREE.BufferGeometry | null;
 /**
  * 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).
+ * scale.y is already in (elevation x scale.y). With a layout: the layout's mask in
+ * place of the rectangle's, plus its lift (x scale.y); 0 off the layout.
  */
-export declare function landHeightAt(cfg: LandObjectConfig, scale: THREE.Vector3, tx: number, tz: number, lodCell?: number): number;
+export declare function landHeightAt(cfg: LandObjectConfig, scale: THREE.Vector3, tx: number, tz: number, lodCell?: number, layout?: LandLayout | null): 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;
+export declare function landWorldHeightAt(object: THREE.Object3D, cfg: LandObjectConfig, x: number, z: number, layout?: LandLayout | null): number | null;
 //# sourceMappingURL=landPatch.d.ts.map

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

@@ -1 +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"}
+{"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,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAgBlI,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;AACpB,iGAAiG;AACjG,YAAY,UAAQ,GACrB,IAAI,CAkBN;AAcD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAAG,KAAK,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAwBrE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,KAAK,CAAC,cAAc,GAAG,IAAI,CAkDpG;AAGD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,SAAI,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,CAWjJ;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,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAYhJ"}

package/dist/utils/landPatch.js

@@ -56,13 +56,16 @@ const _off = new THREE.Vector2();
  * 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) {
+export function applyLandPatchUniforms(material, cfg, frame, camera, 
+/** The grid is a layout's (landLayoutGeometry): its per-vertex band replaces the rectangle's. */
+layoutActive = false) {
     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);
+    // with a layout its own edge band takes over (per vertex): the rectangle only bounds it
+    u.u_edgeWidth.value = layoutActive ? 0 : 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;
@@ -84,22 +87,132 @@ function patchMask(tx, tz, sizeX, sizeZ, edge) {
     const x = Math.min(Math.max(d / edge, 0), 1);
     return x * x * (3 - 2 * x);
 }
+const _ed = { d: 0, gx: 0, gz: 0 };
+/**
+ * The layout at unit-grid (u, v): its mask (0 at the edge … 1 past the band) and the mask's slope
+ * per unit, and its lift — the layout's height in its own metres (times scale.y where drawn). false off it.
+ */
+function layoutAt(l, u, v, out) {
+    if (!l.field.contains(u, v))
+        return false;
+    let m = 1, dmx = 0, dmz = 0;
+    if (l.edge > 1e-4) {
+        const e = l.field.edgeDistance(u, v, l.edge, _ed);
+        const x = Math.min(Math.max(e.d / l.edge, 0), 1);
+        m = x * x * (3 - 2 * x);
+        const dm = x < 1 ? (6 * x * (1 - x)) / l.edge : 0;
+        dmx = dm * e.gx;
+        dmz = dm * e.gz;
+    }
+    const h = l.field.heightAt(u, v);
+    out[0] = m;
+    out[1] = dmx;
+    out[2] = dmz;
+    out[3] = Number.isFinite(h) ? h / l.field.heightScale : 0;
+    return true;
+}
+/** The layout's height (its metres) at (u, v), NaN off it. */
+const liftAt = (l, u, v) => l.field.heightAt(u, v) / l.field.heightScale;
+/**
+ * The patch grid for a land on a layout — independent of the object's scale. The unit grid with the
+ * cells that touch the layout kept, and every kept point that lies off it moved onto the layout's
+ * edge (the outline follows the layout, not the cells). Per vertex, for TerrainMaterial's
+ * LAND_LAYOUT path: the mask with its slope (per unit) and the lift (metres) with its slope.
+ * null: nothing of the grid is on the layout.
+ */
+export function landLayoutGeometry(segments, layout) {
+    const g = new THREE.PlaneGeometry(1, 1, segments, segments);
+    g.rotateX(-Math.PI / 2);
+    const p = g.getAttribute('position');
+    const n = p.count, mask = new Float32Array(n * 3), lift = new Float32Array(n * 3);
+    const inside = new Uint8Array(n);
+    const v = [0, 0, 0, 0], cell = 1 / segments, eps = cell / 2;
+    for (let i = 0; i < n; i++) {
+        const u = p.getX(i), w = p.getZ(i);
+        if (!layoutAt(layout, u, w, v))
+            continue;
+        inside[i] = 1;
+        mask[i * 3] = v[0];
+        mask[i * 3 + 1] = v[1];
+        mask[i * 3 + 2] = v[2];
+        // the lift's slope by central differences (a side off the layout: the one-sided one)
+        const h = v[3], hx1 = liftAt(layout, u + eps, w), hx0 = liftAt(layout, u - eps, w);
+        const hz1 = liftAt(layout, u, w + eps), hz0 = liftAt(layout, u, w - eps);
+        const gx = Number.isFinite(hx1) && Number.isFinite(hx0) ? (hx1 - hx0) / (2 * eps) : Number.isFinite(hx1) ? (hx1 - h) / eps : Number.isFinite(hx0) ? (h - hx0) / eps : 0;
+        const gz = Number.isFinite(hz1) && Number.isFinite(hz0) ? (hz1 - hz0) / (2 * eps) : Number.isFinite(hz1) ? (hz1 - h) / eps : Number.isFinite(hz0) ? (h - hz0) / eps : 0;
+        lift[i * 3] = h;
+        lift[i * 3 + 1] = gx;
+        lift[i * 3 + 2] = gz;
+    }
+    // keep the triangles with a point on the layout; their points off it go onto the edge
+    const idx = g.getIndex().array, keep = [];
+    const snap = new Uint8Array(n);
+    for (let t = 0; t < idx.length; t += 3) {
+        const a = idx[t], b = idx[t + 1], c = idx[t + 2];
+        if (!inside[a] && !inside[b] && !inside[c])
+            continue;
+        keep.push(a, b, c);
+        if (!inside[a])
+            snap[a] = 1;
+        if (!inside[b])
+            snap[b] = 1;
+        if (!inside[c])
+            snap[c] = 1;
+    }
+    if (!keep.length) {
+        g.dispose();
+        return null;
+    }
+    for (let i = 0; i < n; i++) {
+        if (!snap[i])
+            continue;
+        const u = p.getX(i), w = p.getZ(i);
+        const e = layout.field.edgeDistance(u, w, cell * 2, _ed);
+        if (e.d >= cell * 2)
+            continue; // no edge near: leave it (mask 0)
+        // the nearest edge point, at the edge's own height there (a surface lookup right on the edge
+        // can miss the triangles and fall back to 0 — a lone vertex dropped or raised: a spike)
+        const ex = u - e.gx * e.d, ez = w - e.gz * e.d;
+        p.setX(i, ex);
+        p.setZ(i, ez);
+        lift[i * 3] = (e.y ?? 0) / layout.field.heightScale;
+        // no slope of its own on the edge (the shading takes it from the points inside)
+        lift[i * 3 + 1] = 0;
+        lift[i * 3 + 2] = 0;
+    }
+    p.needsUpdate = true;
+    g.setIndex(keep);
+    g.setAttribute('aLayoutMask', new THREE.BufferAttribute(mask, 3));
+    g.setAttribute('aLayoutLift', new THREE.BufferAttribute(lift, 3));
+    g.computeBoundingBox();
+    return g;
+}
+const _lv = [0, 0, 0, 0];
 /**
  * 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).
+ * scale.y is already in (elevation x scale.y). With a layout: the layout's mask in
+ * place of the rectangle's, plus its lift (x scale.y); 0 off the layout.
  */
-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));
+export function landHeightAt(cfg, scale, tx, tz, lodCell = 2, layout) {
+    let m, lift = 0;
+    if (layout) {
+        if (!layoutAt(layout, tx / scale.x, tz / scale.z, _lv))
+            return 0;
+        m = _lv[0];
+        lift = _lv[3] * scale.y;
+    }
+    else
+        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;
+        return lift;
     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;
+    return terrainHeightAt(t, tx + off.x, tz + off.y, lodCell) * m + lift;
 }
 /** 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) {
+export function landWorldHeightAt(object, cfg, x, z, layout) {
     object.updateWorldMatrix(true, false);
     const f = landFrame(object);
     // A vertical line through (x, z) in terrain space: assume the patch is not
@@ -107,7 +220,9 @@ export function landWorldHeightAt(object, cfg, x, z) {
     _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);
+    if (layout && !layout.field.contains(_v.x / f.scale.x, _v.z / f.scale.z))
+        return null; // off the layout: no ground here
+    const h = landHeightAt(cfg, f.scale, _v.x, _v.z, 2, layout);
     _v.y = h;
     _v.applyQuaternion(f.quaternion).add(f.position);
     return _v.y;

package/dist/utils/layoutPlacement.d.ts

@@ -0,0 +1,30 @@
+import { Matrix4 } from 'three';
+import type { Object3D } from 'three';
+import type { LayoutCopy } from '@3driseai/3drise-core';
+export interface PlacementOptions {
+    onGround?: boolean;
+    alignToSlope?: boolean;
+    /** Area / path layouts: in world metres (the object's scale sizes each copy, not the layout). */
+    layout?: string;
+}
+/** Layouts measured in world metres: the object's scale must not stretch where copies go. */
+export declare const isMetricLayout: (layout: string | undefined) => boolean;
+/**
+ * Writes one local matrix per copy into `out` (grown as needed). `root` is the layout
+ * root (its matrixWorld must be current). Without ground (or root) copies keep their
+ * slot height. Area / path positions are metres: divided by the root's world scale,
+ * so the object's scale sizes the copies and not the layout.
+ */
+export declare function placeCopies(copies: LayoutCopy[], opts: PlacementOptions, root: Object3D | null, out: Matrix4[]): Matrix4[];
+/** When a layout with onGround has to re-drop its copies. One per layout. */
+export declare class GroundTracker {
+    private version;
+    private last;
+    private placedOnce;
+    private pending;
+    private frame;
+    /** Call once per frame with the layout root (matrixWorld current). True = re-place now. */
+    tick(root: Object3D): boolean;
+    reset(): void;
+}
+//# sourceMappingURL=layoutPlacement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layoutPlacement.d.ts","sourceRoot":"","sources":["../../src/utils/layoutPlacement.ts"],"names":[],"mappings":"AAcA,OAAO,EAAS,OAAO,EAAuB,MAAM,OAAO,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAexD,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,6FAA6F;AAC7F,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,GAAG,SAAS,KAAG,OAAiD,CAAC;AAM9G;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAgC1H;AAKD,6EAA6E;AAC7E,qBAAa,aAAa;IACtB,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,IAAI,CAAiB;IAC7B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAK;IAElB,2FAA2F;IAC3F,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;IAa7B,KAAK,IAAI,IAAI;CAChB"}

package/dist/utils/layoutPlacement.js

@@ -0,0 +1,113 @@
+// =============================================================================
+// layoutPlacement — layout copies to local matrices, dropped onto the ground
+// =============================================================================
+//
+// core's layoutCopies gives each copy its slot transform with the variation
+// applied. This turns them into matrices in the layout root's space and, with
+// `onGround`, moves each copy vertically onto the highest ground under it
+// (groundRegistry) — optionally tilted to the slope. Shared by InstancedLayout
+// (instance matrices) and LayoutInstances (slot group transforms).
+//
+// `GroundTracker` decides when to re-drop: when the ground changed (groundVersion)
+// or the layout root moved by more than a centimetre / a hundredth of a radian —
+// not on every frame of a small physical wobble — and at most every few frames
+// while it keeps moving.
+import { Euler, Matrix4, Quaternion, Vector3 } from 'three';
+import { groundHeightAt, groundVersion } from './groundRegistry.js';
+const _pos = new Vector3();
+const _w = new Vector3();
+const _n = new Vector3();
+const _q = new Quaternion();
+const _tilt = new Quaternion();
+const _e = new Euler();
+const _s = new Vector3();
+const _inv = new Matrix4();
+const UP = new Vector3(0, 1, 0);
+/** Finite-difference step for the slope normal, in world metres. */
+const SLOPE_STEP = 0.75;
+/** Layouts measured in world metres: the object's scale must not stretch where copies go. */
+export const isMetricLayout = (layout) => layout === 'area' || layout === 'path';
+const _rootScale = new Vector3();
+const _rq = new Quaternion();
+const _rp = new Vector3();
+/**
+ * Writes one local matrix per copy into `out` (grown as needed). `root` is the layout
+ * root (its matrixWorld must be current). Without ground (or root) copies keep their
+ * slot height. Area / path positions are metres: divided by the root's world scale,
+ * so the object's scale sizes the copies and not the layout.
+ */
+export function placeCopies(copies, opts, root, out) {
+    while (out.length < copies.length)
+        out.push(new Matrix4());
+    out.length = copies.length;
+    const ground = !!opts.onGround && !!root;
+    if (ground)
+        _inv.copy(root.matrixWorld).invert();
+    const metric = isMetricLayout(opts.layout) && !!root;
+    if (metric)
+        root.matrixWorld.decompose(_rp, _rq, _rootScale);
+    for (let i = 0; i < copies.length; i++) {
+        const c = copies[i];
+        _pos.set(c.position[0], c.position[1], c.position[2]);
+        if (metric)
+            _pos.set(_pos.x / (_rootScale.x || 1), _pos.y / (_rootScale.y || 1), _pos.z / (_rootScale.z || 1));
+        _q.setFromEuler(_e.set(c.rotation[0], c.rotation[1], c.rotation[2]));
+        _s.set(c.scale[0], c.scale[1], c.scale[2]);
+        if (ground) {
+            _w.copy(_pos).applyMatrix4(root.matrixWorld);
+            const h = groundHeightAt(_w.x, _w.z);
+            if (h !== null) {
+                _w.y = h;
+                _pos.copy(_w).applyMatrix4(_inv);
+                if (opts.alignToSlope) {
+                    const hx = groundHeightAt(_w.x + SLOPE_STEP, _w.z) ?? h;
+                    const hz = groundHeightAt(_w.x, _w.z + SLOPE_STEP) ?? h;
+                    // world normal of the plane through the three samples, into root space
+                    _n.set(h - hx, SLOPE_STEP, h - hz).normalize().transformDirection(_inv);
+                    _tilt.setFromUnitVectors(UP, _n);
+                    _q.premultiply(_tilt);
+                }
+            }
+        }
+        out[i].compose(_pos, _q, _s);
+    }
+    return out;
+}
+const EPS_MOVE = 0.01;
+const REDROP_EVERY = 6;
+/** When a layout with onGround has to re-drop its copies. One per layout. */
+export class GroundTracker {
+    version = -1;
+    last = new Matrix4();
+    placedOnce = false;
+    pending = false;
+    frame = 0;
+    /** Call once per frame with the layout root (matrixWorld current). True = re-place now. */
+    tick(root) {
+        this.frame++;
+        const v = groundVersion();
+        if (v !== this.version || !this.placedOnce || moved(this.last, root.matrixWorld))
+            this.pending = true;
+        if (!this.pending)
+            return false;
+        if (this.placedOnce && this.frame % REDROP_EVERY)
+            return false;
+        this.version = v;
+        this.last.copy(root.matrixWorld);
+        this.placedOnce = true;
+        this.pending = false;
+        return true;
+    }
+    reset() { this.placedOnce = false; }
+}
+function moved(a, b) {
+    const x = a.elements, y = b.elements;
+    // translation by more than EPS_MOVE metres; rotation / scale columns by more than EPS_MOVE
+    for (let i = 0; i < 16; i++) {
+        if (i === 3 || i === 7 || i === 11 || i === 15)
+            continue;
+        if (Math.abs(x[i] - y[i]) > EPS_MOVE)
+            return true;
+    }
+    return false;
+}

package/dist/utils/linkRegistry.d.ts

@@ -0,0 +1,15 @@
+import type { BufferGeometry, Matrix4 } from 'three';
+export interface LinkPartInfo {
+    geometry: BufferGeometry;
+    /** the part's matrix relative to the source's master */
+    rel: Matrix4;
+}
+export interface LinkState {
+    status: 'shared' | 'fallback';
+    parts: LinkPartInfo[];
+    version: number;
+}
+export declare function publishLink(sourceId: string, status: LinkState['status'], parts: LinkPartInfo[]): void;
+export declare function clearLink(sourceId: string): void;
+export declare const linkState: (sourceId: string) => LinkState | undefined;
+//# sourceMappingURL=linkRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"linkRegistry.d.ts","sourceRoot":"","sources":["../../src/utils/linkRegistry.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAErD,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,wDAAwD;IACxD,GAAG,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACtB,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC9B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAGtG;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAGhD;AAED,eAAO,MAAM,SAAS,GAAI,UAAU,MAAM,KAAG,SAAS,GAAG,SAAiC,CAAC"}

package/dist/utils/linkRegistry.js

@@ -0,0 +1,11 @@
+const states = new Map();
+export function publishLink(sourceId, status, parts) {
+    const prev = states.get(sourceId);
+    states.set(sourceId, { status, parts, version: (prev?.version ?? 0) + 1 });
+}
+export function clearLink(sourceId) {
+    const prev = states.get(sourceId);
+    if (prev)
+        states.set(sourceId, { status: 'fallback', parts: [], version: prev.version + 1 });
+}
+export const linkState = (sourceId) => states.get(sourceId);

package/dist/utils/shapes.d.ts

@@ -1,5 +1,6 @@
 import { BufferGeometry } from 'three';
-export type ShapeName = 'heart' | 'box' | 'star' | 'polygon' | 'gear' | 'flower' | 'spade' | 'club' | 'diamond' | 'droplet' | 'lightning' | 'sparkle' | 'shield' | 'pawPrint' | 'superformula' | 'sphere' | 'cylinder' | 'cone' | 'torus' | 'plane' | 'ring' | 'arcPlane' | 'bentPlane' | 'bentPlaneInverse' | 'capsule' | 'icosahedron' | 'octahedron' | 'tetrahedron' | 'dodecahedron' | 'text' | 'point' | 'custom' | 'infinity';
+import { type ScriptParams } from '@3driseai/3drise-core';
+export type ShapeName = 'heart' | 'box' | 'star' | 'polygon' | 'gear' | 'flower' | 'spade' | 'club' | 'diamond' | 'droplet' | 'lightning' | 'sparkle' | 'shield' | 'pawPrint' | 'superformula' | 'sphere' | 'cylinder' | 'cone' | 'torus' | 'plane' | 'ring' | 'arcPlane' | 'bentPlane' | 'bentPlaneInverse' | 'capsule' | 'icosahedron' | 'octahedron' | 'tetrahedron' | 'dodecahedron' | 'text' | 'point' | 'custom' | 'infinity' | 'outline' | 'extrude' | 'lathe' | 'sweep' | 'svg' | 'superellipsoid' | 'torusKnot' | 'script';
 export interface ShapeOptions {
     type: ShapeName;
     curveSegments?: number;
@@ -7,7 +8,8 @@ export interface ShapeOptions {
     segments?: number;
     rings?: number;
     /** counts */
-    points?: number;
+    /** star / sparkle: the point count; outline / extrude: the plan outline as [x, z] metres */
+    points?: number | number[][];
     sides?: number;
     petals?: number;
     teeth?: number;
@@ -68,6 +70,30 @@ export interface ShapeOptions {
     /** infinity */
     waist?: number;
     thickness?: number;
+    /** parametric recipes (core ParametricShapeConfig) */
+    holes?: number[][][];
+    profile?: number[][];
+    path?: number[][];
+    curve?: number;
+    depth?: number;
+    twist?: number;
+    angle?: number;
+    cap?: boolean;
+    scaleEnd?: number;
+    closed?: boolean;
+    svg?: string;
+    svgUrl?: string;
+    orientation?: 'flat' | 'upright';
+    e1?: number;
+    e2?: number;
+    crease?: number;
+    /** torusKnot */
+    p?: number;
+    q?: number;
+    /** script */
+    source?: string;
+    params?: ScriptParams;
+    schema?: Record<string, unknown>;
 }
 export type ShapeGenerator = (opts: ShapeOptions) => BufferGeometry;
 /**

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

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

package/dist/utils/shapes.js

@@ -1,6 +1,11 @@
-import { BoxGeometry, BufferGeometry, CapsuleGeometry, ConeGeometry, CylinderGeometry, DodecahedronGeometry, ExtrudeGeometry, Float32BufferAttribute, IcosahedronGeometry, OctahedronGeometry, Path, PlaneGeometry, RingGeometry, Shape, ShapeGeometry, SphereGeometry, TetrahedronGeometry, TorusGeometry, } from 'three';
+import { BoxGeometry, BufferGeometry, CapsuleGeometry, ConeGeometry, CylinderGeometry, DodecahedronGeometry, ExtrudeGeometry, Float32BufferAttribute, IcosahedronGeometry, OctahedronGeometry, Path, PlaneGeometry, RingGeometry, Shape, ShapeGeometry, SphereGeometry, TetrahedronGeometry, TorusGeometry, TorusKnotGeometry, } from 'three';
 import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+import { buildParametricGeometry } from '@3driseai/3drise-core';
 import { buildTextGeometry, outlineFontSync } from './textShape.js';
+import { cachedScriptGeometry } from './geometryScript.js';
+import { svgAssetSync } from './svgAsset.js';
+/** A recipe generator: the config is the recipe (core buildParametricGeometry). */
+const parametric = (o) => buildParametricGeometry(o);
 const safeNumber = (value, fallback, min) => {
     const num = typeof value === 'number' && !Number.isNaN(value) ? value : fallback;
     return min !== undefined ? Math.max(num, min) : num;
@@ -222,7 +227,8 @@ export const shapeGenerators = {
         }
         return geometry;
     },
-    star: ({ points = 5, outer = 0.5, inner = 0.2, curveSegments, bevelThickness, bevelSize, bevelSegments }) => {
+    star: ({ points: count = 5, outer = 0.5, inner = 0.2, curveSegments, bevelThickness, bevelSize, bevelSegments }) => {
+        const points = typeof count === 'number' ? count : 5;
         const s = new Shape();
         for (let i = 0; i < points * 2; i++) {
             const r = i % 2 === 0 ? outer : inner;
@@ -361,7 +367,8 @@ export const shapeGenerators = {
         s.closePath();
         return extrude(s, curveSegments, bevelThickness, bevelSize, bevelSegments);
     },
-    sparkle: ({ points = 4, outer = 0.5, inner = 0.14, curveSegments, bevelThickness = 0.015, bevelSize = 0.015, bevelSegments = 1 }) => {
+    sparkle: ({ points: count = 4, outer = 0.5, inner = 0.14, curveSegments, bevelThickness = 0.015, bevelSize = 0.015, bevelSegments = 1 }) => {
+        const points = typeof count === 'number' ? count : 4;
         const step = (Math.PI * 2) / points;
         const tip = (k) => {
             const a = k * step + Math.PI / 2;
@@ -419,6 +426,28 @@ export const shapeGenerators = {
             blob(0.26, 0.10, 0.11, 0.14),
         ], false);
     },
+    /* ---------------- parametric recipes: the config is the recipe (core geometry/parametricGeometry.ts) ---------------- */
+    outline: parametric,
+    extrude: parametric,
+    lathe: parametric,
+    sweep: parametric,
+    superellipsoid: parametric,
+    svg: (o) => {
+        // an uploaded .svg is fetched once (svgAsset); until it lands the shape is empty and GeometryShape re-renders when it does
+        if (o.svgUrl) {
+            const text = svgAssetSync(o.svgUrl);
+            if (text === null)
+                return new BufferGeometry();
+            return buildParametricGeometry(o, text);
+        }
+        return parametric(o);
+    },
+    torusKnot: ({ radius = 1, tube = 0.3, p = 2, q = 3, radialSegments = 12, tubularSegments = 128 }) => new TorusKnotGeometry(safeNumber(radius, 1, 0.0001), safeNumber(tube, 0.3, 0.0001), safeNumber(tubularSegments, 128, 16), safeNumber(radialSegments, 12, 3), safeNumber(p, 2, 1), safeNumber(q, 3, 1)),
+    /* ---------------- scripted: built in the geometry worker (utils/geometryScript.ts); read from its cache here ---------------- */
+    script: ({ source = '', params = {} }) => {
+        const hit = cachedScriptGeometry(source, params);
+        return hit ? hit.geometry.clone() : new BufferGeometry();
+    },
     /* ---------------- parametric ---------------- */
     superformula: ({ symmetry = 6, // was m  — rotational symmetry (lobe / corner count)
     roundness = 0.3, // was n1 — overall inflation: lower = puffier, higher = pinched/spikier

package/dist/utils/sharedParts.d.ts

@@ -0,0 +1,61 @@
+import { InstancedMesh, Matrix4, Mesh } from 'three';
+import type { Object3D } from 'three';
+/** One drawn part: the master mesh and what draws it at every slot. */
+export interface SharedPart {
+    source: Mesh;
+    /** instanced mode: one InstancedMesh for all slots */
+    inst: InstancedMesh | null;
+    /** mirrors mode: one Mesh per slot */
+    mirrors: Mesh[] | null;
+    /** the part's matrix relative to its master */
+    rel: Matrix4;
+    relValid: boolean;
+    tintFor: string;
+    tintKey: unknown;
+}
+export interface SharedSyncInput {
+    /** Number of slots. */
+    count: number;
+    /** Slot k's matrix in the draw root's space (the master's frame there), or null = hidden. */
+    slot: (k: number) => Matrix4 | null;
+    /** Slots moved / changed since the last sync. */
+    slotsDirty: boolean;
+    /** Re-scan the master's meshes (a model landed, a geometry was rebuilt). Cheap enough every few frames. */
+    checkParts: boolean;
+    /** Per-slot tint shift [hue turns, lightness] (instanced parts only), and what it was computed from. */
+    tint?: {
+        amount: number;
+        of: (k: number) => [number, number];
+        key: unknown;
+    };
+}
+export declare const sameMatrix: (a: Matrix4, b: Matrix4) => boolean;
+/** The meshes of a master, whether they must be mirrored, and why they cannot be shared (if they cannot). */
+export declare function collectParts(master: Object3D, forceMirrors: boolean): {
+    meshes: Mesh[];
+    mirrors: boolean;
+    reason?: string;
+};
+/** Draws one master at `count` slots under `drawRoot`. One per master (a layout's variant, a link source). */
+export declare class SharedParts {
+    private readonly drawRoot;
+    /** tagged on every drawn mesh as userData.layoutVariant (picking maps a hit back to its slot) */
+    private readonly tag;
+    private readonly forceMirrors;
+    parts: SharedPart[];
+    /** Bumps when the part set changes (pick proxies rebuild on it). */
+    version: number;
+    private signature;
+    private count;
+    constructor(drawRoot: Object3D, 
+    /** tagged on every drawn mesh as userData.layoutVariant (picking maps a hit back to its slot) */
+    tag: number, forceMirrors?: boolean);
+    /** Draws the master at every slot. Returns why it cannot be shared (the caller falls back), or null. */
+    sync(master: Object3D, input: SharedSyncInput): string | null;
+    private rebuild;
+    private writeTint;
+    private disposeParts;
+    /** Takes the drawing down and puts the master's meshes back on the render layers. */
+    dispose(): void;
+}
+//# sourceMappingURL=sharedParts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sharedParts.d.ts","sourceRoot":"","sources":["../../src/utils/sharedParts.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAS,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAC5D,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,OAAO,CAAC;AAIhD,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,IAAI,CAAC;IACb,sDAAsD;IACtD,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,sCAAsC;IACtC,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IACvB,+CAA+C;IAC/C,GAAG,EAAE,OAAO,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC5B,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IACpC,iDAAiD;IACjD,UAAU,EAAE,OAAO,CAAC;IACpB,2GAA2G;IAC3G,UAAU,EAAE,OAAO,CAAC;IACpB,wGAAwG;IACxG,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;CAChF;AAUD,eAAO,MAAM,UAAU,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAInD,CAAC;AAaF,6GAA6G;AAC7G,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAkB3H;AAiBD,8GAA8G;AAC9G,qBAAa,WAAW;IAQhB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,iGAAiG;IACjG,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAVjC,KAAK,EAAE,UAAU,EAAE,CAAM;IACzB,oEAAoE;IACpE,OAAO,SAAK;IACZ,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,KAAK,CAAK;gBAGG,QAAQ,EAAE,QAAQ;IACnC,iGAAiG;IAChF,GAAG,EAAE,MAAM,EACX,YAAY,UAAQ;IAKzC,wGAAwG;IACxG,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI;IAuD7D,OAAO,CAAC,OAAO;IAmCf,OAAO,CAAC,SAAS;IA6BjB,OAAO,CAAC,YAAY;IASpB,qFAAqF;IACrF,OAAO;CAMV"}