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.
In the Chart tool, the hook parses the pasted table, runs the layout and hands the template a finished list of shapes. The template only prints the shapes.
signed by Lollyvector SVG54 paths378 nodes39 groups43 KBCheck it yourselfدستخط شدہ فائل حاصل کریں
signed by Lollyvector SVG54 paths378 nodes39 groups43 KBCheck it yourselfدستخط شدہ فائل حاصل کریںTry it in the app
How a hook works
A hook is a top-level function with a known name, such as onInit or onInput. Lolly calls each hook at a set 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. 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. Each budget below is how long the runtime waits for a hook's promise:
- 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 poses the tool att0 and freezes its loop before this hook runs. A raster calls the clock after this hook (the frame clock). - The tool makes the file itself:
exportStillorexportFile, 10 seconds.exportStillmakes 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 visibly. afterExport runs even when the render fails. 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. See Live input.
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. The optional ctx.view (engine v1.255) has 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. The tool redraws in place. The shell calls runtime.setTokenSelection(). The runtime resolves every input linked to the design system again and runs onInput for each one whose colour moved. Then the runtime 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 '__tokens' run's patch 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 hook work. 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 them 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 the new choice, the runtime sends 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, such as a 1080 x 1920 story, an A4 page or a 3:1 banner. Engine v1.293 passes that size to every hook as ctx.canvasSize, a { width, height } in CSS pixels at 96 per inch. An A4 page arrives as 793.7 x 1122.5. When nobody asked for a size, the size is the manifest's render.width x render.height. The web app reads the size 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. 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 canvas 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. The size never reaches the saved inputs, undo, links or collaboration. A tool without the key renders as before: the runtime records the size for the tool's next ordinary run, 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 and also ctx.opts.width and ctx.opts.height, the export's own size. The two 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 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 stay empty, and the tool then picks the colour. Certificate's Ink follows the design system's text colour, and Timezone's Text override follows the theme. In the web app's sidebar an empty colour input shows a neutral pattern and the word Automatic, and its picker offers a 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. Work it 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. The field then 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 to react to a live camera. The shell shows a Go live toggle wherever a camera is available (host.media). The runtime calls onFrame once per frame with { frame, model, host }. frame is { width, height, data, t }, and data is RGBA pixels. Return a patch, as from onInput.
onFrame is never called where there is no camera. There, the tool 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 pattern wraps the pixels in a canvas and reuses the still pipeline:
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 onFrame cheap. It 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. The SVG-filter duotone hands the frame back as a data-URL image. Live camera lists the render keys that tune the camera.
Recording tools (render.capture + onLevel)
Set render.capture to give the tool a record button. The button captures the person's microphone, camera or screen to a file, as the audio and video counterpart of the file transform path. There are 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. The browser's own picker chooses the screen, window or tab, so the tool never sees a target it was not given.
Recording asks for a device permission, so, unlike the live camera, recording 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 the hook once per audio-level sample from the meter, before recording and during the take. As with onFrame, overlapping samples are dropped and the hook 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's.
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. Name an audio or video input and a text input, and the shell mounts speech-to-text: consent for the one-time on-device model download, a background job with progress and cancel in its notice 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.
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, not capability-gated. A shell without on-device speech, such as the headless CLI, mounts nothing and leaves the target input with the value from the link or saved session. Pair the declaration with a template.srt or template.vtt (Data formats) to export the cues as a separate file.
Network access (host.net)
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). A live-data tool, such as weather, status, a news ticker or a calendar feed, opts in with two manifest declarations: the capability and a 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. List only the endpoints you call.
- Closed when unsure, everywhere. No
networkblock, or a URL no entry matches, makes everyhost.net.fetchreject. This is true 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.
- Stay away from
window,document,fetchandlocalStorage. Hooks are loaded withnew Functionandhostinjected as closure scope, so in a browser shell those globals are 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 browser-only exception. The Threat Model explains that this injection is a portability rule, not a security sandbox. - 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 hooks run in the page. 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 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)
New host.* APIs arrive in minor engine versions, are never removed and are optional, so an older shell may not have them. 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. The engine then refuses the tool clearly instead of failing on a missing method. Recent additions:
host.images- decode, resize and re-encode images on the device. Read the result'smime,widthandheightinstead of assuming the request was honoured.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, in thecommunityfolder and not listed on lolly.tools) 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, and the tool stops responding with no message. That is why host.geom returns { ok: false, code, message } instead of throwing.