Most tools need no code: the template prints what people type. Add a hooks.js when the picture depends on a calculation the template cannot do, such as laying out a chart from a pasted table, encoding a QR code or reacting to a camera.
The Chart tool is a typical case. Its hook parses the pasted table, runs the layout and hands the template a finished list of shapes; the template only prints them.
signed by Lollyvector SVG54 paths378 nodes39 groups43 KBCheck it yourselfStáhni podepsaný soubor
signed by Lollyvector SVG54 paths378 nodes39 groups43 KBCheck it yourselfStáhni podepsaný souborTry it in the app
How a hook works
A hook is a plain top-level function with a known name, such as onInit or onInput. Lolly calls each one at a known moment, passes it the current inputs and a host object and merges what it returns into the render:
- A key that matches a declared input
idchanges that input's value. - Any other key becomes a computed value, an extra, that the template prints like an input.
// Top-level functions are picked up by name. Declare the ones you need.
function onInit({ model, host }) {
// Runs once when the tool opens. Return a patch to seed computed values.
return { computedThing: derive(model) };
}
function onInput({ id, value, model, host }) {
// Runs after every input change. Return a patch, or nothing.
return { computedThing: derive(model) };
}Flag each hook you define in the manifest's hooks object ({ "onInit": true }). A manifest with no hooks object never loads hooks.js at all, and validation and the shell read the flags, for example to wire the download for exportFile.
Hooks behave the same in the web app, the desktop apps and the command line when they use only host.*. Host API lists everything host offers.
When each hook runs
Async results are time-boxed. The budget in each step below is how long the runtime waits for a hook's promise before it moves on:
- The tool opens:
onInit, 5 seconds. Runs once and seeds computed values. - Each edit:
onInput, 2 seconds. Runs after every input change, with the changed input'sidandvalue. - An export starts:
beforeExport, 5 seconds. Adjust the node or call host APIs before the file is drawn. Receives{ node, format, opts, host }. If your template's frame clock declaresstillPose, an SVG, PDF or other still that reads the page has already posed the tool att0 and frozen its loop when this hook runs; a raster calls the clock after this hook (the frame clock). - The tool makes the file itself:
exportStillorexportFile, 10 seconds.exportStillowns a raster still the 8-bit page render cannot make, such as a 16-bit or HDR PNG, OpenEXR or Radiance; it receivesoptswith depth, HDR, size and DPI, and returns{ bytes, mime }, ornullto let the normal path draw that format.exportFileis the transform path for on-device utilities (Assets and file utilities). - The export ends:
afterExport, 5 seconds. Runs after the file is made, for cleanup and chaining. Receives{ node, format, blob, host }.
When a hook overruns, the runtime applies nothing at first, but the hook keeps running. A late onInit or onInput result still applies when it arrives, unless a newer onInit or onInput run has started since. Export hooks never apply late: a beforeExport, exportFile or exportStill overrun or error fails that export where people can see the failure. afterExport runs even when the render fails, so cleanup always happens; its overruns and errors are only logged. Errors in onInit and onInput are logged, never fatal. A synchronous overrun cannot be interrupted in the page, so it is measured and logged as a warning; in a Worker, an overrunning hook is stopped.
onFrame and onLevel run once per camera frame or audio sample and are not time-boxed. They are under Live input below.
What every hook receives
| Field | What it holds |
|---|---|
model | The input model: every declared input with its current value. |
host | The host bridge. |
lang | The language the tool is rendering in, such as de; en when none is set. |
view | Local presentation choices, when the shell sets any (below). |
canvasSize | The size the tool is being made at, { width, height } in CSS pixels (engine v1.293, below). |
report(patch, { ready }) | onInit and onInput only: publish an intermediate patch before the hook finishes. A report is ignored once a newer run has started. In onInit, { ready: true } tells a view that shows partial renders that the document can be shown as it stands (engine v1.228). |
progressive | onInit only: true when a view is showing reported patches as they arrive, so a partial render is worth sending. |
onInput also gets id and value, the input that changed. Four reserved ids mark runs the runtime starts itself: '__view' (a view change, below), '__tokens' (a theme or colourway change, below), '__canvasSize' (a change of canvas size, below) and '__emoji', which runs when the emoji set changes for a tool that drew emoji itself through host.emoji.renderSvg, host.emoji.renderText or host.text.layoutRuns.
Reacting to the view and the design system
View changes. Engine v1.255 adds an optional ctx.view for local presentation choices. Lolly Design uses ctx.view.pageId to render the page the viewer chose while ctx.model keeps the whole document. A shell can call runtime.setViewState() to refresh that view through onInput with id: '__view'; the patch from this run can update computed extras but cannot write declared inputs. View state stays out of saved sessions, links, undo and collaboration. A one-shot document render leaves pageId absent and renders every page.
When the theme or colourway changes
A person can switch a mounted tool to another theme or colourway from the sidebar's Design system section or Lolly Design's inspector, and the tool redraws in place. The shell calls runtime.setTokenSelection(). The runtime resolves every input linked to the design system again, runs onInput for each one whose colour moved, then runs onInput once more with id: '__tokens', whether or not the tool links anything. onInit does not run again, because that would reset the person's inputs. As with '__view', the patch from the '__tokens' run can update computed extras but cannot write declared inputs.
Colours that reach the template through a linked input or a var(--brand-*) variable follow the switch with no work from the hook. A hook that read colours from host.tokens and kept them, such as a palette, a paper colour or a set of treatment seeds, drops what it kept when id is '__tokens' and reads again:
var palette = null; // read once, because onInput runs on every keystroke
async function onInput({ id, model, host }) {
if (id === '__tokens') palette = null; // a theme or colourway switch: read again
palette = palette || await readPalette(host);
return draw(model, palette);
}An isolated hook sees the new choice too: before any hook runs under it, the runtime hands the Worker a fresh copy of the design system through the executor's tokensChanged. tests/tool-theme-switch.test.ts mounts every community tool, switches it live and checks that the render matches a fresh mount in the new choice.
Never return a colour under the id of a declared colour input. Writing that id replaces the input's design-system link with a fixed colour, and the next switch leaves the colour behind.
When the canvas size changes
People choose the size of what they make: a 1080 x 1920 story, an A4 page, a 3:1 banner. Engine v1.293 tells every hook that size as ctx.canvasSize, a { width, height } in CSS pixels at 96 per inch, so an A4 page arrives as 793.7 x 1122.5. When nobody asked for a size it is the manifest's render.width x render.height. The web app reads it from the export size fields, the CLI from --width, --height and --unit, the TUI from its Export panel and the MCP server from the request, and each converts with the engine's canvasSizeOf, so every shell hands a tool the same numbers for the same request. Templates read the same size as {{@canvasSize.width}} and {{@canvasSize.height}} (Templates and rendering).
A tool whose layout follows the shape declares "render": { "followsCanvasSize": true }. When the size changes, the runtime runs onInput with id: '__canvasSize', then repaints, so the live canvas shows the layout the export writes. As with '__view' and '__tokens', the patch from that run can update computed extras but cannot write declared inputs, so the size never reaches the saved inputs, undo, links or collaboration. A tool without the key keeps rendering exactly as before: the runtime records the size for the next run the tool gets for its own reasons, and nothing re-runs or repaints. Declaring the key needs "engineVersion": "^1.293.0".
function layout(model, size) {
// size is absent on an engine older than 1.293: fall back to the manifest's size.
var w = size ? size.width : 1280, h = size ? size.height : 720;
return { cols: w >= h ? 4 : 2, frameW: w, frameH: h };
}
function onInit({ model, canvasSize }) { return layout(model, canvasSize); }
// Every edit, and '__canvasSize' when the size changes, lays out again.
function onInput({ model, canvasSize }) { return layout(model, canvasSize); }Do not declare hidden width and height inputs to get the size. The web shell writes into inputs with those ids, but the size then travels in links and undo, and the CLI warns that --width and --height shadow them. The export hooks see ctx.canvasSize too, beside ctx.opts.width and ctx.opts.height, the export's own size, which can differ: a batch row or a caller can ask for a size the canvas was never set to. Lolly Logo Wall is the reference tool: it lays the wall out for the canvas's shape and lays it out again in beforeExport only when the export's shape differs.
Showing what an empty colour input draws
A colour input whose default is empty can be left empty, and the tool then picks the colour itself: Certificate's Ink follows the design system's text colour, Timezone's Text override follows the theme. In the web app's sidebar an empty colour input shows as automatic, with a neutral pattern and the word Automatic, and its picker offers the way back to empty. A hook can say which colour the tool draws there by returning autoColors, keyed by input id:
return {
inkColor: ink, // what the template uses
autoColors: {
color: { value: inkWithoutOverride, source: 'design-system' },
background: { value: themeBackground }, // no source: the tool's own rule
},
};value is the colour the tool draws while that input is empty, worked out as if the input were empty even when the person has set a colour, so the picker's "Follow the design system" choice shows the colour the input returns to. source: 'design-system' makes the field read "Design system" and announce "Ink: follows the design system (Liquorice)"; without the key the field reads "Automatic". Leave value out when the template decides the colour later, as Lolly Chart's palette slots do, and the field keeps the neutral pattern. autoColors is an ordinary extra: the template never needs to read the value, and other shells ignore the key. Lolly Certificate is the reference tool.
Live input
Motion-reactive tools (onFrame)
Declare an onFrame hook and your tool can react to a live camera. The shell shows a Go live toggle wherever a camera is available (host.media), and the runtime calls onFrame once per frame with { frame, model, host }, where frame is { width, height, data, t } and data is RGBA pixels. Return a patch, as from onInput.
This is pure progressive enhancement: onFrame is never called where there is no camera, so the tool still works as an ordinary still-image tool.
camera for onFrameAdding camera to capabilities would require a camera and hide the tool where there is none.
The usual move is to wrap the pixels in a canvas the still pipeline already understands and reuse it:
function onFrame({ frame, model }) {
const c = document.createElement('canvas');
c.width = frame.width; c.height = frame.height;
c.getContext('2d').putImageData(new ImageData(frame.data, frame.width, frame.height), 0, 0);
return { svgContent: build(c, inputsFrom(model)) }; // same builder as onInit/onInput
}Keep it cheap: onFrame is not time-boxed, but the runtime drops a frame while the previous one is still rendering, so an expensive render only lowers the frame rate. The filter tool's effects are the reference (halftone, scanline, posterise and duotone). Pixel tracers wrap the frame as above, while the SVG-filter duotone hands the frame back as a data-URL image. The render keys that tune the camera are under Live camera.
Recording tools (render.capture + onLevel)
Set render.capture and the tool gets a record button that captures the person's microphone, camera or screen to a file, the audio and video counterpart to the file transform path. Four modes:
"audio"- microphone only, for a voice recorder. Also shows a live input-level meter when the tool declares anonLevelhook."video"- camera only, silent, with no microphone track."av"- camera and microphone, for a talking-head recorder. Use it rather than"video"when the clip needs sound. The shell also mounts a coaching display for audio level and background noise."screen"- display capture (engine v1.54). The shell mounts a Screenshot and Record pair, and the browser's own picker chooses the screen, window or tab, so the tool never sees a target it was not handed.
Recording asks for a device permission, so, unlike the live camera, it is a gated capability: declare microphone for audio, camera for video, both for av and screen for screen. The tool is then unavailable on shells that cannot record; the headless CLI provides no host.recorder. The recorded bytes reach the person through the transform path (host.export.file, never watermarked) or become a template asset that a compositing tool wraps.
"render": { "width": 1080, "height": 1080, "formats": ["png", "svg"], "capture": "audio", "actions": ["download", "save"] },
"capabilities": ["microphone"],
"hooks": { "onInit": true, "onLevel": true }The onLevel hook is a live level meter and sound check. The runtime calls it once per audio-level sample, from the meter before recording and again during the take, the same way onFrame handles camera frames: overlapping samples are dropped, and it is not time-boxed. It returns a patch, like onInput:
function onLevel({ level, model, host }) {
// `level` is an AudioLevel. Return a patch the template renders.
return { barPct: Math.round(Math.min(1, level.rms / 0.5) * 100), tooHot: level.clipping };
}The fields of an AudioLevel
rms- loudness from 0 to 1, the value a level bar follows.peak- the instantaneous peak, from 0 to 1.dbfs- the peak in decibels:0is clipping and−∞is silence.clipping- true while the peak sits at the "too hot" threshold, about 0.99.t- the sample's time.
Engine v1.19 adds four optional background-noise cues. Check for them first, because a shell that does not compute spectral levels leaves them undefined:
noiseFloor- the level in the quiet gaps, in dBFS.snr- signal to noise in dB; about 15 dB or less means a noisy room.hum- from 0 to 1, the share of energy in the mains bands, a sign of electrical hum or a ground loop.hiss- from 0 to 1, the spectral flatness, a sign of broadband fan or air-conditioning hiss.
The noise cues are trustworthy only from the raw meter: the sound check runs the microphone with noise suppression and automatic gain off. A recording session turns them on for a clean file, so its noise floor reads lower than the room really is.
voice-recorder (capture: "audio" with onLevel coaching), record (capture: "av") and screencap (capture: "screen", declaring screen and microphone) are the reference tools. The host.recorder bridge, with meter and record, is on Host API.
Transcribing audio (render.transcribe)
Engine v1.150. Point at an audio or video input and a text input, and the shell mounts the whole speech-to-text feature for you: consent for the one-time on-device model download, a background job whose notice shows progress and offers cancel and one undoable write into the target input.
"render": {
"width": 1920, "height": 1080, "formats": ["png", "srt"],
"transcribe": { "source": "clip", "target": "captions", "format": "srt", "auto": "autoCaption" }
}source- the id of theassetinput holding the clip. While it is empty the button is disabled and says why.target- the id of thelongtextortextinput the result is written into. One write, so one undo.format-"srt"(the default) or"vtt"for numbered subtitle cue blocks or"words"for the plain spoken text, one cue per line with no timestamps.auto- the optional id of abooleaninput. While it is on, a freshly recorded or picked clip is processed with no click. The consent sheet still appears the first time the model is not on the device.
Everything runs locally: the clip is decoded and read on the device, and nothing is uploaded. A clip with no speech writes an empty value and shows a note in the interface, never invented text. The declaration is feature-detected rather than capability-gated, so a shell without on-device speech, such as the headless CLI, mounts nothing and leaves the target input with the value the link or saved session gave. Pair it with a template.srt or template.vtt (Data formats) to export the cues as a separate file.
Network access (host.net)
Tools work offline first. By default a tool gets no host.net, so it has no supported way to reach the network. That is a contract checked in review, not isolation: Portability and isolation explains why. A live-data tool, such as weather, status, a news ticker or a calendar feed, opts in with two manifest declarations: the capability, and an explicit list of what it may fetch.
"capabilities": ["network"],
"network": {
"allowlist": [
"https://api.example.com/*",
"https://example.com/status.json"
]
}The allowlist rules:
httpsonly. Entries are full URLs; plainhttpnever validates.- A bare entry allows exactly that URL, including its query string.
- *A trailing
/makes an entry a prefix*:https://api.example.com/allows everything under that path. The wildcard must follow a path separator (/, never a bare), so a prefix cannot spill into a lookalike host:https://api.example.com*would also matchhttps://api.example.com.evil.io/. - 1 to 32 entries. Small on purpose: list the endpoints you call.
- Closed when unsure, everywhere. No
networkblock, or a URL no entry matches, means everyhost.net.fetchrejects, the same way in the web shell, off-screen batch and gallery renders, the CLI and the TUI. The host applies the allowlist per mounted tool, and nothing a hook does can widen the list. Response bodies are capped at 64 MB, so a wrong or compromised endpoint cannot stream unbounded bytes into memory.
In a hook, host.net.fetch is an ordinary fetch behind that gate:
async function onInit({ model, host }) {
try {
const res = await host.net.fetch('https://api.example.com/v1/status');
if (!res.ok) return { statusText: 'unavailable' };
return { statusText: (await res.json()).status };
} catch {
return { statusText: 'offline' }; // the tool must still mount without a network
}
}Keep fetches inside the hook budgets above, return extras the template can print as they are and always render something sensible when the fetch fails. A network tool that renders blank offline is a bug.
Portability and isolation
host. is the only surface every shell guarantees, so build on host..
- Stay away from
window,document,fetchandlocalStorage. Hooks are loaded withnew Functionandhostinjected as closure scope, so in a browser shell those globals are technically reachable. Using them ties your tool to browser shells, breaks headless rendering in the CLI and rules out strict Worker execution. TheonFramecanvas pattern above is a deliberate browser-only exception. That this injection is a portability rule and not a security sandbox is set out in the Threat Model. - No module imports. Hooks are loaded as one source string, so
importdoes not work.
Run hooks in a Worker (isolate)
A built-in tool can set isolate: true in its manifest (engine v1.105 and later) to ask the web shell to run its hooks in a Web Worker while the tool is open for editing. The executor keeps colour, geometry and design-token calls inside the Worker and forwards the other host.* calls to the shell. If a Worker cannot start, the shell runs the hooks in the page instead. The CLI runs hooks in a worker thread only when LOLLY_HOOK_WORKER=1 is set.
Do not set the flag by hand. node scripts/tool-isolation.ts --verify --write sets it only when both checks pass: the hooks use none of the page-only globals a Worker lacks (document, window, Image and the like), and lolly smoke renders the tool byte for byte the same in the page and in a worker thread. A tool that later gains a page dependency fails --verify and loses the flag the same way.
The flag is a request. A sideloaded or remote tool always runs its hooks in strict isolation, whatever its manifest says, and refuses to run when isolation is unavailable.
Shared helper regions (community/_shared/)
hooks.js must stay self-contained, because tools are data and cannot import or require. Helpers that several tools need, such as the filter overlay block, canRaster, loadImage, esc, clamp and safeColor, are kept once in community/_shared/*.js and copied byte for byte into each tool that uses them, between marker comments:
// === lolly:shared clamp - generated from community/_shared/math.js; edit there and run pnpm run sync:shared ===
function clamp(v, a, b) { return v < a ? a : (v > b ? b : v); }
// === /lolly:shared clamp ===Never edit inside the markers. Edit the shared file and run pnpm run sync:shared; pnpm run validate:catalog fails on any drift. community/_shared/README.md has the details.
Newer optional host APIs (feature-detect)
The bridge grows by addition: new host.* APIs arrive in minor engine versions, are never removed and are optional, so an older shell may not have them yet. Check for an API, and keep the tool working when the API is missing. If your tool cannot work without one, list it in requires (Tool manifests) or raise the manifest's engineVersion floor, so the engine refuses the tool clearly instead of a method being missing. Recent additions that tools reach for include these:
host.images- decode, resize and re-encode images on the device. Read the result'smime,widthandheightrather than assuming the request was honoured exactly.host.geom- exact vector geometry on SVG path strings: booleans, offset, stroke, simplify and measurement. Failures are returned, never thrown.host.text.fontUrl- resolve a font family the host knows to a file forhost.text.toPath(), with thevariationsa variable face needs. It resolvesnullwhen no file is found, so keep your<text>fallback.host.calc- work out spreadsheet formulas on the device, withevaluate,tableandfunctions. Sales Quote (quote) is the reference tool.host.audio.loudnessandhost.audio.align- EBU R128 loudness of a clip, and the offset between two recordings of one event. Both are optional members ofhost.audio, so check for each one.
For example, with host.geom:
function onInput({ model, host }) {
if (!host.geom) return {}; // older shell: leave the path alone
const values = Object.fromEntries(model.map(i => [i.id, i.value]));
const cut = host.geom.difference([values.shape, values.hole]);
if (!cut.ok) return { pathError: cut.code }; // never silently wrong
const outline = host.geom.stroke(cut.d, 4, { cap: 'round', join: 'round' });
return { shapePath: cut.d, outlinePath: outline.ok ? outline.d : '' };
}A throw out of a hook is only logged and discarded, leaving the tool silently unresponsive, which is why host.geom returns { ok: false, code, message } instead of throwing.