Architecture

Core Principle

bitwrench.js is the frontend. webwrench does not have its own JavaScript or CSS — it sends instructions that bitwrench renders.

Data Flow

TACO Format

Every UI element is represented as a TACO dict:

{
    "t": "div",            # Tag
    "a": {"class": "..."},  # Attributes
    "c": "Hello",           # Content
    "o": {"id": "el-1"}     # Options (bwserve metadata)
}

TACO stands for Tag, Attributes, Content, Options. This is the wire format between Python and bitwrench.

bwserve Protocol

Server → Browser (SSE)

The server sends JSON messages over Server-Sent Events. Message types:

Type	Purpose
`init`	Initial page load — full element tree
`patch`	Update a specific element by ID
`call`	Invoke a bitwrench function (e.g. `bw.loadStyles`)
`remove`	Remove an element from the DOM

Browser → Server (POST)

User interactions (button clicks, slider changes) are sent as POST requests with a JSON payload containing the widget ID, event type, and new value. The server dispatches these to registered callbacks.

Session Management

Each browser tab gets a unique session (via client ID). Sessions hold:

Widget state — current values of all widgets
User state — SessionState object for custom data
Message queue — outbound SSE messages

Module Structure

Module	Purpose
`taco.py`	TACO dict creation and element building
`_context.py`	Page, Element, WidgetHandle, default page management
`display.py`	Display element functions (title, text, table, etc.)
`widgets.py`	Input widget functions (slider, button, select, etc.)
`charts.py`	Chart.js integration (chart, plot)
`layout.py`	Layout containers (columns, tabs, grid, etc.)
`theme.py`	Theme presets and CSS generation
`export.py`	Static HTML export
`state.py`	Session, SessionState, SessionManager
`server.py`	HTTP server with SSE + POST handling
`app.py`	Multi-page App, PageContext, routing
`options.py`	Global configuration options
`_shell.py`	HTML shell template for served pages
`_assets/`	Bundled bitwrench.js and Chart.js

Design Principles

bitwrench is the frontend — no custom JS or CSS in webwrench
TACO is the wire format — everything is a dict
Surgical updates — only changed elements are patched, no full reruns
Zero dependencies — pure Python stdlib + bundled JS
Context variables — per-session dispatch without global state