@series-inc/stowkit-cli 0.1.11 → 0.1.13

package/dist/workers/process-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workers/process-worker.js

@@ -0,0 +1,83 @@
+import { parentPort } from 'node:worker_threads';
+import { processAsset, processExtractedMesh } from '../pipeline.js';
+import { BlobStore } from '../app/blob-store.js';
+import { NodeBasisEncoder } from '../encoders/basis-encoder.js';
+import { NodeDracoEncoder } from '../encoders/draco-encoder.js';
+import { NodeAacEncoder, NodeAudioDecoder } from '../encoders/aac-encoder.js';
+import { NodeFbxImporter } from '../encoders/fbx-loader.js';
+import { SharpImageDecoder } from '../encoders/image-decoder.js';
+// Lazy-init encoder context
+let ctx = null;
+let initPromise = null;
+function getCtx(wasmDir) {
+    if (ctx)
+        return Promise.resolve(ctx);
+    if (initPromise)
+        return initPromise;
+    initPromise = (async () => {
+        const textureEncoder = new NodeBasisEncoder(wasmDir);
+        const meshEncoder = new NodeDracoEncoder();
+        const aacEncoder = new NodeAacEncoder();
+        const audioDecoder = new NodeAudioDecoder();
+        const meshImporter = new NodeFbxImporter();
+        const imageDecoder = new SharpImageDecoder();
+        await Promise.all([
+            textureEncoder.initialize(),
+            meshEncoder.initialize(),
+            aacEncoder.initialize(),
+            audioDecoder.initialize(),
+        ]);
+        ctx = {
+            textureEncoder,
+            meshEncoder,
+            meshImporter,
+            imageDecoder,
+            audioDecoder,
+            aacEncoder,
+            onProgress: (id, msg) => {
+                parentPort.postMessage({ type: 'progress', id, msg });
+            },
+        };
+        return ctx;
+    })();
+    return initPromise;
+}
+function harvestBlobs() {
+    const blobs = BlobStore.getAllProcessed();
+    const result = [];
+    for (const [key, data] of blobs) {
+        result.push([key, data]);
+    }
+    return result;
+}
+parentPort.on('message', async (msg) => {
+    const { type, id, wasmDir } = msg;
+    try {
+        const processingCtx = await getCtx(wasmDir);
+        if (type === 'processAsset') {
+            const { sourceData, assetType, stringId, settings } = msg;
+            // Clear blobs from previous task
+            BlobStore.clearProcessed();
+            // Set source so pipeline can find it
+            BlobStore.setSource(id, sourceData);
+            const result = await processAsset(id, sourceData, assetType, stringId, settings, processingCtx);
+            const blobs = harvestBlobs();
+            parentPort.postMessage({ type: 'result', id, result, blobs });
+        }
+        else if (type === 'processExtractedMesh') {
+            const { childId, imported, hasSkeleton, stringId, settings } = msg;
+            BlobStore.clearProcessed();
+            const result = await processExtractedMesh(childId, imported, hasSkeleton, stringId, settings, processingCtx);
+            const blobs = harvestBlobs();
+            parentPort.postMessage({ type: 'result', id: childId, result, blobs });
+        }
+    }
+    catch (err) {
+        const errorId = type === 'processExtractedMesh' ? msg.childId : id;
+        parentPort.postMessage({
+            type: 'error',
+            id: errorId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+});

package/dist/workers/worker-pool.d.ts

@@ -0,0 +1,41 @@
+import type { AssetType } from '../core/types.js';
+import type { AssetSettings } from '../app/state.js';
+import type { ProcessResult } from '../pipeline.js';
+import type { ImportedMesh } from '../encoders/interfaces.js';
+export declare class WorkerPool {
+    private workers;
+    private idle;
+    private pending;
+    private taskMap;
+    private wasmDir?;
+    private terminated;
+    constructor(opts?: {
+        poolSize?: number;
+        wasmDir?: string;
+    });
+    private handleMessage;
+    private handleError;
+    private releaseWorker;
+    private acquireWorker;
+    processAsset(task: {
+        id: string;
+        sourceData: Uint8Array;
+        type: AssetType;
+        stringId: string;
+        settings: AssetSettings;
+    }, onProgress?: (id: string, msg: string) => void): Promise<{
+        result: ProcessResult;
+        blobs: [string, Uint8Array][];
+    }>;
+    processExtractedMesh(task: {
+        childId: string;
+        imported: ImportedMesh;
+        hasSkeleton: boolean;
+        stringId: string;
+        settings: AssetSettings;
+    }, onProgress?: (id: string, msg: string) => void): Promise<{
+        result: ProcessResult;
+        blobs: [string, Uint8Array][];
+    }>;
+    terminate(): Promise<void>;
+}

package/dist/workers/worker-pool.js

@@ -0,0 +1,130 @@
+import { Worker } from 'node:worker_threads';
+import * as os from 'node:os';
+export class WorkerPool {
+    workers = [];
+    idle = [];
+    pending = [];
+    taskMap = new Map();
+    wasmDir;
+    terminated = false;
+    constructor(opts) {
+        this.wasmDir = opts?.wasmDir;
+        const poolSize = opts?.poolSize ?? Math.min(4, Math.max(1, os.cpus().length - 1));
+        for (let i = 0; i < poolSize; i++) {
+            const worker = new Worker(new URL('./process-worker.js', import.meta.url));
+            worker.on('message', (msg) => this.handleMessage(worker, msg));
+            worker.on('error', (err) => this.handleError(worker, err));
+            this.workers.push(worker);
+            this.idle.push(worker);
+        }
+    }
+    handleMessage(worker, msg) {
+        const task = this.taskMap.get(worker);
+        if (!task)
+            return;
+        if (msg.type === 'progress') {
+            task.onProgress?.(msg.id, msg.msg);
+            return;
+        }
+        if (msg.type === 'result') {
+            this.taskMap.delete(worker);
+            this.releaseWorker(worker);
+            task.resolve({ result: msg.result, blobs: msg.blobs ?? [] });
+            return;
+        }
+        if (msg.type === 'error') {
+            this.taskMap.delete(worker);
+            this.releaseWorker(worker);
+            task.reject(new Error(msg.error ?? 'Unknown worker error'));
+            return;
+        }
+    }
+    handleError(worker, err) {
+        const task = this.taskMap.get(worker);
+        if (task) {
+            this.taskMap.delete(worker);
+            task.reject(err);
+        }
+        // Replace dead worker
+        const idx = this.workers.indexOf(worker);
+        if (idx !== -1 && !this.terminated) {
+            const replacement = new Worker(new URL('./process-worker.js', import.meta.url));
+            replacement.on('message', (msg) => this.handleMessage(replacement, msg));
+            replacement.on('error', (e) => this.handleError(replacement, e));
+            this.workers[idx] = replacement;
+            this.releaseWorker(replacement);
+        }
+    }
+    releaseWorker(worker) {
+        if (this.pending.length > 0) {
+            const next = this.pending.shift();
+            // Worker stays busy — the pending task will claim it
+            this.idle.push(worker);
+            next();
+        }
+        else {
+            this.idle.push(worker);
+        }
+    }
+    acquireWorker() {
+        const worker = this.idle.pop();
+        if (worker)
+            return Promise.resolve(worker);
+        return new Promise((resolve) => {
+            this.pending.push(() => {
+                const w = this.idle.pop();
+                resolve(w);
+            });
+        });
+    }
+    async processAsset(task, onProgress) {
+        if (this.terminated)
+            throw new Error('WorkerPool is terminated');
+        const worker = await this.acquireWorker();
+        return new Promise((resolve, reject) => {
+            this.taskMap.set(worker, { resolve, reject, onProgress });
+            const msg = {
+                type: 'processAsset',
+                id: task.id,
+                sourceData: task.sourceData,
+                assetType: task.type,
+                stringId: task.stringId,
+                settings: task.settings,
+                wasmDir: this.wasmDir,
+            };
+            worker.postMessage(msg);
+        });
+    }
+    async processExtractedMesh(task, onProgress) {
+        if (this.terminated)
+            throw new Error('WorkerPool is terminated');
+        const worker = await this.acquireWorker();
+        return new Promise((resolve, reject) => {
+            this.taskMap.set(worker, { resolve, reject, onProgress });
+            const msg = {
+                type: 'processExtractedMesh',
+                id: task.childId,
+                childId: task.childId,
+                imported: task.imported,
+                hasSkeleton: task.hasSkeleton,
+                stringId: task.stringId,
+                settings: task.settings,
+                wasmDir: this.wasmDir,
+            };
+            // Use structured clone (no transfer list) — mesh typed arrays may share
+            // underlying ArrayBuffers from the GLB binary chunk, making transfer unsafe.
+            worker.postMessage(msg);
+        });
+    }
+    async terminate() {
+        this.terminated = true;
+        // Reject any pending tasks
+        for (const cb of this.pending) {
+            // Tasks waiting for a worker — they'll never get one
+        }
+        this.pending = [];
+        await Promise.all(this.workers.map(w => w.terminate()));
+        this.workers = [];
+        this.idle = [];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -17,8 +17,8 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@series-inc/stowkit-packer-gui": "^0.1.1",
-    "@series-inc/stowkit-editor": "^0.1.1",
+    "@series-inc/stowkit-packer-gui": "^0.1.6",
+    "@series-inc/stowkit-editor": "^0.1.2",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",
     "@strangeape/ffmpeg-audio-wasm": "^0.1.0",

package/skill.md

@@ -11,41 +11,54 @@ A StowKit project has a `.felicityproject` JSON file at its root:
   "srcArtDir": "assets",
   "name": "My Game",
   "cdnAssetsPath": "public/cdn-assets",
+  "prefabsPath": "prefabs",
   "packs": [{ "name": "default" }]
 }
 ```
 
-- `srcArtDir` — directory containing source art files (PNG, JPG, FBX, WAV, etc.)
+- `srcArtDir` — directory containing source art files (PNG, JPG, FBX, GLB, WAV, etc.)
 - `cdnAssetsPath` — output directory for built `.stow` packs
+- `prefabsPath` — directory for prefab definitions (optional)
 - `packs` — named packs to split assets into
 
 ## CLI Commands
 
 ```bash
-npx stowkit init              # Scaffold a new project (creates .felicityproject, assets/, public/cdn-assets/)
-npx stowkit build             # Full build: scan + compress + pack (reads from cwd)
-npx stowkit scan              # Detect new assets and generate .stowmeta defaults
-npx stowkit status            # Show project info and how many assets need processing
-npx stowkit packer            # Open the visual packer GUI in browser
-npx stowkit build --force     # Reprocess everything, ignore cache
+npx stowkit init [dir]              # Scaffold a new project (creates .felicityproject, assets/, public/cdn-assets/)
+npx stowkit build [dir]             # Full build: scan + process + pack
+npx stowkit scan [dir]              # Detect new assets and generate .stowmeta defaults
+npx stowkit process [dir]           # Compress assets (respects cache)
+npx stowkit status [dir]            # Show project summary, stale asset count
+npx stowkit clean [dir]             # Delete orphaned .stowcache and .stowmeta files
+npx stowkit packer [dir]            # Open the packer GUI in browser
+npx stowkit editor [dir]            # Open the level editor in browser
+npx stowkit serve [dir]             # Start API server only (no GUI)
 ```
 
-All commands default to the current directory. Pass a path as second argument to target a different directory.
+All commands default to the current directory.
+
+**Options:**
+- `--force` — Ignore cache and reprocess everything
+- `--verbose` / `-v` — Detailed output
+- `--port <number>` — Server port (default 3210)
 
 ## Supported Asset Types
 
 | Type | Extensions | Compression |
 |------|-----------|-------------|
+| **GlbContainer** | **gltf, glb** | **Container — auto-extracts textures, meshes, materials, and animations** |
 | Texture2D | png, jpg, jpeg, bmp, tga, webp, gif | KTX2 (Basis Universal) |
 | Audio | wav, mp3, ogg, flac, aac, m4a | AAC (M4A container) |
-| StaticMesh | fbx, obj, gltf, glb | Draco |
+| StaticMesh | fbx, obj | Draco |
 | SkinnedMesh | fbx | Uncompressed interleaved vertex data |
 | AnimationClip | fbx | v2 format (Three.js-native tracks) |
 | MaterialSchema | .stowmat | Metadata only (no data blob) |
 
+**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
 
-Every source asset gets a `.stowmeta` sidecar file (JSON) that controls processing settings:
+Every source asset gets a `.stowmeta` sidecar file (JSON) that controls processing settings.
 
 **Texture example:**
 ```json
@@ -119,6 +132,114 @@ Every source asset gets a `.stowmeta` sidecar file (JSON) that controls processi
 }
 ```
 
+## GLB Container Assets
+
+When a `.glb` or `.gltf` file is added, it gets a `glbContainer` stowmeta. On the first build, the pipeline parses the GLB and automatically extracts all embedded content as **inline children** stored directly in the container's `.stowmeta`.
+
+**GLB container stowmeta example:**
+```json
+{
+  "version": 1,
+  "type": "glbContainer",
+  "stringId": "hero",
+  "tags": [],
+  "pack": "default",
+  "preserveHierarchy": false,
+  "children": [
+    {
+      "name": "Hero_Diffuse.png",
+      "childType": "texture",
+      "stringId": "hero_diffuse",
+      "quality": "fastest",
+      "resize": "full",
+      "generateMipmaps": false
+    },
+    {
+      "name": "Hero",
+      "childType": "skinnedMesh",
+      "stringId": "hero",
+      "dracoQuality": "balanced",
+      "materialOverrides": {
+        "0": "models/hero.glb/HeroSkin.stowmat"
+      }
+    },
+    {
+      "name": "HeroSkin.stowmat",
+      "childType": "materialSchema",
+      "stringId": "HeroSkin",
+      "materialConfig": {
+        "schemaId": "",
+        "properties": [
+          {
+            "fieldName": "BaseColor",
+            "fieldType": "texture",
+            "previewFlag": "mainTex",
+            "value": [1, 1, 1, 1],
+            "textureAsset": "models/hero.glb/Hero_Diffuse.png"
+          },
+          {
+            "fieldName": "Tint",
+            "fieldType": "color",
+            "previewFlag": "tint",
+            "value": [1, 1, 1, 1],
+            "textureAsset": null
+          }
+        ]
+      }
+    },
+    {
+      "name": "Idle",
+      "childType": "animationClip",
+      "stringId": "idle",
+      "targetMeshId": null
+    }
+  ]
+}
+```
+
+### GLB child types
+
+Children extracted from a GLB container can be any of:
+
+- **texture** — Embedded images (PNG/JPG) extracted from GLB binary chunk. Processed through the normal KTX2 pipeline.
+- **staticMesh** — Meshes with no skeleton. Draco-compressed. Positions stored in local space when `preserveHierarchy` is true, otherwise baked to world space.
+- **skinnedMesh** — Meshes with a skeleton and bone weights. Uncompressed interleaved vertex data.
+- **animationClip** — Animations from the GLB. Processed into v2 format.
+- **materialSchema** — PBR materials extracted from the GLB. Automatically converted from glTF PBR metallic-roughness to StowKit material configs with texture references pointing to sibling child textures.
+
+### GLB child IDs
+
+Child asset IDs follow the pattern `{containerId}/{childName}`. For example, if the container is `models/hero.glb`, its children have IDs like:
+- `models/hero.glb/Hero_Diffuse.png` (texture)
+- `models/hero.glb/Hero` (mesh)
+- `models/hero.glb/HeroSkin.stowmat` (material)
+- `models/hero.glb/Idle` (animation)
+
+Material texture references within a GLB also use these child IDs (e.g. `"textureAsset": "models/hero.glb/Hero_Diffuse.png"`).
+
+### GLB auto-assignment
+
+The build pipeline automatically:
+1. Parses the GLB and discovers all textures, meshes, materials, and animations
+2. Creates a `children` manifest in the container's `.stowmeta`
+3. Converts glTF PBR materials into `materialConfig` entries with correct texture references
+4. Auto-assigns `materialOverrides` on mesh children based on GLB sub-mesh→material mappings
+5. Processes each child through the appropriate encoder (KTX2 for textures, Draco for static meshes, etc.)
+
+### preserveHierarchy
+
+Set `"preserveHierarchy": true` on a GLB container to preserve the scene graph node hierarchy in extracted static meshes. When false (default), all mesh geometry is baked to world space and flattened. Skinned meshes are always excluded from hierarchy preservation.
+
+### GLB child settings
+
+Each child in the `children` array supports the same settings as its corresponding standalone asset type:
+- Texture children: `quality`, `resize`, `generateMipmaps`
+- Mesh children: `dracoQuality`, `materialOverrides`
+- Animation children: `targetMeshId`
+- All children: `excluded`, `tags`, `pack`, `stringId`
+
+Edit these fields in the container's `.stowmeta` to customize per-child processing, then run `npx stowkit build`.
+
 ## .stowmat Files (Material Schemas)
 
 Materials are defined as `.stowmat` JSON files placed in the source art directory:
@@ -150,6 +271,8 @@ Materials are defined as `.stowmat` JSON files placed in the source art director
 **Preview flags:** none, mainTex, tint, alphaTest
 **textureAsset:** relative path to a texture in the project (e.g. "textures/hero.png")
 
+GLB containers also produce inline material children with a `materialConfig` field — these replace separate `.stowmat` files for GLB-extracted materials.
+
 ## Material Overrides on Meshes
 
 To assign materials to mesh sub-meshes, set `materialOverrides` in the mesh's `.stowmeta`:
@@ -163,7 +286,9 @@ To assign materials to mesh sub-meshes, set `materialOverrides` in the mesh's `.
 }
 ```
 
-Keys are sub-mesh indices (as strings), values are relative paths to `.stowmat` files.
+Keys are sub-mesh indices (as strings), values are relative paths to `.stowmat` files or GLB child material IDs (e.g. `"models/hero.glb/HeroSkin.stowmat"`).
+
+For GLB mesh children, `materialOverrides` are auto-assigned from the GLB's sub-mesh→material mappings. You can override them by editing the child entry in the container's `.stowmeta`.
 
 ## Setting Up a New Project
 
@@ -178,6 +303,8 @@ Edit the `.stowmeta` file for any asset, then run `npx stowkit build`.
 The build respects cache — only assets whose settings or source files changed get reprocessed.
 Use `--force` to reprocess everything.
 
+For GLB child assets, edit the child's entry inside the container's `.stowmeta` `children` array.
+
 ## Multi-Pack Setup
 
 Split assets into multiple packs by editing `.felicityproject`:
@@ -193,19 +320,45 @@ Split assets into multiple packs by editing `.felicityproject`:
 ```
 
 Then set `"pack": "level1"` in each asset's `.stowmeta` to assign it to a pack.
+GLB children inherit the container's pack by default, but each child can override it with its own `"pack"` field.
 
 ## Cache
 
 Processed assets are cached in `.stowcache` sidecar files next to the source.
 The `.stowmeta` file stores a cache stamp (source size, modified time, settings hash).
 Cache is automatically invalidated when source files or settings change.
+GLB children have their own cache entries stored alongside the container.
 Add `*.stowcache` to `.gitignore`.
 
 ## Common Tasks for AI Agents
 
+### Adding a GLB model (recommended 3D workflow)
+
+1. Place the `.glb` file into the `srcArtDir` (e.g. `assets/models/hero.glb`)
+2. Run `npx stowkit build`
+3. The pipeline automatically:
+   - Creates a `glbContainer` `.stowmeta` for the file
+   - Parses the GLB and extracts all textures, meshes, materials, and animations
+   - Populates the `children` array in the `.stowmeta` with one entry per extracted asset
+   - Converts glTF PBR materials to StowKit `materialConfig` with correct texture references
+   - Auto-assigns `materialOverrides` on mesh children from the GLB's sub-mesh→material mapping
+   - Processes each child (KTX2 for textures, Draco for static meshes, etc.)
+4. To customize child settings after the first build, edit the `children` array entries in the container's `.stowmeta`
+5. To exclude a child from packing, set `"excluded": true` on that child entry
+6. To preserve the scene graph hierarchy in static meshes, set `"preserveHierarchy": true` on the container
+
+### When to use preserveHierarchy
+
+- **Default (false):** All mesh geometry is baked to world space and flattened into a single mesh. Use this for simple props and environment pieces.
+- **true:** The original scene graph node hierarchy is preserved with local transforms (position, rotation, scale) per node. Use this for complex multi-part models where you need individual nodes at runtime (e.g. a vehicle with doors, a character with attachable accessories).
+- Skinned meshes are always excluded from hierarchy preservation regardless of this setting.
+
+### 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`
 - **Check project health:** Run `npx stowkit status`
 - **Full rebuild:** `npx stowkit build --force`
+- **Clean orphaned files:** `npx stowkit clean`