fix: late replies, unknown backgrounds, small windows, and --cells

CHANGELOG.md

@@ -11,6 +11,13 @@ listed under a **Changed** or **Removed** heading.
 
 ### Added
 
+- **`--cells STYLE`** (#142): start the chart in a cell style — `auto`,
+  `pixel`, `rounded`, `snug`, `squares`, `grid`, `spaced`, `blocks`, `slim` or
+  `compact`, the names the legend prints. A font with no block sextants meant
+  pressing `d` on every launch to get off rounded; `mossaic-glyphs`, the
+  check for exactly that font, now names `--cells squares`. `Options` gains a
+  `cells` field for library users.
+
 - **`mossaic-art --future`** (#125). `--write` now refuses to date commits
   after today without it, explains why, and points at `--save` and
   `--track`; docs/ART.md's first example takes that route.
@@ -47,6 +54,62 @@ listed under a **Changed** or **Removed** heading.
 
 ### Fixed
 
+- **A terminal reply that arrived after the start-up probe was read as
+  keystrokes** (#140). On a slow link the answers came in after the 250 ms
+  deadline, and crossterm read the background colour as Alt+`]` (next year)
+  followed by `r` (reload) and two `d`s (cell style): a dark kitty over ssh
+  started in snug cells, with no pixels and a guessed theme. The probe now
+  waits 500 ms, and a terminal that has started answering by then gets a
+  second window to finish; anything later still is recognised as a reply and
+  swallowed up to its terminator, and keys carrying Alt no longer act as
+  their plain letter.
+
+- **A terminal that did not report its background got white text on white**
+  (#141). The appearance fell back to dark, so on a light terminal that did
+  not answer `OSC 11` — every native Windows run, mosh, multiplexers that do
+  not forward it — the header, the month labels and the footer were `#f0f6fc`
+  at about 1.07:1. Text is now drawn in the terminal's own colour (dimmed for
+  the quieter lines) and only the cells keep GitHub's; the help overlay says
+  the background was not reported and offers `--theme light`. Sixel edges are
+  no longer blended into a dark canvas that was only a guess: they are cut
+  hard instead. The README no longer lists Windows Terminal among the
+  terminals found automatically — on Windows nothing is asked, so it needs
+  `--graphics sixel --cell WxH`.
+
+- **In a small window the way out was the first thing to go** (#139). The
+  demo's and a file's source label trimmed `q quit` off the footer before
+  itself (56×24 showed only `? help · demo — …`); at 80×18 the note pushed
+  the footer off, and at 60×14 and 40×10 there was neither a footer nor any
+  word of why. A short window now gives up the statistics, then the spacing,
+  the detail line and the legend, and keeps the note and the keys; below
+  59×14, where no chart fits beside them, it says `terminal too small (needs
+  59×14) — q quits`. A style asked for that is taller than the window loses
+  its bottom rows instead of the footer. The failure screen offers `u` only
+  where it works — not for `--file` or `--demo` — and the tooltip's `▼` no
+  longer overwrites a letter of the month label beneath it.
+
+- **Pixel cells forced into a narrow window drew nothing** (#142). After `d`
+  at under 112 columns the grid and the legend were blank, no image was sent
+  at all, and the undrawn days still answered the mouse. The weeks that fit
+  are drawn now, clipped at the edge as text is, and only those are days to
+  the mouse. `d` from any style that does not fit goes to the best one that
+  does rather than on round the cycle, which could be wider still. A terminal
+  that speaks kitty or sixel but does not report its cell size is told to
+  pass `--cell WxH` — under the legend and in the help overlay — where before
+  the hint appeared only for a forced `--graphics`, and the overlay suggested
+  another terminal.
+
+- **The art editor and `mossaic-glyphs` always sent truecolour on a dark
+  theme** (#143). `env -u COLORTERM mossaic-glyphs --color always` wrote
+  `\e[38;2;21;27;35m`, so the checker for terminals without truecolour —
+  Terminal.app among them — showed colours the chart never draws there. Both
+  now take the chart's palette: the 256-colour ramp unless `COLORTERM` says
+  otherwise, and the light theme on a terminal that reports a light
+  background. To know that, `mossaic-art --draw` and an interactive
+  `mossaic-glyphs` now ask the terminal as the chart does, and the editor
+  drops a reply that arrives late rather than painting its digits.
+  `draw::palette_over` and `term::LateReplies` are new for library users.
+
 - **`mossaic-art --write` into an existing repository deleted its files and
   moved its branch** (#124). It started a new root and ran `git reset --hard
   main` on whatever was checked out, so uncommitted work was lost and the

README.md

@@ -125,12 +125,20 @@ cells      kitty
 ```
 
 - **`cells text`** means the terminal draws neither protocol. kitty, Ghostty,
-  WezTerm, foot, Konsole, iTerm2, mlterm, Windows Terminal and
-  `xterm -ti vt340` all draw one of them; GNOME Terminal and Ptyxis draw
-  neither, because VTE ships sixel switched off. Nothing is lost but the
-  pixels — the chart still draws in block sextants.
+  WezTerm, foot, Konsole, iTerm2, mlterm and `xterm -ti vt340` all draw one
+  of them; GNOME Terminal and Ptyxis draw neither, because VTE ships sixel
+  switched off. Nothing is lost but the pixels — the chart still draws in
+  block sextants.
+- **On native Windows nothing is asked at all** — the probe reads the
+  terminal's replies in a way only unix offers — so the answers are all `no`.
+  Windows Terminal draws sixel when told to: `mossaic --graphics sixel --cell
+  WxH`, measuring the cell yourself, and `--theme light` on a light background.
 - **A window under 112 columns** falls back too, and the chart says so under the
-  legend, naming the number it wants.
+  legend, naming the number it wants. Forced with `d`, pixel cells draw the weeks
+  that fit.
+- **`cell unknown`** with `kitty yes` or `sixel yes` means the terminal can draw
+  but did not say how big a character cell is, and an image cannot be lined up
+  without it. The chart says so too; measure it and pass `--cell WxH`.
 - Either way, `mossaic --png chart.png` renders the same image to a file from
   any terminal at all.
 
@@ -203,6 +211,7 @@ mossaic --png chart.png          # the chart as an image, from any terminal
 mossaic --demo --png - > c.png   # `-` is stdout; the status line goes to stderr
 mossaic --graphics sixel         # force a protocol, or `text` for no pixels
 mossaic --cell 10x20             # when the terminal will not say how big a cell is
+mossaic --cells squares          # start in a cell style, instead of the best that fits
 mossaic --today 2027-06-30       # read the year as of a day — its year, its season
 mossaic --theme light            # instead of following the terminal's background
 mossaic --palette winter         # GitHub's own seasonal colours (a --png is
@@ -409,7 +418,7 @@ kitty protocol.
 | `Home` / `End` | first / last day in range |
 | `?` | keys, mouse, and what this terminal can draw |
 | `u` | type a different username (`Enter` load, `Esc` cancel) |
-| `d` | cycle cell style — auto / pixel / rounded / snug / squares / grid / spaced / blocks / slim / compact. The legend names it, and says `auto:` while the chart is still choosing |
+| `d` | cycle cell style — auto / pixel / rounded / snug / squares / grid / spaced / blocks / slim / compact. The legend names it, and says `auto:` while the chart is still choosing. From a style that does not fit, it goes to the best one that does. `--cells NAME` starts in one |
 | `m` | mouse reporting on or off — off gives the terminal its own selection back |
 | `r` | reload |
 | `q` | quit — `Esc` cancels the username prompt and closes the help overlay, and does nothing else |
@@ -459,7 +468,8 @@ act on:
 - **Which colours.** Every value is a Primer token read out of the stylesheets
   github.com serves, not transcribed. Light or dark follows the terminal's own
   background over `OSC 11`, the way a browser follows the OS; `--theme`
-  overrides it. GitHub swaps the greens for a few days a year and so does
+  overrides it. A terminal that does not say gets its own colour for the text
+  and GitHub's only for the cells, which read on either background. GitHub swaps the greens for a few days a year and so does
   mossaic, on the same dates — `--palette` asks for them out of season.
 - **How a day is sized.** A day is two character columns wide and one row tall,
   and the square inside it keeps github.com's ratios — an 11px cell on a 14px
@@ -483,8 +493,9 @@ palette is degraded on purpose, and what the capability probe actually sends.
 - **Motion reporting is not universal.** Terminals that report clicks but not motion
   (Terminal.app among them) get click-to-select-a-day and no hover.
 - **Sixel has no alpha.** Anti-aliased edges are composited against the background
-  colour the terminal reported; where it reports none, GitHub's own canvas colour
-  stands in, and on a terminal with a background image the corners will show a faint
+  colour the terminal reported; where it reports none, the canvas of the `--theme`
+  asked for stands in, and with neither the edges are cut rather than blended into
+  a guess. On a terminal with a background image the corners will show a faint
   halo. Kitty, which takes an alpha channel, does not have the problem.
 - **The tooltip sits above the grid, not over the day** — the one placement both
   protocols can live with.
@@ -494,7 +505,10 @@ palette is degraded on purpose, and what the capability probe actually sends.
 - **A 53-week year needs a 112×19 window** for pixel or square cells, 165 columns
   for rounded corners, 166×27 for the bordered grid. Below that `Auto` drops to a
   borderless style, where a future day and a day off the end of the year both look
-  blank; `d` still forces the others if you would rather they clipped.
+  blank; `d` still forces the others if you would rather they clipped. A shorter
+  window gives up the statistics line first, then the legend and the spacing,
+  and keeps the keys; below 59×14 there is no room for a chart and the way out
+  together, and the chart says so instead.
 - Private contributions appear only if the authenticated user can see them.
 
 ## Install

docs/DESIGN.md

@@ -167,14 +167,25 @@ doubles as the "everything that is coming has come" marker. The read is from
 timeout and nothing else — no thread left blocked holding the keyboard, which
 is what a naive blocking read would do to the next keypress.
 
+A reply that misses the deadline is not lost, which is the trouble with it: it
+arrives on the keyboard's input, and crossterm, which has no parser for `OSC` or
+`APC`, reads `ESC ] 11 ; rgb:0d0d/…` as Alt+`]` and then an `r` and two `d`s —
+next year, reload, and a different cell style. So a terminal that has started
+answering by the deadline gets a second window to reach the sentinel; a silent
+one still costs only the first. Whatever arrives later still is swallowed by
+the key handler: an Alt+`]`, Alt+`_` or Alt+`P` opens a reply, the keys after
+it are dropped up to its terminator (bounded in count and in time), and no
+binding in the chart answers to Alt at all.
+
 Only `OK` counts for kitty. A terminal that knows the protocol but not that
 transmission medium answers `ENOTSUPPORTED`, and would then be sent images it
 cannot draw.
 
 **Without a cell size there are no pixels.** An image that cannot be lined up
 with the labels around it is worse than no image, so a terminal that will not say
-gets text cells — and the chart says so under the legend rather than leaving a
-`--graphics kitty` looking ignored. There are three places the size can come
+gets text cells — and the chart says so under the legend, naming `--cell WxH`,
+whether the protocol was forced with `--graphics` or only answered for: text
+cells from a terminal that said yes to kitty look like a terminal that said no. There are three places the size can come
 from, in order: `TIOCGWINSZ`, the `CSI 16 t` reply, and the window size from
 `CSI 14 t` divided by the grid. Or you measure it yourself and pass
 `--cell 10x20`, which outranks all three. A resize re-asks, because that is also
@@ -192,7 +203,9 @@ repairing it means re-emitting a slice of the image on a frame boundary that
 does not exist. One placement that works everywhere beat two that did not.
 
 What is kept: the wording is github.com's exactly, ordinals included, and a `▼`
-points at the hovered week's column so the association is unambiguous.
+points at the hovered week's column so the association is unambiguous — from a
+column of that week clear of the month labels it shares a row with, or not at
+all, since a `▼` drawn over one turned `Jan` into `J▼n`.
 
 ## 8. Two pointers, not one