@series-inc/stowkit-cli 0.1.0

package/dist/server.js

@@ -0,0 +1,859 @@
+import * as http from 'node:http';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { WebSocketServer, WebSocket } from 'ws';
+import { AssetType } from './core/types.js';
+import { defaultAssetSettings } from './app/state.js';
+import { BlobStore } from './app/blob-store.js';
+import { readProjectConfig, scanDirectory, readFile, writeFile, deleteFile, getFileSnapshot, } from './node-fs.js';
+import { detectAssetType, readStowmeta, writeStowmeta, stowmetaToAssetSettings, assetSettingsToStowmeta, generateDefaultStowmeta, } from './app/stowmeta-io.js';
+import { readStowmat, writeStowmat, stowmatToMaterialConfig, materialConfigToStowmat } from './app/stowmat-io.js';
+import { readCacheBlobs, writeCacheBlobs, buildCacheStamp, isCacheValid, } from './app/process-cache.js';
+import { processAsset, buildPack } from './pipeline.js';
+import { NodeBasisEncoder } from './encoders/basis-encoder.js';
+import { NodeDracoEncoder } from './encoders/draco-encoder.js';
+import { NodeAacEncoder, NodeAudioDecoder } from './encoders/aac-encoder.js';
+import { NodeFbxImporter } from './encoders/fbx-loader.js';
+import { SharpImageDecoder } from './encoders/image-decoder.js';
+async function scanPrefabFiles(dir, prefix) {
+    const results = [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...await scanPrefabFiles(path.join(dir, entry.name), relPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.stowprefab')) {
+            const stat = await fs.stat(path.join(dir, entry.name));
+            results.push({ name: entry.name.replace(/\.stowprefab$/, ''), path: relPath, lastModified: stat.mtimeMs });
+        }
+    }
+    return results;
+}
+// ─── State ──────────────────────────────────────────────────────────────────
+let projectConfig = null;
+let assets = [];
+let folders = [];
+let processingCtx = null;
+let encodersReady = false;
+// Track in-flight processing
+const processing = new Set();
+// staticApps is passed per-server via closure, not module-level
+// WebSocket clients
+const wsClients = new Set();
+function broadcast(msg) {
+    const data = JSON.stringify(msg);
+    for (const ws of wsClients) {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(data);
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function resolvePackName(pack, packs) {
+    if (packs.length === 0)
+        return pack;
+    if (packs.some(p => p.name === pack))
+        return pack;
+    return packs[0].name;
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8');
+}
+async function readBinaryBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+function json(res, data, status = 200) {
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+    });
+    res.end(JSON.stringify(data));
+}
+function cors(res) {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+}
+// ─── Initialize encoders ────────────────────────────────────────────────────
+async function initEncoders(wasmDir) {
+    console.log('[server] Initializing encoders...');
+    const textureEncoder = new NodeBasisEncoder(wasmDir);
+    const meshEncoder = new NodeDracoEncoder();
+    const aacEncoder = new NodeAacEncoder();
+    const audioDecoder = new NodeAudioDecoder();
+    const meshImporter = new NodeFbxImporter();
+    const imageDecoder = new SharpImageDecoder();
+    await Promise.all([
+        textureEncoder.initialize(),
+        meshEncoder.initialize(),
+        aacEncoder.initialize(),
+        audioDecoder.initialize(),
+    ]);
+    console.log('[server] All encoders ready');
+    encodersReady = true;
+    broadcast({ type: 'encoders-ready' });
+    return {
+        textureEncoder,
+        meshEncoder,
+        meshImporter,
+        imageDecoder,
+        audioDecoder,
+        aacEncoder,
+        onProgress: (id, msg) => {
+            broadcast({ type: 'progress', id, message: msg });
+        },
+    };
+}
+// ─── Open project ──────────────────────────────────────────────────────────
+async function openProject(projectDir) {
+    projectConfig = await readProjectConfig(projectDir);
+    BlobStore.clear();
+    assets = [];
+    folders = [];
+    const scan = await scanDirectory(projectConfig.srcArtDir);
+    folders = scan.folders;
+    const configuredPacks = projectConfig.config.packs ?? [];
+    // Build asset shells from source files
+    for (const file of scan.sourceFiles) {
+        const type = detectAssetType(file.relativePath);
+        if (type === AssetType.Unknown)
+            continue;
+        const fileName = file.relativePath.split('/').pop() ?? file.relativePath;
+        let meta = await readStowmeta(projectConfig.srcArtDir, file.relativePath);
+        if (!meta) {
+            meta = generateDefaultStowmeta(file.relativePath, type);
+            await writeStowmeta(projectConfig.srcArtDir, file.relativePath, meta);
+        }
+        const { type: metaType, settings: metaSettings } = stowmetaToAssetSettings(meta);
+        metaSettings.pack = resolvePackName(metaSettings.pack, configuredPacks);
+        const asset = {
+            id: file.relativePath,
+            fileName,
+            stringId: meta.stringId,
+            type: metaType,
+            status: 'pending',
+            settings: metaSettings,
+            sourceSize: file.size,
+            processedSize: 0,
+        };
+        // Check cache
+        if (meta.cache) {
+            const snapshot = await getFileSnapshot(projectConfig.srcArtDir, file.relativePath);
+            if (snapshot && isCacheValid(meta, snapshot, metaType, metaSettings)) {
+                const cached = await readCacheBlobs(projectConfig.srcArtDir, file.relativePath);
+                if (cached && cached.size > 0) {
+                    for (const [key, data] of cached) {
+                        if (key.endsWith(':__metadata__')) {
+                            try {
+                                asset.metadata = JSON.parse(new TextDecoder().decode(data));
+                            }
+                            catch { /* skip */ }
+                        }
+                        else {
+                            BlobStore.setProcessed(key, data);
+                        }
+                    }
+                    asset.status = 'ready';
+                    asset.processedSize = BlobStore.getProcessed(file.relativePath)?.length ?? 0;
+                }
+            }
+        }
+        assets.push(asset);
+    }
+    // Materials from .stowmat files
+    for (const matFile of scan.matFiles) {
+        const id = matFile.relativePath;
+        const mat = await readStowmat(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.MaterialSchema);
+            await writeStowmeta(projectConfig.srcArtDir, id, meta);
+        }
+        const materialConfig = mat ? stowmatToMaterialConfig(mat) : { schemaId: '', properties: [] };
+        const settings = defaultAssetSettings();
+        settings.materialConfig = materialConfig;
+        settings.pack = meta.pack ?? 'default';
+        settings.tags = meta.tags ?? [];
+        assets.push({
+            id,
+            fileName: baseName,
+            stringId: meta.stringId || baseName,
+            type: AssetType.MaterialSchema,
+            status: 'ready',
+            settings,
+            sourceSize: matFile.size,
+            processedSize: 0,
+        });
+    }
+    console.log(`[server] Opened: ${projectConfig.projectName} (${assets.length} assets, ${folders.length} folders)`);
+}
+// ─── Process single asset ─────────────────────────────────────────────────
+async function processOneAsset(id) {
+    if (!projectConfig || !processingCtx)
+        return;
+    if (processing.has(id))
+        return;
+    const asset = assets.find(a => a.id === id);
+    if (!asset)
+        return;
+    if (asset.type === AssetType.MaterialSchema)
+        return;
+    processing.add(id);
+    asset.status = 'processing';
+    broadcast({ type: 'asset-update', id, updates: { status: 'processing' } });
+    try {
+        // Load source
+        let sourceData = BlobStore.getSource(id);
+        if (!sourceData) {
+            const data = await readFile(projectConfig.srcArtDir, id);
+            if (!data)
+                throw new Error(`Could not read source: ${id}`);
+            BlobStore.setSource(id, data);
+            sourceData = data;
+        }
+        const t0 = performance.now();
+        const result = await processAsset(id, sourceData, asset.type, asset.stringId, asset.settings, processingCtx);
+        const elapsed = (performance.now() - t0).toFixed(0);
+        asset.status = 'ready';
+        asset.metadata = result.metadata;
+        asset.processedSize = result.processedSize;
+        asset.sourceSize = sourceData.length;
+        broadcast({
+            type: 'asset-update', id,
+            updates: {
+                status: 'ready',
+                metadata: result.metadata,
+                processedSize: result.processedSize,
+                sourceSize: sourceData.length,
+            },
+        });
+        console.log(`[server] Processed ${id} (${elapsed}ms)`);
+        // Write cache
+        const cacheEntries = new Map();
+        const processed = BlobStore.getProcessed(id);
+        if (processed)
+            cacheEntries.set(id, processed);
+        if (result.metadata) {
+            cacheEntries.set(`${id}:__metadata__`, new TextEncoder().encode(JSON.stringify(result.metadata)));
+        }
+        for (const suffix of [':skinnedMeta', ':animMeta', ':animCount']) {
+            const blob = BlobStore.getProcessed(`${id}${suffix}`);
+            if (blob)
+                cacheEntries.set(`${id}${suffix}`, blob);
+        }
+        const animCountBlob = BlobStore.getProcessed(`${id}:animCount`);
+        const clipCount = animCountBlob ? animCountBlob[0] : 0;
+        for (let ci = 0; ci < clipCount; ci++) {
+            for (const key of [`${id}:anim:${ci}`, `${id}:animMeta:${ci}`]) {
+                const blob = BlobStore.getProcessed(key);
+                if (blob)
+                    cacheEntries.set(key, blob);
+            }
+        }
+        if (cacheEntries.size > 0) {
+            await writeCacheBlobs(projectConfig.srcArtDir, id, cacheEntries);
+            const snapshot = await getFileSnapshot(projectConfig.srcArtDir, id);
+            if (snapshot) {
+                const meta = await readStowmeta(projectConfig.srcArtDir, id);
+                if (meta) {
+                    meta.cache = buildCacheStamp(snapshot, asset.type, asset.settings);
+                    await writeStowmeta(projectConfig.srcArtDir, id, meta);
+                }
+            }
+        }
+    }
+    catch (err) {
+        asset.status = 'error';
+        asset.error = err instanceof Error ? err.message : String(err);
+        broadcast({ type: 'asset-update', id, updates: { status: 'error', error: asset.error } });
+        console.error(`[server] Failed ${id}: ${asset.error}`);
+    }
+    finally {
+        processing.delete(id);
+    }
+}
+// ─── Route handler ──────────────────────────────────────────────────────────
+async function handleRequest(req, res, staticApps) {
+    cors(res);
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    const url = new URL(req.url ?? '/', `http://localhost`);
+    const pathname = url.pathname;
+    // GET /api/project — project state
+    if (pathname === '/api/project' && req.method === 'GET') {
+        json(res, {
+            project: projectConfig ? {
+                projectName: projectConfig.projectName,
+                projectDir: projectConfig.projectDir,
+                srcArtDir: projectConfig.srcArtDir,
+                config: projectConfig.config,
+            } : null,
+            assets,
+            folders,
+            encodersReady,
+        });
+        return;
+    }
+    // POST /api/open — open a project by path
+    if (pathname === '/api/open' && req.method === 'POST') {
+        const body = JSON.parse(await readBody(req));
+        try {
+            await openProject(body.projectDir);
+            json(res, { ok: true, projectName: projectConfig.projectName, assetCount: assets.length });
+        }
+        catch (err) {
+            json(res, { ok: false, error: err.message }, 400);
+        }
+        return;
+    }
+    // POST /api/process — process all pending or specific IDs
+    if (pathname === '/api/process' && req.method === 'POST') {
+        const body = JSON.parse(await readBody(req));
+        const ids = body.ids ?? assets.filter(a => a.status === 'pending').map(a => a.id);
+        const force = body.force ?? false;
+        if (force) {
+            for (const id of ids) {
+                const asset = assets.find(a => a.id === id);
+                if (asset && asset.type !== AssetType.MaterialSchema) {
+                    asset.status = 'pending';
+                }
+            }
+        }
+        // Process concurrently (max 8)
+        const pending = ids.filter(id => {
+            const a = assets.find(x => x.id === id);
+            return a && (a.status === 'pending' || force) && a.type !== AssetType.MaterialSchema;
+        });
+        const queue = [...pending];
+        async function drain() {
+            while (queue.length > 0) {
+                const id = queue.shift();
+                await processOneAsset(id);
+            }
+        }
+        const workers = [];
+        for (let i = 0; i < Math.min(8, pending.length); i++)
+            workers.push(drain());
+        Promise.all(workers).then(() => {
+            broadcast({ type: 'processing-complete' });
+        });
+        json(res, { ok: true, queued: pending.length });
+        return;
+    }
+    // POST /api/build — build .stow packs
+    if (pathname === '/api/build' && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const assetsById = new Map(assets.map(a => [a.id, a]));
+        const packs = projectConfig.config.packs ?? [{ name: 'default' }];
+        const cdnDir = path.resolve(projectConfig.projectDir, projectConfig.config.cdnAssetsPath ?? 'public/cdn-assets');
+        await fs.mkdir(cdnDir, { recursive: true });
+        const results = [];
+        for (const pack of packs) {
+            const packAssets = assets.filter(a => a.status === 'ready' &&
+                (a.settings.pack === pack.name || (!a.settings.pack && pack.name === 'default')));
+            if (packAssets.length === 0)
+                continue;
+            const packData = buildPack(packAssets, assetsById);
+            const outPath = path.join(cdnDir, `${pack.name}.stow`);
+            await fs.writeFile(outPath, packData);
+            results.push({ name: pack.name, size: packData.length, assetCount: packAssets.length });
+            console.log(`[server] Built ${pack.name}.stow (${packAssets.length} assets, ${(packData.length / 1024).toFixed(0)} KB)`);
+        }
+        broadcast({ type: 'build-complete', packs: results });
+        json(res, { ok: true, packs: results });
+        return;
+    }
+    // PUT /api/asset/:id/settings — update settings
+    if (pathname.startsWith('/api/asset/') && pathname.endsWith('/settings') && req.method === 'PUT') {
+        const id = decodeURIComponent(pathname.slice('/api/asset/'.length, -'/settings'.length));
+        const body = JSON.parse(await readBody(req));
+        const asset = assets.find(a => a.id === id);
+        if (!asset) {
+            json(res, { error: 'Asset not found' }, 404);
+            return;
+        }
+        const merged = { ...asset.settings, ...body.settings };
+        asset.settings = merged;
+        // Persist to disk
+        if (projectConfig) {
+            const meta = assetSettingsToStowmeta(asset);
+            await writeStowmeta(projectConfig.srcArtDir, id, meta);
+            if (asset.type === AssetType.MaterialSchema && body.settings.materialConfig) {
+                const stowmat = materialConfigToStowmat(merged.materialConfig);
+                await writeStowmat(projectConfig.srcArtDir, id, stowmat);
+            }
+        }
+        // Check if needs reprocessing
+        const needsReprocess = (asset.type === AssetType.Texture2D && (body.settings.quality !== undefined || body.settings.resize !== undefined || body.settings.generateMipmaps !== undefined)) ||
+            (asset.type === AssetType.StaticMesh && body.settings.dracoQuality !== undefined) ||
+            (asset.type === AssetType.Audio && (body.settings.aacQuality !== undefined || body.settings.audioSampleRate !== undefined));
+        if (needsReprocess) {
+            asset.status = 'pending';
+            broadcast({ type: 'asset-update', id, updates: { settings: merged, status: 'pending' } });
+            // Auto-trigger processing
+            processOneAsset(id);
+        }
+        else {
+            broadcast({ type: 'asset-update', id, updates: { settings: merged } });
+        }
+        json(res, { ok: true });
+        return;
+    }
+    // PUT /api/asset/:id/type — change asset type
+    if (pathname.startsWith('/api/asset/') && pathname.endsWith('/type') && req.method === 'PUT') {
+        const id = decodeURIComponent(pathname.slice('/api/asset/'.length, -'/type'.length));
+        const body = JSON.parse(await readBody(req));
+        const asset = assets.find(a => a.id === id);
+        if (!asset) {
+            json(res, { error: 'Asset not found' }, 404);
+            return;
+        }
+        asset.type = body.type;
+        asset.status = 'pending';
+        asset.metadata = undefined;
+        if (projectConfig) {
+            const meta = assetSettingsToStowmeta(asset);
+            await writeStowmeta(projectConfig.srcArtDir, id, meta);
+        }
+        broadcast({ type: 'asset-update', id, updates: { type: body.type, status: 'pending', metadata: undefined } });
+        processOneAsset(id);
+        json(res, { ok: true });
+        return;
+    }
+    // DELETE /api/asset/:id — delete asset
+    if (pathname.startsWith('/api/asset/') && req.method === 'DELETE') {
+        const id = decodeURIComponent(pathname.slice('/api/asset/'.length));
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        assets = assets.filter(a => a.id !== id);
+        BlobStore.remove(id);
+        deleteFile(projectConfig.srcArtDir, id);
+        deleteFile(projectConfig.srcArtDir, `${id}.stowmeta`);
+        deleteFile(projectConfig.srcArtDir, `${id}.stowcache`);
+        broadcast({ type: 'asset-removed', id });
+        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));
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const data = await readFile(projectConfig.srcArtDir, id);
+        if (!data) {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const ext = id.split('.').pop()?.toLowerCase() ?? '';
+        const mimeMap = {
+            png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg',
+            bmp: 'image/bmp', webp: 'image/webp', gif: 'image/gif',
+            wav: 'audio/wav', mp3: 'audio/mpeg', ogg: 'audio/ogg',
+            flac: 'audio/flac', aac: 'audio/aac', m4a: 'audio/mp4',
+        };
+        res.writeHead(200, {
+            'Content-Type': mimeMap[ext] ?? 'application/octet-stream',
+            'Content-Length': data.length,
+            'Access-Control-Allow-Origin': '*',
+        });
+        res.end(Buffer.from(data));
+        return;
+    }
+    // GET /api/asset/:id/processed — serve processed data (for audio preview)
+    if (pathname.startsWith('/api/asset/') && pathname.endsWith('/processed') && req.method === 'GET') {
+        const id = decodeURIComponent(pathname.slice('/api/asset/'.length, -'/processed'.length));
+        const data = BlobStore.getProcessed(id);
+        if (!data) {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const asset = assets.find(a => a.id === id);
+        const mime = asset?.type === AssetType.Audio ? 'audio/mp4' : 'application/octet-stream';
+        res.writeHead(200, {
+            'Content-Type': mime,
+            'Content-Length': data.length,
+            'Access-Control-Allow-Origin': '*',
+        });
+        res.end(Buffer.from(data));
+        return;
+    }
+    // POST /api/import — import files (receives multipart or raw binary)
+    if (pathname === '/api/import' && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const fileName = url.searchParams.get('name') ?? 'unknown';
+        const targetFolder = url.searchParams.get('folder') ?? '';
+        const relativePath = targetFolder ? `${targetFolder}/${fileName}` : fileName;
+        const data = await readBinaryBody(req);
+        const sourceData = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        await writeFile(projectConfig.srcArtDir, relativePath, sourceData);
+        const type = detectAssetType(fileName);
+        const configuredPacks = projectConfig.config.packs ?? [];
+        const meta = generateDefaultStowmeta(relativePath, type);
+        meta.pack = resolvePackName(meta.pack ?? '', configuredPacks);
+        await writeStowmeta(projectConfig.srcArtDir, relativePath, meta);
+        const settings = defaultAssetSettings();
+        settings.pack = resolvePackName(settings.pack, configuredPacks);
+        const asset = {
+            id: relativePath,
+            fileName,
+            stringId: meta.stringId,
+            type,
+            status: 'pending',
+            settings,
+            sourceSize: sourceData.length,
+            processedSize: 0,
+        };
+        BlobStore.setSource(relativePath, sourceData);
+        assets.push(asset);
+        broadcast({ type: 'asset-added', asset });
+        processOneAsset(relativePath);
+        json(res, { ok: true, id: relativePath });
+        return;
+    }
+    // POST /api/create-material
+    if (pathname === '/api/create-material' && 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 count = assets.filter(a => a.type === AssetType.MaterialSchema).length;
+        const name = `Material ${count + 1}`;
+        const baseName = `${name.replace(/\s+/g, '_')}.stowmat`;
+        const fileName = targetFolder ? `${targetFolder}/${baseName}` : baseName;
+        const settings = defaultAssetSettings();
+        settings.materialConfig = {
+            schemaId: '',
+            properties: [
+                { fieldName: 'Diffuse', fieldType: 0, previewFlag: 1, value: [1, 1, 1, 1], textureAssetId: null },
+                { fieldName: 'Tint', fieldType: 1, previewFlag: 2, value: [1, 1, 1, 1], textureAssetId: null },
+            ],
+        };
+        const asset = {
+            id: fileName,
+            fileName: name,
+            stringId: name,
+            type: AssetType.MaterialSchema,
+            status: 'ready',
+            settings,
+            sourceSize: 0,
+            processedSize: 0,
+        };
+        assets.push(asset);
+        const stowmat = materialConfigToStowmat(settings.materialConfig);
+        await writeStowmat(projectConfig.srcArtDir, fileName, stowmat);
+        const meta = assetSettingsToStowmeta(asset);
+        await writeStowmeta(projectConfig.srcArtDir, fileName, meta);
+        broadcast({ type: 'asset-added', asset });
+        json(res, { ok: true, asset });
+        return;
+    }
+    // POST /api/create-folder
+    if (pathname === '/api/create-folder' && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const body = JSON.parse(await readBody(req));
+        const parentFolder = body.parentFolder ?? '';
+        let folderName = 'New Folder';
+        let counter = 1;
+        const existingFolders = new Set(folders);
+        const parentPrefix = parentFolder ? `${parentFolder}/` : '';
+        while (existingFolders.has(`${parentPrefix}${folderName}`)) {
+            folderName = `New Folder ${counter}`;
+            counter++;
+        }
+        const folderPath = parentPrefix + folderName;
+        const fullPath = path.join(projectConfig.srcArtDir, folderPath);
+        await fs.mkdir(fullPath, { recursive: true });
+        folders.push(folderPath);
+        broadcast({ type: 'folder-added', path: folderPath });
+        json(res, { ok: true, path: folderPath });
+        return;
+    }
+    // PUT /api/project/config — update .felicityproject
+    if (pathname === '/api/project/config' && req.method === 'PUT') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const body = JSON.parse(await readBody(req));
+        if (body.packs !== undefined) {
+            projectConfig.config.packs = body.packs;
+        }
+        if (body.renamedPack) {
+            const { oldName, newName } = body.renamedPack;
+            for (const asset of assets) {
+                if ((asset.settings.pack ?? 'default') === oldName) {
+                    asset.settings.pack = newName;
+                    const meta = assetSettingsToStowmeta(asset);
+                    writeStowmeta(projectConfig.srcArtDir, asset.id, meta);
+                }
+            }
+        }
+        const configPath = path.join(projectConfig.projectDir, '.felicityproject');
+        await fs.writeFile(configPath, JSON.stringify(projectConfig.config, null, 2));
+        broadcast({ type: 'config-updated', config: projectConfig.config });
+        json(res, { ok: true });
+        return;
+    }
+    // ── Editor endpoints: prefabs + packs ─────────────────────────────────────
+    // GET /api/prefabs — list all .stowprefab files
+    if (pathname === '/api/prefabs' && req.method === 'GET') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const prefabsDir = projectConfig.config.prefabsPath
+            ? path.resolve(projectConfig.projectDir, projectConfig.config.prefabsPath)
+            : projectConfig.projectDir;
+        const prefabs = await scanPrefabFiles(prefabsDir, '');
+        json(res, { prefabs });
+        return;
+    }
+    // GET /api/prefab/* — read a .stowprefab file
+    if (pathname.startsWith('/api/prefab/') && req.method === 'GET') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const relPath = decodeURIComponent(pathname.slice('/api/prefab/'.length));
+        const prefabsDir = projectConfig.config.prefabsPath
+            ? path.resolve(projectConfig.projectDir, projectConfig.config.prefabsPath)
+            : projectConfig.projectDir;
+        const fullPath = path.join(prefabsDir, relPath);
+        try {
+            const data = await fs.readFile(fullPath, 'utf-8');
+            res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
+            res.end(data);
+        }
+        catch {
+            res.writeHead(404);
+            res.end('Not found');
+        }
+        return;
+    }
+    // PUT /api/prefab/* — write a .stowprefab file
+    if (pathname.startsWith('/api/prefab/') && req.method === 'PUT') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const relPath = decodeURIComponent(pathname.slice('/api/prefab/'.length));
+        const prefabsDir = projectConfig.config.prefabsPath
+            ? path.resolve(projectConfig.projectDir, projectConfig.config.prefabsPath)
+            : projectConfig.projectDir;
+        const fullPath = path.join(prefabsDir, relPath);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        const body = await readBody(req);
+        await fs.writeFile(fullPath, body);
+        json(res, { ok: true });
+        return;
+    }
+    // DELETE /api/prefab/* — delete a .stowprefab file
+    if (pathname.startsWith('/api/prefab/') && req.method === 'DELETE') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const relPath = decodeURIComponent(pathname.slice('/api/prefab/'.length));
+        const prefabsDir = projectConfig.config.prefabsPath
+            ? path.resolve(projectConfig.projectDir, projectConfig.config.prefabsPath)
+            : projectConfig.projectDir;
+        const fullPath = path.join(prefabsDir, relPath);
+        try {
+            await fs.unlink(fullPath);
+        }
+        catch { /* ignore */ }
+        json(res, { ok: true });
+        return;
+    }
+    // GET /api/pack/* — serve a .stow pack file from cdn-assets
+    if (pathname.startsWith('/api/pack/') && req.method === 'GET') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        const relPath = decodeURIComponent(pathname.slice('/api/pack/'.length));
+        const cdnDir = path.resolve(projectConfig.projectDir, projectConfig.config.cdnAssetsPath ?? 'public/cdn-assets');
+        const fullPath = path.join(cdnDir, relPath);
+        try {
+            const data = await fs.readFile(fullPath);
+            res.writeHead(200, {
+                'Content-Type': 'application/octet-stream',
+                'Content-Length': data.length,
+                'Access-Control-Allow-Origin': '*',
+            });
+            res.end(data);
+        }
+        catch {
+            res.writeHead(404);
+            res.end('Not found');
+        }
+        return;
+    }
+    // POST /api/scan — re-scan and detect new assets
+    if (pathname === '/api/scan' && req.method === 'POST') {
+        if (!projectConfig) {
+            json(res, { error: 'No project open' }, 400);
+            return;
+        }
+        await openProject(projectConfig.projectDir);
+        broadcast({ type: 'project-reloaded' });
+        json(res, { ok: true, assetCount: assets.length });
+        return;
+    }
+    // Static file serving for GUI apps (packer, editor)
+    // Sort: longer prefixes first so /packer matches before /
+    const mimeTypes = {
+        '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css',
+        '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
+        '.svg': 'image/svg+xml', '.wasm': 'application/wasm', '.ico': 'image/x-icon',
+    };
+    const sortedApps = Object.entries(staticApps).sort((a, b) => b[0].length - a[0].length);
+    for (const [prefix, dir] of sortedApps) {
+        const isRoot = prefix === '/';
+        if (!isRoot && !pathname.startsWith(prefix))
+            continue;
+        if (isRoot) {
+            // Don't match root for paths that belong to other apps
+            const belongsToOther = sortedApps.some(([p]) => p !== '/' && pathname.startsWith(p));
+            if (belongsToOther)
+                continue;
+        }
+        const stripped = isRoot ? pathname : pathname.slice(prefix.length) || '/';
+        const filePath = stripped === '/' ? '/index.html' : stripped;
+        const fullPath = path.join(dir, filePath);
+        try {
+            const fstat = await fs.stat(fullPath);
+            if (fstat.isFile()) {
+                let data = await fs.readFile(fullPath);
+                const ext = path.extname(fullPath).toLowerCase();
+                // Rewrite asset paths in HTML when serving under a prefix
+                if (ext === '.html' && !isRoot) {
+                    let html = data.toString('utf-8');
+                    html = html.replace(/(src|href)="\/(?!\/)/g, `$1="${prefix}/`);
+                    data = html;
+                }
+                res.writeHead(200, { 'Content-Type': mimeTypes[ext] ?? 'application/octet-stream' });
+                res.end(data);
+                return;
+            }
+        }
+        catch { /* fall through */ }
+        // SPA fallback
+        try {
+            let html = await fs.readFile(path.join(dir, 'index.html'), 'utf-8');
+            if (!isRoot) {
+                html = html.replace(/(src|href)="\/(?!\/)/g, `$1="${prefix}/`);
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(html);
+            return;
+        }
+        catch { /* no index.html */ }
+    }
+    // 404
+    res.writeHead(404);
+    res.end('Not found');
+}
+export async function startServer(opts = {}) {
+    const port = opts.port ?? 3210;
+    const apps = opts.staticApps ?? {};
+    const server = http.createServer(async (req, res) => {
+        try {
+            await handleRequest(req, res, apps);
+        }
+        catch (err) {
+            console.error('[server] Request error:', err);
+            if (!res.headersSent) {
+                json(res, { error: err.message }, 500);
+            }
+        }
+    });
+    const wss = new WebSocketServer({ server, path: '/api/ws' });
+    wss.on('connection', (ws) => {
+        wsClients.add(ws);
+        // Send current state on connect
+        ws.send(JSON.stringify({
+            type: 'init',
+            project: projectConfig ? {
+                projectName: projectConfig.projectName,
+                config: projectConfig.config,
+            } : null,
+            assets,
+            folders,
+            encodersReady,
+        }));
+        ws.on('close', () => wsClients.delete(ws));
+    });
+    // Initialize encoders in background
+    initEncoders(opts.wasmDir).then(ctx => {
+        processingCtx = ctx;
+    }).catch(err => {
+        console.error('[server] Encoder init failed:', err);
+    });
+    // Open project if specified
+    if (opts.projectDir) {
+        await openProject(opts.projectDir);
+        // Auto-process pending assets once encoders are ready
+        const waitForEncoders = async () => {
+            while (!processingCtx)
+                await new Promise(r => setTimeout(r, 100));
+            const pending = assets.filter(a => a.status === 'pending' && a.type !== AssetType.MaterialSchema);
+            if (pending.length > 0) {
+                console.log(`[server] Auto-processing ${pending.length} pending assets...`);
+                const queue = pending.map(a => a.id);
+                async function drain() {
+                    while (queue.length > 0) {
+                        const id = queue.shift();
+                        await processOneAsset(id);
+                    }
+                }
+                const workers = [];
+                for (let i = 0; i < Math.min(8, pending.length); i++)
+                    workers.push(drain());
+                await Promise.all(workers);
+                broadcast({ type: 'processing-complete' });
+            }
+        };
+        waitForEncoders();
+    }
+    return new Promise((resolve) => {
+        server.listen(port, () => {
+            console.log(`[stowkit] API server listening on http://localhost:${port}`);
+            resolve(server);
+        });
+    });
+}