Framework Runtime

At a high level, it measures the space you have and then plans columns, clamps text, formats and fits values, and adjusts gaps and index widths, so everything fits neatly without manual tweaking.

• Normalizes screen context (size, orientation, bit depth, scale)
• Maps legacy responsive classes to data attributes for consistency
• Formats values and fits numbers into their containers
• Adjusts gaps so columns/grids land on integer pixel widths
• Plans multi-column layouts, re-clamps text per column, and can add a trailing "and N more" label when enabled
• Applies standalone clamping where needed outside columns
• Limits overly tall content and schedules pixel-perfect text processing

When the runtime executes, it performs these steps in the order below. Column Gaps runs twice: once before Overflow for the columns Overflow does not own, and once at the end.

The runtime starts itself. It runs one pass after the page load event, then runs again whenever a screen--* class changes on a .screen element. Content injected after that needs an explicit re-run.

• terminalize(): runs the full pipeline and returns a Promise that resolves once the screen has settled, including the deferred pixel-perfect pass. Call it after you inject or replace content.
• executeTerminalize(): queues a run two animation frames out instead of starting one immediately. Repeated calls before it fires collapse into a single pass.
• markFrameworkReady(): sets window.frameworkReady and dispatches trmnl:framework:ready on window. A host page calls it once its own setup is done.

• window.TRMNL_PLUGINS_READY: false while a pass runs and true once it settles. A screenshot pipeline waits for true before it captures.
• window.frameworkReady: false until markFrameworkReady() runs.
• window.__TRMNL_BUILD__: the build stamp of the loaded plugins.js. A released bundle reports its own version (plugins.js v3.2.0) and a working checkout reports plugins.js source. Read it when an edit does not show up and you suspect a pinned or cached file.

Every pass dispatches trmnl:terminalize:stats on window. Its detail carries three fields.

• steps: every step the pass ran, each with a name, a durationMs, and its own counters.
• engines and engineCount: the subset of steps that changed something.
• errors: present only when an engine threw, as { engine, message } entries. The pass runs the remaining engines and readiness still flips to true.

// Re-run after injecting content into a screen.
terminalize().then(function () {
  console.log("screen settled");
});

// Inspect what each pass did.
window.addEventListener("trmnl:terminalize:stats", function (event) {
  console.log(event.detail.engineCount, "engines changed something");
});

Set window.__TRMNL_DEBUG__ = true before a pass to log what each engine decided. Renders are quiet by default. Engine failures always reach the console, debug flag or not.

plugins.js also puts TRMNLPaint and TRMNLCharts on window. Those are documented on Paint API .

Plugins need to fit source data into a static layout space that is device-defined and varies by model, orientation, and density. While this resembles responsive web design, the runtime provides purpose-built tools (overflow planning, per-column clamping, integer pixel alignment, and value fitting) tailored specifically for TRMNL devices.