@series-inc/stowkit-cli 0.1.18 → 0.1.21

package/dist/app/disk-project.js

@@ -64,7 +64,13 @@ export const PREVIEW_FLAG_STRINGS = {
     mainTex: 1,
     tint: 2,
     alphaTest: 3,
+    metalness: 4,
+    roughness: 5,
+    normalMap: 6,
+    emissiveMap: 7,
+    emissive: 8,
 };
 export const PREVIEW_FLAG_TO_STRING = {
     0: 'none', 1: 'mainTex', 2: 'tint', 3: 'alphaTest',
+    4: 'metalness', 5: 'roughness', 6: 'normalMap', 7: 'emissiveMap', 8: 'emissive',
 };

package/dist/core/types.d.ts

@@ -39,7 +39,12 @@ export declare enum PreviewPropertyFlag {
     None = 0,
     MainTex = 1,
     Tint = 2,
-    AlphaTest = 3
+    AlphaTest = 3,
+    Metalness = 4,
+    Roughness = 5,
+    NormalMap = 6,
+    EmissiveMap = 7,
+    Emissive = 8
 }
 export declare enum AacQuality {
     Lowest = 0,

package/dist/core/types.js

@@ -49,6 +49,11 @@ export var PreviewPropertyFlag;
     PreviewPropertyFlag[PreviewPropertyFlag["MainTex"] = 1] = "MainTex";
     PreviewPropertyFlag[PreviewPropertyFlag["Tint"] = 2] = "Tint";
     PreviewPropertyFlag[PreviewPropertyFlag["AlphaTest"] = 3] = "AlphaTest";
+    PreviewPropertyFlag[PreviewPropertyFlag["Metalness"] = 4] = "Metalness";
+    PreviewPropertyFlag[PreviewPropertyFlag["Roughness"] = 5] = "Roughness";
+    PreviewPropertyFlag[PreviewPropertyFlag["NormalMap"] = 6] = "NormalMap";
+    PreviewPropertyFlag[PreviewPropertyFlag["EmissiveMap"] = 7] = "EmissiveMap";
+    PreviewPropertyFlag[PreviewPropertyFlag["Emissive"] = 8] = "Emissive";
 })(PreviewPropertyFlag || (PreviewPropertyFlag = {}));
 // ─── Audio Enums ────────────────────────────────────────────────────────
 export var AacQuality;

package/dist/init.js

@@ -49,15 +49,17 @@ export async function initProject(projectDir) {
     catch {
         await fs.writeFile(gitignorePath, stowkitIgnores + '\n');
     }
-    // Copy Claude skill file
-    const skillDir = path.join(absDir, '.claude', 'skills');
-    await fs.mkdir(skillDir, { recursive: true });
+    // Copy AI skill/rule files (CLI skill only — loader skills are installed locally with their packages)
     const thisDir = path.dirname(fileURLToPath(import.meta.url));
     const skillSrc = path.resolve(thisDir, '../skill.md');
-    const skillDst = path.join(skillDir, 'stowkit.md');
     try {
         const skillContent = await fs.readFile(skillSrc, 'utf-8');
-        await fs.writeFile(skillDst, skillContent);
+        const claudeDir = path.join(absDir, '.claude', 'skills', 'stowkit');
+        await fs.mkdir(claudeDir, { recursive: true });
+        await fs.writeFile(path.join(claudeDir, 'SKILL.md'), skillContent);
+        const cursorDir = path.join(absDir, '.cursor', 'rules');
+        await fs.mkdir(cursorDir, { recursive: true });
+        await fs.writeFile(path.join(cursorDir, 'stowkit.mdc'), `---\ndescription: StowKit asset pipeline — CLI usage, .stowmeta/.stowmat formats, GLB containers, and runtime reader packages\nalwaysApply: true\n---\n\n${skillContent}`);
     }
     catch {
         // Skill file not found in package — skip silently
@@ -66,7 +68,7 @@ export async function initProject(projectDir) {
     console.log(`  Source art dir: ${srcArtDir}/`);
     console.log(`  Output dir:     public/cdn-assets/`);
     console.log(`  Config:         .felicityproject`);
-    console.log(`  Claude skill:   .claude/skills/stowkit.md`);
+    console.log(`  AI skills:      .claude/skills/stowkit/SKILL.md, .cursor/rules/stowkit.mdc`);
     console.log('');
     console.log('Drop your assets (PNG, JPG, FBX, WAV, etc.) into assets/');
     console.log('Then run: npx stowkit build');

package/package.json

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

package/skill.md

@@ -7,12 +7,12 @@ StowKit is a game asset pipeline that compresses and packs assets into `.stow` b
 `.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`)
+2. Run `stowkit build` (or `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.
 
-To create materials, use `npx stowkit create-material <path>` — this scaffolds a `.stowmat` file with the right structure. You can also create `.stowmat` files manually if needed.
+To create materials, use `stowkit create-material <path>` — this scaffolds a `.stowmat` file with the right structure. You can also create `.stowmat` files manually if needed.
 
 ## Project Structure
 
@@ -36,20 +36,20 @@ A StowKit project has a `.felicityproject` JSON file at its root:
 ## CLI Commands
 
 ```bash
-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 create-material <path>  # Create a .stowmat material file (--schema pbr|unlit|<name>)
-npx stowkit rename <path> <name>    # Rename an asset file (preserves extension, updates sidecars)
-npx stowkit move <path> <folder>    # Move an asset to a different folder (updates GLB child refs)
-npx stowkit delete <path>           # Delete an asset and its .stowmeta/.stowcache files
-npx stowkit set-id <path> <id>      # Change an asset's stringId
-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)
+stowkit init [dir]              # Scaffold a new project (creates .felicityproject, assets/, public/cdn-assets/)
+stowkit build [dir]             # Full build: scan + process + pack
+stowkit scan [dir]              # Detect new assets and generate .stowmeta defaults
+stowkit process [dir]           # Compress assets (respects cache)
+stowkit status [dir]            # Show project summary, stale asset count
+stowkit clean [dir]             # Delete orphaned .stowcache and .stowmeta files
+stowkit create-material <path>  # Create a .stowmat material file (--schema pbr|unlit|<name>)
+stowkit rename <path> <name>    # Rename an asset file (preserves extension, updates sidecars)
+stowkit move <path> <folder>    # Move an asset to a different folder (updates GLB child refs)
+stowkit delete <path>           # Delete an asset and its .stowmeta/.stowcache files
+stowkit set-id <path> <id>      # Change an asset's stringId
+stowkit packer [dir]            # Open the packer GUI in browser
+stowkit editor [dir]            # Open the level editor in browser
+stowkit serve [dir]             # Start API server only (no GUI)
 ```
 
 All commands default to the current directory.
@@ -76,7 +76,7 @@ All commands default to the current directory.
 
 ## .stowmeta Files (auto-generated — do not create manually)
 
-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.
+Every source asset gets a `.stowmeta` sidecar file generated by `stowkit build` or `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
@@ -269,7 +269,7 @@ Each child in the `children` array supports the same settings as its correspondi
 - 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`.
+Edit these fields in the container's `.stowmeta` to customize per-child processing, then run `stowkit build`.
 
 ## .stowmat Files (Material Schemas)
 
@@ -323,14 +323,43 @@ For GLB mesh children, `materialOverrides` are auto-assigned from the GLB's sub-
 
 ## Setting Up a New Project
 
-1. Run `npx stowkit init` in the project root
-2. Place source art files in `assets/` (or whatever `srcArtDir` is set to)
-3. Run `npx stowkit build` to process and pack everything
-4. Output `.stow` files appear in `public/cdn-assets/`
+1. Install the CLI globally: `npm install -g @series-inc/stowkit-cli`
+2. Run `stowkit init` in the project root
+3. Place source art files in `assets/` (PNG, JPG, GLB, FBX, WAV, etc.)
+4. Run `stowkit build` to scan, compress, and pack everything
+5. Output `.stow` files appear in `public/cdn-assets/`
+
+## Packer GUI
+
+Run `stowkit packer` to open a visual asset management UI in the browser (default http://localhost:3210). The packer provides:
+
+- **Asset browser** — browse all assets in the project organized by folder, with type icons, file sizes, and processing status
+- **Drag-and-drop import** — drag files directly into the browser to import them into the `srcArtDir`
+- **3D mesh preview** — preview static meshes and skinned meshes with PBR lighting, grid, and human-scale reference
+- **Texture preview** — view compressed KTX2 textures with resolution and channel info
+- **Audio preview** — play back audio assets directly
+- **Material editing** — view and edit `.stowmat` material properties, texture assignments, and preview flags
+- **Per-asset settings** — adjust compression quality, resize, pack assignment, stringId, tags, and other settings through the inspector panel
+- **GLB child management** — expand GLB containers to see and configure individual child assets (textures, meshes, materials, animations)
+- **Pack management** — create, rename, and assign assets to different packs
+- **Build button** — trigger a full build from the UI and see pack sizes
+- **Folder management** — create, rename, move, and delete folders
+
+The packer runs alongside the CLI build server — changes made in the GUI are written to the `.stowmeta` files on disk and stay in sync with CLI builds.
+
+### When to recommend the packer
+
+- The user wants to **visually inspect** their assets (mesh previews, texture quality, audio playback)
+- The user needs to **bulk-adjust settings** across many assets
+- The user is **new to StowKit** and wants to understand the project structure
+- The user wants to **import many files at once** via drag-and-drop
+- The user is **debugging material/texture assignments** on meshes
+
+For quick one-off changes (adjust a quality setting, rename an asset), the CLI commands are faster.
 
 ## Modifying Asset Settings
 
-Edit the `.stowmeta` file for any asset, then run `npx stowkit build`.
+Edit the `.stowmeta` file for any asset, then run `stowkit build`. Or use the packer GUI to change settings visually.
 The build respects cache — only assets whose settings or source files changed get reprocessed.
 Use `--force` to reprocess everything.
 
@@ -361,12 +390,127 @@ 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`.
 
+## Runtime Reader Packages
+
+The CLI builds `.stow` packs. To **load** them at runtime you need a reader package. Choose based on your rendering engine:
+
+| Package | Install | Use When |
+|---------|---------|----------|
+| `@series-inc/stowkit-reader` | `npm install @series-inc/stowkit-reader` | You want the low-level WASM reader only (zero deps) — parse packs, list assets, read binary data |
+| `@series-inc/stowkit-three-loader` | `npm install @series-inc/stowkit-three-loader three` | Your game uses **Three.js** — loads meshes, skinned meshes, animations, textures, audio |
+| `@series-inc/stowkit-phaser-loader` | `npm install @series-inc/stowkit-phaser-loader phaser` | Your game uses **Phaser** — loads KTX2/Basis compressed textures and audio |
+
+If the project has a `.stow` build output but no reader dependency in `package.json`, the user likely needs one of these.
+
+### Three.js Quick Start
+
+```typescript
+import { StowKitLoader } from '@series-inc/stowkit-three-loader';
+
+const pack = await StowKitLoader.load('game.stow');
+
+const mesh = await pack.loadMesh('building');
+scene.add(mesh);
+
+const character = await pack.loadSkinnedMesh('player');
+scene.add(character);
+
+const { mixer } = await pack.loadAnimation(character, 'walk');
+
+// In animation loop
+mixer.update(clock.getDelta());
+
+// Cleanup
+pack.dispose();
+```
+
+Key APIs on `StowKitPack`:
+- `loadMesh(stringId)` / `loadMeshByIndex(i)` — static mesh → `THREE.Group`
+- `loadSkinnedMesh(stringId)` / `loadSkinnedMeshByIndex(i)` — skeletal mesh → `THREE.Group`
+- `loadAnimation(skinnedGroup, stringId)` — returns `{ mixer, action, clip }`
+- `loadAnimationClip(stringId)` — returns `THREE.AnimationClip` without playback
+- `loadTexture(stringId)` — KTX2 → `THREE.CompressedTexture`
+- `loadAudio(stringId, listener)` — AAC → `THREE.Audio`
+- `listAssets()` — full manifest of the pack
+- `dispose()` — free resources
+
+Loader options (passed to `StowKitLoader.load`):
+- `wasmPath` — path to `stowkit_reader.wasm` (default `'/stowkit/stowkit_reader.wasm'`)
+- `basisPath` — path to Basis Universal transcoder (default `'/stowkit/basis/'`)
+- `dracoPath` — path to Draco decoder (default `'/stowkit/draco/'`)
+
+The three-loader auto-copies WASM/Basis/Draco files into `public/stowkit/` via a postinstall script.
+
+### Phaser Quick Start
+
+```typescript
+import { StowKitPhaserLoader } from '@series-inc/stowkit-phaser-loader';
+
+const pack = await StowKitPhaserLoader.load('/assets/game.stow');
+
+await pack.loadTexture('characters/player', this); // registers with Phaser texture manager
+const player = this.add.sprite(400, 300, 'characters/player');
+
+const audioBuffer = await pack.loadAudio('sounds/bgm');
+
+pack.dispose();
+```
+
+Key APIs on `StowKitPhaserPack`:
+- `loadTexture(assetPath, scene)` — KTX2 → Phaser texture (auto-transcodes to best GPU format)
+- `loadAudio(assetPath, audioContext?)` — AAC → `AudioBuffer`
+- `listAssets()` / `getAssetCount()` — pack manifest
+- `dispose()` — free resources
+
+Phaser limitation: no 3D model support — only 2D textures and audio. For 3D, use the three-loader.
+
+### Low-Level Reader
+
+```typescript
+import { StowKitReader } from '@series-inc/stowkit-reader';
+
+const reader = new StowKitReader();
+await reader.init();
+await reader.open(await fetch('assets.stow').then(r => r.arrayBuffer()));
+
+const assets = reader.listAssets();
+const texInfo = reader.parseTextureMetadata(0);
+const audioInfo = reader.parseAudioMetadata(1);
+const data = reader.readAssetData(0);
+
+reader.close();
+```
+
+All binary parsing is done in WASM (Zig) — 10-50x faster than JavaScript DataView.
+
+### Multiple Packs
+
+All reader packages support loading multiple `.stow` packs simultaneously with isolated state:
+
+```typescript
+const [envPack, charPack] = await Promise.all([
+  StowKitLoader.load('environment.stow'),
+  StowKitLoader.load('characters.stow'),
+]);
+```
+
+### Performance Logging
+
+All reader packages re-export `PerfLogger`:
+
+```typescript
+import { PerfLogger } from '@series-inc/stowkit-three-loader';
+PerfLogger.enable();
+// ... load assets — timing details appear in console ...
+PerfLogger.disable();
+```
+
 ## 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`
+2. Run `stowkit build`
 3. The pipeline automatically:
    - Creates a `glbContainer` `.stowmeta` for the file
    - Parses the GLB and extracts all textures, meshes, materials, and animations
@@ -385,7 +529,7 @@ To enable hierarchy preservation on a GLB, edit its `.stowmeta` and set `"preser
 ```bash
 # After the first build has generated the .stowmeta, edit it:
 # Set "preserveHierarchy": true in assets/models/hero.glb.stowmeta
-npx stowkit build
+stowkit build
 ```
 
 The CLI always re-extracts GLB containers on every build, so changes to `preserveHierarchy` take effect immediately — no `--force` needed.
@@ -398,17 +542,17 @@ The CLI always re-extracts GLB containers on every build, so changes to `preserv
 
 ### Other common tasks
 
-- **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`.
-- **Enable preserve hierarchy on a GLB:** Edit the `.stowmeta` for the GLB container, set `"preserveHierarchy": true`, then `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:** Run `npx stowkit create-material materials/MyMat` (creates `assets/materials/MyMat.stowmat` with PBR template). Use `--schema unlit` for unlit materials, or `--schema <name>` for a custom schema. Then run `npx stowkit build`.
+- **Add a texture:** Place PNG/JPG into `assets/`, run `stowkit build`. The CLI auto-generates the `.stowmeta`. Do NOT create it yourself.
+- **Add audio:** Place WAV/MP3/OGG into `assets/`, run `stowkit build`. Same rule — never manually create `.stowmeta`.
+- **Add an FBX mesh:** Place FBX into `assets/`, run `stowkit build`.
+- **Enable preserve hierarchy on a GLB:** Edit the `.stowmeta` for the GLB container, set `"preserveHierarchy": true`, then `stowkit build`
+- **Change compression quality:** Edit the **existing** `.stowmeta` file's quality/resize fields (after it was generated by a build/scan), then `stowkit build`
+- **Create a material:** Run `stowkit create-material materials/MyMat` (creates `assets/materials/MyMat.stowmat` with PBR template). Use `--schema unlit` for unlit materials, or `--schema <name>` for a custom schema. Then run `stowkit build`.
 - **Assign material to mesh:** Edit the mesh's **existing** `.stowmeta` to add `materialOverrides`
-- **Rename an asset:** `npx stowkit rename textures/old_name.png new_name` (extension preserved automatically, sidecars renamed too)
-- **Move an asset:** `npx stowkit move textures/hero.png characters` (moves to `characters/hero.png`, updates GLB child refs if container)
-- **Delete an asset:** `npx stowkit delete textures/unused.png` (removes source + .stowmeta + .stowcache, cascades for GLB containers)
-- **Change an asset's stringId:** `npx stowkit set-id textures/hero.png hero_diffuse`
-- **Check project health:** Run `npx stowkit status`
-- **Full rebuild:** `npx stowkit build --force`
-- **Clean orphaned files:** `npx stowkit clean`
+- **Rename an asset:** `stowkit rename textures/old_name.png new_name` (extension preserved automatically, sidecars renamed too)
+- **Move an asset:** `stowkit move textures/hero.png characters` (moves to `characters/hero.png`, updates GLB child refs if container)
+- **Delete an asset:** `stowkit delete textures/unused.png` (removes source + .stowmeta + .stowcache, cascades for GLB containers)
+- **Change an asset's stringId:** `stowkit set-id textures/hero.png hero_diffuse`
+- **Check project health:** Run `stowkit status`
+- **Full rebuild:** `stowkit build --force`
+- **Clean orphaned files:** `stowkit clean`