@series-inc/stowkit-cli 0.1.17 → 0.1.20

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/dist/server.js

@@ -523,8 +523,14 @@ async function processOneAsset(id) {
     const asset = assets.find(a => a.id === id);
     if (!asset)
         return;
-    if (asset.type === AssetType.MaterialSchema)
+    if (asset.type === AssetType.MaterialSchema) {
+        // Materials are metadata-only — no encoding needed. Ensure they're always ready.
+        if (asset.status !== 'ready') {
+            asset.status = 'ready';
+            broadcast({ type: 'asset-update', id, updates: { status: 'ready' } });
+        }
         return;
+    }
     // GLB children: if source data isn't in BlobStore, re-extract from parent GLB
     // and process just this child (not the entire container)
     if (asset.parentId && !BlobStore.getSource(id)) {
@@ -741,9 +747,12 @@ async function handleRequest(req, res, staticApps) {
                 [...currentIds].some(id => !diskIds.has(id)) ||
                 [...diskIds].some(id => !currentIds.has(id));
             // Check for modified files (size or mtime changed)
+            // Skip MaterialSchema — .stowmat files are metadata-only and written by the server itself
             const modifiedIds = [];
             if (!changed) {
                 for (const asset of currentAssets) {
+                    if (asset.type === AssetType.MaterialSchema)
+                        continue;
                     const diskFile = diskFiles.get(asset.id);
                     if (diskFile && asset.sourceSize > 0 && diskFile.size !== asset.sourceSize) {
                         modifiedIds.push(asset.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.1.17",
+  "version": "0.1.20",
   "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.10",
     "@series-inc/stowkit-editor": "^0.1.2",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",

package/skill.md

@@ -361,6 +361,121 @@ 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)