Hilbert Clock — functional requirements

This document is the behavior contract for the Hilbert Clock. Source of truth during the TypeScript migration was the former single-file hilbert/clock.html. The public URL stays https://nebelmesser.com/hilbert/clock.html.

The clock draws a half-open time interval [start, end) as a 2D space-filling curve (generalized Hilbert / Gilbert). Consecutive moments stay adjacent on screen, so an interval appears as a compact region rather than scattered pixels.

Theme and tunables

Map colors and most visual constants live as CSS custom properties on :root. JavaScript reads them (Theme / cssPixel) and does not hard-code the palette.

Tokens:

Numeric thresholds (grid score, zoom, labels, fit, loop) are named constants with the values from the original file.

Map layers

Each panel is four stacked canvases:

  1. base — cell fill (ImageData, alpha: false), pixelated
  2. bounds — unit edges
  3. labels — text
  4. hl — live-unit outline + yellow zoom frame outside the cells (HL_PAD_PX, ZOOM_FRAME_OUTSET)

Cells are never stretched: a Fit slot letterboxes to the grid aspect.

Fill

For each curve cell with start t0 and duration dur:

The live unit is the coarsest unit on that map. If it covers more than CURRENT_UNIT_MAX_SHARE (0.9) of the map, drop to the next level (or do not highlight).

Curve

Grid (pickGrid)

Pick w × h and cellDur for the range duration and the available slot aspect.

Boundary and label units

Ladder, coarse → fine. No weeks.

century (roman XXI) → year → month (English names) → day (ordinal 1st) → hour (HH) → minute (HH:MM) → second (HH:MM:SS) → ms100 → ms10 → ms1

Labels

Ranges and presets

Buttons: D (today), M (month), Y (year), Unix, Range, then + / −.

Zoom / inset

Fit layout

Chrome (F-mode)

Keyboard

Ignore when Ctrl / Meta / Alt is down, or when focus is in an input.

Persistence

localStorage key clock-hilbert-frame:

{ mode, layout: "fit", zoom, zoomMs, arbitrary? }

`zoom[mode] === ZOOM_HIDDEN` (−1) means the inset was dismissed.

F-mode is not persisted. Corrupt JSON is ignored.

Query parameters

Other UI

Out of scope