@afromero/kin3o 0.1.0 → 0.2.1

package/README.md

@@ -4,7 +4,7 @@
 
 **Text to Motion. From your terminal.**
 
-[![npm](https://img.shields.io/npm/v/kin3o)](https://www.npmjs.com/package/kin3o)
+[![npm](https://img.shields.io/npm/v/@afromero/kin3o)](https://www.npmjs.com/package/@afromero/kin3o)
 [![CI](https://github.com/affromero/kin3o/actions/workflows/ci.yml/badge.svg)](https://github.com/affromero/kin3o/actions/workflows/ci.yml)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
@@ -12,36 +12,33 @@
 
 AI-powered Lottie animation generator. Turns natural language prompts into valid, playable Lottie JSON and interactive dotLottie state machines using your existing Claude or Codex subscription.
 
+<img src="assets/stick-figure-demo.gif" alt="Interactive state machine demo — hover to walk, press to run" width="640" />
+
 </div>
 
 ## Why?
 
-Every motion design tool (Rive, LottieFiles, Hera) sandboxes its AI inside a walled-garden editor, charges per-generation credits, and requires designs we don't have. kin3o spawns `claude --print` or `codex exec` as subprocesses to use existing Max/Pro subscriptions at zero marginal cost, with full context control via system prompts.
+Great tools like [LottieFiles](https://lottiefiles.com), [Lottielab](https://www.lottielab.com), and [Rive](https://rive.app) offer powerful visual editors, massive animation libraries, and team collaboration — if you need a full design workflow, they're excellent choices.
+
+kin3o takes a different approach: it's a CLI tool for developers who want to generate animations from their terminal using AI subscriptions they already pay for. Search and download from the [LottieFiles](https://lottiefiles.com) marketplace (122K+ community animations), refine with AI, and publish back — all without leaving the terminal.
 
-## Competitors
+## Choosing the right tool
 
-| Feature | **kin3o** | [LottieFiles](https://lottiefiles.com) | [LottieGen](https://lottiegenai.webflow.io/) | [Recraft](https://www.recraft.ai) | [Lottielab](https://www.lottielab.com) |
-|---------|-----------|-----------------|---------------|-------------|---------------|
-| Text → Lottie JSON | **Yes** | Yes (Motion Copilot) | Yes | Yes (via export) | No |
-| Text → State machines | **Yes (dotLottie)** | No | No | No | No |
-| CLI | **Yes** | No | No | No | No |
-| Web editor | **CLI-first** | Yes | Yes | Yes | Yes |
-| Open source | **Yes** | No | No | No | No |
-| Uses your own AI sub | **Yes** | No | No | No | No |
-| Custom design tokens | **Yes** | No | No | No | No |
-| Animation library | **Compatible with [LottieFiles](https://lottiefiles.com)** | Yes (massive) | No | Yes | Yes |
-| State machines | **Yes (dotLottie)** | Yes | No | No | Yes |
-| Team collaboration | **Git-native** | Yes | No | Yes | Yes |
-| Programmatic access | **Yes (CLI + stdout)** | Yes (REST API) | No | Yes (REST API) | Yes (REST API) |
-| **Price** | **Free (OSS)** | Free / $19.99+/mo | Waitlist (TBD) | Free (50/day) / $10+/mo | Free / up to $99/mo |
+There are great tools for different animation workflows. Here's an honest look at where each shines:
 
-> Prices as of March 2026.
+| Tool | Best for | Strengths |
+|------|----------|-----------|
+| **kin3o** | Developers who want animations from their terminal | CLI-first, uses your existing AI subscription, open source, git-friendly JSON output, interactive state machines from text |
+| [**Rive**](https://rive.app) | Complex interactive animations with a visual editor | Skeletal animation, mesh deformation, runtime inputs (cursor tracking, sliders), built-in state machines, beautiful visual editor |
+| [**LottieFiles**](https://lottiefiles.com) | Finding and sharing animations | Massive community library, Motion Copilot AI, After Effects integration, team collaboration — kin3o integrates directly for search, download, and publish |
+| [**Lottielab**](https://www.lottielab.com) | Designing Lottie animations visually | Polished editor with timeline and keyframes, team collaboration, export to Lottie JSON |
+| [**Recraft**](https://www.recraft.ai) | AI-powered design with animation export | Visual AI design tool, vector and animation output, broad creative capabilities |
 
 ## Quick Start
 
 ```bash
 # Install globally
-npm install -g kin3o
+npm install -g @afromero/kin3o
 
 # Generate a static animation
 kin3o generate "loading spinner with 3 dots"
@@ -53,7 +50,7 @@ kin3o generate "toggle switch with on/off states" --interactive
 Or use without installing:
 
 ```bash
-npx kin3o generate "pulsing circle"
+npx @afromero/kin3o generate "pulsing circle"
 ```
 
 ## CLI Usage
@@ -69,6 +66,10 @@ kin3o generate "loading dots" --tokens sotto
 kin3o generate "toggle switch with on/off states" --interactive
 kin3o generate "like button with hover and click" --interactive
 
+# Refine an existing animation
+kin3o refine output/animation.json "make it faster and add easing"
+kin3o refine output/animation.lottie "add a bounce on the pressed state"
+
 # Preview
 kin3o preview output/animation.json
 kin3o preview output/animation.lottie
@@ -79,6 +80,21 @@ kin3o validate output/animation.lottie
 
 # List available AI providers
 kin3o providers
+
+# Marketplace (LottieFiles)
+kin3o search "loading spinner"                         # Search marketplace
+kin3o search --featured --limit 10                     # Browse featured
+kin3o search --popular                                 # Browse popular
+kin3o search "button" --no-browser                     # Terminal output only
+kin3o download abc12345                                # Download by UUID
+kin3o download <url> --lottie                          # Download as .lottie
+kin3o login                                            # Authenticate for publishing
+kin3o publish output/anim.json --name "My Anim" --tags "loading,ui"
+kin3o logout                                           # Clear auth token
+
+# Live preview with hot reload
+kin3o view output/animation.json                       # File watcher + auto-reload
+kin3o view output/animation.lottie --port 3000         # Specific port
 ```
 
 ### Options
@@ -91,6 +107,13 @@ kin3o providers
 | `--no-preview` | Skip browser preview |
 | `-i, --interactive` | Generate interactive state machine (`.lottie` output) |
 | `-t, --tokens <path>` | Design tokens JSON or `sotto` preset |
+| `--featured` | Browse featured marketplace animations |
+| `--popular` | Browse popular marketplace animations |
+| `--recent` | Browse recent marketplace animations |
+| `--limit <n>` | Number of search results (default: 20) |
+| `--no-browser` | Print search results in terminal |
+| `--lottie` | Download `.lottie` format instead of `.json` |
+| `--port <n>` | Port for view server (auto-selects if omitted) |
 
 ## Using Generated Animations
 
@@ -139,41 +162,29 @@ animationView.play()
 </script>
 ```
 
-## Why Lottie over Rive?
-
-### For AI generation
-
-| Criteria | Lottie | Rive |
-|----------|--------|------|
-| Format | JSON (text, diffable) | Binary (.riv) |
-| LLM can generate? | Yes (structured JSON) | No (binary, no public writer) |
-| Web runtime | lottie-web (165KB) | @rive-app/canvas (200KB+) |
-| React integration | lottie-react | @rive-app/react-canvas |
-| Ecosystem | Massive (LottieFiles, AE) | Growing (Rive editor) |
-| **Verdict for AI gen** | **Winner** | Binary format = blocker |
+## Why Lottie?
 
-### Animation capabilities
+kin3o generates [Lottie](https://airbnb.io/lottie/) because its JSON format is ideal for AI generation — structured, text-based, and diffable. [Rive](https://rive.app) is a fantastic tool with capabilities Lottie doesn't have (skeletal animation, mesh deformation, runtime inputs), but its binary `.riv` format can't be generated by LLMs today.
 
-| Capability | Lottie | Rive |
-|-----------|--------|------|
-| Shape animation (scale, rotate, position, opacity) | ✓ | ✓ |
-| Path morphing, trim paths | ✓ | ✓ |
-| Color transitions | ✓ | ✓ |
-| Multi-layer compositions | ✓ | ✓ |
-| Masking, mattes | ✓ | ✓ |
-| Easing curves | ✓ | ✓ |
-| State machines (hover, click, drag → states) | ✓ (dotLottie) | ✓ |
-| Skeletal/bone animation | ✗ | ✓ |
-| Mesh deformation | ✗ | ✓ |
-| Runtime input (eyes follow cursor, sliders) | ✗ | ✓ |
+| What you need | Best tool |
+|--------------|-----------|
+| AI-generated animations from text | **kin3o** (Lottie JSON) |
+| Interactive state machines from text | **kin3o** (dotLottie) |
+| Skeletal animation, mesh deformation | [Rive](https://rive.app) (visual editor) |
+| Massive animation library + community | [LottieFiles](https://lottiefiles.com) |
+| Polished visual animation editor | [Lottielab](https://www.lottielab.com) or [Rive](https://rive.app) |
+| Runtime inputs (cursor tracking, sliders) | [Rive](https://rive.app) |
+| Search, download, publish to marketplace | **kin3o** + [LottieFiles](https://lottiefiles.com) |
 
-Lottie covers ~90% of real-world animation needs. The 10% Rive wins on — skeletal animation, mesh deformation — requires an interactive editor to wire up, not something generatable from a text prompt. State machines are now covered by kin3o via dotLottie.
+Lottie covers shapes, paths, easing, color transitions, masking, and — via dotLottie — interactive state machines (hover, click, tap). That handles the vast majority of UI animations, loading states, and micro-interactions.
 
 ## Architecture
 
 ```
 Static:      prompt → generate() → extractJson() → validateLottie() → autoFix() → .json → preview
 Interactive: prompt → generate() → extractInteractiveJson() → validate animations + state machine → .lottie → preview
+Marketplace: search → browse → download → validate → .json/.lottie → refine → publish
+Live preview: view <file> → HTTP server + fs.watch → SSE → browser auto-reload
 ```
 
 ### Prompt System

package/dist/index.js

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
-import { writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { Command } from 'commander';
 import { PROVIDERS, detectAvailableProviders, getDefaultProvider } from './providers/registry.js';
-import { buildSystemPrompt, buildInteractiveSystemPrompt, loadDesignTokens } from './prompts/index.js';
+import { buildSystemPrompt, buildInteractiveSystemPrompt, buildRefinementUserPrompt, buildInteractiveRefinementUserPrompt, loadDesignTokens } from './prompts/index.js';
 import { validateLottie, autoFix } from './validator.js';
 import { validateStateMachine } from './state-machine-validator.js';
 import { openPreview, openDotLottiePreview } from './preview.js';
 import { writeDotLottie, readDotLottie } from './packager.js';
-import { extractJson, extractInteractiveJson, slugify, ensureOutputDir } from './utils.js';
+import { extractJson, extractInteractiveJson, slugify, ensureOutputDir, nextVersionedPath } from './utils.js';
+import { searchAnimations, featuredAnimations, popularAnimations, recentAnimations, resolveTarget, createLoginToken, pollForAccessToken, createUploadRequest, uploadFile, publishAnimation } from './marketplace.js';
+import { openSearchResults } from './marketplace-preview.js';
+import { loadAuthToken, loadAuthExpiry, saveAuthToken, clearAuthToken } from './marketplace-auth.js';
+import { startViewServer } from './view.js';
 const program = new Command();
 program
     .name('kin3o')
@@ -154,6 +157,92 @@ async function handleInteractiveOutput(content, prompt, options) {
         console.log(`  ✓ Preview opened: ${previewPath}`);
     }
 }
+program
+    .command('refine <file> <prompt>')
+    .description('Refine an existing Lottie animation with a follow-up instruction')
+    .option('-p, --provider <provider>', 'AI provider to use')
+    .option('-m, --model <model>', 'Model to use')
+    .option('-o, --output <path>', 'Output file path')
+    .option('--no-preview', 'Skip opening preview in browser')
+    .option('-t, --tokens <path>', 'Path to design tokens JSON (or "sotto" for built-in)')
+    .action(async (file, prompt, rawOptions) => {
+    const resolvedPath = resolve(file);
+    // 1. Validate input file
+    if (!existsSync(resolvedPath)) {
+        console.error(`  ✗ File not found: ${resolvedPath}`);
+        process.exit(1);
+    }
+    const isInteractive = file.endsWith('.lottie');
+    const mode = isInteractive ? 'interactive' : 'static';
+    console.log(`\nkin3o — Refining ${mode} animation...`);
+    // 2. Read current animation
+    let currentJson;
+    try {
+        if (isInteractive) {
+            const { animations, stateMachine } = await readDotLottie(resolvedPath);
+            currentJson = JSON.stringify({ animations, stateMachine }, null, 2);
+        }
+        else {
+            currentJson = readFileSync(resolvedPath, 'utf-8');
+            JSON.parse(currentJson); // validate it's valid JSON
+        }
+    }
+    catch (err) {
+        console.error(`  ✗ Failed to read input file: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    // 3. Warn on large files
+    const sizeKb = Math.round(statSync(resolvedPath).size / 1024);
+    if (sizeKb > 500) {
+        console.log(`  ⚠ Large animation (${sizeKb}KB) — may hit provider token limits`);
+    }
+    // 4. Detect provider
+    let providerKey = rawOptions.provider;
+    if (!providerKey) {
+        providerKey = await getDefaultProvider() ?? undefined;
+        if (!providerKey) {
+            console.error('  ✗ No AI providers available. Install Claude Code, Codex, or set ANTHROPIC_API_KEY.');
+            process.exit(1);
+        }
+    }
+    const provider = PROVIDERS[providerKey];
+    if (!provider) {
+        console.error(`  ✗ Unknown provider "${providerKey}". Run "kin3o providers" to see available options.`);
+        process.exit(1);
+    }
+    const model = rawOptions.model ?? provider.defaultModel;
+    console.log(`  Provider: ${provider.displayName} (${model})`);
+    console.log(`  Refining: ${file}`);
+    console.log(`  Instruction: "${prompt}"\n`);
+    // 5. Build prompts
+    const tokens = rawOptions.tokens ? loadDesignTokens(rawOptions.tokens) : undefined;
+    const systemPrompt = isInteractive
+        ? buildInteractiveSystemPrompt(tokens)
+        : buildSystemPrompt(tokens);
+    const userPrompt = isInteractive
+        ? buildInteractiveRefinementUserPrompt(currentJson, prompt)
+        : buildRefinementUserPrompt(currentJson, prompt);
+    // 6. Generate refined output
+    try {
+        const result = await provider.generate(model, systemPrompt, userPrompt);
+        console.log(`  ✓ Refined in ${(result.durationMs / 1000).toFixed(1)}s`);
+        // 7. Compute output path
+        const outputDir = ensureOutputDir();
+        const outputFile = rawOptions.output ?? nextVersionedPath(resolvedPath, outputDir);
+        const options = { ...rawOptions, interactive: isInteractive, output: outputFile };
+        if (isInteractive) {
+            await handleInteractiveOutput(result.content, prompt, options);
+        }
+        else {
+            await handleStaticOutput(result.content, prompt, options);
+        }
+        console.log('');
+    }
+    catch (err) {
+        console.error(`  ✗ Refinement failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
 program
     .command('preview <file>')
     .description('Preview a Lottie JSON or .lottie file in the browser')
@@ -176,6 +265,33 @@ program
         process.exit(1);
     }
 });
+program
+    .command('view <file>')
+    .description('Live preview with hot reload (file watcher + auto-reload)')
+    .option('--port <n>', 'Port number (auto-selects if omitted)')
+    .action(async (file, options) => {
+    const resolvedPath = resolve(file);
+    if (!existsSync(resolvedPath)) {
+        console.error(`  ✗ File not found: ${resolvedPath}`);
+        process.exit(1);
+    }
+    const ext = resolvedPath.split('.').pop()?.toLowerCase();
+    if (ext !== 'json' && ext !== 'lottie') {
+        console.error('  ✗ Unsupported file type. Use .json or .lottie');
+        process.exit(1);
+    }
+    const port = options.port ? parseInt(options.port, 10) : undefined;
+    console.log('\nkin3o — Live preview');
+    const server = await startViewServer(resolvedPath, { port });
+    console.log(`  ✓ Serving ${file}`);
+    console.log(`  ✓ ${server.url}`);
+    console.log('  Watching for changes... (Ctrl+C to stop)\n');
+    process.on('SIGINT', () => {
+        server.close();
+        console.log('\n  ✓ Server stopped');
+        process.exit(0);
+    });
+});
 program
     .command('providers')
     .description('List available AI providers')
@@ -246,4 +362,238 @@ program
         process.exit(1);
     }
 });
+program
+    .command('search [query]')
+    .description('Search LottieFiles marketplace for animations')
+    .option('--featured', 'Show featured animations', false)
+    .option('--popular', 'Show popular animations', false)
+    .option('--recent', 'Show recent animations', false)
+    .option('--limit <n>', 'Number of results', '20')
+    .option('--no-browser', 'Print results to terminal instead')
+    .action(async (query, options) => {
+    const limit = parseInt(options.limit, 10) || 20;
+    const isBrowse = options.featured || options.popular || options.recent;
+    if (!query && !isBrowse) {
+        console.error('  ✗ Provide a search query or use --featured, --popular, or --recent');
+        process.exit(1);
+    }
+    console.log('\nkin3o — Searching LottieFiles...');
+    try {
+        let result;
+        let mode;
+        if (options.featured) {
+            mode = 'featured';
+            result = await featuredAnimations(limit);
+        }
+        else if (options.popular) {
+            mode = 'popular';
+            result = await popularAnimations(limit);
+        }
+        else if (options.recent) {
+            mode = 'recent';
+            result = await recentAnimations(limit);
+        }
+        else {
+            mode = 'search';
+            result = await searchAnimations(query, { first: limit });
+        }
+        console.log(`  ✓ Found ${result.totalCount} animations${query ? ` for "${query}"` : ''}`);
+        if (result.animations.length === 0) {
+            console.log('  No results found.\n');
+            return;
+        }
+        if (!options.browser) {
+            // Terminal table output
+            console.log('');
+            const header = '  Name                              Author          UUID             Likes  Downloads';
+            console.log(header);
+            console.log('  ' + '─'.repeat(header.length - 2));
+            for (const anim of result.animations) {
+                const name = (anim.name || '').slice(0, 32).padEnd(34);
+                const author = (anim.createdBy?.username || 'Unknown').slice(0, 14).padEnd(16);
+                const uuid = anim.uuid.slice(0, 14).padEnd(17);
+                const likes = String(anim.likesCount).padStart(5);
+                const dl = String(anim.downloads ?? 0).padStart(10);
+                console.log(`  ${name}${author}${uuid}${likes}${dl}`);
+            }
+            console.log('');
+        }
+        else {
+            const previewPath = await openSearchResults(result.animations, {
+                query: query || '',
+                totalCount: result.totalCount,
+                mode,
+            });
+            console.log(`  ✓ Results opened in browser: ${previewPath}`);
+        }
+        console.log('  Tip: Run "kin3o download <uuid>" to save an animation to output/\n');
+    }
+    catch (err) {
+        console.error(`  ✗ Search failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+program
+    .command('download <target>')
+    .description('Download an animation from LottieFiles (UUID, URL, or CDN link)')
+    .option('-o, --output <path>', 'Output file path')
+    .option('--no-preview', 'Skip preview')
+    .option('--lottie', 'Download .lottie format instead of .json', false)
+    .action(async (target, options) => {
+    console.log('\nkin3o — Downloading from LottieFiles...');
+    try {
+        const resolved = await resolveTarget(target, options.lottie);
+        if (options.lottie && resolved.lottieBuffer) {
+            const outputDir = ensureOutputDir();
+            const slug = resolved.meta ? slugify(resolved.meta.name) : 'animation';
+            const timestamp = Math.floor(Date.now() / 1000);
+            const outputPath = options.output
+                ? join(outputDir, options.output)
+                : join(outputDir, `${slug}-${timestamp}.lottie`);
+            writeFileSync(outputPath, resolved.lottieBuffer);
+            if (resolved.meta) {
+                console.log(`  ✓ Downloaded: ${resolved.meta.name} by ${resolved.meta.createdBy?.username ?? 'Unknown'}`);
+            }
+            console.log(`  ✓ Written to ${outputPath}`);
+            if (options.preview) {
+                const previewPath = await openDotLottiePreview(resolved.lottieBuffer);
+                console.log(`  ✓ Preview opened: ${previewPath}`);
+            }
+            console.log(`  Tip: Run "kin3o refine ${outputPath} 'your instruction'" to modify\n`);
+            return;
+        }
+        // JSON download
+        const lottieJson = resolved.json;
+        const validation = validateLottie(lottieJson);
+        if (!validation.valid) {
+            console.error('  ⚠ Downloaded Lottie has validation errors:');
+            validation.errors.forEach(e => console.error(`    - ${e}`));
+        }
+        let finalJson = lottieJson;
+        if (validation.warnings.length > 0) {
+            finalJson = autoFix(lottieJson);
+            const fixes = validation.warnings.length;
+            console.log(`  ✓ Valid Lottie JSON (${fixes} auto-fix${fixes > 1 ? 'es' : ''}: ${validation.warnings.join(', ')})`);
+        }
+        else if (validation.valid) {
+            console.log('  ✓ Valid Lottie JSON');
+        }
+        const outputDir = ensureOutputDir();
+        const slug = resolved.meta ? slugify(resolved.meta.name) : 'animation';
+        const timestamp = Math.floor(Date.now() / 1000);
+        const outputPath = options.output
+            ? join(outputDir, options.output)
+            : join(outputDir, `${slug}-${timestamp}.json`);
+        writeFileSync(outputPath, JSON.stringify(finalJson, null, 2), 'utf-8');
+        if (resolved.meta) {
+            console.log(`  ✓ Downloaded: ${resolved.meta.name} by ${resolved.meta.createdBy?.username ?? 'Unknown'}`);
+        }
+        console.log(`  ✓ Written to ${outputPath}`);
+        if (options.preview) {
+            const previewPath = await openPreview(finalJson);
+            console.log(`  ✓ Preview opened: ${previewPath}`);
+        }
+        console.log(`  Tip: Run "kin3o refine ${outputPath} 'your instruction'" to modify\n`);
+    }
+    catch (err) {
+        console.error(`  ✗ Download failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+// --- Auth + Publish commands ---
+program
+    .command('login')
+    .description('Log in to LottieFiles to enable publishing')
+    .action(async () => {
+    const existing = loadAuthToken();
+    if (existing) {
+        const expiry = loadAuthExpiry();
+        console.log(`  ✓ Already logged in (expires ${expiry ?? 'unknown'})`);
+        return;
+    }
+    const appKey = process.env['LOTTIEFILES_APP_KEY'];
+    if (!appKey) {
+        console.error('  ✗ LOTTIEFILES_APP_KEY environment variable is required.');
+        console.error('    Set it to your LottieFiles app key to enable login.');
+        process.exit(1);
+    }
+    console.log('\nkin3o — Logging in to LottieFiles...');
+    try {
+        const { loginUrl, token } = await createLoginToken(appKey);
+        const open = (await import('open')).default;
+        await open(loginUrl);
+        console.log('  Waiting for authentication... (complete login in browser)');
+        const { accessToken, expiresAt } = await pollForAccessToken(token);
+        saveAuthToken(accessToken, expiresAt);
+        console.log(`  ✓ Logged in! Token expires ${expiresAt}\n`);
+    }
+    catch (err) {
+        console.error(`  ✗ Login failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+program
+    .command('logout')
+    .description('Log out from LottieFiles')
+    .action(() => {
+    clearAuthToken();
+    console.log('  ✓ Logged out');
+});
+program
+    .command('publish <file>')
+    .description('Publish an animation to LottieFiles marketplace')
+    .requiredOption('--name <name>', 'Animation name')
+    .requiredOption('--tags <tags>', 'Comma-separated tags')
+    .option('--description <desc>', 'Optional description')
+    .action(async (file, options) => {
+    const token = loadAuthToken();
+    if (!token) {
+        console.error('  ✗ Not logged in. Run "kin3o login" first.');
+        process.exit(1);
+    }
+    const resolvedPath = resolve(file);
+    if (!existsSync(resolvedPath)) {
+        console.error(`  ✗ File not found: ${resolvedPath}`);
+        process.exit(1);
+    }
+    console.log('\nkin3o — Publishing to LottieFiles...');
+    try {
+        // Validate the file
+        const isLottie = file.endsWith('.lottie');
+        if (!isLottie) {
+            const raw = readFileSync(resolvedPath, 'utf-8');
+            const json = JSON.parse(raw);
+            const validation = validateLottie(json);
+            if (!validation.valid) {
+                console.error('  ✗ Invalid Lottie JSON:');
+                validation.errors.forEach(e => console.error(`    - ${e}`));
+                process.exit(1);
+            }
+            console.log('  ✓ Validation passed');
+        }
+        const fileBuffer = readFileSync(resolvedPath);
+        const type = isLottie ? 'DOT_LOTTIE' : 'LOTTIE';
+        const filename = resolvedPath.split('/').pop() ?? 'animation.json';
+        // Create upload request
+        const { requestId, presignedUrl } = await createUploadRequest(token, filename, type);
+        console.log('  ✓ Upload request created');
+        // Upload file
+        await uploadFile(presignedUrl, fileBuffer);
+        console.log('  ✓ File uploaded');
+        // Create animation entry
+        const tags = options.tags.split(',').map(t => t.trim()).filter(Boolean);
+        const result = await publishAnimation(token, {
+            name: options.name,
+            requestId,
+            tags,
+            description: options.description,
+        });
+        console.log(`  ✓ Published: ${options.name}`);
+        console.log(`  ✓ View at: ${result.url}\n`);
+    }
+    catch (err) {
+        console.error(`  ✗ Publish failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
 program.parse();

package/dist/marketplace-auth.d.ts

@@ -0,0 +1,4 @@
+export declare function loadAuthToken(): string | null;
+export declare function loadAuthExpiry(): string | null;
+export declare function saveAuthToken(token: string, expiresAt: string): void;
+export declare function clearAuthToken(): void;

package/dist/marketplace-auth.js

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const AUTH_DIR = join(homedir(), '.kin3o');
+const AUTH_FILE = join(AUTH_DIR, 'auth.json');
+export function loadAuthToken() {
+    if (!existsSync(AUTH_FILE))
+        return null;
+    try {
+        const raw = readFileSync(AUTH_FILE, 'utf-8');
+        const data = JSON.parse(raw);
+        if (!data.accessToken || !data.expiresAt)
+            return null;
+        const expires = new Date(data.expiresAt);
+        if (expires.getTime() <= Date.now())
+            return null;
+        return data.accessToken;
+    }
+    catch {
+        return null;
+    }
+}
+export function loadAuthExpiry() {
+    if (!existsSync(AUTH_FILE))
+        return null;
+    try {
+        const raw = readFileSync(AUTH_FILE, 'utf-8');
+        const data = JSON.parse(raw);
+        return data.expiresAt ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveAuthToken(token, expiresAt) {
+    mkdirSync(AUTH_DIR, { recursive: true });
+    const data = { accessToken: token, expiresAt };
+    writeFileSync(AUTH_FILE, JSON.stringify(data, null, 2), 'utf-8');
+}
+export function clearAuthToken() {
+    if (existsSync(AUTH_FILE)) {
+        unlinkSync(AUTH_FILE);
+    }
+}

package/dist/marketplace-preview.d.ts

@@ -0,0 +1,7 @@
+import type { LottieFilesAnimation } from './marketplace.js';
+export interface SearchMeta {
+    query: string;
+    totalCount: number;
+    mode: 'search' | 'featured' | 'popular' | 'recent';
+}
+export declare function openSearchResults(animations: LottieFilesAnimation[], meta: SearchMeta): Promise<string>;

package/dist/marketplace-preview.js

@@ -0,0 +1,18 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import open from 'open';
+import { ensureOutputDir } from './utils.js';
+const templateDir = join(fileURLToPath(new URL('.', import.meta.url)), '..', 'preview');
+export async function openSearchResults(animations, meta) {
+    const template = readFileSync(join(templateDir, 'template-search.html'), 'utf-8');
+    const html = template
+        .replace('__SEARCH_RESULTS__', JSON.stringify(animations))
+        .replace('__SEARCH_META__', JSON.stringify(meta));
+    const outputDir = ensureOutputDir();
+    const filename = `search-${Date.now()}.html`;
+    const fullPath = join(outputDir, filename);
+    writeFileSync(fullPath, html, 'utf-8');
+    await open(fullPath);
+    return fullPath;
+}