@haiyue/extensions 0.1.0

package/dist/gltf/GltfLoaderContract.d.ts

@@ -0,0 +1,249 @@
+import type { AssetHandle, AssetManager } from '@haiyue/engine/assets';
+import type { Entity, Geometry3D } from '@haiyue/engine';
+import type { Transform3D } from '@haiyue/engine/components';
+import { type GltfAnimationInterpolation, type GltfAsset } from './GltfSchema';
+import { type GltfExtensionAdapter, type GltfExtensionCapability } from './GltfExtensionAdapter';
+import type { GltfCompatibilityExtensionEntry, GltfCompatibilityReport, GltfPrimitiveCompatibilityInput } from './GltfCompatibilityReport';
+export type { GltfCompatibilityExtensionEntry, GltfCompatibilityIssue, GltfCompatibilityPerformanceSummary, GltfCompatibilityReport, GltfCompatibilityStatus, GltfPrimitiveBoundsCompatibilityEntry, GltfPrimitiveBoundsSupport, GltfPrimitiveUvSemanticCompatibilityEntry, GltfTextureCompatibilityEntry, GltfTextureMipmapSource, } from './GltfCompatibilityReport';
+export type { GltfAnimationInterpolation } from './GltfSchema';
+export type { GltfExtensionAdapter, GltfExtensionCapability, GltfExtensionSupport, } from './GltfExtensionAdapter';
+export interface LoadedGltfModel {
+    root: Entity;
+    animations: GltfAnimationInfo[];
+    animationClips: GltfAnimationClip[];
+    assetStats: GltfAssetStats;
+    loadMetrics: GltfLoadMetrics;
+    objectUrls: string[];
+    assetHandles: AssetHandle<unknown>[];
+    materialVariants: readonly string[];
+    warnings: readonly GltfLoadWarning[];
+    extensionReport: GltfExtensionReport;
+    compatibilityReport: GltfCompatibilityReport;
+}
+export type GltfExtensionReportEntry = GltfCompatibilityExtensionEntry;
+export interface GltfExtensionReport {
+    readonly fullySupported: boolean;
+    readonly entries: readonly GltfExtensionReportEntry[];
+}
+export declare const GLTF_EXTENSION_CAPABILITIES: Readonly<Record<string, GltfExtensionCapability>>;
+export interface GltfLoadWarning {
+    readonly code: 'W_GLTF_PARTIAL_OPTIONAL_EXTENSION' | 'W_GLTF_UNSUPPORTED_OPTIONAL_EXTENSION';
+    readonly message: string;
+    readonly extension: string;
+    readonly path: string;
+}
+export interface GltfAnimationInfo {
+    name: string;
+    duration: number;
+    channelCount: number;
+}
+export type GltfAnimationPath = 'translation' | 'rotation' | 'scale' | 'weights';
+export interface GltfAnimationTarget {
+    entity: Entity;
+    transform: Transform3D;
+    translation: [number, number, number];
+    rotation: [number, number, number, number];
+    scale: [number, number, number];
+    weights: number[];
+    morphPrimitives: GltfMorphPrimitiveRuntime[];
+}
+export interface GltfMorphPrimitiveRuntime {
+    geometry: Geometry3D;
+    basePositions: Float32Array;
+    baseNormals: Float32Array | null;
+    positionTargets: Float32Array[];
+    normalTargets: Float32Array[];
+}
+export interface GltfAnimationChannelRuntime {
+    target: GltfAnimationTarget;
+    path: GltfAnimationPath;
+    interpolation: GltfAnimationInterpolation;
+    valueSize: number;
+    input: Float32Array;
+    output: Float32Array;
+    sampleA: Float32Array;
+    sampleB: Float32Array;
+    sampleOut: Float32Array;
+    quatScratch: Float32Array;
+}
+export interface GltfAnimationClip {
+    name: string;
+    duration: number;
+    channels: GltfAnimationChannelRuntime[];
+    skinnedPrimitives: GltfSkinnedPrimitiveRuntime[];
+    stateCache: Map<GltfAnimationTarget, GltfAnimationTargetState>;
+    activeStates: GltfAnimationTargetState[];
+}
+export interface GltfAnimationTargetState {
+    target: GltfAnimationTarget;
+    translation: Float32Array;
+    rotation: Float32Array;
+    scale: Float32Array;
+    matrix: Float32Array<ArrayBuffer>;
+    active: boolean;
+}
+export interface GltfAssetStats {
+    meshCount: number;
+    primitiveCount: number;
+    materialCount: number;
+    textureCount: number;
+    imageCount: number;
+    animationCount: number;
+}
+export interface GltfLoadPhaseTimings {
+    readonly fetchMs: number;
+    readonly workerParseMs: number;
+    readonly dracoDecodeMs: number;
+    readonly geometryPreparationMs: number;
+    readonly instantiateMs: number;
+    readonly textureDecodeTranscodeUploadMs: number;
+    readonly totalMs: number;
+}
+export interface GltfLoadMetrics {
+    readonly timings: GltfLoadPhaseTimings;
+    readonly sourceBytes: number;
+    readonly decodedGeometryBytes: number;
+    readonly workerTransferBytes: number;
+    readonly workerTransferBufferCount: number;
+}
+export interface GltfLoadDiagnostics {
+    onDracoDecode?(durationMs: number, decodedBytes: number): void;
+}
+export interface LoadGltfOptions {
+    scene?: number | null;
+    baseColorFactor?: [number, number, number, number];
+    dracoDecoder?: DracoDecoderModule | Promise<DracoDecoderModule> | DracoDecoderFactory | null;
+    dracoDecoderConfig?: DracoDecoderConfig;
+    assetManager?: AssetManager | null;
+    assetWorker?: GltfAssetWorker | null;
+    signal?: AbortSignal;
+    onWarning?: (warning: GltfLoadWarning) => void;
+    diagnostics?: GltfLoadDiagnostics;
+    extensionAdapters?: readonly GltfExtensionAdapter[];
+}
+export interface GltfAssetWorker {
+    loadParsedAsset(src: string, options?: {
+        signal?: AbortSignal;
+        dracoDecoderConfig?: DracoDecoderConfig;
+    }): Promise<GltfParsedAsset>;
+}
+export interface GltfParsedAsset {
+    gltf: GltfAsset;
+    binaryChunk: ArrayBuffer | null;
+    buffers: ArrayBuffer[];
+    baseUrl: string;
+    geometryPayloads?: GltfGeometryPayloadMatrix;
+    metrics?: GltfParsedAssetMetrics;
+}
+export interface GltfParsedAssetMetrics {
+    readonly fetchMs: number;
+    readonly parseMs: number;
+    readonly workerParseMs: number;
+    readonly dracoDecodeMs: number;
+    readonly geometryPreparationMs: number;
+    readonly sourceBytes: number;
+    readonly workerTransferBytes: number;
+    readonly workerTransferBufferCount: number;
+}
+export declare function isGltfParsedAsset(value: unknown): value is GltfParsedAsset;
+export type GltfGeometryPayloadMatrix = Array<Array<GltfPrimitiveGeometryPayload | null>>;
+export interface GltfPrimitiveGeometryPayload {
+    positions: Float32Array;
+    indices?: Uint16Array | Uint32Array;
+    normals?: Float32Array;
+    textureCoordinates: Array<{
+        set: number;
+        data: Float32Array;
+    }>;
+    joints?: Uint16Array | Uint32Array;
+    weights?: Float32Array;
+    positionTargets: Float32Array[];
+    normalTargets: Float32Array[];
+}
+export interface DracoDecoderConfig {
+    scriptUrl?: string;
+    locateFile?: (path: string, prefix: string) => string;
+    wasmBinary?: ArrayBuffer | Uint8Array;
+}
+export interface DracoDecoderArray {
+    GetValue(index: number): number;
+    size(): number;
+}
+export interface DracoPointAttribute {
+    size(): number;
+}
+export interface DracoStatus {
+    ok(): boolean;
+    error_msg(): string;
+}
+export interface DracoMesh {
+    num_faces(): number;
+    num_points(): number;
+}
+export interface DracoDecoder {
+    DecodeBufferToMesh(buffer: unknown, mesh: DracoMesh): DracoStatus;
+    GetAttributeByUniqueId(mesh: DracoMesh, uniqueId: number): DracoPointAttribute;
+    GetAttributeFloatForAllPoints(mesh: DracoMesh, attribute: DracoPointAttribute, out: DracoDecoderArray): boolean;
+    GetAttributeUInt16ForAllPoints?(mesh: DracoMesh, attribute: DracoPointAttribute, out: DracoDecoderArray): boolean;
+    GetAttributeUInt32ForAllPoints?(mesh: DracoMesh, attribute: DracoPointAttribute, out: DracoDecoderArray): boolean;
+    GetFaceFromMesh(mesh: DracoMesh, faceIndex: number, out: DracoDecoderArray): boolean;
+}
+export interface DracoDecoderModule {
+    Decoder: new () => DracoDecoder;
+    DecoderBuffer: new () => {
+        Init(data: Uint8Array, byteLength: number): void;
+    };
+    Mesh: new () => DracoMesh;
+    DracoFloat32Array: new () => DracoDecoderArray;
+    DracoUInt16Array?: new () => DracoDecoderArray;
+    DracoUInt32Array?: new () => DracoDecoderArray;
+    DracoInt32Array: new () => DracoDecoderArray;
+    destroy(object: unknown): void;
+}
+export type DracoDecoderFactory = (config?: DracoDecoderConfig) => Promise<DracoDecoderModule> | DracoDecoderModule;
+export interface DracoPrimitiveGeometry {
+    positions: Float32Array;
+    normals?: Float32Array;
+    textureCoordinates: Array<{
+        set: number;
+        data: Float32Array;
+    }>;
+    joints?: Uint16Array | Uint32Array;
+    weights?: Float32Array;
+    indices: Uint16Array | Uint32Array;
+}
+export interface GltfLoadContext {
+    baseUrl: string;
+    assetIdentity: string;
+    objectUrls: string[];
+    imageSources: Map<number, string>;
+    sharedImageSources: boolean;
+    preloadedTextures: Map<string, GPUTexture>;
+    animationTargets: Map<number, GltfAnimationTarget>;
+    skinnedPrimitives: GltfSkinnedPrimitiveRuntime[];
+    pendingSkinnedPrimitives: GltfPendingSkinnedPrimitive[];
+    assetHandles: AssetHandle<unknown>[];
+    geometryPayloads?: GltfGeometryPayloadMatrix;
+    compatibilityPrimitives: GltfPrimitiveCompatibilityInput[];
+    extensionAdapters: readonly GltfExtensionAdapter[];
+}
+export interface GltfPendingSkinnedPrimitive {
+    skinIndex: number;
+    geometry: Geometry3D;
+    meshEntity: Entity;
+    joints: Uint16Array | Uint32Array;
+    weights: Float32Array;
+}
+export interface GltfSkinnedPrimitiveRuntime {
+    geometry: Geometry3D;
+    meshEntity: Entity;
+    jointTargets: Array<GltfAnimationTarget | null>;
+    inverseBindMatrices: Float32Array[];
+    jointMatrices: Float32Array;
+    inverseMeshWorldScratch: Float32Array;
+    jointMatrixScratch: Float32Array;
+    skinMatrixScratch: Float32Array;
+    lastMeshWorldVersion: number;
+    lastGeometryVersion: number;
+    lastJointWorldVersions: Int32Array;
+}

package/dist/gltf/GltfLoaderErrors.d.ts

@@ -0,0 +1,4 @@
+import { EngineError } from '@haiyue/engine';
+export declare function throwIfGltfLoadAborted(signal: AbortSignal | undefined): void;
+export declare function attachGltfSource(error: unknown, src: string): Error;
+export declare function gltfDataError(message: string, context?: Record<string, unknown>, path?: string, cause?: unknown): EngineError;

package/dist/gltf/GltfMaterialDescriptor.d.ts

@@ -0,0 +1,23 @@
+import { type MaterialDescriptor, type MaterialTextureSource, type PbrTextureMappingOptions } from '@haiyue/engine/material';
+import type { GltfAsset, GltfMaterial, GltfPrimitive } from './GltfSchema';
+import { type GltfExtensionAdapter, type GltfMaterialTextureBinding } from './GltfExtensionAdapter';
+export interface ResolvedGltfMaterialTexture {
+    readonly source: MaterialTextureSource;
+    readonly mapping: PbrTextureMappingOptions;
+    readonly sampler: GPUSamplerDescriptor | null;
+}
+export interface GltfMaterialDescriptorInput {
+    readonly gltf: GltfAsset;
+    readonly material: GltfMaterial | null;
+    readonly primitive: GltfPrimitive;
+    readonly materialPath: string;
+    readonly defaultBaseColor?: readonly [number, number, number, number];
+    readonly adapters: readonly GltfExtensionAdapter[];
+    readonly resolveTexture: (binding: GltfMaterialTextureBinding) => ResolvedGltfMaterialTexture;
+}
+/** Compiles glTF core material data and extension patches into one engine descriptor. */
+export declare function createGltfMaterialDescriptor(input: GltfMaterialDescriptorInput): Extract<MaterialDescriptor, {
+    shadingModel: 'pbr-metallic-roughness';
+}>;
+/** Shared semantic source for preload, UV planning, and descriptor compilation. */
+export declare function collectGltfMaterialTextureBindings(gltf: GltfAsset, material: GltfMaterial | null, primitive: GltfPrimitive, materialPath: string, adapters: readonly GltfExtensionAdapter[]): readonly GltfMaterialTextureBinding[];

package/dist/gltf/GltfMaterialEncoder.d.ts

@@ -0,0 +1,20 @@
+import type { MaterialTextureSource, PbrMaterial, PbrTextureSlot } from '@haiyue/engine/material';
+import type { GltfMaterial } from './GltfSchema';
+export interface EncodeGltfPbrMaterialOptions {
+    readonly name?: string;
+    /**
+     * Resolves an engine texture source to the texture index already allocated
+     * by the surrounding glTF/GLB exporter.
+     */
+    readonly resolveTextureIndex: (slot: PbrTextureSlot, source: MaterialTextureSource) => number;
+}
+export interface EncodedGltfPbrMaterial {
+    readonly material: GltfMaterial;
+    readonly extensionsUsed: readonly string[];
+}
+/**
+ * Encodes the standard glTF material portion without taking ownership of image,
+ * sampler, or buffer allocation. Scene exporters can share this codec instead
+ * of duplicating KHR material semantics.
+ */
+export declare function encodeGltfPbrMaterial(material: PbrMaterial, options: EncodeGltfPbrMaterialOptions): EncodedGltfPbrMaterial;

package/dist/gltf/GltfMaterialLoader.d.ts

@@ -0,0 +1,6 @@
+import type { PbrMaterial } from '@haiyue/engine';
+import { type GltfUvSemanticPlan } from './GltfUvSemanticPlanner';
+import type { GltfLoadContext, LoadGltfOptions } from './GltfLoaderContract';
+import type { GltfAsset, GltfPrimitive } from './GltfSchema';
+export declare function createGltfMaterial(gltf: GltfAsset, buffers: ArrayBuffer[], primitive: GltfPrimitive, options: LoadGltfOptions, context: GltfLoadContext, uvPlan: GltfUvSemanticPlan): Promise<PbrMaterial>;
+export declare function preloadGltfTextures(gltf: GltfAsset, buffers: ArrayBuffer[], options: LoadGltfOptions, context: GltfLoadContext): Promise<void>;

package/dist/gltf/GltfModelComponent.d.ts

@@ -0,0 +1,72 @@
+import { Component, Entity } from '@haiyue/engine';
+import type { GltfAnimationClip, GltfAnimationInfo, GltfAssetStats } from './GltfLoaderContract';
+import type { GltfCompatibilityReport } from './GltfCompatibilityReport';
+export interface GltfModelComponentOptions {
+    src?: string;
+    scene?: number;
+    autoLoad?: boolean;
+    clearPrevious?: boolean;
+    baseColorFactor?: [number, number, number, number];
+}
+export type GltfModelStatus = 'idle' | 'loading' | 'loaded' | 'error';
+export declare class GltfModelComponent extends Component {
+    static UniqueCheckType: number;
+    static UniqueSymbol: symbol;
+    static editor: {
+        fields: {
+            src: {
+                type: string;
+                label: string;
+                assetType: string;
+                placeholder: string;
+                validate: (value: unknown) => "Source is required." | null;
+            };
+            scene: {
+                type: string;
+                label: string;
+                min: number;
+                step: number;
+                visibleWhen: (component: GltfModelComponent) => boolean;
+            };
+            autoLoad: {
+                type: string;
+                label: string;
+            };
+            clearPrevious: {
+                type: string;
+                label: string;
+            };
+            baseColorFactor: {
+                type: string;
+                label: string;
+                rows: number;
+                validate: (value: unknown) => "Fallback Color must be [r, g, b, a]." | null;
+            };
+        };
+    };
+    private _src;
+    private _scene;
+    private _sourceKey;
+    private _sourceKeyDirty;
+    autoLoad: boolean;
+    clearPrevious: boolean;
+    baseColorFactor: [number, number, number, number];
+    status: GltfModelStatus;
+    error: string | null;
+    /** Runtime root inserted by GltfModelSystem. Do not serialize. */
+    runtimeRoot: Entity | null;
+    runtimeAnimations: GltfAnimationInfo[];
+    runtimeAnimationClips: GltfAnimationClip[];
+    runtimeAssetStats: GltfAssetStats | null;
+    runtimeCompatibilityReport: GltfCompatibilityReport | null;
+    runtimeMaterialVariants: readonly string[];
+    runtimeSourceKey: string;
+    loadingSourceKey: string;
+    constructor(options?: GltfModelComponentOptions);
+    get src(): string;
+    set src(value: string);
+    get scene(): number | null;
+    set scene(value: number | null);
+    get sourceKey(): string;
+    clone(): GltfModelComponent;
+}

package/dist/gltf/GltfModelSystem.d.ts

@@ -0,0 +1,37 @@
+import { type AssetJobPriority, type AssetManager } from '@haiyue/engine/assets';
+import { System, type World } from '@haiyue/engine';
+import type { DracoDecoderConfig, DracoDecoderFactory, DracoDecoderModule, GltfAssetWorker } from './GltfLoaderContract';
+export interface GltfModelSystemOptions {
+    priority?: number;
+    dracoDecoder?: DracoDecoderModule | Promise<DracoDecoderModule> | DracoDecoderFactory | null;
+    dracoDecoderConfig?: DracoDecoderConfig;
+    loadTimeoutMs?: number;
+    assetManager?: AssetManager | null;
+    assetWorker?: GltfAssetWorker | null;
+    assetPriority?: AssetJobPriority | number;
+}
+export declare class GltfModelSystem extends System {
+    private dracoDecoder;
+    private dracoDecoderConfig;
+    private loadTimeoutMs;
+    private assetManager;
+    private assetWorker;
+    private assetPriority;
+    private readonly componentModels;
+    private readonly pendingLoads;
+    private readonly failedLoads;
+    private readonly liveComponents;
+    constructor(options?: GltfModelSystemOptions);
+    update(world: World, _time: number, _delta: number): this;
+    destroy(): this;
+    private loadIntoEntity;
+    private createPendingLoad;
+    private clearPendingLoad;
+    private abortPendingLoad;
+    private trackModel;
+    private disposeModelsForComponent;
+    private releaseModelsNotIn;
+    private abortLoadsNotIn;
+    private releaseFailuresNotIn;
+    private disposeAllModels;
+}

package/dist/gltf/GltfPlugin.d.ts

@@ -0,0 +1,6 @@
+import type { EnginePlugin } from '@haiyue/engine/core';
+import { type GltfModelSystemOptions } from './GltfModelSystem';
+export interface GltfPluginOptions {
+    system?: GltfModelSystemOptions;
+}
+export declare function createGltfPlugin(options?: GltfPluginOptions): EnginePlugin;

package/dist/gltf/GltfSchema.d.ts

@@ -0,0 +1,225 @@
+export type GltfComponentType = 5120 | 5121 | 5122 | 5123 | 5125 | 5126;
+export type GltfAccessorType = 'SCALAR' | 'VEC2' | 'VEC3' | 'VEC4' | 'MAT2' | 'MAT3' | 'MAT4';
+export type GltfAnimationInterpolation = 'LINEAR' | 'STEP' | 'CUBICSPLINE';
+export interface GltfBuffer {
+    uri?: string;
+    byteLength?: number;
+}
+export interface GltfBufferView {
+    buffer: number;
+    byteOffset?: number;
+    byteLength: number;
+    byteStride?: number;
+}
+export interface GltfAccessor {
+    bufferView?: number;
+    byteOffset?: number;
+    componentType: GltfComponentType;
+    count: number;
+    type: GltfAccessorType;
+    normalized?: boolean;
+    min?: number[];
+    max?: number[];
+    sparse?: GltfAccessorSparse;
+}
+export interface GltfAccessorSparse {
+    count: number;
+    indices: {
+        bufferView: number;
+        byteOffset?: number;
+        componentType: 5121 | 5123 | 5125;
+    };
+    values: {
+        bufferView: number;
+        byteOffset?: number;
+    };
+}
+export interface GltfDracoMeshCompression {
+    bufferView: number;
+    attributes: Record<string, number>;
+}
+export interface GltfPrimitive {
+    attributes: Record<string, number>;
+    indices?: number;
+    material?: number;
+    mode?: number;
+    targets?: Array<Record<string, number>>;
+    extensions?: {
+        [extension: string]: unknown;
+        KHR_draco_mesh_compression?: GltfDracoMeshCompression;
+        KHR_materials_variants?: {
+            mappings: Array<{
+                material: number;
+                variants: number[];
+            }>;
+        };
+    };
+}
+export interface GltfMesh {
+    name?: string;
+    primitives: GltfPrimitive[];
+    weights?: number[];
+}
+export interface GltfNode {
+    name?: string;
+    mesh?: number;
+    skin?: number;
+    children?: number[];
+    matrix?: number[];
+    translation?: [number, number, number];
+    rotation?: [number, number, number, number];
+    scale?: [number, number, number];
+}
+export interface GltfScene {
+    nodes?: number[];
+}
+export interface GltfSkin {
+    inverseBindMatrices?: number;
+    joints: number[];
+    skeleton?: number;
+    name?: string;
+}
+export interface GltfMaterial {
+    name?: string;
+    doubleSided?: boolean;
+    pbrMetallicRoughness?: {
+        baseColorFactor?: [number, number, number, number];
+        baseColorTexture?: GltfTextureInfo;
+        metallicRoughnessTexture?: GltfTextureInfo;
+        metallicFactor?: number;
+        roughnessFactor?: number;
+    };
+    emissiveFactor?: [number, number, number];
+    emissiveTexture?: GltfTextureInfo;
+    normalTexture?: GltfTextureInfo & {
+        scale?: number;
+    };
+    occlusionTexture?: GltfTextureInfo & {
+        strength?: number;
+    };
+    alphaMode?: 'OPAQUE' | 'MASK' | 'BLEND';
+    alphaCutoff?: number;
+    extensions?: {
+        [extension: string]: unknown;
+        KHR_materials_clearcoat?: {
+            clearcoatFactor?: number;
+            clearcoatTexture?: GltfTextureInfo;
+            clearcoatRoughnessFactor?: number;
+            clearcoatRoughnessTexture?: GltfTextureInfo;
+            clearcoatNormalTexture?: GltfTextureInfo & {
+                scale?: number;
+            };
+        };
+        KHR_materials_anisotropy?: {
+            anisotropyStrength?: number;
+            anisotropyRotation?: number;
+            anisotropyTexture?: GltfTextureInfo;
+        };
+        KHR_materials_ior?: {
+            ior?: number;
+        };
+        KHR_materials_specular?: {
+            specularFactor?: number;
+            specularTexture?: GltfTextureInfo;
+            specularColorFactor?: [number, number, number];
+            specularColorTexture?: GltfTextureInfo;
+        };
+        KHR_materials_sheen?: {
+            sheenColorFactor?: [number, number, number];
+            sheenColorTexture?: GltfTextureInfo;
+            sheenRoughnessFactor?: number;
+            sheenRoughnessTexture?: GltfTextureInfo;
+        };
+        KHR_materials_transmission?: {
+            transmissionFactor?: number;
+            transmissionTexture?: GltfTextureInfo;
+        };
+        KHR_materials_volume?: {
+            thicknessFactor?: number;
+            thicknessTexture?: GltfTextureInfo;
+            attenuationDistance?: number;
+            attenuationColor?: [number, number, number];
+        };
+    };
+}
+export interface GltfTextureInfo {
+    index: number;
+    texCoord?: number;
+    extensions?: {
+        [extension: string]: unknown;
+        KHR_texture_transform?: GltfTextureTransform;
+    };
+}
+export interface GltfTextureTransform {
+    offset?: [number, number];
+    rotation?: number;
+    scale?: [number, number];
+    texCoord?: number;
+}
+export interface GltfImage {
+    uri?: string;
+    bufferView?: number;
+    mimeType?: string;
+}
+export interface GltfTexture {
+    sampler?: number;
+    source?: number;
+    extensions?: {
+        [extension: string]: unknown;
+        KHR_texture_basisu?: {
+            source: number;
+        };
+    };
+}
+export interface GltfSampler {
+    magFilter?: number;
+    minFilter?: number;
+    wrapS?: number;
+    wrapT?: number;
+}
+export interface GltfAnimation {
+    name?: string;
+    channels?: Array<{
+        sampler: number;
+        target: {
+            node?: number;
+            path?: string;
+        };
+    }>;
+    samplers?: Array<{
+        input: number;
+        output: number;
+        interpolation?: GltfAnimationInterpolation;
+    }>;
+}
+export interface GltfAsset {
+    asset: {
+        version: string;
+    };
+    extensionsUsed?: string[];
+    extensionsRequired?: string[];
+    buffers?: GltfBuffer[];
+    bufferViews?: GltfBufferView[];
+    accessors?: GltfAccessor[];
+    meshes?: GltfMesh[];
+    nodes?: GltfNode[];
+    scenes?: GltfScene[];
+    scene?: number;
+    skins?: GltfSkin[];
+    materials?: GltfMaterial[];
+    images?: GltfImage[];
+    textures?: GltfTexture[];
+    samplers?: GltfSampler[];
+    animations?: GltfAnimation[];
+    extensions?: {
+        [extension: string]: unknown;
+        KHR_materials_variants?: {
+            variants: Array<{
+                name: string;
+            }>;
+        };
+    };
+}
+/** Validates the untrusted JSON envelope before the loader follows references. */
+export declare function isGltfAsset(value: unknown): value is GltfAsset;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/gltf/GltfUvSemanticPlanner.d.ts

@@ -0,0 +1,33 @@
+import type { GltfAsset, GltfPrimitive } from './GltfSchema';
+import { type GltfExtensionAdapter } from './GltfExtensionAdapter';
+export declare const GLTF_UV_CHANNEL_CAPACITY: 2;
+export interface GltfUvSemanticMapping {
+    readonly semantic: string;
+    readonly set: number;
+    readonly channel: 0 | 1;
+}
+export interface GltfUvSemanticPlan {
+    readonly meshIndex: number;
+    readonly primitiveIndex: number;
+    readonly path: string;
+    readonly capacity: typeof GLTF_UV_CHANNEL_CAPACITY;
+    readonly availableSemantics: readonly string[];
+    readonly referencedSemantics: readonly string[];
+    readonly mappings: readonly GltfUvSemanticMapping[];
+}
+export interface GltfUvSemanticPlanFailure {
+    readonly code: 'GLTF_UV_SEMANTIC_MISSING' | 'GLTF_UV_CHANNEL_CAPACITY_EXCEEDED';
+    readonly message: string;
+    readonly path: string;
+    readonly context: Readonly<Record<string, unknown>>;
+}
+export type GltfUvSemanticPlanResult = {
+    readonly ok: true;
+    readonly plan: GltfUvSemanticPlan;
+} | {
+    readonly ok: false;
+    readonly failure: GltfUvSemanticPlanFailure;
+};
+export declare function planGltfUvSemantics(gltf: GltfAsset, primitive: GltfPrimitive, meshIndex: number, primitiveIndex: number, adapters?: readonly GltfExtensionAdapter[]): GltfUvSemanticPlanResult;
+export declare function getGltfUvChannel(plan: GltfUvSemanticPlan, semanticSet: number): 0 | 1 | null;
+export declare function parseTextureCoordinateSemantic(semantic: string): number | null;