VfpPackageReader：URI、预览与缩略图

这一组 API 服务于文件选择、作品列表和外部 GLB 预览。它们不会自动把 PRVW 交给 VoxelViewer；VoxelViewer 的 VFP 路径优先使用自身预览缓存。

URI 读取

readUri()

async readUri(uri: string): Promise<ArrayBuffer>

打开只读 URI，检查非空与 64 MiB 上限，完整读取后关闭文件句柄。返回缓冲归调用方所有。权限被回收、URI 不存在、文件大于 64 MiB 或读取长度不足均会拒绝 Promise。

parseUri() 与 validateUri()

async parseUri(uri: string): Promise<VfpDocument>
async validateUri(uri: string): Promise<VfpDocument>

两者均先读取 URI；前者只解析目录，后者还验证所有载荷 CRC。需要权威数据时，按 readUri → validateAuthoritative 显式执行，避免误把容器校验当作体素完整性校验。

async function listSections(uri: string): Promise<Array<string>> {
  const reader = VoxelKit.createVfpReader();
  const document = await reader.parseUri(uri);
  return document.sectionTags();
}

PRVW：extractPreviewGlb()

extractPreviewGlb(bytes: ArrayBuffer): ArrayBuffer

提取 PRVW 后验证其为 GLB 2.0：魔数 glTF、版本 2、声明总长度和实际长度一致。没有 PRVW、CRC 错误或载荷不是有效 GLB 时会抛错。

const glbBytes = reader.extractPreviewGlb(vfpBytes);
console.info('GLB bytes: ' + glbBytes.byteLength);

该方法不保证 GLB 的材质、节点、纹理语义正确；它只做容器级 GLB 结构检查。

THMB：extractThumbnail()

extractThumbnail(bytes: ArrayBuffer): VfpThumbnail
async extractThumbnailUri(uri: string): Promise<VfpThumbnail>

VFP 1.3 的 THMB 是可选的、全局 RAW PNG。Reader 校验目录、区段 CRC、PNG 签名和 IHDR 宽高，返回：

VfpThumbnail 字段	类型	值
mimeType	string	固定为 image/png。
width	number	PNG IHDR 宽度。
height	number	PNG IHDR 高度。
bytes	ArrayBuffer	与源文件断开的 PNG 副本。

透明底由 PNG alpha 通道表达，Reader 不合成背景色，因此可以直接交由 ArkUI Image 或缓存层决定如何显示。

async function thumbnailSize(uri: string): Promise<string> {
  const reader = VoxelKit.createVfpReader();
  const thumbnail = await reader.extractThumbnailUri(uri);
  return thumbnail.width + ' × ' + thumbnail.height + ' (' + thumbnail.mimeType + ')';
}

缺少 THMB 是正常情况。作品列表应捕获“VFP 不包含 THMB 缩略图”并显示占位图，而不是将它作为导入失败处理。