@afromero/kin3o 0.1.0

package/README.md

@@ -0,0 +1,204 @@
+<div align="center">
+
+# kin3o
+
+**Text to Motion. From your terminal.**
+
+[![npm](https://img.shields.io/npm/v/kin3o)](https://www.npmjs.com/package/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)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/affromero/kin3o/pulls)
+
+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.
+
+</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.
+
+## Competitors
+
+| 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 |
+
+> Prices as of March 2026.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g kin3o
+
+# Generate a static animation
+kin3o generate "loading spinner with 3 dots"
+
+# Generate an interactive state machine
+kin3o generate "toggle switch with on/off states" --interactive
+```
+
+Or use without installing:
+
+```bash
+npx kin3o generate "pulsing circle"
+```
+
+## CLI Usage
+
+```bash
+# Static animations (.json)
+kin3o generate "pulsing circle that breathes"
+kin3o generate "5-bar audio waveform" --provider claude-code --model sonnet
+kin3o generate "notification bell" --no-preview --output bell.json
+kin3o generate "loading dots" --tokens sotto
+
+# Interactive state machines (.lottie)
+kin3o generate "toggle switch with on/off states" --interactive
+kin3o generate "like button with hover and click" --interactive
+
+# Preview
+kin3o preview output/animation.json
+kin3o preview output/animation.lottie
+
+# Validate
+kin3o validate output/animation.json
+kin3o validate output/animation.lottie
+
+# List available AI providers
+kin3o providers
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-p, --provider <name>` | AI provider (`claude-code`, `codex`, `anthropic`) |
+| `-m, --model <name>` | Model (`sonnet`, `opus`, `haiku`, `codex`) |
+| `-o, --output <path>` | Output filename |
+| `--no-preview` | Skip browser preview |
+| `-i, --interactive` | Generate interactive state machine (`.lottie` output) |
+| `-t, --tokens <path>` | Design tokens JSON or `sotto` preset |
+
+## Using Generated Animations
+
+### Static animations (`.json`)
+
+```tsx
+// React (lottie-react)
+import Lottie from 'lottie-react';
+import animationData from './pulsing-circle.json';
+
+<Lottie animationData={animationData} loop autoplay />
+```
+
+```html
+<!-- Vanilla JS (lottie-web) -->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>
+<div id="anim"></div>
+<script>
+  lottie.loadAnimation({
+    container: document.getElementById('anim'),
+    path: './pulsing-circle.json',
+    loop: true,
+    autoplay: true,
+  });
+</script>
+```
+
+```swift
+// iOS (lottie-ios)
+let animationView = LottieAnimationView(name: "pulsing-circle")
+animationView.loopMode = .loop
+animationView.play()
+```
+
+### Interactive state machines (`.lottie`)
+
+```html
+<!-- dotlottie-web — hover, click, and tap state transitions -->
+<script type="module">
+  import { DotLottie } from 'https://esm.sh/@lottiefiles/dotlottie-web';
+  const dotLottie = new DotLottie({
+    canvas: document.querySelector('canvas'),
+    src: './toggle-switch.lottie',
+    autoplay: true,
+  });
+</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 |
+
+### Animation capabilities
+
+| 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) | ✗ | ✓ |
+
+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.
+
+## Architecture
+
+```
+Static:      prompt → generate() → extractJson() → validateLottie() → autoFix() → .json → preview
+Interactive: prompt → generate() → extractInteractiveJson() → validate animations + state machine → .lottie → preview
+```
+
+### Prompt System
+
+All prompts live in `src/prompts/` with a barrel export at `src/prompts/index.ts`:
+
+| Module | Purpose |
+|--------|---------|
+| `system.ts` | Static Lottie generation prompt + `LOTTIE_FORMAT_REFERENCE` |
+| `system-interactive.ts` | Interactive state machine prompt (imports shared ref) |
+| `examples.ts` | Few-shot: pulsing circle, waveform bars |
+| `examples-interactive.ts` | Few-shot: interactive button (idle/hover/pressed) |
+| `examples-mascot.ts` | kin3o mascot/logo (static + interactive) |
+| `tokens.ts` | Design token loader (hex → Lottie RGBA) |
+
+## Development
+
+```bash
+npm install
+npm run typecheck    # Type check
+npm run test         # Run tests (node --test)
+npm run ci           # typecheck + test
+npm run build        # Compile to dist/
+```
+
+## License
+
+MIT

package/dist/brand.d.ts

@@ -0,0 +1,39 @@
+/**
+ * kin3o brand tokens — single source of truth for colors, fonts, and styling.
+ * Used by landing page generator, preview template, and design token presets.
+ */
+export declare const brand: {
+    readonly name: "kin3o";
+    readonly tagline: "Text to Motion";
+    readonly description: "AI-powered Lottie animation generator";
+    readonly colors: {
+        readonly accent: "#A78BFA";
+        readonly accentBright: "#C4B5FD";
+        readonly accentDeep: "#7C3AED";
+        readonly warm: "#E2B96F";
+        readonly warmMuted: "rgba(226, 185, 111, 0.7)";
+        readonly bg: "#08080A";
+        readonly bgElevated: "#0E0E12";
+        readonly bgCard: "#131318";
+        readonly bgCardHover: "#1A1A21";
+        readonly border: "rgba(255, 255, 255, 0.05)";
+        readonly borderHover: "rgba(255, 255, 255, 0.1)";
+        readonly borderAccent: "rgba(167, 139, 250, 0.15)";
+        readonly text: "#EDEDF0";
+        readonly textSecondary: "#9494A0";
+        readonly textMuted: "#4E4E5A";
+        readonly success: "#34D399";
+        readonly error: "#EF4444";
+    };
+    readonly gradients: {
+        readonly text: "linear-gradient(135deg, #C4B5FD 0%, #E2B96F 100%)";
+        readonly glow: "radial-gradient(circle, rgba(124, 58, 237, 0.07) 0%, rgba(167, 139, 250, 0.03) 40%, transparent 70%)";
+    };
+    readonly fonts: {
+        readonly heading: "'DM Serif Display', serif";
+        readonly body: "'Inter', -apple-system, BlinkMacSystemFont, sans-serif";
+        readonly mono: "'JetBrains Mono', monospace";
+    };
+    /** Generate CSS custom properties block from brand tokens */
+    readonly toCssVars: () => string;
+};

package/dist/brand.js

@@ -0,0 +1,63 @@
+/**
+ * kin3o brand tokens — single source of truth for colors, fonts, and styling.
+ * Used by landing page generator, preview template, and design token presets.
+ */
+export const brand = {
+    name: 'kin3o',
+    tagline: 'Text to Motion',
+    description: 'AI-powered Lottie animation generator',
+    colors: {
+        accent: '#A78BFA', // Soft violet — primary brand color
+        accentBright: '#C4B5FD', // Lighter violet — hover states, highlights
+        accentDeep: '#7C3AED', // Deep violet — buttons, CTAs
+        warm: '#E2B96F', // Champagne gold — secondary accent
+        warmMuted: 'rgba(226, 185, 111, 0.7)',
+        bg: '#08080A', // Near-black background
+        bgElevated: '#0E0E12', // Slightly raised surfaces
+        bgCard: '#131318', // Card backgrounds
+        bgCardHover: '#1A1A21', // Card hover state
+        border: 'rgba(255, 255, 255, 0.05)',
+        borderHover: 'rgba(255, 255, 255, 0.1)',
+        borderAccent: 'rgba(167, 139, 250, 0.15)',
+        text: '#EDEDF0', // Primary text
+        textSecondary: '#9494A0', // Secondary/body text
+        textMuted: '#4E4E5A', // Muted/disabled text
+        success: '#34D399', // Validation passed
+        error: '#EF4444', // Validation failed
+    },
+    gradients: {
+        text: 'linear-gradient(135deg, #C4B5FD 0%, #E2B96F 100%)',
+        glow: 'radial-gradient(circle, rgba(124, 58, 237, 0.07) 0%, rgba(167, 139, 250, 0.03) 40%, transparent 70%)',
+    },
+    fonts: {
+        heading: "'DM Serif Display', serif",
+        body: "'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
+        mono: "'JetBrains Mono', monospace",
+    },
+    /** Generate CSS custom properties block from brand tokens */
+    toCssVars() {
+        return `
+  :root {
+    --accent: ${this.colors.accent};
+    --accent-bright: ${this.colors.accentBright};
+    --accent-deep: ${this.colors.accentDeep};
+    --accent-glow: rgba(167, 139, 250, 0.12);
+    --accent-glow-strong: rgba(167, 139, 250, 0.25);
+    --warm: ${this.colors.warm};
+    --warm-muted: ${this.colors.warmMuted};
+    --bg: ${this.colors.bg};
+    --bg-elevated: ${this.colors.bgElevated};
+    --bg-card: ${this.colors.bgCard};
+    --bg-card-hover: ${this.colors.bgCardHover};
+    --border: ${this.colors.border};
+    --border-hover: ${this.colors.borderHover};
+    --border-accent: ${this.colors.borderAccent};
+    --text: ${this.colors.text};
+    --text-secondary: ${this.colors.textSecondary};
+    --text-muted: ${this.colors.textMuted};
+    --code-bg: #111116;
+    --success: ${this.colors.success};
+    --gradient-text: ${this.gradients.text};
+  }`.trim();
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { PROVIDERS, detectAvailableProviders, getDefaultProvider } from './providers/registry.js';
+import { buildSystemPrompt, buildInteractiveSystemPrompt, 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';
+const program = new Command();
+program
+    .name('kin3o')
+    .description('AI-powered Lottie animation generator')
+    .version('0.1.0');
+program
+    .command('generate <prompt>')
+    .description('Generate a Lottie animation from a natural language prompt')
+    .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)')
+    .option('-i, --interactive', 'Generate interactive state machine (.lottie output)', false)
+    .action(async (prompt, options) => {
+    const mode = options.interactive ? 'interactive' : 'static';
+    console.log(`\nkin3o — Generating ${mode} animation...`);
+    // 1. Detect provider
+    let providerKey = options.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 = options.model ?? provider.defaultModel;
+    console.log(`  Provider: ${provider.displayName} (${model})`);
+    console.log(`  Prompt: "${prompt}"\n`);
+    // 2. Load design tokens
+    const tokens = options.tokens ? loadDesignTokens(options.tokens) : undefined;
+    // 3. Build system prompt
+    const systemPrompt = options.interactive
+        ? buildInteractiveSystemPrompt(tokens)
+        : buildSystemPrompt(tokens);
+    // 4. Generate
+    try {
+        const result = await provider.generate(model, systemPrompt, prompt);
+        console.log(`  ✓ Generated in ${(result.durationMs / 1000).toFixed(1)}s`);
+        if (options.interactive) {
+            await handleInteractiveOutput(result.content, prompt, options);
+        }
+        else {
+            await handleStaticOutput(result.content, prompt, options);
+        }
+        console.log('');
+    }
+    catch (err) {
+        console.error(`  ✗ Generation failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+async function handleStaticOutput(content, prompt, options) {
+    const jsonStr = extractJson(content);
+    const lottieJson = JSON.parse(jsonStr);
+    const validation = validateLottie(lottieJson);
+    if (!validation.valid) {
+        console.error('  ✗ Invalid Lottie JSON:');
+        validation.errors.forEach(e => console.error(`    - ${e}`));
+        process.exit(1);
+    }
+    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 {
+        console.log('  ✓ Valid Lottie JSON');
+    }
+    const outputDir = ensureOutputDir();
+    const slug = slugify(prompt);
+    const timestamp = Math.floor(Date.now() / 1000);
+    const filename = options.output ?? `${slug}-${timestamp}.json`;
+    const outputPath = join(outputDir, filename);
+    writeFileSync(outputPath, JSON.stringify(finalJson, null, 2), 'utf-8');
+    console.log(`  ✓ Written to ${outputPath}`);
+    if (options.preview) {
+        const previewPath = await openPreview(finalJson);
+        console.log(`  ✓ Preview opened: ${previewPath}`);
+    }
+}
+async function handleInteractiveOutput(content, prompt, options) {
+    const envelope = extractInteractiveJson(content);
+    const animationIds = Object.keys(envelope.animations);
+    console.log(`  ✓ Extracted ${animationIds.length} animations: ${animationIds.join(', ')}`);
+    // Validate each animation
+    let totalFixes = 0;
+    const fixedAnimations = {};
+    for (const [id, anim] of Object.entries(envelope.animations)) {
+        const validation = validateLottie(anim);
+        if (!validation.valid) {
+            console.error(`  ✗ Animation "${id}" invalid:`);
+            validation.errors.forEach(e => console.error(`    - ${e}`));
+            process.exit(1);
+        }
+        if (validation.warnings.length > 0) {
+            fixedAnimations[id] = autoFix(anim);
+            totalFixes += validation.warnings.length;
+        }
+        else {
+            fixedAnimations[id] = anim;
+        }
+    }
+    if (totalFixes > 0) {
+        console.log(`  ✓ All animations valid (${totalFixes} auto-fix${totalFixes > 1 ? 'es' : ''})`);
+    }
+    else {
+        console.log('  ✓ All animations valid');
+    }
+    // Validate state machine
+    const smValidation = validateStateMachine(envelope.stateMachine, animationIds);
+    if (!smValidation.valid) {
+        console.error('  ✗ Invalid state machine:');
+        smValidation.errors.forEach(e => console.error(`    - ${e}`));
+        process.exit(1);
+    }
+    if (smValidation.warnings.length > 0) {
+        smValidation.warnings.forEach(w => console.log(`  ⚠ ${w}`));
+    }
+    console.log('  ✓ State machine valid');
+    // Package .lottie
+    const outputDir = ensureOutputDir();
+    const slug = slugify(prompt);
+    const timestamp = Math.floor(Date.now() / 1000);
+    const filename = options.output ?? `${slug}-${timestamp}.lottie`;
+    const outputPath = join(outputDir, filename);
+    await writeDotLottie(outputPath, {
+        animations: Object.entries(fixedAnimations).map(([id, data]) => ({ id, data })),
+        stateMachine: { id: 'state-machine', data: envelope.stateMachine },
+    });
+    console.log(`  ✓ Written to ${outputPath}`);
+    // Preview
+    if (options.preview) {
+        const buffer = readFileSync(outputPath);
+        const previewPath = await openDotLottiePreview(buffer);
+        console.log(`  ✓ Preview opened: ${previewPath}`);
+    }
+}
+program
+    .command('preview <file>')
+    .description('Preview a Lottie JSON or .lottie file in the browser')
+    .action(async (file) => {
+    try {
+        if (file.endsWith('.lottie')) {
+            const buffer = readFileSync(file);
+            const previewPath = await openDotLottiePreview(buffer);
+            console.log(`Preview opened: ${previewPath}`);
+        }
+        else {
+            const raw = readFileSync(file, 'utf-8');
+            const json = JSON.parse(raw);
+            const previewPath = await openPreview(json);
+            console.log(`Preview opened: ${previewPath}`);
+        }
+    }
+    catch (err) {
+        console.error(`Failed to preview: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+program
+    .command('providers')
+    .description('List available AI providers')
+    .action(async () => {
+    const available = await detectAvailableProviders();
+    console.log('\nAvailable AI Providers:\n');
+    for (const [key, config] of Object.entries(PROVIDERS)) {
+        const status = available.includes(key) ? '✓' : '✗';
+        console.log(`  ${status} ${config.displayName} (${key})`);
+        console.log(`    Models: ${config.models.join(', ')}`);
+    }
+    console.log('');
+});
+program
+    .command('validate <file>')
+    .description('Validate a Lottie JSON or .lottie file')
+    .action(async (file) => {
+    try {
+        if (file.endsWith('.lottie')) {
+            const { animations, stateMachine } = await readDotLottie(file);
+            const animationIds = Object.keys(animations);
+            let allValid = true;
+            for (const [id, anim] of Object.entries(animations)) {
+                const result = validateLottie(anim);
+                if (result.valid) {
+                    console.log(`✓ Animation "${id}": valid`);
+                }
+                else {
+                    console.log(`✗ Animation "${id}": invalid`);
+                    result.errors.forEach(e => console.log(`  Error: ${e}`));
+                    allValid = false;
+                }
+                result.warnings.forEach(w => console.log(`  Warning: ${w}`));
+            }
+            if (stateMachine) {
+                const smResult = validateStateMachine(stateMachine, animationIds);
+                if (smResult.valid) {
+                    console.log('✓ State machine: valid');
+                }
+                else {
+                    console.log('✗ State machine: invalid');
+                    smResult.errors.forEach(e => console.log(`  Error: ${e}`));
+                    allValid = false;
+                }
+                smResult.warnings.forEach(w => console.log(`  Warning: ${w}`));
+            }
+            process.exit(allValid ? 0 : 1);
+        }
+        else {
+            const raw = readFileSync(file, 'utf-8');
+            const json = JSON.parse(raw);
+            const result = validateLottie(json);
+            if (result.valid) {
+                console.log(`✓ Valid Lottie JSON: ${file}`);
+            }
+            else {
+                console.log(`✗ Invalid Lottie JSON: ${file}`);
+                result.errors.forEach(e => console.log(`  Error: ${e}`));
+            }
+            if (result.warnings.length > 0) {
+                result.warnings.forEach(w => console.log(`  Warning: ${w}`));
+            }
+            process.exit(result.valid ? 0 : 1);
+        }
+    }
+    catch (err) {
+        console.error(`Failed to validate: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/packager.d.ts

@@ -0,0 +1,16 @@
+export interface PackageOptions {
+    animations: Array<{
+        id: string;
+        data: object;
+    }>;
+    stateMachine?: {
+        id: string;
+        data: object;
+    };
+}
+export declare function packageDotLottie(options: PackageOptions): Promise<Buffer>;
+export declare function writeDotLottie(outputPath: string, options: PackageOptions): Promise<void>;
+export declare function readDotLottie(filePath: string): Promise<{
+    animations: Record<string, object>;
+    stateMachine?: object;
+}>;

package/dist/packager.js

@@ -0,0 +1,40 @@
+import { writeFileSync, readFileSync } from 'node:fs';
+import { DotLottie, getAnimations, getStateMachines } from '@dotlottie/dotlottie-js';
+export async function packageDotLottie(options) {
+    const dotlottie = new DotLottie();
+    for (const anim of options.animations) {
+        dotlottie.addAnimation({
+            id: anim.id,
+            data: anim.data,
+        });
+    }
+    if (options.stateMachine) {
+        dotlottie.addStateMachine({
+            id: options.stateMachine.id,
+            data: options.stateMachine.data,
+        });
+    }
+    const arrayBuffer = await dotlottie.toArrayBuffer();
+    return Buffer.from(arrayBuffer);
+}
+export async function writeDotLottie(outputPath, options) {
+    const buffer = await packageDotLottie(options);
+    writeFileSync(outputPath, buffer);
+}
+export async function readDotLottie(filePath) {
+    const fileBuffer = readFileSync(filePath);
+    const uint8 = new Uint8Array(fileBuffer.buffer, fileBuffer.byteOffset, fileBuffer.byteLength);
+    const animations = {};
+    const animRecord = await getAnimations(uint8);
+    for (const [id, data] of Object.entries(animRecord)) {
+        animations[id] = data;
+    }
+    let stateMachine;
+    const smRecord = await getStateMachines(uint8);
+    const smEntries = Object.entries(smRecord);
+    if (smEntries.length > 0) {
+        const [, smStr] = smEntries[0];
+        stateMachine = JSON.parse(smStr);
+    }
+    return { animations, stateMachine };
+}

package/dist/preview.d.ts

@@ -0,0 +1,2 @@
+export declare function openPreview(lottieJson: object, outputPath?: string): Promise<string>;
+export declare function openDotLottiePreview(dotlottieBuffer: Buffer): Promise<string>;

package/dist/preview.js

@@ -0,0 +1,30 @@
+import { readFileSync, writeFileSync, existsSync } 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 openPreview(lottieJson, outputPath) {
+    const template = readFileSync(join(templateDir, 'template.html'), 'utf-8');
+    const html = template.replace('__ANIMATION_DATA__', JSON.stringify(lottieJson));
+    const outputDir = ensureOutputDir();
+    const filename = outputPath ?? `preview-${Date.now()}.html`;
+    const fullPath = join(outputDir, filename);
+    writeFileSync(fullPath, html, 'utf-8');
+    await open(fullPath);
+    return fullPath;
+}
+export async function openDotLottiePreview(dotlottieBuffer) {
+    const templatePath = join(templateDir, 'template-interactive.html');
+    if (!existsSync(templatePath)) {
+        throw new Error(`Interactive preview template not found at ${templatePath}`);
+    }
+    const template = readFileSync(templatePath, 'utf-8');
+    const base64 = dotlottieBuffer.toString('base64');
+    const html = template.replace('__DOTLOTTIE_DATA_BASE64__', base64);
+    const outputDir = ensureOutputDir();
+    const fullPath = join(outputDir, `preview-interactive-${Date.now()}.html`);
+    writeFileSync(fullPath, html, 'utf-8');
+    await open(fullPath);
+    return fullPath;
+}