# ADR 0018: Presets, built once and cached on the host origin

- **Status:** accepted (2026-10-23)
- **Context:** The common start for an agent or a user is the same: a Vite + React +
  TypeScript project, ready for `npm run dev`. From scratch that costs an `npm ci` (about
  50 packages), plus first-use downloads of rolldown's and lightningcss's WebAssembly stand-ins
  (ADR 0013, about 27 MB) when Vite first reaches for them. Every instance paid this again: each
  runs on its own origin, so nothing one instance downloaded or persisted (OPFS, ADR 0004)
  could help another. Only the browser's HTTP cache was shared, and only for the downloads,
  not the unpacking and installing.
- **Decision:**
  - `createInstance({ preset: 'vite-react-ts' })` starts an instance from a ready-made project
    in `/home/user/app`: its files, its installed `node_modules`, and the stand-ins its
    toolchain uses. It cannot be combined with `fs.from`. A restored persistent filesystem still
    wins over it, as it wins over `fs.from`.
  - A preset is a **template** and a **setup command**. The template is a real project in
    `packages/clientvm/presets/<name>/` with a committed lockfile that pins every package to an
    exact version and sha512 integrity. `scripts/build-presets.mjs` embeds it in
    `src/presets/<name>.ts` with a hash of its files. A unit test fails if the two drift. The
    setup for `vite-react-ts` is `npm ci`, a throwaway `vite build` to fetch the stand-ins, and
    removing `dist` and npm's download cache.
  - **Building:** the first request for a preset starts a hidden **builder** instance. It runs
    the template and setup with the stock runtime (the same npm and stand-in paths as any
    instance), and the controller exports its filesystem image (the format forks use). Then the
    builder is destroyed. Concurrent requests share one build. A request can pass
    `onPresetBuild` to watch the builder's process events (a cold build takes a minute or more);
    a request that joins a running build gets its history replayed first.
  - **Caching:** the image goes into a `PresetStore` owned by the controller. The default store
    is the **host origin's Cache Storage** (cache `clientvm-presets`), so a preset is built once
    per browser profile and host app. Where Cache Storage is unavailable, the store is memory
    for the page's lifetime. Host apps can pass their own store (`ClientVMOptions.presetStore`),
    for example IndexedDB or a store that is preloaded at deploy time.
  - **Keying:** an image is stored under `<name>@<template hash>.<format>`. A changed template,
    or a bumped `PRESET_FORMAT` (for a changed setup or image contents), gets a new key. Storing
    a new version drops older ones of the same preset.
  - Each instance boots from its own copy of the image. Boot transfers the buffers to the
    kernel, and nothing is shared after boot.
- **Why the host origin:** this is the first state ClientVM keeps on the host app's origin.
  Instance origins are per instance and cannot share. A dedicated cache subdomain would keep the
  host origin clean, but it would need another iframe and protocol, and its storage would be
  partitioned under the host's top-level site anyway. The controller is already the trusted
  party on the host page, so it owns the store.
- **Security:**
  - Agent instances never write to the store. Only builders do, and a builder runs only the
    pinned template and setup, never agent code. So one instance cannot plant files in another
    instance's starting image.
  - What a builder installs is what the lockfile pins, integrity-checked by npm, plus stand-ins
    checked against registry integrity (ADR 0013). This is the same trust as running `npm ci` in
    the instance yourself.
  - The image is still treated as untrusted at boot: the kernel validates its structure
    (`importImage`). A truncated or garbled stored image is detected by its framing, dropped, and
    rebuilt.
  - The store is readable by any script on the host origin. It holds only public packages and
    the template, so nothing in it is secret.
- **Consequences:**
  - Measured (`test/e2e/preset.spec.ts`, Chromium, warm HTTP cache): the first `vite-react-ts`
    instance takes about 10 s, building included. Later instances, including after a reload,
    boot in about 0.2 s and make no registry requests.
  - The first build needs the registry. Building in an instance with a limited `quotaBytes`
    is not possible, because builders use the default limits.
  - Cache Storage counts against the host origin's storage quota. One `vite-react-ts` image is
    tens of MB, mostly the stand-ins' WebAssembly. Browsers may evict it under storage pressure,
    which only costs a rebuild.
  - Presets are fixed by ClientVM's release. Custom templates are a possible extension (a
    `FileTree` plus setup, keyed by its hash) but are not part of this change.
  - The open question about a shared package cache (`docs/open-questions.md`) is answered for
    preset projects only. Arbitrary `npm install`s in an instance still download per instance.