@series-inc/stowkit-cli 0.1.13 → 0.1.15

package/dist/orchestrator.js

@@ -318,10 +318,9 @@ export async function fullBuild(projectDir, opts) {
             console.error(`  [glb] ${container.id} FAILED: ${container.error}`);
         }
     }
-    // 2c. Process GLB mesh children + stale assets via worker pool
-    const glbMeshChildren = assets.filter(a => a.status === 'pending' && a.parentId && (a.type === AssetType.StaticMesh || a.type === AssetType.SkinnedMesh));
-    const pending = assets.filter(a => a.status === 'pending' && !a.parentId);
-    const totalWork = glbMeshChildren.length + pending.length;
+    // 2c. Process all pending assets via worker pool (one queue, no split)
+    const pending = assets.filter(a => a.status === 'pending');
+    const totalWork = pending.length;
     if (totalWork === 0) {
         if (verbose)
             console.log('All assets cached, nothing to process.');
@@ -330,39 +329,34 @@ export async function fullBuild(projectDir, opts) {
         console.log(`Processing ${totalWork} asset(s)...`);
         const pool = new WorkerPool({ wasmDir: opts?.wasmDir });
         let processed = 0;
-        // Process GLB mesh children
-        for (const child of glbMeshChildren) {
-            const extract = glbExtracts.get(child.parentId);
-            if (!extract)
-                continue;
-            const mesh = extract.meshes.find(m => `${child.parentId}/${m.name}` === child.id);
-            if (!mesh)
-                continue;
-            try {
-                const { result, blobs } = await pool.processExtractedMesh({ childId: child.id, imported: mesh.imported, hasSkeleton: mesh.hasSkeleton, stringId: child.stringId, settings: child.settings });
-                for (const [key, data] of blobs)
-                    BlobStore.setProcessed(key, data);
-                child.status = 'ready';
-                child.metadata = result.metadata;
-                child.processedSize = result.processedSize;
-                processed++;
-                if (verbose)
-                    console.log(`  [${processed}/${totalWork}] ${child.id} (glb-mesh)`);
-            }
-            catch (err) {
-                child.status = 'error';
-                child.error = err instanceof Error ? err.message : String(err);
-                processed++;
-            }
-        }
-        // Process remaining pending assets with concurrency limit
         const queue = [...pending];
         async function processNext() {
             while (queue.length > 0) {
                 const asset = queue.shift();
                 const id = asset.id;
                 try {
-                    // Load source (GLB texture children have source in BlobStore already)
+                    // GLB mesh children use processExtractedMesh (needs parsed mesh data)
+                    const isMeshChild = asset.parentId &&
+                        (asset.type === AssetType.StaticMesh || asset.type === AssetType.SkinnedMesh);
+                    if (isMeshChild) {
+                        const extract = glbExtracts.get(asset.parentId);
+                        if (!extract)
+                            throw new Error(`No extract for parent ${asset.parentId}`);
+                        const mesh = extract.meshes.find(m => `${asset.parentId}/${m.name}` === id);
+                        if (!mesh)
+                            throw new Error(`Mesh not found in extract: ${id}`);
+                        const { result, blobs } = await pool.processExtractedMesh({ childId: id, imported: mesh.imported, hasSkeleton: mesh.hasSkeleton, stringId: asset.stringId, settings: asset.settings });
+                        for (const [key, data] of blobs)
+                            BlobStore.setProcessed(key, data);
+                        asset.status = 'ready';
+                        asset.metadata = result.metadata;
+                        asset.processedSize = result.processedSize;
+                        processed++;
+                        if (verbose)
+                            console.log(`  [${processed}/${totalWork}] ${id} (glb-mesh)`);
+                        continue;
+                    }
+                    // Everything else uses processAsset (source bytes)
                     let sourceData = BlobStore.getSource(id);
                     if (!sourceData) {
                         const data = await readFile(config.srcArtDir, id);
@@ -381,39 +375,39 @@ export async function fullBuild(projectDir, opts) {
                     asset.processedSize = result.processedSize;
                     processed++;
                     console.log(`  [${processed}/${totalWork}] ${id} (${elapsed}ms)`);
-                    // Write cache
-                    const cacheEntries = new Map();
-                    const processedBlob = BlobStore.getProcessed(id);
-                    if (processedBlob)
-                        cacheEntries.set(id, processedBlob);
-                    if (result.metadata) {
-                        cacheEntries.set(`${id}:__metadata__`, new TextEncoder().encode(JSON.stringify(result.metadata)));
-                    }
-                    // Auxiliary blobs
-                    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++) {
-                        const animData = BlobStore.getProcessed(`${id}:anim:${ci}`);
-                        if (animData)
-                            cacheEntries.set(`${id}:anim:${ci}`, animData);
-                        const animMeta = BlobStore.getProcessed(`${id}:animMeta:${ci}`);
-                        if (animMeta)
-                            cacheEntries.set(`${id}:animMeta:${ci}`, animMeta);
-                    }
-                    if (cacheEntries.size > 0) {
-                        await writeCacheBlobs(config.srcArtDir, id, cacheEntries);
-                        // Stamp cache in .stowmeta
-                        const snapshot = await getFileSnapshot(config.srcArtDir, id);
-                        if (snapshot) {
-                            const meta = await readStowmeta(config.srcArtDir, id);
-                            if (meta) {
-                                meta.cache = buildCacheStamp(snapshot, asset.type, asset.settings);
-                                await writeStowmeta(config.srcArtDir, id, meta);
+                    // Write cache (only for top-level assets that have their own file on disk)
+                    if (!asset.parentId) {
+                        const cacheEntries = new Map();
+                        const processedBlob = BlobStore.getProcessed(id);
+                        if (processedBlob)
+                            cacheEntries.set(id, processedBlob);
+                        if (result.metadata) {
+                            cacheEntries.set(`${id}:__metadata__`, new TextEncoder().encode(JSON.stringify(result.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++) {
+                            const animData = BlobStore.getProcessed(`${id}:anim:${ci}`);
+                            if (animData)
+                                cacheEntries.set(`${id}:anim:${ci}`, animData);
+                            const animMeta = BlobStore.getProcessed(`${id}:animMeta:${ci}`);
+                            if (animMeta)
+                                cacheEntries.set(`${id}:animMeta:${ci}`, animMeta);
+                        }
+                        if (cacheEntries.size > 0) {
+                            await writeCacheBlobs(config.srcArtDir, id, cacheEntries);
+                            const snapshot = await getFileSnapshot(config.srcArtDir, id);
+                            if (snapshot) {
+                                const meta = await readStowmeta(config.srcArtDir, id);
+                                if (meta) {
+                                    meta.cache = buildCacheStamp(snapshot, asset.type, asset.settings);
+                                    await writeStowmeta(config.srcArtDir, id, meta);
+                                }
                             }
                         }
                     }
@@ -427,7 +421,7 @@ export async function fullBuild(projectDir, opts) {
             }
         }
         const workers = [];
-        for (let i = 0; i < Math.min(maxConcurrent, pending.length); i++) {
+        for (let i = 0; i < Math.min(maxConcurrent, queue.length); i++) {
             workers.push(processNext());
         }
         await Promise.all(workers);

package/dist/server.js

@@ -721,19 +721,55 @@ async function handleRequest(req, res, staticApps) {
         if (projectConfig && Date.now() - lastScanTime > 5000) {
             lastScanTime = Date.now();
             const scan = await scanDirectory(projectConfig.srcArtDir);
-            // Only compare top-level (non-child) asset IDs with disk files
-            const currentIds = new Set(assets.filter(a => !a.parentId).map(a => a.id));
-            const diskIds = new Set([
-                ...scan.sourceFiles.map(f => f.relativePath),
-                ...scan.matFiles.map(f => f.relativePath),
+            // Compare top-level (non-child) asset IDs with disk files
+            const currentAssets = assets.filter(a => !a.parentId);
+            const currentIds = new Set(currentAssets.map(a => a.id));
+            const diskFiles = new Map([
+                ...scan.sourceFiles.map(f => [f.relativePath, f]),
+                ...scan.matFiles.map(f => [f.relativePath, f]),
             ]);
-            const changed = currentIds.size !== diskIds.size ||
+            const diskIds = new Set(diskFiles.keys());
+            // Check for added/removed files
+            let changed = currentIds.size !== diskIds.size ||
                 [...currentIds].some(id => !diskIds.has(id)) ||
                 [...diskIds].some(id => !currentIds.has(id));
+            // Check for modified files (size or mtime changed)
+            const modifiedIds = [];
+            if (!changed) {
+                for (const asset of currentAssets) {
+                    const diskFile = diskFiles.get(asset.id);
+                    if (diskFile && asset.sourceSize > 0 && diskFile.size !== asset.sourceSize) {
+                        modifiedIds.push(asset.id);
+                    }
+                }
+            }
             if (changed) {
                 await openProject(projectConfig.projectDir);
                 queueProcessing();
             }
+            else if (modifiedIds.length > 0) {
+                // Re-read source and reprocess modified assets without full project reload
+                for (const id of modifiedIds) {
+                    const asset = assets.find(a => a.id === id);
+                    if (!asset)
+                        continue;
+                    const diskFile = diskFiles.get(id);
+                    if (diskFile)
+                        asset.sourceSize = diskFile.size;
+                    BlobStore.remove(id);
+                    // Also clear children for GLB containers
+                    if (asset.type === AssetType.GlbContainer) {
+                        const prefix = id + '/';
+                        for (const child of assets) {
+                            if (child.id.startsWith(prefix))
+                                BlobStore.remove(child.id);
+                        }
+                    }
+                    asset.status = 'pending';
+                    broadcast({ type: 'asset-update', id, updates: { status: 'pending', sourceSize: asset.sourceSize } });
+                }
+                queueProcessing({ ids: modifiedIds });
+            }
         }
         json(res, {
             project: projectConfig ? {

package/package.json

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

package/skill.md

@@ -2,6 +2,18 @@
 
 StowKit is a game asset pipeline that compresses and packs assets into `.stow` binary files for runtime loading.
 
+## CRITICAL: Never manually create .stowmeta files
+
+`.stowmeta` files are **auto-generated by the CLI**. To add any asset to the project:
+
+1. Place the source file (GLB, PNG, FBX, WAV, etc.) into the `srcArtDir`
+2. Run `npx stowkit build` (or `npx stowkit scan`)
+3. The CLI detects the new file, generates the correct `.stowmeta` with proper defaults, and processes it
+
+**Do not write `.stowmeta` files by hand.** Only edit an existing `.stowmeta` after it has been generated by the CLI (e.g. to change quality settings, pack assignment, or stringId). The same applies to GLB children — the `children` array is populated automatically on the first build.
+
+The only file you should manually create is `.stowmat` (material schema) files — these are user-authored material definitions, not generated metadata.
+
 ## Project Structure
 
 A StowKit project has a `.felicityproject` JSON file at its root:
@@ -56,9 +68,9 @@ All commands default to the current directory.
 
 **GLB/GLTF is the recommended format for 3D models.** Dropping a `.glb` file into the project is the easiest way to get meshes, textures, materials, and animations into the pipeline — everything is extracted and processed automatically. FBX and OBJ are still supported as standalone mesh formats but lack the automatic material/texture extraction that GLB provides.
 
-## .stowmeta Files
+## .stowmeta Files (auto-generated — do not create manually)
 
-Every source asset gets a `.stowmeta` sidecar file (JSON) that controls processing settings.
+Every source asset gets a `.stowmeta` sidecar file generated by `npx stowkit build` or `npx stowkit scan`. These files control processing settings and should only be **edited** (never created) by hand. The examples below are reference for understanding and editing existing files.
 
 **Texture example:**
 ```json
@@ -355,10 +367,12 @@ Add `*.stowcache` to `.gitignore`.
 
 ### Other common tasks
 
-- **Add a texture:** Drop a PNG/JPG into `assets/`, run `npx stowkit scan` to generate its `.stowmeta`, optionally edit settings, then `npx stowkit build`
-- **Change compression quality:** Edit the `.stowmeta` file's quality/resize fields, then `npx stowkit build`
-- **Create a material:** Create a `.stowmat` JSON file in `assets/`, run `npx stowkit scan`
-- **Assign material to mesh:** Edit the mesh's `.stowmeta` to add `materialOverrides`
+- **Add a texture:** Place PNG/JPG into `assets/`, run `npx stowkit build`. The CLI auto-generates the `.stowmeta`. Do NOT create it yourself.
+- **Add audio:** Place WAV/MP3/OGG into `assets/`, run `npx stowkit build`. Same rule — never manually create `.stowmeta`.
+- **Add an FBX mesh:** Place FBX into `assets/`, run `npx stowkit build`.
+- **Change compression quality:** Edit the **existing** `.stowmeta` file's quality/resize fields (after it was generated by a build/scan), then `npx stowkit build`
+- **Create a material:** Create a `.stowmat` JSON file in `assets/` (this is the one file type you DO create manually), then run `npx stowkit build`
+- **Assign material to mesh:** Edit the mesh's **existing** `.stowmeta` to add `materialOverrides`
 - **Check project health:** Run `npx stowkit status`
 - **Full rebuild:** `npx stowkit build --force`
 - **Clean orphaned files:** `npx stowkit clean`