@volter/editor-threejs 0.5.66 → 0.5.68

package/src/kit/camera-authoring.ts

@@ -0,0 +1,175 @@
+import type * as THREE from 'three';
+
+/**
+ * Transient camera-authoring presentation for the Scene viewport.
+ *
+ * Cameras remain ordinary native Three.js objects owned by the active
+ * AuthoringAdapter. This module carries only viewport presentation (pin,
+ * view-through, pilot) and delegates every authored mutation to the host's
+ * canonical transform gesture path. There is no camera document or sidecar.
+ */
+
+export type CameraViewMode = 'view' | 'pilot';
+
+export interface CameraAuthoringSubject {
+  readonly id: string;
+  readonly name: string;
+  readonly camera: THREE.Camera;
+  readonly lens: string;
+  /** Position and rotation can both enter the adapter's normal edit gesture. */
+  readonly canAuthorPose: boolean;
+  readonly poseRefusal?: string;
+}
+
+export interface CameraAuthoringPresentation {
+  readonly preview: CameraAuthoringSubject | null;
+  readonly previewPinned: boolean;
+  readonly view: {
+    readonly mode: CameraViewMode;
+    readonly subject: CameraAuthoringSubject;
+  } | null;
+  readonly guidesVisible: boolean;
+}
+
+export interface CameraAuthoringHost {
+  /** Camera authoring is an Edit/Scene affordance, never a Play overlay. */
+  readonly active: () => boolean;
+  readonly selected: () => CameraAuthoringSubject | null;
+  readonly resolve: (id: string) => CameraAuthoringSubject | null;
+  readonly showView: (subject: CameraAuthoringSubject, mode: CameraViewMode) => void;
+  readonly leaveView: () => void;
+  readonly alignToViewport: (subject: CameraAuthoringSubject) => void;
+  readonly subscribe: (listener: () => void) => () => void;
+}
+
+let host: CameraAuthoringHost | null = null;
+let disposeHostSubscription: (() => void) | null = null;
+let pinnedId: string | null = null;
+let viewState: { id: string; mode: CameraViewMode; camera: THREE.Camera } | null = null;
+let guidesVisible = true;
+let version = 0;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+function syncHostState(): void {
+  if (!host) return;
+  if (!host.active()) {
+    if (viewState) host.leaveView();
+    viewState = null;
+    notify();
+    return;
+  }
+  if (pinnedId && !host.resolve(pinnedId)) pinnedId = null;
+  if (viewState) {
+    const subject = host.resolve(viewState.id);
+    if (!subject) {
+      viewState = null;
+      host.leaveView();
+    } else if (subject.camera !== viewState.camera) {
+      // HMR may replace the native camera while preserving its semantic id.
+      // Rebind the transient view to the fresh object rather than retaining a
+      // dead Three.js reference.
+      viewState = { ...viewState, camera: subject.camera };
+      host.showView(subject, viewState.mode);
+    }
+  }
+  notify();
+}
+
+/** Install the one live Scene viewport host. The returned disposer is
+ * identity-guarded so a stale unmount cannot clear a newer viewport. */
+export function installCameraAuthoringHost(next: CameraAuthoringHost): () => void {
+  disposeHostSubscription?.();
+  host?.leaveView();
+  host = next;
+  pinnedId = null;
+  viewState = null;
+  guidesVisible = true;
+  disposeHostSubscription = next.subscribe(syncHostState);
+  notify();
+  return () => {
+    if (host !== next) return;
+    disposeHostSubscription?.();
+    disposeHostSubscription = null;
+    next.leaveView();
+    host = null;
+    pinnedId = null;
+    viewState = null;
+    guidesVisible = true;
+    notify();
+  };
+}
+
+export function subscribeCameraAuthoring(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function cameraAuthoringVersion(): number {
+  return version;
+}
+
+export function cameraAuthoringPresentation(): CameraAuthoringPresentation {
+  if (!host?.active()) {
+    return { preview: null, previewPinned: false, view: null, guidesVisible };
+  }
+  const selected = host?.selected() ?? null;
+  const pinned = pinnedId ? (host?.resolve(pinnedId) ?? null) : null;
+  const viewSubject = viewState ? (host?.resolve(viewState.id) ?? null) : null;
+  return {
+    preview: viewSubject ? null : (pinned ?? selected),
+    previewPinned: Boolean(pinned),
+    view: viewState && viewSubject ? { mode: viewState.mode, subject: viewSubject } : null,
+    guidesVisible,
+  };
+}
+
+export function currentCameraAuthoringSubject(): CameraAuthoringSubject | null {
+  const presentation = cameraAuthoringPresentation();
+  return presentation.view?.subject ?? presentation.preview;
+}
+
+export function toggleCameraPreviewPin(): void {
+  const presentation = cameraAuthoringPresentation();
+  const subject = presentation.preview;
+  if (!subject) return;
+  pinnedId = presentation.previewPinned ? null : subject.id;
+  notify();
+}
+
+export function viewThroughCamera(subject = currentCameraAuthoringSubject()): void {
+  if (!host || !subject) return;
+  if (viewState) host.leaveView();
+  viewState = { id: subject.id, mode: 'view', camera: subject.camera };
+  host.showView(subject, 'view');
+  notify();
+}
+
+export function pilotCamera(subject = currentCameraAuthoringSubject()): void {
+  if (!host || !subject || !subject.canAuthorPose) return;
+  if (viewState) host.leaveView();
+  viewState = { id: subject.id, mode: 'pilot', camera: subject.camera };
+  host.showView(subject, 'pilot');
+  notify();
+}
+
+export function alignCameraToViewport(subject = currentCameraAuthoringSubject()): void {
+  if (!host || !subject || !subject.canAuthorPose) return;
+  host.alignToViewport(subject);
+}
+
+export function leaveCameraView(): void {
+  if (!host || !viewState) return;
+  viewState = null;
+  host.leaveView();
+  notify();
+}
+
+export function toggleCameraCompositionGuides(): void {
+  guidesVisible = !guidesVisible;
+  notify();
+}

package/src/kit/components/CameraInfo.tsx

@@ -0,0 +1,56 @@
+import { EditorSurface, Inline, Text } from '@volter/editor-sdk/widgets';
+import { useEffect, useRef, useState } from 'react';
+import { useEditorStats } from '@volter/editor-sdk/kit/editor-runtime';
+
+function fmt(n: number): string {
+  return n.toFixed(2);
+}
+
+export function CameraInfo() {
+  const stats = useEditorStats();
+  const [pos, setPos] = useState({ x: 0, y: 0, z: 0 });
+  const [target, setTarget] = useState({ x: 0, y: 0, z: 0 });
+  const rafRef = useRef(0);
+
+  useEffect(() => {
+    function tick() {
+      const cam = stats.cameraPosition;
+      const tgt = stats.cameraTarget;
+      setPos((prev) =>
+        prev.x !== cam.x || prev.y !== cam.y || prev.z !== cam.z
+          ? { x: cam.x, y: cam.y, z: cam.z }
+          : prev,
+      );
+      setTarget((prev) =>
+        prev.x !== tgt.x || prev.y !== tgt.y || prev.z !== tgt.z
+          ? { x: tgt.x, y: tgt.y, z: tgt.z }
+          : prev,
+      );
+      rafRef.current = requestAnimationFrame(tick);
+    }
+    rafRef.current = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(rafRef.current);
+  }, [stats]);
+
+  return (
+    // P6-U6 (owner taste decision 3: HUD overlays → real islands): under
+    // islands chrome the pill wears the shared glass-island material
+    // (compact tier; pointer-events stays none — it is a readout, not a
+    // control). Bars chrome keeps the pre-U6 overlay surface + blur.
+    <EditorSurface
+      variant="overlay"
+      border
+      className="vgai-camera-info vgai-chrome-island vgai-glass-island"
+      data-island-scale="compact"
+    >
+      <Inline gap={8} align="center" style={{ whiteSpace: 'nowrap' }}>
+        <Text variant="code">
+          Pos {fmt(pos.x)} {fmt(pos.y)} {fmt(pos.z)}
+        </Text>
+        <Text variant="code">
+          Target {fmt(target.x)} {fmt(target.y)} {fmt(target.z)}
+        </Text>
+      </Inline>
+    </EditorSurface>
+  );
+}

package/src/kit/components/InspectorObjectPreview.tsx

@@ -0,0 +1,57 @@
+import type * as THREE from 'three';
+import { Object3DSnapshotDocument } from './asset-viewers/EntityModelDocument';
+
+/**
+ * Inspector-sized projection of the canonical Asset Lab viewport, over a live
+ * `Object3D` the caller already has in hand.
+ *
+ * It takes the OBJECT, not an id to look one up by: a subject's preview is
+ * composed only when the thing is genuinely previewable
+ * (`inspection/compose.ts`), and the object the composer proved exists is the
+ * one rendered here. A scene node and a part inside an asset document are
+ * therefore the same case — the part is not in the shell's object map, and
+ * with an id this component could only have shown a "no longer available"
+ * alert for a thing that is right there on screen.
+ *
+ * Every host passes `fill`: the section body's square box, the compact card's
+ * round disc, and the minimized card's round thumb all own their own geometry
+ * and this component just fills it.
+ */
+export function InspectorObjectPreview({
+  previewKey,
+  object,
+  displayName,
+  fill = false,
+}: {
+  /** Stable identity for the isolated preview document. */
+  previewKey: string;
+  object: THREE.Object3D;
+  displayName: string;
+  fill?: boolean;
+}) {
+  return (
+    <div
+      data-testid="inspector-object-preview"
+      style={
+        fill
+          ? { position: 'absolute', inset: 0, overflow: 'hidden' }
+          : {
+              width: '100%',
+              height: 220,
+              minHeight: 220,
+              borderBottom: '1px solid var(--vgai-structural-divider)',
+              overflow: 'hidden',
+              position: 'relative',
+            }
+      }
+    >
+      <Object3DSnapshotDocument
+        documentId={`inspector-preview:${previewKey}`}
+        source={object}
+        displayName={displayName}
+        active
+        chromeless
+      />
+    </div>
+  );
+}