one model, one view, two faces

Kinogaki architecture

Kinogaki is a small stack of C++ libraries around one idea: a file is a live, typed object model that tools and agents can edit, and a UI is a pure function of that file rendered the same way on the desktop and in the browser. This is the whole system, from the model on disk to the bytes on the wire.

What Kinogaki is

Kinogaki is a stack of C++ libraries built on one idea. A file is a live, typed object model that tools and AI agents can read in full, change precisely, and write back with its structure intact. That file format is Prism. Everything above it (the runtime, the widgets, the server, the Python binding) exists to make that model practical to build on.

Two sentences carry the whole architecture. The first is the model:

A Document is a set of Elements indexed by Path, each carrying typed Propertys; a Property is a Value, optionally varying over time.

The second is the user interface built on it: a view is a pure function of a Document, and that view is itself a Document, rendered by the same C++ widgets on the desktop and in the browser.

Three ideas

Everything on this site is one of three ideas working together.

One model. Scenes, images, vector art, narrative documents, and UI trees are all the same Document with different type tokens. The model is in Kinogaki Core, pure and portable, with no idea a screen exists. See the document model.
One view, two faces. A view function takes state and returns a Document of widgets. The same C++ toolkit renders it natively (Cocoa and Metal) or in a browser (WebAssembly and WebGL2). See the two faces.
Prism is the wire. When a server sends a view to a client, or an edit travels back, the message is a Prism Document. A change is a sparse Prism overlay applied to the last one. There is no separate protocol format. See the wire.

The stack, top to bottom

your app            Python (or C++) that authors a view and edits the Document
   │
Kinogaki UI         a GPU-drawn widget toolkit; turns a view-Document into pixels
   │
Kinogaki Platform   OS windowing, input, a Metal-style GPU interface, the buses,
   │                and the server-driven-UI transport
   │
Kinogaki Core       the document model: Elements, Paths, Values, time, codecs
   │
the OS / the browser    Cocoa + Metal, or WebAssembly + WebGL2, or a headless server

The arrows of dependency point down and never back up. Core depends on nothing. Platform depends on Core. UI depends on both. That one rule is what keeps the model portable and the whole thing testable.

How a frame actually moves

When the issue tracker runs as a web app, one cycle looks like this:

The state is a Document (the .prisma issue store). Python calls view(state), a pure function that returns a Document of widgets.
The server's per-client channel compares this view to the last one it sent that client. If only values changed, it ships a sparse diff; if the structure changed, a full snapshot. Either way the bytes are a serialized Prism Document with an envelope on the root.
The browser client deserializes the frame, applies it (a snapshot replaces the running view, a diff overlays onto it), and the C++ widgets reconcile in place, so scroll and focus survive.
A press or a form submit becomes a small event Document and travels back over the same socket. The server mutates the state, re-runs view(state), and the cycle closes.

The rest of this manual takes each layer of that cycle in turn: the model underneath it, the libraries that implement it, the platforms it runs on, the seams where the pieces meet, the loop and the wire that carry it, the two faces that render it, the Python boundary, how it is built and shipped, and the runtimes live today.

The document model ›