theatrics

JS Actor System with first-class support for AI Agents and Assistants

about

theatrics is a lightweight JavaScript actor system designed for building interactive, real-time applications with strong support for AI agents and assistants. It relies solely on the Bun runtime and the framerock framework, which provides zero-dependency web server and WebSocket infrastructure.

features

theatrics enables structured, modular interaction between actors through a clean message-passing model. It manages DOM setup, role definitions, and bidirectional communication between client and server.

Feature	Description
Role-based actor model	Each role represents a functional unit that can receive input and return results via defined cues
Real-time interaction	Clients can initiate cues and receive responses instantly through WebSocket transport
Dynamic UI rendering	The frontend automatically renders a table of role definitions with interactive buttons to trigger actions

AI-Ready

theatrics is specifically optimized for integration with AI tools and agent workflows. It minimizes context overhead by exposing only the relevant code and message structure to language models, enabling prompt engineering and iterative behavior refinement without infrastructure noise.

Benefit	Description
Minimal context pollution	LLMs see only role logic and message patterns, not server routing or boilerplate
Direct prompt compatibility	Role functions can be directly evaluated or generated as code by AI tools
Safe and structured execution	All input and output are serialized as JSON, avoiding unsafe string parsing or injection risks

when to use

• when building agent-based applications where multiple AI-driven actors need to collaborate in real time
• when prototyping or refining agent behaviors using AI tools with minimal setup or abstraction
• when you want a clean, portable foundation that supports both human and AI-driven interaction with your app

getting started

Install theatrics via Bun:

bun add 'git+https://git.daemons.my/dab/theatrics.git'

Create a file named your-app-entrypoint.js with the following content:

import { async_stage } from 'theatrics'

const roles = {
	'say-hello': () => `Hello!`,
}

await async_stage(roles, { framerock_config: { page_title: 'theatrics | minimal example' } })

Run the app:

bun run ./your-app-entrypoint.js

Your app will be visible at http://127.0.0.1:8800. You can customize the hostname and port using the framerock_config object.

codebase overview

file	purpose
src/index.js	Implements the core actor system, including role handling, cue initiation, result delivery, DOM setup, and integration with framerock's transport layer

why theatrics

• simplifies the development of complex, interactive agent systems by abstracting communication and state management
• enables rapid iteration when paired with AI tools for generating or refining role logic
• provides a transparent and predictable interface for both developers and AI agents to interact with the system

changelog

• Version 0.1.0
  • initial release