@volter/editor-threejs 0.5.210 → 0.5.212

package/NOTICE

@@ -10,5 +10,10 @@ with src/asset-loaders.ts, src/asset-parse-error.ts and src/loader.ts, were
 imported from the Apache-2.0 @volter/threejs-runtime package. They retain that
 license; LICENSE-APACHE contains its text.
 
-Source revisions and original file hashes are recorded in the repository's
-provenance/blender-integration.json and provenance/editor-host.json.
+Original AGPL source revision: cf9cb8e22dd7ae5709ed0dd8a46dd6f16d1e4945.
+The Apache-2.0 runtime modules were transferred at revision 09c2749ce.
+
+Modules moved under src/kit/ from @volter/sdk's src/kit/ because only this package
+imports them (docs/adr/sdk-plugin-api.md, decisions 1 and 4) are Volter AI, Inc.'s
+own work and are AGPL-3.0-only here, as editor source. The @volter/sdk releases
+that carried them remain Apache-2.0.

package/README.md

@@ -1,16 +1,11 @@
-# Three.js editor utilities
+# Cyclotron three.js integration
 
-Shared bounds, layers, clipping, renderer ownership, preview environment and
-detached scene capture used by Volter Editor's modeling integration.
+The assembled three.js viewport, scene presentation, object authoring, animation
+inspection, asset loading and capture used by Cyclotron and its Blender integration.
 
-This package does not yet own the interactive viewport. The current Three-aware
-editor core retains that implementation; full extraction remains deferred.
-No game-runtime, DOM authoring, physics or gameplay packages are dependencies.
+The integration reaches the editor host through `@volter/sdk`. Structural object
+marks and asset utilities keep their own small module boundaries, so a consumer
+can load them independently of the viewport.
 
-Structural object marks retain their existing keys and behavior. Their readers
-are included here because bounds and editor-layer filtering need them; importing
-these small modules must not pull in a gameplay runtime.
-
-Run `npm run typecheck -w @volter/editor-threejs` through the active World.
-See NOTICE for the per-file license distinction. This package remains private
-while the editor migration and complete distribution review are unfinished.
+Run `npm run typecheck -w @volter/editor-threejs` from the repository root.
+See NOTICE for the per-file license distinction.

package/contributions/animation-mixers.service.ts

@@ -1,8 +1,6 @@
 /**
- * The animation stamp's status facet (`@volter/sdk/services`, a `workspace.service`
- * contribution): the editor's `status` command reports the mixers the running world's own code made, with the
- * clips it has played through each and the objects each animates, so "the timeline found
- * nothing" is answerable from the session.
+ * Report live animation mixers, their played clips and animated objects through a workspace service
+ * status facet.
  */
 import { editorHost } from '@volter/sdk/host';
 import { liveMixers } from '../src/animation/live-mixers';

package/contributions/animation-timeline.utility.tsx

@@ -6,12 +6,11 @@
  * its Scene view. While Play drives time the strip goes read-only and says why.
  */
 import { editorHost } from '@volter/sdk/host';
-import { TransportStrip } from '@volter/sdk/kit/transport-strip';
+import { TransportStrip } from '../src/kit/transport-strip';
 import { Text } from '@volter/sdk/widgets';
 import { useCallback, useSyncExternalStore } from 'react';
 
 export const point = 'workspace.utility';
-export const title = 'Animation';
 
 export default function AnimationTimeline() {
   const { documents, transport } = editorHost();

package/contributions/three.page.ts

@@ -0,0 +1,50 @@
+/**
+ * EDITOR-THREEJS'S PAGE HALF (`contributes.volter.page`, `docs/adr/plugin-apis.md`): it installs the
+ * Three integration (`../src/kit/three-integration.ts`) and registers the Three viewport's relay verbs as
+ * the Code-OSS commands `volter.<verb>` its package.json declares, with their budgets
+ * (`../src/kit/viewport-commands.ts`). Its API is the shared viewport for a document that draws its own content in it:
+ * the viewport, each mounted stage (its rig, renderer included, and its frame), a document's display transform, its
+ * framing and its World.
+ *
+ * It activates on its first event: a viewport verb, the Animation panel's first showing, an Asset Lab
+ * route with no viewer (`onAssetViewer:`), or a JSON document opening (`onAssetViewer:json`), whose three.quarks
+ * particle systems its recognizer claims; and before editor-blender, which names it in `extensionDependencies`
+ * because a model document draws through the surfaces and stages this integration installs. A viewport that editor-blender or editor-ui mounts as a library
+ * ensures the integration itself before it mounts, whether or not this page half has activated.
+ */
+import { registerVerbCommands } from '@volter/sdk/commands';
+import type { PluginContext } from '@volter/sdk/plugins';
+import type * as THREE from 'three';
+import { object3DDocumentSession } from '../src/kit/authoring/object3d-document-session-registry';
+import { Object3DDocumentViewport } from '../src/kit/components/Object3DDocumentViewport';
+import { ensureThreeIntegration } from '../src/kit/three-integration';
+import { viewportVerbs } from '../src/kit/viewport-commands';
+import type { DocumentDisplayTransform } from '../src/render/document-display-transform';
+import { DocumentScene } from '../src/render/document-scene';
+import { onViewportStages, viewportStages } from '../src/viewport-door';
+
+export function activate(context: PluginContext) {
+  context.subscriptions.push({ dispose: ensureThreeIntegration() });
+  registerVerbCommands(context, viewportVerbs);
+  return {
+    /** The shared viewport (orbit, pick, framing, overlays), drawing the root a document's `build` answers. */
+    Object3DDocumentViewport,
+    /** The stage a document has mounted, while it has one. */
+    stage: (documentId: string) => viewportStages().find((one) => one.documentId === documentId) ?? null,
+    /** Fires whenever a stage mounts or unmounts; the return unsubscribes. */
+    onStages: onViewportStages,
+    /** The scene-linear-to-display transform a document's stage applies to every frame it draws (null: the stage's
+     *  own); false where the document has no stage session. */
+    setDisplayTransform(documentId: string, transform: DocumentDisplayTransform | null): boolean {
+      const session = object3DDocumentSession(documentId);
+      session?.setDisplayTransform(transform);
+      return session !== null;
+    },
+    /** Frame everything the document's stage draws, as the viewport's Frame All does; false where the document has
+     *  no stage session or nothing to frame. */
+    frameAll: (documentId: string): boolean => object3DDocumentSession(documentId)?.frame(1, 'all') ?? false,
+    /** A document's World: the scene its `build` root stands in, whose background, environment and fog the stage draws
+     *  by (it mirrors them into the scene it renders); null while the root stands in no stage. */
+    documentWorld: (root: THREE.Object3D): THREE.Scene | null => (root.parent instanceof DocumentScene ? root.parent : null),
+  };
+}

package/dist-node/serving.mjs

@@ -285,7 +285,9 @@ async function parseSourceModel(primaryPath, format, bytes) {
       return loader.parse(new TextDecoder().decode(bytes));
     }
     case "dae": {
-      return new ColladaLoader().parse(new TextDecoder().decode(bytes), resourcePath).scene;
+      const collada = new ColladaLoader().parse(new TextDecoder().decode(bytes), resourcePath);
+      if (!collada) throw new Error(`${primaryPath} is not a COLLADA document`);
+      return collada.scene;
     }
     case "stl": {
       const geometry = new STLLoader().parse(bytes.buffer);
@@ -395,11 +397,90 @@ function disposeObject(root) {
   });
 }
 
+// serving/shared-three.ts
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+// ../sdk/src/shared-doorway.ts
+var SHARED_DOORWAY_PREFIX = "\0volter-shared:";
+function sharedDoorwayId(specifier) {
+  return `${SHARED_DOORWAY_PREFIX}${specifier}`;
+}
+
+// serving/shared-three.ts
+var SHARED_THREE_SPECIFIER = "three";
+var SHARED_THREE_MANIFEST_FILE = "volter-shared-three.json";
+function readSharedThreeManifest(distPath) {
+  const manifestPath = path.join(distPath, SHARED_THREE_MANIFEST_FILE);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  if (typeof manifest.file !== "string" || !manifest.file || typeof manifest.coreFile !== "string" || !manifest.coreFile)
+    throw new Error(`${manifestPath} must name the shared three.js and core chunks. Rebuild the editor.`);
+  return { file: manifest.file, coreFile: manifest.coreFile };
+}
+function sharedThreeUrl(file) {
+  return `/${file}`;
+}
+var SHARED_THREE_DOORWAY = sharedDoorwayId(SHARED_THREE_SPECIFIER);
+var SHARED_THREE_CORE_DOORWAY = sharedDoorwayId("three/build/three.core.js");
+function sharedThreePlugin(url, coreUrl) {
+  return {
+    // Vite includes this plugin name in the dependency cache version.
+    name: "volter-shared:three",
+    enforce: "pre",
+    // `three` is the shell's here, never prebundled: excluding it externalizes it out of every
+    // prebundled chunk (Fiber's own `import 'three'` included), so those imports resolve at serve
+    // time through this plugin. A specifier cannot be both included and excluded.
+    config(config) {
+      const optimizeDeps = config.optimizeDeps ??= {};
+      optimizeDeps.include = (optimizeDeps.include ?? []).filter((specifier) => specifier !== SHARED_THREE_SPECIFIER);
+      optimizeDeps.exclude = [...optimizeDeps.exclude ?? [], SHARED_THREE_SPECIFIER];
+    },
+    load(id) {
+      if (id === SHARED_THREE_CORE_DOORWAY) return `export * from ${JSON.stringify(coreUrl)};
+`;
+      return id === SHARED_THREE_DOORWAY ? `export * from ${JSON.stringify(SHARED_THREE_SPECIFIER)};
+export { default } from ${JSON.stringify(SHARED_THREE_SPECIFIER)};
+` : void 0;
+    },
+    resolveId(source, importer, options) {
+      if (importer === SHARED_THREE_CORE_DOORWAY && source === coreUrl) return coreUrl;
+      const cleanSource = source.split("?")[0].replaceAll("\\", "/");
+      const cleanImporter = (importer ?? "").split("?")[0].replaceAll("\\", "/");
+      const core = /(?:^|\/)three\/build\/three\.core\.js$/.test(cleanSource) || cleanSource === "./three.core.js" && /\/three\/build\/three\.[^/]+\.js$/.test(cleanImporter);
+      if (source !== SHARED_THREE_SPECIFIER && !core) return void 0;
+      if (options?.scan) return void 0;
+      if (core) return SHARED_THREE_CORE_DOORWAY;
+      return importer === SHARED_THREE_DOORWAY ? url : SHARED_THREE_DOORWAY;
+    }
+  };
+}
+function projectThreeDedupePlugin() {
+  return {
+    name: "volter-three-dedupe",
+    config: () => ({ resolve: { dedupe: [SHARED_THREE_SPECIFIER, "@react-three/fiber", "its-fine"] } })
+  };
+}
+function sharedThreeServingPlugins(shellOutputDir) {
+  const dedupe = projectThreeDedupePlugin();
+  if (shellOutputDir === null) return [dedupe];
+  const manifest = readSharedThreeManifest(shellOutputDir);
+  return [dedupe, sharedThreePlugin(sharedThreeUrl(manifest.file), sharedThreeUrl(manifest.coreFile))];
+}
+
 // serving/index.ts
 var servingPlugins = (services) => {
   services.registerModelConverter(threeModelConverter);
-  return [animationStampPlugin(services)];
+  return [...sharedThreeServingPlugins(services.shellOutputDir), animationStampPlugin(services)];
 };
+var substrates = [
+  {
+    substrate: "three",
+    surface: "stage",
+    dialects: ["r3f"],
+    default: { dialect: "r3f", anchors: ["source-prop", "source-structure", "construction-literal"] }
+  }
+];
 export {
-  servingPlugins
+  servingPlugins,
+  substrates
 };

package/dist-node/shared-three.mjs

@@ -0,0 +1,145 @@
+// serving/shared-three.ts
+import { readFileSync } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import path2 from "node:path";
+
+// ../sdk/src/shared-doorway.ts
+var SHARED_DOORWAY_PREFIX = "\0volter-shared:";
+function sharedDoorwayId(specifier) {
+  return `${SHARED_DOORWAY_PREFIX}${specifier}`;
+}
+
+// ../sdk/src/shared-entry-module.ts
+import { createRequire } from "node:module";
+import path from "node:path";
+var VALID_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function sharedEntryModule(specifier, exportNames) {
+  const named = exportNames.filter((name) => VALID_IDENTIFIER.test(name)).map((name) => `export const ${name} = __m.${name};`);
+  return [
+    `import * as __ns from ${JSON.stringify(specifier)};`,
+    // Bracketed on purpose: `__ns.default` makes rollup warn that the ES-module
+    // shape (the jsx-dev-runtime shim) has no `default` export, which is the
+    // case this line exists to handle.
+    "const __m = __ns['default'] ?? __ns;",
+    "export default __m;",
+    ...named,
+    ""
+  ].join("\n");
+}
+function installedExportNames(fromDir, specifier) {
+  const require_ = createRequire(path.join(fromDir, "package.json"));
+  const loaded = require_(specifier);
+  return Object.keys(loaded).filter((name) => name !== "default");
+}
+
+// serving/shared-three.ts
+var SHARED_THREE_SPECIFIER = "three";
+var SHARED_THREE_ENTRY_NAME = "volter-shared-three";
+var SHARED_THREE_MANIFEST_FILE = "volter-shared-three.json";
+var VIRTUAL_PREFIX = "\0volter-shared-three:";
+function sharedThreeBuildPlugin(fromDir) {
+  let referenceId;
+  let coreReferenceId;
+  return {
+    name: "volter-shared-three-build",
+    apply: "build",
+    buildStart() {
+      const require_ = createRequire2(path2.join(fromDir, "package.json"));
+      coreReferenceId = this.emitFile({
+        type: "chunk",
+        id: path2.join(path2.dirname(require_.resolve("three")), "three.core.js"),
+        name: "volter-shared-three-core",
+        preserveSignature: "strict"
+      });
+      referenceId = this.emitFile({
+        type: "chunk",
+        id: `${VIRTUAL_PREFIX}${SHARED_THREE_SPECIFIER}`,
+        name: SHARED_THREE_ENTRY_NAME,
+        // Same reason as the shared-React entries: Vite's app build sets
+        // `preserveEntrySignatures: false`, which would mangle the entry's
+        // export names away — `strict` keeps `Mesh` spelled `Mesh`.
+        preserveSignature: "strict"
+      });
+    },
+    resolveId(id) {
+      return id.startsWith(VIRTUAL_PREFIX) ? id : void 0;
+    },
+    load(id) {
+      if (!id.startsWith(VIRTUAL_PREFIX)) return void 0;
+      const specifier = id.slice(VIRTUAL_PREFIX.length);
+      return sharedEntryModule(specifier, installedExportNames(fromDir, specifier));
+    },
+    generateBundle() {
+      this.emitFile({
+        type: "asset",
+        fileName: SHARED_THREE_MANIFEST_FILE,
+        source: `${JSON.stringify(
+          { file: this.getFileName(referenceId), coreFile: this.getFileName(coreReferenceId) },
+          null,
+          2
+        )}
+`
+      });
+    }
+  };
+}
+function readSharedThreeManifest(distPath) {
+  const manifestPath = path2.join(distPath, SHARED_THREE_MANIFEST_FILE);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  if (typeof manifest.file !== "string" || !manifest.file || typeof manifest.coreFile !== "string" || !manifest.coreFile)
+    throw new Error(`${manifestPath} must name the shared three.js and core chunks. Rebuild the editor.`);
+  return { file: manifest.file, coreFile: manifest.coreFile };
+}
+function sharedThreeUrl(file) {
+  return `/${file}`;
+}
+var SHARED_THREE_DOORWAY = sharedDoorwayId(SHARED_THREE_SPECIFIER);
+var SHARED_THREE_CORE_DOORWAY = sharedDoorwayId("three/build/three.core.js");
+function sharedThreePlugin(url, coreUrl) {
+  return {
+    // Vite includes this plugin name in the dependency cache version.
+    name: "volter-shared:three",
+    enforce: "pre",
+    // `three` is the shell's here, never prebundled: excluding it externalizes it out of every
+    // prebundled chunk (Fiber's own `import 'three'` included), so those imports resolve at serve
+    // time through this plugin. A specifier cannot be both included and excluded.
+    config(config) {
+      const optimizeDeps = config.optimizeDeps ??= {};
+      optimizeDeps.include = (optimizeDeps.include ?? []).filter((specifier) => specifier !== SHARED_THREE_SPECIFIER);
+      optimizeDeps.exclude = [...optimizeDeps.exclude ?? [], SHARED_THREE_SPECIFIER];
+    },
+    load(id) {
+      if (id === SHARED_THREE_CORE_DOORWAY) return `export * from ${JSON.stringify(coreUrl)};
+`;
+      return id === SHARED_THREE_DOORWAY ? `export * from ${JSON.stringify(SHARED_THREE_SPECIFIER)};
+export { default } from ${JSON.stringify(SHARED_THREE_SPECIFIER)};
+` : void 0;
+    },
+    resolveId(source, importer, options) {
+      if (importer === SHARED_THREE_CORE_DOORWAY && source === coreUrl) return coreUrl;
+      const cleanSource = source.split("?")[0].replaceAll("\\", "/");
+      const cleanImporter = (importer ?? "").split("?")[0].replaceAll("\\", "/");
+      const core = /(?:^|\/)three\/build\/three\.core\.js$/.test(cleanSource) || cleanSource === "./three.core.js" && /\/three\/build\/three\.[^/]+\.js$/.test(cleanImporter);
+      if (source !== SHARED_THREE_SPECIFIER && !core) return void 0;
+      if (options?.scan) return void 0;
+      if (core) return SHARED_THREE_CORE_DOORWAY;
+      return importer === SHARED_THREE_DOORWAY ? url : SHARED_THREE_DOORWAY;
+    }
+  };
+}
+function projectThreeDedupePlugin() {
+  return {
+    name: "volter-three-dedupe",
+    config: () => ({ resolve: { dedupe: [SHARED_THREE_SPECIFIER, "@react-three/fiber", "its-fine"] } })
+  };
+}
+function sharedThreeServingPlugins(shellOutputDir) {
+  const dedupe = projectThreeDedupePlugin();
+  if (shellOutputDir === null) return [dedupe];
+  const manifest = readSharedThreeManifest(shellOutputDir);
+  return [dedupe, sharedThreePlugin(sharedThreeUrl(manifest.file), sharedThreeUrl(manifest.coreFile))];
+}
+export {
+  sharedThreeBuildPlugin,
+  sharedThreeServingPlugins
+};