sa2kit 1.6.78 → 1.6.80

package/dist/mmd/index.d.mts

@@ -1,10 +1,10 @@
 import { e as MMDPlayerBaseProps, f as MMDPlayerBaseRef, g as MMDPlayerEnhancedProps, h as MMDPlaylistProps, b as MMDPlaylistNode, d as MMDResources, i as MMDStage, j as MobileOptimization } from '../types-HorDyIRv.mjs';
 export { M as MMDPlaylistConfig, a as MMDResourceItem, c as MMDResourceOptions, O as OutlineOptions, R as ResourceOption } from '../types-HorDyIRv.mjs';
 import * as React$1 from 'react';
-import React__default from 'react';
+import React__default, { CSSProperties } from 'react';
 import * as THREE from 'three';
 import { a as UploadFileInfo, c as UploadProgress, F as FileMetadata, A as AccessPermission } from '../types-CK4We_aI.mjs';
-import { d as ARMarkerConfig } from '../types-CvKvpyN8.mjs';
+import { d as ARMarkerConfig } from '../types-D4vSK3AJ.mjs';
 
 /**
  * PMX模型解析器类型定义
@@ -1562,6 +1562,12 @@ interface MMDARPlayerProps {
     cameraParametersUrl?: string;
     /** Marker 配置 */
     markerConfig?: ARMarkerConfig;
+    /**
+     * Marker 放置模式
+     * - manual: 识别到 marker 后仍需点击按钮手动放置（默认）
+     * - follow-marker: 识别到 marker 自动显示并跟随 marker
+     */
+    markerPlacementMode?: 'manual' | 'follow-marker';
     /** 是否开启镜像显示 (通常前置摄像头需要开启) */
     mirrored?: boolean;
     /** 是否显示设置按钮 */
@@ -1611,7 +1617,7 @@ interface MMDARPlayerProps {
     onError?: (error: Error) => void;
     /** 样式 */
     className?: string;
-    style?: React.CSSProperties;
+    style?: CSSProperties;
 }
 interface MMDARPlayerRef {
     /** 开启摄像头 */

package/dist/mmd/index.d.ts

@@ -1,10 +1,10 @@
 import { e as MMDPlayerBaseProps, f as MMDPlayerBaseRef, g as MMDPlayerEnhancedProps, h as MMDPlaylistProps, b as MMDPlaylistNode, d as MMDResources, i as MMDStage, j as MobileOptimization } from '../types-HorDyIRv.js';
 export { M as MMDPlaylistConfig, a as MMDResourceItem, c as MMDResourceOptions, O as OutlineOptions, R as ResourceOption } from '../types-HorDyIRv.js';
 import * as React$1 from 'react';
-import React__default from 'react';
+import React__default, { CSSProperties } from 'react';
 import * as THREE from 'three';
 import { a as UploadFileInfo, c as UploadProgress, F as FileMetadata, A as AccessPermission } from '../types-CK4We_aI.js';
-import { d as ARMarkerConfig } from '../types-CvKvpyN8.js';
+import { d as ARMarkerConfig } from '../types-D4vSK3AJ.js';
 
 /**
  * PMX模型解析器类型定义
@@ -1562,6 +1562,12 @@ interface MMDARPlayerProps {
     cameraParametersUrl?: string;
     /** Marker 配置 */
     markerConfig?: ARMarkerConfig;
+    /**
+     * Marker 放置模式
+     * - manual: 识别到 marker 后仍需点击按钮手动放置（默认）
+     * - follow-marker: 识别到 marker 自动显示并跟随 marker
+     */
+    markerPlacementMode?: 'manual' | 'follow-marker';
     /** 是否开启镜像显示 (通常前置摄像头需要开启) */
     mirrored?: boolean;
     /** 是否显示设置按钮 */
@@ -1611,7 +1617,7 @@ interface MMDARPlayerProps {
     onError?: (error: Error) => void;
     /** 样式 */
     className?: string;
-    style?: React.CSSProperties;
+    style?: CSSProperties;
 }
 interface MMDARPlayerRef {
     /** 开启摄像头 */

package/dist/mmd/index.js

@@ -7132,6 +7132,42 @@ var DEFAULT_AR_ASSETS = {
 
 // src/ar/load-arjs.ts
 var loadPromise = null;
+function isTHREExNamespace(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.ArToolkitSource === "function" && typeof candidate.ArToolkitContext === "function" && typeof candidate.ArMarkerControls === "function";
+}
+function resolveTHREExNamespace(moduleExports) {
+  const arWindow = window;
+  const globalTHREEx = arWindow.THREEx;
+  if (isTHREExNamespace(globalTHREEx)) {
+    return globalTHREEx;
+  }
+  if (isTHREExNamespace(moduleExports)) {
+    return moduleExports;
+  }
+  const record = moduleExports;
+  const defaultExport = record?.default;
+  if (isTHREExNamespace(defaultExport)) {
+    return defaultExport;
+  }
+  if (isTHREExNamespace(record?.THREEx)) {
+    return record?.THREEx;
+  }
+  const arjsCandidate = record?.ARjs ?? defaultExport ?? record ?? arWindow.ARjs;
+  const arjsRecord = arjsCandidate;
+  const source = arjsRecord?.Source;
+  const context = arjsRecord?.Context;
+  const markerControls = arjsRecord?.MarkerControls;
+  if (typeof source === "function" && typeof context === "function" && typeof markerControls === "function") {
+    return {
+      ArToolkitSource: source,
+      ArToolkitContext: context,
+      ArMarkerControls: markerControls
+    };
+  }
+  return void 0;
+}
 async function loadARJS(options = {}) {
   if (typeof window === "undefined") {
     throw new Error("AR.js can only be loaded in a browser environment.");
@@ -7141,15 +7177,18 @@ async function loadARJS(options = {}) {
   }
   const existing = window.THREEx;
   if (existing && !options.forceReload) {
-    return existing;
+    if (isTHREExNamespace(existing)) {
+      return existing;
+    }
   }
   if (!loadPromise || options.forceReload) {
     const importPromise = options.locationOnly ? import('@ar-js-org/ar.js/three.js/build/ar-threex-location-only.js') : import('@ar-js-org/ar.js/three.js/build/ar-threex.js');
-    loadPromise = importPromise.then(() => {
-      const THREEx = window.THREEx;
+    loadPromise = importPromise.then((loadedModule) => {
+      const THREEx = resolveTHREExNamespace(loadedModule);
       if (!THREEx) {
-        throw new Error("AR.js loaded, but THREEx namespace was not found.");
+        throw new Error("AR.js loaded, but THREEx namespace was not found in module exports or window.");
       }
+      window.THREEx = THREEx;
       return THREEx;
     });
   }
@@ -7192,6 +7231,7 @@ var MMDARApp = React10.forwardRef((props, ref) => {
     cameraConfig,
     cameraParametersUrl,
     markerConfig,
+    markerPlacementMode = "manual",
     mirrored = false,
     showSettings,
     modelPresets,
@@ -7233,6 +7273,7 @@ var MMDARApp = React10.forwardRef((props, ref) => {
   const mmdMeshRef = React10.useRef(null);
   const animationFrameRef = React10.useRef(null);
   const markerDetectedRef = React10.useRef(false);
+  const markerPlacedOnceRef = React10.useRef(false);
   const audioRef = React10.useRef(null);
   const autoPlayRef = React10.useRef(autoPlay);
   const [isLoading, setIsLoading] = React10.useState(true);
@@ -7263,6 +7304,7 @@ var MMDARApp = React10.forwardRef((props, ref) => {
     return {
       type: markerConfig?.type ?? "pattern",
       patternUrl: markerConfig?.patternUrl ?? DEFAULT_AR_ASSETS.patternUrl,
+      descriptorsUrl: markerConfig?.descriptorsUrl,
       barcodeValue: markerConfig?.barcodeValue ?? 0,
       changeMatrixMode: markerConfig?.changeMatrixMode ?? "modelViewMatrix"
     };
@@ -7335,14 +7377,24 @@ var MMDARApp = React10.forwardRef((props, ref) => {
         modelRootRef.current.quaternion.identity();
         updateModelPlacement(true);
       } else {
-        if (modelRootRef.current.parent !== sceneRef.current) {
-          modelRootRef.current.parent?.remove(modelRootRef.current);
-          sceneRef.current.add(modelRootRef.current);
+        if (markerPlacementMode === "follow-marker" && markerRootRef.current) {
+          if (modelRootRef.current.parent !== markerRootRef.current) {
+            modelRootRef.current.parent?.remove(modelRootRef.current);
+            markerRootRef.current.add(modelRootRef.current);
+          }
+          modelRootRef.current.position.set(0, 0, 0);
+          modelRootRef.current.quaternion.identity();
+          updateModelPlacement(markerDetectedRef.current);
+        } else {
+          if (modelRootRef.current.parent !== sceneRef.current) {
+            modelRootRef.current.parent?.remove(modelRootRef.current);
+            sceneRef.current.add(modelRootRef.current);
+          }
+          updateModelPlacement(initialModelVisible);
         }
-        updateModelPlacement(initialModelVisible);
       }
     },
-    [initialModelVisible, updateModelPlacement]
+    [initialModelVisible, markerPlacementMode, updateModelPlacement]
   );
   const stopCameraStream = React10.useCallback(() => {
     const source = arToolkitSourceRef.current;
@@ -7369,6 +7421,7 @@ var MMDARApp = React10.forwardRef((props, ref) => {
     arToolkitSourceRef.current = null;
     arToolkitContextRef.current = null;
     markerDetectedRef.current = false;
+    markerPlacedOnceRef.current = false;
     setMarkerDetected(false);
     setCameraReady(false);
     setArReady(false);
@@ -7444,6 +7497,13 @@ var MMDARApp = React10.forwardRef((props, ref) => {
           if (isVisible !== markerDetectedRef.current) {
             markerDetectedRef.current = isVisible;
             setMarkerDetected(isVisible);
+            if (resolvedARMode !== "overlay" /* Overlay */ && markerPlacementMode === "follow-marker") {
+              updateModelPlacement(isVisible);
+              if (isVisible && !markerPlacedOnceRef.current) {
+                markerPlacedOnceRef.current = true;
+                onModelPlaced?.();
+              }
+            }
           }
         }
       }
@@ -7454,10 +7514,15 @@ var MMDARApp = React10.forwardRef((props, ref) => {
       renderer.render(scene, camera);
     };
     render();
-  }, []);
+  }, [markerPlacementMode, onModelPlaced, resolvedARMode, updateModelPlacement]);
   const setupAR = React10.useCallback(async (facingOverride) => {
     if (!sceneRef.current || !cameraRef.current) return;
     const THREEx = await loadARJS({ three: THREE2__namespace });
+    if (resolvedMarkerConfig.type === "nft" && !resolvedMarkerConfig.descriptorsUrl) {
+      throw new Error(
+        'markerConfig.descriptorsUrl is required when markerConfig.type is "nft".'
+      );
+    }
     const facingMode = facingOverride ?? cameraFacing;
     const sourceWidth = typeof cameraConfig?.width === "number" ? cameraConfig.width : cameraConfig?.width?.ideal;
     const sourceHeight = typeof cameraConfig?.height === "number" ? cameraConfig.height : cameraConfig?.height?.ideal;
@@ -7477,6 +7542,7 @@ var MMDARApp = React10.forwardRef((props, ref) => {
     const markerRoot = new THREE2__namespace.Group();
     markerRootRef.current = markerRoot;
     sceneRef.current.add(markerRoot);
+    attachModelRoot(resolvedARMode);
     markerControlsRef.current = new THREEx.ArMarkerControls(
       arToolkitContext,
       markerRoot,
@@ -7517,6 +7583,8 @@ var MMDARApp = React10.forwardRef((props, ref) => {
     mirrored,
     onCameraReady,
     resize,
+    attachModelRoot,
+    resolvedARMode,
     resolvedMarkerConfig
   ]);
   const loadMMDResources = React10.useCallback(async () => {
@@ -7610,12 +7678,19 @@ var MMDARApp = React10.forwardRef((props, ref) => {
       onModelPlaced?.();
       return;
     }
+    if (markerPlacementMode === "follow-marker") {
+      updateModelPlacement(markerDetectedRef.current);
+      if (markerDetectedRef.current) {
+        onModelPlaced?.();
+      }
+      return;
+    }
     if (!markerRootRef.current) return;
     modelRootRef.current.position.copy(markerRootRef.current.position);
     modelRootRef.current.quaternion.copy(markerRootRef.current.quaternion);
     updateModelPlacement(true);
     onModelPlaced?.();
-  }, [onModelPlaced, resolvedARMode, updateModelPlacement]);
+  }, [markerPlacementMode, onModelPlaced, resolvedARMode, updateModelPlacement]);
   const removeModel = React10.useCallback(() => {
     updateModelPlacement(false);
   }, [updateModelPlacement]);
@@ -7768,7 +7843,7 @@ var MMDARApp = React10.forwardRef((props, ref) => {
     /* @__PURE__ */ React10__default.default.createElement("canvas", { ref: canvasRef, className: "absolute inset-0 w-full h-full", style: mirroredStyle }),
     isLoading && /* @__PURE__ */ React10__default.default.createElement("div", { className: "absolute inset-0 flex items-center justify-center bg-black/70 text-white z-20" }, /* @__PURE__ */ React10__default.default.createElement("div", { className: "text-center" }, /* @__PURE__ */ React10__default.default.createElement("div", { className: "h-10 w-10 animate-spin rounded-full border-b-2 border-white mx-auto mb-3" }), /* @__PURE__ */ React10__default.default.createElement("div", null, "Initializing AR..."))),
     error && /* @__PURE__ */ React10__default.default.createElement("div", { className: "absolute inset-0 flex items-center justify-center bg-red-950/80 text-white z-20" }, /* @__PURE__ */ React10__default.default.createElement("div", { className: "text-center max-w-sm px-4" }, /* @__PURE__ */ React10__default.default.createElement("div", { className: "text-lg font-semibold mb-2" }, "AR Error"), /* @__PURE__ */ React10__default.default.createElement("div", { className: "text-sm text-red-200" }, error))),
-    arReady && !error && /* @__PURE__ */ React10__default.default.createElement(React10__default.default.Fragment, null, resolvedARMode !== "overlay" /* Overlay */ && !modelPlaced && /* @__PURE__ */ React10__default.default.createElement("div", { className: "absolute top-4 left-4 right-4 bg-black/70 text-white p-3 rounded-lg text-sm z-10" }, /* @__PURE__ */ React10__default.default.createElement("div", { className: "font-semibold mb-1" }, "Marker Placement"), /* @__PURE__ */ React10__default.default.createElement("div", { className: "text-gray-200" }, 'Align the marker in view, then tap "', placementText, '" to place the model.'), /* @__PURE__ */ React10__default.default.createElement("div", { className: "mt-2" }, markerDetected ? /* @__PURE__ */ React10__default.default.createElement("span", { className: "text-green-400" }, "Marker detected") : /* @__PURE__ */ React10__default.default.createElement("span", { className: "text-yellow-400" }, "Waiting for marker..."))), /* @__PURE__ */ React10__default.default.createElement("div", { className: "absolute top-4 right-4 flex items-center space-x-2 z-10" }, /* @__PURE__ */ React10__default.default.createElement(
+    arReady && !error && /* @__PURE__ */ React10__default.default.createElement(React10__default.default.Fragment, null, resolvedARMode !== "overlay" /* Overlay */ && !modelPlaced && /* @__PURE__ */ React10__default.default.createElement("div", { className: "absolute top-4 left-4 right-4 bg-black/70 text-white p-3 rounded-lg text-sm z-10" }, /* @__PURE__ */ React10__default.default.createElement("div", { className: "font-semibold mb-1" }, "Marker Placement"), /* @__PURE__ */ React10__default.default.createElement("div", { className: "text-gray-200" }, markerPlacementMode === "follow-marker" ? "Align the marker in view, model will be placed automatically." : `Align the marker in view, then tap "${placementText}" to place the model.`), /* @__PURE__ */ React10__default.default.createElement("div", { className: "mt-2" }, markerDetected ? /* @__PURE__ */ React10__default.default.createElement("span", { className: "text-green-400" }, "Marker detected") : /* @__PURE__ */ React10__default.default.createElement("span", { className: "text-yellow-400" }, "Waiting for marker..."))), /* @__PURE__ */ React10__default.default.createElement("div", { className: "absolute top-4 right-4 flex items-center space-x-2 z-10" }, /* @__PURE__ */ React10__default.default.createElement(
       "span",
       {
         className: clsx.clsx("h-2.5 w-2.5 rounded-full", cameraReady ? "bg-green-400" : "bg-red-400"),
@@ -7793,7 +7868,7 @@ var MMDARApp = React10.forwardRef((props, ref) => {
         className: "px-4 py-2 rounded-lg bg-gray-700 text-white hover:bg-gray-600"
       },
       "Settings"
-    ), resolvedARMode !== "overlay" /* Overlay */ && !modelPlaced && /* @__PURE__ */ React10__default.default.createElement(
+    ), resolvedARMode !== "overlay" /* Overlay */ && markerPlacementMode === "manual" && !modelPlaced && /* @__PURE__ */ React10__default.default.createElement(
       "button",
       {
         onClick: placeModel,
@@ -7860,6 +7935,13 @@ var MMDARApp = React10.forwardRef((props, ref) => {
       },
       /* @__PURE__ */ React10__default.default.createElement("option", { value: "overlay" /* Overlay */ }, "Overlay"),
       /* @__PURE__ */ React10__default.default.createElement("option", { value: "world-fixed" /* WorldFixed */ }, "World Fixed")
+    )), /* @__PURE__ */ React10__default.default.createElement("label", { className: "block text-xs text-gray-300" }, "Marker Placement", /* @__PURE__ */ React10__default.default.createElement(
+      "input",
+      {
+        value: markerPlacementMode === "follow-marker" ? "Auto Follow" : "Manual Place",
+        readOnly: true,
+        className: "mt-1 w-full bg-gray-700 text-white text-sm rounded px-2 py-1 opacity-70"
+      }
     )), /* @__PURE__ */ React10__default.default.createElement("label", { className: "block text-xs text-gray-300" }, "Camera", /* @__PURE__ */ React10__default.default.createElement(
       "select",
       {