Lolly
Запустити застосунок

АвтоматизаціяСтворення інструментів і дизайн-систем

Tool hooks and host capabilities

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.

A treemap from the Chart tool - nested rectangles sized and placed by a hook, with the template only printing the shapes it was handed signed by Lollyvector SVG54 paths378 nodes39 groups43 KBCheck it yourselfОтримати підписаний файлA treemap from the Chart tool - nested rectangles sized and placed by a hook, with the template only printing the shapes it was handed signed by Lollyvector SVG54 paths378 nodes39 groups43 KBCheck it yourselfОтримати підписаний файлTry 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:

// 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's id and value.
  • 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 declares stillPose, an SVG, PDF or other still that reads the page has already posed the tool at t 0 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: exportStill or exportFile, 10 seconds. exportStill owns a raster still the 8-bit page render cannot make, such as a 16-bit or HDR PNG, OpenEXR or Radiance; it receives opts with depth, HDR, size and DPI, and returns { bytes, mime }, or null to let the normal path draw that format. exportFile is 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, are not time-boxed and drop a sample while the previous one is still rendering. They are under Live input below.

What every hook receives

FieldWhat it holds
modelThe input model: every declared input with its current value.
hostThe host bridge.
langThe language the tool is rendering in, such as de; en when none is set.
viewLocal presentation choices, when the shell sets any (below).
canvasSizeThe 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).
progressiveonInit 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. Return a computed colour under a name of its own, never 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. 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.

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. Do not add camera to capabilities, which 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:

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: 0 is 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" }
}

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:

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..

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. Three recent additions tools reach for:

The pattern for any of them is to check, try and render something sensible either way. 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.