@series-inc/stowkit-cli 0.6.16 → 0.6.18

package/dist/cli.js

@@ -10,6 +10,8 @@ import { cleanupProject } from './cleanup.js';
 import { createMaterial } from './create-material.js';
 import { renameAsset, moveAsset, deleteAsset, setStringId } from './asset-commands.js';
 import { inspectPack } from './inspect.js';
+import { publishPackage } from './publish.js';
+import { storeSearch, storeList, storeInfo } from './store.js';
 const args = process.argv.slice(2);
 const thisDir = path.dirname(fileURLToPath(import.meta.url));
 const STOWKIT_PACKAGES = [
@@ -89,6 +91,10 @@ Usage:
   stowkit delete <path>           Delete an asset and its sidecar files
   stowkit set-id <path> <id>      Change an asset's stringId
   stowkit inspect <file.stow>     Show manifest of a built .stow pack
+  stowkit publish [dir]            Publish asset packs to GCS bucket
+  stowkit store search <query>     Search the asset store
+  stowkit store list               List all packages in the store
+  stowkit store info <package>     Show package details and assets
   stowkit update                  Update CLI to latest version and refresh skill files
   stowkit version                 Show installed version
   stowkit packer [dir]            Open the packer GUI
@@ -100,6 +106,10 @@ Options:
   --verbose     Detailed output
   --port        Server port (default 3210)
   --schema      Material schema template: pbr (default), unlit, or custom name
+  --bucket      GCS bucket for publish/store (overrides default)
+  --dry-run     Show what would be published without uploading
+  --json        Output store results as JSON (for AI agents)
+  --type        Filter store search by asset type
   --help        Show this help message
 `.trim());
 }
@@ -128,6 +138,18 @@ function openBrowser(url) {
         exec(`${cmd} ${url}`);
     });
 }
+async function isStowKitRunning(port) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 1000);
+        const res = await fetch(`http://localhost:${port}/api/project`, { signal: controller.signal });
+        clearTimeout(timeout);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
 async function main() {
     if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
         printUsage();
@@ -139,6 +161,12 @@ async function main() {
     const verbose = args.includes('--verbose') || args.includes('-v');
     const portIdx = args.indexOf('--port');
     const port = portIdx >= 0 ? parseInt(args[portIdx + 1]) : 3210;
+    const dryRun = args.includes('--dry-run');
+    const jsonOutput = args.includes('--json');
+    const bucketIdx = args.indexOf('--bucket');
+    const bucket = bucketIdx >= 0 ? args[bucketIdx + 1] : undefined;
+    const typeIdx = args.indexOf('--type');
+    const typeFilter = typeIdx >= 0 ? args[typeIdx + 1] : undefined;
     const opts = { force, verbose };
     try {
         switch (command) {
@@ -268,7 +296,43 @@ async function main() {
                 await inspectPack(stowPath, { verbose });
                 break;
             }
+            case 'publish':
+                await publishPackage(projectDir, { force, dryRun, bucket, verbose });
+                break;
+            case 'store': {
+                const subCmd = args[1];
+                const storeOpts = { json: jsonOutput, bucket };
+                if (subCmd === 'search') {
+                    const query = args.filter(a => !a.startsWith('-') && a !== 'store' && a !== 'search').join(' ');
+                    if (!query) {
+                        console.error('Usage: stowkit store search <query> [--type <type>] [--json]');
+                        process.exit(1);
+                    }
+                    await storeSearch(query, { ...storeOpts, type: typeFilter });
+                }
+                else if (subCmd === 'list') {
+                    await storeList(storeOpts);
+                }
+                else if (subCmd === 'info') {
+                    const pkgName = args.find(a => !a.startsWith('-') && a !== 'store' && a !== 'info');
+                    if (!pkgName) {
+                        console.error('Usage: stowkit store info <package-name> [--json]');
+                        process.exit(1);
+                    }
+                    await storeInfo(pkgName, storeOpts);
+                }
+                else {
+                    console.error('Usage: stowkit store <search|list|info> [args]');
+                    process.exit(1);
+                }
+                break;
+            }
             case 'packer': {
+                if (await isStowKitRunning(port)) {
+                    console.log(`\n  Packer already running: http://localhost:${port}\n`);
+                    openBrowser(`http://localhost:${port}`);
+                    break;
+                }
                 const packerDir = resolveAppDir('@series-inc/stowkit-packer-gui', 'stowkit-packer-gui');
                 if (!packerDir) {
                     console.error('Packer GUI not found. Install it: npm install @series-inc/stowkit-packer-gui');
@@ -281,6 +345,11 @@ async function main() {
                 break;
             }
             case 'editor': {
+                if (await isStowKitRunning(port)) {
+                    console.log(`\n  Editor already running: http://localhost:${port}\n`);
+                    openBrowser(`http://localhost:${port}`);
+                    break;
+                }
                 const editorDir = resolveAppDir('@series-inc/stowkit-editor', 'stowkit-editor');
                 if (!editorDir) {
                     console.error('Editor not found. Install it: npm install @series-inc/stowkit-editor');

package/dist/core/constants.d.ts

@@ -12,8 +12,10 @@ export declare const DATA_ALIGNMENT = 16;
 export declare const MAX_PATH_LENGTH = 512;
 /** Size of the string_id field in metadata structs (bytes) */
 export declare const STRING_ID_SIZE = 128;
-/** Size of TextureMetadata on disk (bytes) */
-export declare const TEXTURE_METADATA_SIZE = 144;
+/** Size of TextureMetadata on disk (bytes) — v1.1: appended filtering uint32 */
+export declare const TEXTURE_METADATA_SIZE = 148;
+/** Size of legacy TextureMetadata without filtering field (bytes) */
+export declare const LEGACY_TEXTURE_METADATA_SIZE = 144;
 /** Size of AudioMetadata on disk (bytes) */
 export declare const AUDIO_METADATA_SIZE = 140;
 /** Size of MeshGeometryInfo on disk (bytes) */

package/dist/core/constants.js

@@ -12,8 +12,10 @@ export const DATA_ALIGNMENT = 16;
 export const MAX_PATH_LENGTH = 512;
 /** Size of the string_id field in metadata structs (bytes) */
 export const STRING_ID_SIZE = 128;
-/** Size of TextureMetadata on disk (bytes) */
-export const TEXTURE_METADATA_SIZE = 144;
+/** Size of TextureMetadata on disk (bytes) — v1.1: appended filtering uint32 */
+export const TEXTURE_METADATA_SIZE = 148;
+/** Size of legacy TextureMetadata without filtering field (bytes) */
+export const LEGACY_TEXTURE_METADATA_SIZE = 144;
 /** Size of AudioMetadata on disk (bytes) */
 export const AUDIO_METADATA_SIZE = 140;
 /** Size of MeshGeometryInfo on disk (bytes) */

package/dist/core/types.d.ts

@@ -26,6 +26,10 @@ export declare enum TextureResize {
     Quarter = 2,
     Eighth = 3
 }
+export declare enum TextureFilterMode {
+    Linear = 0,
+    Nearest = 1
+}
 export declare enum MaterialFieldType {
     Texture = 0,
     Color = 1,
@@ -86,6 +90,7 @@ export interface TextureMetadata {
     channels: number;
     channelFormat: TextureChannelFormat;
     stringId: string;
+    filtering: TextureFilterMode;
 }
 export interface AudioMetadata {
     stringId: string;

package/dist/core/types.js

@@ -32,6 +32,11 @@ export var TextureResize;
     TextureResize[TextureResize["Quarter"] = 2] = "Quarter";
     TextureResize[TextureResize["Eighth"] = 3] = "Eighth";
 })(TextureResize || (TextureResize = {}));
+export var TextureFilterMode;
+(function (TextureFilterMode) {
+    TextureFilterMode[TextureFilterMode["Linear"] = 0] = "Linear";
+    TextureFilterMode[TextureFilterMode["Nearest"] = 1] = "Nearest";
+})(TextureFilterMode || (TextureFilterMode = {}));
 // ─── Material Enums ─────────────────────────────────────────────────────────
 export var MaterialFieldType;
 (function (MaterialFieldType) {

package/dist/encoders/basis-encoder.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
-import { KTX2Quality, TextureChannelFormat } from '../core/types.js';
+import { KTX2Quality, TextureChannelFormat, TextureFilterMode } from '../core/types.js';
 const QUALITY_TO_LEVEL = {
     [KTX2Quality.Fastest]: 1,
     [KTX2Quality.Fast]: 64,
@@ -106,6 +106,7 @@ export class NodeBasisEncoder {
                 channels: useUastc ? 4 : 3,
                 channelFormat: useUastc ? TextureChannelFormat.RGBA : TextureChannelFormat.RGB,
                 stringId: '',
+                filtering: TextureFilterMode.Linear,
             };
             return { data: ktx2Data, metadata };
         }

package/dist/format/metadata.js

@@ -1,5 +1,6 @@
 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 { TextureFilterMode } from '../core/types.js';
 // ─── Texture Metadata ───────────────────────────────────────────────────────
 export function serializeTextureMetadata(meta) {
     const w = new BinaryWriter(TEXTURE_METADATA_SIZE);
@@ -8,17 +9,21 @@ export function serializeTextureMetadata(meta) {
     w.writeUint32(meta.channels);
     w.writeUint32(meta.channelFormat);
     w.writeFixedString(meta.stringId, STRING_ID_SIZE);
+    w.writeUint32(meta.filtering);
     return w.getUint8Array();
 }
 export function deserializeTextureMetadata(data) {
     const r = new BinaryReader(data);
-    return {
-        width: r.readUint32(),
-        height: r.readUint32(),
-        channels: r.readUint32(),
-        channelFormat: r.readUint32(),
-        stringId: r.readFixedString(STRING_ID_SIZE),
-    };
+    const width = r.readUint32();
+    const height = r.readUint32();
+    const channels = r.readUint32();
+    const channelFormat = r.readUint32();
+    const stringId = r.readFixedString(STRING_ID_SIZE);
+    // Old packs have 144-byte texture metadata (no filtering field)
+    const filtering = data.length >= TEXTURE_METADATA_SIZE
+        ? r.readUint32()
+        : TextureFilterMode.Linear;
+    return { width, height, channels, channelFormat, stringId, filtering };
 }
 // ─── Audio Metadata ─────────────────────────────────────────────────────────
 export function serializeAudioMetadata(meta) {

package/dist/gcs.d.ts

@@ -0,0 +1,10 @@
+export interface GCSClient {
+    upload(objectPath: string, data: Uint8Array | string, contentType?: string): Promise<void>;
+    download(objectPath: string): Promise<string | null>;
+    downloadWithGeneration(objectPath: string): Promise<{
+        data: string;
+        generation: string;
+    } | null>;
+    uploadWithGeneration(objectPath: string, data: string, generation: string | null, contentType?: string): Promise<void>;
+}
+export declare function createGCSClient(projectDir: string, bucketUri: string): Promise<GCSClient>;

package/dist/gcs.js

@@ -0,0 +1,158 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+// ─── JWT Auth ────────────────────────────────────────────────────────────────
+function base64url(data) {
+    const buf = typeof data === 'string' ? Buffer.from(data) : data;
+    return buf.toString('base64url');
+}
+function createJWT(sa) {
+    const now = Math.floor(Date.now() / 1000);
+    const header = { alg: 'RS256', typ: 'JWT' };
+    const payload = {
+        iss: sa.client_email,
+        scope: 'https://www.googleapis.com/auth/devstorage.read_write',
+        aud: 'https://oauth2.googleapis.com/token',
+        iat: now,
+        exp: now + 3600,
+    };
+    const segments = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(payload))}`;
+    const sign = crypto.createSign('RSA-SHA256');
+    sign.update(segments);
+    const signature = sign.sign(sa.private_key);
+    return `${segments}.${base64url(signature)}`;
+}
+async function getAccessToken(sa) {
+    const jwt = createJWT(sa);
+    const res = await fetch('https://oauth2.googleapis.com/token', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: `grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=${jwt}`,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`GCS auth failed (${res.status}): ${text}`);
+    }
+    const data = await res.json();
+    return data.access_token;
+}
+// ─── Credential Resolution ───────────────────────────────────────────────────
+async function loadServiceAccount(projectDir) {
+    // Search order: project dir, cwd, GOOGLE_APPLICATION_CREDENTIALS env
+    const candidates = [
+        path.join(projectDir, 'service_account.json'),
+        path.join(process.cwd(), 'service_account.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const text = await fs.readFile(candidate, 'utf-8');
+            return JSON.parse(text);
+        }
+        catch { /* not found */ }
+    }
+    // Fall back to GOOGLE_APPLICATION_CREDENTIALS
+    const envPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+    if (envPath) {
+        try {
+            const text = await fs.readFile(envPath, 'utf-8');
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Could not read service account from GOOGLE_APPLICATION_CREDENTIALS: ${envPath}`);
+        }
+    }
+    throw new Error('No GCS credentials found. Place service_account.json in project root, ' +
+        'current directory, or set GOOGLE_APPLICATION_CREDENTIALS environment variable.');
+}
+// ─── Bucket Name Parsing ─────────────────────────────────────────────────────
+function parseBucket(bucketUri) {
+    // Accept "gs://bucket-name" or just "bucket-name"
+    if (bucketUri.startsWith('gs://'))
+        return bucketUri.slice(5).replace(/\/$/, '');
+    return bucketUri.replace(/\/$/, '');
+}
+// ─── GCS Client Factory ─────────────────────────────────────────────────────
+export async function createGCSClient(projectDir, bucketUri) {
+    const sa = await loadServiceAccount(projectDir);
+    const token = await getAccessToken(sa);
+    const bucket = parseBucket(bucketUri);
+    const apiBase = `https://storage.googleapis.com`;
+    return {
+        async upload(objectPath, data, contentType = 'application/octet-stream') {
+            const encoded = encodeURIComponent(objectPath);
+            const url = `${apiBase}/upload/storage/v1/b/${bucket}/o?uploadType=media&name=${encoded}`;
+            const body = typeof data === 'string' ? data : Buffer.from(data);
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    'Content-Type': contentType,
+                },
+                body,
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`GCS upload failed for ${objectPath} (${res.status}): ${text}`);
+            }
+        },
+        async download(objectPath) {
+            const encoded = encodeURIComponent(objectPath);
+            const url = `${apiBase}/storage/v1/b/${bucket}/o/${encoded}?alt=media`;
+            const res = await fetch(url, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (res.status === 404)
+                return null;
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`GCS download failed for ${objectPath} (${res.status}): ${text}`);
+            }
+            return res.text();
+        },
+        async downloadWithGeneration(objectPath) {
+            const encoded = encodeURIComponent(objectPath);
+            const url = `${apiBase}/storage/v1/b/${bucket}/o/${encoded}?alt=media`;
+            const res = await fetch(url, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (res.status === 404)
+                return null;
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`GCS download failed for ${objectPath} (${res.status}): ${text}`);
+            }
+            const data = await res.text();
+            const generation = res.headers.get('x-goog-generation') ?? '0';
+            return { data, generation };
+        },
+        async uploadWithGeneration(objectPath, data, generation, contentType = 'application/json') {
+            const encoded = encodeURIComponent(objectPath);
+            let url = `${apiBase}/upload/storage/v1/b/${bucket}/o?uploadType=media&name=${encoded}`;
+            const headers = {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': contentType,
+            };
+            // Optimistic concurrency: if we have a generation, require it to match
+            if (generation) {
+                headers['x-goog-if-generation-match'] = generation;
+            }
+            else {
+                // Object should not exist yet
+                headers['x-goog-if-generation-match'] = '0';
+            }
+            const res = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: data,
+            });
+            if (res.status === 412) {
+                throw new Error(`Registry was modified by another publish while uploading. ` +
+                    `Please retry the publish command.`);
+            }
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`GCS upload failed for ${objectPath} (${res.status}): ${text}`);
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -27,3 +27,8 @@ export type { ServerOptions } from './server.js';
 export { initProject } from './init.js';
 export { cleanupProject } from './cleanup.js';
 export { syncRuntimeAssets } from './sync-runtime-assets.js';
+export { publishPackage } from './publish.js';
+export type { PublishOptions, PublishResult } from './publish.js';
+export * from './assets-package.js';
+export { fetchRegistry, searchAssets, listPackages, resolveAssetDeps } from './store.js';
+export type { SearchResult, PackageInfo } from './store.js';

package/dist/index.js

@@ -35,3 +35,8 @@ export { initProject } from './init.js';
 export { cleanupProject } from './cleanup.js';
 // Runtime asset sync
 export { syncRuntimeAssets } from './sync-runtime-assets.js';
+// Publish
+export { publishPackage } from './publish.js';
+export * from './assets-package.js';
+// Store
+export { fetchRegistry, searchAssets, listPackages, resolveAssetDeps } from './store.js';

package/dist/init.js

@@ -96,6 +96,8 @@ export async function initProject(projectDir, opts) {
         '# StowKit',
         '*.stowcache',
         'public/cdn-assets/',
+        'Open Packer.bat',
+        'open-packer.sh',
     ].join('\n');
     try {
         const existing = await fs.readFile(gitignorePath, 'utf-8');
@@ -108,11 +110,14 @@ export async function initProject(projectDir, opts) {
     }
     // Copy AI skill/rule files
     await copySkillFiles(absDir);
+    // Create double-clickable launcher scripts
+    await createLauncherScripts(absDir);
     console.log(`Initialized StowKit project at ${absDir}`);
     console.log(`  Source art dir: ${srcArtDir}/`);
     console.log(`  Output dir:     public/cdn-assets/`);
     console.log(`  Config:         .felicityproject`);
     console.log(`  AI skills:      .claude/skills/stowkit/SKILL.md, .cursor/rules/stowkit.mdc`);
+    console.log(`  Launcher:       Open Packer.bat (Windows) / open-packer.sh (macOS/Linux)`);
     // Install engine if selected
     if (withEngine) {
         await installEngine(absDir);
@@ -120,6 +125,7 @@ export async function initProject(projectDir, opts) {
     console.log('');
     console.log('Drop your assets (PNG, JPG, FBX, WAV, etc.) into assets/');
     console.log('Then run: stowkit build');
+    console.log('Or double-click "Open Packer.bat" to launch the packer GUI.');
 }
 async function installEngine(absDir) {
     console.log('');
@@ -159,6 +165,20 @@ async function copySkillFiles(absDir) {
         // Skill file not found in package — skip silently
     }
 }
+async function createLauncherScripts(absDir) {
+    const batContent = [
+        '@echo off',
+        'npx @series-inc/stowkit-cli packer .',
+        'if %errorlevel% neq 0 pause',
+    ].join('\r\n');
+    const shContent = [
+        '#!/bin/sh',
+        'cd "$(dirname "$0")"',
+        'npx @series-inc/stowkit-cli packer .',
+    ].join('\n');
+    await fs.writeFile(path.join(absDir, 'Open Packer.bat'), batContent);
+    await fs.writeFile(path.join(absDir, 'open-packer.sh'), shContent, { mode: 0o755 });
+}
 async function copyEngineSkillFiles(absDir) {
     const thisDir = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [

package/dist/node-fs.d.ts

@@ -6,6 +6,10 @@ export declare function renameFile(basePath: string, oldRelative: string, newRel
 export declare function deleteFile(basePath: string, relativePath: string): Promise<void>;
 export declare function fileExists(basePath: string, relativePath: string): Promise<boolean>;
 export declare function getFileSnapshot(basePath: string, relativePath: string): Promise<FileSnapshot | null>;
+export declare function probeImageDimensions(srcArtDir: string, relativePath: string): Promise<{
+    width: number;
+    height: number;
+} | null>;
 export interface ScanResult {
     sourceFiles: FileSnapshot[];
     metaFiles: FileSnapshot[];

package/dist/node-fs.js

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import sharp from 'sharp';
 // ─── File I/O ────────────────────────────────────────────────────────────────
 export async function readFile(basePath, relativePath) {
     try {
@@ -68,6 +69,19 @@ export async function getFileSnapshot(basePath, relativePath) {
         return null;
     }
 }
+export async function probeImageDimensions(srcArtDir, relativePath) {
+    try {
+        const absPath = path.join(srcArtDir, relativePath);
+        const metadata = await sharp(absPath).metadata();
+        if (metadata.width && metadata.height) {
+            return { width: metadata.width, height: metadata.height };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 // ─── Directory Scanning ──────────────────────────────────────────────────────
 const SOURCE_EXTENSIONS = new Set([
     'png', 'jpg', 'jpeg', 'bmp', 'tga', 'webp', 'gif',

package/dist/orchestrator.js

@@ -4,8 +4,8 @@ import { AssetType } from './core/types.js';
 import { cleanupProject } from './cleanup.js';
 import { defaultAssetSettings } from './app/state.js';
 import { BlobStore } from './app/blob-store.js';
-import { readProjectConfig, scanDirectory, readFile, getFileSnapshot, } from './node-fs.js';
-import { readStowmeta, writeStowmeta, stowmetaToAssetSettings, generateDefaultStowmeta, glbChildToAssetSettings, generateDefaultGlbChild, } from './app/stowmeta-io.js';
+import { readProjectConfig, scanDirectory, readFile, getFileSnapshot, probeImageDimensions, } from './node-fs.js';
+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 { readCacheBlobs, writeCacheBlobs, buildCacheStamp, isCacheValid, } from './app/process-cache.js';
@@ -21,7 +21,11 @@ export async function scanProject(projectDir, opts) {
     for (const file of scan.sourceFiles) {
         if (!existingMeta.has(file.relativePath)) {
             newFiles.push(file.relativePath);
-            const meta = generateDefaultStowmeta(file.relativePath);
+            const type = detectAssetType(file.relativePath);
+            const imageDimensions = type === AssetType.Texture2D
+                ? await probeImageDimensions(config.srcArtDir, file.relativePath)
+                : null;
+            const meta = generateDefaultStowmeta(file.relativePath, type, config.config.defaults, imageDimensions);
             await writeStowmeta(config.srcArtDir, file.relativePath, meta);
             if (verbose)
                 console.log(`  [new] ${file.relativePath} → .stowmeta (${meta.type})`);
@@ -60,7 +64,11 @@ export async function fullBuild(projectDir, opts) {
         const id = file.relativePath;
         let meta = await readStowmeta(config.srcArtDir, id);
         if (!meta) {
-            meta = generateDefaultStowmeta(id);
+            const type = detectAssetType(id);
+            const imageDimensions = type === AssetType.Texture2D
+                ? await probeImageDimensions(config.srcArtDir, id)
+                : null;
+            meta = generateDefaultStowmeta(id, type, config.config.defaults, imageDimensions);
             await writeStowmeta(config.srcArtDir, id, meta);
         }
         const { type, settings } = stowmetaToAssetSettings(meta);
@@ -115,7 +123,7 @@ export async function fullBuild(projectDir, opts) {
         const baseName = fileName.replace(/\.[^.]+$/, '');
         let meta = await readStowmeta(config.srcArtDir, id);
         if (!meta) {
-            meta = generateDefaultStowmeta(id, AssetType.MaterialSchema);
+            meta = generateDefaultStowmeta(id, AssetType.MaterialSchema, config.config.defaults);
             await writeStowmeta(config.srcArtDir, id, meta);
         }
         const asset = {
@@ -147,12 +155,12 @@ export async function fullBuild(projectDir, opts) {
             const existingChildren = new Map((containerMeta.children ?? []).map(c => [c.name, c]));
             const childrenManifest = [];
             for (const tex of extract.textures) {
-                childrenManifest.push(existingChildren.get(tex.name) ?? generateDefaultGlbChild(tex.name, 'texture'));
+                childrenManifest.push(existingChildren.get(tex.name) ?? generateDefaultGlbChild(tex.name, 'texture', config.config.defaults));
                 BlobStore.setSource(`${container.id}/${tex.name}`, tex.data);
             }
             for (const mesh of extract.meshes) {
                 const typeName = mesh.hasSkeleton ? 'skinnedMesh' : 'staticMesh';
-                const meshChild = existingChildren.get(mesh.name) ?? generateDefaultGlbChild(mesh.name, typeName);
+                const meshChild = existingChildren.get(mesh.name) ?? generateDefaultGlbChild(mesh.name, typeName, config.config.defaults);
                 // Store scene node names so AI agents can see the hierarchy in the stowmeta
                 if (mesh.imported.nodes.length > 1) {
                     meshChild.sceneNodeNames = mesh.imported.nodes.map(n => n.name);
@@ -169,7 +177,7 @@ export async function fullBuild(projectDir, opts) {
                     childrenManifest.push(existing);
                 }
                 else {
-                    const child = generateDefaultGlbChild(matName, 'materialSchema');
+                    const child = generateDefaultGlbChild(matName, 'materialSchema', config.config.defaults);
                     const matConfig = pbrToMaterialConfig(mat.pbrConfig, container.id);
                     child.materialConfig = {
                         schemaId: matConfig.schemaId,
@@ -189,7 +197,7 @@ export async function fullBuild(projectDir, opts) {
                 }
             }
             for (const anim of extract.animations) {
-                childrenManifest.push(existingChildren.get(anim.name) ?? generateDefaultGlbChild(anim.name, 'animationClip'));
+                childrenManifest.push(existingChildren.get(anim.name) ?? generateDefaultGlbChild(anim.name, 'animationClip', config.config.defaults));
             }
             // Update stowmeta with inline children
             containerMeta.children = childrenManifest;
@@ -408,7 +416,26 @@ export async function fullBuild(projectDir, opts) {
     }
     // 4. Clean orphaned caches/metas
     await cleanupProject(config.projectDir, { verbose });
-    // 5. Build packs
+    // 5. Validate unique stringIds
+    const idCounts = new Map();
+    for (const a of assets) {
+        if (a.status !== 'ready' || a.type === AssetType.GlbContainer || a.settings.excluded)
+            continue;
+        const files = idCounts.get(a.stringId) ?? [];
+        files.push(a.id);
+        idCounts.set(a.stringId, files);
+    }
+    const duplicates = [...idCounts.entries()].filter(([, files]) => files.length > 1);
+    if (duplicates.length > 0) {
+        console.error('Build failed: duplicate stringIds found. Each asset must have a unique stringId.');
+        for (const [id, files] of duplicates) {
+            console.error(`  "${id}" used by:`);
+            for (const f of files)
+                console.error(`    - ${f}`);
+        }
+        throw new Error(`Cannot build: ${duplicates.length} duplicate stringId(s) found.`);
+    }
+    // 6. Build packs
     const packs = config.config.packs ?? [{ name: 'default' }];
     const cdnDir = path.resolve(config.projectDir, config.config.cdnAssetsPath ?? 'public/cdn-assets');
     await fs.mkdir(cdnDir, { recursive: true });

package/dist/pipeline.js

@@ -54,6 +54,7 @@ export async function processAsset(id, sourceData, type, stringId, settings, ctx
         log('encoding KTX2...');
         const result = await ctx.textureEncoder.encode(pixels, width, height, 4, settings.quality, TextureChannelFormat.RGBA, settings.generateMipmaps);
         result.metadata.stringId = stringId;
+        result.metadata.filtering = settings.filtering;
         BlobStore.setProcessed(id, result.data);
         log(`KTX2 encoded (${(result.data.length / 1024).toFixed(0)} KB)`);
         return { metadata: result.metadata, processedSize: result.data.length };

package/dist/publish.d.ts

@@ -0,0 +1,27 @@
+export interface PublishProgress {
+    phase: 'auth' | 'files' | 'thumbnails' | 'registry';
+    done: number;
+    total: number;
+    message: string;
+}
+export interface PublishOptions {
+    force?: boolean;
+    dryRun?: boolean;
+    bucket?: string;
+    verbose?: boolean;
+    /** Thumbnails keyed by stringId (from packer GUI) */
+    thumbnails?: Record<string, {
+        data: string;
+        format: 'png' | 'webp' | 'webm';
+    }>;
+    onProgress?: (progress: PublishProgress) => void;
+}
+export interface PublishResult {
+    ok: boolean;
+    packageName: string;
+    version: string;
+    assetCount: number;
+    fileCount: number;
+    thumbnailCount: number;
+}
+export declare function publishPackage(projectDir: string, opts?: PublishOptions): Promise<PublishResult>;