@series-inc/stowkit-cli 0.6.17 → 0.6.19

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

@@ -1,13 +1,32 @@
-import type { KTX2Quality, TextureResize, DracoQualityPreset, AacQuality, AudioSampleRate, MaterialFieldType, PreviewPropertyFlag } from '../core/types.js';
+import type { KTX2Quality, TextureResize, TextureFilterMode, DracoQualityPreset, AacQuality, AudioSampleRate, MaterialFieldType, PreviewPropertyFlag } from '../core/types.js';
 export interface PackConfig {
     name: string;
 }
+export interface TextureDefaults {
+    quality?: string;
+    resize?: string;
+    filtering?: string;
+    generateMipmaps?: boolean;
+}
+export interface AudioDefaults {
+    aacQuality?: string;
+    sampleRate?: string;
+}
+export interface MeshDefaults {
+    dracoQuality?: string;
+}
+export interface ProjectDefaults {
+    texture?: TextureDefaults;
+    audio?: AudioDefaults;
+    mesh?: MeshDefaults;
+}
 export interface FelicityProject {
     srcArtDir: string;
     name?: string;
     cdnAssetsPath?: string;
     prefabsPath?: string;
     packs?: PackConfig[];
+    defaults?: ProjectDefaults;
 }
 export interface FileSnapshot {
     relativePath: string;
@@ -33,6 +52,7 @@ export interface StowMetaTexture extends StowMetaBase {
     type: 'texture';
     quality: string;
     resize: string;
+    filtering?: string;
     generateMipmaps: boolean;
 }
 export interface StowMetaAudio extends StowMetaBase {
@@ -67,6 +87,7 @@ export interface StowMetaGlbChild {
     cache?: StowMetaCache;
     quality?: string;
     resize?: string;
+    filtering?: string;
     generateMipmaps?: boolean;
     aacQuality?: string;
     sampleRate?: string;
@@ -101,6 +122,8 @@ 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>;
 export declare const TEXTURE_RESIZE_TO_STRING: Record<number, string>;
+export declare const TEXTURE_FILTER_STRINGS: Record<string, TextureFilterMode>;
+export declare const TEXTURE_FILTER_TO_STRING: Record<number, string>;
 export declare const DRACO_QUALITY_STRINGS: Record<string, DracoQualityPreset>;
 export declare const DRACO_QUALITY_TO_STRING: Record<number, string>;
 export declare const AAC_QUALITY_STRINGS: Record<string, AacQuality>;

package/dist/app/disk-project.js

@@ -18,6 +18,13 @@ export const TEXTURE_RESIZE_STRINGS = {
 export const TEXTURE_RESIZE_TO_STRING = {
     0: 'full', 1: 'half', 2: 'quarter', 3: 'eighth',
 };
+export const TEXTURE_FILTER_STRINGS = {
+    linear: 0,
+    nearest: 1,
+};
+export const TEXTURE_FILTER_TO_STRING = {
+    0: 'linear', 1: 'nearest',
+};
 export const DRACO_QUALITY_STRINGS = {
     fast: 0,
     balanced: 1,

package/dist/app/process-cache.js

@@ -96,7 +96,7 @@ export function computeSettingsHash(type, settings) {
     const parts = [String(type)];
     switch (type) {
         case 2: // Texture2D
-            parts.push(`q=${settings.quality}`, `r=${settings.resize}`, `m=${settings.generateMipmaps}`);
+            parts.push(`q=${settings.quality}`, `r=${settings.resize}`, `f=${settings.filtering}`, `m=${settings.generateMipmaps}`);
             break;
         case 3: // Audio
             parts.push(`aq=${settings.aacQuality}`, `sr=${settings.audioSampleRate}`);

package/dist/app/state.d.ts

@@ -1,4 +1,4 @@
-import type { AssetType, TextureMetadata, AudioMetadata, MeshMetadata, AnimationClipMetadata, SkinnedMeshMetadata, KTX2Quality, TextureResize, DracoQualityPreset, AacQuality, AudioSampleRate, MaterialFieldType, PreviewPropertyFlag } from '../core/types.js';
+import type { AssetType, TextureMetadata, AudioMetadata, MeshMetadata, AnimationClipMetadata, SkinnedMeshMetadata, KTX2Quality, TextureResize, TextureFilterMode, DracoQualityPreset, AacQuality, AudioSampleRate, MaterialFieldType, PreviewPropertyFlag } from '../core/types.js';
 export interface MaterialProperty {
     fieldName: string;
     fieldType: MaterialFieldType;
@@ -13,6 +13,7 @@ export interface MaterialConfig {
 export interface AssetSettings {
     quality: KTX2Quality;
     resize: TextureResize;
+    filtering: TextureFilterMode;
     generateMipmaps: boolean;
     tags: string[];
     dracoQuality: DracoQualityPreset;

package/dist/app/state.js

@@ -1,8 +1,9 @@
-import { KTX2Quality as KQ, TextureResize as TR, DracoQualityPreset as DQ, AacQuality as AQ, AudioSampleRate as ASR, } from '../core/types.js';
+import { KTX2Quality as KQ, TextureResize as TR, TextureFilterMode as TFM, DracoQualityPreset as DQ, AacQuality as AQ, AudioSampleRate as ASR, } from '../core/types.js';
 export function defaultAssetSettings() {
     return {
         quality: KQ.Fastest,
         resize: TR.Full,
+        filtering: TFM.Linear,
         generateMipmaps: false,
         tags: [],
         dracoQuality: DQ.Balanced,

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

@@ -1,7 +1,7 @@
 import type { AssetSettings } from './state.js';
 import { AssetType } from '../core/types.js';
 import type { ProjectAsset } from './state.js';
-import type { StowMeta, StowMetaGlbChild } from './disk-project.js';
+import type { ProjectDefaults, StowMeta, StowMetaGlbChild } from './disk-project.js';
 export declare function detectAssetType(fileName: string): AssetType;
 export declare function stowmetaPath(relativePath: string): string;
 export declare function readStowmeta(srcArtDir: string, relativePath: string): Promise<StowMeta | null>;
@@ -11,9 +11,12 @@ export declare function stowmetaToAssetSettings(meta: StowMeta): {
     settings: AssetSettings;
 };
 export declare function assetSettingsToStowmeta(asset: ProjectAsset): StowMeta;
-export declare function generateDefaultStowmeta(relativePath: string, type?: AssetType): StowMeta;
+export declare function generateDefaultStowmeta(relativePath: string, type?: AssetType, projectDefaults?: ProjectDefaults, imageDimensions?: {
+    width: number;
+    height: number;
+} | null): StowMeta;
 /** Generate a default inline child entry for a GLB container. */
-export declare function generateDefaultGlbChild(name: string, childType: string): StowMetaGlbChild;
+export declare function generateDefaultGlbChild(name: string, childType: string, projectDefaults?: ProjectDefaults): StowMetaGlbChild;
 /** Convert an inline child entry to { type, settings } for use in ProjectAsset. */
 export declare function glbChildToAssetSettings(child: StowMetaGlbChild): {
     type: AssetType;

package/dist/app/stowmeta-io.js

@@ -1,6 +1,6 @@
 import { AssetType } from '../core/types.js';
-import { KTX2Quality, TextureResize, DracoQualityPreset, AacQuality, AudioSampleRate, MaterialFieldType, PreviewPropertyFlag } from '../core/types.js';
-import { KTX2_QUALITY_STRINGS, KTX2_QUALITY_TO_STRING, TEXTURE_RESIZE_STRINGS, TEXTURE_RESIZE_TO_STRING, DRACO_QUALITY_STRINGS, DRACO_QUALITY_TO_STRING, AAC_QUALITY_STRINGS, AAC_QUALITY_TO_STRING, AUDIO_SAMPLE_RATE_STRINGS, AUDIO_SAMPLE_RATE_TO_STRING, MATERIAL_FIELD_TYPE_STRINGS, MATERIAL_FIELD_TYPE_TO_STRING, PREVIEW_FLAG_STRINGS, PREVIEW_FLAG_TO_STRING, } from './disk-project.js';
+import { KTX2Quality, TextureResize, TextureFilterMode, DracoQualityPreset, AacQuality, AudioSampleRate, MaterialFieldType, PreviewPropertyFlag } from '../core/types.js';
+import { KTX2_QUALITY_STRINGS, KTX2_QUALITY_TO_STRING, TEXTURE_RESIZE_STRINGS, TEXTURE_RESIZE_TO_STRING, TEXTURE_FILTER_STRINGS, TEXTURE_FILTER_TO_STRING, DRACO_QUALITY_STRINGS, DRACO_QUALITY_TO_STRING, AAC_QUALITY_STRINGS, AAC_QUALITY_TO_STRING, AUDIO_SAMPLE_RATE_STRINGS, AUDIO_SAMPLE_RATE_TO_STRING, MATERIAL_FIELD_TYPE_STRINGS, MATERIAL_FIELD_TYPE_TO_STRING, PREVIEW_FLAG_STRINGS, PREVIEW_FLAG_TO_STRING, } from './disk-project.js';
 import { readTextFile, writeFile } from '../node-fs.js';
 import { defaultAssetSettings } from './state.js';
 // ─── Detect asset type from file extension ──────────────────────────────────
@@ -70,6 +70,7 @@ export function stowmetaToAssetSettings(meta) {
                     ...base,
                     quality: KTX2_QUALITY_STRINGS[meta.quality] ?? KTX2Quality.Fastest,
                     resize: TEXTURE_RESIZE_STRINGS[meta.resize] ?? TextureResize.Full,
+                    filtering: TEXTURE_FILTER_STRINGS[meta.filtering ?? 'linear'] ?? TextureFilterMode.Linear,
                     generateMipmaps: meta.generateMipmaps ?? false,
                 },
             };
@@ -152,6 +153,7 @@ export function assetSettingsToStowmeta(asset) {
                 type: 'texture',
                 quality: KTX2_QUALITY_TO_STRING[asset.settings.quality] ?? 'fastest',
                 resize: TEXTURE_RESIZE_TO_STRING[asset.settings.resize] ?? 'full',
+                filtering: TEXTURE_FILTER_TO_STRING[asset.settings.filtering] ?? 'linear',
                 generateMipmaps: asset.settings.generateMipmaps,
             };
         case AssetType.Audio:
@@ -196,11 +198,12 @@ function serializeMaterialOverrides(overrides) {
     return result;
 }
 // ─── Generate default .stowmeta ─────────────────────────────────────────────
-export function generateDefaultStowmeta(relativePath, type) {
+export function generateDefaultStowmeta(relativePath, type, projectDefaults, imageDimensions) {
     const fileName = relativePath.split('/').pop() ?? relativePath;
     const resolvedType = type ?? detectAssetType(fileName);
-    const baseName = fileName.replace(/\.[^.]+$/, '');
-    const stringId = resolvedType === AssetType.MaterialSchema ? baseName : baseName.toLowerCase();
+    // Use full relative path (minus extension) as stringId to avoid collisions across folders
+    const pathWithoutExt = relativePath.replace(/\.[^.]+$/, '');
+    const stringId = resolvedType === AssetType.MaterialSchema ? pathWithoutExt : pathWithoutExt.toLowerCase();
     const base = {
         version: 1,
         stringId,
@@ -208,12 +211,39 @@ export function generateDefaultStowmeta(relativePath, type) {
         pack: 'default',
     };
     switch (resolvedType) {
-        case AssetType.Texture2D:
-            return { ...base, type: 'texture', quality: 'fastest', resize: 'quarter', generateMipmaps: false };
-        case AssetType.Audio:
-            return { ...base, type: 'audio', aacQuality: 'medium', sampleRate: 'auto' };
-        case AssetType.StaticMesh:
-            return { ...base, type: 'staticMesh', dracoQuality: 'balanced', materialOverrides: {} };
+        case AssetType.Texture2D: {
+            const textureDefaults = projectDefaults?.texture;
+            const isSmall = imageDimensions != null
+                && imageDimensions.width <= 256
+                && imageDimensions.height <= 256;
+            const defaultResize = isSmall ? 'full' : 'quarter';
+            return {
+                ...base,
+                type: 'texture',
+                quality: textureDefaults?.quality ?? 'fastest',
+                resize: textureDefaults?.resize ?? defaultResize,
+                filtering: textureDefaults?.filtering ?? 'linear',
+                generateMipmaps: textureDefaults?.generateMipmaps ?? false,
+            };
+        }
+        case AssetType.Audio: {
+            const audioDefaults = projectDefaults?.audio;
+            return {
+                ...base,
+                type: 'audio',
+                aacQuality: audioDefaults?.aacQuality ?? 'medium',
+                sampleRate: audioDefaults?.sampleRate ?? 'auto',
+            };
+        }
+        case AssetType.StaticMesh: {
+            const meshDefaults = projectDefaults?.mesh;
+            return {
+                ...base,
+                type: 'staticMesh',
+                dracoQuality: meshDefaults?.dracoQuality ?? 'balanced',
+                materialOverrides: {},
+            };
+        }
         case AssetType.SkinnedMesh:
             return { ...base, type: 'skinnedMesh', materialOverrides: {} };
         case AssetType.AnimationClip:
@@ -228,23 +258,32 @@ export function generateDefaultStowmeta(relativePath, type) {
 }
 // ─── GLB Inline Child Helpers ───────────────────────────────────────────────
 /** Generate a default inline child entry for a GLB container. */
-export function generateDefaultGlbChild(name, childType) {
+export function generateDefaultGlbChild(name, childType, projectDefaults) {
     const baseName = name.replace(/\.[^.]+$/, '');
     const stringId = childType === 'materialSchema' ? baseName : baseName.toLowerCase();
     const child = { name, childType, stringId };
     switch (childType) {
-        case 'texture':
-            child.quality = 'fastest';
-            child.resize = 'quarter';
-            child.generateMipmaps = false;
+        case 'texture': {
+            const textureDefaults = projectDefaults?.texture;
+            child.quality = textureDefaults?.quality ?? 'fastest';
+            child.resize = textureDefaults?.resize ?? 'quarter';
+            child.filtering = textureDefaults?.filtering ?? 'linear';
+            child.generateMipmaps = textureDefaults?.generateMipmaps ?? false;
             break;
-        case 'audio':
-            child.aacQuality = 'medium';
-            child.sampleRate = 'auto';
+        }
+        case 'audio': {
+            const audioDefaults = projectDefaults?.audio;
+            child.aacQuality = audioDefaults?.aacQuality ?? 'medium';
+            child.sampleRate = audioDefaults?.sampleRate ?? 'auto';
             break;
-        case 'staticMesh':
+        }
+        case 'staticMesh': {
+            const meshDefaults = projectDefaults?.mesh;
+            child.dracoQuality = meshDefaults?.dracoQuality ?? 'balanced';
+            child.materialOverrides = {};
+            break;
+        }
         case 'skinnedMesh':
-            child.dracoQuality = 'balanced';
             child.materialOverrides = {};
             break;
         case 'animationClip':
@@ -269,6 +308,7 @@ export function glbChildToAssetSettings(child) {
                     ...base,
                     quality: KTX2_QUALITY_STRINGS[child.quality ?? 'fastest'] ?? KTX2Quality.Fastest,
                     resize: TEXTURE_RESIZE_STRINGS[child.resize ?? 'full'] ?? TextureResize.Full,
+                    filtering: TEXTURE_FILTER_STRINGS[child.filtering ?? 'linear'] ?? TextureFilterMode.Linear,
                     generateMipmaps: child.generateMipmaps ?? false,
                 },
             };
@@ -342,6 +382,7 @@ export function assetSettingsToGlbChild(name, childType, stringId, settings, exi
         case 'texture':
             child.quality = KTX2_QUALITY_TO_STRING[settings.quality] ?? 'fastest';
             child.resize = TEXTURE_RESIZE_TO_STRING[settings.resize] ?? 'full';
+            child.filtering = TEXTURE_FILTER_TO_STRING[settings.filtering] ?? 'linear';
             child.generateMipmaps = settings.generateMipmaps;
             break;
         case 'audio':

package/dist/app/thumbnail-cache.d.ts

@@ -0,0 +1,29 @@
+export interface ThumbnailManifestEntry {
+    format: 'png' | 'webp' | 'webm';
+    sourceSize: number;
+    settingsHash: string;
+    materialDepsHash: string;
+}
+export type ThumbnailManifest = Record<string, ThumbnailManifestEntry>;
+export declare function readManifest(srcArtDir: string): Promise<ThumbnailManifest>;
+export declare function writeManifest(srcArtDir: string, manifest: ThumbnailManifest): Promise<void>;
+/** Hash the settings fields that affect thumbnail appearance. */
+export declare function computeSettingsHash(settings: Record<string, unknown>): string;
+/**
+ * Compute a hash over material dependencies for mesh/animation assets.
+ * Covers materialOverrides → referenced material asset settings + their texture dependencies.
+ */
+export declare function computeMaterialDepsHash(settings: Record<string, unknown>, allAssets: Array<{
+    id: string;
+    stringId: string;
+    sourceSize: number;
+    settings: Record<string, unknown>;
+}>): string;
+export declare function isThumbnailCacheValid(entry: ThumbnailManifestEntry | undefined, sourceSize: number, settingsHash: string, materialDepsHash: string): boolean;
+export declare function writeThumbnailFile(srcArtDir: string, stringId: string, format: 'png' | 'webp' | 'webm', data: Buffer): Promise<void>;
+export declare function readThumbnailFile(srcArtDir: string, stringId: string, format: 'png' | 'webp' | 'webm'): Promise<Buffer | null>;
+/** Clean up thumbnail cache directory. */
+export declare function cleanThumbnailCache(srcArtDir: string): Promise<{
+    deleted: number;
+    freedBytes: number;
+}>;

package/dist/app/thumbnail-cache.js

@@ -0,0 +1,137 @@
+/**
+ * Server-side thumbnail cache.
+ * Stores captured thumbnails in `.stow-thumbnails/` to skip re-capture for unchanged assets.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+const CACHE_DIR = '.stow-thumbnails';
+const MANIFEST_FILE = 'manifest.json';
+function cacheDir(srcArtDir) {
+    return path.join(srcArtDir, CACHE_DIR);
+}
+function manifestPath(srcArtDir) {
+    return path.join(cacheDir(srcArtDir), MANIFEST_FILE);
+}
+function thumbnailFileName(stringId, format) {
+    // Use a hash of stringId to avoid filesystem issues with slashes/special chars
+    const hash = crypto.createHash('sha256').update(stringId).digest('hex').slice(0, 16);
+    return `${hash}.${format}`;
+}
+export async function readManifest(srcArtDir) {
+    try {
+        const raw = await fs.readFile(manifestPath(srcArtDir), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export async function writeManifest(srcArtDir, manifest) {
+    const dir = cacheDir(srcArtDir);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(manifestPath(srcArtDir), JSON.stringify(manifest, null, 2));
+}
+/** Hash the settings fields that affect thumbnail appearance. */
+export function computeSettingsHash(settings) {
+    // Only include settings that affect visual output
+    const relevant = {};
+    for (const key of ['quality', 'resize', 'generateMipmaps', 'dracoQuality', 'materialConfig', 'targetMeshId', 'materialOverrides']) {
+        if (settings[key] !== undefined)
+            relevant[key] = settings[key];
+    }
+    return crypto.createHash('sha256').update(JSON.stringify(relevant)).digest('hex').slice(0, 16);
+}
+/**
+ * Compute a hash over material dependencies for mesh/animation assets.
+ * Covers materialOverrides → referenced material asset settings + their texture dependencies.
+ */
+export function computeMaterialDepsHash(settings, allAssets) {
+    const overrides = settings.materialOverrides;
+    if (!overrides || Object.keys(overrides).length === 0)
+        return '';
+    const parts = [];
+    for (const [idx, matId] of Object.entries(overrides)) {
+        if (!matId)
+            continue;
+        const matAsset = allAssets.find(a => a.id === matId);
+        if (!matAsset)
+            continue;
+        // Include material's settings and sourceSize
+        parts.push(`${idx}:${matId}:${matAsset.sourceSize}:${JSON.stringify(matAsset.settings.materialConfig ?? {})}`);
+        // Also hash texture assets referenced by material properties
+        const matConfig = matAsset.settings.materialConfig;
+        if (matConfig?.properties) {
+            for (const prop of matConfig.properties) {
+                if (prop.type === 'texture' && prop.value) {
+                    const texAsset = allAssets.find(a => a.id === prop.value);
+                    if (texAsset)
+                        parts.push(`tex:${prop.value}:${texAsset.sourceSize}`);
+                }
+            }
+        }
+    }
+    // For animation clips, also include the target mesh
+    const targetMeshId = settings.targetMeshId;
+    if (targetMeshId) {
+        const meshAsset = allAssets.find(a => a.id === targetMeshId);
+        if (meshAsset) {
+            parts.push(`mesh:${targetMeshId}:${meshAsset.sourceSize}:${computeSettingsHash(meshAsset.settings)}`);
+            // Recurse: include the mesh's own material deps
+            const meshDeps = computeMaterialDepsHash(meshAsset.settings, allAssets);
+            if (meshDeps)
+                parts.push(`meshDeps:${meshDeps}`);
+        }
+    }
+    if (parts.length === 0)
+        return '';
+    return crypto.createHash('sha256').update(parts.join('|')).digest('hex').slice(0, 16);
+}
+export function isThumbnailCacheValid(entry, sourceSize, settingsHash, materialDepsHash) {
+    if (!entry)
+        return false;
+    return entry.sourceSize === sourceSize &&
+        entry.settingsHash === settingsHash &&
+        entry.materialDepsHash === materialDepsHash;
+}
+export async function writeThumbnailFile(srcArtDir, stringId, format, data) {
+    const dir = cacheDir(srcArtDir);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, thumbnailFileName(stringId, format)), data);
+}
+export async function readThumbnailFile(srcArtDir, stringId, format) {
+    try {
+        return await fs.readFile(path.join(cacheDir(srcArtDir), thumbnailFileName(stringId, format)));
+    }
+    catch {
+        return null;
+    }
+}
+/** Clean up thumbnail cache directory. */
+export async function cleanThumbnailCache(srcArtDir) {
+    const dir = cacheDir(srcArtDir);
+    let deleted = 0;
+    let freedBytes = 0;
+    try {
+        const manifest = await readManifest(srcArtDir);
+        const validFiles = new Set();
+        for (const [stringId, entry] of Object.entries(manifest)) {
+            validFiles.add(thumbnailFileName(stringId, entry.format));
+        }
+        validFiles.add(MANIFEST_FILE);
+        const entries = await fs.readdir(dir);
+        for (const name of entries) {
+            if (!validFiles.has(name)) {
+                const fullPath = path.join(dir, name);
+                const stat = await fs.stat(fullPath);
+                await fs.unlink(fullPath);
+                deleted++;
+                freedBytes += stat.size;
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist yet — nothing to clean
+    }
+    return { deleted, freedBytes };
+}

package/dist/assets-package.d.ts

@@ -0,0 +1,66 @@
+export interface AssetsPackage {
+    name: string;
+    version: string;
+    author: string;
+    description: string;
+    tags: string[];
+    bucket: string;
+}
+export interface RegistryAsset {
+    /** Unique string identifier for this asset */
+    stringId: string;
+    /** Asset type: texture, staticMesh, skinnedMesh, audio, materialSchema, animationClip, glbContainer */
+    type: string;
+    /** Relative file path within the version directory */
+    file: string;
+    /** All files needed for this asset (source + stowmeta + stowmat) */
+    files: string[];
+    /** Source file size in bytes */
+    size: number;
+    /** User-defined tags from stowmeta */
+    tags: string[];
+    /** Direct dependency stringIds (mesh→material, material→texture, anim→mesh) */
+    dependencies: string[];
+    /** Whether a thumbnail was uploaded for this asset */
+    thumbnail?: boolean;
+    /** Thumbnail format: 'png' (default) or 'webm' for animated previews */
+    thumbnailFormat?: 'png' | 'webp' | 'webm';
+    /** Texture filtering mode — 'nearest' for pixel art, 'linear' (default) for smooth */
+    filtering?: 'linear' | 'nearest';
+}
+export interface RegistryVersion {
+    publishedAt: string;
+    fileCount: number;
+    totalSize: number;
+    assets: RegistryAsset[];
+}
+export interface RegistryPackage {
+    description: string;
+    author: string;
+    tags: string[];
+    latest: string;
+    versions: Record<string, RegistryVersion>;
+    /** Pack-level thumbnail filename (e.g. "thumbnail.webp"), uploaded during publish */
+    thumbnail?: string;
+}
+export interface Registry {
+    schemaVersion: number;
+    packages: Record<string, RegistryPackage>;
+}
+export declare function readAssetsPackage(dir: string): Promise<AssetsPackage | null>;
+export declare function writeAssetsPackage(dir: string, pkg: AssetsPackage): Promise<void>;
+export declare function initAssetsPackage(dir: string, config: {
+    name: string;
+}): Promise<AssetsPackage>;
+export declare function createEmptyRegistry(): Registry;
+/**
+ * Given a set of requested stringIds and a version's asset list,
+ * returns the full set of stringIds needed (transitive closure).
+ * Deduplicates automatically — shared deps are only included once.
+ */
+export declare function resolveTransitiveDeps(requestedIds: string[], assets: RegistryAsset[]): string[];
+/**
+ * Given resolved stringIds and a version's asset list,
+ * returns the deduplicated set of files needed to download.
+ */
+export declare function resolveFiles(stringIds: string[], assets: RegistryAsset[]): string[];

package/dist/assets-package.js

@@ -0,0 +1,80 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+// ─── Constants ───────────────────────────────────────────────────────────────
+const ASSETS_PACKAGE_FILE = 'assets-package.json';
+const DEFAULT_BUCKET = 'venus-shared-assets-test';
+// ─── Read / Write / Init ─────────────────────────────────────────────────────
+export async function readAssetsPackage(dir) {
+    try {
+        const filePath = path.join(dir, ASSETS_PACKAGE_FILE);
+        const text = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeAssetsPackage(dir, pkg) {
+    const filePath = path.join(dir, ASSETS_PACKAGE_FILE);
+    await fs.writeFile(filePath, JSON.stringify(pkg, null, 2) + '\n');
+}
+export async function initAssetsPackage(dir, config) {
+    const pkg = {
+        name: config.name,
+        version: '1.0.0',
+        author: '',
+        description: '',
+        tags: [],
+        bucket: `gs://${DEFAULT_BUCKET}`,
+    };
+    await writeAssetsPackage(dir, pkg);
+    return pkg;
+}
+export function createEmptyRegistry() {
+    return { schemaVersion: 1, packages: {} };
+}
+// ─── Dependency Resolution ───────────────────────────────────────────────────
+/**
+ * Given a set of requested stringIds and a version's asset list,
+ * returns the full set of stringIds needed (transitive closure).
+ * Deduplicates automatically — shared deps are only included once.
+ */
+export function resolveTransitiveDeps(requestedIds, assets) {
+    const assetMap = new Map();
+    for (const a of assets)
+        assetMap.set(a.stringId, a);
+    const resolved = new Set();
+    const queue = [...requestedIds];
+    while (queue.length > 0) {
+        const id = queue.pop();
+        if (resolved.has(id))
+            continue;
+        resolved.add(id);
+        const asset = assetMap.get(id);
+        if (!asset)
+            continue;
+        for (const dep of asset.dependencies) {
+            if (!resolved.has(dep))
+                queue.push(dep);
+        }
+    }
+    return [...resolved];
+}
+/**
+ * Given resolved stringIds and a version's asset list,
+ * returns the deduplicated set of files needed to download.
+ */
+export function resolveFiles(stringIds, assets) {
+    const assetMap = new Map();
+    for (const a of assets)
+        assetMap.set(a.stringId, a);
+    const files = new Set();
+    for (const id of stringIds) {
+        const asset = assetMap.get(id);
+        if (!asset)
+            continue;
+        for (const f of asset.files)
+            files.add(f);
+    }
+    return [...files];
+}

package/dist/cleanup.js

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { readProjectConfig, scanDirectory } from './node-fs.js';
+import { cleanThumbnailCache } from './app/thumbnail-cache.js';
 export async function cleanupProject(projectDir, opts) {
     const verbose = opts?.verbose ?? false;
     const config = await readProjectConfig(projectDir);
@@ -27,11 +28,19 @@ export async function cleanupProject(projectDir, opts) {
                 console.log(`  [delete] ${orphanPath} (orphaned meta)`);
         }
     });
-    if (deletedCaches + deletedMetas === 0) {
+    // Clean orphaned thumbnail cache files
+    const thumbResult = await cleanThumbnailCache(config.srcArtDir);
+    if (thumbResult.deleted > 0) {
+        freedBytes += thumbResult.freedBytes;
+        if (verbose)
+            console.log(`  [delete] ${thumbResult.deleted} orphaned thumbnail cache file(s)`);
+    }
+    if (deletedCaches + deletedMetas + thumbResult.deleted === 0) {
         console.log('No orphaned files found.');
     }
     else {
-        console.log(`Cleaned up ${deletedCaches} cache(s) and ${deletedMetas} meta(s) (${(freedBytes / 1024).toFixed(0)} KB freed)`);
+        const thumbNote = thumbResult.deleted > 0 ? `, ${thumbResult.deleted} thumbnail(s)` : '';
+        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) {