@series-inc/stowkit-cli 0.6.39 → 0.6.41

package/dist/ai-tagger.d.ts

@@ -1,4 +1,14 @@
 import { AssetType } from './core/types.js';
+export interface SpriteSheetDetection {
+    isSpriteSheet: boolean;
+    rows?: number;
+    columns?: number;
+}
+/**
+ * Use Gemini Vision to detect whether an image is a sprite sheet.
+ * If it is, returns the detected row/column grid dimensions.
+ */
+export declare function detectSpriteSheet(apiKey: string, imageData: Buffer, mimeType: string): Promise<SpriteSheetDetection>;
 /**
  * Verify that a Gemini API key is valid by making a minimal request.
  */

package/dist/ai-tagger.js

@@ -1,6 +1,7 @@
 import { GoogleGenAI } from '@google/genai';
 import { AssetType } from './core/types.js';
-const MODEL = 'gemini-3.1-flash-lite-preview';
+const MODEL_LITE = 'gemini-3.1-flash-lite-preview';
+const MODEL_FLASH = 'gemini-3.1-pro-preview';
 const ASSET_TYPE_LABELS = {
     [AssetType.Texture2D]: 'texture',
     [AssetType.StaticMesh]: '3D mesh',
@@ -26,6 +27,65 @@ Rules:
 - no generic tags like asset, file, media, content
 - only include tags directly supported by the input`;
 }
+/**
+ * Use Gemini Vision to detect whether an image is a sprite sheet.
+ * If it is, returns the detected row/column grid dimensions.
+ */
+export async function detectSpriteSheet(apiKey, imageData, mimeType) {
+    const client = new GoogleGenAI({ apiKey });
+    const response = await client.models.generateContent({
+        model: MODEL_FLASH,
+        contents: [{
+                role: 'user',
+                parts: [
+                    {
+                        text: `Analyze this image and determine if it is a sprite sheet: a grid of multiple animation frames or game sprites arranged in regular rows and columns.
+
+If it IS a sprite sheet, count the rows and columns of the grid.
+If it is NOT a sprite sheet (e.g. a single image, photo, icon, or seamless texture), respond accordingly.
+
+Respond with ONLY a JSON object:
+- Sprite sheet: { "isSpriteSheet": true, "rows": <number>, "columns": <number> }
+- Not a sprite sheet: { "isSpriteSheet": false }`,
+                    },
+                    {
+                        inlineData: {
+                            data: imageData.toString('base64'),
+                            mimeType,
+                        },
+                    },
+                ],
+            }],
+        config: {
+            temperature: 0.1,
+            maxOutputTokens: 64,
+            responseMimeType: 'application/json',
+            responseSchema: {
+                type: 'OBJECT',
+                properties: {
+                    isSpriteSheet: { type: 'BOOLEAN' },
+                    rows: { type: 'INTEGER' },
+                    columns: { type: 'INTEGER' },
+                },
+                required: ['isSpriteSheet'],
+            },
+            safetySettings: [
+                { category: 'HARM_CATEGORY_HATE_SPEECH', threshold: 'OFF' },
+                { category: 'HARM_CATEGORY_DANGEROUS_CONTENT', threshold: 'OFF' },
+                { category: 'HARM_CATEGORY_SEXUALLY_EXPLICIT', threshold: 'OFF' },
+                { category: 'HARM_CATEGORY_HARASSMENT', threshold: 'OFF' },
+            ],
+        },
+    });
+    const text = response.text ?? '{}';
+    const parsed = JSON.parse(text);
+    return {
+        isSpriteSheet: !!parsed.isSpriteSheet,
+        rows: typeof parsed.rows === 'number' && parsed.rows > 0 ? parsed.rows : undefined,
+        columns: typeof parsed.columns === 'number' && parsed.columns > 0 ? parsed.columns : undefined,
+    };
+}
+// ─── API Key Verification ─────────────────────────────────────────────────────
 /**
  * Verify that a Gemini API key is valid by making a minimal request.
  */
@@ -33,7 +93,7 @@ export async function verifyApiKey(apiKey) {
     try {
         const client = new GoogleGenAI({ apiKey });
         const response = await client.models.generateContent({
-            model: MODEL,
+            model: MODEL_LITE,
             contents: [{ role: 'user', parts: [{ text: 'Respond with the word "ok"' }] }],
             config: { maxOutputTokens: 10 },
         });
@@ -51,7 +111,7 @@ export async function verifyApiKey(apiKey) {
 export async function tagAsset(apiKey, assetType, fileName, inputData, mimeType) {
     const client = new GoogleGenAI({ apiKey });
     const response = await client.models.generateContent({
-        model: MODEL,
+        model: MODEL_LITE,
         contents: [{
                 role: 'user',
                 parts: [

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/cli.js

@@ -78,6 +78,7 @@ Usage:
   stowkit init [dir]              Initialize a StowKit project (interactive menu)
   stowkit init --with-engine      Initialize with 3D engine included
   stowkit init --no-engine        Initialize without 3D engine (skip prompt)
+  stowkit init --with-publish     Initialize with assets-package.json for publishing
   stowkit init --update [dir]     Update AI skill files to match installed CLI version
   stowkit build [dir]             Full build: scan + process + pack
   stowkit scan [dir]              Detect new assets, generate .stowmeta defaults
@@ -175,6 +176,7 @@ async function main() {
                     update: args.includes('--update'),
                     withEngine: args.includes('--with-engine'),
                     noEngine: args.includes('--no-engine'),
+                    withPublish: args.includes('--with-publish'),
                 });
                 break;
             case 'update': {

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/init.d.ts

@@ -2,5 +2,6 @@ export interface InitOptions {
     update?: boolean;
     withEngine?: boolean;
     noEngine?: boolean;
+    withPublish?: boolean;
 }
 export declare function initProject(projectDir: string, opts?: InitOptions): Promise<void>;

package/dist/init.js

@@ -153,6 +153,12 @@ export async function initProject(projectDir, opts) {
     if (withEngine) {
         await installEngine(absDir);
     }
+    // Create assets-package.json for publishing
+    if (opts?.withPublish) {
+        const { initAssetsPackage } = await import('./assets-package.js');
+        await initAssetsPackage(absDir, { name: path.basename(absDir) });
+        console.log(`  Publish config: assets-package.json`);
+    }
     console.log('');
     if (withEngine) {
         console.log('Ready to go! Run:');

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

@@ -1,6 +1,7 @@
 import * as http from 'node:http';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import { exec } from 'node:child_process';
 import { WebSocketServer, WebSocket } from 'ws';
 import { AssetType } from './core/types.js';
 import { defaultAssetSettings } from './app/state.js';
@@ -8,6 +9,7 @@ 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 { 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';
@@ -563,6 +565,68 @@ async function readBinaryBody(req) {
         chunks.push(chunk);
     return Buffer.concat(chunks);
 }
+// ─── SpriteSheet grid detection ──────────────────────────────────────────────
+const COMMON_TILE_SIZES = [16, 32, 48, 64, 128];
+function detectSpriteGrid(width, height) {
+    const result = detectGridDimensions(width, height);
+    if (result)
+        return { ...result, frameCount: result.columns * result.rows };
+    // Absolute fallback: single frame
+    return { columns: 1, rows: 1, frameCount: 1 };
+}
+function detectGridDimensions(width, height) {
+    // 1. Try common square tile sizes (covers most character/monster/item sheets)
+    for (const tile of COMMON_TILE_SIZES) {
+        if (width % tile === 0 && height % tile === 0) {
+            return { columns: width / tile, rows: height / tile };
+        }
+    }
+    // 2. Square frames where frame_size = height (single-row FX sheets)
+    if (height < width && width % height === 0) {
+        return { columns: width / height, rows: 1 };
+    }
+    // 3. Near-square single-row: find frame width closest to height among width's divisors
+    if (height < 64 && width > height * 1.5) {
+        const match = findBestSingleRowCols(width, height);
+        if (match)
+            return { columns: match, rows: 1 };
+    }
+    // 4. Non-square common tile combos
+    for (const th of COMMON_TILE_SIZES) {
+        if (height % th === 0) {
+            const rows = height / th;
+            for (const tw of COMMON_TILE_SIZES) {
+                if (width % tw === 0)
+                    return { columns: width / tw, rows };
+            }
+        }
+    }
+    // 5. frame_width = 16 with non-standard height
+    if (width % 16 === 0)
+        return { columns: width / 16, rows: 1 };
+    // 6. Near-square fallback for any size
+    const cols = findBestSingleRowCols(width, height);
+    if (cols)
+        return { columns: cols, rows: 1 };
+    return null;
+}
+function findBestSingleRowCols(width, height) {
+    let bestCloseness = Infinity;
+    let bestCols = null;
+    for (let cols = 1; cols <= width; cols++) {
+        if (width % cols !== 0)
+            continue;
+        const fw = width / cols;
+        if (fw < height * 0.4 || fw > height * 2.5)
+            continue;
+        const closeness = Math.abs(fw / height - 1.0);
+        if (closeness < bestCloseness) {
+            bestCloseness = closeness;
+            bestCols = cols;
+        }
+    }
+    return bestCloseness < 0.6 ? bestCols : null;
+}
 function json(res, data, status = 200) {
     res.writeHead(status, {
         'Content-Type': 'application/json',
@@ -688,6 +752,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 ─────────────────────────────────────────────────
@@ -953,6 +1044,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
@@ -964,7 +1056,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) {
@@ -1154,6 +1246,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
@@ -1423,6 +1519,34 @@ async function handleRequest(req, res, staticApps) {
         json(res, { ok: true, removedAssets: removedIds.length });
         return;
     }
+    // POST /api/reveal — open file or folder in OS file explorer
+    if (pathname === '/api/reveal' && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const body = JSON.parse(await readBody(req));
+        const relativePath = body.path;
+        if (!relativePath) {
+            json(res, { error: 'Missing path' }, 400);
+            return;
+        }
+        const fullPath = path.resolve(projectConfig.srcArtDir, relativePath);
+        // Ensure the path is inside the project
+        if (!fullPath.startsWith(path.resolve(projectConfig.srcArtDir))) {
+            json(res, { error: 'Path outside project' }, 403);
+            return;
+        }
+        const stat = await fs.stat(fullPath).catch(() => null);
+        if (stat?.isDirectory()) {
+            exec(`explorer "${fullPath}"`);
+        }
+        else {
+            exec(`explorer /select,"${fullPath}"`);
+        }
+        json(res, { ok: true });
+        return;
+    }
     // GET /api/asset/:id/source — serve source file for preview
     if (pathname.startsWith('/api/asset/') && pathname.endsWith('/source') && req.method === 'GET') {
         const id = decodeURIComponent(pathname.slice('/api/asset/'.length, -'/source'.length));
@@ -1559,6 +1683,210 @@ 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/convert-to-spritesheet — auto-detect grid from a texture and create a .stowspritesheet
+    if (pathname === '/api/convert-to-spritesheet' && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const body = JSON.parse(await readBody(req));
+        const textureId = body.textureId;
+        if (!textureId) {
+            json(res, { error: 'Missing textureId' }, 400);
+            return;
+        }
+        const textureAsset = assets.find(a => a.id === textureId);
+        if (!textureAsset || textureAsset.type !== AssetType.Texture2D) {
+            json(res, { error: 'Asset is not a texture' }, 400);
+            return;
+        }
+        // Use caller-supplied grid override, otherwise heuristic-detect from image dimensions
+        let rows;
+        let columns;
+        if (typeof body.rows === 'number' && body.rows > 0 && typeof body.columns === 'number' && body.columns > 0) {
+            rows = body.rows;
+            columns = body.columns;
+        }
+        else {
+            const dims = await probeImageDimensions(projectConfig.srcArtDir, textureId);
+            if (!dims) {
+                json(res, { error: 'Could not read image dimensions' }, 500);
+                return;
+            }
+            ({ rows, columns } = detectSpriteGrid(dims.width, dims.height));
+        }
+        const frameCount = rows * columns;
+        // Build name: foldername_imagename_animation
+        const parts = textureId.replace(/\\/g, '/').split('/');
+        const stem = parts[parts.length - 1].replace(/\.[^.]+$/, '').replace(/^SpriteSheet/, '').replace(/^spritesheet/i, '');
+        const folder = parts.length >= 2 ? parts[parts.length - 2] : '';
+        const safeName = [folder, stem].filter(Boolean).join('_').replace(/\s+/g, '_').toLowerCase();
+        const sheetName = `${safeName}_animation`;
+        const targetFolder = parts.slice(0, -1).join('/');
+        const baseName = `${sheetName}.stowspritesheet`;
+        const fileName = targetFolder ? `${targetFolder}/${baseName}` : baseName;
+        // Check if already exists
+        if (assets.find(a => a.id === fileName)) {
+            json(res, { error: `Spritesheet already exists: ${fileName}` }, 409);
+            return;
+        }
+        const settings = defaultAssetSettings();
+        settings.spritesheetConfig = {
+            textureAssetId: textureId,
+            rows,
+            columns,
+            frameCount,
+            frameRate: 12,
+        };
+        const asset = {
+            id: fileName,
+            fileName: sheetName,
+            stringId: fileName.replace(/\.[^.]+$/, '').toLowerCase(),
+            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);
+        broadcast({ type: 'refresh' });
+        json(res, { ok: true, asset });
+        return;
+    }
+    // POST /api/batch-convert-folder-name — find all folders matching a name and convert all textures under them to sprite sheets
+    if (pathname === '/api/batch-convert-folder-name' && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const body = JSON.parse(await readBody(req));
+        const folderName = body.folderName;
+        if (!folderName) {
+            json(res, { error: 'Missing folderName' }, 400);
+            return;
+        }
+        // Find all folders that match the given name (case-insensitive)
+        const matchingFolders = folders.filter(f => {
+            const parts = f.replace(/\\/g, '/').split('/');
+            return parts[parts.length - 1].toLowerCase() === folderName.toLowerCase();
+        });
+        if (matchingFolders.length === 0) {
+            json(res, { error: `No folders found matching "${folderName}"` }, 404);
+            return;
+        }
+        // Find all Texture2D assets under any of the matching folders
+        const textureIds = [];
+        for (const folder of matchingFolders) {
+            const prefix = folder + '/';
+            for (const asset of assets) {
+                if (asset.type === AssetType.Texture2D && (asset.id.startsWith(prefix) || asset.id.replace(/\\/g, '/').startsWith(prefix))) {
+                    textureIds.push(asset.id);
+                }
+            }
+        }
+        if (textureIds.length === 0) {
+            json(res, { error: `No textures found under folders matching "${folderName}"` }, 404);
+            return;
+        }
+        // Convert each texture to a sprite sheet (reuse the same logic as convert-to-spritesheet)
+        let succeeded = 0;
+        let failed = 0;
+        const created = [];
+        for (const textureId of textureIds) {
+            const textureAsset = assets.find(a => a.id === textureId);
+            if (!textureAsset) {
+                failed++;
+                continue;
+            }
+            const dims = await probeImageDimensions(projectConfig.srcArtDir, textureId);
+            if (!dims) {
+                failed++;
+                continue;
+            }
+            const { columns, rows, frameCount } = detectSpriteGrid(dims.width, dims.height);
+            const parts = textureId.replace(/\\/g, '/').split('/');
+            const stem = parts[parts.length - 1].replace(/\.[^.]+$/, '').replace(/^SpriteSheet/, '').replace(/^spritesheet/i, '');
+            const folder = parts.length >= 2 ? parts[parts.length - 2] : '';
+            const safeName = [folder, stem].filter(Boolean).join('_').replace(/\s+/g, '_').toLowerCase();
+            const sheetName = `${safeName}_animation`;
+            const targetFolder = parts.slice(0, -1).join('/');
+            const baseName = `${sheetName}.stowspritesheet`;
+            const fileName = targetFolder ? `${targetFolder}/${baseName}` : baseName;
+            if (assets.find(a => a.id === fileName)) {
+                failed++;
+                continue;
+            }
+            const settings = defaultAssetSettings();
+            settings.spritesheetConfig = {
+                textureAssetId: textureId,
+                rows,
+                columns,
+                frameCount,
+                frameRate: 12,
+            };
+            const asset = {
+                id: fileName,
+                fileName: sheetName,
+                stringId: fileName.replace(/\.[^.]+$/, '').toLowerCase(),
+                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);
+            created.push(asset);
+            succeeded++;
+        }
+        broadcast({ type: 'refresh' });
+        json(res, { ok: true, succeeded, failed, matchingFolders, assets: created });
+        return;
+    }
     // POST /api/create-folder
     if (pathname === '/api/create-folder' && req.method === 'POST') {
         if (!projectConfig) {
@@ -1973,6 +2301,31 @@ async function handleRequest(req, res, staticApps) {
         }
         return;
     }
+    // POST /api/asset-store/package/:name/delist — remove package from registry (keeps GCS files)
+    if (pathname.startsWith('/api/asset-store/package/') && pathname.endsWith('/delist') && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        try {
+            const packageName = decodeURIComponent(pathname.slice('/api/asset-store/package/'.length, -'/delist'.length));
+            const { createFirestoreClient } = await import('./firestore.js');
+            const firestore = await createFirestoreClient(projectConfig.projectDir);
+            const pkg = await firestore.getPackage(packageName);
+            if (!pkg) {
+                json(res, { error: `Package "${packageName}" not found` }, 404);
+                return;
+            }
+            await firestore.deletePackage(packageName);
+            const { clearFirestoreCache } = await import('./firestore.js');
+            clearFirestoreCache();
+            json(res, { ok: true, packageName });
+        }
+        catch (err) {
+            json(res, { error: err.message }, 500);
+        }
+        return;
+    }
     // POST /api/publish — publish assets to GCS (SSE stream with progress)
     if (pathname === '/api/publish' && req.method === 'POST') {
         if (!projectConfig) {
@@ -2300,6 +2653,159 @@ async function handleRequest(req, res, staticApps) {
         }
         return;
     }
+    // POST /api/ai/guess-spritesheet-grid/:id — ask Gemini to count rows/columns on a texture without creating anything
+    if (pathname.startsWith('/api/ai/guess-spritesheet-grid/') && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const apiKey = projectConfig.config.ai?.geminiApiKey;
+        if (!apiKey) {
+            json(res, { error: 'Gemini API key not configured' }, 400);
+            return;
+        }
+        const id = decodeURIComponent(pathname.slice('/api/ai/guess-spritesheet-grid/'.length));
+        const asset = assets.find(a => a.id === id);
+        if (!asset || asset.type !== AssetType.Texture2D) {
+            json(res, { error: 'Asset is not a texture' }, 404);
+            return;
+        }
+        try {
+            const raw = await readFile(projectConfig.srcArtDir, id);
+            if (!raw) {
+                json(res, { error: 'Source file not found' }, 404);
+                return;
+            }
+            const ext = id.split('.').pop()?.toLowerCase() ?? 'png';
+            const mimeMap = {
+                png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif',
+            };
+            const mimeType = mimeMap[ext] ?? 'image/png';
+            const { detectSpriteSheet: aiDetectSpriteSheet } = await import('./ai-tagger.js');
+            const detection = await aiDetectSpriteSheet(apiKey, Buffer.from(raw), mimeType);
+            if (detection.isSpriteSheet && detection.rows && detection.columns) {
+                json(res, { rows: detection.rows, columns: detection.columns });
+            }
+            else {
+                // Fall back to heuristic
+                const dims = await probeImageDimensions(projectConfig.srcArtDir, id);
+                const grid = dims ? detectSpriteGrid(dims.width, dims.height) : { rows: 1, columns: 1 };
+                json(res, { rows: grid.rows, columns: grid.columns });
+            }
+        }
+        catch (err) {
+            json(res, { error: err.message }, 500);
+        }
+        return;
+    }
+    // POST /api/ai/detect-spritesheet-batch — use Gemini to detect sprite sheets across multiple textures concurrently
+    if (pathname === '/api/ai/detect-spritesheet-batch' && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const apiKey = projectConfig.config.ai?.geminiApiKey;
+        if (!apiKey) {
+            json(res, { error: 'Gemini API key not configured' }, 400);
+            return;
+        }
+        try {
+            const body = JSON.parse(await readBody(req));
+            const ids = body.ids;
+            if (!Array.isArray(ids) || ids.length === 0) {
+                json(res, { error: 'ids must be a non-empty array' }, 400);
+                return;
+            }
+            const { detectSpriteSheet: aiDetectSpriteSheet } = await import('./ai-tagger.js');
+            const mimeMap = {
+                png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif',
+            };
+            let created = 0;
+            let notSpriteSheet = 0;
+            let alreadyExists = 0;
+            const errors = [];
+            const results = await Promise.allSettled(ids.map(async (id) => {
+                const asset = assets.find(a => a.id === id);
+                if (!asset || asset.type !== AssetType.Texture2D)
+                    throw new Error('Not a texture');
+                const raw = await readFile(projectConfig.srcArtDir, id);
+                if (!raw)
+                    throw new Error(`Source file not found: ${id}`);
+                const ext = id.split('.').pop()?.toLowerCase() ?? 'png';
+                const mimeType = mimeMap[ext] ?? 'image/png';
+                const detection = await aiDetectSpriteSheet(apiKey, Buffer.from(raw), mimeType);
+                if (!detection.isSpriteSheet)
+                    return 'notSpriteSheet';
+                // Use AI-detected grid, falling back to heuristic
+                let rows;
+                let columns;
+                if (detection.rows && detection.columns) {
+                    rows = detection.rows;
+                    columns = detection.columns;
+                }
+                else {
+                    const dims = await probeImageDimensions(projectConfig.srcArtDir, id);
+                    if (!dims)
+                        throw new Error('Could not read image dimensions');
+                    const grid = detectSpriteGrid(dims.width, dims.height);
+                    rows = grid.rows;
+                    columns = grid.columns;
+                }
+                const frameCount = rows * columns;
+                const parts = id.replace(/\\/g, '/').split('/');
+                const stem = parts[parts.length - 1].replace(/\.[^.]+$/, '').replace(/^SpriteSheet/, '').replace(/^spritesheet/i, '');
+                const folder = parts.length >= 2 ? parts[parts.length - 2] : '';
+                const safeName = [folder, stem].filter(Boolean).join('_').replace(/\s+/g, '_').toLowerCase();
+                const sheetName = `${safeName}_animation`;
+                const targetFolder = parts.slice(0, -1).join('/');
+                const baseName = `${sheetName}.stowspritesheet`;
+                const fileName = targetFolder ? `${targetFolder}/${baseName}` : baseName;
+                if (assets.find(a => a.id === fileName))
+                    return 'alreadyExists';
+                const settings = defaultAssetSettings();
+                settings.spritesheetConfig = { textureAssetId: id, rows, columns, frameCount, frameRate: 12 };
+                const newAsset = {
+                    id: fileName,
+                    fileName: sheetName,
+                    stringId: fileName.replace(/\.[^.]+$/, '').toLowerCase(),
+                    type: AssetType.SpriteSheet,
+                    status: 'ready',
+                    settings,
+                    sourceSize: 0,
+                    processedSize: 0,
+                };
+                assets.push(newAsset);
+                const stowSpriteSheet = spritesheetConfigToStowSpriteSheet(settings.spritesheetConfig);
+                await writeStowSpriteSheet(projectConfig.srcArtDir, fileName, stowSpriteSheet);
+                const newMeta = assetSettingsToStowmeta(newAsset);
+                await writeStowmeta(projectConfig.srcArtDir, fileName, newMeta);
+                return 'created';
+            }));
+            for (let i = 0; i < results.length; i++) {
+                const r = results[i];
+                if (r.status === 'fulfilled') {
+                    if (r.value === 'created')
+                        created++;
+                    else if (r.value === 'notSpriteSheet')
+                        notSpriteSheet++;
+                    else if (r.value === 'alreadyExists')
+                        alreadyExists++;
+                }
+                else {
+                    const errMsg = r.reason?.message ?? String(r.reason);
+                    console.error(`[ai-detect-spritesheet] ${ids[i]}: ${errMsg}`);
+                    errors.push({ id: ids[i], error: errMsg });
+                }
+            }
+            if (created > 0)
+                broadcast({ type: 'refresh' });
+            json(res, { created, notSpriteSheet, alreadyExists, errors });
+        }
+        catch (err) {
+            json(res, { error: err.message }, 500);
+        }
+        return;
+    }
     // GET /api/thumbnails/cached — return which thumbnails are still valid in the cache
     if (pathname === '/api/thumbnails/cached' && req.method === 'GET') {
         if (!projectConfig) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.6.39",
+  "version": "0.6.41",
   "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.26",
+    "@series-inc/stowkit-packer-gui": "^0.1.30",
     "@strangeape/ffmpeg-audio-wasm": "^0.1.0",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",