@3driseai/3drise-viewer 0.1.42 → 0.1.44

package/dist/components/layout/InstancedLayout.js

@@ -0,0 +1,154 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// =============================================================================
+// InstancedLayout — a mesh / model layout drawn as one InstancedMesh per part
+// =============================================================================
+//
+// The part machinery (instanced / mirrors, sync, tint) lives in utils/sharedParts.ts and
+// is shared with linked instances (LinkedSource). This file adds the layout: copies,
+// variants, ground placement, clicks.
+//
+// Master + mirrors. The object renders ONCE, as itself (the master: the real
+// CustomPrimitive / ModelPrimitive inside its CreatedObject), so everything that
+// already works on an object keeps working on the layout untouched: material
+// application and material clips, model-part tracks, object effects, findById,
+// readiness. Its meshes stay in the scene graph but are taken off the render
+// layers (layers.mask = 0): they are not drawn and not picked.
+//
+// Beside it, one InstancedMesh per master mesh SHARES the master's geometry and
+// material by reference. Each frame a cheap sync copies over whatever the master
+// swapped (material, geometry, visibility, shadow flags); instance matrices are
+// rewritten only when an input changed: the copies (layout / variation), the
+// ground (onGround), or a part's own matrix (a clip moving a model part).
+//
+// - instance matrix = copy (slot × variation, on the ground) × partRel, where
+//   partRel is the part's matrix relative to its master.
+// - The instanced group carries SELF_OWNED_MATERIAL_KEY (useMaterialApplication
+//   skips it: no material clones per copy) and every instanced mesh carries
+//   __opFxHelper (object effects work on the master only; the copies show the
+//   result through the shared material).
+// - variantMix: one master per variant used, each with its own instanced set.
+// - tintJitter: instanceColor = the per-copy shifted colour / the material colour.
+// - Mirrors: an object that instances its own insides (vegetation: leaves, blades
+//   and fruit are InstancedBufferGeometry with per-leaf attributes) cannot be
+//   instanced again. Each part then gets one plain Mesh per copy (a mirror) that
+//   shares the master's geometry, material and depth material — no rebuild, no
+//   extra memory, one draw per part per copy, culled per copy. Chosen by `mirrors`
+//   (getObjectLayoutSupport mode) or automatically when a master part has
+//   InstancedBufferGeometry. Every part of that master is mirrored, so the parts of
+//   one copy stay together (their shaders read modelMatrix, e.g. the plant wind).
+// - Falls back (onFallback) when a part cannot be instanced: a skinned mesh, a
+//   line / points object, or a shader material with no instancing in its vertex
+//   shader. ObjectNode then renders full copies with the copies limit.
+//
+// The 18 Oct rule holds: one master per variant, so every animation, effect or
+// config change on the object reaches every copy.
+import { memo, useEffect, useMemo, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { layoutCopies, objectForVariant } from '@3driseai/3drise-core';
+import { GroundTracker, isMetricLayout, placeCopies } from '../../utils/layoutPlacement.js';
+import { SharedParts } from '../../utils/sharedParts.js';
+const PART_CHECK_EVERY = 10;
+const InstancedLayout = memo(({ createdObject, layout, render, handleObjectClick, onFallback, mirrors: forceMirrors = false }) => {
+    const rootRef = useRef(null);
+    const instRootRef = useRef(null);
+    const proxyRef = useRef(null);
+    // ObjectNode normalises the block on every render, so key on its contents.
+    const layoutKey = JSON.stringify(layout);
+    const copies = useMemo(() => layoutCopies(layout, layout.count), [layoutKey]); // eslint-disable-line react-hooks/exhaustive-deps
+    const mix = layout.variantMix && layout.variantMix.values?.length ? layout.variantMix : null;
+    // copies grouped by variant (-1 = the object as it is)
+    const variants = useMemo(() => {
+        const by = new Map();
+        copies.forEach((c, i) => { const v = mix ? c.variant : -1; (by.get(v) ?? by.set(v, []).get(v)).push(i); });
+        return [...by.entries()].sort((a, b) => a[0] - b[0]);
+    }, [copies, mix]);
+    const sets = useRef([]);
+    const dropped = useRef([]);
+    // one VariantSet per variant, kept across renders (the master group refs are filled by React)
+    const prevSets = sets.current;
+    sets.current = variants.map(([variant, list]) => {
+        const prev = prevSets.find(s => s.variant === variant);
+        if (prev) {
+            if (prev.copies.join() !== list.join()) {
+                prev.copies = list;
+                prev.dirty = true;
+            }
+            return prev;
+        }
+        return { variant, master: null, copies: list, shared: null, dirty: true };
+    });
+    for (const s of prevSets)
+        if (!sets.current.includes(s))
+            dropped.current.push(s); // disposed next frame
+    const matrices = useRef([]);
+    const tracker = useMemo(() => new GroundTracker(), []);
+    const placedFor = useRef(null);
+    const fellBack = useRef(false);
+    const frame = useRef(0);
+    useEffect(() => () => { sets.current.forEach(s => s.shared?.dispose()); dropped.current.forEach(s => s.shared?.dispose()); }, []);
+    useFrame(() => {
+        const root = rootRef.current, g = instRootRef.current;
+        if (!root || !g || fellBack.current)
+            return;
+        const checkParts = !(frame.current++ % PART_CHECK_EVERY);
+        if (dropped.current.length) {
+            dropped.current.forEach(s => s.shared?.dispose());
+            dropped.current = [];
+        }
+        root.updateWorldMatrix(true, false);
+        // copies -> local matrices (re-dropped onto the ground only when it or the root moved)
+        let copiesDirty = false;
+        if (placedFor.current !== copies) {
+            placedFor.current = copies;
+            tracker.reset();
+            copiesDirty = true;
+        }
+        // ground and metre layouts depend on where the root is: re-placed when it moves
+        const tracksRoot = !!layout.onGround || isMetricLayout(layout.layout);
+        if (tracksRoot ? tracker.tick(root) : copiesDirty) {
+            placeCopies(copies, layout, root, matrices.current);
+            copiesDirty = true;
+        }
+        for (const s of sets.current) {
+            if (!s.master)
+                continue;
+            s.shared ??= new SharedParts(g, s.variant, forceMirrors);
+            const list = s.copies;
+            const reason = s.shared.sync(s.master, {
+                count: list.length,
+                slot: (k) => matrices.current[list[k]] ?? null,
+                slotsDirty: copiesDirty || s.dirty,
+                checkParts,
+                tint: { amount: layout.tintJitter ?? 0, of: (k) => copies[list[k]].tint, key: copies },
+            });
+            s.dirty = false;
+            if (reason) {
+                fellBack.current = true;
+                sets.current.forEach(x => x.shared?.dispose());
+                onFallback(reason);
+                return;
+            }
+        }
+    });
+    // Clicks: the copy that was hit, as a stand-in object at its transform (zoom / focus target it).
+    const onClick = handleObjectClick
+        ? (e) => {
+            const hit = e.object;
+            const set = sets.current.find(s => s.variant === hit.userData?.layoutVariant);
+            // an instanced part reports the instance; a mirror carries its copy
+            const k = hit.isInstancedMesh ? e.instanceId : hit.userData?.layoutCopy;
+            const ci = set && k !== undefined ? set.copies[k] : undefined;
+            const proxy = proxyRef.current;
+            if (ci === undefined || !proxy || !matrices.current[ci])
+                return;
+            e.stopPropagation();
+            matrices.current[ci].decompose(proxy.position, proxy.quaternion, proxy.scale);
+            proxy.updateMatrixWorld(true);
+            handleObjectClick(createdObject, proxy, e);
+        }
+        : undefined;
+    return (_jsxs("group", { ref: rootRef, name: "layout-instanced", children: [variants.map(([variant], i) => (_jsx("group", { name: `layout-master-${variant}`, ref: (m) => { const s = sets.current.find(x => x.variant === variant); if (s)
+                    s.master = m; }, children: render(objectForVariant(createdObject, mix, variant), i) }, variant))), _jsx("group", { ref: instRootRef, name: "layout-instances", onClick: onClick }), _jsx("group", { ref: proxyRef, name: "layout-picked-copy" })] }));
+});
+InstancedLayout.displayName = 'InstancedLayout';
+export default InstancedLayout;

package/dist/components/layout/LayoutGrounds.d.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+import * as THREE from 'three';
+import { type ShapeLayout } from '@3driseai/3drise-core';
+/** How the geometry's UVs are measured: 'metres' (u = x m — a mesh) or 'unit' (0…1 across the object — a land, tiled by its world scale each frame). */
+export type GroundUvMode = 'metres' | 'unit';
+export interface LayoutGroundsProps {
+    grounds: Array<{
+        id: string;
+        geometry: THREE.BufferGeometry;
+    }>;
+    shapeLayout: ShapeLayout;
+    uv: GroundUvMode;
+    /** An untextured ground: 'object' (left to the object's material), or this material. */
+    untextured: 'object' | THREE.Material;
+    receiveShadow?: boolean;
+    castShadow?: boolean;
+}
+export default function LayoutGrounds({ grounds, shapeLayout, uv, untextured, receiveShadow, castShadow }: LayoutGroundsProps): React.JSX.Element;
+//# sourceMappingURL=LayoutGrounds.d.ts.map

package/dist/components/layout/LayoutGrounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayoutGrounds.d.ts","sourceRoot":"","sources":["../../../src/components/layout/LayoutGrounds.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+C,MAAM,OAAO,CAAC;AAEpE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAA4D,KAAK,WAAW,EAAwB,MAAM,uBAAuB,CAAC;AAkBzI,wJAAwJ;AACxJ,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,CAAC;AAgC7C,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAA;KAAE,CAAC,CAAC;IAC/D,WAAW,EAAE,WAAW,CAAC;IACzB,EAAE,EAAE,YAAY,CAAC;IACjB,wFAAwF;IACxF,UAAU,EAAE,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IACtC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB;AAYD,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,UAAU,EAAE,aAAoB,EAAE,UAAkB,EAAE,EAAE,kBAAkB,qBAmD3I"}

package/dist/components/layout/LayoutGrounds.js

@@ -0,0 +1,104 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useFrame } from '@react-three/fiber';
+import * as THREE from 'three';
+import { SELF_OWNED_MATERIAL_KEY, shapeLayoutGroundTexture, toCdn } from '@3driseai/3drise-core';
+import { resolveTextureMaps, textureResolverVersion } from '../urban/textureSetResolver.js';
+const loader = new THREE.TextureLoader();
+const cache = new Map();
+/** A map, loaded once per url (each material clones it to tile on its own). */
+function mapTexture(url, color) {
+    const key = `${color ? 'c' : 'd'}|${url}`;
+    let t = cache.get(key);
+    if (!t) {
+        t = loader.load(toCdn(url));
+        t.wrapS = t.wrapT = THREE.RepeatWrapping;
+        t.anisotropy = 4;
+        if (color)
+            t.colorSpace = THREE.SRGBColorSpace;
+        cache.set(key, t);
+    }
+    const c = t.clone();
+    c.wrapS = c.wrapT = THREE.RepeatWrapping;
+    return c;
+}
+/** A ground's standard material from its texture ref (its maps from the library when the ref names only the set). */
+function groundMaterial(ref) {
+    const m = new THREE.MeshStandardMaterial({ color: '#ffffff', roughness: 0.9, metalness: 0 });
+    const maps = (Object.values(ref.maps ?? {}).some(Boolean) ? ref.maps : resolveTextureMaps(ref)) ?? {};
+    if (maps.color)
+        m.map = mapTexture(maps.color, true);
+    if (maps.normal)
+        m.normalMap = mapTexture(maps.normal, false);
+    if (maps.roughness)
+        m.roughnessMap = mapTexture(maps.roughness, false);
+    if (maps.ao)
+        m.aoMap = mapTexture(maps.ao, false);
+    return m;
+}
+const mapsOf = (m) => [m.map, m.normalMap, m.roughnessMap, m.aoMap].filter((t) => !!t);
+/** The texture library's version — a set named before the library loaded resolves once it has. */
+function useResolverVersion() {
+    const [v, setV] = useState(textureResolverVersion());
+    useEffect(() => {
+        const t = setInterval(() => { const n = textureResolverVersion(); if (n !== v)
+            setV(n); }, 1000);
+        return () => clearInterval(t);
+    }, [v]);
+    return v;
+}
+export default function LayoutGrounds({ grounds, shapeLayout, uv, untextured, receiveShadow = true, castShadow = false }) {
+    // one material per textured ground (rebuilt when its texture changes, or the library arrives)
+    const resolverVersion = useResolverVersion();
+    const texKey = JSON.stringify(grounds.map((g) => shapeLayoutGroundTexture(shapeLayout, g.id))) + '|' + resolverVersion;
+    const materials = useMemo(() => grounds.map((g) => {
+        const ref = shapeLayoutGroundTexture(shapeLayout, g.id);
+        if (!ref)
+            return null;
+        const m = groundMaterial(ref);
+        if (uv === 'metres')
+            for (const t of mapsOf(m))
+                t.repeat.set(1 / Math.max(0.05, ref.tileSize || 4), 1 / Math.max(0.05, ref.tileSize || 4));
+        return { m, tile: Math.max(0.05, ref.tileSize || 4) };
+    }), [grounds, texKey, uv]); // eslint-disable-line react-hooks/exhaustive-deps
+    useEffect(() => () => { for (const x of materials) {
+        if (!x)
+            continue;
+        for (const t of mapsOf(x.m))
+            t.dispose();
+        x.m.dispose();
+    } }, [materials]);
+    // 'unit' UVs: the land's footprint changes with its scale — the tiling follows it every frame
+    const own = useRef(null);
+    const s = useMemo(() => new THREE.Vector3(), []);
+    useFrame(() => {
+        if (uv !== 'unit' || !own.current)
+            return;
+        own.current.updateWorldMatrix(true, false);
+        s.setFromMatrixScale(own.current.matrixWorld);
+        for (const x of materials)
+            if (x)
+                for (const t of mapsOf(x.m))
+                    t.repeat.set(Math.abs(s.x) / x.tile, Math.abs(s.z) / x.tile);
+    });
+    useEffect(() => { if (own.current)
+        own.current.userData[SELF_OWNED_MATERIAL_KEY] = true; }, []);
+    // 'object': the untextured grounds draw with the parent mesh's material (whatever the material system gave it, followed every frame)
+    const plain = useRef(null);
+    useFrame(() => {
+        if (untextured !== 'object' || !plain.current)
+            return;
+        const parent = plain.current.parent;
+        const material = parent && parent.isMesh ? parent.material : null;
+        if (!material)
+            return;
+        for (const child of plain.current.children) {
+            const m = child;
+            if (m.isMesh && m.material !== material)
+                m.material = material;
+        }
+    });
+    return (_jsxs(_Fragment, { children: [_jsx("group", { ref: own, children: grounds.map((g, k) => materials[k] && (_jsx("mesh", { name: `ground ${g.id}`, geometry: g.geometry, material: materials[k].m, receiveShadow: receiveShadow, castShadow: castShadow }, g.id))) }), _jsx("group", { ref: plain, children: grounds.map((g, k) => !materials[k] && (untextured === 'object'
+                    ? _jsx("mesh", { name: `ground ${g.id}`, geometry: g.geometry, receiveShadow: receiveShadow, castShadow: castShadow }, g.id)
+                    : _jsx("mesh", { name: `ground ${g.id}`, geometry: g.geometry, material: untextured, receiveShadow: receiveShadow, castShadow: castShadow }, g.id))) })] }));
+}

package/dist/components/layout/LinkProxies.d.ts

@@ -0,0 +1,5 @@
+declare const LinkProxies: ({ sourceId }: {
+    sourceId: string;
+}) => import("react").JSX.Element;
+export default LinkProxies;
+//# sourceMappingURL=LinkProxies.d.ts.map

package/dist/components/layout/LinkProxies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LinkProxies.d.ts","sourceRoot":"","sources":["../../../src/components/layout/LinkProxies.tsx"],"names":[],"mappings":"AAoBA,QAAA,MAAM,WAAW,GAAI,cAAc;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,gCA0BtD,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/components/layout/LinkProxies.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// =============================================================================
+// LinkProxies — invisible hit shapes of a link source's parts (pick proxies)
+// =============================================================================
+//
+// A member of a linked group (the source itself, or a linked instance) is drawn by the
+// source's shared drawing, outside its own subtree. So that hover, click, selection and
+// the gizmo still treat it as its own object, it carries one invisible mesh per source
+// part: the same geometry at the part's place, a pick material with material.visible
+// off (hit by the pointer and counted in bounds, never drawn — no draw call).
+// Rebuilt when the source publishes a new part set (linkRegistry version).
+import { useEffect, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { Mesh } from 'three';
+import { SELF_OWNED_MATERIAL_KEY } from '@3driseai/3drise-core';
+import { linkState } from '../../utils/linkRegistry.js';
+import { pickMaterial, PICK_PROXY_NAME } from '../../utils/pickProxy.js';
+const material = (() => { const m = pickMaterial(); m.visible = false; return m; })();
+const LinkProxies = ({ sourceId }) => {
+    const ref = useRef(null);
+    const version = useRef(-1);
+    useEffect(() => {
+        const g = ref.current;
+        // material application and object effects leave the proxies alone
+        if (g) {
+            g.userData[SELF_OWNED_MATERIAL_KEY] = true;
+            g.userData.__opFxHelper = true;
+        }
+        return () => { g?.clear(); };
+    }, []);
+    useFrame(() => {
+        const g = ref.current, st = linkState(sourceId);
+        if (!g || !st || st.version === version.current)
+            return;
+        version.current = st.version;
+        g.clear();
+        if (st.status !== 'shared')
+            return;
+        for (const p of st.parts) {
+            const m = new Mesh(p.geometry, material);
+            m.name = PICK_PROXY_NAME;
+            m.userData.__opFxHelper = true;
+            m.matrixAutoUpdate = false;
+            m.matrix.copy(p.rel);
+            m.castShadow = m.receiveShadow = false;
+            g.add(m);
+        }
+    });
+    return _jsx("group", { ref: ref, name: "link-proxies" });
+};
+export default LinkProxies;

package/dist/components/layout/LinkedSource.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+export interface LinkedSourceProps {
+    sourceId: string;
+    /** The linked instances' ids (ObjectTreeNode.linkedIds). */
+    memberIds: string[];
+    /** The source's own renderer output (the master). */
+    children: ReactNode;
+    /** Draw as mirrors (vegetation) — see utils/sharedParts. */
+    mirrors?: boolean;
+    onFallback: (reason: string) => void;
+}
+declare const LinkedSource: ({ sourceId, memberIds, children, mirrors, onFallback }: LinkedSourceProps) => import("react").JSX.Element;
+export default LinkedSource;
+//# sourceMappingURL=LinkedSource.d.ts.map

package/dist/components/layout/LinkedSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LinkedSource.d.ts","sourceRoot":"","sources":["../../../src/components/layout/LinkedSource.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAUvC,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,qDAAqD;IACrD,QAAQ,EAAE,SAAS,CAAC;IACpB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAaD,QAAA,MAAM,YAAY,GAAI,wDAAgE,iBAAiB,gCAqFtG,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/components/layout/LinkedSource.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// =============================================================================
+// LinkedSource — a link source draws itself and every linked instance in one go
+// =============================================================================
+//
+// Rendered by ObjectNode in place of the source's own renderer output when other
+// objects are linked to it (meshSettings.instanceOf — core linkedInstances.ts).
+//
+// - The master is the source's renderer output, as itself, inside its CreatedObject:
+//   material application, material clips, model-part tracks and object effects work
+//   on it unchanged and reach every member through the shared material.
+// - The drawing (utils/sharedParts: one InstancedMesh per part, or mirrors for
+//   vegetation) lives at the scene root, one slot per member: the source first, then
+//   each linked instance at its own CreatedObject's world matrix. Hiding the source
+//   hides its slot only; a hidden member (or one under a hidden group) is skipped.
+// - Every member, the source included, carries LinkProxies so hover, click,
+//   selection and the gizmo work on it as its own object.
+// - A part that cannot be shared (skinned, points / lines, a shader without
+//   instancing) → onFallback: the source renders normally and every linked instance
+//   renders the source's look on its own (linkRegistry status 'fallback').
+import { useEffect, useMemo, useRef } from 'react';
+import { useFrame, useThree } from '@react-three/fiber';
+import { Group, Matrix4 } from 'three';
+import { findById } from '../../utils/sceneQuery.js';
+import { shownInScene } from '../../utils/shownInScene.js';
+import { SharedParts, sameMatrix } from '../../utils/sharedParts.js';
+import { clearLink, publishLink } from '../../utils/linkRegistry.js';
+import LinkProxies from './LinkProxies.js';
+const PART_CHECK_EVERY = 10;
+/** Whether `o` still hangs under `scene` (a remounted object leaves a detached old root behind). */
+function attachedTo(o, scene) {
+    for (let p = o; p; p = p.parent)
+        if (p === scene)
+            return true;
+    return false;
+}
+const _rootInv = new Matrix4();
+const _masterInRoot = new Matrix4();
+const _next = new Matrix4();
+const LinkedSource = ({ sourceId, memberIds, children, mirrors = false, onFallback }) => {
+    const scene = useThree(s => s.scene);
+    const masterRef = useRef(null);
+    const drawRoot = useMemo(() => { const g = new Group(); g.name = `linked-drawing:${sourceId}`; return g; }, [sourceId]);
+    const shared = useMemo(() => new SharedParts(drawRoot, 0, mirrors), [drawRoot, mirrors]);
+    useEffect(() => {
+        scene.add(drawRoot);
+        return () => { shared.dispose(); drawRoot.removeFromParent(); clearLink(sourceId); };
+    }, [scene, drawRoot, shared, sourceId]);
+    const ids = useMemo(() => [sourceId, ...memberIds], [sourceId, memberIds.join()]); // eslint-disable-line react-hooks/exhaustive-deps
+    // last frame's member matrices (world × master-in-root) and whether each was shown
+    const slots = useRef([]);
+    const shown = useRef([]);
+    const published = useRef({ version: -1, masterInRoot: new Matrix4() });
+    const frame = useRef(0);
+    const fellBack = useRef(false);
+    // member roots, cached: findById walks the scene, so it runs only for a root that is missing
+    // or no longer attached (remounted) — and for a missing one at most every few frames
+    const roots = useRef(new Map());
+    const rootOf = (id) => {
+        const cached = roots.current.get(id);
+        if (cached && attachedTo(cached, scene))
+            return cached;
+        if (cached === undefined || frame.current % PART_CHECK_EVERY === 0) {
+            const found = findById(id);
+            if (found)
+                roots.current.set(id, found);
+            else
+                roots.current.delete(id);
+            return found;
+        }
+        return null;
+    };
+    useEffect(() => { fellBack.current = false; }, [ids]);
+    useFrame(() => {
+        const master = masterRef.current;
+        if (!master || fellBack.current)
+            return;
+        const sourceRoot = rootOf(sourceId);
+        if (!sourceRoot)
+            return;
+        sourceRoot.updateWorldMatrix(true, false);
+        master.updateWorldMatrix(true, false);
+        _rootInv.copy(sourceRoot.matrixWorld).invert();
+        _masterInRoot.multiplyMatrices(_rootInv, master.matrixWorld);
+        // one slot per member, at its own CreatedObject's place (the master's frame inside it)
+        let dirty = slots.current.length !== ids.length;
+        slots.current.length = ids.length;
+        shown.current.length = ids.length;
+        for (let k = 0; k < ids.length; k++) {
+            const root = k === 0 ? sourceRoot : rootOf(ids[k]);
+            const vis = !!root && shownInScene(root);
+            if (root)
+                root.updateWorldMatrix(true, false);
+            const m = slots.current[k] ?? (slots.current[k] = new Matrix4());
+            if (root) {
+                _next.multiplyMatrices(root.matrixWorld, _masterInRoot);
+                if (!sameMatrix(_next, m)) {
+                    m.copy(_next);
+                    dirty = true;
+                }
+            }
+            if (shown.current[k] !== vis) {
+                shown.current[k] = vis;
+                dirty = true;
+            }
+        }
+        const reason = shared.sync(master, {
+            count: ids.length,
+            slot: (k) => (shown.current[k] ? slots.current[k] : null),
+            slotsDirty: dirty,
+            checkParts: !(frame.current++ % PART_CHECK_EVERY),
+        });
+        if (reason) {
+            fellBack.current = true;
+            publishLink(sourceId, 'fallback', []);
+            onFallback(reason);
+            return;
+        }
+        // tell the members (their pick proxies) which parts there are and where
+        const pub = published.current;
+        if (pub.version !== shared.version || !sameMatrix(pub.masterInRoot, _masterInRoot)) {
+            pub.version = shared.version;
+            pub.masterInRoot.copy(_masterInRoot);
+            publishLink(sourceId, 'shared', shared.parts.map(p => ({ geometry: p.source.geometry, rel: new Matrix4().multiplyMatrices(_masterInRoot, p.rel) })));
+        }
+    });
+    return (_jsxs(_Fragment, { children: [_jsx("group", { ref: masterRef, name: "link-master", children: children }), _jsx(LinkProxies, { sourceId: sourceId })] }));
+};
+export default LinkedSource;

package/dist/components/projector/Projector.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { AnimationOptions, CreatedObjectSettings, MouseMoveDomain } from '@3driseai/3drise-core';
+import type { ObjectReadyProps } from '../../types/objectReady';
+export type ProjectorProps = ObjectReadyProps & {
+    /** Scene object id: the light controller finds the live-edit handle by it. */
+    id?: string;
+    config: Record<string, any>;
+    animations?: AnimationOptions[];
+    mouseMove?: MouseMoveDomain;
+    settings: CreatedObjectSettings | Record<string, any>;
+};
+declare const Projector: React.FC<ProjectorProps>;
+export default Projector;
+//# sourceMappingURL=Projector.d.ts.map

package/dist/components/projector/Projector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Projector.d.ts","sourceRoot":"","sources":["../../../src/components/projector/Projector.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAqC,MAAM,OAAO,CAAC;AAI1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAItG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG;IAC5C,8EAA8E;IAC9E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACzD,CAAC;AAEF,QAAA,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CA4BvC,CAAC;AACF,eAAe,SAAS,CAAC"}

package/dist/components/projector/Projector.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// =============================================================================
+// Projector — a stadium floodlight bank (light family)
+// =============================================================================
+//
+// Rendered by LightObject for `config.type === 'projector'`. The construction is
+// projectorCore.ts (generated from the approved lab module); this file is the light
+// contract around it: useLightConfig merges committed config + live drags +
+// keyframes + pointer bindings into `merged`, which the core reads every frame.
+//
+// Generated by Claude outputs/lights-lab/emit_object.mjs — edit the lab and regenerate.
+//
+import { useEffect, useMemo, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { DEFAULT_LIGHTS, SELF_OWNED_MATERIAL_KEY } from '@3driseai/3drise-core';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useLightShadow } from '../../hooks/useLightShadow.js';
+import { useLightConfig } from '../../hooks/useLightConfig.js';
+import { createProjector } from './projectorCore.js';
+const Projector = ({ id, config, animations, mouseMove, settings, onObjectReady, onObjectDispose }) => {
+    const groupRef = useRef(null);
+    // One instance for the object's life: structural knobs (lamp, columns, rows,
+    // aspect, edge softness) rebuild the fixture inside the core, keyed on the
+    // merged config, so the light, its shadow map and its target stay put.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const instance = useMemo(() => createProjector({ ...DEFAULT_LIGHTS.projector, ...config }), []);
+    const lightRef = useRef(instance.light);
+    useObjectReady(groupRef, settings, onObjectReady, onObjectDispose);
+    useLightShadow(lightRef, config.shadow, config.type);
+    // Before the frame callback below: R3F runs them in subscription order.
+    const { merged } = useLightConfig(groupRef, lightRef, id, config, animations, mouseMove);
+    // The light owns its materials and its shadow flags.
+    useEffect(() => {
+        const group = groupRef.current;
+        if (!group)
+            return;
+        group.userData[SELF_OWNED_MATERIAL_KEY] = true;
+        return () => { delete group.userData[SELF_OWNED_MATERIAL_KEY]; };
+    }, []);
+    useEffect(() => () => instance.dispose(), [instance]);
+    useFrame(({ camera }, delta) => instance.update(delta, camera, merged.current));
+    return (_jsx("group", { ref: groupRef, children: _jsx("primitive", { object: instance.root }) }));
+};
+export default Projector;

package/dist/components/projector/index.d.ts

@@ -0,0 +1,4 @@
+export { default as Projector } from './Projector';
+export type { ProjectorProps } from './Projector';
+export { createProjector } from './projectorCore';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/projector/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/projector/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/components/projector/index.js

@@ -0,0 +1,2 @@
+export { default as Projector } from './Projector.js';
+export { createProjector } from './projectorCore.js';

package/dist/components/projector/projectorCore.d.ts

@@ -0,0 +1,19 @@
+import * as THREE from 'three';
+/** The defaults live in core (DEFAULT_LIGHTS.projector); this is that table. */
+export declare const DEFAULTS: Record<string, any>;
+export declare const STRUCTURAL: string[];
+/**
+ * The spot's projection square spans ±tan(angle); the optic's rectangle spans
+ * ±tx, ±ty inside it. angle is set from the rectangle's corner (×1.04), so the
+ * rectangle's share of the square depends only on aspect — `spread` can then be
+ * animated without redrawing the mask.
+ */
+export declare const CORNER = 1.04;
+export declare function createProjector(cfg0: any): {
+    root: THREE.Group<THREE.Object3DEventMap>;
+    light: THREE.SpotLight;
+    update: (dt: any, camera: any, cfg: any) => void;
+    dispose: () => void;
+    heads: any[];
+};
+//# sourceMappingURL=projectorCore.d.ts.map

package/dist/components/projector/projectorCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectorCore.d.ts","sourceRoot":"","sources":["../../../src/components/projector/projectorCore.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,gFAAgF;AAChF,eAAO,MAAM,QAAQ,EAA+B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAExE,eAAO,MAAM,UAAU,UAAwD,CAAC;AAyEhF;;;;;GAKG;AACH,eAAO,MAAM,MAAM,OAAO,CAAC;AAuI3B,wBAAgB,eAAe,CAAC,IAAI,KAAA;;;;;;EA8QnC"}