Application JSDoc Configuration

Application JSDoc configuration

TinyPanel Canvas applications keep metadata and display preferences directly in main.canvas.js. A separate manifest.json is not required. Applications live under the repository-level apps/<app-id>/ directory.

Complete example

/**
 * @tinypanel
 * @name Synthwave
 * @description Animated retro sun, mountains, and perspective grid
 * @width 160
 * @height 128
 * @orientation landscape
 * @fps 30
 */

function render(ctx, state) {
  ctx.clear('#000000');
}

Only a JSDoc block containing @tinypanel is treated as application configuration. Unknown tags are ignored.

Parameters

Tag	Type	Default	Constraints	Purpose
@tinypanel	marker	required	no value	Identifies TinyPanel configuration.
@name	string	Canvas App	1–100 characters, one line	App library and editor name.
@description	string	empty	0–500 characters, one line	Short app description.
@width	integer	160	1–4096	Logical width in pixels.
@height	integer	128	1–4096	Logical height in pixels.
@orientation	enum	landscape	values below	Preferred orientation.
@fps	number	30	1–60	Target maximum frame rate.

Supported orientation values are landscape, landscape-reversed, portrait, and portrait-reversed. Current firmware and Studio controls support the two landscape rotations; portrait requires a compatible firmware and display profile.

Frame-rate behavior

@fps belongs to the application and is applied automatically when the app becomes active. It is an upper target, not a guaranteed measurement. Render time, frame size, network throughput, display writes, and ACK latency can lower the observed FPS.

Use the lowest useful rate: Crypto Tracker can use @fps 1, regular animation can use @fps 30, and fast animation can use @fps 60 when transport and hardware can sustain it. Network refresh frequency is independent from render frequency.

Dimensions and hardware

@width and @height describe the logical application coordinate space and should match the active firmware profile. These tags do not reconfigure the physical display; use Hardware Setup and rebuild firmware when hardware or the driver changes.

Persistence and validation

Editing the block and saving with Ctrl+S applies the configuration with the source. Names and descriptions must fit on one JSDoc line and cannot contain */. Invalid values are rejected without replacing the last valid app.

Legacy manifest.json metadata remains a fallback, but new applications should use this JSDoc format.