@series-inc/stowkit-cli 0.1.26 → 0.1.29

package/dist/encoders/fbx-loader.js

@@ -2,6 +2,7 @@ import * as THREE from 'three';
 import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
 import { PropertyBinding } from 'three';
 import { parseBinary as fbxParseBinary, parseText as fbxParseText, FBXReader } from 'fbx-parser';
+import { mergeByMaterial, } from './interfaces.js';
 // ─── Minimal DOM shim for Three.js FBXLoader in Node ────────────────────────
 function ensureDomShim() {
     const g = globalThis;
@@ -291,14 +292,14 @@ function extractMeshFromGroup(group) {
     }
     if (materials.length === 0)
         materials.push({ name: 'default' });
-    return {
+    return mergeByMaterial({
         subMeshes,
         materials,
         nodes,
         hasSkeleton,
         bones: allBones,
         animations: [],
-    };
+    });
 }
 // ─── Hierarchical Group → ImportedMesh extraction ────────────────────────────
 function extractMeshFromGroupHierarchical(group) {

package/dist/encoders/glb-loader.js

@@ -1,5 +1,6 @@
 import * as THREE from 'three';
 import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { mergeByMaterial } from './interfaces.js';
 import { PropertyBinding } from 'three';
 import { MaterialFieldType, PreviewPropertyFlag } from '../core/types.js';
 // ─── DOM shim (shared pattern from fbx-loader) ─────────────────────────────
@@ -333,14 +334,14 @@ function extractMeshes(gltf) {
     }
     if (materials.length === 0)
         materials.push({ name: 'default' });
-    const imported = {
+    const imported = mergeByMaterial({
         subMeshes,
         materials,
         nodes,
         hasSkeleton,
         bones: allBones,
         animations: [],
-    };
+    });
     const meshName = meshObjects[0]?.name || 'mesh';
     return [{ name: meshName, imported, hasSkeleton }];
 }

package/dist/encoders/interfaces.d.ts

@@ -83,6 +83,13 @@ export interface ImportedSkinData {
     boneIndices: Uint32Array;
     boneWeights: Float32Array;
 }
+/**
+ * Merge submeshes that share the same material into a single submesh.
+ * Only used when preserveHierarchy is OFF — vertices are already in world space.
+ * Skinned submeshes are left unmerged.
+ * Returns a new ImportedMesh with merged submeshes and a single root node.
+ */
+export declare function mergeByMaterial(mesh: ImportedMesh): ImportedMesh;
 export interface DecodedPcm {
     channels: Float32Array[];
     sampleRate: number;

package/dist/encoders/interfaces.js

@@ -1 +1,107 @@
-export {};
+// ─── Mesh Merging (flat mode) ────────────────────────────────────────────────
+/**
+ * Merge submeshes that share the same material into a single submesh.
+ * Only used when preserveHierarchy is OFF — vertices are already in world space.
+ * Skinned submeshes are left unmerged.
+ * Returns a new ImportedMesh with merged submeshes and a single root node.
+ */
+export function mergeByMaterial(mesh) {
+    // Group non-skinned submeshes by materialIndex
+    const groups = new Map(); // materialIndex → submesh indices
+    const skinnedIndices = [];
+    for (let i = 0; i < mesh.subMeshes.length; i++) {
+        const sm = mesh.subMeshes[i];
+        if (sm.skinData) {
+            skinnedIndices.push(i);
+            continue;
+        }
+        let list = groups.get(sm.materialIndex);
+        if (!list) {
+            list = [];
+            groups.set(sm.materialIndex, list);
+        }
+        list.push(i);
+    }
+    // Nothing to merge
+    if (groups.size === mesh.subMeshes.length - skinnedIndices.length && skinnedIndices.length === 0) {
+        // Already one submesh per material, just collapse to single node
+        return collapseToSingleNode(mesh);
+    }
+    const mergedSubMeshes = [];
+    // Merge each material group
+    for (const [matIdx, smIndices] of groups) {
+        if (smIndices.length === 1) {
+            mergedSubMeshes.push(mesh.subMeshes[smIndices[0]]);
+            continue;
+        }
+        // Calculate total sizes
+        let totalVerts = 0;
+        let totalIndices = 0;
+        let hasNormals = true;
+        let hasUvs = true;
+        for (const si of smIndices) {
+            const sm = mesh.subMeshes[si];
+            totalVerts += sm.positions.length / 3;
+            totalIndices += sm.indices.length;
+            if (!sm.normals)
+                hasNormals = false;
+            if (!sm.uvs)
+                hasUvs = false;
+        }
+        const positions = new Float32Array(totalVerts * 3);
+        const normals = hasNormals ? new Float32Array(totalVerts * 3) : null;
+        const uvs = hasUvs ? new Float32Array(totalVerts * 2) : null;
+        const indices = new Uint32Array(totalIndices);
+        let vertOffset = 0;
+        let idxOffset = 0;
+        for (const si of smIndices) {
+            const sm = mesh.subMeshes[si];
+            const vc = sm.positions.length / 3;
+            positions.set(sm.positions, vertOffset * 3);
+            if (normals && sm.normals)
+                normals.set(sm.normals, vertOffset * 3);
+            if (uvs && sm.uvs)
+                uvs.set(sm.uvs, vertOffset * 2);
+            // Offset indices to account for merged vertex buffer
+            for (let j = 0; j < sm.indices.length; j++) {
+                indices[idxOffset + j] = sm.indices[j] + vertOffset;
+            }
+            vertOffset += vc;
+            idxOffset += sm.indices.length;
+        }
+        mergedSubMeshes.push({ positions, normals, uvs, indices, materialIndex: matIdx });
+    }
+    // Append skinned submeshes unchanged
+    for (const si of skinnedIndices) {
+        mergedSubMeshes.push(mesh.subMeshes[si]);
+    }
+    // Single node referencing all submeshes — the user sees one mesh
+    const node = {
+        name: mesh.nodes[0]?.name || 'mesh',
+        parentIndex: -1,
+        position: [0, 0, 0],
+        rotation: [0, 0, 0, 1],
+        scale: [1, 1, 1],
+        meshIndices: mergedSubMeshes.map((_, i) => i),
+    };
+    return {
+        subMeshes: mergedSubMeshes,
+        materials: mesh.materials,
+        nodes: [node],
+        hasSkeleton: mesh.hasSkeleton,
+        bones: mesh.bones,
+        animations: mesh.animations,
+    };
+}
+/** Collapse N flat nodes into a single node referencing all submeshes */
+function collapseToSingleNode(mesh) {
+    const node = {
+        name: mesh.nodes[0]?.name || 'mesh',
+        parentIndex: -1,
+        position: [0, 0, 0],
+        rotation: [0, 0, 0, 1],
+        scale: [1, 1, 1],
+        meshIndices: mesh.subMeshes.map((_, i) => i),
+    };
+    return { ...mesh, nodes: [node] };
+}

package/dist/orchestrator.js

@@ -453,22 +453,45 @@ export async function showStatus(projectDir) {
     console.log(`Meta files: ${scan.metaFiles.length}`);
     const packs = config.config.packs ?? [{ name: 'default' }];
     console.log(`Packs: ${packs.map(p => p.name).join(', ')}`);
-    // Count stale
+    // Count stale (including GLB children)
     let cached = 0;
     let stale = 0;
+    const staleIds = [];
     for (const file of scan.sourceFiles) {
         const meta = await readStowmeta(config.srcArtDir, file.relativePath);
         if (!meta) {
             stale++;
+            staleIds.push(file.relativePath);
             continue;
         }
         const { type, settings } = stowmetaToAssetSettings(meta);
         if (meta.cache && isCacheValid(meta, file, type, settings)) {
             cached++;
         }
-        else {
+        else if (type !== AssetType.GlbContainer) {
             stale++;
+            staleIds.push(file.relativePath);
+        }
+        // Check GLB children
+        if (meta.type === 'glbContainer') {
+            const glbMeta = meta;
+            for (const child of glbMeta.children ?? []) {
+                if (child.childType === 'materialSchema')
+                    continue;
+                const childId = `${file.relativePath}/${child.name}`;
+                if (child.cache) {
+                    cached++;
+                }
+                else {
+                    stale++;
+                    staleIds.push(childId);
+                }
+            }
         }
     }
     console.log(`Cached: ${cached}, Needs processing: ${stale}`);
+    if (staleIds.length > 0) {
+        for (const id of staleIds)
+            console.log(`  ${id}`);
+    }
 }

package/dist/pipeline.js

@@ -367,8 +367,14 @@ function resolveAssignedMaterial(meshAsset, subMeshIndex, sourceMaterialName, as
 }
 function toMaterialPropertyValue(prop, assetsById) {
     const textureAsset = prop.textureAssetId ? assetsById.get(prop.textureAssetId) : undefined;
+    // Use previewFlag name as fallback when fieldName is empty (e.g. alphaTest)
+    const flagNames = {
+        1: 'mainTex', 2: 'tint', 3: 'alphaTest',
+        4: 'metalness', 5: 'roughness', 6: 'normalMap', 7: 'emissiveMap', 8: 'emissive',
+    };
+    const fieldName = prop.fieldName.trim() || flagNames[prop.previewFlag] || '';
     return {
-        fieldName: prop.fieldName,
+        fieldName,
         value: [prop.value[0], prop.value[1], prop.value[2], prop.value[3]],
         textureId: textureAsset?.stringId ?? '',
     };
@@ -390,7 +396,7 @@ function applyMaterialAssignments(meshAsset, metadata, assetsById, materialsBySt
             continue;
         const config = assigned.settings.materialConfig;
         const propertyValues = config.properties
-            .filter((prop) => prop.fieldName.trim().length > 0)
+            .filter((prop) => prop.fieldName.trim().length > 0 || prop.previewFlag > 0)
             .map((prop) => toMaterialPropertyValue(prop, assetsById));
         materials[i].schemaId = config.schemaId || assigned.stringId;
         materials[i].properties = propertyValues;

package/dist/server.js

@@ -89,12 +89,18 @@ function queueProcessing(opts = {}) {
                 }
             }
         }
-        // Build the processing queue — process children directly (their source data
-        // is already in BlobStore from the initial GLB extraction). Only promote to
-        // parent container when the container itself is a target (re-export, preserveHierarchy change).
+        // Build the processing queue.
+        // If a GLB container is in the queue, skip its children — processGlbContainer
+        // handles all child processing internally. Without this, drain workers race:
+        // a child worker and the container worker both process the same children,
+        // and the container replaces the assets array mid-flight.
+        const containerIds = new Set(targets.filter(a => a.type === AssetType.GlbContainer).map(a => a.id));
         const queue = [];
         const seen = new Set();
         for (const a of targets) {
+            // Skip children whose parent container is also being processed
+            if (a.parentId && containerIds.has(a.parentId))
+                continue;
             if (!seen.has(a.id)) {
                 seen.add(a.id);
                 queue.push(a.id);
@@ -115,6 +121,16 @@ function queueProcessing(opts = {}) {
             workers.push(drain());
         }
         await Promise.all(workers);
+        // Diagnostic: log any assets that aren't ready after processing completes
+        const notReady = assets.filter(a => a.status !== 'ready' && a.type !== AssetType.MaterialSchema);
+        if (notReady.length > 0) {
+            console.log(`[server] WARNING: ${notReady.length} asset(s) still not ready after processing:`);
+            for (const a of notReady)
+                console.log(`  ${a.id} → ${a.status}${a.error ? ` (${a.error})` : ''}`);
+        }
+        else {
+            console.log(`[server] All ${assets.length} assets ready.`);
+        }
         broadcast({ type: 'processing-complete' });
     })();
     if (opts.await)
@@ -155,7 +171,8 @@ async function expandGlbChildren(srcArtDir, containerId, containerMeta, configur
             fileName: child.name,
             stringId: child.stringId || baseName,
             type: childType,
-            status: 'pending',
+            // Materials are metadata-only — always ready, no processing needed
+            status: childType === AssetType.MaterialSchema ? 'ready' : 'pending',
             settings: childSettings,
             sourceSize: 0,
             processedSize: 0,
@@ -263,7 +280,14 @@ async function processGlbContainer(containerId) {
         const existing = existingChildren.get(anim.name);
         childrenManifest.push(existing ?? generateDefaultGlbChild(anim.name, 'animationClip'));
     }
-    // Update container stowmeta with full inline children
+    // Clear old cache stamps on all children — processGlbContainer always re-processes
+    // everything (the container was marked pending, so children must be reprocessed too).
+    // Without this, expandGlbChildren would restore children from stale cache and skip
+    // re-processing (e.g. after a preserveHierarchy toggle).
+    for (const child of childrenManifest) {
+        delete child.cache;
+    }
+    // Update container stowmeta with full inline children (cache stamps cleared)
     if (containerStowmeta) {
         containerStowmeta.children = childrenManifest;
         await writeStowmeta(projectConfig.srcArtDir, containerId, containerStowmeta);
@@ -271,7 +295,7 @@ async function processGlbContainer(containerId) {
     // Remove old child assets from the list
     const prefix = containerId + '/';
     assets = assets.filter(a => !a.id.startsWith(prefix));
-    // Create child assets from inline entries
+    // Create child assets from inline entries (all will be 'pending' since cache was cleared)
     const childAssets = await expandGlbChildren(projectConfig.srcArtDir, containerId, { ...containerStowmeta, children: childrenManifest }, configuredPacks);
     // Set up material configs for extracted GLB materials (runtime config from inline)
     for (const mat of extract.materials) {
@@ -352,16 +376,56 @@ async function processGlbContainer(containerId) {
             }
         }
     }
-    // Persist updated stowmeta (may have auto-assigned materialOverrides)
+    // Process texture children (their raw image data is in BlobStore from extraction)
+    const pendingTextures = childAssets.filter(a => a.status === 'pending' && a.type === AssetType.Texture2D);
+    await Promise.all(pendingTextures.map(child => processOneAsset(child.id)));
+    // Write cache blobs and stamps for ALL children processed in this container.
+    // Without this, a server restart / rescan would see no cache → children restart as 'pending'.
+    const parentSnapshot = await getFileSnapshot(projectConfig.srcArtDir, containerId);
+    for (const childAsset of childAssets) {
+        if (childAsset.status !== 'ready')
+            continue;
+        if (childAsset.type === AssetType.MaterialSchema)
+            continue;
+        const childName = childAsset.id.split('/').pop();
+        const inlineChild = childrenManifest.find(c => c.name === childName);
+        if (!inlineChild)
+            continue;
+        // Collect cache blobs for this child
+        const cacheEntries = new Map();
+        const processed = BlobStore.getProcessed(childAsset.id);
+        if (processed)
+            cacheEntries.set(childAsset.id, processed);
+        if (childAsset.metadata) {
+            cacheEntries.set(`${childAsset.id}:__metadata__`, new TextEncoder().encode(JSON.stringify(childAsset.metadata)));
+        }
+        for (const suffix of [':skinnedMeta', ':animMeta', ':animCount']) {
+            const blob = BlobStore.getProcessed(`${childAsset.id}${suffix}`);
+            if (blob)
+                cacheEntries.set(`${childAsset.id}${suffix}`, blob);
+        }
+        const animCountBlob = BlobStore.getProcessed(`${childAsset.id}:animCount`);
+        const clipCount = animCountBlob ? animCountBlob[0] : 0;
+        for (let ci = 0; ci < clipCount; ci++) {
+            for (const key of [`${childAsset.id}:anim:${ci}`, `${childAsset.id}:animMeta:${ci}`]) {
+                const blob = BlobStore.getProcessed(key);
+                if (blob)
+                    cacheEntries.set(key, blob);
+            }
+        }
+        if (cacheEntries.size > 0) {
+            await writeCacheBlobs(projectConfig.srcArtDir, childAsset.id, cacheEntries);
+        }
+        // Set cache stamp on the inline child entry (uses parent file snapshot)
+        if (parentSnapshot) {
+            inlineChild.cache = buildCacheStamp(parentSnapshot, childAsset.type, childAsset.settings);
+        }
+    }
+    // Persist updated stowmeta with materialOverrides AND cache stamps
     if (containerStowmeta) {
         containerStowmeta.children = childrenManifest;
         await writeStowmeta(projectConfig.srcArtDir, containerId, containerStowmeta);
     }
-    // Queue texture children for processing (their raw image data is in BlobStore)
-    const pendingTextures = childAssets.filter(a => a.status === 'pending' && a.type === AssetType.Texture2D);
-    for (const child of pendingTextures) {
-        processOneAsset(child.id);
-    }
 }
 async function readBody(req) {
     const chunks = [];
@@ -528,26 +592,21 @@ async function processOneAsset(id) {
                     throw new Error(`Could not read parent GLB: ${asset.parentId}`);
                 parentSource = data;
             }
-            const extract = await parseGlb(parentSource);
+            // Read parent's preserveHierarchy setting
+            const parentMeta = await readStowmeta(projectConfig.srcArtDir, asset.parentId);
+            const preserveHierarchy = parentMeta?.preserveHierarchy ?? false;
+            const extract = await parseGlb(parentSource, { preserveHierarchy });
             const childName = id.split('/').pop();
+            let childResult = null;
             if (asset.type === AssetType.Texture2D) {
                 const tex = extract.textures.find(t => t.name === childName);
                 if (!tex)
                     throw new Error(`Texture "${childName}" not found in GLB`);
                 BlobStore.setSource(id, tex.data);
-                // Process via worker pool
                 const { result, blobs } = await workerPool.processAsset({ id, sourceData: tex.data, type: asset.type, stringId: asset.stringId, settings: asset.settings }, (pid, msg) => broadcast({ type: 'progress', id: pid, message: msg }));
                 for (const [key, data] of blobs)
                     BlobStore.setProcessed(key, data);
-                if (asset.status !== 'pending') {
-                    asset.status = 'ready';
-                    asset.metadata = result.metadata;
-                    asset.processedSize = result.processedSize;
-                    broadcast({
-                        type: 'asset-update', id,
-                        updates: { status: 'ready', metadata: result.metadata, processedSize: result.processedSize },
-                    });
-                }
+                childResult = result;
             }
             else if (asset.type === AssetType.StaticMesh || asset.type === AssetType.SkinnedMesh) {
                 const mesh = extract.meshes.find(m => m.name === childName);
@@ -556,15 +615,7 @@ async function processOneAsset(id) {
                 const { result, blobs } = await workerPool.processExtractedMesh({ childId: id, imported: mesh.imported, hasSkeleton: mesh.hasSkeleton, stringId: asset.stringId, settings: asset.settings }, (pid, msg) => broadcast({ type: 'progress', id: pid, message: msg }));
                 for (const [key, data] of blobs)
                     BlobStore.setProcessed(key, data);
-                if (asset.status !== 'pending') {
-                    asset.status = 'ready';
-                    asset.metadata = result.metadata;
-                    asset.processedSize = result.processedSize;
-                    broadcast({
-                        type: 'asset-update', id,
-                        updates: { status: 'ready', metadata: result.metadata, processedSize: result.processedSize },
-                    });
-                }
+                childResult = result;
             }
             else {
                 // Animation or other — fall back to full container reprocess
@@ -575,7 +626,52 @@ async function processOneAsset(id) {
                 }
                 return;
             }
-            console.log(`[server] Re-processed GLB child ${id}`);
+            if (childResult && asset.status !== 'pending') {
+                asset.status = 'ready';
+                asset.metadata = childResult.metadata;
+                asset.processedSize = childResult.processedSize;
+                broadcast({
+                    type: 'asset-update', id,
+                    updates: { status: 'ready', metadata: childResult.metadata, processedSize: childResult.processedSize },
+                });
+            }
+            // Write cache for this child
+            const cacheEntries = new Map();
+            const processed = BlobStore.getProcessed(id);
+            if (processed)
+                cacheEntries.set(id, processed);
+            if (childResult?.metadata) {
+                cacheEntries.set(`${id}:__metadata__`, new TextEncoder().encode(JSON.stringify(childResult.metadata)));
+            }
+            for (const suffix of [':skinnedMeta', ':animMeta', ':animCount']) {
+                const blob = BlobStore.getProcessed(`${id}${suffix}`);
+                if (blob)
+                    cacheEntries.set(`${id}${suffix}`, blob);
+            }
+            const animCountBlob = BlobStore.getProcessed(`${id}:animCount`);
+            const clipCount = animCountBlob ? animCountBlob[0] : 0;
+            for (let ci = 0; ci < clipCount; ci++) {
+                for (const key of [`${id}:anim:${ci}`, `${id}:animMeta:${ci}`]) {
+                    const blob = BlobStore.getProcessed(key);
+                    if (blob)
+                        cacheEntries.set(key, blob);
+                }
+            }
+            if (cacheEntries.size > 0) {
+                await writeCacheBlobs(projectConfig.srcArtDir, id, cacheEntries);
+                // Update cache stamp in parent's stowmeta for this child
+                if (parentMeta) {
+                    const inlineChild = parentMeta.children.find(c => c.name === childName);
+                    if (inlineChild) {
+                        const parentSnapshot = await getFileSnapshot(projectConfig.srcArtDir, asset.parentId);
+                        if (parentSnapshot) {
+                            inlineChild.cache = buildCacheStamp(parentSnapshot, asset.type, asset.settings);
+                            await writeStowmeta(projectConfig.srcArtDir, asset.parentId, parentMeta);
+                        }
+                    }
+                }
+            }
+            console.log(`[server] Re-processed GLB child ${id} (status: ${asset.status}, in assets: ${assets.some(a => a.id === id)})`);
         }
         catch (err) {
             asset.status = 'error';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.1.26",
+  "version": "0.1.29",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -17,7 +17,7 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@series-inc/stowkit-packer-gui": "^0.1.12",
+    "@series-inc/stowkit-packer-gui": "^0.1.16",
     "@series-inc/stowkit-editor": "^0.1.2",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",