@loaders.gl/scene 5.0.0-alpha.9 → 5.0.0-beta.1

package/src/gltf/gltf-source.ts

@@ -0,0 +1,244 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTF, GLTFNode, GLTFScene} from './lib/types/gltf-json-schema';
+import type {GLTFExternalBuffer, GLTFExternalFile, GLTFWithBuffers} from './lib/types/gltf-types';
+
+/** Options for a persistent, CPU-only glTF source. */
+export type GLTFSourceOptions = {
+  /** Override the platform fetch implementation. */
+  fetch?: typeof fetch;
+  /** Maximum number of nested node references traversed. */
+  maxDepth?: number;
+};
+
+/**
+ * Persistent, schema-preserving access to a glTF document and its resources.
+ *
+ * Opening reads the root document, but does not fetch external buffers, images or assets.
+ * The source owns its resource cache and outstanding requests. No GPU resources are created.
+ */
+export class GLTFSource {
+  /** Canonical URL of the root document, including redirects. */
+  readonly url: string;
+  /** Parsed container and lazily resolved resources. */
+  readonly gltf: GLTFWithBuffers;
+  /** Original glTF JSON without extension decoding. */
+  readonly json: GLTF;
+  /** Fetch implementation used for lazy requests. */
+  private readonly fetcher: typeof fetch;
+  /** Maximum traversal depth relative to each scene root. */
+  private readonly maxDepth: number;
+  /** Requests shared by canonical resource URL. */
+  private readonly pending = new Map<string, Promise<ArrayBuffer>>();
+  /** Downloaded bytes shared by canonical resource URL. */
+  private readonly cache = new Map<string, ArrayBuffer>();
+  /** Cancellation signal shared by resource requests. */
+  private readonly controller = new AbortController();
+  /** Whether this source has been closed. */
+  private closed = false;
+
+  /** Initialize an open source around the parsed container. */
+  private constructor(url: string, gltf: GLTFWithBuffers, options: GLTFSourceOptions) {
+    this.url = url;
+    this.gltf = gltf;
+    this.json = gltf.json;
+    this.fetcher = options.fetch || globalThis.fetch.bind(globalThis);
+    this.maxDepth = options.maxDepth ?? 256;
+  }
+
+  /** Load the root JSON or GLB container without fetching external resources. */
+  static async open(url: string, options: GLTFSourceOptions = {}): Promise<GLTFSource> {
+    if (
+      options.maxDepth !== undefined &&
+      (!Number.isSafeInteger(options.maxDepth) || options.maxDepth < 0)
+    ) {
+      throw new Error('maxDepth must be a nonnegative safe integer');
+    }
+    const fetcher = options.fetch || globalThis.fetch.bind(globalThis);
+    const response = await fetcher(url);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch glTF ${url}: HTTP ${response.status}`);
+    }
+    const bytes = await response.arrayBuffer();
+    url = response.url || url;
+    const baseUrl = new URL('.', url).href;
+    const {parse: parseGLTF} = await import('./gltf-loader');
+    const {EXTENSIONS} = await import('./lib/api/gltf-extensions');
+    const gltf = await parseGLTF(
+      bytes,
+      {
+        core: {baseUrl},
+        gltf: {
+          normalize: false,
+          excludeExtensions: EXTENSIONS.map(extension => extension.name),
+          loadBuffers: false,
+          loadImages: false,
+          loadAudio: false,
+          loadFiles: false,
+          loadExternalAssets: false,
+          decompressMeshes: false
+        }
+      },
+      {url, fetch: fetcher}
+    );
+    return new GLTFSource(url, gltf, options);
+  }
+
+  /** Return an unmodified glTF scene definition. */
+  getScene(index: number = this.json.scene ?? 0): GLTFScene {
+    this.assertOpen();
+    const scene = this.json.scenes?.[index];
+    if (!scene) throw new Error(`Invalid glTF scene index ${index}`);
+    return scene;
+  }
+
+  /** Return an unmodified glTF node definition. */
+  getNode(index: number): GLTFNode {
+    this.assertOpen();
+    const node = this.json.nodes?.[index];
+    if (!node) throw new Error(`Invalid glTF node index ${index}`);
+    return node;
+  }
+
+  /** Traverse a scene's native node indices in depth-first order. */
+  *traverse(
+    sceneIndex: number = this.json.scene ?? 0
+  ): IterableIterator<{index: number; node: GLTFNode}> {
+    const scene = this.getScene(sceneIndex);
+    const active = new Set<number>();
+    /** Visit one node while tracking only the current ancestry path. */
+    const visit = function* (
+      source: GLTFSource,
+      index: number,
+      depth: number
+    ): IterableIterator<{index: number; node: GLTFNode}> {
+      if (depth > source.maxDepth) throw new Error('glTF node traversal depth exceeded');
+      if (active.has(index)) throw new Error(`Cycle in glTF node hierarchy at index ${index}`);
+      const node = source.getNode(index);
+      active.add(index);
+      try {
+        yield {index, node};
+        for (const child of node.children || []) yield* visit(source, child, depth + 1);
+      } finally {
+        active.delete(index);
+      }
+    };
+    for (const index of scene.nodes || []) yield* visit(this, index, 0);
+  }
+
+  /** Fetch an external or data-URI buffer, or return an embedded GLB buffer. */
+  async resolveBuffer(index: number): Promise<GLTFExternalBuffer> {
+    this.assertOpen();
+    const definition = this.json.buffers?.[index];
+    if (!definition) throw new Error(`Invalid glTF buffer index ${index}`);
+    const embedded = this.gltf.buffers[index];
+    if (embedded) {
+      if (embedded.byteLength < definition.byteLength)
+        throw new Error(`Truncated glTF buffer ${index}`);
+      embedded.byteLength = definition.byteLength;
+      return embedded;
+    }
+    if (!definition.uri) throw new Error(`glTF buffer ${index} has no embedded data or URI`);
+    const data = await this.fetchBytes(definition.uri);
+    if (data.byteLength < definition.byteLength) throw new Error(`Truncated glTF buffer ${index}`);
+    this.assertOpen();
+    const buffer = {arrayBuffer: data, byteOffset: 0, byteLength: definition.byteLength};
+    this.gltf.buffers[index] = buffer;
+    return buffer;
+  }
+
+  /** Resolve a glTF 2.1 file entry without loading unrelated resources. */
+  async resolveFile(index: number): Promise<GLTFExternalFile> {
+    this.assertOpen();
+    const definition = this.json.files?.[index];
+    if (!definition) throw new Error(`Invalid glTF file index ${index}`);
+    const existing = this.gltf.files?.[index];
+    if (existing) return existing;
+    if (!definition.mimeType) throw new Error(`glTF file ${index} lacks mimeType`);
+    if ((definition.uri === undefined) === (definition.bufferView === undefined)) {
+      throw new Error(`glTF file ${index} must specify exactly one of uri or bufferView`);
+    }
+    let arrayBuffer: ArrayBuffer;
+    let byteOffset = 0;
+    let byteLength: number;
+    if (definition.uri !== undefined) {
+      arrayBuffer = await this.fetchBytes(definition.uri);
+      byteLength = arrayBuffer.byteLength;
+    } else {
+      const view = this.json.bufferViews?.[definition.bufferView!];
+      if (!view) throw new Error(`Invalid glTF file bufferView ${definition.bufferView}`);
+      const buffer = await this.resolveBuffer(view.buffer);
+      arrayBuffer = buffer.arrayBuffer;
+      const viewOffset = view.byteOffset ?? 0;
+      byteOffset = buffer.byteOffset + viewOffset;
+      byteLength = view.byteLength;
+      if (
+        !Number.isSafeInteger(viewOffset) ||
+        viewOffset < 0 ||
+        !Number.isSafeInteger(byteLength) ||
+        byteLength < 0 ||
+        viewOffset + byteLength > buffer.byteLength ||
+        byteOffset + byteLength > arrayBuffer.byteLength
+      ) {
+        throw new Error('glTF file bufferView exceeds buffer');
+      }
+    }
+    this.assertOpen();
+    const result: GLTFExternalFile = {
+      arrayBuffer,
+      byteOffset,
+      byteLength,
+      mimeType: definition.mimeType,
+      name: definition.name,
+      ...(definition.uri ? {url: new URL(definition.uri, this.url).href} : {})
+    };
+    this.gltf.files ||= new Array(this.json.files?.length || 0).fill(null);
+    this.gltf.files[index] = result;
+    return result;
+  }
+
+  /** Release source-owned cached bytes and cancel outstanding fetches. */
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.controller.abort();
+    this.cache.clear();
+    this.pending.clear();
+    this.gltf.buffers.length = 0;
+    if (this.gltf.files) this.gltf.files.length = 0;
+    Reflect.deleteProperty(this.gltf, '_glb');
+    delete this.gltf.binary;
+  }
+
+  /** Reject operations after close. */
+  private assertOpen(): void {
+    if (this.closed) throw new Error('GLTFSource is closed');
+  }
+
+  /** Fetch bytes once per URL, allowing failed requests to be retried. */
+  private async fetchBytes(uri: string): Promise<ArrayBuffer> {
+    this.assertOpen();
+    const key = new URL(uri, this.url).href;
+    const cached = this.cache.get(key);
+    if (cached) return cached;
+    const inFlight = this.pending.get(key);
+    if (inFlight) return inFlight;
+    const promise = (async () => {
+      const response = await this.fetcher(key, {signal: this.controller.signal});
+      if (!response.ok)
+        throw new Error(`Failed to fetch glTF resource ${key}: HTTP ${response.status}`);
+      const data = await response.arrayBuffer();
+      this.assertOpen();
+      this.cache.set(key, data);
+      return data;
+    })();
+    this.pending.set(key, promise);
+    try {
+      return await promise;
+    } finally {
+      this.pending.delete(key);
+    }
+  }
+}

package/src/gltf/gltf-writer.ts

@@ -0,0 +1,62 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {WriterOptions, WriterWithEncoder} from '@loaders.gl/core/loader-utils';
+import {VERSION} from './lib/utils/version';
+import {encodeGLTFSync} from './lib/encoders/encode-gltf';
+import type {GLTFWithBuffers} from './lib/types/gltf-types';
+import {compressGLTFWithDraco, type GLTFDracoWriterOptions} from './lib/encoders/encode-gltf-draco';
+import {encodeExtensions} from './lib/api/gltf-extensions';
+import {GLTFFormat} from './gltf-format';
+
+export type GLTFWriterOptions = WriterOptions & {
+  gltf?: {
+    /** Optional glTF-specific encoding features. */
+    draco?: GLTFDracoWriterOptions;
+  };
+  byteOffset?: number;
+};
+
+/**
+ * GLTF exporter
+ */
+export const GLTFWriter = {
+  dataType: null as unknown as any,
+  batchType: null as never,
+
+  ...GLTFFormat,
+  version: VERSION,
+  options: {
+    gltf: {}
+  },
+
+  encode: async (gltf: GLTFWithBuffers, options: GLTFWriterOptions = {}) => {
+    const compressed = await compressGLTFWithDraco(gltf, options);
+    const encodeOptions = {...options};
+    encodeOptions.gltf = options.gltf ? {...options.gltf, draco: undefined} : undefined;
+    return encodeSync(compressed, encodeOptions);
+  },
+  encodeSync
+} as WriterWithEncoder<any, never, GLTFWriterOptions>;
+
+function encodeSync(gltf: GLTFWithBuffers, options: GLTFWriterOptions = {}) {
+  if (options.gltf?.draco?.enabled) {
+    throw new Error(
+      'GLTFWriter Draco compression is asynchronous; use encode() instead of encodeSync()'
+    );
+  }
+  const {byteOffset = 0} = options;
+  const gltfToEncode = encodeExtensions(gltf);
+  // Extension encoders repack JSON buffer references; keep the input container in sync.
+  gltf.buffers = gltfToEncode.buffers;
+  gltf.binary = gltfToEncode.binary;
+
+  // Calculate length, then create arraybuffer and encode
+  const byteLength = encodeGLTFSync(gltfToEncode, null, byteOffset, options);
+  const arrayBuffer = new ArrayBuffer(byteLength);
+  const dataView = new DataView(arrayBuffer);
+  encodeGLTFSync(gltfToEncode, dataView, byteOffset, options);
+
+  return arrayBuffer;
+}

package/src/gltf/index.ts

@@ -0,0 +1,270 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/* eslint-disable camelcase, indent */
+export type {GLB, GLBChunk} from './lib/types/glb-types';
+
+// Raw GLTF Types (i.e. not post-processed)
+export type {
+  GLTF,
+  GLTFAccessor,
+  GLTFBuffer,
+  GLTFBufferView,
+  GLTFMeshPrimitive,
+  GLTFMesh,
+  GLTFNode,
+  GLTFMaterial,
+  GLTFSampler,
+  GLTFScene,
+  GLTFSkin,
+  GLTFTexture,
+  GLTFImage,
+  GLTFFile,
+  GLTFExternalAsset,
+  GLTFObject,
+  // The following extensions are handled by the GLTFLoader and removed from the parsed glTF (disable via options.gltf.excludeExtensions)
+  GLTF_KHR_binary_glTF,
+  GLTF_KHR_draco_mesh_compression,
+  GLTF_KHR_texture_basisu,
+  GLTF_KHR_meshopt_compression,
+  GLTF_EXT_meshopt_compression,
+  GLTF_EXT_texture_webp
+} from './lib/types/gltf-json-schema';
+
+export type {GLTFShape, GLTFBoundingVolume} from './lib/types/gltf-shape-schema';
+export type {
+  GLTF_MPEG_audio_spatial,
+  GLTFSpatialAudio,
+  GLTFSpatialAudioSource,
+  GLTFSpatialAudioListener,
+  GLTFSpatialAudioReverb,
+  GLTFSpatialAudioReverbProperty
+} from './lib/types/gltf-mpeg-audio-spatial-schema';
+export {name as MPEG_AUDIO_SPATIAL, getSpatialAudio} from './lib/extensions/MPEG_audio_spatial';
+export type {
+  GLTF_KHR_audio_emitter,
+  GLTFKHRAudioData,
+  GLTFKHRAudioSource,
+  GLTFKHRAudioPositional,
+  GLTFKHRAudioEmitter,
+  GLTFKHRAudioAttachment,
+  GLTFAudioClip,
+  GLTFAudioEmitterSource,
+  GLTFAudioEmitter
+} from './lib/types/gltf-khr-audio-emitter-schema';
+export {name as KHR_AUDIO_EMITTER} from './lib/extensions/KHR_audio_emitter';
+export type {
+  GLTF_EXT_mesh_polygon,
+  GLTFImplicitFeatureIdRange,
+  GLTFMeshPolygonData,
+  GLTFPolygon,
+  GLTFPrimitiveIndexRange,
+  GLTFPrimitiveRestartData
+} from './lib/types/gltf-vector-topology';
+export type {
+  GLTF_KHR_gaussian_splatting,
+  GLTF_KHR_gaussian_splatting_compression_spz_2,
+  GLTFGaussianSplatPrimitive
+} from './lib/types/gltf-ext-gaussian-splatting-schema';
+export type {
+  GLTF_EXT_primitive_voxels,
+  GLTFVoxelPrimitive
+} from './lib/types/gltf-ext-vector-voxel-schema';
+
+// 3DTiles extensions
+export type {
+  GLTF_EXT_feature_metadata_GLTF,
+  GLTF_EXT_feature_metadata_Schema,
+  GLTF_EXT_feature_metadata_Class,
+  GLTF_EXT_feature_metadata_ClassProperty,
+  GLTF_EXT_feature_metadata_Enum,
+  GLTF_EXT_feature_metadata_EnumValue,
+  GLTF_EXT_feature_metadata_FeatureTable,
+  GLTF_EXT_feature_metadata_FeatureTableProperty,
+  GLTF_EXT_feature_metadata_FeatureTexture,
+  GLTF_EXT_feature_metadata_TextureAccessor,
+  GLTF_EXT_feature_metadata_Statistics,
+  GLTF_EXT_feature_metadata_StatisticsClass,
+  GLTF_EXT_feature_metadata_StatisticsClassProperty,
+  GLTF_EXT_feature_metadata_Primitive,
+  GLTF_EXT_feature_metadata_FeatureIdAttribute,
+  GLTF_EXT_feature_metadata_FeatureIdAttributeFeatureIds,
+  GLTF_EXT_feature_metadata_FeatureIdTexture,
+  GLTF_EXT_feature_metadata_FeatureIdTextureAccessor
+} from './lib/types/gltf-ext-feature-metadata-schema';
+
+export type {
+  GLTF_EXT_structural_metadata_GLTF,
+  GLTF_EXT_structural_metadata_Schema,
+  GLTF_EXT_structural_metadata_PropertyTable,
+  GLTF_EXT_structural_metadata_PropertyTexture,
+  GLTF_EXT_structural_metadata_Class,
+  GLTF_EXT_structural_metadata_ClassProperty
+} from './lib/types/gltf-ext-structural-metadata-schema';
+
+export type {
+  GLTF_EXT_mesh_features,
+  GLTF_EXT_mesh_features_featureId
+} from './lib/types/gltf-ext-mesh-features-schema';
+
+export {name as EXT_MESH_FEATURES} from './lib/extensions/EXT_mesh_features';
+export {name as EXT_MESH_POLYGON} from './lib/extensions/EXT_mesh_polygon';
+export {
+  name as KHR_GAUSSIAN_SPLATTING,
+  SPZ_COMPRESSION_EXTENSION_NAME,
+  getGaussianSplatPrimitives
+} from './lib/extensions/KHR_gaussian_splatting';
+export {
+  name as EXT_PRIMITIVE_VOXELS,
+  getVoxelPrimitives
+} from './lib/extensions/EXT_primitive_voxels';
+export {
+  name as KHR_MESH_PRIMITIVE_RESTART,
+  getPrimitiveRestartRanges
+} from './lib/extensions/KHR_mesh_primitive_restart';
+export {name as EXT_STRUCTURAL_METADATA} from './lib/extensions/EXT_structural_metadata';
+export {name as EXT_FEATURE_METADATA} from './lib/extensions/deprecated/EXT_feature_metadata';
+
+export type {
+  GLTFWithBuffers,
+  GLTFExternalFile,
+  FeatureTableJson
+} from './lib/types/gltf-types';
+export {
+  GLTFSchema,
+  GLTFIdSchema,
+  GLTFObjectSchema,
+  GLTFAccessorSchema,
+  GLTFAccessorSparseSchema,
+  GLTFAccessorSparseIndicesSchema,
+  GLTFAccessorSparseValuesSchema,
+  GLTFAnimationSchema,
+  GLTFAnimationChannelSchema,
+  GLTFAnimationChannelTargetSchema,
+  GLTFAnimationSamplerSchema,
+  GLTFAssetSchema,
+  GLTFBufferSchema,
+  GLTFBufferViewSchema,
+  GLTFCameraSchema,
+  GLTFCameraOrthographicSchema,
+  GLTFCameraPerspectiveSchema,
+  GLTFImageSchema,
+  GLTFExternalAssetSchema,
+  GLTFMaterialSchema,
+  GLTFMaterialNormalTextureInfoSchema,
+  GLTFMaterialOcclusionTextureInfoSchema,
+  GLTFMaterialPbrMetallicRoughnessSchema,
+  GLTFMeshSchema,
+  GLTFMeshPrimitiveSchema,
+  GLTFNodeSchema,
+  GLTFSamplerSchema,
+  GLTFSceneSchema,
+  GLTFSkinSchema,
+  GLTFTextureSchema,
+  GLTFTextureInfoSchema,
+  GLTFTextureInfoMetadataSchema,
+  GLTFKHRBinarySchema,
+  GLTFKHRDracoMeshCompressionSchema,
+  GLTFKHRTextureBasisuSchema,
+  GLTFKHRMeshoptCompressionSchema,
+  GLTFEXTMeshoptCompressionSchema,
+  GLTFEXTTextureWebpSchema,
+  GLTFMSFTTextureDdsSchema,
+  GLTFShapeSchema,
+  GLTFBoundingVolumeSchema
+} from './lib/types/gltf-zod-schema';
+export {GLTFFormat, GLBFormat} from './gltf-format';
+
+// glTF loader/writer definition objects
+export {GLTFLoader} from './gltf-loader-types';
+export {GLTFSource, type GLTFSourceOptions} from './gltf-source';
+export {GLTFWriter} from './gltf-writer';
+export {
+  compressGLTFWithDraco,
+  type GLTFDracoWriterOptions
+} from './lib/encoders/encode-gltf-draco';
+
+// GLB Loader & Writer (for custom formats that want to leverage the GLB binary "envelope")
+export {GLBLoader} from './glb-loader-types';
+export {GLBWriter} from './glb-writer';
+
+// glTF Data Access Helper Class
+export {GLTFScenegraph} from './lib/api/gltf-scenegraph';
+export {
+  GLTFIterator,
+  type GLTFIteratorType,
+  type GLTFIteratorMetadata,
+  type GLTFIteratorReferences,
+  type GLTFAccessorReferences,
+  type GLTFAnimationReferences,
+  type GLTFAnimationChannelReferences,
+  type GLTFAnimationChannelTargetReferences,
+  type GLTFAnimationSamplerReferences,
+  type GLTFBufferViewReferences,
+  type GLTFBufferViewOwnerReferences,
+  type GLTFExternalAssetReferences,
+  type GLTFMaterialReferences,
+  type GLTFTextureInfoReferences,
+  type GLTFMeshReferences,
+  type GLTFMeshPrimitiveReferences,
+  type GLTFNodeReferences,
+  type GLTFSceneReferences,
+  type GLTFSkinReferences,
+  type GLTFTextureReferences
+} from './lib/api/gltf-iterator';
+export {getGLTFCullingShape, getGLTFNodeCullingShape} from './lib/api/gltf-culling';
+export {
+  convertGLTFV1ToGLTF2,
+  normalizeGLTFV1,
+  type GLTFV1NormalizationLog,
+  type GLTFV1NormalizationOptions,
+  type GLTFV1NormalizationReport
+} from './lib/api/normalize-gltf-v1';
+export {getMemoryUsageGLTF as _getMemoryUsageGLTF} from './lib/gltf-utils/gltf-utils';
+export {
+  findGLTFFileIndex,
+  resolveGLTFFile
+} from './lib/gltf-utils/resolve-gltf-file';
+
+export {
+  createExtStructuralMetadata,
+  type PropertyAttribute
+} from './lib/extensions/EXT_structural_metadata';
+export {createExtMeshFeatures} from './lib/extensions/EXT_mesh_features';
+
+export {
+  getGLTFInteractivity,
+  type GLTF_KHR_interactivity,
+  type GLTFInteractivityGraph,
+  type GLTFInteractivityNode,
+  type GLTFInteractivityDeclaration,
+  type GLTFInteractivityValue,
+  type GLTFInteractivitySocket,
+  type GLTFInteractivityProperty,
+  type GLTFInteractivityConfiguration,
+  type GLTFInteractivityDeclarationSocket,
+  type GLTFInteractivityType,
+  type GLTFInteractivityEventValue,
+  type GLTFInteractivityVariable,
+  type GLTFInteractivityEvent
+} from './lib/types/gltf-interactivity';
+
+// Permissive extension schemas retain unknown properties and do not insert defaults.
+export * from './lib/types/gltf-additional-extension-schemas';
+export * from './lib/types/gltf-audio-extension-schemas';
+export * from './lib/types/gltf-extension-schemas';
+export {
+  getMaterialVariantMappings,
+  getMeshInstances,
+  getXMPMetadata
+} from './lib/api/gltf-extension-data';
+export type {GLTFMaterialVariantData, GLTFMeshInstanceData} from './lib/api/gltf-extension-data';
+
+export {
+  getGLTFAccessor,
+  getGLTFAccessorValue,
+  setGLTFAccessorValue
+} from './lib/api/gltf-accessors';
+
+export type {GLTFAccessorReference} from './lib/api/gltf-accessors';

package/src/gltf/lib/api/append-gltf-v1-buffer-data.ts

@@ -0,0 +1,61 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {encodeArrayBufferToBase64, padToNBytes} from '@loaders.gl/core/loader-utils';
+import type {GLTFWithBuffers} from '../types/gltf-types';
+
+/** A validated payload and its deferred metadata update. */
+export type GLTFV1BufferAppend = {
+  /** Loaded source buffer to copy and extend. */
+  readonly bufferIndex: number;
+  /** Converted payload, including any element/column padding. */
+  readonly bytes: ArrayBuffer;
+  /** Optional vertex element stride. */
+  readonly byteStride?: number;
+  /** Optional WebGL vertex/index target. */
+  readonly target?: number;
+  /** Update consumers after the new view exists. */
+  readonly apply: (bufferViewIndex: number) => void;
+};
+
+/** Append validated data to aligned copies, preserving borrowed bytes and original views. */
+export function appendGLTFV1BufferData(gltf: GLTFWithBuffers, plans: GLTFV1BufferAppend[]): void {
+  if (!plans.length) return;
+  const groups = new Map<number, GLTFV1BufferAppend[]>();
+  for (const plan of plans) {
+    const group = groups.get(plan.bufferIndex) || [];
+    group.push(plan);
+    groups.set(plan.bufferIndex, group);
+  }
+  gltf.buffers = [...gltf.buffers];
+  gltf.json.bufferViews ||= [];
+  for (const [bufferIndex, group] of groups) {
+    const definition = gltf.json.buffers![bufferIndex];
+    const source = gltf.buffers[bufferIndex];
+    let byteOffset = padToNBytes(definition.byteLength, 4);
+    const byteLength =
+      byteOffset +
+      group.reduce((length, plan) => length + padToNBytes(plan.bytes.byteLength, 4), 0);
+    const arrayBuffer = new ArrayBuffer(byteLength);
+    const bytes = new Uint8Array(arrayBuffer);
+    bytes.set(new Uint8Array(source.arrayBuffer, source.byteOffset, definition.byteLength));
+    for (const plan of group) {
+      bytes.set(new Uint8Array(plan.bytes), byteOffset);
+      const bufferViewIndex = gltf.json.bufferViews.length;
+      gltf.json.bufferViews.push({
+        buffer: bufferIndex,
+        byteOffset,
+        byteLength: plan.bytes.byteLength,
+        ...(plan.byteStride === undefined ? {} : {byteStride: plan.byteStride}),
+        ...(plan.target === undefined ? {} : {target: plan.target})
+      });
+      plan.apply(bufferViewIndex);
+      byteOffset += padToNBytes(plan.bytes.byteLength, 4);
+    }
+    definition.byteLength = byteLength;
+    if (definition.uri !== undefined)
+      definition.uri = `data:application/octet-stream;base64,${encodeArrayBufferToBase64(arrayBuffer)}`;
+    gltf.buffers[bufferIndex] = {arrayBuffer, byteOffset: 0, byteLength};
+  }
+}