@afromero/kin3o 0.1.0 → 0.2.1

package/dist/marketplace.d.ts

@@ -0,0 +1,68 @@
+export interface LottieFilesAnimation {
+    id: number;
+    name: string;
+    slug: string;
+    uuid: string;
+    description: string | null;
+    url: string | null;
+    jsonUrl: string | null;
+    lottieUrl: string | null;
+    gifUrl: string | null;
+    imageUrl: string | null;
+    likesCount: number;
+    downloads: number | null;
+    createdBy: {
+        username: string;
+    } | null;
+    createdAt: string;
+    lottieFileSize: number | null;
+    frameRate: number | null;
+}
+export interface SearchResult {
+    totalCount: number;
+    animations: LottieFilesAnimation[];
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor: string | null;
+    };
+}
+export declare function searchAnimations(query: string, opts?: {
+    first?: number;
+    after?: string;
+}): Promise<SearchResult>;
+export declare function featuredAnimations(first?: number): Promise<SearchResult>;
+export declare function popularAnimations(first?: number): Promise<SearchResult>;
+export declare function recentAnimations(first?: number): Promise<SearchResult>;
+export declare function fetchAnimationJson(jsonUrl: string): Promise<object>;
+export declare function fetchAnimationByUuid(uuid: string): Promise<{
+    json: object;
+    meta: LottieFilesAnimation;
+}>;
+export interface ResolvedTarget {
+    json: object;
+    meta: LottieFilesAnimation | null;
+    lottieBuffer: Buffer | null;
+}
+export declare function resolveTarget(target: string, lottie?: boolean): Promise<ResolvedTarget>;
+export declare function createLoginToken(appKey: string): Promise<{
+    loginUrl: string;
+    token: string;
+}>;
+export declare function pollForAccessToken(token: string, timeoutMs?: number): Promise<{
+    accessToken: string;
+    expiresAt: string;
+}>;
+export declare function createUploadRequest(authToken: string, filename: string, type: 'LOTTIE' | 'DOT_LOTTIE'): Promise<{
+    requestId: string;
+    presignedUrl: string;
+}>;
+export declare function uploadFile(presignedUrl: string, buffer: Buffer): Promise<void>;
+export declare function publishAnimation(authToken: string, input: {
+    name: string;
+    requestId: string;
+    tags: string[];
+    description?: string;
+}): Promise<{
+    id: number;
+    url: string;
+}>;

package/dist/marketplace.js

@@ -0,0 +1,267 @@
+const GRAPHQL_ENDPOINT = 'https://graphql.lottiefiles.com/';
+const ANIM_FIELDS_FRAGMENT = `
+  fragment AnimFields on PublicAnimation {
+    id name slug uuid description url
+    jsonUrl lottieUrl gifUrl imageUrl
+    likesCount downloads
+    createdBy { username }
+    createdAt lottieFileSize frameRate
+  }
+`;
+async function gqlQuery(query, variables, token) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (token)
+        headers['Authorization'] = `Bearer ${token}`;
+    let response;
+    try {
+        response = await fetch(GRAPHQL_ENDPOINT, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ query, variables }),
+        });
+    }
+    catch {
+        throw new Error('Network error: unable to reach LottieFiles API');
+    }
+    if (!response.ok) {
+        throw new Error(`LottieFiles API returned HTTP ${response.status}`);
+    }
+    const body = (await response.json());
+    if (body.errors && body.errors.length > 0) {
+        const msg = body.errors.map(e => e.message).join('; ');
+        throw new Error(`LottieFiles API error: ${msg}`);
+    }
+    if (!body.data) {
+        throw new Error('LottieFiles API returned no data');
+    }
+    return body.data;
+}
+function parseEdges(edges) {
+    if (!edges)
+        return [];
+    return edges.map(e => e.node);
+}
+export async function searchAnimations(query, opts) {
+    const first = opts?.first ?? 20;
+    const variables = { query, first };
+    if (opts?.after)
+        variables['after'] = opts.after;
+    const data = await gqlQuery(`query($query: String!, $first: Int, $after: String) {
+      searchPublicAnimations(query: $query, first: $first, after: $after) {
+        totalCount
+        edges { node { ...AnimFields } }
+        pageInfo { hasNextPage endCursor }
+      }
+    }
+    ${ANIM_FIELDS_FRAGMENT}`, variables);
+    const result = data.searchPublicAnimations;
+    return {
+        totalCount: result.totalCount,
+        animations: parseEdges(result.edges),
+        pageInfo: result.pageInfo,
+    };
+}
+export async function featuredAnimations(first = 20) {
+    const data = await gqlQuery(`query($first: Int) {
+      featuredPublicAnimations(first: $first) {
+        totalCount
+        edges { node { ...AnimFields } }
+        pageInfo { hasNextPage endCursor }
+      }
+    }
+    ${ANIM_FIELDS_FRAGMENT}`, { first });
+    const result = data.featuredPublicAnimations;
+    return {
+        totalCount: result.totalCount,
+        animations: parseEdges(result.edges),
+        pageInfo: result.pageInfo,
+    };
+}
+export async function popularAnimations(first = 20) {
+    const data = await gqlQuery(`query($first: Int) {
+      popularPublicAnimations(first: $first) {
+        totalCount
+        edges { node { ...AnimFields } }
+        pageInfo { hasNextPage endCursor }
+      }
+    }
+    ${ANIM_FIELDS_FRAGMENT}`, { first });
+    const result = data.popularPublicAnimations;
+    return {
+        totalCount: result.totalCount,
+        animations: parseEdges(result.edges),
+        pageInfo: result.pageInfo,
+    };
+}
+export async function recentAnimations(first = 20) {
+    const data = await gqlQuery(`query($first: Int) {
+      recentPublicAnimations(first: $first) {
+        totalCount
+        edges { node { ...AnimFields } }
+        pageInfo { hasNextPage endCursor }
+      }
+    }
+    ${ANIM_FIELDS_FRAGMENT}`, { first });
+    const result = data.recentPublicAnimations;
+    return {
+        totalCount: result.totalCount,
+        animations: parseEdges(result.edges),
+        pageInfo: result.pageInfo,
+    };
+}
+export async function fetchAnimationJson(jsonUrl) {
+    let response;
+    try {
+        response = await fetch(jsonUrl);
+    }
+    catch {
+        throw new Error(`Network error: unable to fetch animation from ${jsonUrl}`);
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch animation: HTTP ${response.status}`);
+    }
+    return (await response.json());
+}
+export async function fetchAnimationByUuid(uuid) {
+    const data = await gqlQuery(`query($hash: String!) {
+      publicAnimationByHash(hash: $hash) { ...AnimFields }
+    }
+    ${ANIM_FIELDS_FRAGMENT}`, { hash: uuid });
+    const anim = data.publicAnimationByHash;
+    if (!anim) {
+        throw new Error(`Animation not found: ${uuid}`);
+    }
+    if (!anim.jsonUrl) {
+        throw new Error(`Animation "${anim.name}" has no JSON URL available`);
+    }
+    const json = await fetchAnimationJson(anim.jsonUrl);
+    return { json, meta: anim };
+}
+export async function resolveTarget(target, lottie = false) {
+    if (target.startsWith('http')) {
+        const url = new URL(target);
+        // LottieFiles page URL → extract hash from last segment after last hyphen
+        if (url.hostname === 'lottiefiles.com' || url.hostname.endsWith('.lottiefiles.com')) {
+            if (url.hostname.startsWith('assets') || url.hostname === 'lottie.host') {
+                // Direct CDN URL
+                if (lottie) {
+                    const buffer = await fetchLottieBuffer(target);
+                    return { json: {}, meta: null, lottieBuffer: buffer };
+                }
+                const json = await fetchAnimationJson(target);
+                return { json, meta: null, lottieBuffer: null };
+            }
+            // Page URL — extract hash from path
+            const segments = url.pathname.split('/').filter(Boolean);
+            const lastSegment = segments[segments.length - 1];
+            if (!lastSegment)
+                throw new Error('Could not extract animation hash from URL');
+            const parts = lastSegment.split('-');
+            const hash = parts[parts.length - 1];
+            if (!hash)
+                throw new Error('Could not extract animation hash from URL');
+            if (lottie) {
+                const { meta } = await fetchAnimationByUuid(hash);
+                if (!meta.lottieUrl)
+                    throw new Error(`Animation "${meta.name}" has no .lottie URL available`);
+                const buffer = await fetchLottieBuffer(meta.lottieUrl);
+                return { json: {}, meta, lottieBuffer: buffer };
+            }
+            const { json, meta } = await fetchAnimationByUuid(hash);
+            return { json, meta, lottieBuffer: null };
+        }
+        // Direct CDN URL for other hosts (lottie.host, etc.)
+        if (url.hostname === 'lottie.host') {
+            if (lottie) {
+                const buffer = await fetchLottieBuffer(target);
+                return { json: {}, meta: null, lottieBuffer: buffer };
+            }
+            const json = await fetchAnimationJson(target);
+            return { json, meta: null, lottieBuffer: null };
+        }
+        // Generic URL — try fetching directly
+        if (lottie) {
+            const buffer = await fetchLottieBuffer(target);
+            return { json: {}, meta: null, lottieBuffer: buffer };
+        }
+        const json = await fetchAnimationJson(target);
+        return { json, meta: null, lottieBuffer: null };
+    }
+    // UUID/hash pattern
+    if (/^[a-zA-Z0-9]{8,}$/.test(target)) {
+        if (lottie) {
+            const { meta } = await fetchAnimationByUuid(target);
+            if (!meta.lottieUrl)
+                throw new Error(`Animation "${meta.name}" has no .lottie URL available`);
+            const buffer = await fetchLottieBuffer(meta.lottieUrl);
+            return { json: {}, meta, lottieBuffer: buffer };
+        }
+        const { json, meta } = await fetchAnimationByUuid(target);
+        return { json, meta, lottieBuffer: null };
+    }
+    throw new Error('Unrecognized target. Provide a UUID, LottieFiles URL, or CDN URL.');
+}
+async function fetchLottieBuffer(url) {
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch {
+        throw new Error(`Network error: unable to fetch .lottie from ${url}`);
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch .lottie: HTTP ${response.status}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}
+export async function createLoginToken(appKey) {
+    const data = await gqlQuery(`mutation($appKey: String!) {
+      createLoginToken(input: { appKey: $appKey }) { token loginUrl }
+    }`, { appKey });
+    return data.createLoginToken;
+}
+export async function pollForAccessToken(token, timeoutMs = 120_000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        await new Promise(r => setTimeout(r, 3000));
+        try {
+            const result = await gqlQuery('mutation($token: String!) { tokenLogin(token: $token) { accessToken expiresAt } }', { token });
+            if (result.tokenLogin.accessToken)
+                return result.tokenLogin;
+        }
+        catch {
+            // User hasn't completed login yet — keep polling
+        }
+    }
+    throw new Error('Login timed out. Please try again.');
+}
+export async function createUploadRequest(authToken, filename, type) {
+    const data = await gqlQuery(`mutation($input: PublicAnimationUploadRequestCreateInput!) {
+      publicAnimationUploadRequestCreate(input: $input) { requestId presignedUrl }
+    }`, { input: { filename, type } }, authToken);
+    return data.publicAnimationUploadRequestCreate;
+}
+export async function uploadFile(presignedUrl, buffer) {
+    let response;
+    try {
+        const body = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+        response = await fetch(presignedUrl, {
+            method: 'PUT',
+            body,
+            headers: { 'Content-Type': 'application/octet-stream' },
+        });
+    }
+    catch {
+        throw new Error('Network error: unable to upload file');
+    }
+    if (!response.ok) {
+        throw new Error(`Upload failed: HTTP ${response.status}`);
+    }
+}
+export async function publishAnimation(authToken, input) {
+    const data = await gqlQuery(`mutation($input: PublicAnimationCreateInput!) {
+      publicAnimationCreate(input: $input) { id url }
+    }`, { input }, authToken);
+    return data.publicAnimationCreate;
+}

package/dist/prompts/index.d.ts

@@ -8,9 +8,9 @@
  * Each mode has its own few-shot examples tuned for that output format.
  */
 export { LOTTIE_FORMAT_REFERENCE } from './system.js';
-export { buildSystemPrompt } from './system.js';
+export { buildSystemPrompt, buildRefinementUserPrompt } from './system.js';
 export { PULSING_CIRCLE, WAVEFORM_BARS } from './examples.js';
-export { buildInteractiveSystemPrompt } from './system-interactive.js';
+export { buildInteractiveSystemPrompt, buildInteractiveRefinementUserPrompt } from './system-interactive.js';
 export { INTERACTIVE_BUTTON } from './examples-interactive.js';
 export { MASCOT_STATIC, MASCOT_INTERACTIVE } from './examples-mascot.js';
 export { loadDesignTokens, SOTTO_TOKENS } from './tokens.js';

package/dist/prompts/index.js

@@ -10,10 +10,10 @@
 // ── Shared ──
 export { LOTTIE_FORMAT_REFERENCE } from './system.js';
 // ── Static mode ──
-export { buildSystemPrompt } from './system.js';
+export { buildSystemPrompt, buildRefinementUserPrompt } from './system.js';
 export { PULSING_CIRCLE, WAVEFORM_BARS } from './examples.js';
 // ── Interactive mode ──
-export { buildInteractiveSystemPrompt } from './system-interactive.js';
+export { buildInteractiveSystemPrompt, buildInteractiveRefinementUserPrompt } from './system-interactive.js';
 export { INTERACTIVE_BUTTON } from './examples-interactive.js';
 // ── Mascot ──
 export { MASCOT_STATIC, MASCOT_INTERACTIVE } from './examples-mascot.js';

package/dist/prompts/system-interactive.d.ts

@@ -1,2 +1,4 @@
 import type { DesignTokens } from './tokens.js';
+/** Build the user prompt for a refinement request (interactive mode) */
+export declare function buildInteractiveRefinementUserPrompt(currentEnvelope: string, instruction: string): string;
 export declare function buildInteractiveSystemPrompt(tokens?: DesignTokens): string;

package/dist/prompts/system-interactive.js

@@ -1,5 +1,15 @@
 import { LOTTIE_FORMAT_REFERENCE } from './system.js';
 import { INTERACTIVE_BUTTON } from './examples-interactive.js';
+/** Build the user prompt for a refinement request (interactive mode) */
+export function buildInteractiveRefinementUserPrompt(currentEnvelope, instruction) {
+    return `Here is the current interactive animation envelope (animations + state machine):
+
+${currentEnvelope}
+
+Refine this interactive animation according to the following instruction: ${instruction}
+
+Output ONLY the complete updated envelope JSON with all animations and the state machine. Preserve the overall structure and only modify what the instruction requires. Do not add explanation or commentary.`;
+}
 export function buildInteractiveSystemPrompt(tokens) {
     const sections = [];
     // 1. Role + output rules

package/dist/prompts/system.d.ts

@@ -1,3 +1,5 @@
 import type { DesignTokens } from './tokens.js';
 export declare const LOTTIE_FORMAT_REFERENCE = "\nLOTTIE FORMAT REFERENCE:\n\nTop-level required fields:\n- \"v\": string (use \"5.5.2\")\n- \"fr\": number (use 60 for 60fps)\n- \"ip\": 0 (in-point, always 0)\n- \"op\": number (out-point, end frame \u2014 e.g. 120 for 2s at 60fps)\n- \"w\": number (width in pixels)\n- \"h\": number (height in pixels)\n- \"ddd\": 0 (no 3D)\n- \"assets\": [] (empty array)\n- \"layers\": array of layer objects\n\nLayer (shape layer, ty=4):\n- \"ty\": 4 (shape layer)\n- \"ind\": number (unique index)\n- \"nm\": string (layer name)\n- \"ip\": 0, \"op\": same as top-level op\n- \"st\": 0 (start time)\n- \"ddd\": 0\n- \"ks\": transform object\n- \"shapes\": array of shape objects\n- \"bm\": 0 (blend mode, normal)\n\nTransform \"ks\" object:\n- \"a\": anchor point (VECTOR property)\n- \"p\": position (VECTOR property)\n- \"s\": scale (VECTOR property, [100,100] = 100%)\n- \"r\": rotation (SCALAR property, degrees)\n- \"o\": opacity (SCALAR property, 0-100)\n\nPROPERTY TYPES \u2014 this distinction is critical:\n- VECTOR property (position, scale, anchor, size): {\"a\":0,\"k\":[x,y]} or animated {\"a\":1,\"k\":[keyframes]}\n- SCALAR property (rotation, opacity, roundness, stroke width): {\"a\":0,\"k\":0} or animated {\"a\":1,\"k\":[keyframes]}\n- COLOR property: {\"a\":0,\"k\":[r,g,b,1]} with 0-1 floats (NOT 0-255)\n\nKeyframe format:\n{\"t\":frame,\"s\":[values],\"o\":{\"x\":[n],\"y\":[n]},\"i\":{\"x\":[n],\"y\":[n]}}\n- \"t\": frame number\n- \"s\": start values (array for vector, array with single value for scalar)\n- \"o\": out-tangent (ease out), \"i\": in-tangent (ease in)\n- Last keyframe needs only \"t\" and \"s\" (no tangents)\n\nEasing (ease-in-out): \"o\":{\"x\":[0.42],\"y\":[0]}, \"i\":{\"x\":[0.58],\"y\":[1]}\n\nShape types:\n- \"el\": ellipse \u2014 \"p\" (center, vector), \"s\" (size, vector)\n- \"rc\": rectangle \u2014 \"p\" (center, vector), \"s\" (size, vector), \"r\" (roundness, scalar)\n- \"sh\": path \u2014 \"ks\" with bezier {\"c\":bool, \"v\":[[x,y],...], \"i\":[[dx,dy],...], \"o\":[[dx,dy],...]}\n- \"fl\": fill \u2014 \"c\" (color), \"o\" (opacity, scalar), \"r\" (fill rule, 1=nonzero)\n- \"st\": stroke \u2014 \"c\" (color), \"o\" (opacity), \"w\" (width, scalar), \"lc\" (line cap, 2=round), \"lj\" (line join, 2=round)\n- \"gr\": group \u2014 \"it\" array of shapes + MUST end with \"tr\" (group transform)\n- \"tr\": group transform \u2014 same fields as layer transform \"ks\"\n- \"tm\": trim path \u2014 \"s\" (start%, scalar), \"e\" (end%, scalar), \"o\" (offset, scalar)\n\nCRITICAL: Groups MUST have \"tr\" (transform) as the LAST item in their \"it\" array.";
+/** Build the user prompt for a refinement request (static mode) */
+export declare function buildRefinementUserPrompt(currentJson: string, instruction: string): string;
 export declare function buildSystemPrompt(tokens?: DesignTokens): string;

package/dist/prompts/system.js

@@ -56,6 +56,16 @@ Shape types:
 - "tm": trim path — "s" (start%, scalar), "e" (end%, scalar), "o" (offset, scalar)
 
 CRITICAL: Groups MUST have "tr" (transform) as the LAST item in their "it" array.`;
+/** Build the user prompt for a refinement request (static mode) */
+export function buildRefinementUserPrompt(currentJson, instruction) {
+    return `Here is the current Lottie animation JSON:
+
+${currentJson}
+
+Refine this animation according to the following instruction: ${instruction}
+
+Output ONLY the complete updated Lottie JSON. Preserve the overall structure and only modify what the instruction requires. Do not add explanation or commentary.`;
+}
 export function buildSystemPrompt(tokens) {
     const sections = [];
     // 1. Role + output rules

package/dist/utils.d.ts

@@ -18,3 +18,5 @@ export declare function hexToLottieColor(hex: string): [number, number, number,
 export declare function slugify(text: string, maxLength?: number): string;
 /** Ensure the output directory exists */
 export declare function ensureOutputDir(dir?: string): string;
+/** Compute the next versioned output path for a refinement */
+export declare function nextVersionedPath(inputPath: string, outputDir: string): string;

package/dist/utils.js

@@ -1,5 +1,5 @@
-import { mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, readdirSync } from 'node:fs';
+import { join, parse as parsePath } from 'node:path';
 /** Strip benign CLI warnings (e.g. PATH update failures) from stderr */
 export function filterCliStderr(stderr) {
     return stderr
@@ -87,3 +87,28 @@ export function ensureOutputDir(dir = 'output') {
     mkdirSync(outputPath, { recursive: true });
     return outputPath;
 }
+/** Compute the next versioned output path for a refinement */
+export function nextVersionedPath(inputPath, outputDir) {
+    const { name, ext } = parsePath(inputPath);
+    // Strip existing -vN suffix to get base name
+    const baseName = name.replace(/-v\d+$/, '');
+    // Scan output dir for existing versioned files
+    const versionPattern = new RegExp(`^${escapeRegex(baseName)}-v(\\d+)\\${ext}$`);
+    let maxVersion = 1;
+    try {
+        for (const file of readdirSync(outputDir)) {
+            const match = file.match(versionPattern);
+            if (match) {
+                maxVersion = Math.max(maxVersion, parseInt(match[1], 10));
+            }
+        }
+    }
+    catch {
+        // Output dir may not exist yet — that's fine, start at v2
+    }
+    const nextVersion = maxVersion + 1;
+    return join(outputDir, `${baseName}-v${nextVersion}${ext}`);
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/view.d.ts

@@ -0,0 +1,9 @@
+export interface ViewOptions {
+    port?: number;
+    openBrowser?: boolean;
+}
+export interface ViewServer {
+    url: string;
+    close(): void;
+}
+export declare function startViewServer(filePath: string, options?: ViewOptions): Promise<ViewServer>;

package/dist/view.js

@@ -0,0 +1,99 @@
+import { createServer } from 'node:http';
+import { readFileSync, watch } from 'node:fs';
+import { join, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import open from 'open';
+const templateDir = join(fileURLToPath(new URL('.', import.meta.url)), '..', 'preview');
+const SSE_SCRIPT = `<script>
+(function(){
+  var es = new EventSource('/events');
+  es.onmessage = function(){ location.reload(); };
+  es.onerror = function(){ es.close(); };
+})();
+</script>`;
+function renderHtml(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    let template;
+    let html;
+    if (ext === '.lottie') {
+        template = readFileSync(join(templateDir, 'template-interactive.html'), 'utf-8');
+        const base64 = readFileSync(filePath).toString('base64');
+        html = template.replace('__DOTLOTTIE_DATA_BASE64__', base64);
+    }
+    else {
+        template = readFileSync(join(templateDir, 'template.html'), 'utf-8');
+        const json = readFileSync(filePath, 'utf-8');
+        html = template.replace('__ANIMATION_DATA__', json);
+    }
+    return html.replace('</body>', SSE_SCRIPT + '</body>');
+}
+export function startViewServer(filePath, options) {
+    const clients = new Set();
+    let debounceTimer = null;
+    let watcher = null;
+    const server = createServer((req, res) => {
+        if (req.url === '/' || req.url === '') {
+            try {
+                const html = renderHtml(filePath);
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(html);
+            }
+            catch (err) {
+                res.writeHead(500, { 'Content-Type': 'text/plain' });
+                res.end(`Error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return;
+        }
+        if (req.url === '/events') {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+            });
+            res.write('\n');
+            clients.add(res);
+            req.on('close', () => clients.delete(res));
+            return;
+        }
+        if (req.url === '/favicon.ico') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not found');
+    });
+    // Watch for file changes
+    watcher = watch(filePath, () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            for (const client of clients) {
+                client.write('data: reload\n\n');
+            }
+        }, 100);
+    });
+    const requestedPort = options?.port ?? 0;
+    return new Promise((resolve) => {
+        server.listen(requestedPort, () => {
+            const port = server.address().port;
+            const url = `http://localhost:${port}`;
+            if (options?.openBrowser !== false) {
+                open(url);
+            }
+            resolve({
+                url,
+                close() {
+                    if (debounceTimer)
+                        clearTimeout(debounceTimer);
+                    watcher?.close();
+                    for (const client of clients) {
+                        client.end();
+                    }
+                    clients.clear();
+                    server.close();
+                },
+            });
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afromero/kin3o",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "AI-powered Lottie animation generator — text to motion from your terminal",
   "type": "module",
   "license": "MIT",