cozyclay 2.1.0 → 3.0.0

package/src/domains/scenes.js

@@ -44,8 +44,7 @@ import {
 import { playgroundSceneUrl, fetchSceneProject } from "../playground.js";
 import { openAssetDb, referencedAssetIds, getAsset, putAsset } from "../scene-assets.js";
 import { internWorkflowOutputs, workflowOutputRefs, resolveWorkflowOutputs } from "../workflow/workflow-resources.js";
-import { encodeMotionResource } from "../motion-resources.js";
-import { openMotionDb, putMotion, sweepMotions } from "../motion-store.js";
+
 import { resourceManifest } from "../project-resources.js";
 import { isKo, ko } from "../locale.js";
 import { track, bucketCount, bucketProjectAge, startExportAttempt } from "../analytics.js";
@@ -54,7 +53,7 @@ import { DEFAULT_WORKSPACE_LAYOUT, DEFAULT_DURATION_S, TIMELINE_FPS } from "../a
 import { saveCustomPoses } from "../poses.js";
 import { readShotAuthoringDocument } from "../shot-authoring.js";
 import { initialShots } from "../cuts.js";
-import { createIkState } from "../ardy/ik.js";
+import { createIkState } from "../motion/ik.js";
 
 // The scene list and project identity share one history. Dirty is derived from
 // the saved checkpoint, not an authored edit, and has its own non-history slice.
@@ -238,56 +237,17 @@ export function useScenes(appContext) {
 		return JSON.stringify(createProjectDocument(projectDocumentInput(name)));
 	}
 
-	async function collectProjectSerialized(name) {
+		async function collectProjectSerialized(name) {
 		const input = projectDocumentInput(name);
-		const scenesDocument = {
-			...input.scenesDocument,
-			scenes: input.scenesDocument.scenes.map((scene) => ({
-				...scene,
-				stage: scene.stage
-					? {
-						...scene.stage,
-						characters: (scene.stage.characters ?? []).map((character) => ({
-							...character,
-							motionRef: character.motionRef ? { ...character.motionRef } : character.motionRef,
-						})),
-					}
-					: scene.stage,
-			})),
-		};
+		const scenesDocument = input.scenesDocument;
 		const db = await openAssetDb();
 		try {
 			const ids = [...referencedAssetIds(scenesDocument.scenes)];
 			const assets = await Promise.all(ids.map((id) => getAsset(db, id)));
 			const workflowResult = await internWorkflowOutputs(input.workflow);
-			const referencedMotionIds = new Set(
-				scenesDocument.scenes.flatMap((scene) => (scene.stage?.characters ?? [])
-					.map((character) => character.motionRef?.motionId?.toLowerCase())
-					.filter(Boolean)),
-			);
-			const motions = [...appContext.shared.projectMotionsRef.current.entries()]
-				.filter(([id]) => referencedMotionIds.has(id))
-				.map(([, record]) => record);
-			const motionCache = new Map();
-			for (const record of motions) motionCache.set(record.motionId.toLowerCase(), record);
-			for (const scene of scenesDocument.scenes) for (const character of scene.stage?.characters ?? []) {
-				const clip = appContext.shared.motionFullRef.current.get(character.id);
-				if (!clip?.sourceBytes) continue;
-				let record = appContext.shared.motionEncodingCacheRef.current.get(clip.sourceBytes);
-				if (!record) {
-					record = await encodeMotionResource(clip.sourceBytes, { prompt: character.motionRef?.prompt, sourceUrl: character.motionRef?.url });
-					appContext.shared.motionEncodingCacheRef.current.set(clip.sourceBytes, record);
-				}
-				const cached = motionCache.get(record.motionId) ?? record;
-				motionCache.set(record.motionId, cached);
-				if (!motions.includes(cached)) motions.push(cached);
-				appContext.shared.projectMotionsRef.current.set(record.motionId.toLowerCase(), cached);
-				character.motionRef = { ...(character.motionRef || {}), motionId: cached.motionId };
-			}
-			try { const motionDb = await openMotionDb(); await Promise.all(motions.map((record) => putMotion(motionDb, record))); motionDb.close(); } catch (error) { console.warn("[cozyclay] could not cache motions", error); }
 			const allAssets = [...assets.filter(Boolean), ...workflowResult.assets];
-			const nextInput = { ...input, scenesDocument, workflow: workflowResult.graph, assets: allAssets, motions };
-			const manifest = resourceManifest({ scenesDocument: nextInput.scenesDocument, workflow: nextInput.workflow, poseLibrary: nextInput.customPoses, assets: allAssets, motions, workflowOutputRefs });
+			const nextInput = { ...input, scenesDocument, workflow: workflowResult.graph, assets: allAssets };
+			const manifest = resourceManifest({ scenesDocument: nextInput.scenesDocument, workflow: nextInput.workflow, poseLibrary: nextInput.customPoses, assets: allAssets, workflowOutputRefs });
 			setProjectManifest(manifest);
 			if (manifest.missing.length) {
 				const error = new Error("Project has missing resources");
@@ -445,10 +405,8 @@ export function useScenes(appContext) {
 		appContext.shared.setTutorialSeedPending(false);
 		appContext.shared.setCameraTutorialHandoff(null);
 		appContext.shared.exportShotIdRef.current = null;
-		appContext.shared.projectMotionsRef.current = new Map((project.motions ?? []).map((record) => [record.motionId?.toLowerCase(), record]).filter(([id]) => id));
 		const source = project.scenesDocument;
-		openMotionDb().then(async (db) => { try { await Promise.all([...appContext.shared.projectMotionsRef.current.values()].map((record) => putMotion(db, record))); const ids = new Set((source?.scenes ?? []).flatMap((scene) => (scene.stage?.characters ?? []).map((character) => character.motionRef?.motionId?.toLowerCase()).filter(Boolean))); await sweepMotions(db, ids); } finally { db.close(); } }).catch(() => {});
-		// A project FILE carries its own scene document and never passes the
+				// A project FILE carries its own scene document and never passes the
 		// storage reader, so the 20 fps → 24 fps clock migration is applied here
 		// too — otherwise an older .cozyclay would open a sixth too fast.
 		const doc = migrateToCurrentScenes(source);
@@ -470,7 +428,7 @@ export function useScenes(appContext) {
 		// Whatever document this is, it is no longer the scene the tutorial opened
 		// for itself; startCameraTutorial re-arms the flag after its own open.
 		appContext.shared.tutorialStarterRef.current = false;
-		setProjectManifest(resourceManifest({ scenesDocument: doc, workflow: resolvedWorkflow, poseLibrary: mergedCustomPoses, assets: project.assets ?? [], motions: appContext.shared.projectMotionsRef.current, workflowOutputRefs }));
+		setProjectManifest(resourceManifest({ scenesDocument: doc, workflow: resolvedWorkflow, poseLibrary: mergedCustomPoses, assets: project.assets ?? [], workflowOutputRefs }));
 		track("project:opened", { age_bucket: bucketProjectAge(Date.now() - (project.savedAt ?? Date.now())) });
 	}
 
@@ -586,7 +544,6 @@ export function useScenes(appContext) {
 		setProjectNameDialog(null);
 		const fresh = createSceneDocument(ko("SCENE 01", "씬 01"));
 		storeWorkflowGraph(createWorkflowGraph());
-		appContext.shared.projectMotionsRef.current = new Map();
 		appContext.shared.motionFullRef.current.clear();
 		domain.replaceDocument(fresh.scenes, fresh.activeSceneId, name, previsMode);
 		persistScenes(fresh.scenes, fresh.activeSceneId);
@@ -660,16 +617,16 @@ export function useScenes(appContext) {
 		// The motion-layer buffer reloads from the scene's first character.
 		const firstLayer = stage.characters[0]?.layer;
 		appContext.shared.setWaypoints(firstLayer?.waypoints ?? shotState.waypoints ?? []);
-		appContext.shared.setPromptClips(firstLayer?.promptClips?.map((clip) => ({ ...clip })) ?? []);
-		// Takes belong to the room being left; restoreMotionRefs re-fetches the
+		
+		// Takes belong to the room being left; the motion layers load the
 		// incoming scene's, and a stale full take must never survive the switch.
 		appContext.shared.motionFullRef.current.clear();
-		appContext.shared.setSelectedPromptId(null);
+		
 		appContext.shared.ikStatesRef.current.clear();
 		appContext.shared.ikStateRef.current = createIkState();
 		appContext.shared.loadedLayerCharRef.current = stage.characters[0]?.id ?? null;
 		appContext.shared.setActiveCharacterId(stage.characters[0]?.id ?? null);
-		appContext.shared.restoreMotionRefs(stage.characters);
+		
 		appContext.shared.setTlFrame(0);
 		appContext.shared.setMovePlaying(false);
 		appContext.shared.manualCameraOverrideRef.current = false;

package/src/domains/shots.js

@@ -381,7 +381,7 @@ export function useShots(appContext) {
   function clampShotRailRanges() {}
   const extentInputs = useRef(null);
   function syncTimelineExtent() {
-    const inputs = [appContext.shared.characters, appContext.shared.activeChar.id, appContext.shared.motion, appContext.shared.promptClips, appContext.shared.multiModelFootage?.frames];
+    const inputs = [appContext.shared.characters, appContext.shared.activeChar.id, appContext.shared.motion];
     // App also re-runs this effect when shot history publishes. Only new
     // content can request a new extent; replaying it after Undo would replace
     // the restored entry and destroy Redo. Shot writes already clamp ranges.
@@ -402,7 +402,7 @@ export function useShots(appContext) {
     const target = shotId ? shots.find(entry => entry.id === shotId) : shots[atPlayhead >= 0 ? atPlayhead : 0] ?? null;
     if (shotId && !target) return null;
     let exportShots = shots;
-    if (target && target.cameraKeys.length === 0 && !shotId && scope !== 'timeline') {
+    if (target && target.cameraKeys.length === 0 && (target.camera?.mode ?? 'keys') === 'keys' && !shotId && scope !== 'timeline') {
       appContext.bus.run('shot.addKey', { shotId: target.id, frame: target.startFrame });
       exportShots = appContext.storeDomain('shot').read();
     }

package/src/domains/stage.js

@@ -2,7 +2,7 @@ import { useContext, useEffect, useRef, useState } from 'react';
 import { AppContext } from '../app-context.js';
 import { createSceneStageStore } from '../store/scene-stage.js';
 import { useDocumentDomain } from '../store/use-document-store.js';
-import { createKeyLight } from '../scenes.js';
+import { createKeyLight } from '../stage-lighting.js';
 import { shotAspectRatio } from '../shot.js';
 import { normalizeStage } from '../commands/stage.js';
 
@@ -70,7 +70,9 @@ export function useStageTransaction() {
 }
 
 export function useStage(appContext) {
-  const [domain] = useState(() => createStageDomain(appContext));
+  // One stage owner: StrictMode runs this initializer twice, and a second domain would leave App
+  // rendering (and mirroring into the saved scene) a stage no command writes.
+  const [domain] = useState(() => appContext.storeDomain('stage') ?? createStageDomain(appContext));
   const stage = useDocumentDomain(domain.documentStore, 'stage');
   const [preset, setPreset] = useState('medium');
   const gesture = useRef(null);

package/src/draft-ghost.js

@@ -0,0 +1,46 @@
+// The agent's latest motion draft as one translucent figure in the working views, so the user sees the motion
+// take shape while the agent works (agent-progress.js publishes every motion.compile, installed or not). This
+// module holds the pure choices: whether the ghost shows, at what opacity and frame (its own loop at the take's
+// rate from the moment the draft arrived, whatever the timeline does), what its label says, and the viewer's
+// on/off setting (transient like the View menu: never saved, never undone). draft-ghost.jsx draws it on
+// GIZMO_LAYER, so captures, contact sheets and exports never see it.
+import { useSyncExternalStore } from "react";
+import { ko } from "./locale.js";
+
+/** Teal: apart from the onion skin's blue (before) and orange (after). */
+export const DRAFT_GHOST_COLOR = "#2fc79a";
+export const DRAFT_GHOST_OPACITY = 0.42;
+/** An installed draft fades out over this long from its arrival: the real take plays now. */
+export const DRAFT_GHOST_FADE_MS = 1200;
+const HIDDEN = Object.freeze({ shown: false, opacity: 0, frame: 0 });
+
+/**
+ * draftGhostState(draft, now) -> { shown, opacity, frame }: a draft whose take is a take v3 shows at
+ * DRAFT_GHOST_OPACITY while it is not installed; an installed one fades out over DRAFT_GHOST_FADE_MS.
+ * frame loops over the take at its fps from draft.at (ms, as now).
+ */
+export function draftGhostState(draft, now) {
+	const take = draft?.take;
+	if (take?.schema !== "cozyclay.take.v3" || !(take.frameCount > 0)) return HIDDEN;
+	const age = Math.max(0, now - (draft.at ?? now)), fps = take.fps > 0 ? take.fps : 24;
+	const opacity = draft.installed ? DRAFT_GHOST_OPACITY * (1 - age / DRAFT_GHOST_FADE_MS) : DRAFT_GHOST_OPACITY;
+	if (!(opacity > 0.01)) return HIDDEN;
+	return { shown: true, opacity: +opacity.toFixed(3), frame: Math.floor((age / 1000) * fps) % take.frameCount };
+}
+
+/** "Draft 3 · QA 31" ("초안 3 · QA 31"). */
+export const draftLabel = draft => `${ko("Draft", "초안")} ${draft?.n ?? 0} · QA ${draft?.qa?.total ?? 0}`;
+
+let shown = true;
+const listeners = new Set();
+/** Whether the viewer wants the draft ghost (default on). */
+export const draftGhostShown = () => shown;
+export function setDraftGhostShown(value) {
+	const next = !!value;
+	if (next === shown) return shown;
+	shown = next;
+	for (const listener of [...listeners]) listener();
+	return shown;
+}
+const subscribe = listener => { listeners.add(listener); return () => listeners.delete(listener); };
+export const useDraftGhostShown = () => useSyncExternalStore(subscribe, draftGhostShown, draftGhostShown);

package/src/draft-ghost.jsx

@@ -0,0 +1,129 @@
+// The agent's latest motion draft in the working views (draft-ghost.js decides what shows): one GhostSet slot
+// of the drafting character's rig, posed from the draft take on its own loop, the records that take moves
+// riding along, and a label over its head ("Draft 3 · QA 31"). Everything sits on GIZMO_LAYER: the shot
+// preview card, PlayView, captures, contact sheets and exports never draw it, and it takes no ray. The canvas
+// may render on demand, so a shown ghost asks for frames at the take's rate.
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import * as THREE from "three";
+import { useFrame, useThree } from "@react-three/fiber";
+import { GIZMO_LAYER } from "./dualview.jsx";
+import { GhostSet, takeTracks } from "./ghost-set.js";
+import { latestDraft, progressVersion, subscribeProgress } from "./agent-progress.js";
+import { DRAFT_GHOST_COLOR, DRAFT_GHOST_OPACITY, draftGhostState, draftLabel, useDraftGhostShown } from "./draft-ghost.js";
+
+// Kit parts can mount a frame after the take changes (view-ghosts.jsx does the same).
+const SOURCE_PASSES = 3;
+// Metres above the head joint; the label's height as a share of the view (sizeAttenuation off).
+const LABEL_LIFT = 0.3, LABEL_VIEW_HEIGHT = 0.042, LABEL_PX = { w: 512, h: 96 };
+const noRay = () => {};
+const headBones = new WeakMap();
+
+/** The ghost rig's head bone, found once per rig. */
+function headOf(rig) {
+	if (!headBones.has(rig)) {
+		let head = null;
+		// "mixamorigHead" or "mixamorig:Head": the first depth-first one is the control bone playback.js poses
+		rig.traverse(node => { if (!head && node.isBone && /Head$/.test(node.name)) head = node; });
+		headBones.set(rig, head);
+	}
+	return headBones.get(rig);
+}
+
+/** A screen-sized label sprite on GIZMO_LAYER, drawn over everything, never picked. */
+function makeLabel() {
+	const canvas = document.createElement("canvas");
+	Object.assign(canvas, { width: LABEL_PX.w, height: LABEL_PX.h });
+	const texture = new THREE.CanvasTexture(canvas);
+	texture.colorSpace = THREE.SRGBColorSpace;
+	const sprite = new THREE.Sprite(new THREE.SpriteMaterial({ map: texture, transparent: true, depthTest: false, depthWrite: false, sizeAttenuation: false, toneMapped: false }));
+	sprite.center.set(0.5, 0);
+	sprite.renderOrder = 1000;
+	sprite.layers.set(GIZMO_LAYER);
+	sprite.raycast = noRay;
+	sprite.userData = { canvas, texture, text: null };
+	return sprite;
+}
+
+/** Paint `text` as a rounded tag (teal edge; green dot once QA is clean) and size the sprite to it. */
+function paintLabel(sprite, text, clean) {
+	const { canvas, texture } = sprite.userData;
+	if (sprite.userData.text === `${text}|${clean}`) return;
+	sprite.userData.text = `${text}|${clean}`;
+	const g = canvas.getContext("2d"), font = "600 44px system-ui, -apple-system, 'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif";
+	g.font = font;
+	const pad = 26, dot = 34, width = Math.min(LABEL_PX.w - 4, Math.ceil(g.measureText(text).width) + pad * 2 + dot);
+	g.clearRect(0, 0, canvas.width, canvas.height);
+	g.fillStyle = "rgba(16, 24, 28, 0.82)";
+	g.strokeStyle = DRAFT_GHOST_COLOR;
+	g.lineWidth = 4;
+	g.beginPath();
+	g.roundRect((LABEL_PX.w - width) / 2, 8, width, LABEL_PX.h - 16, 30);
+	g.fill();
+	g.stroke();
+	g.fillStyle = clean ? "#46d36f" : DRAFT_GHOST_COLOR;
+	g.beginPath();
+	g.arc((LABEL_PX.w - width) / 2 + pad + 8, LABEL_PX.h / 2, 9, 0, Math.PI * 2);
+	g.fill();
+	g.fillStyle = "#eef6f3";
+	g.font = font;
+	g.textBaseline = "middle";
+	g.fillText(text, (LABEL_PX.w - width) / 2 + pad + dot, LABEL_PX.h / 2 + 2);
+	texture.needsUpdate = true;
+	sprite.scale.set(LABEL_VIEW_HEIGHT * (LABEL_PX.w / LABEL_PX.h), LABEL_VIEW_HEIGHT, 1);
+}
+
+/** One viewport frame of the draft ghost: pose the slot at the draft's own clock, tint it, and set the label over its head. */
+function frameDraft({ set, label, draft, rig, scene, objects, propTake }) {
+	const state = draft ? draftGhostState(draft, Date.now()) : null;
+	const on = !!state?.shown && !!rig?.parent;
+	label.visible = on;
+	if (typeof window !== "undefined") window.__cozyclayDraftGhost = { set, label, draft, state, on };
+	if (!set.show(on)) return;
+	set.setRig(rig);
+	set.syncSources(scene, objects, draft.take, SOURCE_PASSES);
+	rig.parent.updateWorldMatrix(true, false);
+	set.update({ entries: [{ f: state.frame, side: "after", rank: 1 }], take: draft.take, placement: rig.parent.matrixWorld, propTake, objects, count: 1 });
+	const slot = set.slots[0];
+	slot.material.color.set(DRAFT_GHOST_COLOR).multiplyScalar(1.15);
+	slot.material.opacity = state.opacity;
+	const head = headOf(slot.rig);
+	if (!head) return;
+	set.object.updateMatrixWorld(true);
+	head.getWorldPosition(label.position);
+	label.position.y += LABEL_LIFT;
+	label.material.opacity = Math.min(1, state.opacity / DRAFT_GHOST_OPACITY);
+}
+
+/** rigs: live rigs by character id; objects: the authored records (carried ones ride along). */
+export function DraftGhost({ rigs, objects }) {
+	const version = useSyncExternalStore(subscribeProgress, progressVersion, progressVersion);
+	const draft = useMemo(() => latestDraft(), [version]); // eslint-disable-line react-hooks/exhaustive-deps
+	const wanted = useDraftGhostShown();
+	const scene = useThree(state => state.scene), invalidate = useThree(state => state.invalidate);
+	const set = useMemo(() => new GhostSet({ layer: GIZMO_LAYER }), []);
+	const label = useMemo(() => makeLabel(), []);
+	const rig = draft ? rigs?.[draft.characterId] ?? null : null;
+	const active = wanted && !!rig && !!draft?.take;
+	const propTake = useMemo(() => (draft?.take ? { frameCount: draft.take.frameCount, fps: draft.take.fps, objectTracks: takeTracks(draft.take) } : null), [draft]);
+	useEffect(() => {
+		if (!active) return undefined;
+		scene.add(set.object);
+		set.object.add(label);
+		return () => { set.object.remove(label); scene.remove(set.object); };
+	}, [active, scene, set, label]);
+	useEffect(() => () => {
+		set.dispose();
+		label.material.dispose();
+		label.userData.texture.dispose();
+	}, [set, label]);
+	useEffect(() => { if (draft) paintLabel(label, draftLabel(draft), draft.qa?.total === 0); }, [draft, label]);
+	// A shown ghost moves on its own clock: ask for frames at the take's rate, and one more once it is gone.
+	useEffect(() => {
+		invalidate();
+		if (!active) return undefined;
+		const timer = setInterval(() => { if (draftGhostState(draft, Date.now()).shown || set.object.visible) invalidate(); }, 1000 / (draft.take.fps || 24));
+		return () => clearInterval(timer);
+	}, [active, draft, set, invalidate]);
+	useFrame(() => frameDraft({ set, label, draft: active ? draft : null, rig, scene, objects, propTake }));
+	return null;
+}

package/src/dualview.jsx

@@ -100,7 +100,7 @@ const EDGE_FRAGMENT = `
 		float depthLine = smoothstep(0.055, 0.16, depthEdge);
 		float normalLine = smoothstep(0.7, 1.7, normalEdge);
 		float edge = max(depthLine * foregroundOwner, normalLine * 0.68);
-		gl_FragColor = vec4(edgeColor, edge * 0.76 * distanceFade);
+		gl_FragColor = vec4(edgeColor, edge * 0.38 * distanceFade);
 	}
 `;
 
@@ -349,10 +349,11 @@ export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCa
 				// grazing angle its depth runs away fast enough that the depth
 				// kernel inked the whole far floor as a dark band under the
 				// horizon. Without it in the prepass, figures still outline
-				// against the cleared depth behind them.
+				// against the cleared depth behind them. A glow halo (beautyOnly)
+				// is light, not a surface: it takes no ink either.
 				const cutouts = [];
 				scene.traverse((node) => {
-					if ((node.userData?.cutoutTexture !== undefined || node.userData?.noInk) && node.visible) {
+					if ((node.userData?.cutoutTexture !== undefined || node.userData?.noInk || node.userData?.beautyOnly) && node.visible) {
 						cutouts.push(node);
 						node.visible = false;
 					}

package/src/effects/EffectsLayer.jsx

@@ -0,0 +1,112 @@
+/**
+ * Effects in the set: the particles and trails of every effect record, plus
+ * the editor-only marker that lets an emitter be picked and moved.
+ *
+ * Particles live in WORLD space under SetProps, not under the emitter's own
+ * group: a puff already in the air keeps drifting when its emitter moves on
+ * or is hidden (an exhale ends, a cigarette goes back in the pocket). They
+ * are placed imperatively from the frame ref, like a prop, and registered in
+ * the props registry, so the recorder's "place every prop now" pass redraws
+ * them for the frame it is about to capture.
+ */
+import { useEffect, useMemo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import * as THREE from "three";
+import { GIZMO_LAYER } from "../dualview.jsx";
+import { createEffectMeshes } from "./effect-meshes.js";
+import { effectSceneOf, publishEffectScene } from "./state.js";
+
+/** The props-registry key the effects pass is filed under (never an object id). */
+const EFFECTS_ENTRY = Symbol("effects");
+const MARKER_COLOR = "#7fd4f0";
+const onGizmoLayer = (node) => {
+	if (node) node.layers.set(GIZMO_LAYER);
+};
+
+/**
+ * An emitter's viewport presence, editor furniture like an Empty's cross:
+ * a small diamond with an arrow up its local +Y (where particles are thrown)
+ * or, for a trail, a bar along local Y as wide as the ribbon. On GIZMO_LAYER,
+ * so no shot, capture or export ever draws it, with an invisible pick volume.
+ */
+export function EffectMarker({ object }) {
+	const trail = object.effect?.preset === "trail";
+	const half = trail ? Math.max(0.05, (object.effect?.width ?? 0.5) / 2) : 0.06;
+	const lines = useMemo(() => {
+		const d = 0.05;
+		const diamond = [[d, 0, 0], [0, d, 0], [0, d, 0], [-d, 0, 0], [-d, 0, 0], [0, -d, 0], [0, -d, 0], [d, 0, 0],
+			[0, 0, d], [0, d, 0], [0, d, 0], [0, 0, -d], [0, 0, -d], [0, -d, 0], [0, -d, 0], [0, 0, d]];
+		const marks = trail
+			? [[0, -half, 0], [0, half, 0], [-0.03, -half, 0], [0.03, -half, 0], [-0.03, half, 0], [0.03, half, 0]]
+			: [[0, d, 0], [0, 0.16, 0], [0, 0.16, 0], [0.025, 0.12, 0], [0, 0.16, 0], [-0.025, 0.12, 0]];
+		const geometry = new THREE.BufferGeometry();
+		geometry.setAttribute("position", new THREE.Float32BufferAttribute([...diamond, ...marks].flat(), 3));
+		return geometry;
+	}, [trail, half]);
+	useEffect(() => () => lines.dispose(), [lines]);
+	return (
+		<group userData={{ effectMarker: true }}>
+			<lineSegments ref={onGizmoLayer} geometry={lines} renderOrder={997} frustumCulled={false}>
+				<lineBasicMaterial color={MARKER_COLOR} depthTest={false} depthWrite={false} transparent opacity={0.95} />
+			</lineSegments>
+			<mesh ref={onGizmoLayer} visible={false} userData={{ emptyPick: true }}>
+				<sphereGeometry args={[0.08, 12, 8]} />
+				<meshBasicMaterial />
+			</mesh>
+		</group>
+	);
+}
+
+/** A record pinned to a bone emits from where the bone is now: its prop is
+ * placed first, then its world matrix read back from the props registry. */
+const liveWorld = (registryRef) => (id, out) => {
+	const entry = registryRef?.current?.get(id);
+	if (!entry) return null;
+	entry.place();
+	return entry.world(out);
+};
+
+/**
+ * Every effect record's particles at the frame in `frameRef`. `objects` are
+ * the AUTHORED records (a take can hide an emitter at the current frame while
+ * its smoke is still in the air); `registryRef` is SetProps' placement
+ * registry, which the recorder's sync pass walks.
+ */
+export function EffectsLayer({ objects, frameRef = null, take = null, registryRef = null, fadeOpacity = null }) {
+	const base = useMemo(() => effectSceneOf(objects), [objects]);
+	const any = base.records.length > 0;
+	const meshes = useMemo(() => (any ? createEffectMeshes() : null), [any]);
+	useEffect(() => () => meshes?.dispose(), [meshes]);
+	const live = useMemo(() => liveWorld(registryRef), [registryRef]);
+	const scene = useMemo(() => ({ ...base, take: take ?? {}, live }), [base, take, live]);
+	const drawnRef = useRef(null);
+	const place = () => {
+		if (!meshes) return;
+		const frame = frameRef?.current ?? 0, opacity = fadeOpacity ?? 1;
+		const key = [frame, scene, opacity];
+		const attached = scene.records.some((record) => record.attach);
+		if (!attached && drawnRef.current?.every((value, i) => value === key[i])) return;
+		drawnRef.current = key;
+		meshes.update(scene, frame, opacity);
+	};
+	useFrame(place);
+	useEffect(() => {
+		publishEffectScene(() => scene);
+		return () => publishEffectScene(null);
+	}, [scene]);
+	// Re-filed every render, so the recorder's pass runs this render's
+	// placement and runs it after every prop (an attached emitter reads one).
+	useEffect(() => {
+		const registry = registryRef?.current;
+		if (!registry || !meshes) return undefined;
+		registry.set(EFFECTS_ENTRY, { place, world: () => null });
+		return () => { registry.delete(EFFECTS_ENTRY); };
+	});
+	if (!meshes) return null;
+	return (
+		<>
+			<primitive object={meshes.particles} />
+			<primitive object={meshes.ribbons} />
+		</>
+	);
+}