This reference describes the currently implemented JavaScript runtime in this repository, not the broader brainstorm API from the early LOUPE-005 design docs. The important distinction is that the real runtime is intentionally narrow: it exposes retained pages, reactive state, and animation helpers above the Go-owned renderer and writer stack, and it does not expose raw framebuffer or transport operations.

This matters because the Loupedeck transport is fragile enough that letting scripts own low-level I/O would recreate the exact architecture problems the Go refactor was built to remove. Treat this page as the source of truth for what JavaScript can do today.

Runtime model in one page

The current JS layer runs inside a goja VM that is owned by an explicit runtime-owner abstraction. Hardware events, animation callbacks, and reactive closures are all serialized back onto that owner thread before they execute JavaScript.

At a high level:

script
-> goja runtime
-> loupedeck/state, loupedeck/ui, loupedeck/gfx, loupedeck/anim, loupedeck/easing
-> pure-Go reactive runtime + retained UI + host runtime + animation runtime
-> retained tile renderer
-> Go display/writer/transport stack
-> hardware

The practical consequence is simple: mutate state and retained UI from JavaScript, and let Go own everything below that boundary.

Two rendering paths

Scripts can render content in two fundamentally different ways. Understanding the distinction is critical for writing performant scenes.

Retained tile path (recommended for most scenes)

You declare what to show — tile.text("HELLO"), tile.icon("circle") — and Go decides how and when to render it. When a tile property changes, only that tile is re-rendered and sent to the hardware (90×90 pixels ≈ 32KB per tile). This is the fastest path for per-tile updates.

Surface path (for custom pixel content)

You create a gfx.surface(width, height), draw pixels into it from JavaScript, and assign it to a display or tile. When the surface changes, the display or tile it belongs to is re-rendered. You can assign surfaces at two levels:

• Display-level surface: display.surface(fullDisplaySurface) — the entire display (360×270 for main) is re-rendered when any pixel changes. Use this for full-display effects that span tile boundaries (ripples, scanlines, cross-tile animations).
• Per-tile surface: tile.surface(tileSurface) — only that tile is re-rendered when its surface changes (90×90). Use this for independent tile content (clocks, meters, status indicators).

Performance rule of thumb: If each tile's content is independent, use per-tile surfaces. If content spans tile boundaries, use a display-level surface. Per-tile surfaces send 12× less data per update on the main display.

Module overview

loupedeck/state

The state module is the reactive core exposed to JavaScript. Use it whenever values should drive text, visibility, animation targets, or event-driven updates. The module is intentionally tiny because the real value comes from how it plugs into retained UI bindings.

state.signal(initial)

Creates a mutable signal and returns an object with get(), set(value), and update(fn).

const state = require("loupedeck/state");

const count = state.signal(0);

count.get();          // 0
count.set(1);         // count is now 1
count.update(v => v + 1);  // count is now 2

Why you use it:

• to hold the source-of-truth value for the current page
• to let multiple tile bindings read the same state
• to provide an animation target via get() and set()

signal.get()

Returns the current exported JS value.

const value = count.get();

If you call get() inside a reactive binding such as tile.text(() => ...), the underlying Go reactive runtime tracks that dependency so later mutations re-run the binding.

signal.set(value)

Sets a new value immediately.

count.set(42);

If the new value is equal to the old one under the default equality check, the reactive runtime does not mark dependents dirty.

signal.update(fn)

Reads the current value, calls your JS updater on the owner thread, and stores the returned value.

count.update(v => v + 1);

Use update(...) when the next value depends on the current one. This avoids duplicating get() / set() logic in JavaScript and keeps the mutation shape clear.

state.computed(fn)

Creates a derived value and returns an object with get().

const double = state.computed(() => count.get() * 2);
double.get();

Use computed(...) when you want one place to encode derived logic that several bindings can read. The current implementation keeps the surface minimal: there is no setter and no custom equality hook in JS.

state.batch(fn)

Runs a group of state mutations as one reactive batch.

state.batch(() => {
  left.set(10);
  right.set(20);
});

Why it matters:

• it reduces intermediate reactive churn
• it makes multi-value updates feel atomic at the UI layer
• it keeps related mutations grouped conceptually

state.watch(fn)

Registers an eager watcher and returns an object with stop().

const sub = state.watch(() => {
  console.log(count.get());
});

sub.stop();

The function runs through the owner-thread bridge, just like other deferred JS callbacks. Use watch(...) when you want a side effect that follows reactive changes. Do not use it as your primary rendering API; tile bindings are the better fit for UI updates.

loupedeck/ui

The UI module is the retained UI surface. It lets scripts declare named pages, add tiles to those pages, bind tile properties to reactive values, and listen to hardware events.

ui.page(name, fn)

Creates or reuses a named page and optionally passes a page object to a configuration callback.

const ui = require("loupedeck/ui");

ui.page("home", page => {
  page.tile(0, 0, tile => {
    tile.text("HELLO");
  });
});

The current runtime targets the 4×3 main display tile grid. Tile coordinates are zero-based: column 0–3, row 0–2.

page.tile(col, row, fn)

Creates or reuses a tile on the page and optionally configures it.

page.tile(1, 2, tile => {
  tile.text("BOTTOM");
});

The tile callback receives a tile object with the methods documented below.

page.display(name, fn)

Creates or reuses a display on the page and optionally configures it. Display names are "left", "main", and "right".

ui.page("scene", page => {
  page.display("left", display => {
    display.text("VU");
  });
  page.display("main", display => {
    display.surface(mainSurface);
  });
  page.display("right", display => {
    display.text("INFO");
  });
});

tile.text(valueOrFn, opts?)

Sets static text or binds text to a reactive closure. An optional second argument provides rendering options.

Static:

tile.text("READY");

Reactive:

tile.text(() => `COUNT ${count.get()}`);

With wrapping (text wraps to tile width with 4px padding):

tile.text("Very long label text", { wrap: true });

Text options:

Newline support: Text containing \n is rendered as multiple lines. Each line is vertically offset by the font's line height. This works for both retained tiles and surface.text().

Word wrapping: When wrap: true is set, long text is automatically word-wrapped to fit within the tile (82px with 4px padding). This is useful for labels that may be too long to fit on a single line.

Use the reactive form when the tile should update automatically after signal changes. The closure executes on the owner thread and its signal dependencies are tracked by the Go reactive runtime. When the signal changes, the tile is marked dirty individually — only that 90×90 tile is re-rendered and sent to hardware.

tile.icon(valueOrFn)

Sets or binds the tile icon string.

tile.icon("circle");
tile.icon(() => mode.get() === "armed" ? "record" : "stop");

Important current limitation: the JS renderer does not yet map icon names to the SVG asset pipeline. The retained renderer currently displays the icon string as centered placeholder text. This is still useful for structure and testing, but it is not yet the final asset story.

tile.visible(boolOrFn)

Sets static visibility or binds visibility to a reactive boolean closure.

tile.visible(true);

tile.visible(() => count.get() > 0);

If a tile is invisible, the retained renderer currently clears it to the themed background instead of drawing accent/text content.

tile.surface(surfaceOrNull)

Sets a per-tile pixel surface, or clears it by passing null/undefined. When a tile has a surface, the renderer draws the surface content instead of the retained text/icon layout. When the surface changes, only that tile is re-rendered.

const gfx = require("loupedeck/gfx");
const ui = require("loupedeck/ui");

const tileSurface = gfx.surface(90, 90);

ui.page("clock", page => {
  page.tile(0, 0, tile => {
    tile.surface(tileSurface);
  });
});

// Draw into the surface — only tile (0,0) is re-rendered
tileSurface.clear(0);
tileSurface.text("12:34", { x: 0, y: 20, width: 90, height: 20, center: true });

Why this matters: A per-tile surface gives you custom pixel content (charts, meters, patterns, custom fonts) while retaining per-tile invalidation. When the surface changes, the Go runtime marks only that tile dirty, and the renderer sends only 90×90 pixels (≈ 32KB) instead of the full display (≈ 389KB). This is 12× less data per update on the main display.

When to use per-tile vs. display-level surfaces:

Pass null or undefined to remove a surface and revert to the retained text/icon rendering:

tile.surface(null);

tile.draw(fn)

Convenience method that auto-creates a per-tile surface (90×90) if one doesn't already exist, passes it to fn for drawing, and marks the tile dirty. This is a shorthand for the gfx.surface() + tile.surface() pattern.

const ui = require("loupedeck/ui");

ui.page("demo", page => {
  page.tile(0, 0, tile => {
    tile.draw(s => {
      s.clear(0);
      s.fillRect(0, 0, 90, 8, 100);  // accent bar
      s.text("HELLO", { x: 0, y: 30, width: 90, height: 20, center: true });
    });
  });
});

If the tile already has a surface (set via tile.surface() or a previous tile.draw()), draw() reuses it. The surface is passed as the first argument to fn.

When to use:

• tile.text() for simple text labels (fastest, retained rendering)
• tile.draw() for custom pixel content within a single tile (per-tile invalidation)
• tile.surface() when you need a shared surface reference across multiple tiles or for animation updates

tile.invalidate()

Explicitly marks the tile as dirty, causing it to be re-rendered on the next flush. This is useful when you have modified the tile's surface via a stored reference outside of a reactive binding.

const tileSurface = gfx.surface(90, 90);
ui.page("demo", page => {
  page.tile(0, 0, tile => {
    tile.surface(tileSurface);
  });
});

// Later, modify the surface and invalidate
tileSurface.clear(0);
tileSurface.text("UPDATED", { x: 0, y: 30, width: 90, height: 20, center: true });
// Surface.OnChange auto-marks the tile dirty, so invalidate() is not needed here.
// But if you're bypassing the surface's change notification, use:
// tile.invalidate();

Note: In most cases you don't need tile.invalidate() because surface mutations automatically trigger the tile's dirty flag via the OnChange listener. Use invalidate() only when you need to force a re-render for reasons outside the normal change notification flow.

Display objects

Display objects represent the three physical screen areas: left (60×270), main (360×270), and right (60×270). The main display contains the 4×3 tile grid.

display.text(valueOrFn)

Sets or binds display-level text. Shown as centered text on the display.

display.text("STATUS");
display.text(() => mode.get());

display.icon(valueOrFn)

Sets or binds the display icon string. Same placeholder limitation as tile.icon().

display.visible(boolOrFn)

Sets or binds display visibility.

display.surface(surfaceOrNull)

Sets a display-level pixel surface. When set, the renderer draws the surface content instead of the retained text/icon layout. When any pixel in the surface changes, the entire display is re-rendered — so use this for full-display content, not per-tile content.

const gfx = require("loupedeck/gfx");

const mainSurface = gfx.surface(360, 270);

ui.page("full", page => {
  page.display("main", display => {
    display.surface(mainSurface);
  });
});

display.layer(name, surfaceOrNull, opts?)

Adds or removes a named compositing layer on the display. Layers are drawn on top of the base surface in the order they were added. Each layer can have a foreground tint.

const base = gfx.surface(360, 270);
const overlay = gfx.surface(360, 270);

display.surface(base);
display.layer("fx", overlay);

// Tint the layer red
display.layer("accent", redOverlay, { r: 255, g: 0, b: 0, a: 255 });

Layers are useful for compositing effects on top of a base surface — for example, a background animation layer with a static content layer on top.

display.tile(col, row, fn)

Creates or reuses a tile on the main display. Same as page.tile() but called on the display object directly. Only available on the "main" display.

ui.show(name)

Makes the named page active.

ui.show("home");

This is the call that turns your retained page into something the renderer can actually flush. If you forget it, the script may build pages successfully but nothing becomes visible on the hardware.

ui.invalidate(reason)

Marks the current frame as needing re-render. Use this when you need to trigger a redraw from outside of reactive state changes.

const present = require("loupedeck/present");
present.invalidate("manual-update");

The reason string is passed through to the present runtime for debugging and metrics, but does not affect which regions are re-rendered — that is determined by the dirty tile/display tracking in the UI layer.

ui.onButton(name, fn)

Registers a button handler and returns a subscription object with close().

const sub = ui.onButton("Button1", event => {
  console.log(event.name, event.status);
});

sub.close();

Event object fields:

Supported button names:

• Circle
• Button1 through Button7

ui.onTouch(name, fn)

Registers a touch-region handler and returns a subscription object with close().

ui.onTouch("Touch6", event => {
  console.log(event.name, event.x, event.y);
});

Event object fields:

Supported touch names: Touch1 through Touch12

ui.onKnob(name, fn)

Registers a knob handler and returns a subscription object with close().

ui.onKnob("Knob1", event => {
  level.update(v => Math.max(0, Math.min(100, v + event.value)));
});

Event object fields:

Supported knob names: Knob1 through Knob6

Subscription objects

ui.onButton(...), ui.onTouch(...), and ui.onKnob(...) return a small subscription object:

const sub = ui.onButton("Button1", () => {
  // ...
});

sub.close();

Use close() when a script installs a temporary handler that should not live for the entire process.

loupedeck/gfx

The graphics module provides pixel surfaces for custom drawing and text rendering. Surfaces are grayscale (8-bit per pixel, 0–255). The renderer converts them to themed RGBA at flush time.

gfx.surface(width, height)

Creates a new pixel surface and returns a surface object with the drawing methods documented below.

const gfx = require("loupedeck/gfx");

const s = gfx.surface(90, 90);

Typical sizes:

gfx.font(path, opts)

Loads an OpenType font and returns a font object. The font can be passed to surface.text() for custom rendering.

const font = gfx.font("/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", {
  size: 14,
  dpi: 72,
  index: 0,  // font index within a .ttc collection
});

Options:

Fonts are cached by path+options, so calling gfx.font() with the same arguments returns the same Go object.

Surface drawing methods

surface.width / surface.height

Returns the surface dimensions.

surface.width;   // 90
surface.height;  // 90

surface.clear(v)

Fills every pixel with the given value (0–255).

surface.clear(0);    // all black
surface.clear(255);  // all white (within the theme)

surface.batch(fn)

Groups multiple drawing operations so that change notifications are coalesced into a single notification. Use this when making many changes to a surface at once.

surface.batch(() => {
  surface.clear(0);
  surface.fillRect(0, 0, 30, 30, 100);
  surface.text("HELLO", { x: 0, y: 10, width: 90, height: 20, center: true });
});
// Only one OnChange notification is fired after the batch completes

Performance note: Always use batch() when making multiple changes to a surface between frames. Without batching, each individual drawing operation triggers a separate change notification, which can cause redundant re-renders.

surface.set(x, y, v)

Sets a pixel to a specific value (0–255), overwriting the previous value.

surface.set(10, 20, 200);

surface.add(x, y, v)

Adds to a pixel value (saturating at 255). Use this for additive blending.

surface.add(10, 20, 50);

surface.fillRect(x, y, width, height, v)

Fills a rectangle with a specific value.

surface.fillRect(5, 60, 80, 10, 150);

surface.line(x1, y1, x2, y2, v)

Draws a line between two points using Bresenham's algorithm. Uses additive blending.

surface.line(0, 0, 89, 89, 180);

surface.crosshatch(x, y, width, height, density, v)

Draws a crosshatch pattern within the given region. density controls the spacing between lines.

surface.crosshatch(0, 0, 90, 90, 2, 30);

surface.text(text, opts)

Draws text onto the surface. The text is rendered as alpha-masked glyphs and blended into the grayscale pixel buffer.

surface.text("HELLO", {
  x: 0,
  y: 10,
  width: 90,
  height: 20,
  brightness: 200,
  center: true,
  font: myFont,
  lineGap: 2,
  wrapWidth: 80,
});

Text options:

Multi-line text: Text containing \n is automatically rendered as multiple lines. Each line is offset vertically by the font's line height plus lineGap. Empty lines are preserved for vertical spacing.

surface.text("HELLO\nWORLD", {
  x: 0, y: 0, width: 90, center: true,
  lineGap: 4,  // 4 extra pixels between lines
});

Word wrapping: When wrapWidth is set to a value > 0, text that would exceed the given pixel width is automatically word-wrapped. The wrapping algorithm is greedy: it fills each line with as many words as fit, then wraps to the next line. Explicit \n newlines are still respected within wrapped text.

// Wrap long text to fit within an 82-pixel wide area
surface.text("This is a very long label", {
  x: 4, y: 0, width: 90, center: true,
  wrapWidth: 82,
});

surface.compositeAdd(other, x, y)

Adds the pixels of another surface onto this surface at the given offset, using additive blending.

const overlay = gfx.surface(20, 20);
overlay.fillRect(0, 0, 20, 20, 100);
surface.compositeAdd(overlay, 10, 10);

surface.at(x, y)

Reads the pixel value at the given coordinates. Returns 0 for out-of-bounds.

const v = surface.at(10, 20);

loupedeck/present

The present module controls frame scheduling. It bridges between the JS side (which decides when to invalidate) and the Go side (which decides what to re-render based on dirty tracking).

present.invalidate(reason)

Marks the current frame as needing re-render. The reason string is used for debugging and metrics only — it does not affect which tiles or displays are re-rendered. The actual re-render scope is determined by the UI dirty tracking.

const present = require("loupedeck/present");
present.invalidate("tick");

Important: If you are using the retained tile path with reactive bindings, you typically do not need to call invalidate() manually. Signal changes automatically mark tiles dirty, and the UI dirty handler calls invalidate() for you. You only need invalidate() when:

• You are using display-level surfaces and need to trigger a full re-render
• You are modifying per-tile surfaces outside of reactive bindings

present.onFrame(fn)

Registers a callback that runs on every invalidated frame, before the renderer flushes. The callback receives the reason string.

const present = require("loupedeck/present");

present.onFrame(reason => {
  // Redraw all surfaces
  mainSurface.batch(() => {
    mainSurface.clear(0);
    drawScene();
  });
});

When to use onFrame(): Use it when you have display-level surfaces that need to be redrawn every frame (e.g., full-display animation scenes like 11-cyb-os-tiles.js). For per-tile content with reactive bindings, you typically don't need onFrame() — signal changes drive tile updates automatically.

loupedeck/anim

The animation module gives JavaScript access to the host-owned animation runtime. These helpers operate on numeric targets, not arbitrary tiles or scene objects. A valid target is any object that exposes get() and set(value).

Signals are the intended primary target.

anim.to(target, to, durationMs, easeFn?)

Tweens a numeric target to a new value and returns a handle with stop().

const anim = require("loupedeck/anim");
const easing = require("loupedeck/easing");

const opacity = state.signal(0);

const handle = anim.to(opacity, 1, 250, easing.inOutCubic);

Parameter meanings:

anim.loop(durationMs, fn)

Runs a repeating loop that calls your function with a normalized phase from 0.0 to < 1.0 and returns a handle with stop().

const pulse = state.signal(0);

const handle = anim.loop(1200, t => {
  pulse.set(t);
});

Use loop(...) when the script wants to derive its own animated value instead of asking the runtime for a target tween.

anim.timeline()

Creates a sequential timeline builder. The builder supports .to(...) chaining and .play().

const timeline = anim.timeline()
  .to(level, 100, 200, easing.outBack)
  .to(level, 50, 180, easing.inOutCubic);

const handle = timeline.play();

This is a sequential timeline in the current implementation. Each step begins after the previous tween finishes.

Animation handles

All current animation entry points return a handle object with stop().

const handle = anim.loop(1000, t => {
  pulse.set(t);
});

handle.stop();

Stopping the handle stops future timer-driven updates. It does not rewind the signal automatically.

loupedeck/easing

The easing module exposes pure functions that map t in [0, 1] to an eased t in [0, 1].

Available functions

Example:

const easing = require("loupedeck/easing");

const blink = easing.steps(2);
const value = blink(0.75);

These functions are useful both as tween easing functions and as ordinary numeric transforms inside reactive bindings.

loupedeck/metrics

The low-level metrics module is the narrow bridge from JavaScript into the Go-owned in-process metrics collector. It is intentionally small and generic.

metrics.inc(name, delta = 1)

Increments a named counter.

const metrics = require("loupedeck/metrics");
metrics.inc("scene.frames");
metrics.inc("scene.activations", 2);

metrics.observeMillis(name, value)

Records a timing sample in milliseconds.

metrics.observeMillis("scene.renderAll", 12.5);

metrics.time(name, fn)

Times a synchronous block and records the elapsed milliseconds.

metrics.time("scene.renderAll", () => {
  renderAll();
});

metrics.counted(name, fn)

Increments a counter and then executes a synchronous block.

metrics.counted("scene.frames", () => {
  renderAll();
});

metrics.now()

Returns the current wall-clock time in milliseconds.

const t0 = metrics.now();

loupedeck/scene-metrics

The scene-metrics module is the reusable higher-level helper package for scene authors. Use it when you want consistent metric names and common patterns like rebuild-reason tracking, activation counting, loop tick counting, and per-tile timing without repeating string-building logic in every scene.

sceneMetrics = require("loupedeck/scene-metrics").create(prefix)

Creates a helper object whose counters and timings are automatically namespaced under prefix.

const sceneMetrics = require("loupedeck/scene-metrics").create("scene");

sceneMetrics.time(suffix, fn)

Times a block and records it under prefix + "." + suffix.

sceneMetrics.time("renderAll", () => {
  renderAll();
});

sceneMetrics.timeTile(name, fn)

Records per-tile timing under prefix + ".tile." + name.

sceneMetrics.timeTile("SPIRAL", () => {
  drawSpiralTile(...);
});

sceneMetrics.recordLoopTick()

Increments prefix + ".loopTicks".

sceneMetrics.recordActivation(reason)

Records prefix + ".activations" plus a categorized activation counter such as prefix + ".activations.touch" or prefix + ".activations.button".

sceneMetrics.recordActivation("T3");
sceneMetrics.recordActivation("B1");

sceneMetrics.recordRebuild(reason, fn)

Tracks a rebuild cause and, when a function is provided, times the rebuild body.

Recorded counters include:

• prefix + ".renderAll.calls"
• prefix + ".renderAll.reason.<category>"
• prefix + ".renderAll.reasonExact.<reason>"

If fn is provided, the timing is recorded as:

• prefix + ".renderAll"

sceneMetrics.recordRebuild("loop", () => {
  renderAll();
});

sceneMetrics.reasonCategory(reason)

Maps a reason like loop, initial, T12, or B1 into a stable category such as loop, initial, touch, or button.

Live-runner command reference

The main hardware execution path is cmd/loupedeck, with the live runner exposed as the run subcommand. It is a Cobra/Glazed command, and these flags are the operational surface you will use while developing scripts.

Basic usage

go run ./cmd/loupedeck run ./examples/js/01-hello.js --duration 5s

Important flags

Important operational rule

If your script uses Circle as an input, run with:

--exit-on-circle=false

Otherwise the runner will exit before your script callback becomes useful.

Example patterns

Reactive counter (retained tile path)

The simplest pattern: button press → signal change → tile text updates automatically.

const state = require("loupedeck/state");
const ui = require("loupedeck/ui");

const count = state.signal(0);

ui.page("counter", page => {
  page.tile(0, 0, tile => tile.text("BUTTON1"));
  page.tile(1, 0, tile => tile.text(() => `COUNT ${count.get()}`));
});

ui.onButton("Button1", () => {
  count.update(v => v + 1);
});

ui.show("counter");

Per-tile surface clock

Use per-tile surfaces for custom drawing that only invalidates the changed tile. This is 12× faster than redrawing the full display.

const gfx = require("loupedeck/gfx");
const ui = require("loupedeck/ui");
const anim = require("loupedeck/anim");

// Create per-tile surfaces
const clockTile = gfx.surface(90, 90);

ui.page("clock", page => {
  page.tile(0, 0, tile => {
    tile.surface(clockTile);
  });
});

// Update the clock tile surface every second
anim.loop(1000, () => {
  const d = new Date();
  const h = String(d.getHours()).padStart(2, "0");
  const m = String(d.getMinutes()).padStart(2, "0");
  const s = String(d.getSeconds()).padStart(2, "0");

  clockTile.batch(() => {
    clockTile.clear(0);
    clockTile.text(`${h}:${m}`, { x: 0, y: 20, width: 90, height: 24, center: true, brightness: 220 });
    clockTile.text(s, { x: 0, y: 48, width: 90, height: 14, center: true, brightness: 100 });
  });
  // Only tile (0,0) is re-rendered — 32KB instead of 389KB
});

ui.show("clock");

Full-display surface scene

Use a display-level surface when effects span tile boundaries (ripples, scanlines, cross-tile animations). This is the most flexible but slowest path — every frame redraws the entire 360×270 display.

const gfx = require("loupedeck/gfx");
const ui = require("loupedeck/ui");
const present = require("loupedeck/present");
const anim = require("loupedeck/anim");

const main = gfx.surface(360, 270);

ui.page("full", page => {
  page.display("main", display => {
    display.surface(main);
  });
});

let frame = 0;

function drawScene() {
  main.batch(() => {
    main.clear(0);
    // Draw all 12 tiles, background effects, scanlines, etc.
    frame++;
  });
}

present.onFrame(() => {
  drawScene();
});

anim.loop(2000, () => {
  present.invalidate("loop");
});

ui.show("full");

Hybrid: display layers + per-tile surfaces

Combine display-level background effects with per-tile foreground content for the best of both worlds.

const gfx = require("loupedeck/gfx");
const ui = require("loupedeck/ui");

const bgEffect = gfx.surface(360, 270);
const tileContent = gfx.surface(90, 90);

ui.page("hybrid", page => {
  page.display("main", display => {
    display.surface(bgEffect);       // background layer (full display)
  });

  page.tile(0, 0, tile => {
    tile.surface(tileContent);       // per-tile content (only this tile redraws)
  });
});

When tileContent changes, only tile (0,0) is re-rendered. When bgEffect changes, the entire display is re-rendered (because the background spans all tiles).

Knob-driven numeric state

const state = require("loupedeck/state");
const ui = require("loupedeck/ui");

const level = state.signal(50);

ui.page("knob", page => {
  page.tile(0, 0, tile => tile.text(() => `${level.get()}%`));
});

ui.onKnob("Knob1", event => {
  level.update(v => Math.max(0, Math.min(100, v + event.value)));
});

ui.show("knob");

Animation loop driving a signal

const state = require("loupedeck/state");
const ui = require("loupedeck/ui");
const anim = require("loupedeck/anim");
const easing = require("loupedeck/easing");

const pulse = state.signal(0);

ui.page("pulse", page => {
  page.tile(0, 0, tile => {
    tile.text(() => `${Math.round(easing.inOutCubic(pulse.get()) * 100)}%`);
  });
});

anim.loop(1000, t => {
  pulse.set(t);
});

ui.show("pulse");

Current limitations and non-goals

The current API is deliberately narrower than the long-term brainstorm docs.

What is implemented today:

• retained pages and tiles on the main display
• per-tile surfaces with per-tile invalidation
• display-level surfaces with layers and compositing
• reactive state
• hardware event callbacks
• numeric animation helpers
• easing helpers
• owned-runtime callback serialization
• live hardware execution through loupedeck run

What is not implemented yet:

• raw transport or framebuffer access from JavaScript
• a JS assets module
• full JS-driven SVG/icon raster asset support
• direct JS timer APIs such as setTimeout / setInterval
• left/right strip retained UI in the JS layer
• advanced scene-graph widgets beyond simple tiles

These omissions are intentional. The current boundary preserves Go-side transport ownership and keeps the first runtime slice understandable.

Troubleshooting

See Also

• Build your first live Loupedeck JavaScript script — Step-by-step user guide for writing and running a real script
• runtime/js/module_ui/module.go — Concrete source of truth for the UI module exports
• runtime/js/module_gfx/module.go — Concrete source of truth for the gfx module exports
• runtime/js/module_present/module.go — Concrete source of truth for the present module exports
• runtime/js/module_state/module.go — Concrete source of truth for the reactive state exports
• runtime/js/module_anim/module.go — Concrete source of truth for the animation exports
• runtime/js/module_easing/module.go — Concrete source of truth for the easing exports
• cmd/loupedeck/main.go — Primary CLI root
• cmd/loupedeck/cmds/run/command.go — Current live hardware runner command
• examples/js/ — Repository example scripts that match this API surface