Guide

Structure is layout

<row gap="8" align="center">
  <image src="icon.svg" w="20" h="20">
  <text grow>A row lines things up</text>
  <button>Go</button>
</row>

<row> lines up, <col> stacks, <grid cols="3"> tiles, <stack> layers, <scroll> clips. A box measures itself from its content and its padding unless you give it w or h. Something with grow takes its share of what is left over, its share of the free space, not its content plus a share, which is what makes two of them exactly equal.

Responsive without a breakpoint

There is no media query and nowhere to put one. The author says what a thing needs; the layout decides what fits.

<!-- as many columns as fit -->
<grid col-min="220">…</grid>

<!-- a row, until it cannot be -->
<row wrap="200">…</row>

A row whose children cannot each have 200 pixels stops being a row: it folds onto as many lines as it takes, and at one child per line it is a column. One calculation in layout.c, so it folds at the same pixel on all three systems, which a stylesheet per platform could never promise.

Events

button.addEventListener("click", save);
document.body.addEventListener("key", function () {
  if (document.body.key === "Escape") close();
});
card.addEventListener("drop", function () {
  open(String(document.body.files).split("\n")[0]);
});

Spark has no event object, a listener is a function of no arguments everywhere, so what came with an event is read off <window> like any other property. Key names are decided once for all three systems, so nobody has to know whether this one calls it Return or Enter.

A sound, when something finishes

spark.sound("sounds/done.wav", 0.5);

NSSound on macOS, PlaySound on Win32, and whatever the desktop brought along on Linux. Spark carries no audio library and no decoder, it hands over a path.

More than one window

spark.open("settings.html");   // a second window, a second document
spark.tell("saved");           // a line to every other window

A window is a document: its own tree, its own script context, its own clock. They share a process and nothing else, so the only thing one can do to another is tell it something.

Any language, one layer

# Python, shell, Go, Rust, the same fourteen commands
spark app.html --serve

The window opens and speaks one line at a time over stdin and stdout. clients/spark.py is 208 lines and clients/spark.sh is 65; the format is in PROTOCOL.md. Nothing has to stay in sync as Spark grows, a new property, service or plugin command is a new string, not a new binding.

Looking at a window that is already open

$ spark app.html --agent &
$ spark apps
$ spark live app actions
$ spark live app set email ada@example.com
$ spark live app press create

The same protocol as --serve, on a local socket beside a running window. tree gives everything, actions gives what can be pressed and filled in. Useful for a test; useful for anything driving your app that is not a person.

Saying what a driver may touch

<window agent="read">
  <input  id="customer" agent="read write">
  <button id="send"     agent="invoke">Send invoice</button>
  <button id="delete"   agent="deny">Delete account</button>
</window>

read, write, invoke, all, deny. A control that says nothing inherits from the nearest ancestor that does, so a document is shut at the top and opened one control at a time. One that says nothing anywhere is open, the same bargain spark.toml makes, and for the same reason: a model that breaks every app that already exists is one nobody turns on.

invoke carries read with it, because a control in actions is listed by name and nobody means "press this blind". write does not: a field an agent may fill but never read back is a real thing to want.

This never applies to --serve. That hands the window to a program which is the app, its own logic in Python or a shell instead of JavaScript, and an app is not a stranger to itself.

A session is a text file

$ spark record app.html session.txt   # use the window
$ spark replay app.html session.txt   # watch it again

press	save
set	who	value	Ada
set	shout	checked	true

Because the whole surface is nine string operations, the protocol that drives an app is already a recording of it. Nothing is captured or serialised; the log is the session.

That holds for a person, not only a program. Every click and every value typed goes through one function, so what lands in the file is the command that would have caused it: names and values, never coordinates. A recorder that writes down where the pointer was stops working the moment somebody moves a button. This one keeps working, and the test proves it by replaying a recording into a document whose layout was changed underneath it.

One file is three things at once: a bug report that reproduces itself, a regression test with no screenshots in it, and a macro.

What this app offers, in the repository

$ spark contract --write app.html
$ spark contract --check app.html      # fails when it drifts

control   button        #tb_run    uname -a       read write invoke
control   slider        #vol       Lautstaerke    read write invoke
offer     #tb_run
space     #tb_run -> pressed

A renamed id, a widget that changed tag, a tightened agent=: one-character edits that nothing notices at build time and that every script, test and agent written against the app notices at once, after it shipped. So what the app offers its four callers is written down beside it and checked in.

Above the marker is what every system must agree about; below it is what each system answers for itself — where Tab goes, what the space bar does, and where Enter lands — which is what spark cross compares. Nothing runtime goes in the file.

On its first run across the three systems it found four defects that the layout check could not see — every one with the pixels matching, the keyboard order identical and the four-caller count full: a Windows field read back its own placeholder as a value, a Linux slider read back nothing, a Linux <select> reported nothing while visibly showing an item, and a progress bar's number had become its accessible name.

<button default> is the button Enter presses. Every system has the idea and no two spell it the same way, so the document says which button it is once and each host does its own thing with the mark: a Return key equivalent on AppKit, BS_DEFPUSHBUTTON on Win32, and the suggested-action class on GTK.

Your window is an MCP server

$ spark mcp notes.html
spark: 5 tool(s) from Notes
  press_save     Press save — the button labelled “Save”.
  fill_what      Type into what — the input labelled “a note”.
  read_screen    Every control: role, name, value, position.

An app with named controls, a list of what can be pressed, and a rule for what a stranger may touch is most of the way to being an MCP server already. So this is a translator and nothing else: a button becomes a tool, a field becomes a tool that takes a value, and the tree becomes read_screen, which is what replaces a screenshot. There is nothing to recognise and nothing to guess at.

The list is built from the running app, so it is the real controls and not a description of them somebody has to remember to update. Rename a button and the tool is renamed.

It opens the app with --agent rather than --serve, which is the point: a model is a stranger, so the agent= rules above stand between it and the controls. A field it may not write never becomes a tool. The bridge can only translate what the app already offers.

Which also means the window is a window. Somebody can watch it, and use it, while the model works in it.

A request that does not stop the window

spark.fetch(api + "/games", { into: "games" });

<text>{{games}}</text>

Returns at once. When the server answers, the signal is set and everything bound to it follows — no callback crosses the JavaScript bridge, and an app that already knows how to show a signal has nothing new to learn.

No event loop, no thread and no second HTTP stack: curl is started detached and leaves a marker, and the window looks for it on the frames it is already drawing. A window with a request out is a window that is not idle, and it goes back to sleep the moment the answer lands.

Talking to a server

var r = spark.fetch(api + "/games", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
  body: JSON.stringify(game)
});
if (r === null) offline();          // the request never happened
else if (r.ok) done(JSON.parse(r.body));

One implementation, not three: every system ships curl (Windows since 2018), and NSURLSession, WinHTTP and libcurl would be three chances to disagree about a redirect. Nothing is passed on a command line, the url, method, headers and body go into a config file curl reads, which is also the only way to carry a header containing a quote without inventing an escaping rule.

It waits for the answer, the way spark.run does. A request that takes a second holds the window for a second.

What the system already runs

spark.file.write(spark.dir("config") + "/settings.json", text);
spark.notify("Build finished", name);
spark.tray("", "Running");
spark.hotkey("ctrl+alt+G");
spark.sound("sounds/done.wav", 0.5);
spark.openFile();  spark.run("git status");  spark.writeClipboard(text);

Dialogs, the clipboard, notifications, the status area, global shortcuts, standard folders, running a program, opening a URL. Every one of them is the system's own, and every one answers null where the system has no such thing, so an app can ask and carry on.

npm packages, without shipping a runtime

<script src="main.js" bundle></script>

The developer's own esbuild and Babel translate the script down to es5 before it is baked in, never on the machine that runs the app. They have Node because they installed the packages; the person using the app needs neither.