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

package/src/gltf/lib/types/gltf-ext-structural-metadata-schema.ts

@@ -0,0 +1,387 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {GLTFTextureInfoMetadata} from './gltf-json-schema';
+
+/* eslint-disable camelcase */
+
+/**
+ * glTF extension that provides structural metadata about vertices, texels, and features in a glTF asset.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/glTF.EXT_structural_metadata.schema.json
+ */
+export type GLTF_EXT_structural_metadata_GLTF = {
+  /** An object defining classes and enums. */
+  schema?: GLTF_EXT_structural_metadata_Schema;
+  /** A uri to an external schema file. */
+  schemaUri?: string;
+  /** An array of property table definitions, which may be referenced by index. */
+  propertyTables?: GLTF_EXT_structural_metadata_PropertyTable[];
+  /** An array of property texture definitions, which may be referenced by index. */
+  propertyTextures?: GLTF_EXT_structural_metadata_PropertyTexture[];
+  /** "An array of property attribute definitions, which may be referenced by index. */
+  propertyAttributes?: GLTF_EXT_structural_metadata_PropertyAttribute[];
+  /** This is not part of the spec. GLTFLoader loads names of attributes crated into this property */
+  dataAttributeNames?: string[];
+};
+
+/**
+ * An object defining classes and enums.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/schema.schema.json
+ */
+export type GLTF_EXT_structural_metadata_Schema = {
+  /** Unique identifier for the schema. Schema IDs must be alphanumeric identifiers matching the regular expression `^[a-zA-Z_][a-zA-Z0-9_]*$`. */
+  id: string;
+  /** The name of the schema. */
+  name?: string;
+  /** The description of the schema. */
+  description?: string;
+  /** Application-specific version of the schema. */
+  version?: string;
+  /** A dictionary, where each key is a class ID and each value is an object defining the class. */
+  classes?: {
+    [key: string]: GLTF_EXT_structural_metadata_Class;
+  };
+  /** A dictionary, where each key is an enum ID and each value is an object defining the values for the enum. */
+  enums?: {
+    [key: string]: GLTF_EXT_structural_metadata_Enum;
+  };
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+};
+
+/**
+ * An object defining the values of an enum.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/enum.schema.json
+ */
+export type GLTF_EXT_structural_metadata_Enum = {
+  /** The name of the enum, e.g. for display purposes. */
+  name?: string;
+  /** The description of the enum. */
+  description?: string;
+  /**
+   * The type of the integer enum value.
+   * Default value is 'UINT16'
+   */
+  valueType?: 'INT8' | 'UINT8' | 'INT16' | 'UINT16' | 'INT32' | 'UINT32' | 'INT64' | 'UINT64';
+  /** An array of enum values. Duplicate names or duplicate integer values are not allowed. */
+  values: GLTF_EXT_structural_metadata_EnumValue[];
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+};
+
+/**
+ * An enum value.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/enum.value.schema.json
+ */
+export type GLTF_EXT_structural_metadata_EnumValue = {
+  /** The name of the enum value. */
+  name: string;
+  /** The description of the enum value. */
+  description?: string;
+  /** The integer enum value. */
+  value: number;
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+};
+
+/**
+ * A class containing a set of properties.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/class.schema.json
+ */
+export type GLTF_EXT_structural_metadata_Class = {
+  /** The name of the class, e.g. for display purposes. */
+  name?: string;
+  /** The description of the class. */
+  description?: string;
+  /**
+   * A dictionary, where each key is a property ID and each value is an object defining the property.
+   * Property IDs must be alphanumeric identifiers matching the regular expression `^[a-zA-Z_][a-zA-Z0-9_]*$`.
+   */
+  properties: {
+    [key: string]: GLTF_EXT_structural_metadata_ClassProperty;
+  };
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+};
+
+/**
+ * A class property.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/class.property.schema.json
+ */
+export type GLTF_EXT_structural_metadata_ClassProperty = {
+  /** The name of the property, e.g. for display purposes. */
+  name?: string;
+
+  /** The description of the property. */
+  description?: string;
+
+  /** The element type. */
+  type:
+    | 'SCALAR'
+    | 'VEC2'
+    | 'VEC3'
+    | 'VEC4'
+    | 'MAT2'
+    | 'MAT3'
+    | 'MAT4'
+    | 'BOOLEAN'
+    | 'STRING'
+    | 'ENUM'
+    | string;
+
+  /** The datatype of the element's components. Only applicable to `SCALAR`, `VECN`, and `MATN` types. */
+  componentType?:
+    | 'INT8'
+    | 'UINT8'
+    | 'INT16'
+    | 'UINT16'
+    | 'INT32'
+    | 'UINT32'
+    | 'INT64'
+    | 'UINT64'
+    | 'FLOAT32'
+    | 'FLOAT64'
+    | string;
+
+  /** Enum ID as declared in the `enums` dictionary. Required when `type` is `ENUM`. */
+  enumType?: string;
+
+  /**
+   * Whether the property is an array.
+   * When `count` is defined the property is a fixed-length array. Otherwise the property is a variable-length array.
+   */
+  array?: boolean;
+
+  /** The number of array elements. May only be defined when `array` is true. */
+  count?: number;
+
+  /**
+   * Specifies whether integer values are normalized.
+   * Only applicable to `SCALAR`, `VECN`, and `MATN` types with integer component types.
+   * For unsigned integer component types, values are normalized between `[0.0, 1.0]`.
+   * For signed integer component types, values are normalized between `[-1.0, 1.0]`.
+   * For all other component types, this property must be false.
+   */
+  normalized?: boolean;
+
+  /**
+   * An offset to apply to property values.
+   * Only applicable to `SCALAR`, `VECN`, and `MATN` types when the component type is `FLOAT32` or `FLOAT64`, or when the property is `normalized`.
+   */
+  offset?: number | number[];
+
+  /**
+   * A scale to apply to property values.
+   * Only applicable to `SCALAR`, `VECN`, and `MATN` types when the component type is `FLOAT32` or `FLOAT64`, or when the property is `normalized`.
+   */
+  scale?: number | number[];
+
+  /**
+   * Maximum allowed value for the property.
+   * Only applicable to `SCALAR`, `VECN`, and `MATN` types.
+   * This is the maximum of all property values, after the transforms based on the `normalized`, `offset`, and `scale` properties have been applied.
+   */
+  max?: number | number[];
+
+  /**
+   * Minimum allowed value for the property.
+   * Only applicable to `SCALAR`, `VECN`, and `MATN` types.
+   * This is the minimum of all property values, after the transforms based on the `normalized`, `offset`, and `scale` properties have been applied.
+   */
+  min?: number | number[];
+
+  default?: boolean | number | string | number[];
+  /**
+   * If required, the property must be present in every entity conforming to the class.
+   * If not required, individual entities may include `noData` values, or the entire property may be omitted.
+   * As a result, `noData` has no effect on a required property.
+   * Client implementations may use required properties to make performance optimizations.
+   * Default value is false.
+   */
+  required?: boolean;
+
+  /**
+   * A `noData` value represents missing data — also known as a sentinel value — wherever it appears.
+   * `BOOLEAN` properties may not specify `noData` values.
+   * This is given as the plain property value, without the transforms from the `normalized`, `offset`, and `scale` properties.
+   * Must not be defined if `required` is true.
+   */
+  noData?: number | string | number[] | string[];
+
+  /**
+   * An identifier that describes how this property should be interpreted.
+   * The semantic cannot be used by other properties in the class.
+   */
+  semantic?: string;
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+};
+
+/**
+ * Properties conforming to a class, organized as property values stored in binary columnar arrays.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/propertyTable.schema.json
+ */
+export type GLTF_EXT_structural_metadata_PropertyTable = {
+  /** The name of the property table, e.g. for display purposes. */
+  name?: string;
+  /** The class that property values conform to. The value must be a class ID declared in the `classes` dictionary. */
+  class: string;
+  /** The number of elements in each property array. */
+  count: number;
+  /**
+   * A dictionary, where each key corresponds to a property ID in the class' `properties` dictionary
+   * and each value is an object describing where property values are stored.
+   * Required properties must be included in this dictionary.
+   */
+  properties?: {
+    [key: string]: GLTF_EXT_structural_metadata_PropertyTable_Property;
+  };
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+};
+
+/**
+ * An array of binary property values.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/propertyTable.property.schema.json
+ */
+export type GLTF_EXT_structural_metadata_PropertyTable_Property = {
+  /**
+   * The index of the buffer view containing property values.
+   * The data type of property values is determined by the property definition:
+   * When `type` is `BOOLEAN` values are packed into a bitstream.
+   * When `type` is `STRING` values are stored as byte sequences and decoded as UTF-8 strings.
+   * When `type` is `SCALAR`, `VECN`, or `MATN` the values are stored as the provided `componentType`
+   * and the buffer view `byteOffset` must be aligned to a multiple of the `componentType` size.
+   * When `type` is `ENUM` values are stored as the enum's `valueType`
+   * and the buffer view `byteOffset` must be aligned to a multiple of the `valueType` size.
+   * Each enum value in the array must match one of the allowed values in the enum definition.
+   * `arrayOffsets` is required for variable-length arrays and `stringOffsets` is required for strings (for variable-length arrays of strings, both are required).
+   */
+  values: number;
+  /**
+   * The index of the buffer view containing offsets for variable-length arrays.
+   * The number of offsets is equal to the property table `count` plus one.
+   * The offsets represent the start positions of each array, with the last offset representing the position after the last array.
+   * The array length is computed using the difference between the subsequent offset and the current offset.
+   * If `type` is `STRING` the offsets index into the string offsets array (stored in `stringOffsets`), otherwise they index into the property array (stored in `values`).
+   * The data type of these offsets is determined by `arrayOffsetType`.
+   * The buffer view `byteOffset` must be aligned to a multiple of the `arrayOffsetType` size.
+   */
+  arrayOffsets?: number;
+  /**
+   * The index of the buffer view containing offsets for strings.
+   * The number of offsets is equal to the number of string elements plus one.
+   * The offsets represent the byte offsets of each string in the property array (stored in `values`), with the last offset representing the byte offset after the last string.
+   * The string byte length is computed using the difference between the subsequent offset and the current offset.
+   * The data type of these offsets is determined by `stringOffsetType`.
+   * The buffer view `byteOffset` must be aligned to a multiple of the `stringOffsetType` size.
+   */
+  stringOffsets?: number;
+  /**
+   * The type of values in `arrayOffsets`.
+   * Default value is 'UINT32'
+   */
+  arrayOffsetType?: 'UINT8' | 'UINT16' | 'UINT32' | 'UINT64' | string;
+
+  /**
+   * The type of values in `stringOffsets`.
+   * Default value is 'UINT32'
+   */
+  stringOffsetType?: 'UINT8' | 'UINT16' | 'UINT32' | 'UINT64' | string;
+  /**
+   * An offset to apply to property values.
+   * Only applicable when the component type is `FLOAT32` or `FLOAT64`, or when the property is `normalized`.
+   * Overrides the class property's `offset` if both are defined.
+   */
+  offset?: number | number[];
+  /**
+   * A scale to apply to property values.
+   * Only applicable when the component type is `FLOAT32` or `FLOAT64`, or when the property is `normalized`.
+   * Overrides the class property's `scale` if both are defined.
+   */
+  scale?: number | number[];
+  /**
+   * Maximum value present in the property values.
+   * Only applicable to `SCALAR`, `VECN`, and `MATN` types.
+   * This is the maximum of all property values, after the transforms based on the `normalized`, `offset`, and `scale` properties have been applied.
+   */
+  max?: number | number[];
+  /**
+   * Minimum value present in the property values.
+   * Only applicable to `SCALAR`, `VECN`, and `MATN` types.
+   * This is the minimum of all property values, after the transforms based on the `normalized`, `offset`, and `scale` properties have been applied.
+   */
+  min?: number | number[];
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+  /** This is not part of the spec. GLTFLoader loads transformed feature-table data into this property. */
+  data?: unknown;
+  /**
+   * This is not part of the spec. GLTFLoader preserves the decoded values before normalized, scale,
+   * and offset transforms so consumers can apply `noData` sentinels in the source value domain.
+   */
+  rawData?: unknown;
+};
+
+/**
+ * Properties conforming to a class, organized as property values stored in textures.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/propertyTexture.schema.json
+ */
+export type GLTF_EXT_structural_metadata_PropertyTexture = {
+  /** The name of the property texture, e.g. for display purposes. */
+  name?: string;
+  /** The class that property values conform to. The value must be a class ID declared in the `classes` dictionary. */
+  class: string;
+  /**
+   * A dictionary, where each key corresponds to a property ID in the class' `properties` dictionary
+   * and each value is an object describing where property values are stored.
+   * Required properties must be included in this dictionary.
+   *
+   * https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata
+   * Each property that is defined in the propertyTexture object extends the glTF textureInfo object.
+   * The texCoord specifies a texture coordinate set in the referring primitive.
+   * The index is the index of the glTF texture object that stores the actual data. Additionally,
+   * each property specifies an array of channels, which are the indices of the texture channels providing data for the respective property.
+   * Channels of an RGBA texture are numbered 0..3 respectively.
+   */
+  properties?: {
+    [key: string]: GLTFTextureInfoMetadata;
+  };
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+};
+
+/**
+ * Properties conforming to a class, organized as property values stored in attributes.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/propertyAttribute.schema.json
+ */
+export type GLTF_EXT_structural_metadata_PropertyAttribute = {
+  /** The name of the property attribute, e.g. for display purposes. */
+  name?: string;
+  /** The class that property values conform to. The value must be a class ID declared in the `classes` dictionary. */
+  class: string;
+  /**
+   * "A dictionary, where each key corresponds to a property ID in the class' `properties` dictionary
+   * and each value is an object describing where property values are stored.
+   * Required properties must be included in this dictionary.
+   */
+  properties?: {
+    [key: string]: unknown;
+  };
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+};
+
+/**
+ * Structural metadata about a glTF primitive.
+ * @see https://github.com/CesiumGS/glTF/blob/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata/schema/mesh.primitive.EXT_structural_metadata.schema.json
+ */
+export type GLTF_EXT_structural_metadata_Primitive = {
+  /** An array of indexes of property textures in the root `EXT_structural_metadata` object. */
+  propertyTextures?: number[];
+  /** An array of indexes of property attributes in the root `EXT_structural_metadata` object. */
+  propertyAttributes?: number[];
+  extensions?: Record<string, unknown>;
+  extras?: unknown;
+};

package/src/gltf/lib/types/gltf-ext-vector-voxel-schema.ts

@@ -0,0 +1,49 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+/** Polygon topology metadata used by vector/CAD glTF primitives. */
+export type GLTF_EXT_mesh_polygon = {
+  /** Number of polygons encoded by the primitive. */
+  count: number;
+  /** Accessor containing loop vertex indices. */
+  loopIndices: number;
+  /** Accessor containing the first loop offset for each polygon. */
+  loopIndicesOffsets: number;
+  /** Accessor containing the first triangle offset for each polygon. */
+  indicesOffsets: number;
+};
+
+/** Primitive-restart groups used by vector and CAD line/edge data. */
+export type GLTF_EXT_mesh_primitive_restart = {
+  /** Groups that share an index accessor and restart value. */
+  primitiveGroups: Array<Record<string, unknown>>;
+};
+
+/** Edge visibility bitfield declaration preserved for vector/CAD renderers. */
+export type GLTF_EXT_mesh_primitive_edge_visibility = {
+  /** Accessor containing two-bit visibility values for triangle edges. */
+  visibility: number;
+  /** Optional edge material index. */
+  material?: number;
+};
+
+/** Voxel primitive declaration. Values remain lazy and reference glTF accessors. */
+export type GLTF_EXT_primitive_voxels = {
+  /** Index of the shape declaration in KHR_implicit_shapes. */
+  shape: number;
+  /** Voxel-grid dimensions in shape space. */
+  dimensions: number[];
+  /** Optional padding around the voxel grid. */
+  padding?: Record<string, number>;
+  /** Per-attribute no-data sentinel values. */
+  noData?: Record<string, number[]>;
+};
+
+/** Normalized, lazy descriptor for one voxel primitive. */
+export type GLTFVoxelPrimitive = {
+  meshIndex: number;
+  primitiveIndex: number;
+  attributes: Readonly<Record<string, number>>;
+  extension: GLTF_EXT_primitive_voxels;
+};

package/src/gltf/lib/types/gltf-extension-schemas.ts

@@ -0,0 +1,87 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+import {z} from 'zod';
+import {
+  GLTFKHRMaterialsVariantsSchema,
+  GLTFKHRMaterialsVariantsPrimitiveSchema,
+  GLTFEXTMeshGPUInstancingSchema,
+  GLTFKHRAnimationPointerSchema,
+  GLTFKHRNodeVisibilitySchema,
+  GLTFKHRNodeSelectabilitySchema,
+  GLTFKHRNodeHoverabilitySchema,
+  GLTFKHRXMPJSONLDSchema,
+  GLTFKHRXMPJSONLDReferenceSchema
+} from './gltf-additional-extension-schemas';
+import {
+  GLTFKHRAudioEmitterExtensionSchema,
+  GLTFKHRAudioAttachmentSchema,
+  GLTFMPEGAudioSpatialSchema
+} from './gltf-audio-extension-schemas';
+
+/** Permissive extension map for objects that can reference an XMP packet. */
+export const GLTFPropertyExtensionsSchema = z.looseObject({
+  /** Shared XMP packet reference. */
+  KHR_xmp_json_ld: GLTFKHRXMPJSONLDReferenceSchema.optional()
+});
+
+/** Permissive document-level extension map. */
+export const GLTFRootExtensionsSchema = z.looseObject({
+  /** Shared material variant declarations. */
+  KHR_materials_variants: GLTFKHRMaterialsVariantsSchema.optional(),
+  /** Shared XMP metadata packets. */
+  KHR_xmp_json_ld: GLTFKHRXMPJSONLDSchema.optional(),
+  /** Shared KHR audio resources, sources and emitters. */
+  KHR_audio_emitter: GLTFKHRAudioEmitterExtensionSchema.optional(),
+  /** Root-level MPEG spatial audio declaration. */
+  MPEG_audio_spatial: GLTFMPEGAudioSpatialSchema.optional()
+});
+
+/** Permissive node-level extension map. */
+export const GLTFNodeExtensionsSchema = GLTFPropertyExtensionsSchema.extend({
+  /** Accessors defining GPU instance attributes. */
+  EXT_mesh_gpu_instancing: GLTFEXTMeshGPUInstancingSchema.optional(),
+  /** Local visibility affecting the entire subtree. */
+  KHR_node_visibility: GLTFKHRNodeVisibilitySchema.optional(),
+  /** Local selectability affecting the entire subtree. */
+  KHR_node_selectability: GLTFKHRNodeSelectabilitySchema.optional(),
+  /** Local hoverability affecting the entire subtree. */
+  KHR_node_hoverability: GLTFKHRNodeHoverabilitySchema.optional(),
+  /** Attached KHR audio emitters. */
+  KHR_audio_emitter: GLTFKHRAudioAttachmentSchema.optional(),
+  /** Node-level MPEG spatial audio declaration. */
+  MPEG_audio_spatial: GLTFMPEGAudioSpatialSchema.optional()
+});
+
+/** Permissive scene-level extension map. */
+export const GLTFSceneExtensionsSchema = GLTFPropertyExtensionsSchema.extend({
+  /** Attached global KHR audio emitters. */
+  KHR_audio_emitter: GLTFKHRAudioAttachmentSchema.optional()
+});
+
+/** Permissive mesh-primitive extension map. */
+export const GLTFMeshPrimitiveExtensionsSchema = z.looseObject({
+  /** Material-to-variant mappings for this primitive. */
+  KHR_materials_variants: GLTFKHRMaterialsVariantsPrimitiveSchema.optional()
+});
+
+/** Permissive animation-target extension map. */
+export const GLTFAnimationTargetExtensionsSchema = z.looseObject({
+  /** JSON Pointer identifying the animated property. */
+  KHR_animation_pointer: GLTFKHRAnimationPointerSchema.optional()
+});
+
+/** Typed document-level extensions with arbitrary additional extension names. */
+export type GLTFRootExtensions = z.infer<typeof GLTFRootExtensionsSchema>;
+/** Typed node-level extensions with arbitrary additional extension names. */
+export type GLTFNodeExtensions = z.infer<typeof GLTFNodeExtensionsSchema>;
+/** Typed scene-level extensions with arbitrary additional extension names. */
+export type GLTFSceneExtensions = z.infer<typeof GLTFSceneExtensionsSchema>;
+/** Typed primitive-level extensions with arbitrary additional extension names. */
+export type GLTFMeshPrimitiveExtensions = z.infer<typeof GLTFMeshPrimitiveExtensionsSchema>;
+/** Typed animation-target extensions with arbitrary additional extension names. */
+export type GLTFAnimationTargetExtensions = z.infer<typeof GLTFAnimationTargetExtensionsSchema>;
+
+/** Typed shared metadata extensions with arbitrary additional extension names. */
+export type GLTFPropertyExtensions = z.infer<typeof GLTFPropertyExtensionsSchema>;

package/src/gltf/lib/types/gltf-interactivity.ts

@@ -0,0 +1,168 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTF} from './gltf-json-schema';
+
+/** Metadata shared by KHR_interactivity schema objects. */
+export type GLTFInteractivityProperty = {
+  /** Extension-specific data. */
+  extensions?: Record<string, unknown>;
+  /** Application-specific data. */
+  extras?: unknown;
+};
+
+/** An input value socket: a connected output or a typed inline/default value. */
+export type GLTFInteractivityValue = GLTFInteractivityProperty &
+  (
+    | {
+        /** Source node index in this graph. */
+        node: number;
+        /** Source output socket identifier. */
+        socket?: string;
+        /** Optional type index for the connected socket. */
+        type?: number;
+        /** Connected sockets cannot also have inline values. */
+        value?: never;
+      }
+    | {
+        /** Inline sockets do not reference nodes. */
+        node?: never;
+        /** Inline sockets do not reference output sockets. */
+        socket?: never;
+        /** Type index in this graph. */
+        type: number;
+        /** Components of the inline value; omission uses the type's default. */
+        value?: unknown[];
+      }
+  );
+
+/** An output flow connection to another node. */
+export type GLTFInteractivitySocket = GLTFInteractivityProperty & {
+  /** Destination node index in this graph. */
+  node: number;
+  /** Destination input flow socket; defaults to `in`. */
+  socket?: string;
+};
+
+/** Static configuration for an operation. */
+export type GLTFInteractivityConfiguration = GLTFInteractivityProperty & {
+  /** Configuration components, interpreted by the operation. */
+  value: unknown[];
+};
+
+/** An operation instance in a behavior graph. */
+export type GLTFInteractivityNode = GLTFInteractivityProperty & {
+  /** Index of the operation declaration in this graph. */
+  declaration: number;
+  /** Input value sockets keyed by identifier. */
+  values?: Record<string, GLTFInteractivityValue>;
+  /** Output flow connections keyed by identifier. */
+  flows?: Record<string, GLTFInteractivitySocket>;
+  /** Static configuration keyed by identifier. */
+  configuration?: Record<string, GLTFInteractivityConfiguration>;
+};
+
+/** A value socket declared by an extension-defined operation. */
+export type GLTFInteractivityDeclarationSocket = GLTFInteractivityProperty & {
+  /** Type index in this graph. */
+  type: number;
+};
+
+/** An operation declaration; custom socket declarations require an extension. */
+export type GLTFInteractivityDeclaration = GLTFInteractivityProperty & {
+  /** Operation identifier. */
+  op: string;
+} & (
+    | {
+        /** Extension defining the operation. */
+        extension: string;
+        /** Extension-defined input value sockets. */
+        inputValueSockets?: Record<string, GLTFInteractivityDeclarationSocket>;
+        /** Extension-defined output value sockets. */
+        outputValueSockets?: Record<string, GLTFInteractivityDeclarationSocket>;
+      }
+    | {
+        /** Built-in operations do not declare an extension. */
+        extension?: never;
+        /** Built-in input sockets are defined by the specification. */
+        inputValueSockets?: never;
+        /** Built-in output sockets are defined by the specification. */
+        outputValueSockets?: never;
+      }
+  );
+
+/** A graph-local value type. */
+export type GLTFInteractivityType = GLTFInteractivityProperty & {
+  /** Standard type signature; extension-defined types use `custom`. */
+  signature:
+    | 'bool'
+    | 'float'
+    | 'float2'
+    | 'float3'
+    | 'float4'
+    | 'float2x2'
+    | 'float3x3'
+    | 'float4x4'
+    | 'int'
+    | 'ref'
+    | 'custom';
+};
+
+/** A typed event value socket with an optional initial value. */
+export type GLTFInteractivityEventValue = GLTFInteractivityProperty & {
+  /** Type index in this graph. */
+  type: number;
+  /** Initial components; omission uses the type's default. */
+  value?: unknown[];
+};
+
+/** A graph-local variable. */
+export type GLTFInteractivityVariable = GLTFInteractivityEventValue & {
+  /** Optional user-defined name. */
+  name?: string;
+};
+
+/** A custom event; events without an id are internal to the graph. */
+export type GLTFInteractivityEvent = GLTFInteractivityProperty & {
+  /** Optional external event identifier. */
+  id?: string;
+  /** Optional user-defined name. */
+  name?: string;
+  /** Event payload sockets keyed by identifier. */
+  values?: Record<string, GLTFInteractivityEventValue>;
+};
+
+/** A behavior graph with graph-local indices. */
+export type GLTFInteractivityGraph = GLTFInteractivityProperty & {
+  /** Operation declarations referenced by nodes. */
+  declarations?: GLTFInteractivityDeclaration[];
+  /** Operation instances; requires declarations when present. */
+  nodes?: GLTFInteractivityNode[];
+  /** Value types referenced by sockets and variables. */
+  types?: GLTFInteractivityType[];
+  /** Graph variables; requires types when present. */
+  variables?: GLTFInteractivityVariable[];
+  /** Custom event definitions. */
+  events?: GLTFInteractivityEvent[];
+  /** Optional user-defined name. */
+  name?: string;
+};
+
+/** KHR_interactivity root extension; graph execution belongs to the rendering runtime. */
+export type GLTF_KHR_interactivity = GLTFInteractivityProperty & {
+  /** Default behavior graph index; defaults to zero. */
+  graph?: number;
+  /** Available behavior graphs. */
+  graphs: GLTFInteractivityGraph[];
+};
+
+/**
+ * Read the raw extension from glTF JSON or a GLTFLoader result.
+ * Returns the original object without validation, cloning, or default expansion.
+ */
+export function getGLTFInteractivity(gltf: GLTF | {json: GLTF}): GLTF_KHR_interactivity | null {
+  // GLTF permits arbitrary properties, so an `in` check cannot narrow this union.
+  const json = ('asset' in gltf ? gltf : gltf.json) as GLTF;
+  return (json.extensions?.KHR_interactivity as GLTF_KHR_interactivity | undefined) ?? null;
+}