Host API

You are writing a tool's hooks.js and need something the template cannot do alone: read the person's profile, place a brand asset, shape a headline into outlines or hand back a finished file. Every hook receives one object, host, that does those jobs for you.

The same hook runs unchanged in the web app, the desktop and mobile apps, the CLI, the TUI and the MCP server. Each of them implements host in its own way, so your tool never touches the DOM outside its template, the network or storage directly. (The TUI reuses the CLI's implementation, so anything this page says of the CLI applies to the TUI too.)

Every shell provides six members: profile, assets, state, clipboard, export and log. The rest are optional. Check for an optional API before you call it, or list the ones your hooks cannot do without in the manifest's requires, and a shell that lacks one refuses to open the tool instead of failing halfway.

Unless a section says otherwise, an API works on the device and sends nothing anywhere. Where the engine does the work, as it does for colour, geometry, connectors, codecs, audio analysis and layout, every shell runs the same engine code, so the web app and the CLI get the same numbers and the same bytes.

To type-check and test against this contract without cloning Lolly, install the SDK: npm i -D @lolly-tools/core. It installs the HostV1 types, validateTool and createMockHost (package page). The canonical declarations are in packages/core/src/host-v1.ts, a stable barrel over one file per API in packages/core/src/host-v1/, and an API snapshot test rejects accidental signature drift.

function onInit({ model, host }) {
  host.log('info', 'tool booting', { shell: host.shell });
  // ... call host.profile / assets / state / clipboard / export / net / text
}

Build a tool covers a tool's anatomy, and Tool hooks covers when each hook runs.

Rules of the contract

• Additive only. Methods may be added in a minor version, and are never removed or changed in signature without a major version. When v2 ships, v1 keeps working.
• Check, or declare requires. Check for an optional API before you call it (host.text?.toPath). When your hooks call one without checking, list it in the manifest's requires (["text", "tokens"]): the runtime then refuses to mount the tool on a shell that lacks one, before any hook runs, and the gallery greys the tool out there. node scripts/tool-requires.ts --write reads your hooks.js and writes the list. See Tool manifests. HOST_V1_OPTIONAL_APIS in packages/core/src/host-v1/apis.ts is the complete list of optional APIs.
• Device and network access needs a capability. net (network), capture (capture), compose (compose) and recorder (microphone, camera or screen) need a matching flag in the manifest's capabilities. Every other optional API takes no flag and is present only on a shell that provides that API.
• No platform-specific methods. If only one shell can do something, it sits behind a capabilities flag, and shells that cannot fulfil it expose a stub or an error.
• Identify the host. host.version is '1'; host.shell is one of web, tauri-desktop, tauri-mobile or cli.
• host is the portable surface, not a sandbox. Where hooks run says when a hook runs in the page and when it runs in a Worker.

Find the API for your job

What every shell provides

host.profile

The person's details. Tools read them; the person manages them in the host's own interface. Most tools never call this directly: declare bindToProfile: "firstname" on an input and the host fills it in for you.

Profile: the fields a tool reads are firstname, lastname, email, phone, title, org, city, country, lang, headshot (AssetRef), useDetails and custom. useDetails is the opt-in that gates embedding author and contact details into export provenance. The rest are app preferences and interface records, not a tool concern: featureFlags (the person's local interface flags), a11y, appearance, emoji, saveRenders, exportHome, favourites, hidden tools, templates and assets, trusted sites and similar records.

host.assets

The bridge to the catalog and the person's own library. For an asset-typed input the host builds the picker from your manifest declaration, so you rarely call pick() yourself. Use the url of an AssetRef in your template through the asset helper ({{asset logo}}).

host.state

Per-tool saved state: IndexedDB on the web, the filesystem on Tauri and memory on the CLI. Never use localStorage. The host already saves and loads people's sessions, so reach for this only for state the tool manages itself.

StateEntry: { slot, toolId, toolVersion, updatedAt, label? }.

host.clipboard

host.export

The host owns the renderer, so tools do not bundle their own. render turns the tool's DOM into a file, file delivers bytes the tool made itself, and imprint marks an existing raster.

File inputs

A file-typed input (the person's own file, picked into memory) arrives as an InputFile: { __file: true, name, mime, size, bytes (Uint8Array), url }. The hook reads bytes directly. There is no host.* call, because the bytes ride in the input value: the portable host surface has no file-read API, so the same hook runs on every shell. A file value never serialises to a URL and is never persisted. The exportFile hook transforms those bytes and returns { bytes, mime, filename }, which the shell delivers through host.export.file. strip-data is the reference; Build a tool has the full pattern.

host.log

log(level, msg, ctx?): level is debug, info, warn or error. Goes to the console in development and to a diagnostics buffer for support. Hook errors are caught and logged, not thrown.

Brand and type

host.tokens

Design tokens (DTCG) for the active theme. The host's colour pickers draw their swatches from these, and the runtime resolves token-referenced input values against them. A shell without it offers no token-driven controls.

The family of leads. A tool that uses several colours at once, such as chart series or a gradient's shuffle, can draw on every colourway's lead rather than one primary. family() lists them whatever colourway the artefact uses, and the artefact's own one has active: true. Treat fewer than two members as no family, and draw exactly as you would on a shell without the member:

const family = typeof host.tokens?.family === 'function' ? await host.tokens.family('primary') : [];
const leads = family.length >= 2 ? family.map((m) => m.value) : [];

Put the leads ahead of the colours you would otherwise draw, never in their place. A design system with two colourways and no spectrum of its own still needs a full categorical palette, and two leads alone would repeat from the third series on. For chart series, prefer the brand's own color.spectrum.* tokens from host.tokens.colors() (they carry measured print inks), top up with host.color.distinct() anchored on {color.semantic.primary} and keep your shipped palette as the fallback; chart is the reference.

The web shell, the CLI and the hook Worker answer family() and axes() with the same engine functions, scoped to the artefact's choices like every other read. The canvas carries the same family as CSS variables, --brand-lead-1 onwards, described in Authoring tools. A colourway or look switch re-points the slots without running onInit, so a hook that keeps colours it read there reads them again when onInput runs with id: '__tokens', as When the theme or colourway changes describes. A hook can also compare {color.semantic.primary}, and any other slot it depends on, on each onInput and read again when the value changed, which catches an edit to the design system too. Chart, Mesh Gradient and Filter do both.

host.text

Shape a text run and outline it into an SVG path with HarfBuzz, with correct kerning, ligatures and GPOS/GSUB. It needs no DOM: the web app, the CLI and the TUI all provide it, and in the Node shells fonts resolve off disk. The wordmark tool uses it to outline display type for crisp vector export.

host.fonts

Optional, v1.262. Read a font file's own tables and subset it to chosen text. The web, desktop, CLI, TUI and MCP shells provide it, and the same engine code answers on each, so the facts and the bytes match. Convert Font is the reference tool.

host.emoji

Optional, v1.196. The pinned vector emoji sets this shell's catalog mounts, so text in a render draws its emoji from the set the person chose rather than from the operating system's font. The runtime calls it for you after every paint and again inside an export, so most tools never call these methods. The web, desktop, CLI and TUI shells provide the API. A shell with no set mounted leaves it out, and the render shows the engine's neutral placeholder, never a system glyph.

The host supplies storage and transport only. Every decision about what to draw (sequence lookup, admission, fallback through the saved pins, the brand treatment and sizing) is the engine's, so a run of text looks the same on every shell.

host.color

Optional, v1.40. Work from brand primitives without shipping colour science in every tool: perceptual distance, contrast (WCAG plus advisory APCA), smooth OKLab ramps, data class breaks, distinct categorical palettes, harmony schemes, CSS-correct mixing and gradient baking. Every method is pure and synchronous. Keep a small fallback for older shells. Every colour it emits is a gamut-mapped #rrggbb (#rrggbbaa when translucent).

Pictures and pixels

host.images

Optional, v1.60. Decode, resize and re-encode: the "HEIC to JPEG, compress to WebP, downscale" job as a first-class API. Encoded bytes (or a Blob) go in, and encoded bytes plus dimensions come out, so the shell owns the codec and the engine never sees a canvas or an <img>. Fall back gracefully where it is absent.

An animated source flattens to its first frame. Read the result's mime, width and height rather than assuming the request was honoured, because a shell may fall back (PNG where WebP encoding is unsupported).

host.raster

Optional, v1.105. The sibling of host.images for tools that composite, sample or change pixels themselves (Darkroom, the Filter tool, the logo composers, Redact). Where images converts bytes to bytes with no pixel access, this hands back drawable pixels. Fall back to your placeholder where it is absent. The headless CLI provides it when the optional Skia canvas (@napi-rs/canvas) resolves, which is what lets lolly redact repaint pixels locally; on a lean install without it the member stays undefined.

src is a URL (including blob:/data:), an AssetRef or raw bytes or a Blob. Building and drawing into a canvas is left out of this API: new OffscreenCanvas(w, h) is a realm global a hook constructs directly, so a round trip through the host would buy nothing.

host.codec

Optional, v1.100. Encode a float pixel frame into finished image bytes at real bit depth. It is the counterpart of host.export.render, which rasterises the DOM to 8-bit. A tool that computes its own high-precision pixels, such as a float grading pipeline or a renderer with real headroom, hands over a linear Float32 RGBA frame and gets back a 16-bit PNG, an OpenEXR or Radiance HDR master or an error-diffused 8-bit PNG, depths the browser's 8-bit canvas cannot originate. Fall back to the ordinary 8-bit export where it is absent. Darkroom is the reference consumer.

host.layers

Optional, v1.102. Write a set of positioned RGBA layers as a layered Photoshop PSD with the engine's own writer, so the file opens in Photoshop, GIMP and Krita. One method today. Like every export.file path, the result is never watermarked or provenance-stamped, because it is the person's own file.

A LayerWrite is { name, x, y, width, height, pixels, opacity?, blend?, visible? }: pixels is RGBA8, un-premultiplied sRGB (what a canvas getImageData gives), and width/height must match the buffer. blend takes a CSS mix-blend-mode value. The read side is not part of this API: PSD and XCF import is a shell ingest flow (the drop router turns each layer into a library asset), not something a running tool does.

host.scan

Optional, v1.153. Find machine-readable codes (QR, Data Matrix, Aztec, PDF417 and the 1D families) in one RGBA frame. The web shell uses the browser's BarcodeDetector where present and a zxing-wasm decoder otherwise; the CLI and TUI load zxing-wasm from disk. Pair it with host.media for a live viewfinder, or use it alone on a still image. The Scan tool (scan-code) is the reference.

A ScanHit is { format, rawValue, rawBytes?, corners? }. rawValue is untrusted input: show it, never act on it automatically. rawBytes is present when the content is not valid UTF-8, and corners is the code's quad for an overlay.

host.lift

Optional, v1.123. svg(source) fetches and sanitises an SVG named by URL (a catalog asset, a blob: or a data: URL) and returns its layers in paint order as standalone SVG documents with their ink boxes, plus the source viewBox. A source that is not an SVG, or has fewer than two layers, comes back with layers: []; the method throws only on a fetch or parse failure. Turning layers into depth is the caller's job. The web and desktop shells provide it; the Node shells do not. Flythrough is the reference tool.

Vector, layout and motion

host.geom

Optional, v1.64. Path booleans, offsetting, stroke-to-fill outlining, pen-tool spline lowering, simplification and hit testing: the engine's geometry kernel, which keeps everything as real Béziers (nothing flattens, samples or rasterises). Every method is pure and synchronous, so a pen tool's geometry is identical in the browser, in Tauri and headless on the CLI.

The currency both ways is an SVG path-data string, which already lives in your template, your saved state and your URL. parse and toPathData expose the structured form (contours of whole cubics, 8 numbers each) for callers that want to walk or edit curves themselves.

Failures are returned, never thrown. Every method answers { ok: true, … } or { ok: false, code, message }, because a throw out of onInit or onInput is caught, logged and discarded by the runtime, which would leave a tool unresponsive rather than telling the person anything. A path result carries { d, contours, curves }; a measurement result carries { value }.

host.connectors

Optional, v1.106. Export-safe connector, line and arrow geometry: the engine's connector module behind a tool-facing surface, attached verbatim by every shell, so web, Tauri and CLI emit identical arrows. A canvas tool's hooks.js renders its connectors in one line, and a headless --export keeps them. Pure and synchronous, like color and geom. Everything below build is optional, so check for each member, not just the surface.

host.layout

Optional, v1.249. evaluate({ boxes, tracks? }) solves the Design tool's layout rules for a set of boxes and returns the solved boxes, any findings ({ id, code, message }), the number of passes and solved boxes, and the grids it laid out with their columns, rows and cells. The web, desktop, CLI and TUI shells provide the API. The Design tool is the reference consumer.

host.keyframes

Optional, v1.124. sample(kf, count) evaluates a kf track (the format the Design tool's camera and every keyframed input use) at count evenly spaced times across its own span, and returns each pose as a channel-to-value map (x, y, z, rx, ry, …). The engine owns the parsing, interpolation and easing, so a template's motion matches the Design tool's; the template decides how the channels map onto its own scene. An empty or unreadable track returns []. The web and desktop shells provide it; the Node shells do not. Flythrough is the reference tool.

Documents and text

host.pdf

Inspect a PDF, remove its metadata and make it smaller. The metadata and structural work is pure pdf-lib, so it runs even in the lean CLI; image recompression uses a browser canvas. strip-data and compress-pdf are built on this API. Check for each method (for example host.pdf?.compress): an older shell may provide analyze and strip but not compress, or no host.pdf at all.

host.pptx

PowerPoint inspection and surgical rebranding (engine 1.58). The shell unzips with fflate and injects its DOMParser, so the engine's OOXML reader and patcher need no zip or DOM code of their own. rebrand-deck is built on this API. Check for host.pptx?.rebrand, because an older shell may lack it entirely.

host.prepare

Optional. Inspect files for hidden data and personal values, then write copies with the replacements the person chose. Working values stay in memory, and the report leaves private values out. The web, desktop, CLI and TUI shells provide the API. Strip Hidden Data is the reference tool.

host.compare

Optional, v1.189. A bounded comparison of two immutable snapshots: text, structured data, YAML, tables or the reading units of a document. The shell resolves the sources; this API only compares what it is given. The web, desktop, CLI and TUI shells provide it, and the Compare view calls run().

host.textTools

Optional, v1.191. Portable text operations: the list a text utility offers, running one operation and highlighting code. The web, desktop, CLI and TUI shells provide the API, and the Text (text-helper) and Snippet tools are built on this API.

Sound, speech and camera

Five APIs cover sound and video, and each faces a different way:

host.media

Optional, v1.4. A live camera frame source for motion-reactive tools, such as a filter that responds to movement. It is progressive enhancement, not a gated capability: a tool offers a "live" control only where a camera exists and works as an ordinary still-image tool everywhere else, so do not list camera in the manifest's capabilities. Check for host.media?.isAvailable(). The web shell and Tauri (its webview) provide it through getUserMedia; the headless CLI does not.

A MediaFrame is { width, height, data: Uint8ClampedArray (RGBA), t }: plain pixels, no DOM types, so the engine stays platform-agnostic, and the shell owns the MediaStream, the <video> and the grab loop, as it does for capture. data is valid only during the callback, so read it synchronously. Frames are downscaled and throttled, and pause while the document is hidden.

You rarely call subscribe yourself. Declare an onFrame hook and the runtime drives it once per camera frame; the shell's "Go live" toggle calls runtime.startLive() and runtime.stopLive(), and no camera outlives the tool. Motion-reactive tools has the pattern; the filter tool is the reference.

host.recorder

Optional, v1.17; capability microphone, camera or screen. Record the microphone (and optionally the camera or the screen) to a finished media Blob, plus a DOM-free level meter for a sound check before recording. The shell owns getUserMedia and MediaRecorder, and the engine only ever sees plain numbers (AudioLevel) and finished Blobs, never a MediaStream or a <video>. Recording prompts for a permission a shell may be unable to grant, so it is gated: declare "microphone" (and "camera" for video) in capabilities. The headless CLI provides no recorder. voice-recorder is the reference tool.

host.audio

Optional, v1.71. Decode a finished clip and get back a per-frame reactivity track: loudness, a bass, mid and treble split, a log-spaced spectrum, brightness, onset strength, a tempo, beat times and, if you ask, raw time-domain windows. It is the primitive behind visuals that move with the music rather than sweeping a playhead over a static shape. Where host.recorder.meter reports the live microphone one sample at a time, a tool drawing a clip needs frame 200's bass while it is still rendering frame 1. Fall back to a static waveform where it is absent.

host.speech

Optional, v1.96. Turn a tool's own text into spoken audio, with no upload: on-device Kokoro TTS returns mono PCM plus word timings, which a shell can play, mix under a video export or hand straight back to audio.analyse. The word timings are what a caption or karaoke-highlight tool keys off. Hide the voiceover control where it is absent. The headless CLI provides it too, over the same models on onnxruntime-node, so a hook that speaks its own text renders headless. lolly speak and lolly transcribe are its discovery surface there, and a model that is not staged refuses by name instead of downloading itself.

host.viz

Optional, v1.72. Availability and attribution only. A tool is data: it has no element to hand over and no business holding a GL context, so it renders a [data-lolly-viz] placeholder carrying its parameters, and the shell owns the canvas behind that placeholder. That is the same contract [data-lottie-src] uses, and it lets the context and its loaded preset survive the innerHTML rebuild every keystroke causes. A shell without this, or without WebGL2, means the tool draws its ordinary canvas style, never that it refuses to render.

A VizPresetInfo is { id, name, author, calm }. author is not decoration: twenty years of MilkDrop craft ships alongside Lolly's own presets, so credit only a preset the shell confirms it has. Naming an artist whose work is not on screen is worse than crediting nobody. calm marks a preset safe to offer under reduced motion.

Reaching outside the tool

host.net

Capability network. fetch(url, init?) → Promise<Response>, an allowlisted fetch. Absent unless the tool declared "network", and tools without it have no supported network path. For a hook that runs in the page realm that is a review rule, not a sandbox; a hook in a strict Worker has no network globals at all (see Where hooks run and the Threat model). Network access covers the allowlist.

host.capture

Capability capture. Rasterise a live URL to an image with a real browser engine. Only shells with an authoritative engine fulfil it: Tauri's webview, a headless-Chromium CLI or the browser extension. The plain web app cannot read cross-origin pixels, so it exposes a stub that throws. Capture is slow and has side effects, so call it from an explicit action, not on every keystroke. The url-shot tool calls page().

host.compose

Capability compose. Render another tool's output to an embeddable asset: tool composition, or nested exports. The runtime resolves a manifest's composes entries through it and exposes each as {{asset <id>}}, so you rarely call it directly. A shell that cannot render a child to bytes (the no-raster CLI for a raster child, for example) leaves it out, and composition degrades gracefully.

host.models

Optional, v1.246. Hand a tool the bytes of named files of an on-device model family. It is for a tool that runs a model in a context of its own, where the shell's model store is out of reach: the Rondocode utility's editor frame has an opaque origin, with no IndexedDB and no network of its own, so it asks here for the singing models its songs need. The web and desktop shells provide it; the Node shells do not.

The shell decides everything about the download. When a named file is not on the device, it offers the family's download in place first, with the size and the licence facts, and nothing moves until the person says yes. A download made there is the same download Settings offers under Available offline, so Settings shows it as downloaded afterwards. A family tools may not read, or a path that is not one of the family's files, is refused by name: the promise rejects. Each value is the only view of its own ArrayBuffer, so the caller can transfer bytes.buffer to a frame without a copy.

On-device AI models

Three APIs run a model on the device: upscale enlarges a picture, matte cuts out its subject and ocr reads its text. They share one pattern. The shell owns the ONNX runtime, the one-time model download (made only with the person's consent) and the memory bound, and the tool only ever sees pixels. A run can take many seconds on a weak device, so it is never driven from a time-boxed hook: a shell offers it as an explicit, cancellable action with progress, whose result becomes an asset. Hide the control where the API is absent.

The headless CLI provides upscale and matte too, with onnxruntime-node and sharp in place of the browser's runtime and canvas, so a hook that uses them renders headless. The member stays undefined on a lean install that carries neither, and a model that is not staged refuses by name rather than downloading itself. The CLI attaches ocr once the model weights are staged.

What each records in the file differs, because what each invents differs:

host.upscale

Optional, v1.101. Enlarge a low-resolution raster with no upload. For the person whose headshot is 400px beside colleagues' 2000px photos, it enlarges theirs offline. The Node shells run onnxruntime-node on the CPU, and their backend() answers null. An UpscaleFrame is { width, height, data: Uint8ClampedArray }: RGBA, 8-bit, straight alpha, the shape a canvas getImageData gives and putImageData takes.

host.matte

Optional, v1.103. Remove the background from a raster with no upload: a plain RGBA frame goes in and the same frame comes out with a model-computed alpha matte. The web and desktop shells run the matte models on WebAssembly only, because onnxruntime-web's WebGPU kernels reject an operation these models use. The result is a same-format cutout that keeps its metadata, colour and credential intact.

A MatteFrame is { width, height, data: Uint8ClampedArray }: RGBA, 8-bit, straight alpha. On the way in the model reads only RGB and ignores alpha. On the way out the RGB is byte for byte the input's and the alpha is the computed matte, so the result composites directly.

host.ocr

Optional, v1.127. Read the text in an image: a plain RGBA frame goes in, and lines of text with boxes and confidences come out. Recognition is a best-effort read, so show the text as a draft the person can correct. OCR reads pixels, so signals carried by digital text (invisible characters, homoglyphs, a text watermark) do not survive the trip through pixels. The web and desktop shells provide the API.

Provenance

Ordinary exports get their Content Credentials through host.export, which owns ingredients, action history and the opt-in gates. Two narrower paths exist for files a tool did not render: host.export.imprint marks an existing raster with the Lolly Imprint, and host.c2pa signs finished bytes.

host.c2pa

Optional, v1.85. Embed a freshly signed C2PA manifest into finished bytes. It exists for the redacted-derivative path, where carrying the source's manifest forward would re-embed a pixel-accurate thumbnail of the unredacted original, so the output is signed as a new work instead, and the caller says so in its interface. Check for host.c2pa?.sign. Signing uses the enrolled device identity when one is valid, else an ephemeral on-device key.

Where hooks run

Hooks are loaded with new Function('host', …), with host injected as closure scope. That is a portability contract, not a security boundary. A hook that runs in the page realm can, in a browser shell, reach window, document and fetch; host is the only surface guaranteed to exist on every shell. Module imports do not work, because hooks ship as a single source string.

Hooks can also run in a Worker:

• Verified built-in tools ask for it with manifest isolate: true, and the web shell then runs their hooks in a Worker, falling back to the page realm if a Worker cannot start. Run hooks in a Worker says how the flag is set.
• On the CLI, LOLLY_HOOK_WORKER=1 runs every tool's hooks in a worker_threads Worker.
• Sideloaded and remote tools, in the web shell, always run in a strict Worker that fails closed rather than falling back, with an allowlisted host facade and no network or storage globals. A strict Worker is terminated when a hook overruns its budget.

Sideloaded and remote code never reaches the page realm. Verified built-ins and visibly unsigned development tools still can, and for verified built-ins the signed catalog is the trust boundary. See the Threat model.

Async hook results are time-boxed, and a late onInit or onInput result can still apply. Tool hooks owns the budgets, the late-result rule and how export hooks fail. afterExport, the cleanup guarantee, is always awaited and its errors are only logged. onFrame and onLevel run once per frame or level sample and are not time-boxed; the runtime drops a sample if the previous one is still rendering.