ridgeline 0.7.4 → 0.7.11

package/dist/catalog/classify.js

@@ -0,0 +1,189 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyWithAI = exports.classifyByHeuristics = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+// --- Heuristic patterns (filename prefix → category) ---
+const IMAGE_HEURISTICS = [
+    [/^(bg|background|backdrop|sky|scenery)[_-]/i, "backgrounds"],
+    [/^(btn|button|icon|hud|bar|frame|panel|menu)[_-]/i, "ui"],
+    [/^(tile|floor|wall|ground|terrain|grass|stone|brick)[_-]/i, "tiles"],
+    [/^(char|character|player|enemy|npc|hero|sprite)[_-]/i, "characters"],
+    [/^(item|pickup|loot|potion|coin|gem|key|weapon|sword|shield)[_-]/i, "items"],
+    [/^(fx|effect|particle|explosion|spark|flash|smoke)[_-]/i, "effects"],
+    [/^(layout|mockup|wireframe|screen)[_-]/i, "layouts"],
+];
+const AUDIO_HEURISTICS = [
+    [/^(bgm|music|soundtrack|theme|ost|track|song)[_-]/i, "music"],
+    [/^(sfx|click|hit|boom|slash|jump|land|step|beep|ding|whoosh|pop|crash)[_-]/i, "sfx"],
+    [/^(ambient|ambience|wind|rain|water|forest|cave|city|night|crowd)[_-]/i, "ambience"],
+    [/^(voice|dialogue|narrat|speech|line)[_-]/i, "dialogue"],
+];
+const VIDEO_HEURISTICS = [
+    [/^(cutscene|cinematic|intro|outro|ending|opening)[_-]/i, "cinematics"],
+];
+const TEXT_HEURISTICS = [
+    [/^(dialogue|conversation|script|line|speech)[_-]/i, "dialogue"],
+    [/^(doc|readme|guide|manual|help|note)[_-]/i, "docs"],
+];
+/** Categories valid for each media type. */
+const CATEGORIES_BY_MEDIA = {
+    image: ["characters", "tiles", "items", "ui", "backgrounds", "effects", "layouts"],
+    audio: ["music", "sfx", "ambience", "dialogue"],
+    video: ["cinematics"],
+    text: ["dialogue", "data", "docs"],
+};
+const HEURISTICS_BY_MEDIA = {
+    image: IMAGE_HEURISTICS,
+    audio: AUDIO_HEURISTICS,
+    video: VIDEO_HEURISTICS,
+    text: TEXT_HEURISTICS,
+};
+/**
+ * Attempt to classify a file using filename pattern matching.
+ * Returns null if no heuristic matches confidently.
+ */
+const classifyByHeuristics = (filename, ext, mediaType) => {
+    const basename = path.basename(filename, ext);
+    // Text data files by extension
+    if (mediaType === "text" && [".json", ".csv", ".yaml", ".yml"].includes(ext)) {
+        return { category: "data", confidence: "medium" };
+    }
+    const patterns = HEURISTICS_BY_MEDIA[mediaType];
+    for (const [pattern, category] of patterns) {
+        if (pattern.test(basename)) {
+            return { category, confidence: "high" };
+        }
+    }
+    return null;
+};
+exports.classifyByHeuristics = classifyByHeuristics;
+// --- AI classification prompts ---
+const IMAGE_CLASSIFY_PROMPT = `You are classifying game assets into organized categories. Analyze this image and determine the best category.
+
+File: {filename}
+
+Available categories:
+- characters: Player characters, NPCs, enemies, character sprites, portraits
+- tiles: Ground tiles, wall tiles, terrain, tileable textures
+- items: Inventory items, pickups, powerups, weapons, equipment
+- ui: HUD elements, buttons, frames, health bars, menu components
+- backgrounds: Scenery, parallax layers, sky, environment backdrops
+- effects: Particles, explosions, magic effects, weather, visual FX
+- layouts: UI mockups, screen layouts, wireframes
+- uncategorized: Does not clearly fit any category above
+
+Respond with ONLY valid JSON:
+{
+  "category": "one of the categories above",
+  "confidence": "high" | "medium" | "low"
+}`;
+const buildNonImagePrompt = (filename, ext, mediaType, fileSizeBytes, contentPreview) => {
+    const categories = CATEGORIES_BY_MEDIA[mediaType];
+    const categoryList = categories
+        .map((c) => `- ${c}`)
+        .join("\n");
+    const preview = contentPreview
+        ? `\nContent preview (first 500 chars):\n\`\`\`\n${contentPreview}\n\`\`\``
+        : "";
+    return `You are classifying game asset files into organized categories based on filename, extension, and file content.
+
+File: ${filename}
+Extension: ${ext}
+Media type: ${mediaType}
+File size: ${Math.round(fileSizeBytes / 1024)} KB${preview}
+
+Available categories for ${mediaType}:
+${categoryList}
+- uncategorized: Does not clearly fit any category above
+
+Respond with ONLY valid JSON:
+{
+  "category": "one of the categories above",
+  "confidence": "high" | "medium" | "low"
+}`;
+};
+/** Invoke Claude and parse the classification result. */
+const invokeClaude = (prompt, model, timeoutMs, filename, filePath) => {
+    const args = ["-p", "--model", model, "--output-format", "json", prompt];
+    if (filePath)
+        args.push("--file", filePath);
+    try {
+        const result = (0, node_child_process_1.execFileSync)("claude", args, {
+            timeout: timeoutMs,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const parsed = JSON.parse(result);
+        const text = parsed.result ?? parsed;
+        const data = typeof text === "string" ? JSON.parse(text) : text;
+        return {
+            category: data.category ?? "uncategorized",
+            confidence: data.confidence ?? "low",
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`\x1b[33mClassification failed for ${filename}: ${msg}\x1b[0m\n`);
+        return { category: "uncategorized", confidence: "low" };
+    }
+};
+/**
+ * Classify a single file using AI.
+ * Dispatches to vision (images) or text-only (audio/video/text).
+ */
+const classifyWithAI = (absPath, filename, ext, mediaType, model, timeoutMs) => {
+    if (mediaType === "image") {
+        const prompt = IMAGE_CLASSIFY_PROMPT.replace("{filename}", filename);
+        return invokeClaude(prompt, model, timeoutMs, filename, absPath);
+    }
+    const stat = fs.statSync(absPath);
+    let contentPreview = null;
+    if (mediaType === "text") {
+        try {
+            const content = fs.readFileSync(absPath, "utf-8");
+            contentPreview = content.slice(0, 500);
+        }
+        catch {
+            // Binary or unreadable — skip preview
+        }
+    }
+    const prompt = buildNonImagePrompt(filename, ext, mediaType, stat.size, contentPreview);
+    return invokeClaude(prompt, model, timeoutMs, filename);
+};
+exports.classifyWithAI = classifyWithAI;
+//# sourceMappingURL=classify.js.map

package/dist/catalog/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/catalog/classify.ts"],"names":[],"mappings":"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"}

package/dist/catalog/extract-metadata.d.ts

@@ -0,0 +1,41 @@
+type ImageMetadata = {
+    width: number;
+    height: number;
+    format: string;
+    hasAlpha: boolean;
+    channels: number;
+};
+type PaletteResult = {
+    dominantColour: string;
+    palette: string[];
+};
+type SpritesheetInfo = {
+    isSpritesheet: boolean;
+    frameCount: number;
+    frameSize: {
+        w: number;
+        h: number;
+    } | null;
+    frameDirection: "horizontal" | "vertical" | null;
+};
+/** Extract image dimensions, format, alpha, and channel info via sharp. */
+export declare const extractImageMetadata: (filepath: string) => Promise<ImageMetadata>;
+/** Extract dominant colour and 6-colour palette via colorthief. */
+export declare const extractPalette: (filepath: string) => Promise<PaletteResult>;
+/** Detect spritesheet from dimensions — one dimension is an exact multiple of the other. */
+export declare const detectSpritesheet: (width: number, height: number) => SpritesheetInfo;
+/**
+ * Detect tilability by comparing edge pixel strips.
+ * If the top row matches the bottom row (and left col matches right col),
+ * the image is likely tileable.
+ */
+export declare const detectTileable: (filepath: string, width: number, height: number) => Promise<boolean>;
+/** Compute MD5 content hash for change detection (not security-sensitive). */
+export declare const computeContentHash: (filepath: string) => string;
+type BasicMetadata = {
+    fileSizeBytes: number;
+    extension: string;
+};
+/** Extract basic file metadata for non-image assets. */
+export declare const extractBasicMetadata: (filepath: string) => BasicMetadata;
+export {};

package/dist/catalog/extract-metadata.js

@@ -0,0 +1,175 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBasicMetadata = exports.computeContentHash = exports.detectTileable = exports.detectSpritesheet = exports.extractPalette = exports.extractImageMetadata = void 0;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// Dynamic imports for native deps — only loaded when catalog command runs
+let sharpModule = null;
+let colorThiefModule = null;
+const loadSharp = async () => {
+    if (!sharpModule)
+        sharpModule = (await Promise.resolve().then(() => __importStar(require("sharp")))).default;
+    return sharpModule;
+};
+const loadColorThief = async () => {
+    if (!colorThiefModule)
+        colorThiefModule = (await Promise.resolve().then(() => __importStar(require("colorthief")))).default;
+    return colorThiefModule;
+};
+/** Extract image dimensions, format, alpha, and channel info via sharp. */
+const extractImageMetadata = async (filepath) => {
+    const sharp = await loadSharp();
+    const meta = await sharp(filepath).metadata();
+    return {
+        width: meta.width ?? 0,
+        height: meta.height ?? 0,
+        format: meta.format ?? "unknown",
+        hasAlpha: meta.hasAlpha ?? false,
+        channels: meta.channels ?? 3,
+    };
+};
+exports.extractImageMetadata = extractImageMetadata;
+/** Extract dominant colour and 6-colour palette via colorthief. */
+const extractPalette = async (filepath) => {
+    const ColorThief = await loadColorThief();
+    try {
+        const dominant = await ColorThief.getColor(filepath);
+        const palette = await ColorThief.getPalette(filepath, 6);
+        return {
+            dominantColour: rgbToHex(dominant),
+            palette: palette.map(rgbToHex),
+        };
+    }
+    catch {
+        // colorthief can fail on very small or single-colour images
+        return { dominantColour: "#000000", palette: [] };
+    }
+};
+exports.extractPalette = extractPalette;
+/** Detect spritesheet from dimensions — one dimension is an exact multiple of the other. */
+const detectSpritesheet = (width, height) => {
+    if (width <= 0 || height <= 0 || width === height) {
+        return { isSpritesheet: false, frameCount: 1, frameSize: null, frameDirection: null };
+    }
+    const isWideStrip = width > height && width % height === 0;
+    const isTallStrip = height > width && height % width === 0;
+    if (isWideStrip) {
+        return {
+            isSpritesheet: true,
+            frameCount: width / height,
+            frameSize: { w: height, h: height },
+            frameDirection: "horizontal",
+        };
+    }
+    if (isTallStrip) {
+        return {
+            isSpritesheet: true,
+            frameCount: height / width,
+            frameSize: { w: width, h: width },
+            frameDirection: "vertical",
+        };
+    }
+    return { isSpritesheet: false, frameCount: 1, frameSize: null, frameDirection: null };
+};
+exports.detectSpritesheet = detectSpritesheet;
+/**
+ * Detect tilability by comparing edge pixel strips.
+ * If the top row matches the bottom row (and left col matches right col),
+ * the image is likely tileable.
+ */
+const detectTileable = async (filepath, width, height) => {
+    if (width < 2 || height < 2)
+        return false;
+    const sharp = await loadSharp();
+    try {
+        // Extract top and bottom edge strips (1px high)
+        const topPixels = await sharp(filepath)
+            .extract({ left: 0, top: 0, width, height: 1 })
+            .raw()
+            .toBuffer();
+        const bottomPixels = await sharp(filepath)
+            .extract({ left: 0, top: height - 1, width, height: 1 })
+            .raw()
+            .toBuffer();
+        // Extract left and right edge strips (1px wide)
+        const leftPixels = await sharp(filepath)
+            .extract({ left: 0, top: 0, width: 1, height })
+            .raw()
+            .toBuffer();
+        const rightPixels = await sharp(filepath)
+            .extract({ left: width - 1, top: 0, width: 1, height })
+            .raw()
+            .toBuffer();
+        const hSimilarity = bufferSimilarity(topPixels, bottomPixels);
+        const vSimilarity = bufferSimilarity(leftPixels, rightPixels);
+        // Threshold: edges must be >85% similar
+        return hSimilarity > 0.85 && vSimilarity > 0.85;
+    }
+    catch {
+        return false;
+    }
+};
+exports.detectTileable = detectTileable;
+/** Compute MD5 content hash for change detection (not security-sensitive). */
+const computeContentHash = (filepath) => {
+    const data = fs.readFileSync(filepath);
+    return crypto.createHash("md5").update(data).digest("hex");
+};
+exports.computeContentHash = computeContentHash;
+/** Extract basic file metadata for non-image assets. */
+const extractBasicMetadata = (filepath) => {
+    const stat = fs.statSync(filepath);
+    return {
+        fileSizeBytes: stat.size,
+        extension: path.extname(filepath).toLowerCase(),
+    };
+};
+exports.extractBasicMetadata = extractBasicMetadata;
+// --- Helpers ---
+const rgbToHex = (rgb) => "#" + rgb.map((c) => c.toString(16).padStart(2, "0")).join("");
+/** Compare two raw pixel buffers and return similarity ratio (0..1). */
+const bufferSimilarity = (a, b) => {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let matching = 0;
+    for (let i = 0; i < a.length; i++) {
+        if (Math.abs(a[i] - b[i]) <= 16)
+            matching++; // tolerance of 16/255
+    }
+    return matching / a.length;
+};
+//# sourceMappingURL=extract-metadata.js.map

package/dist/catalog/extract-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-metadata.js","sourceRoot":"","sources":["../../src/catalog/extract-metadata.ts"],"names":[],"mappings":"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"}

package/dist/catalog/pack-sprites.d.ts

@@ -0,0 +1,8 @@
+import { AssetCatalog } from "./types";
+/**
+ * Pack sprites into texture atlases grouped by category.
+ * Uses free-tex-packer-core to produce PixiJS-compatible JSON + PNG atlas files.
+ *
+ * Output: <assetDir>/packed/<category>.png + <category>.json
+ */
+export declare const packAtlases: (assetDir: string, catalog: AssetCatalog) => Promise<void>;

package/dist/catalog/pack-sprites.js

@@ -0,0 +1,106 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packAtlases = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Pack sprites into texture atlases grouped by category.
+ * Uses free-tex-packer-core to produce PixiJS-compatible JSON + PNG atlas files.
+ *
+ * Output: <assetDir>/packed/<category>.png + <category>.json
+ */
+const packAtlases = async (assetDir, catalog) => {
+    // Dynamic import — only loaded when --pack is used
+    const { packAsync } = await Promise.resolve().then(() => __importStar(require("free-tex-packer-core")));
+    const outputDir = path.join(assetDir, "packed");
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+    // Group assets by category (skip layouts — they're reference-only)
+    const byCategory = new Map();
+    for (const asset of catalog.assets) {
+        if (asset.isReferenceOnly || asset.category === "layouts")
+            continue;
+        // Skip backgrounds — typically too large for atlases
+        if (asset.category === "backgrounds")
+            continue;
+        const list = byCategory.get(asset.category) ?? [];
+        list.push(asset.file);
+        byCategory.set(asset.category, list);
+    }
+    for (const [category, files] of byCategory) {
+        if (files.length === 0)
+            continue;
+        const images = files
+            .map((f) => {
+            const absPath = path.join(assetDir, f);
+            if (!fs.existsSync(absPath))
+                return null;
+            return {
+                path: path.basename(f, path.extname(f)),
+                contents: fs.readFileSync(absPath),
+            };
+        })
+            .filter(Boolean);
+        if (images.length === 0)
+            continue;
+        try {
+            const result = await packAsync(images, {
+                textureName: category,
+                width: 2048,
+                height: 2048,
+                fixedSize: false,
+                padding: 1,
+                allowRotation: false,
+                detectIdentical: true,
+                allowTrim: true,
+                exporter: "Pixi",
+                removeFileExtension: true,
+            });
+            for (const file of result) {
+                const outPath = path.join(outputDir, file.name);
+                fs.writeFileSync(outPath, file.buffer);
+            }
+            process.stderr.write(`\x1b[90m  Packed ${category}: ${images.length} sprites\x1b[0m\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`\x1b[33mFailed to pack ${category}: ${msg}\x1b[0m\n`);
+        }
+    }
+};
+exports.packAtlases = packAtlases;
+//# sourceMappingURL=pack-sprites.js.map

package/dist/catalog/pack-sprites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-sprites.js","sourceRoot":"","sources":["../../src/catalog/pack-sprites.ts"],"names":[],"mappings":"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"}

package/dist/catalog/parse-conventions.d.ts

@@ -0,0 +1,25 @@
+type ConventionResult = {
+    category: string;
+    name: string;
+    subject: string;
+    state: string | null;
+};
+/**
+ * Parse category, subject, and state from the filesystem path.
+ *
+ * "characters/knight-walk.png" →
+ *   { category: "characters", name: "knight-walk", subject: "knight", state: "walk" }
+ *
+ * "export_003.png" (no subdirectory) →
+ *   { category: "uncategorized", name: "export_003", subject: "export_003", state: null }
+ */
+export declare const parseConventions: (relativePath: string) => ConventionResult;
+type CategoryDefaults = {
+    zLayer: string;
+    anchor: string;
+};
+/** Infer default z-layer and anchor from category name. */
+export declare const inferDefaults: (category: string) => CategoryDefaults;
+/** Categories that always get vision descriptions regardless of --describe flag. */
+export declare const AUTO_DESCRIBE_CATEGORIES: Set<string>;
+export {};

package/dist/catalog/parse-conventions.js

@@ -0,0 +1,86 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTO_DESCRIBE_CATEGORIES = exports.inferDefaults = exports.parseConventions = void 0;
+const path = __importStar(require("node:path"));
+/**
+ * Parse category, subject, and state from the filesystem path.
+ *
+ * "characters/knight-walk.png" →
+ *   { category: "characters", name: "knight-walk", subject: "knight", state: "walk" }
+ *
+ * "export_003.png" (no subdirectory) →
+ *   { category: "uncategorized", name: "export_003", subject: "export_003", state: null }
+ */
+const parseConventions = (relativePath) => {
+    const parts = relativePath.split(path.sep);
+    const category = parts.length > 1 ? parts[parts.length - 2] : "uncategorized";
+    const filename = path.basename(relativePath, path.extname(relativePath));
+    const segments = filename.split("-");
+    return {
+        category,
+        name: filename,
+        subject: segments[0] || filename,
+        state: segments.length > 1 ? segments.slice(1).join("-") : null,
+    };
+};
+exports.parseConventions = parseConventions;
+const CATEGORY_DEFAULTS = {
+    // Image categories
+    characters: { zLayer: "entity", anchor: "bottom-center" },
+    tiles: { zLayer: "ground", anchor: "top-left" },
+    items: { zLayer: "entity", anchor: "center" },
+    ui: { zLayer: "ui", anchor: "center" },
+    backgrounds: { zLayer: "background", anchor: "top-left" },
+    effects: { zLayer: "foreground", anchor: "center" },
+    layouts: { zLayer: "ui", anchor: "top-left" },
+    // Audio categories
+    music: { zLayer: "background", anchor: "center" },
+    sfx: { zLayer: "entity", anchor: "center" },
+    ambience: { zLayer: "background", anchor: "center" },
+    dialogue: { zLayer: "entity", anchor: "center" },
+    // Video categories
+    cinematics: { zLayer: "foreground", anchor: "center" },
+    // Text/data categories
+    data: { zLayer: "entity", anchor: "center" },
+    docs: { zLayer: "entity", anchor: "center" },
+};
+const DEFAULT_FALLBACK = { zLayer: "entity", anchor: "center" };
+/** Infer default z-layer and anchor from category name. */
+const inferDefaults = (category) => CATEGORY_DEFAULTS[category] ?? DEFAULT_FALLBACK;
+exports.inferDefaults = inferDefaults;
+/** Categories that always get vision descriptions regardless of --describe flag. */
+exports.AUTO_DESCRIBE_CATEGORIES = new Set(["layouts", "ui"]);
+//# sourceMappingURL=parse-conventions.js.map

package/dist/catalog/parse-conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-conventions.js","sourceRoot":"","sources":["../../src/catalog/parse-conventions.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAiC;AASjC;;;;;;;;GAQG;AACI,MAAM,gBAAgB,GAAG,CAAC,YAAoB,EAAoB,EAAE;IACzE,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAA;IAC7E,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAA;IACxE,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAEpC,OAAO;QACL,QAAQ;QACR,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ;QAChC,KAAK,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI;KAChE,CAAA;AACH,CAAC,CAAA;AAZY,QAAA,gBAAgB,oBAY5B;AAOD,MAAM,iBAAiB,GAAqC;IAC1D,mBAAmB;IACnB,UAAU,EAAG,EAAE,MAAM,EAAE,QAAQ,EAAM,MAAM,EAAE,eAAe,EAAE;IAC9D,KAAK,EAAQ,EAAE,MAAM,EAAE,QAAQ,EAAM,MAAM,EAAE,UAAU,EAAE;IACzD,KAAK,EAAQ,EAAE,MAAM,EAAE,QAAQ,EAAM,MAAM,EAAE,QAAQ,EAAE;IACvD,EAAE,EAAW,EAAE,MAAM,EAAE,IAAI,EAAU,MAAM,EAAE,QAAQ,EAAE;IACvD,WAAW,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE;IACzD,OAAO,EAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE;IACvD,OAAO,EAAM,EAAE,MAAM,EAAE,IAAI,EAAU,MAAM,EAAE,UAAU,EAAE;IACzD,mBAAmB;IACnB,KAAK,EAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE;IACvD,GAAG,EAAU,EAAE,MAAM,EAAE,QAAQ,EAAM,MAAM,EAAE,QAAQ,EAAE;IACvD,QAAQ,EAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE;IACvD,QAAQ,EAAK,EAAE,MAAM,EAAE,QAAQ,EAAM,MAAM,EAAE,QAAQ,EAAE;IACvD,mBAAmB;IACnB,UAAU,EAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE;IACvD,uBAAuB;IACvB,IAAI,EAAS,EAAE,MAAM,EAAE,QAAQ,EAAM,MAAM,EAAE,QAAQ,EAAE;IACvD,IAAI,EAAS,EAAE,MAAM,EAAE,QAAQ,EAAM,MAAM,EAAE,QAAQ,EAAE;CACxD,CAAA;AAED,MAAM,gBAAgB,GAAqB,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;AAEjF,2DAA2D;AACpD,MAAM,aAAa,GAAG,CAAC,QAAgB,EAAoB,EAAE,CAClE,iBAAiB,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAA;AADpC,QAAA,aAAa,iBACuB;AAEjD,oFAAoF;AACvE,QAAA,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAA"}