From 852e65f7d8701c0ba5a7e080f3a606d77c139046 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= <kvtodev@outlook.com>
Date: Tue, 22 Sep 2026 16:56:19 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9F=A5=E7=9C=8B=E5=99=A8=E5=AD=97=E8=8A=82?=
 =?UTF-8?q?=E6=9D=A5=E6=BA=90=E6=B3=A8=E6=98=8E=E5=BC=95=E7=94=A8=E5=BF=85?=
 =?UTF-8?q?=E9=A1=BB=E7=A8=B3=E5=AE=9A=20-=20Model3DViewerSource=20?=
 =?UTF-8?q?=E7=9A=84=20bytes=20=E5=88=86=E6=94=AF=E8=A1=A5=E5=85=85=20buff?=
 =?UTF-8?q?er=20=E7=94=9F=E5=91=BD=E5=91=A8=E6=9C=9F=E4=B8=8E=E7=A8=B3?=
 =?UTF-8?q?=E5=AE=9A=E5=BC=95=E7=94=A8=E8=A6=81=E6=B1=82=20-=20=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E=E5=90=8C=E5=86=85=E5=AE=B9=E6=8D=A2=E6=96=B0=E5=BC=95?=
 =?UTF-8?q?=E7=94=A8=E4=BC=9A=E8=A7=A6=E5=8F=91=E5=9C=BA=E6=99=AF=E9=87=8D?=
 =?UTF-8?q?=E5=BB=BA=E4=B8=8E=20GPU=20=E9=87=8D=E4=BC=A0=E7=9A=84=E5=90=8E?=
 =?UTF-8?q?=E6=9E=9C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/model3d-viewer/src/loader.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/model3d-viewer/src/loader.ts b/packages/model3d-viewer/src/loader.ts
index be4b376ed..83a9a53d6 100644
--- a/packages/model3d-viewer/src/loader.ts
+++ b/packages/model3d-viewer/src/loader.ts
@@ -9,6 +9,14 @@ export type Model3DViewerSource =
    * 调用方已知格式时给出；不传就由加载流程按「声明类型 → 字节魔数 → 地址扩展名」判定。
    */
   | { kind: 'url'; url: string; format?: Model3DViewerFormat }
+  /**
+   * 直接给模型字节；调用方负责持有并与生命周期一致地释放这份 buffer。
+   *
+   * **引用必须稳定**：查看器的加载 effect 依赖 `data` 的对象引用，只比对内容。
+   * 父层每次渲染都新建一份同内容的 ArrayBuffer 会触发「销毁旧场景 → 重新解析 →
+   * 重新上传 GPU」，表现为闪烁与资源抖动；因此请在父层缓存 buffer，或只在内容
+   * 真的变化时才换新引用。
+   */
   | { kind: 'bytes'; data: ArrayBuffer; format?: Model3DViewerFormat };
 
 export const MODEL3D_VIEWER_SUPPORTED_FORMATS: readonly Model3DViewerFormat[] =