For Developers

Build from source, create content packs, or build a companion app.

Architecture

AIVA Pet is a native macOS app built with Swift and WKWebView. The rendering engine (pixel art, animations, physics) runs as an HTML5 canvas inside a transparent, borderless window. All "interesting" content is loaded at runtime from a public GitHub repo.

App (Engine)

Swift + WKWebView. Handles window management, speech recognition, TTS (Flo voice), menu bar, keyboard forwarding, cursor tracking, and the content fetcher.

Content Repo

Public GitHub repo with JSON files: intro animation, cartoon script, chiptune music, and seasonal content packs. Fetched at launch via manifest.json.

Companion App

Optional WebSocket server on localhost:9876. Receives voice queries from the pet, processes them, and streams responses back. Bring your own AI backend.

Content Packs

JSON files with embedded JavaScript. Full access to the rendering engine. Add sprites, expressions, accessories, behaviors, overlays, and animations.

Build from source

Terminal

# Build with Xcode (requires source access)
xcodebuild -scheme AivaPet -configuration Debug build

# Or quick build with swiftc
swiftc -framework Cocoa -framework WebKit -framework Carbon \
    -framework AVFoundation -framework Speech \
    -o AivaPet.app/Contents/MacOS/AivaPet AivaPet.swift
open AivaPet.app

Content pack format

Content packs are JSON files with a js field containing JavaScript that runs inside the WebView. Packs can add custom sprites (18x15 pixel grids), expressions, idle behaviors, action handlers, visual overlays, per-frame update hooks, combo chains, and toggleable accessories.

See the content repo for documentation and examples.

Companion app protocol

The pet connects to ws://localhost:9876 on launch. Messages are JSON with a type field:

Pet to companion: {"type": "query", "text": "user's question"}

Companion to pet:

{"type": "stream", "text": "partial response..."} for live streaming display

{"type": "sentence", "text": "Complete sentence."} for TTS queue

{"type": "complete", "text": "Full response."} for final display

{"type": "error", "text": "Error message"} for error handling

Links

Content Repo (public, JSON content files and pack documentation)