@volter/editor-threejs 0.5.65 → 0.5.67

package/src/kit/components/asset-viewers/three-asset-viewers.tsx

@@ -0,0 +1,132 @@
+/**
+ * THE THREE.JS ASSET LAB VIEWERS, registered by route
+ * (`@volter/editor-sdk/kit/asset-viewers`): a glTF model, an environment map, a
+ * LUT, a shader, a live modeling module and a live entity's model. Each loads on
+ * first use, so a document that never opens one never pays for three.js.
+ */
+import {
+  type AssetViewerProps,
+  type AssetViewerRoute,
+  type JsonContentViewer,
+  registerAssetViewer,
+  registerJsonContentViewer,
+} from '@volter/editor-sdk/kit/asset-viewers';
+import { type ComponentType, lazy } from 'react';
+
+const viewers: Readonly<Record<AssetViewerRoute, ComponentType<AssetViewerProps>>> = {
+  model: lazy(async () => {
+    const { ModelAssetDocument } = await import('./ModelAssetDocument');
+    return {
+      default: (props: AssetViewerProps) => (
+        <ModelAssetDocument
+          documentId={props.documentId}
+          assetPath={props.assetPath}
+          displayName={props.displayName}
+          active={props.active}
+        />
+      ),
+    };
+  }),
+  'entity-model': lazy(async () => {
+    const { EntityModelDocument } = await import('./EntityModelDocument');
+    return {
+      default: (props: AssetViewerProps) => (
+        <EntityModelDocument
+          documentId={props.documentId}
+          entityId={props.entityId ?? ''}
+          displayName={props.displayName}
+          active={props.active}
+        />
+      ),
+    };
+  }),
+  environment: lazy(async () => {
+    const { EnvironmentAssetDocument } = await import('./EnvironmentAssetDocument');
+    return {
+      default: (props: AssetViewerProps) => (
+        <EnvironmentAssetDocument documentId={props.documentId} assetPath={props.assetPath} active={props.active} />
+      ),
+    };
+  }),
+  lut: lazy(async () => {
+    const { LutAssetDocument } = await import('./LutAssetDocument');
+    return {
+      default: (props: AssetViewerProps) => (
+        <LutAssetDocument documentId={props.documentId} assetPath={props.assetPath} active={props.active} />
+      ),
+    };
+  }),
+  shader: lazy(async () => {
+    const { ShaderAssetDocument } = await import('./ShaderAssetDocument');
+    return {
+      default: (props: AssetViewerProps) => (
+        <ShaderAssetDocument documentId={props.documentId} assetPath={props.assetPath} active={props.active} />
+      ),
+    };
+  }),
+  'model-preview': lazy(async () => {
+    const { Object3DPreview } = await import('./Object3DPreview');
+    return {
+      default: (props: AssetViewerProps) => (
+        <Object3DPreview
+          assetPath={props.assetPath}
+          {...(props.materialPath ? { materialPath: props.materialPath } : {})}
+          displayName={props.displayName}
+        />
+      ),
+    };
+  }),
+  // A project script that BUILDS an Object3D opens as the live modeling
+  // document; anything else keeps the text preview it is handed as `fallback`.
+  module: lazy(async () => {
+    const { LiveModuleDocument } = await import('./LiveModuleDocument');
+    return {
+      default: (props: AssetViewerProps) =>
+        props.projectRoot ? (
+          <LiveModuleDocument
+            documentId={props.documentId}
+            projectRoot={props.projectRoot}
+            modulePath={(props.assetPath.split(/[?#]/, 1)[0] ?? props.assetPath).replace(/^\//, '')}
+            displayName={props.displayName}
+            active={props.active}
+            fallback={props.fallback}
+          />
+        ) : (
+          props.fallback
+        ),
+    };
+  }),
+};
+
+// A three.quarks particle system is plain Object3D JSON: recognized by its
+// structure, shown as the particle editor.
+const quarksJson: JsonContentViewer = {
+  recognize: async (assetPath, signal) =>
+    (await import('./QuarksAssetDocument')).loadNativeQuarksJsonSource(assetPath, signal),
+  Viewer: lazy(async () => {
+    const { QuarksAssetDocument } = await import('./QuarksAssetDocument');
+    return {
+      default: (props: AssetViewerProps & { readonly content: unknown }) => (
+        <QuarksAssetDocument
+          documentId={props.documentId}
+          assetPath={props.assetPath}
+          displayName={props.displayName}
+          active={props.active}
+          source={props.content as Parameters<typeof QuarksAssetDocument>[0]['source']}
+        />
+      ),
+    };
+  }),
+};
+
+export function registerThreeAssetViewers(): () => void {
+  const removals = [
+    ...(Object.keys(viewers) as AssetViewerRoute[]).map((route) =>
+      registerAssetViewer(route, viewers[route]),
+    ),
+    registerJsonContentViewer(quarksJson),
+  ];
+  return () => {
+    for (const remove of removals) remove();
+  };
+}

package/src/kit/components/object3d-contribution-surfaces.tsx

@@ -0,0 +1,33 @@
+import { announceDocumentStage } from '@volter/editor-sdk/kit/document-viewports';
+import { lazy, Suspense, useEffect } from 'react';
+import type { ToolObject3DAuthoringProps, ToolObject3DPreviewProps } from '../../object3d-contributions';
+
+/**
+ * The Object3D surfaces a contribution mounts from its `surfaces` prop, as the Three integration
+ * registers them. Each loads its viewport on first use, so installing the integration pulls no
+ * WebGL modules until a document asks for one.
+ */
+const Preview = lazy(async () => ({ default: (await import('./ToolObject3DPreview')).ToolObject3DPreview }));
+const Authoring = lazy(async () => ({ default: (await import('./StageHost')).ToolObject3DAuthoring }));
+
+export function Object3DPreviewSurface(props: ToolObject3DPreviewProps) {
+  return (
+    <Suspense fallback={<div style={{ minHeight: 240 }}>Loading 3D preview…</div>}>
+      <Preview {...props} />
+    </Suspense>
+  );
+}
+
+export function Object3DAuthoringSurface(props: ToolObject3DAuthoringProps) {
+  // A CONTRIBUTED DOCUMENT'S STAGE ANNOUNCES ITSELF HERE, the moment the contribution renders it —
+  // long before the lazy implementation resolves and registers a session. This is what lets the
+  // `tool` and `document` addresses declare a readiness without the host knowing which
+  // contributions mount a stage: the capability catalog's Builder documents do and other
+  // `workspace.document` contributions do not, and which is which belongs to the PROJECT.
+  useEffect(() => announceDocumentStage(props.documentId), [props.documentId]);
+  return (
+    <Suspense fallback={<div style={{ minHeight: 240 }}>Loading 3D authoring surface…</div>}>
+      <Authoring {...props} />
+    </Suspense>
+  );
+}

package/src/kit/components/stage-keyboard.tsx

@@ -0,0 +1,40 @@
+/**
+ * A STAGE'S OWN KEYBOARD ACTIONS — the transform modes, the view presets,
+ * Frame, pivot, snap and the vertex-snap hold, bound for the stage whose
+ * document is ACTIVE.
+ *
+ * They belong to the STAGE, and until 2026-09-19 they were mounted from
+ * `stage-overlay-set.tsx`, which a stage only reaches when it has the shell
+ * above it (`StageHost.tsx`'s `shellStore && !chromeless`). A document
+ * contributed by a PACKAGE mounts outside `EditorProvider`, so the Model
+ * document reached NONE of them: measured live in the Code-OSS frame on a
+ * models project, the editor's action table held 29 entries — the shell set
+ * alone — and the stage's nine (`transform.combined/translate/rotate/scale`,
+ * `viewport.toggleSnap/frameSelection/cyclePivot/snapToFloor`, the four view
+ * presets) were absent, so G/R/S on the Model stage answered nothing at all.
+ * The overlay set is an OVERLAY condition (a bounded host must not pay for
+ * the collaboration client it reaches); which keys a stage answers is not,
+ * and the two were one line by accident.
+ *
+ * The ONE registry still means ONE holder (`hotkeys.ts`'s scope table, and
+ * `key-actions.ts`'s action table under the frame): the active
+ * document's stage, which is exactly the condition below.
+ *
+ * Lazily imported by `StageHost.tsx` so a bounded host neither loads nor pays
+ * for `editor-hotkeys.ts`'s closure — the same boundary, and the same reason,
+ * as `StageOverlays.tsx`.
+ */
+import { useEffect } from 'react';
+import { registerViewportActions } from '../viewport-actions';
+import { registerViewportHotkeys } from '../viewport-hotkeys';
+import type { StageHandle } from './stage-overlay-set';
+
+export function StageKeyboardBinding({ stage }: { readonly stage: StageHandle }): null {
+  useEffect(
+    () => registerViewportHotkeys(stage.store, stage.viewport, stage.canvas),
+    [stage.store, stage.viewport, stage.canvas],
+  );
+  // The same stage's palette entries (`viewport-actions.ts`).
+  useEffect(() => registerViewportActions(stage.store), [stage.store]);
+  return null;
+}

package/src/kit/components/stage-overlay-set.tsx

@@ -0,0 +1,105 @@
+/** Shell overlays for document stages: selection controls, camera readout,
+ * hints and statistics. Package documents supply their own chrome. */
+
+import { useSyncExternalStore } from 'react';
+import { activeAuthoringVersion, subscribeActiveAuthoring } from '@volter/editor-sdk/kit/authoring/active-adapter';
+import {
+  object3DDocumentSessionsVersion,
+  subscribeObject3DDocumentSessions,
+} from '../authoring/object3d-document-session-registry';
+import type { EditorShellStore } from '../editor-shell-store';
+import type { EditorViewport } from '../editor-viewport';
+import { documentStageContext, type StageChrome, threeSelectionToolsApply } from '@volter/editor-sdk/kit/stage-context';
+import {
+  subscribeWorkspaceDocuments,
+  workspaceDocumentRegistryVersion,
+} from '@volter/editor-sdk/kit/workspace-document-registry';
+import {
+  subscribeViewportPresentation,
+  viewPresentation,
+  viewportPresentationVersion,
+} from '@volter/editor-sdk/kit/viewport-presentation';
+import { CameraInfo } from './CameraInfo';
+import { StatsOverlay } from './StatsOverlay';
+import { TransientHintOverlay } from '@volter/editor-sdk/kit/components/TransientHint';
+import { ViewportOverlay } from './ViewportOverlay';
+
+/** What the HOST hands over about the stage itself — its own store, the
+ *  viewport the hotkeys drive and the canvas that claims their scope. Null
+ *  until the stage has finished building. */
+export interface StageHandle {
+  readonly store: EditorShellStore;
+  readonly viewport: EditorViewport;
+  readonly canvas: HTMLCanvasElement;
+}
+
+export interface StageOverlaySetProps {
+  readonly store: EditorShellStore;
+  readonly documentId: string;
+  /** This stage's own handle; `null` while it is still building. */
+  readonly stage: StageHandle | null;
+  /** Whether this stage's document is the ACTIVE centre tab. */
+  readonly active: boolean;
+  /** The host's own answer to `StageContext.chrome`. */
+  readonly chrome: StageChrome;
+
+}
+
+export function StageOverlaySet({
+  store,
+  documentId,
+  stage,
+  active,
+  chrome,
+}: StageOverlaySetProps) {
+  /** THIS stage's own store — the shell's until the stage has finished
+   *  building, which is the same store every overlay read before unit 4. */
+  const stageStore = stage?.store ?? store;
+  useSyncExternalStore(store.shell.subscribe, store.shell.getShellSnapshot ?? store.shell.getSnapshot);
+  // The stage's own state (its grid, helpers, stats, tool mode) lives on ITS
+  // store, so the overlays that read it subscribe there too.
+  useSyncExternalStore(stageStore.shell.subscribe, stageStore.shell.getShellSnapshot ?? stageStore.shell.getSnapshot);
+  useSyncExternalStore(subscribeActiveAuthoring, activeAuthoringVersion);
+  useSyncExternalStore(subscribeObject3DDocumentSessions, object3DDocumentSessionsVersion);
+  useSyncExternalStore(subscribeWorkspaceDocuments, workspaceDocumentRegistryVersion);
+  // THIS stage's context — not the focused one. A capability is present where
+  // its condition holds, and the condition is asked of the stage that would
+  // draw it (ARCHITECTURE-CORE §One stage).
+  const ctx = documentStageContext(store.shell, documentId, chrome);
+  /** Whether the selection tools draw here — and that is the WHOLE condition:
+   *  they read THIS stage's own store (`stage.store`, the one the shared
+   *  panels reach through `focusedStageStore()`), so a prefab's grid button
+   *  toggles the prefab's grid and its readout reports the camera its reader
+   *  is looking through. */
+  const showsSelectionTools = threeSelectionToolsApply(ctx);
+  // The camera readout is the editor's own; a view whose target draws none leaves it off
+  // (`overlays.cameraReadout`).
+  useSyncExternalStore(subscribeViewportPresentation, viewportPresentationVersion, viewportPresentationVersion);
+  const cameraReadout = viewPresentation(documentId).overlays.cameraReadout;
+  return (
+    <>
+      {/* THE STAGE'S OWN KEYBOARD is no longer mounted here: this module is
+          reached only by a stage that has the shell above it, and a
+          package-contributed document (the Model document) has none — so it
+          answered no stage key at all. It is `StageHost.tsx`'s now, beside
+          the stage handle, under the same activation condition
+          (`stage-keyboard.tsx` carries the measurement). */}
+      {showsSelectionTools ? (
+        <>
+          <ViewportOverlay store={stageStore} documentId={documentId} />
+          {cameraReadout ? <CameraInfo /> : null}
+        </>
+      ) : null}
+      {ctx.surface === 'three' && stageStore.showStats && <StatsOverlay />}
+      {/* H2 — the ONE transient hint channel. Lives here because a refused
+          transform is a viewport gesture; the overlay is absent from the DOM
+          entirely until something has a reason to say. ONE channel means one
+          mount — the ACTIVE stage's — so a hint never draws twice. */}
+      {active ? <TransientHintOverlay /> : null}
+      {/* W4 (inventory row V9): the scene document mounts NO network overlay.
+          Compact connection state lives in the status bar
+          (`status-contributions.tsx`); the detailed surface is the `network`
+          workspace utility (`NetworkInspectorPanel`), revealed from there. */}
+    </>
+  );
+}