# HMI screens

A screen is a folder with an index.html — no build step, no proprietary designer. The gateway serves thermite.js for live tag binding over WebSocket and thermite.css for a dark industrial theme. Anything a browser can render, a screen can show.

## One folder per screen.

```
projects/press-line/screens/
├── overview/
│   ├── index.html          # required — makes the folder a screen
│   ├── screen.js           # optional logic
│   └── style.css           # optional styles — relative paths work
└── motor-control/
    └── index.html
```

The folder name is the screen name. Published screens serve at `/p/<slug>/hmi/<screen>/`; the gateway's `/hmi/` lists every project and screen. Images, fonts, and other assets live alongside `index.html`.

## A complete screen.

```html
<!-- screens/overview/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Press Overview</title>
  <link rel="stylesheet" href="../thermite.css">
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <div class="th-screen">
    <div class="th-header">
      <h1>Press Overview</h1>
      <div class="th-header-status">
        <span class="th-status-dot" id="conn-dot"></span>
        <span id="conn-label">Connecting...</span>
      </div>
    </div>
    <div class="th-pad th-row">
      <div class="th-gauge">
        <div class="th-gauge-label">Head pressure</div>
        <div class="th-gauge-value" id="val">--</div>
        <div class="th-gauge-units">psi</div>
      </div>
      <button class="th-btn th-btn-success" id="start">Start cycle</button>
    </div>
  </div>
  <script src="../thermite.js"></script>
  <script src="screen.js"></script>
</body>
</html>
```

```js
// screens/overview/screen.js
Thermite.subscribe("press/hydraulics/HeadPressure", function (tv) {
  var el = document.getElementById("val");
  el.textContent = tv.quality === "good" && typeof tv.value === "number" ? tv.value.toFixed(1) : "--";
  el.className = "th-gauge-value " + (tv.quality === "good" ? "" : "th-stale");
});

document.getElementById("start").onclick = function () {
  Thermite.writeTag("press/controls/StartCycle", true)
    .catch(function (err) { console.error(err); });
};

Thermite.onConnect(function () {
  document.getElementById("conn-dot").classList.add("connected");
  document.getElementById("conn-label").textContent = "Connected";
});
```

## The client API.

Served by the gateway at `/hmi/thermite.js`; it auto-connects on page load and everything hangs off the global `Thermite` object. Values carry quality and timestamp so screens can indicate stale or bad readings. Use ../thermite.js and ../thermite.css in screens to retain the current project prefix.

### `Thermite.subscribe(path | paths, cb)`

Live updates over the managed WebSocket. cb receives { value, quality, timestamp }; returns an unsubscribe function.

### `Thermite.readTag(path)`

Synchronous cached read — null if the tag hasn't been seen yet.

### `Thermite.writeTag(path, value)`

Write a value; returns a Promise. With authentication enabled, the gateway checks can_write_tags.

### `Thermite.getHistory(path, opts)`

Historical series: { start, end, mode: "raw"|"aggregated", interval, limit }.

### `Thermite.onConnect(cb) / onDisconnect(cb)`

Connection lifecycle for status indicators. Thermite.isConnected() reads current state.

### `Thermite.getAlarms()`

Returns a Promise for the project's active-alarm projection. Drafts do not evaluate alarms.

## Gateway permission checks with authentication enabled.

With authentication enabled, `writeTag` uses the project session and the gateway checks `can_write_tags` before dispatching the write. The audit log records write outcomes. Authentication is off by default; enable it before relying on roles. See [Users, roles & security](https://thermitescada.com/docs/security.md).

## Optional hooks — no build step.

If a screen loads React, thermite.js exposes hooks. This stays a runtime choice per screen — there is no bundler or JSX pipeline in the product; complex screens can bring their own tooling and ship the built files into the screen folder.

### `Thermite.useTag(path)`

Returns the live { value, quality, timestamp } or null.

### `Thermite.useTagWrite(path)`

Returns a write function for the tag.

### `Thermite.useConnection()`

Returns the boolean connection state.

## Included components.

A dark industrial theme with layout primitives (`th-screen`, `th-row`, `th-col`, `th-grid-2/3/4`) and components: header with status dot, cards, gauges with bar fill, indicators, value displays, buttons (`th-btn`, `-success`, `-warning`, `-danger`, `-outline`), trend-chart framing around a canvas, and quality colors (`th-good`, `th-warning`, `th-bad`, `th-stale`). It's optional — screens can ship any CSS. Layouts collapse to a single column under 768 px.

## The edit loop.

Publish a draft (`thermite project draft press-line wip`), open it at `/draft/press-line/wip/hmi/…`, and re-run the draft command as you edit — each run swaps the draft's snapshot, and connected screens get a `snapshot_changed` notice that thermite.js surfaces as an update banner; reload to pick it up. Production screen files change when you `publish` production. Drafts share gateway device connections, so writable draft controls can affect equipment. Full lifecycle: [Publishing & the CLI](https://thermitescada.com/docs/publishing.md).
