@series-inc/stowkit-cli 0.6.38 → 0.6.40

package/dist/app/disk-project.d.ts

@@ -80,6 +80,9 @@ export interface StowMetaAnimationClip extends StowMetaBase {
 export interface StowMetaMaterialSchema extends StowMetaBase {
     type: 'materialSchema';
 }
+export interface StowMetaSpriteSheet extends StowMetaBase {
+    type: 'spriteSheet';
+}
 export interface StowMetaGlbChild {
     name: string;
     childType: string;
@@ -108,7 +111,7 @@ export interface StowMetaGlbContainer extends StowMetaBase {
     preserveHierarchy?: boolean;
     children: StowMetaGlbChild[];
 }
-export type StowMeta = StowMetaTexture | StowMetaAudio | StowMetaStaticMesh | StowMetaSkinnedMesh | StowMetaAnimationClip | StowMetaMaterialSchema | StowMetaGlbContainer;
+export type StowMeta = StowMetaTexture | StowMetaAudio | StowMetaStaticMesh | StowMetaSkinnedMesh | StowMetaAnimationClip | StowMetaMaterialSchema | StowMetaSpriteSheet | StowMetaGlbContainer;
 export interface StowMatProperty {
     fieldName: string;
     fieldType: string;
@@ -121,6 +124,14 @@ export interface StowMat {
     schemaName: string;
     properties: StowMatProperty[];
 }
+export interface StowSpriteSheet {
+    version: 1;
+    textureAsset: string | null;
+    rows: number;
+    columns: number;
+    frameCount: number;
+    frameRate: number;
+}
 export declare const KTX2_QUALITY_STRINGS: Record<string, KTX2Quality>;
 export declare const KTX2_QUALITY_TO_STRING: Record<number, string>;
 export declare const TEXTURE_RESIZE_STRINGS: Record<string, TextureResize>;

package/dist/app/state.d.ts

@@ -1,4 +1,4 @@
-import type { AssetType, TextureMetadata, AudioMetadata, MeshMetadata, AnimationClipMetadata, SkinnedMeshMetadata, KTX2Quality, TextureResize, TextureFilterMode, DracoQualityPreset, AacQuality, AudioSampleRate, MaterialFieldType, PreviewPropertyFlag } from '../core/types.js';
+import type { AssetType, TextureMetadata, AudioMetadata, MeshMetadata, AnimationClipMetadata, SkinnedMeshMetadata, SpriteSheetMetadata, KTX2Quality, TextureResize, TextureFilterMode, DracoQualityPreset, AacQuality, AudioSampleRate, MaterialFieldType, PreviewPropertyFlag } from '../core/types.js';
 export interface MaterialProperty {
     fieldName: string;
     fieldType: MaterialFieldType;
@@ -10,6 +10,13 @@ export interface MaterialConfig {
     schemaId: string;
     properties: MaterialProperty[];
 }
+export interface SpriteSheetConfig {
+    textureAssetId: string | null;
+    rows: number;
+    columns: number;
+    frameCount: number;
+    frameRate: number;
+}
 export interface AssetSettings {
     quality: KTX2Quality;
     resize: TextureResize;
@@ -21,6 +28,7 @@ export interface AssetSettings {
     audioSampleRate: AudioSampleRate;
     targetMeshId: string | null;
     materialConfig: MaterialConfig;
+    spritesheetConfig: SpriteSheetConfig;
     materialOverrides: Record<number, string | null>;
     pack: string;
     excluded: boolean;
@@ -35,7 +43,7 @@ export interface ProjectAsset {
     status: 'loading' | 'pending' | 'processing' | 'ready' | 'error';
     error?: string;
     settings: AssetSettings;
-    metadata?: TextureMetadata | AudioMetadata | MeshMetadata | AnimationClipMetadata | SkinnedMeshMetadata;
+    metadata?: TextureMetadata | AudioMetadata | MeshMetadata | AnimationClipMetadata | SkinnedMeshMetadata | SpriteSheetMetadata;
     sourceSize: number;
     processedSize: number;
     parentId?: string;

package/dist/app/state.js

@@ -11,6 +11,7 @@ export function defaultAssetSettings() {
         audioSampleRate: ASR.Auto,
         targetMeshId: null,
         materialConfig: { schemaId: '', properties: [] },
+        spritesheetConfig: { textureAssetId: null, rows: 1, columns: 1, frameCount: 1, frameRate: 12 },
         materialOverrides: {},
         pack: 'default',
         excluded: false,

package/dist/app/stowmeta-io.js

@@ -114,6 +114,11 @@ export function stowmetaToAssetSettings(meta) {
                 type: AssetType.MaterialSchema,
                 settings: base,
             };
+        case 'spriteSheet':
+            return {
+                type: AssetType.SpriteSheet,
+                settings: base,
+            };
         case 'glbContainer':
             return {
                 type: AssetType.GlbContainer,
@@ -185,6 +190,8 @@ export function assetSettingsToStowmeta(asset) {
             };
         case AssetType.MaterialSchema:
             return { ...base, type: 'materialSchema' };
+        case AssetType.SpriteSheet:
+            return { ...base, type: 'spriteSheet' };
         case AssetType.GlbContainer:
             return { ...base, type: 'glbContainer', preserveHierarchy: asset.settings.preserveHierarchy || undefined, children: [] };
         default:
@@ -250,6 +257,8 @@ export function generateDefaultStowmeta(relativePath, type, projectDefaults, ima
             return { ...base, type: 'animationClip', targetMeshId: null };
         case AssetType.MaterialSchema:
             return { ...base, type: 'materialSchema' };
+        case AssetType.SpriteSheet:
+            return { ...base, type: 'spriteSheet' };
         case AssetType.GlbContainer:
             return { ...base, type: 'glbContainer', children: [] };
         default:

package/dist/app/stowspritesheet-io.d.ts

@@ -0,0 +1,6 @@
+import type { SpriteSheetConfig } from './state.js';
+import type { StowSpriteSheet } from './disk-project.js';
+export declare function readStowSpriteSheet(srcArtDir: string, relativePath: string): Promise<StowSpriteSheet | null>;
+export declare function writeStowSpriteSheet(srcArtDir: string, relativePath: string, sheet: StowSpriteSheet): Promise<void>;
+export declare function spritesheetConfigToStowSpriteSheet(config: SpriteSheetConfig): StowSpriteSheet;
+export declare function stowSpriteSheetToConfig(sheet: StowSpriteSheet): SpriteSheetConfig;

package/dist/app/stowspritesheet-io.js

@@ -0,0 +1,40 @@
+import { readTextFile, writeFile } from '../node-fs.js';
+export async function readStowSpriteSheet(srcArtDir, relativePath) {
+    const text = await readTextFile(srcArtDir, relativePath);
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeStowSpriteSheet(srcArtDir, relativePath, sheet) {
+    try {
+        const json = JSON.stringify(sheet, null, 2);
+        await writeFile(srcArtDir, relativePath, json);
+    }
+    catch (err) {
+        console.warn(`[stowspritesheet] Failed to write ${relativePath}:`, err);
+    }
+}
+export function spritesheetConfigToStowSpriteSheet(config) {
+    return {
+        version: 1,
+        textureAsset: config.textureAssetId,
+        rows: config.rows,
+        columns: config.columns,
+        frameCount: config.frameCount,
+        frameRate: config.frameRate,
+    };
+}
+export function stowSpriteSheetToConfig(sheet) {
+    return {
+        textureAssetId: sheet.textureAsset ?? null,
+        rows: sheet.rows ?? 1,
+        columns: sheet.columns ?? 1,
+        frameCount: sheet.frameCount ?? 1,
+        frameRate: sheet.frameRate ?? 12,
+    };
+}

package/dist/app/thumbnail-cache.js

@@ -36,7 +36,7 @@ export async function writeManifest(srcArtDir, manifest) {
 export function computeSettingsHash(settings) {
     // Only include settings that affect visual output
     const relevant = {};
-    for (const key of ['quality', 'resize', 'generateMipmaps', 'dracoQuality', 'materialConfig', 'targetMeshId', 'materialOverrides']) {
+    for (const key of ['quality', 'resize', 'generateMipmaps', 'dracoQuality', 'materialConfig', 'spritesheetConfig', 'targetMeshId', 'materialOverrides']) {
         if (settings[key] !== undefined)
             relevant[key] = settings[key];
     }

package/dist/cleanup.js

@@ -9,11 +9,12 @@ export async function cleanupProject(projectDir, opts) {
     // Build set of source files that exist
     const sourceFiles = new Set(scan.sourceFiles.map(f => f.relativePath));
     const matFiles = new Set(scan.matFiles.map(f => f.relativePath));
+    const spritesheetFiles = new Set(scan.spritesheetFiles.map(f => f.relativePath));
     let deletedCaches = 0;
     let deletedMetas = 0;
     let freedBytes = 0;
     // Walk all files looking for orphaned .stowcache and .stowmeta
-    await walkForOrphans(config.srcArtDir, '', sourceFiles, matFiles, async (orphanPath, type, size) => {
+    await walkForOrphans(config.srcArtDir, '', sourceFiles, matFiles, spritesheetFiles, async (orphanPath, type, size) => {
         const fullPath = path.join(config.srcArtDir, orphanPath);
         await fs.unlink(fullPath);
         freedBytes += size;
@@ -43,7 +44,7 @@ export async function cleanupProject(projectDir, opts) {
         console.log(`Cleaned up ${deletedCaches} cache(s) and ${deletedMetas} meta(s)${thumbNote} (${(freedBytes / 1024).toFixed(0)} KB freed)`);
     }
 }
-async function walkForOrphans(basePath, prefix, sourceFiles, matFiles, onOrphan) {
+async function walkForOrphans(basePath, prefix, sourceFiles, matFiles, spritesheetFiles, onOrphan) {
     const dirPath = prefix ? path.join(basePath, prefix) : basePath;
     let entries;
     try {
@@ -59,21 +60,21 @@ async function walkForOrphans(basePath, prefix, sourceFiles, matFiles, onOrphan)
                 continue;
             if (entry.name.endsWith('.children'))
                 continue;
-            await walkForOrphans(basePath, relativePath, sourceFiles, matFiles, onOrphan);
+            await walkForOrphans(basePath, relativePath, sourceFiles, matFiles, spritesheetFiles, onOrphan);
         }
         else if (entry.isFile()) {
             if (entry.name.endsWith('.stowcache')) {
                 // Cache orphan: source file doesn't exist
                 const sourceId = relativePath.replace(/\.stowcache$/, '');
-                if (!sourceFiles.has(sourceId) && !matFiles.has(sourceId)) {
+                if (!sourceFiles.has(sourceId) && !matFiles.has(sourceId) && !spritesheetFiles.has(sourceId)) {
                     const stat = await fs.stat(path.join(basePath, relativePath));
                     await onOrphan(relativePath, 'cache', stat.size);
                 }
             }
             else if (entry.name.endsWith('.stowmeta')) {
-                // Meta orphan: neither source file nor mat file exists
+                // Meta orphan: neither source file, mat file, nor spritesheet file exists
                 const sourceId = relativePath.replace(/\.stowmeta$/, '');
-                if (!sourceFiles.has(sourceId) && !matFiles.has(sourceId)) {
+                if (!sourceFiles.has(sourceId) && !matFiles.has(sourceId) && !spritesheetFiles.has(sourceId)) {
                     const stat = await fs.stat(path.join(basePath, relativePath));
                     await onOrphan(relativePath, 'meta', stat.size);
                 }

package/dist/core/constants.d.ts

@@ -69,3 +69,5 @@ export declare const ANIMATION_CLIP_METADATA_FIXED_SIZE = 268;
 export declare const TRACK_NAME_SIZE = 64;
 /** Metadata version discriminator for v2 animation clips */
 export declare const ANIMATION_METADATA_VERSION = 2;
+/** Size of SpriteSheetMetadata on disk (bytes) */
+export declare const SPRITESHEET_METADATA_SIZE = 272;

package/dist/core/constants.js

@@ -70,3 +70,5 @@ export const ANIMATION_CLIP_METADATA_FIXED_SIZE = 268;
 export const TRACK_NAME_SIZE = 64;
 /** Metadata version discriminator for v2 animation clips */
 export const ANIMATION_METADATA_VERSION = 2;
+/** Size of SpriteSheetMetadata on disk (bytes) */
+export const SPRITESHEET_METADATA_SIZE = 272;

package/dist/core/types.d.ts

@@ -6,7 +6,8 @@ export declare enum AssetType {
     MaterialSchema = 4,
     SkinnedMesh = 5,
     AnimationClip = 6,
-    GlbContainer = 7
+    GlbContainer = 7,
+    SpriteSheet = 8
 }
 export declare enum KTX2Quality {
     Fastest = 0,
@@ -142,6 +143,14 @@ export interface MaterialSchemaMetadata {
     fieldCount: number;
     fields: MaterialSchemaField[];
 }
+export interface SpriteSheetMetadata {
+    stringId: string;
+    textureId: string;
+    rows: number;
+    columns: number;
+    frameCount: number;
+    frameRate: number;
+}
 export interface MeshMetadata {
     meshGeometryCount: number;
     materialCount: number;

package/dist/core/types.js

@@ -9,6 +9,7 @@ export var AssetType;
     AssetType[AssetType["SkinnedMesh"] = 5] = "SkinnedMesh";
     AssetType[AssetType["AnimationClip"] = 6] = "AnimationClip";
     AssetType[AssetType["GlbContainer"] = 7] = "GlbContainer";
+    AssetType[AssetType["SpriteSheet"] = 8] = "SpriteSheet";
 })(AssetType || (AssetType = {}));
 // ─── Texture Enums ──────────────────────────────────────────────────────────
 export var KTX2Quality;

package/dist/format/metadata.d.ts

@@ -1,4 +1,4 @@
-import type { TextureMetadata, AudioMetadata, MeshMetadata, MaterialSchemaMetadata, AnimationClipMetadata, SkinnedMeshMetadata } from '../core/types.js';
+import type { TextureMetadata, AudioMetadata, MeshMetadata, MaterialSchemaMetadata, AnimationClipMetadata, SkinnedMeshMetadata, SpriteSheetMetadata } from '../core/types.js';
 export declare function serializeTextureMetadata(meta: TextureMetadata): Uint8Array;
 export declare function deserializeTextureMetadata(data: Uint8Array): TextureMetadata;
 export declare function serializeAudioMetadata(meta: AudioMetadata): Uint8Array;
@@ -11,6 +11,8 @@ export declare function serializeAnimationClipMetadata(meta: AnimationClipMetada
 export declare function deserializeAnimationClipMetadata(data: Uint8Array): AnimationClipMetadata;
 export declare function serializeSkinnedMeshMetadata(meta: SkinnedMeshMetadata): Uint8Array;
 export declare function deserializeSkinnedMeshMetadata(data: Uint8Array): SkinnedMeshMetadata;
+export declare function serializeSpriteSheetMetadata(meta: SpriteSheetMetadata): Uint8Array;
+export declare function deserializeSpriteSheetMetadata(data: Uint8Array): SpriteSheetMetadata;
 export declare function wrapMetadata(assetMetadata: Uint8Array, tags: string[]): Uint8Array;
 export declare function unwrapMetadata(wrapped: Uint8Array): {
     tags: string[];

package/dist/format/metadata.js

@@ -1,5 +1,5 @@
 import { BinaryReader, BinaryWriter } from '../core/binary.js';
-import { TEXTURE_METADATA_SIZE, AUDIO_METADATA_SIZE, STRING_ID_SIZE, MESH_GEOMETRY_INFO_SIZE, SCENE_NODE_SIZE, MATERIAL_DATA_FIXED_SIZE, MATERIAL_PROPERTY_VALUE_SIZE, MESH_METADATA_FIXED_SIZE, NODE_NAME_SIZE, MATERIAL_NAME_SIZE, MATERIAL_SCHEMA_ID_SIZE, MATERIAL_FIELD_NAME_SIZE, MATERIAL_SCHEMA_NAME_SIZE, MATERIAL_SCHEMA_DEFAULT_TEXTURE_ID_SIZE, MATERIAL_SCHEMA_METADATA_FIXED_SIZE, MATERIAL_SCHEMA_FIELD_SIZE, BONE_NAME_SIZE, SKINNED_MESH_GEOMETRY_INFO_SIZE, SKINNED_MESH_METADATA_FIXED_SIZE, BONE_SIZE, ANIMATION_TRACK_DESCRIPTOR_SIZE, ANIMATION_CLIP_METADATA_FIXED_SIZE, TRACK_NAME_SIZE, ANIMATION_METADATA_VERSION, } from '../core/constants.js';
+import { TEXTURE_METADATA_SIZE, AUDIO_METADATA_SIZE, STRING_ID_SIZE, MESH_GEOMETRY_INFO_SIZE, SCENE_NODE_SIZE, MATERIAL_DATA_FIXED_SIZE, MATERIAL_PROPERTY_VALUE_SIZE, MESH_METADATA_FIXED_SIZE, NODE_NAME_SIZE, MATERIAL_NAME_SIZE, MATERIAL_SCHEMA_ID_SIZE, MATERIAL_FIELD_NAME_SIZE, MATERIAL_SCHEMA_NAME_SIZE, MATERIAL_SCHEMA_DEFAULT_TEXTURE_ID_SIZE, MATERIAL_SCHEMA_METADATA_FIXED_SIZE, MATERIAL_SCHEMA_FIELD_SIZE, BONE_NAME_SIZE, SKINNED_MESH_GEOMETRY_INFO_SIZE, SKINNED_MESH_METADATA_FIXED_SIZE, BONE_SIZE, ANIMATION_TRACK_DESCRIPTOR_SIZE, ANIMATION_CLIP_METADATA_FIXED_SIZE, TRACK_NAME_SIZE, ANIMATION_METADATA_VERSION, SPRITESHEET_METADATA_SIZE, } from '../core/constants.js';
 import { TextureFilterMode } from '../core/types.js';
 // ─── Texture Metadata ───────────────────────────────────────────────────────
 export function serializeTextureMetadata(meta) {
@@ -361,6 +361,28 @@ export function deserializeSkinnedMeshMetadata(data) {
         bones.push(deserializeBone(r));
     return { meshGeometryCount, materialCount, nodeCount, boneCount, stringId, geometries, materials, nodes, meshIndices, bones };
 }
+// ─── SpriteSheet Metadata ────────────────────────────────────────────────────
+export function serializeSpriteSheetMetadata(meta) {
+    const w = new BinaryWriter(SPRITESHEET_METADATA_SIZE);
+    w.writeFixedString(meta.stringId, STRING_ID_SIZE);
+    w.writeFixedString(meta.textureId, STRING_ID_SIZE);
+    w.writeUint32(meta.rows);
+    w.writeUint32(meta.columns);
+    w.writeUint32(meta.frameCount);
+    w.writeFloat32(meta.frameRate);
+    return w.getUint8Array();
+}
+export function deserializeSpriteSheetMetadata(data) {
+    const r = new BinaryReader(data);
+    return {
+        stringId: r.readFixedString(STRING_ID_SIZE),
+        textureId: r.readFixedString(STRING_ID_SIZE),
+        rows: r.readUint32(),
+        columns: r.readUint32(),
+        frameCount: r.readUint32(),
+        frameRate: r.readFloat32(),
+    };
+}
 // ─── Metadata Wrapping ──────────────────────────────────────────────────────
 export function wrapMetadata(assetMetadata, tags) {
     const tagCsv = tags.length > 0 ? tags.join(',') + '\0' : '\0';

package/dist/node-fs.d.ts

@@ -14,6 +14,7 @@ export interface ScanResult {
     sourceFiles: FileSnapshot[];
     metaFiles: FileSnapshot[];
     matFiles: FileSnapshot[];
+    spritesheetFiles: FileSnapshot[];
     folders: string[];
 }
 export declare function scanDirectory(basePath: string): Promise<ScanResult>;

package/dist/node-fs.js

@@ -98,15 +98,19 @@ function isMetaFile(name) {
 function isMatFile(name) {
     return name.endsWith('.stowmat');
 }
+function isSpritesheetFile(name) {
+    return name.endsWith('.stowspritesheet');
+}
 export async function scanDirectory(basePath) {
     const sourceFiles = [];
     const metaFiles = [];
     const matFiles = [];
+    const spritesheetFiles = [];
     const folders = [];
-    await walkDirectory(basePath, '', sourceFiles, metaFiles, matFiles, folders);
-    return { sourceFiles, metaFiles, matFiles, folders };
+    await walkDirectory(basePath, '', sourceFiles, metaFiles, matFiles, spritesheetFiles, folders);
+    return { sourceFiles, metaFiles, matFiles, spritesheetFiles, folders };
 }
-async function walkDirectory(basePath, prefix, sourceFiles, metaFiles, matFiles, folders) {
+async function walkDirectory(basePath, prefix, sourceFiles, metaFiles, matFiles, spritesheetFiles, folders) {
     const dirPath = prefix ? path.join(basePath, prefix) : basePath;
     let entries;
     try {
@@ -123,7 +127,7 @@ async function walkDirectory(basePath, prefix, sourceFiles, metaFiles, matFiles,
             if (entry.name.endsWith('.children'))
                 continue;
             folders.push(relativePath);
-            await walkDirectory(basePath, relativePath, sourceFiles, metaFiles, matFiles, folders);
+            await walkDirectory(basePath, relativePath, sourceFiles, metaFiles, matFiles, spritesheetFiles, folders);
         }
         else if (entry.isFile()) {
             const fullPath = path.join(basePath, relativePath);
@@ -145,6 +149,9 @@ async function walkDirectory(basePath, prefix, sourceFiles, metaFiles, matFiles,
             else if (isMatFile(entry.name)) {
                 matFiles.push(snapshot);
             }
+            else if (isSpritesheetFile(entry.name)) {
+                spritesheetFiles.push(snapshot);
+            }
             else if (isSourceFile(entry.name)) {
                 sourceFiles.push(snapshot);
             }

package/dist/orchestrator.d.ts

@@ -10,6 +10,7 @@ export interface ScanReport {
     sourceFiles: number;
     metaFiles: number;
     matFiles: number;
+    spritesheetFiles: number;
     newFiles: string[];
     totalAssets: number;
 }

package/dist/orchestrator.js

@@ -8,6 +8,7 @@ import { readProjectConfig, scanDirectory, readFile, getFileSnapshot, probeImage
 import { detectAssetType, readStowmeta, writeStowmeta, stowmetaToAssetSettings, generateDefaultStowmeta, glbChildToAssetSettings, generateDefaultGlbChild, } from './app/stowmeta-io.js';
 import { parseGlb, pbrToMaterialConfig } from './encoders/glb-loader.js';
 import { readStowmat, stowmatToMaterialConfig } from './app/stowmat-io.js';
+import { readStowSpriteSheet, stowSpriteSheetToConfig } from './app/stowspritesheet-io.js';
 import { readCacheBlobs, writeCacheBlobs, buildCacheStamp, isCacheValid, } from './app/process-cache.js';
 import { buildPack, processExtractedAnimations, validatePackDependencies } from './pipeline.js';
 import { WorkerPool } from './workers/worker-pool.js';
@@ -37,8 +38,9 @@ export async function scanProject(projectDir, opts) {
         sourceFiles: scan.sourceFiles.length,
         metaFiles: scan.metaFiles.length,
         matFiles: scan.matFiles.length,
+        spritesheetFiles: scan.spritesheetFiles.length,
         newFiles,
-        totalAssets: scan.sourceFiles.length + scan.matFiles.length,
+        totalAssets: scan.sourceFiles.length + scan.matFiles.length + scan.spritesheetFiles.length,
     };
 }
 // ─── Full Build ──────────────────────────────────────────────────────────────
@@ -56,7 +58,7 @@ export async function fullBuild(projectDir, opts) {
     // 1. Scan
     const scan = await scanDirectory(config.srcArtDir);
     if (verbose)
-        console.log(`Found ${scan.sourceFiles.length} source files, ${scan.matFiles.length} materials`);
+        console.log(`Found ${scan.sourceFiles.length} source files, ${scan.matFiles.length} materials, ${scan.spritesheetFiles.length} spritesheets`);
     // 2. Build asset list
     const assets = [];
     const assetsById = new Map();
@@ -139,6 +141,33 @@ export async function fullBuild(projectDir, opts) {
         assets.push(asset);
         assetsById.set(id, asset);
     }
+    // SpriteSheets from .stowspritesheet files
+    for (const ssFile of scan.spritesheetFiles) {
+        const id = ssFile.relativePath;
+        const sheet = await readStowSpriteSheet(config.srcArtDir, id);
+        if (!sheet)
+            continue;
+        const spritesheetConfig = stowSpriteSheetToConfig(sheet);
+        const fileName = id.split('/').pop() ?? id;
+        const baseName = fileName.replace(/\.[^.]+$/, '');
+        let meta = await readStowmeta(config.srcArtDir, id);
+        if (!meta) {
+            meta = generateDefaultStowmeta(id, AssetType.SpriteSheet, config.config.defaults);
+            await writeStowmeta(config.srcArtDir, id, meta);
+        }
+        const asset = {
+            id,
+            fileName,
+            stringId: meta.stringId || baseName,
+            type: AssetType.SpriteSheet,
+            status: 'ready',
+            settings: { ...defaultAssetSettings(), spritesheetConfig, pack: meta.pack ?? 'default', tags: meta.tags ?? [] },
+            sourceSize: ssFile.size,
+            processedSize: 0,
+        };
+        assets.push(asset);
+        assetsById.set(id, asset);
+    }
     // 2b. Extract all GLB containers (always re-parse so preserveHierarchy etc. are reflected)
     const glbExtracts = new Map();
     const glbContainers = assets.filter(a => a.type === AssetType.GlbContainer);
@@ -480,6 +509,7 @@ export async function showStatus(projectDir) {
     console.log(`Source dir: ${config.srcArtDir}`);
     console.log(`Source files: ${scan.sourceFiles.length}`);
     console.log(`Material files: ${scan.matFiles.length}`);
+    console.log(`SpriteSheet files: ${scan.spritesheetFiles.length}`);
     console.log(`Meta files: ${scan.metaFiles.length}`);
     const packs = config.config.packs ?? [{ name: 'default' }];
     console.log(`Packs: ${packs.map(p => p.name).join(', ')}`);

package/dist/pipeline.js

@@ -2,7 +2,7 @@ import { AssetType, TextureChannelFormat, TextureResize, AudioSampleRate } from
 import { parseGlb } from './encoders/glb-loader.js';
 import { dracoPresetToSettings } from './encoders/draco-encoder.js';
 import { buildSkinnedMeshData } from './encoders/skinned-mesh-builder.js';
-import { serializeTextureMetadata, serializeAudioMetadata, serializeMeshMetadata, serializeAnimationClipMetadata, serializeSkinnedMeshMetadata, serializeMaterialSchemaMetadata, deserializeSkinnedMeshMetadata, deserializeAnimationClipMetadata, } from './format/metadata.js';
+import { serializeTextureMetadata, serializeAudioMetadata, serializeMeshMetadata, serializeAnimationClipMetadata, serializeSkinnedMeshMetadata, serializeMaterialSchemaMetadata, serializeSpriteSheetMetadata, deserializeSkinnedMeshMetadata, deserializeAnimationClipMetadata, } from './format/metadata.js';
 import { StowPacker } from './format/packer.js';
 import { BlobStore } from './app/blob-store.js';
 // ─── Helpers ────────────────────────────────────────────────────────────────
@@ -267,6 +267,22 @@ export function validatePackDependencies(packAssets, allAssetsById) {
                 }
             }
         }
+        // SpriteSheet: check texture reference
+        if (asset.type === AssetType.SpriteSheet) {
+            const texId = asset.settings.spritesheetConfig.textureAssetId;
+            if (texId) {
+                const tex = allAssetsById.get(texId);
+                if (!tex) {
+                    errors.push({ assetId: asset.id, message: `SpriteSheet "${asset.stringId}" references missing texture "${texId}"` });
+                }
+                else if (tex.settings.excluded) {
+                    errors.push({ assetId: asset.id, message: `SpriteSheet "${asset.stringId}" references excluded texture "${tex.stringId}"` });
+                }
+                else if (!packIds.has(tex.id)) {
+                    errors.push({ assetId: asset.id, message: `SpriteSheet "${asset.stringId}" references texture "${tex.stringId}" which is not in the same pack` });
+                }
+            }
+        }
         // AnimationClip: check target mesh reference
         if (asset.type === AssetType.AnimationClip && asset.settings.targetMeshId) {
             const target = allAssetsById.get(asset.settings.targetMeshId);
@@ -298,6 +314,12 @@ export function buildPack(assets, assetsById) {
             packer.addAsset(asset.stringId, AssetType.MaterialSchema, new Uint8Array(0), schemaBytes, asset.settings.tags);
             continue;
         }
+        if (asset.type === AssetType.SpriteSheet) {
+            const ssMeta = buildSpriteSheetMetadata(asset, assetsById);
+            const ssBytes = serializeSpriteSheetMetadata(ssMeta);
+            packer.addAsset(asset.stringId, AssetType.SpriteSheet, new Uint8Array(0), ssBytes, asset.settings.tags);
+            continue;
+        }
         const processedData = BlobStore.getProcessed(asset.id);
         if (!processedData) {
             console.warn(`[buildPack] Skipping ${asset.id} (type=${asset.type}): no processed data in BlobStore`);
@@ -433,6 +455,20 @@ function buildMaterialSchemaMetadata(asset, assetsById) {
         fields,
     };
 }
+function buildSpriteSheetMetadata(asset, assetsById) {
+    const config = asset.settings.spritesheetConfig;
+    const textureAsset = config.textureAssetId
+        ? assetsById.get(config.textureAssetId)
+        : undefined;
+    return {
+        stringId: asset.stringId,
+        textureId: textureAsset?.stringId ?? '',
+        rows: config.rows,
+        columns: config.columns,
+        frameCount: config.frameCount,
+        frameRate: config.frameRate,
+    };
+}
 // ─── Animation data blob builder (v2) ────────────────────────────────────────
 export function buildAnimationDataBlobsV2(imported) {
     const results = [];

package/dist/server.js

@@ -8,7 +8,8 @@ import { BlobStore } from './app/blob-store.js';
 import { readProjectConfig, scanDirectory, readFile, writeFile, renameFile, deleteFile, getFileSnapshot, probeImageDimensions, } from './node-fs.js';
 import { detectAssetType, readStowmeta, writeStowmeta, stowmetaToAssetSettings, assetSettingsToStowmeta, generateDefaultStowmeta, glbChildToAssetSettings, generateDefaultGlbChild, writeGlbChildSettings, } from './app/stowmeta-io.js';
 import { readStowmat, writeStowmat, stowmatToMaterialConfig, materialConfigToStowmat } from './app/stowmat-io.js';
-import { readCacheBlobs, writeCacheBlobs, buildCacheStamp, isCacheValid, } from './app/process-cache.js';
+import { readStowSpriteSheet, writeStowSpriteSheet, stowSpriteSheetToConfig, spritesheetConfigToStowSpriteSheet } from './app/stowspritesheet-io.js';
+import { readCacheBlobs, writeCacheBlobs, buildCacheStamp, isCacheValid, deleteCacheFile, } from './app/process-cache.js';
 import { buildPack, validatePackDependencies, processExtractedAnimations } from './pipeline.js';
 import { syncRuntimeAssets } from './sync-runtime-assets.js';
 import { parseGlb, pbrToMaterialConfig } from './encoders/glb-loader.js';
@@ -637,8 +638,16 @@ async function openProject(projectDir) {
                             BlobStore.setProcessed(key, data);
                         }
                     }
-                    asset.status = 'ready';
-                    asset.processedSize = BlobStore.getProcessed(file.relativePath)?.length ?? 0;
+                    const processedData = BlobStore.getProcessed(file.relativePath);
+                    if (processedData && processedData.length > 0) {
+                        asset.status = 'ready';
+                        asset.processedSize = processedData.length;
+                    }
+                    else {
+                        // Cache corrupt or missing processed blob — delete and reprocess
+                        console.warn(`[cache] Corrupt cache for ${file.relativePath} — deleting and reprocessing`);
+                        await deleteCacheFile(projectConfig.srcArtDir, file.relativePath);
+                    }
                 }
             }
         }
@@ -680,6 +689,33 @@ async function openProject(projectDir) {
             processedSize: 0,
         });
     }
+    // SpriteSheets from .stowspritesheet files
+    for (const ssFile of scan.spritesheetFiles) {
+        const id = ssFile.relativePath;
+        const sheet = await readStowSpriteSheet(projectConfig.srcArtDir, id);
+        const fileName = id.split('/').pop() ?? id;
+        const baseName = fileName.replace(/\.[^.]+$/, '');
+        let meta = await readStowmeta(projectConfig.srcArtDir, id);
+        if (!meta) {
+            meta = generateDefaultStowmeta(id, AssetType.SpriteSheet, projectConfig.config.defaults);
+            await writeStowmeta(projectConfig.srcArtDir, id, meta);
+        }
+        const spritesheetConfig = sheet ? stowSpriteSheetToConfig(sheet) : { textureAssetId: null, rows: 1, columns: 1, frameCount: 1, frameRate: 12 };
+        const settings = defaultAssetSettings();
+        settings.spritesheetConfig = spritesheetConfig;
+        settings.pack = meta.pack ?? 'default';
+        settings.tags = meta.tags ?? [];
+        assets.push({
+            id,
+            fileName: baseName,
+            stringId: meta.stringId || baseName,
+            type: AssetType.SpriteSheet,
+            status: 'ready',
+            settings,
+            sourceSize: ssFile.size,
+            processedSize: 0,
+        });
+    }
     console.log(`[server] Opened: ${projectConfig.projectName} (${assets.length} assets, ${folders.length} folders)`);
 }
 // ─── Process single asset ─────────────────────────────────────────────────
@@ -945,6 +981,7 @@ async function handleRequest(req, res, staticApps) {
             const diskFiles = new Map([
                 ...scan.sourceFiles.map(f => [f.relativePath, f]),
                 ...scan.matFiles.map(f => [f.relativePath, f]),
+                ...scan.spritesheetFiles.map(f => [f.relativePath, f]),
             ]);
             const diskIds = new Set(diskFiles.keys());
             // Check for added/removed files
@@ -956,7 +993,7 @@ async function handleRequest(req, res, staticApps) {
             const modifiedIds = [];
             if (!changed) {
                 for (const asset of currentAssets) {
-                    if (asset.type === AssetType.MaterialSchema)
+                    if (asset.type === AssetType.MaterialSchema || asset.type === AssetType.SpriteSheet)
                         continue;
                     const diskFile = diskFiles.get(asset.id);
                     if (diskFile && asset.sourceSize > 0 && diskFile.size !== asset.sourceSize) {
@@ -1146,6 +1183,10 @@ async function handleRequest(req, res, staticApps) {
                     const stowmat = materialConfigToStowmat(merged.materialConfig);
                     await writeStowmat(projectConfig.srcArtDir, id, stowmat);
                 }
+                if (asset.type === AssetType.SpriteSheet && body.settings.spritesheetConfig) {
+                    const sheet = spritesheetConfigToStowSpriteSheet(merged.spritesheetConfig);
+                    await writeStowSpriteSheet(projectConfig.srcArtDir, id, sheet);
+                }
             }
         }
         // Check if needs reprocessing
@@ -1551,6 +1592,43 @@ async function handleRequest(req, res, staticApps) {
         json(res, { ok: true, asset });
         return;
     }
+    // POST /api/create-spritesheet
+    if (pathname === '/api/create-spritesheet' && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const body = JSON.parse(await readBody(req));
+        const targetFolder = body.targetFolder ?? '';
+        const name = body.name?.trim() || `SpriteSheet ${assets.filter(a => a.type === AssetType.SpriteSheet).length + 1}`;
+        const baseName = `${name.replace(/\s+/g, '_')}.stowspritesheet`;
+        const fileName = targetFolder ? `${targetFolder}/${baseName}` : baseName;
+        const settings = defaultAssetSettings();
+        settings.spritesheetConfig = {
+            textureAssetId: null,
+            rows: 1,
+            columns: 1,
+            frameCount: 1,
+            frameRate: 12,
+        };
+        const asset = {
+            id: fileName,
+            fileName: name,
+            stringId: name,
+            type: AssetType.SpriteSheet,
+            status: 'ready',
+            settings,
+            sourceSize: 0,
+            processedSize: 0,
+        };
+        assets.push(asset);
+        const stowSpriteSheet = spritesheetConfigToStowSpriteSheet(settings.spritesheetConfig);
+        await writeStowSpriteSheet(projectConfig.srcArtDir, fileName, stowSpriteSheet);
+        const meta = assetSettingsToStowmeta(asset);
+        await writeStowmeta(projectConfig.srcArtDir, fileName, meta);
+        json(res, { ok: true, asset });
+        return;
+    }
     // POST /api/create-folder
     if (pathname === '/api/create-folder' && req.method === 'POST') {
         if (!projectConfig) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.6.38",
+  "version": "0.6.40",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -20,7 +20,7 @@
   "dependencies": {
     "@google/genai": "^1.46.0",
     "@series-inc/stowkit-editor": "^0.1.8",
-    "@series-inc/stowkit-packer-gui": "^0.1.25",
+    "@series-inc/stowkit-packer-gui": "^0.1.30",
     "@strangeape/ffmpeg-audio-wasm": "^0.1.0",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",