App Context Kit documentation
Reference page pulled from app-context-kit at commit 4797e81. Edit it in the Kit, not here.
Overview · Getting started · Context guide · Venue guide · Coordination · Architecture · Platforms · Testing · Design decisions · Spec · Contributing · Repository home
The App Context Kit is the root namespace for one running app. It gives an app an identity, a place for its files and settings, test and scratch modes, a presence entry other apps can see, a session with a resource broker, and an opt-in way to find and talk to other copies of itself. It does not decide what any of that means for your app.
It is a piece of a larger platform, it is not published to a package registry yet, and the question behind it is: does the BeOS idea of an Application Kit still make sense when you build several small apps instead of one big one? These pages say what was built, how it was checked, and what is not yet known.
Start here
| I want to… | Read |
|---|---|
| understand what this is in five minutes | Overview |
| build a Flutter app on it | Getting started, then the context guide |
| use it from plain Dart or from Rust | Getting started: plain Dart, Rust and examples/dart_cli, examples/rust_cli |
| have two copies of my app find and talk to each other | Coordination guide |
| take machine time from a resource broker | Venue guide |
| write tests that never touch real files | Testing |
| ship on macOS, Linux or Windows | Platforms |
| judge whether the idea holds | Design decisions, then the results at the foot of this page |
| see how the pieces fit | Architecture |
| read the contract itself | Spec and its fixtures |
Every page
Learn
| Page | What you get |
|---|---|
| Overview | The problem every app re-solves, the idea, the pieces in one table, the rules, what it does not do |
| Getting started | Numbered steps from nothing to a running app, plus pure-Dart and Rust versions |
| Architecture | Six diagrams: the layers, start-up and shutdown, the peer handshake, the roster versus peer announcements |
| Design decisions | Why it is shaped this way, what we chose not to build, and the open questions |
Build
| Page | What you get |
|---|---|
| Context guide | Manifest fields, directories per platform, every environment variable, settings, lifecycle, the roster, the Flutter companion |
| Venue guide | The broker session: modes, holds and leases, typed refusals, orphan holds, pinned TLS, what registering an app costs |
| Coordination guide | The five-method hook, the hub, providers, three worked patterns, and what the hook does not give you |
| Testing | Scratch and mock modes, fakes, the shared fixtures, real-daemon runs, Linux and TLS scripts |
Evidence
| Page | What you get |
|---|---|
| Platforms | What runs where and how it was verified, with the macOS sandbox entitlement table and the crashed-copy numbers |
Runnable examples
Every code sample in these pages is copied from one of these, or from a passing test or one of the demo apps in The Kit Book. Run them rather than trusting the text.
| Example | What it shows | Run |
|---|---|---|
examples/dart_cli | The Kit from plain Dart: open a context, a setting, a counter, the Venue-off session | dart test / dart run bin/main.dart |
examples/rust_cli | The same app in Rust; prints the same lines | cargo run |
examples/flutter_hello | A five-line main.dart, app.json and a widget test | flutter test |
examples/coordination | A two-copy “ping” app on the fake network, plus behaviour tests (scope, ordering, limits) | dart test |
The short version of the results
- One contract, two implementations. Dart and Rust pass the same 61 fixtures. The second implementation found about a dozen behaviours the first had decided silently.
- Less code per app. Helper code the six apps wrote themselves went from 727 lines to 330, up to 777 after coordination was added, and down to 164 once the repeated parts moved into the Kit. Every
main.dartis 5 to 11 lines. Build a Kit piece when the second app copies it, not before. - The hook is the right shape, and not enough on its own. It carried a shared timer and a game handoff cleanly, and live play only just. For sync it was a small shell around a lot of app code, because the Kit gives no acknowledgement, large transfer, replay or liveness tick.
- Same-machine coordination works; across machines is not built. Two copies found each other in under half a second on one machine; a crashed copy disappeared in about 3.5 s.
What is not verified
A real Linux desktop session (the cores are tested in Linux containers, and the demo apps were built in release mode and launched headless in a Linux container), window close on a real window, signed or packaged release builds, Windows beyond the pure path rules, and the peer code against a real remote hub. Each page marks its own unverified claims. “Verified” in these pages means a test, a command or a measurement in the App Context Kit repository; anything else is labelled as reasoned or reported.
The demo apps
Several pages quote six small demo apps (a calculator, minesweeper, a notepad, a stopwatch, a render queue and a launcher) and the helper code each one had to write. The apps are not in the App Context Kit repository: they live in The Kit Book (the Kit Book repository), which documents the Kit and holds the demo apps. Paths such as lib/kit_gaps/ or lib/coordination/ in these pages are paths inside those apps.
Conventions
- Page names are stable; sections are linked by their headings.
- Code blocks are checked against the App Context Kit repository. Where a block is illustrative, it says so.
- Some findings about other systems are deliberately not described here: where a review is pending, the page says that and nothing more.
- Numbers come with what they were measured on (macOS debug builds, loopback, a throwaway local broker). They are not benchmarks.
Repository home · Spec · Contributing · Licence (Apache-2.0)
Pages in this book
Every page pulled from the Kit, in reading order.
| Page | What it covers |
|---|---|
| Overview | The App Context Kit is a small library that gives one running application its root namespace: who it is, where its files live, where its settings are, whether it is running for real or under test… |
| Getting started | This guide takes you from an empty folder to a Flutter desktop app that runs on the App Context Kit, then shows the same thing in plain Dart and in Rust. |
| Context guide | Reference for the AppContext and everything it is built from. |
| Venue guide | How an app built on the App Context Kit asks Venue for a share of a machine’s resources, and what happens when Venue says no, goes away, or the app dies. |
| Coordination guide: copies of one app talking to each other | This guide is for a developer who wants two running copies of the same app to find each other, agree on who is there, and exchange messages. |
| Testing | Two things are covered here: how to test an app built on the Kit, and how to run the App Context Kit repository’s own test suites. |
| Architecture | This page explains how the App Context Kit is put together: the layers, what happens when an app starts and stops, how two copies of an app connect, and how the spec, the shared test fixtures and the… |
| Platforms | What runs where, how it was checked, and what was not. |
| Design decisions | Why the App Context Kit is shaped the way it is, what we tried instead, and what is still undecided. |
| The app context spec | This is the contract both implementations (Rust in rust/, Dart in dart/app_context_kit/) must satisfy. |
| Example: dart_cli | A command-line program on the App Context Kit core (pure Dart, no Flutter). |
| Example: rust_cli | The same program as ../dart_cli, using the Rust crate in rust/: same app.json, same directories, same settings file. |
| Example: flutter_hello | A small Flutter desktop app on the App Context Kit: a button that counts taps, saves the count as a setting and writes it to a file under the data directory. |