@series-inc/stowkit-cli 0.1.0

package/dist/encoders/skinned-mesh-builder.d.ts

@@ -0,0 +1,7 @@
+import type { ImportedMesh } from './interfaces.js';
+import type { SkinnedMeshMetadata } from '../core/types.js';
+export interface SkinnedMeshBuildResult {
+    data: Uint8Array;
+    metadata: SkinnedMeshMetadata;
+}
+export declare function buildSkinnedMeshData(imported: ImportedMesh, scaleFactor?: number): SkinnedMeshBuildResult;

package/dist/encoders/skinned-mesh-builder.js

@@ -0,0 +1,135 @@
+import { SKINNED_VERTEX_STRIDE, VERTEX_WEIGHTS_SIZE } from '../core/constants.js';
+export function buildSkinnedMeshData(imported, scaleFactor = 1.0) {
+    const geometries = [];
+    let totalDataSize = 0;
+    for (const sub of imported.subMeshes) {
+        const vertCount = sub.positions.length / 3;
+        const vertexBufSize = vertCount * SKINNED_VERTEX_STRIDE;
+        const indexBufSize = sub.indices.length * 4;
+        const weightsBufSize = vertCount * VERTEX_WEIGHTS_SIZE;
+        geometries.push({
+            vertexCount: vertCount,
+            indexCount: sub.indices.length,
+            hasNormals: sub.normals ? 1 : 0,
+            hasUvs: sub.uvs ? 1 : 0,
+            vertexBufferOffset: totalDataSize,
+            vertexBufferSize: vertexBufSize,
+            indexBufferOffset: totalDataSize + vertexBufSize,
+            indexBufferSize: indexBufSize,
+            weightsOffset: totalDataSize + vertexBufSize + indexBufSize,
+            weightsSize: weightsBufSize,
+            materialIndex: sub.materialIndex,
+            _padding: 0,
+        });
+        totalDataSize += vertexBufSize + indexBufSize + weightsBufSize;
+    }
+    const data = new Uint8Array(totalDataSize);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    for (const sub of imported.subMeshes) {
+        const vertCount = sub.positions.length / 3;
+        for (let v = 0; v < vertCount; v++) {
+            view.setFloat32(offset, sub.positions[v * 3] * scaleFactor, true);
+            offset += 4;
+            view.setFloat32(offset, sub.positions[v * 3 + 1] * scaleFactor, true);
+            offset += 4;
+            view.setFloat32(offset, sub.positions[v * 3 + 2] * scaleFactor, true);
+            offset += 4;
+            if (sub.normals) {
+                view.setFloat32(offset, sub.normals[v * 3], true);
+                offset += 4;
+                view.setFloat32(offset, sub.normals[v * 3 + 1], true);
+                offset += 4;
+                view.setFloat32(offset, sub.normals[v * 3 + 2], true);
+                offset += 4;
+            }
+            else {
+                view.setFloat32(offset, 0, true);
+                offset += 4;
+                view.setFloat32(offset, 1, true);
+                offset += 4;
+                view.setFloat32(offset, 0, true);
+                offset += 4;
+            }
+            if (sub.uvs) {
+                view.setFloat32(offset, sub.uvs[v * 2], true);
+                offset += 4;
+                view.setFloat32(offset, sub.uvs[v * 2 + 1], true);
+                offset += 4;
+            }
+            else {
+                view.setFloat32(offset, 0, true);
+                offset += 4;
+                view.setFloat32(offset, 0, true);
+                offset += 4;
+            }
+        }
+        for (let i = 0; i < sub.indices.length; i++) {
+            view.setUint32(offset, sub.indices[i], true);
+            offset += 4;
+        }
+        for (let v = 0; v < vertCount; v++) {
+            if (sub.skinData) {
+                for (let w = 0; w < 4; w++) {
+                    view.setUint32(offset, sub.skinData.boneIndices[v * 4 + w], true);
+                    offset += 4;
+                }
+                for (let w = 0; w < 4; w++) {
+                    view.setFloat32(offset, sub.skinData.boneWeights[v * 4 + w], true);
+                    offset += 4;
+                }
+            }
+            else {
+                for (let w = 0; w < 8; w++) {
+                    view.setUint32(offset, 0, true);
+                    offset += 4;
+                }
+            }
+        }
+    }
+    const materials = imported.materials.map((m) => ({
+        name: m.name,
+        schemaId: '',
+        propertyCount: 0,
+        properties: [],
+    }));
+    const meshIndicesFlat = [];
+    const sceneNodes = imported.nodes.map((n) => {
+        const firstMeshIndex = meshIndicesFlat.length;
+        meshIndicesFlat.push(...n.meshIndices);
+        return {
+            name: n.name,
+            parentIndex: n.parentIndex,
+            position: [
+                n.position[0] * scaleFactor,
+                n.position[1] * scaleFactor,
+                n.position[2] * scaleFactor,
+            ],
+            rotation: n.rotation,
+            scale: n.scale,
+            meshCount: n.meshIndices.length,
+            firstMeshIndex,
+        };
+    });
+    const bones = (imported.bones ?? []).map((b) => {
+        const src = b.offsetMatrix ?? [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+        const mat = [...src];
+        mat[12] *= scaleFactor;
+        mat[13] *= scaleFactor;
+        mat[14] *= scaleFactor;
+        return { name: b.name, parentIndex: b.parentIndex, offsetMatrix: mat };
+    });
+    const metadata = {
+        meshGeometryCount: geometries.length,
+        materialCount: materials.length,
+        nodeCount: sceneNodes.length,
+        boneCount: bones.length,
+        stringId: '',
+        geometries,
+        materials,
+        nodes: sceneNodes,
+        meshIndices: meshIndicesFlat,
+        bones,
+    };
+    return { data, metadata };
+}

package/dist/format/metadata.d.ts

@@ -0,0 +1,18 @@
+import type { TextureMetadata, AudioMetadata, MeshMetadata, MaterialSchemaMetadata, AnimationClipMetadata, SkinnedMeshMetadata } from '../core/types.js';
+export declare function serializeTextureMetadata(meta: TextureMetadata): Uint8Array;
+export declare function deserializeTextureMetadata(data: Uint8Array): TextureMetadata;
+export declare function serializeAudioMetadata(meta: AudioMetadata): Uint8Array;
+export declare function deserializeAudioMetadata(data: Uint8Array): AudioMetadata;
+export declare function serializeMaterialSchemaMetadata(meta: MaterialSchemaMetadata): Uint8Array;
+export declare function deserializeMaterialSchemaMetadata(data: Uint8Array): MaterialSchemaMetadata;
+export declare function serializeMeshMetadata(meta: MeshMetadata): Uint8Array;
+export declare function deserializeMeshMetadata(data: Uint8Array): MeshMetadata;
+export declare function serializeAnimationClipMetadata(meta: AnimationClipMetadata): Uint8Array;
+export declare function deserializeAnimationClipMetadata(data: Uint8Array): AnimationClipMetadata;
+export declare function serializeSkinnedMeshMetadata(meta: SkinnedMeshMetadata): Uint8Array;
+export declare function deserializeSkinnedMeshMetadata(data: Uint8Array): SkinnedMeshMetadata;
+export declare function wrapMetadata(assetMetadata: Uint8Array, tags: string[]): Uint8Array;
+export declare function unwrapMetadata(wrapped: Uint8Array): {
+    tags: string[];
+    assetMetadata: Uint8Array;
+};

package/dist/format/metadata.js

@@ -0,0 +1,381 @@
+import { BinaryReader, BinaryWriter } from '../core/binary.js';
+import { TEXTURE_METADATA_SIZE, AUDIO_METADATA_SIZE, STRING_ID_SIZE, MESH_GEOMETRY_INFO_SIZE, SCENE_NODE_SIZE, MATERIAL_DATA_FIXED_SIZE, MATERIAL_PROPERTY_VALUE_SIZE, MESH_METADATA_FIXED_SIZE, NODE_NAME_SIZE, MATERIAL_NAME_SIZE, MATERIAL_SCHEMA_ID_SIZE, MATERIAL_FIELD_NAME_SIZE, MATERIAL_SCHEMA_NAME_SIZE, MATERIAL_SCHEMA_DEFAULT_TEXTURE_ID_SIZE, MATERIAL_SCHEMA_METADATA_FIXED_SIZE, MATERIAL_SCHEMA_FIELD_SIZE, BONE_NAME_SIZE, SKINNED_MESH_GEOMETRY_INFO_SIZE, SKINNED_MESH_METADATA_FIXED_SIZE, BONE_SIZE, ANIMATION_TRACK_DESCRIPTOR_SIZE, ANIMATION_CLIP_METADATA_FIXED_SIZE, TRACK_NAME_SIZE, ANIMATION_METADATA_VERSION, } from '../core/constants.js';
+// ─── Texture Metadata ───────────────────────────────────────────────────────
+export function serializeTextureMetadata(meta) {
+    const w = new BinaryWriter(TEXTURE_METADATA_SIZE);
+    w.writeUint32(meta.width);
+    w.writeUint32(meta.height);
+    w.writeUint32(meta.channels);
+    w.writeUint32(meta.channelFormat);
+    w.writeFixedString(meta.stringId, STRING_ID_SIZE);
+    return w.getUint8Array();
+}
+export function deserializeTextureMetadata(data) {
+    const r = new BinaryReader(data);
+    return {
+        width: r.readUint32(),
+        height: r.readUint32(),
+        channels: r.readUint32(),
+        channelFormat: r.readUint32(),
+        stringId: r.readFixedString(STRING_ID_SIZE),
+    };
+}
+// ─── Audio Metadata ─────────────────────────────────────────────────────────
+export function serializeAudioMetadata(meta) {
+    const w = new BinaryWriter(AUDIO_METADATA_SIZE);
+    w.writeFixedString(meta.stringId, STRING_ID_SIZE);
+    w.writeUint32(meta.sampleRate);
+    w.writeUint32(meta.channels);
+    w.writeUint32(meta.durationMs);
+    return w.getUint8Array();
+}
+export function deserializeAudioMetadata(data) {
+    const r = new BinaryReader(data);
+    return {
+        stringId: r.readFixedString(STRING_ID_SIZE),
+        sampleRate: r.readUint32(),
+        channels: r.readUint32(),
+        durationMs: r.readUint32(),
+    };
+}
+// ─── Mesh Metadata ──────────────────────────────────────────────────────────
+function serializeGeometryInfo(w, g) {
+    w.writeUint32(g.vertexCount);
+    w.writeUint32(g.indexCount);
+    w.writeUint32(g.hasNormals);
+    w.writeUint32(g.hasUvs);
+    w.writeUint64FromNumber(g.compressedBufferOffset);
+    w.writeUint64FromNumber(g.compressedBufferSize);
+    w.writeUint32(g.materialIndex);
+    w.writeUint32(0);
+}
+function deserializeGeometryInfo(r) {
+    const info = {
+        vertexCount: r.readUint32(),
+        indexCount: r.readUint32(),
+        hasNormals: r.readUint32(),
+        hasUvs: r.readUint32(),
+        compressedBufferOffset: r.readUint64AsNumber(),
+        compressedBufferSize: r.readUint64AsNumber(),
+        materialIndex: r.readUint32(),
+    };
+    r.readUint32();
+    return info;
+}
+function serializeNode(w, n) {
+    w.writeFixedString(n.name, NODE_NAME_SIZE);
+    w.writeInt32(n.parentIndex);
+    w.writeFloat32(n.position[0]);
+    w.writeFloat32(n.position[1]);
+    w.writeFloat32(n.position[2]);
+    w.writeFloat32(n.rotation[0]);
+    w.writeFloat32(n.rotation[1]);
+    w.writeFloat32(n.rotation[2]);
+    w.writeFloat32(n.rotation[3]);
+    w.writeFloat32(n.scale[0]);
+    w.writeFloat32(n.scale[1]);
+    w.writeFloat32(n.scale[2]);
+    w.writeUint32(n.meshCount);
+    w.writeUint32(n.firstMeshIndex);
+}
+function deserializeNode(r) {
+    return {
+        name: r.readFixedString(NODE_NAME_SIZE),
+        parentIndex: r.readInt32(),
+        position: [r.readFloat32(), r.readFloat32(), r.readFloat32()],
+        rotation: [r.readFloat32(), r.readFloat32(), r.readFloat32(), r.readFloat32()],
+        scale: [r.readFloat32(), r.readFloat32(), r.readFloat32()],
+        meshCount: r.readUint32(),
+        firstMeshIndex: r.readUint32(),
+    };
+}
+function serializeMaterialProperty(w, p) {
+    w.writeFixedString(p.fieldName, MATERIAL_FIELD_NAME_SIZE);
+    w.writeFloat32(p.value[0]);
+    w.writeFloat32(p.value[1]);
+    w.writeFloat32(p.value[2]);
+    w.writeFloat32(p.value[3]);
+    w.writeFixedString(p.textureId, MATERIAL_FIELD_NAME_SIZE);
+}
+function deserializeMaterialProperty(r) {
+    return {
+        fieldName: r.readFixedString(MATERIAL_FIELD_NAME_SIZE),
+        value: [r.readFloat32(), r.readFloat32(), r.readFloat32(), r.readFloat32()],
+        textureId: r.readFixedString(MATERIAL_FIELD_NAME_SIZE),
+    };
+}
+function serializeMaterialHeader(w, m) {
+    w.writeFixedString(m.name, MATERIAL_NAME_SIZE);
+    w.writeFixedString(m.schemaId, MATERIAL_SCHEMA_ID_SIZE);
+    w.writeUint32(m.propertyCount);
+}
+function deserializeMaterialHeader(r) {
+    return {
+        name: r.readFixedString(MATERIAL_NAME_SIZE),
+        schemaId: r.readFixedString(MATERIAL_SCHEMA_ID_SIZE),
+        propertyCount: r.readUint32(),
+        properties: [],
+    };
+}
+function serializeMaterialSchemaField(w, field) {
+    w.writeFixedString(field.name, MATERIAL_FIELD_NAME_SIZE);
+    w.writeUint32(field.fieldType);
+    w.writeUint32(field.previewFlags);
+    w.writeFloat32(field.defaultValue[0]);
+    w.writeFloat32(field.defaultValue[1]);
+    w.writeFloat32(field.defaultValue[2]);
+    w.writeFloat32(field.defaultValue[3]);
+    w.writeFixedString(field.defaultTextureId, MATERIAL_SCHEMA_DEFAULT_TEXTURE_ID_SIZE);
+}
+function deserializeMaterialSchemaField(r) {
+    return {
+        name: r.readFixedString(MATERIAL_FIELD_NAME_SIZE),
+        fieldType: r.readUint32(),
+        previewFlags: r.readUint32(),
+        defaultValue: [r.readFloat32(), r.readFloat32(), r.readFloat32(), r.readFloat32()],
+        defaultTextureId: r.readFixedString(MATERIAL_SCHEMA_DEFAULT_TEXTURE_ID_SIZE),
+    };
+}
+export function serializeMaterialSchemaMetadata(meta) {
+    const size = MATERIAL_SCHEMA_METADATA_FIXED_SIZE + meta.fields.length * MATERIAL_SCHEMA_FIELD_SIZE;
+    const w = new BinaryWriter(size);
+    w.writeFixedString(meta.stringId, STRING_ID_SIZE);
+    w.writeFixedString(meta.schemaName, MATERIAL_SCHEMA_NAME_SIZE);
+    w.writeUint32(meta.fields.length);
+    for (const field of meta.fields)
+        serializeMaterialSchemaField(w, field);
+    return w.getUint8Array();
+}
+export function deserializeMaterialSchemaMetadata(data) {
+    const r = new BinaryReader(data);
+    const stringId = r.readFixedString(STRING_ID_SIZE);
+    const schemaName = r.readFixedString(MATERIAL_SCHEMA_NAME_SIZE);
+    const fieldCount = r.readUint32();
+    const fields = [];
+    for (let i = 0; i < fieldCount; i++)
+        fields.push(deserializeMaterialSchemaField(r));
+    return { stringId, schemaName, fieldCount, fields };
+}
+export function serializeMeshMetadata(meta) {
+    let size = MESH_METADATA_FIXED_SIZE;
+    size += meta.geometries.length * MESH_GEOMETRY_INFO_SIZE;
+    size += meta.materials.length * MATERIAL_DATA_FIXED_SIZE;
+    size += meta.nodes.length * SCENE_NODE_SIZE;
+    size += meta.meshIndices.length * 4;
+    for (const m of meta.materials)
+        size += m.properties.length * MATERIAL_PROPERTY_VALUE_SIZE;
+    const w = new BinaryWriter(size);
+    w.writeUint32(meta.meshGeometryCount);
+    w.writeUint32(meta.materialCount);
+    w.writeUint32(meta.nodeCount);
+    w.writeFixedString(meta.stringId, STRING_ID_SIZE);
+    for (const g of meta.geometries)
+        serializeGeometryInfo(w, g);
+    for (const m of meta.materials)
+        serializeMaterialHeader(w, m);
+    for (const n of meta.nodes)
+        serializeNode(w, n);
+    for (const idx of meta.meshIndices)
+        w.writeUint32(idx);
+    for (const m of meta.materials) {
+        for (const p of m.properties)
+            serializeMaterialProperty(w, p);
+    }
+    return w.getUint8Array();
+}
+export function deserializeMeshMetadata(data) {
+    const r = new BinaryReader(data);
+    const meshGeometryCount = r.readUint32();
+    const materialCount = r.readUint32();
+    const nodeCount = r.readUint32();
+    const stringId = r.readFixedString(STRING_ID_SIZE);
+    const geometries = [];
+    for (let i = 0; i < meshGeometryCount; i++)
+        geometries.push(deserializeGeometryInfo(r));
+    const materials = [];
+    for (let i = 0; i < materialCount; i++)
+        materials.push(deserializeMaterialHeader(r));
+    const nodes = [];
+    for (let i = 0; i < nodeCount; i++)
+        nodes.push(deserializeNode(r));
+    const totalMeshIndices = nodes.reduce((sum, n) => sum + n.meshCount, 0);
+    const meshIndices = [];
+    for (let i = 0; i < totalMeshIndices; i++)
+        meshIndices.push(r.readUint32());
+    for (const m of materials) {
+        for (let i = 0; i < m.propertyCount; i++)
+            m.properties.push(deserializeMaterialProperty(r));
+    }
+    return { meshGeometryCount, materialCount, nodeCount, stringId, geometries, materials, nodes, meshIndices };
+}
+// ─── Animation Clip Metadata ────────────────────────────────────────────────
+function serializeTrackDescriptor(w, track) {
+    w.writeFixedString(track.trackName, TRACK_NAME_SIZE);
+    w.writeUint32(track.keyframeCount);
+    w.writeUint32(track.valuesPerKey);
+    w.writeUint64FromNumber(track.timesOffset);
+    w.writeUint64FromNumber(track.valuesOffset);
+}
+function deserializeTrackDescriptor(r) {
+    return {
+        trackName: r.readFixedString(TRACK_NAME_SIZE),
+        keyframeCount: r.readUint32(),
+        valuesPerKey: r.readUint32(),
+        timesOffset: r.readUint64AsNumber(),
+        valuesOffset: r.readUint64AsNumber(),
+    };
+}
+export function serializeAnimationClipMetadata(meta) {
+    const size = ANIMATION_CLIP_METADATA_FIXED_SIZE + meta.tracks.length * ANIMATION_TRACK_DESCRIPTOR_SIZE;
+    const w = new BinaryWriter(size);
+    w.writeFixedString(meta.stringId, STRING_ID_SIZE);
+    w.writeFixedString(meta.targetMeshId, STRING_ID_SIZE);
+    w.writeUint32(ANIMATION_METADATA_VERSION);
+    w.writeFloat32(meta.duration);
+    w.writeUint32(meta.trackCount);
+    for (const track of meta.tracks)
+        serializeTrackDescriptor(w, track);
+    return w.getUint8Array();
+}
+export function deserializeAnimationClipMetadata(data) {
+    const r = new BinaryReader(data);
+    const stringId = r.readFixedString(STRING_ID_SIZE);
+    const targetMeshId = r.readFixedString(STRING_ID_SIZE);
+    const metadataVersion = r.readUint32();
+    const duration = r.readFloat32();
+    const trackCount = r.readUint32();
+    const tracks = [];
+    for (let i = 0; i < trackCount; i++)
+        tracks.push(deserializeTrackDescriptor(r));
+    return { stringId, targetMeshId, metadataVersion, duration, trackCount, tracks };
+}
+// ─── Skinned Mesh Metadata ───────────────────────────────────────────────────
+function serializeSkinnedGeometryInfo(w, g) {
+    w.writeUint32(g.vertexCount);
+    w.writeUint32(g.indexCount);
+    w.writeUint32(g.hasNormals);
+    w.writeUint32(g.hasUvs);
+    w.writeUint64FromNumber(g.vertexBufferOffset);
+    w.writeUint64FromNumber(g.vertexBufferSize);
+    w.writeUint64FromNumber(g.indexBufferOffset);
+    w.writeUint64FromNumber(g.indexBufferSize);
+    w.writeUint64FromNumber(g.weightsOffset);
+    w.writeUint64FromNumber(g.weightsSize);
+    w.writeUint32(g.materialIndex);
+    w.writeUint32(g._padding);
+}
+function deserializeSkinnedGeometryInfo(r) {
+    return {
+        vertexCount: r.readUint32(),
+        indexCount: r.readUint32(),
+        hasNormals: r.readUint32(),
+        hasUvs: r.readUint32(),
+        vertexBufferOffset: r.readUint64AsNumber(),
+        vertexBufferSize: r.readUint64AsNumber(),
+        indexBufferOffset: r.readUint64AsNumber(),
+        indexBufferSize: r.readUint64AsNumber(),
+        weightsOffset: r.readUint64AsNumber(),
+        weightsSize: r.readUint64AsNumber(),
+        materialIndex: r.readUint32(),
+        _padding: r.readUint32(),
+    };
+}
+function serializeBone(w, bone) {
+    w.writeFixedString(bone.name, BONE_NAME_SIZE);
+    w.writeInt32(bone.parentIndex);
+    const m = bone.offsetMatrix;
+    for (let i = 0; i < 16; i++) {
+        w.writeFloat32(m?.[i] ?? (i % 5 === 0 ? 1 : 0));
+    }
+}
+function deserializeBone(r) {
+    const name = r.readFixedString(BONE_NAME_SIZE);
+    const parentIndex = r.readInt32();
+    const offsetMatrix = [];
+    for (let i = 0; i < 16; i++)
+        offsetMatrix.push(r.readFloat32());
+    return { name, parentIndex, offsetMatrix };
+}
+export function serializeSkinnedMeshMetadata(meta) {
+    let size = SKINNED_MESH_METADATA_FIXED_SIZE;
+    size += meta.geometries.length * SKINNED_MESH_GEOMETRY_INFO_SIZE;
+    size += meta.materials.length * MATERIAL_DATA_FIXED_SIZE;
+    size += meta.nodes.length * SCENE_NODE_SIZE;
+    size += meta.meshIndices.length * 4;
+    for (const m of meta.materials)
+        size += m.properties.length * MATERIAL_PROPERTY_VALUE_SIZE;
+    size += meta.bones.length * BONE_SIZE;
+    const w = new BinaryWriter(size);
+    w.writeUint32(meta.meshGeometryCount);
+    w.writeUint32(meta.materialCount);
+    w.writeUint32(meta.nodeCount);
+    w.writeUint32(meta.boneCount);
+    w.writeFixedString(meta.stringId, STRING_ID_SIZE);
+    for (const g of meta.geometries)
+        serializeSkinnedGeometryInfo(w, g);
+    for (const m of meta.materials)
+        serializeMaterialHeader(w, m);
+    for (const n of meta.nodes)
+        serializeNode(w, n);
+    for (const idx of meta.meshIndices)
+        w.writeUint32(idx);
+    for (const m of meta.materials) {
+        for (const p of m.properties)
+            serializeMaterialProperty(w, p);
+    }
+    for (const bone of meta.bones)
+        serializeBone(w, bone);
+    return w.getUint8Array();
+}
+export function deserializeSkinnedMeshMetadata(data) {
+    const r = new BinaryReader(data);
+    const meshGeometryCount = r.readUint32();
+    const materialCount = r.readUint32();
+    const nodeCount = r.readUint32();
+    const boneCount = r.readUint32();
+    const stringId = r.readFixedString(STRING_ID_SIZE);
+    const geometries = [];
+    for (let i = 0; i < meshGeometryCount; i++)
+        geometries.push(deserializeSkinnedGeometryInfo(r));
+    const materials = [];
+    for (let i = 0; i < materialCount; i++)
+        materials.push(deserializeMaterialHeader(r));
+    const nodes = [];
+    for (let i = 0; i < nodeCount; i++)
+        nodes.push(deserializeNode(r));
+    const totalMeshIndices = nodes.reduce((sum, n) => sum + n.meshCount, 0);
+    const meshIndices = [];
+    for (let i = 0; i < totalMeshIndices; i++)
+        meshIndices.push(r.readUint32());
+    for (const m of materials) {
+        for (let i = 0; i < m.propertyCount; i++)
+            m.properties.push(deserializeMaterialProperty(r));
+    }
+    const bones = [];
+    for (let i = 0; i < boneCount; i++)
+        bones.push(deserializeBone(r));
+    return { meshGeometryCount, materialCount, nodeCount, boneCount, stringId, geometries, materials, nodes, meshIndices, bones };
+}
+// ─── Metadata Wrapping ──────────────────────────────────────────────────────
+export function wrapMetadata(assetMetadata, tags) {
+    const tagCsv = tags.length > 0 ? tags.join(',') + '\0' : '\0';
+    const tagBytes = new TextEncoder().encode(tagCsv);
+    const totalSize = 4 + tagBytes.length + assetMetadata.length;
+    const w = new BinaryWriter(totalSize);
+    w.writeUint32(tagBytes.length);
+    w.writeBytes(tagBytes);
+    w.writeBytes(assetMetadata);
+    return w.getUint8Array();
+}
+export function unwrapMetadata(wrapped) {
+    const r = new BinaryReader(wrapped);
+    const tagCsvLength = r.readUint32();
+    const tagBytes = r.readBytes(tagCsvLength);
+    const tagString = new TextDecoder().decode(tagBytes);
+    const tags = tagString
+        .replace(/\0/g, '')
+        .split(',')
+        .filter((t) => t.length > 0);
+    const assetMetadata = r.readBytes(r.remaining);
+    return { tags, assetMetadata };
+}

package/dist/format/packer.d.ts

@@ -0,0 +1,8 @@
+import { AssetType } from '../core/types.js';
+export declare class StowPacker {
+    private assets;
+    addAsset(canonicalPath: string, type: AssetType, data: Uint8Array, metadata?: Uint8Array | null, tags?: string[]): void;
+    build(): Uint8Array;
+    get assetCount(): number;
+    clear(): void;
+}

package/dist/format/packer.js

@@ -0,0 +1,87 @@
+import { BinaryWriter } from '../core/binary.js';
+import { STOW_MAGIC, STOW_VERSION, FILE_HEADER_SIZE, DIRECTORY_ENTRY_SIZE, DATA_ALIGNMENT, } from '../core/constants.js';
+import { djb2Hash, normalizePath, validatePath } from '../core/path.js';
+import { wrapMetadata } from './metadata.js';
+function calculatePadding(offset, alignment) {
+    return (alignment - (offset % alignment)) % alignment;
+}
+export class StowPacker {
+    assets = [];
+    addAsset(canonicalPath, type, data, metadata = null, tags = []) {
+        const pathError = validatePath(canonicalPath);
+        if (pathError)
+            throw new Error(`Invalid path "${canonicalPath}": ${pathError}`);
+        const normalized = normalizePath(canonicalPath);
+        const uid = djb2Hash(normalized);
+        if (this.assets.some((a) => a.uid === uid)) {
+            throw new Error(`Duplicate asset UID for path: ${canonicalPath}`);
+        }
+        const wrappedMetadata = metadata ? wrapMetadata(metadata, tags) : null;
+        this.assets.push({
+            canonicalPath: normalized,
+            type,
+            uid,
+            data,
+            metadata: wrappedMetadata,
+            tags,
+        });
+    }
+    build() {
+        if (this.assets.length === 0) {
+            throw new Error('Cannot build an empty pack');
+        }
+        const directoryOffset = FILE_HEADER_SIZE;
+        const directorySize = this.assets.length * DIRECTORY_ENTRY_SIZE;
+        let currentOffset = directoryOffset + directorySize;
+        const dataOffsets = [];
+        for (const asset of this.assets) {
+            currentOffset += calculatePadding(currentOffset, DATA_ALIGNMENT);
+            dataOffsets.push(currentOffset);
+            currentOffset += asset.data.length;
+        }
+        const metadataOffsets = [];
+        for (const asset of this.assets) {
+            if (asset.metadata) {
+                currentOffset += calculatePadding(currentOffset, DATA_ALIGNMENT);
+                metadataOffsets.push(currentOffset);
+                currentOffset += asset.metadata.length;
+            }
+            else {
+                metadataOffsets.push(0);
+            }
+        }
+        const totalSize = currentOffset;
+        const w = new BinaryWriter(totalSize);
+        w.writeUint32(STOW_MAGIC);
+        w.writeUint32(STOW_VERSION);
+        w.writeUint32(this.assets.length);
+        w.writeUint64FromNumber(directoryOffset);
+        for (let i = 0; i < this.assets.length; i++) {
+            const asset = this.assets[i];
+            w.writeUint64(asset.uid);
+            w.writeUint32(asset.type);
+            w.writeUint64FromNumber(dataOffsets[i]);
+            w.writeUint64FromNumber(asset.data.length);
+            w.writeUint64FromNumber(metadataOffsets[i]);
+            w.writeUint32(asset.metadata ? asset.metadata.length : 0);
+        }
+        for (let i = 0; i < this.assets.length; i++) {
+            w.seek(dataOffsets[i]);
+            w.writeBytes(this.assets[i].data);
+        }
+        for (let i = 0; i < this.assets.length; i++) {
+            const asset = this.assets[i];
+            if (asset.metadata && metadataOffsets[i] > 0) {
+                w.seek(metadataOffsets[i]);
+                w.writeBytes(asset.metadata);
+            }
+        }
+        return w.getUint8Array();
+    }
+    get assetCount() {
+        return this.assets.length;
+    }
+    clear() {
+        this.assets = [];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export * from './core/types.js';
+export * from './core/constants.js';
+export * from './core/binary.js';
+export * from './core/path.js';
+export { StowPacker } from './format/packer.js';
+export * from './format/metadata.js';
+export * from './app/disk-project.js';
+export { BlobStore } from './app/blob-store.js';
+export * from './app/state.js';
+export * from './app/stowmeta-io.js';
+export * from './app/stowmat-io.js';
+export * from './app/process-cache.js';
+export * from './node-fs.js';
+export * from './encoders/interfaces.js';
+export { NodeBasisEncoder } from './encoders/basis-encoder.js';
+export { NodeDracoEncoder, dracoPresetToSettings } from './encoders/draco-encoder.js';
+export { NodeAacEncoder, NodeAudioDecoder } from './encoders/aac-encoder.js';
+export { NodeFbxImporter } from './encoders/fbx-loader.js';
+export { SharpImageDecoder } from './encoders/image-decoder.js';
+export { buildSkinnedMeshData } from './encoders/skinned-mesh-builder.js';
+export { processAsset, buildPack, buildAnimationDataBlobsV2 } from './pipeline.js';
+export type { ProcessingContext, ProcessResult } from './pipeline.js';
+export { fullBuild, scanProject, showStatus } from './orchestrator.js';
+export type { BuildOptions, ScanReport } from './orchestrator.js';
+export { startServer } from './server.js';
+export type { ServerOptions } from './server.js';
+export { initProject } from './init.js';
+export { cleanupProject } from './cleanup.js';