The display is a sink. It draws the frames it receives and does nothing else: no engine, no animations, no content of its own. Anything that produces frames (Emacs gamegrid, a Python engine, an ESP32 relaying a sensor, a 16-colour movie player, the building rig) is a source and lives elsewhere. This page specifies what the sink accepts on its URL, what it advertises, what it speaks on the wire, and the numbers it will not exceed.

Three parts:

The relay is one possible transport. A named pipe, a UDP port, a serial line, or the building rig can replace it as long as it delivers the same frames; the page and the advertisement stay the same. The page also accepts frames from a source in the same browser through window.postMessage({frame}) and exposes window.display = {w, h, makeframe, send}, the SPEC section 2.3 surface, so a local source needs no socket at all.

Built as a browser tool under docs/specs/tool-maintenance.org v1.0.0: src/wal_sh/tools/display/core.cljc holds the pure reduction and projection, browser.cljs holds the socket, the DOM, and nothing that decides.

The rendered surface is w by h cells. Every cell shows exactly one of 16 palette entries, index 0 to 15. Index 0 is unlit (the background). The palette is a property of the display (chosen by preset, by the palette parameter, or announced in caps), not of the frame.

A cell on the wire is a palette index. That is the whole rendering contract: the wire carries what the display can show, four bits of information per cell, and nothing the display would discard. Sources that hold colours rather than indices quantize before the wire (see 7); the sink never quantizes.

Default palette is cga, the IBM PC CGA sixteen:

Named palettes in v0.2: cga (default), c64, pico8 (16 entries each), gb (4), grey8 (8), mono (2). A palette with fewer than 16 entries is a display with fewer levels: a lamp behind a window is on or off, a relay-dimmed one has eight steps. A frame is still 16-valued on the wire; the sink reduces each index to the palette's n levels by the display-contract rule

level(idx) = 0            when idx = 0
           = max(1, round(idx * (n - 1) / 15))   otherwise

so index 0 is always unlit and any lit index stays lit. mono and grey8 are mono palettes: their entries are brightness, drawn as a grey ramp; the others are colours. levels and mono are advertised per preset in capabilities.json. A relay may announce a 16-entry palette in caps; the page adopts it. Custom palettes are not accepted on the URL in v0.2 (see 10).

The page takes d, w, h, px, gap, aspect, src, palette, fps. d selects a preset; the explicit parameters override the preset's fields one by one. Unknown parameters are ignored. A parameter outside its domain is rejected, not clamped: the page renders nothing and shows an error element naming the parameter (see 9), so a bad link fails visibly rather than drawing the wrong grid.

w * h must not exceed 65,536 (256 by 256). fps can lower a preset's rate, never raise it: the preset's rate is the hardware's, and the sink honours the tighter of the two.

Geometry authority: an explicit w or h fixes the grid, and a relay whose caps disagree is refused (bad-src with the mismatch in the error element). Without explicit w and h, the relay's caps may resize the grid, since the source knows the panel it is driving. px is a rendering hint and never changes the grid.

Resolution order: preset fields first, then each explicit parameter in the table's order, then caps for w, h, fps, palette when not fixed. The effective values are written to the root element's data- attributes so a reader (or Bombadil) can check what the page decided against what the URL asked.

A preset is a named geometry with a default palette and frame rate. The footer lists every preset as a link, so /tools/display?d=green-building works and the others are one click away.

kind is the display-contract vocabulary (text-mode, field, facade, badge, panel): what the preset stands in for, so a source can pick a demo that suits a building rather than a screen. The two Project Blinkenlights facades are mono displays with 2 and 8 levels; their gap of 0.3 is a placeholder until the window-to-masonry ratio is measured from the catalogue photographs. Toronto City Hall (Stereoscope, 2008, 960 windows, 16 levels), the Cira Centre (Philadelphia, 2013, RGB LED), and the Schonherz dormitory (Budapest) are known but not configured: their grids are not published in the sources consulted, and capabilities.json lists them as unconfigured rather than guessing.

aspect is cell width over cell height throughout; the CGA default's 1.2 is the 6:5 pixel of 320 by 200 on a 4:3 display (issue #93's draft wrote the same cell as 0.8, height over width). It is the largest default that still reads as a screen rather than a poster on a laptop, and its palette is the one the sink ships with.

Presets are data (capabilities.json and the same EDN the core reads), not code. Adding one is a data change plus a footer link.

GET /tools/display/capabilities.json. Static, co-located with the page. The live lease holder is only on the WebSocket; the advertisement never claims to know it. The contract does not live under .well-known/, which this site reserves for cross-cutting agent discovery; it is linked from .well-known/api-catalog.json (RFC 9727 linkset) the way agents.json is:

{
  "anchor": "https://wal.sh/tools/display/",
  "service-desc": [{ "href": "https://wal.sh/tools/display/capabilities.json", "type": "application/json" }],
  "service-doc":  [{ "href": "https://wal.sh/tools/display/", "type": "text/html" }]
}

The advertisement:

{
  "name": "wal.sh display",
  "spec": "0.2.0",
  "endpoints": { "ws": "wss://wal.sh/tools/display/ws", "page": "https://wal.sh/tools/display/?d=<display>" },
  "formats": ["pal16", "hex"],
  "max": { "w": 256, "h": 256, "cells": 65536, "fps": 60, "ttl": 900, "frameBytes": 65538 },
  "default": "cga40",
  "palettes": { "cga": ["#000000", "#0000AA", "..."], "c64": ["..."], "gb": ["..."], "mono": ["..."], "pico8": ["..."] },
  "displays": {
    "cga40":          { "w": 40, "h": 25, "aspect": 1.2, "gap": 0,    "palette": "cga", "fps": 30, "note": "IBM PC CGA 40-column text mode" },
    "tetris":         { "w": 10, "h": 20, "aspect": 1,   "gap": 0.12, "palette": "cga", "fps": 30 },
    "green-building": { "w": 9,  "h": 17, "aspect": 1.5, "gap": 0.35, "palette": "cga", "fps": 30 },
    "hub75":          { "w": 64, "h": 32, "aspect": 1,   "gap": 0.15, "palette": "cga", "fps": 60 }
  },
  "reservation": { "max_ttl": 900, "renew": "any frame or {\"op\":\"renew\"}", "one_holder_per_display": true }
}

WebSocket at the advertised endpoints.ws (src overrides it). Text messages are JSON control, except that a hex frame is also a text message (see 6.4); the two are told apart by the first character, { for control. Binary messages are pal16 frames. Every control message carries op; unknown op values are ignored by the sink and answered with error reason:unknown-op by the relay.

Not normative; the shapes that sources take, so the wire choices above can be judged against real producers.

• Video at CGA geometry. ffmpeg scales and quantizes; a shim does the reserve and sends frames. The quantization is ffmpeg's, to the display's exact palette, so the sink sees indices:

    # palette.png: the sixteen CGA colours as a 16x1 image (make once).
    ffmpeg -hide_banner -re -i rick.mp4 -an \
      -vf "scale=40:25:flags=area,paletteuse=dither=none" -i palette.png \
      -pix_fmt pal8 -f rawvideo - | shim --display cga40 --name ffmpeg@nexus
  

  pal8 is one byte per cell already; the shim maps the 256-entry palette index to 0 to 15 (identity when the palette is ours) and prefixes nothing. Without paletteuse, -pix_fmt rgb24 -f rawvideo gives w*h*3 bytes and the shim quantizes (nearest sRGB, ties to the lower index). On nexus, ffmpeg 8.1 has rawvideo and rgb24 but no libcaca device, so -f caca is not available here; it was never on the wire path.

• Gamegrid. Already palette-indexed; one pal16 frame per board change, 153 bytes for the Green Building.
• Microcontroller. A HUB75 frame buffer is indexed or RGB; pal16 costs 2,048 bytes at 60 fps, 123 KB/s, well inside an ESP32 over WiFi.
• Blinkenlights family. A pal16 frame is an MCUF payload with channels=1, maxval=15 and the header removed; BLP (magic DEADBEEF, one byte per pixel, 0 or 1) is the 2-level case. The relay, when it exists, accepts both over UDP 2323 and as WebSocket binary, picks the display by width x height, scales other maxval to 0..15, and treats a UDP sender as a 5-second holder. The sink never sees these formats; it sees pal16. Reference: https://wiki.blinkenarea.org/index.php/BlinkenlightsProtocolEnglish
• Same-page source. window.display.send(frame) with a Uint8Array of w*h indices, or postMessage({frame}) from another window; no socket, no relay, same reduction.

core.cljc exposes one pure step over the messages above:

(reduce-event state event) ;; => state, total over every event kind

Canonical state:

{:w 40 :h 25 :fixed? false :format :pal16 :palette :cga :fps 30
 :status :connecting            ; :connecting | :live | :idle | :closed | :error
 :holder nil :expires nil
 :seq 0 :cells [...]            ; w*h palette indices
 :dropped 0 :error nil}

Events are the control messages (as maps) plus :frame (bytes or text), :open, :close, :tick. Reductions:

Invariants, asserted on every reduced state and tested by clojure.test.check properties:

• (count cells) equals w * h whenever w and h are set.
• every cell is an integer in 0 to 15.
• :seq is monotone non-decreasing across :frame events.
• a frame of wrong length or with an out-of-range cell never changes :cells.
• reduce-event is total: no event kind throws; unknown input counts as dropped.
• decode is format-symmetric: the hex and pal16 encodings of the same indices decode to the same :cells.

Projection (core.cljc, pure): (dirty state prev) returns the list of (x y idx) triples that differ, so the adapter writes only changed cells. The projection is lossy by declaration: it forgets everything except what the DOM needs.

Observable by a reader, by Bombadil, and by the research-audit checks:

• root #display with data-d data-w data-h data-fixed data-px data-aspect data-gap data-palette data-fps data-format data-src data-status data-holder data-seq data-dropped, the effective values after preset, parameter, and caps resolution.
• one <i data-x data-y data-c> per cell in row-major order; data-c is the palette index; colour comes from a CSS custom property per index (--c0 to --c15) set on the root from the palette.
• #display-error present only when a parameter was rejected or caps contradicted a fixed grid, with data-param naming it.
• footer nav.display-presets listing every preset as a link.

The DOM grid is the v0.2 renderer. A canvas renderer is an experiment (below), gated, and must produce the same data- attributes on the root; the per-cell elements are what the canvas path gives up.

Each limit is a number with a reason and a refutation condition (the observation that would justify changing it).

The CSP limit is the one that decides where the relay can live. The site-wide policy is default-src 'self'; crowsnest widens connect-src for one path to loopback only, via a per-tool .htaccess. Display does the same for /tools/display/ and adds wss://wal.sh for the advertised endpoint. Whether the VPS can proxy WebSockets under Apache is an open question (see 11); until it can, src points at a relay on the LAN and the advertised endpoint is a plan, not a fact.

The tool ships behind the tool.display gate in data/experiments.edn (Statsig-shaped, plaintext, evaluated client-side by wal-sh.experiments.core). Gated off, the page renders the preset footer and the message the other RubyConf-batch tools use.

Dynamic configs, all read once at load:

Experiments, each a gate with a percentage and a checkpoint:

• display.canvas: the canvas renderer against the DOM grid, measured by paint time per frame at hub75 geometry. Refuted for canvas if it does not beat the DOM by 2x at 2,048 cells.
• display.wire-hex: sources offered hex by default. Refuted if any SPEC section 2.3 source breaks on a text frame, or if the relay's fan-out cost at hub75 rate exceeds pal16 by more than the byte ratio.
• display.relay-host: the advertised endpoint on wal.sh against a LAN relay. Refuted for wal.sh if Apache on the VPS cannot hold a WebSocket for 900 s.

Stated, not omitted, each with the condition under which it becomes a requirement.

• NR-CRDT: no conflict-free replicated state. The lease makes the display single-writer, and a full frame is a last-writer-wins register keyed by sequence; there is nothing to merge. Becomes a requirement the day two holders may paint one grid (then each cell is an LWW register and the frame becomes a per-cell map), or the day sparse updates exist and can interleave.
• NR-HISTORY: the relay keeps no frames. A late viewer sees the next frame. Becomes a requirement if a source wants replay.
• NR-AUTH: reserve is first-come. A name is a label, not an identity. Becomes a requirement when the relay leaves the LAN or the loopback trust domain (the crowsnest condition).
• NR-CONF: frames are visible to every viewer of that display.
• NR-ENGINE: the sink never generates content. A test card, a demo animation, a Tetris engine are sources; if one is wanted for the no-holder case it is a source that reserves the display like any other.
• NR-QUANT: the sink never quantizes. Colour-to-index is a source or relay concern; the sink's input is indices, and a byte outside 0 to 15 is a bad frame, not a colour.

Land with the core, under test/wal_sh/tools/display/:

• caps for every preset, and the resulting :cells length; caps against a fixed grid, and the resulting :error.
• one valid frame per format per preset; one frame of each wrong length (off by one either way) per format; a pal16 frame with one byte of 16; a hex frame with one g.
• the same indices as pal16 and as hex, decoding to equal :cells.
• a reordered frame (sequence prefix lower than last) and its rate drop.
• the lease expiry sequence: lease holder:null followed by the black frame, and the DOM after it.

This spec is wrong if any of these is observed:

1. A parameter outside its domain draws a grid instead of the error element.
2. A frame of the wrong length, or with a cell outside 0 to 15, changes any cell.
3. Two connections hold the same display at once, or a non-holder's frame is drawn.
4. The DOM renderer takes more than 16 ms to paint a full 256 by 256 frame on a 2024 laptop; the grid cap is then too generous.
5. The advertised wss://wal.sh endpoint cannot be reached from the page under the site's CSP once the relay is up; the src limit and the per-tool .htaccess are then out of step.
6. A hex frame and a pal16 frame of the same indices render differently.
7. A relay's caps resize a grid the URL fixed with w and h.

• Hosting the relay: a long-lived process on the DreamHost VPS behind Apache, or on a LAN box reached through the src parameter. The experiment above decides; until then remote is the honest default for anything not on loopback.
• Whether gb and mono should reject frames that use indices their palettes alias, rather than aliasing silently. Aliasing keeps every frame renderable; rejecting keeps sources honest.
• Whether the sequence prefix should be mandatory. Optional matches SPEC section 2.3 sources today.
• Whether capabilities.json needs a publish path of its own: org-publish ships org and its attachments; a co-located JSON file needs the static component or an explicit rsync, the way .well-known has one.