/* ===========================================================================
 * The terminal background image, and the one rule that lets it show.
 *
 * A theme may ship a picture inside its own package and a session may
 * override which one it wears; `client/js/terminal-background.js` resolves
 * that PER SESSION and assigns each picture as that session's own terminal
 * host's `background-image`, inline - `.terminal-container` for the page's
 * own pane, `.oc-tl-pane` for a cell. The owner's ruling on 2026-09-20:
 * "the background image should be per session, not over the entire
 * background". This file does two things and nothing else: it says HOW
 * that picture is laid out, and it clears the opaque background between a
 * host and its glyphs that would otherwise hide it.
 *
 * WHY THE IMAGE GOES ON THE TERMINAL HOST AND NOT ON A NEW ELEMENT.
 * That container is a flex column, and `styles.css` carries a long warning
 * about it: an in-flow child steals rows from `#terminal`, the
 * ResizeObserver reads that as a real geometry change, tmux raises
 * SIGWINCH and claude answers by erasing the alternate screen. A painted
 * background costs no rows at all. Nor is anything layered OVER the
 * terminal: the picture is the container's own background, which is by
 * definition behind every descendant, so selection, the cursor and the
 * renderer are untouched.
 *
 * WHY `#terminal` HAS TO GO TRANSPARENT. `styles.css` declares
 * `#terminal { background: var(--color-bg) }`, opaque, and `#terminal` is
 * a child of the container - so without this rule it paints a solid
 * rectangle straight over the picture. The same reasoning
 * `terminal-opacity.css` gives for the animated background applies here,
 * plus one more: xterm's glyph canvas covers exactly rows*cols cells and
 * the container has real padding, so the few pixels of `#terminal` outside
 * that grid would show as a hard-edged opaque margin around a translucent
 * terminal.
 *
 * THE SCRIM IS NOT DECLARED IN THIS FILE, AND THAT IS THE DESIGN. It is a
 * flat `linear-gradient` layer the resolver stacks ABOVE the picture in the
 * same inline `background-image`, coloured with the theme's own terminal
 * background at an alpha of `dim`. So the picture dims towards the theme's
 * own colour rather than towards a black wash: a dark theme dims dark, a
 * light one dims light, and the composited surface is exactly what the
 * contrast floor in `terminal-background.js` is computed against. Declaring
 * a scrim here instead would mean a colour in a stylesheet that has to stay
 * in step with a palette it cannot see.
 *
 * IT IS ONE SCRIM, AND xterm CONTRIBUTES NONE OF IT. The first build put
 * the scrim in xterm's own cell background, which covers exactly rows*cols
 * cells - and a host carries padding and is rarely an exact
 * multiple of the cell size. Rendered in a real browser that left a bright,
 * undimmed ring of raw picture around a correctly dimmed terminal. One
 * layer on the container covers the padding and the grid alike, which is
 * why `withTerminalBackgroundOpacity` hands xterm an alpha of ZERO while an
 * image is up: half a scrim is still a second scrim.
 *
 * THREE-OUTCOME RULE: the selector is gated on `data-terminal-bg="on"`,
 * which the resolver sets ONLY when it has a safe same-origin url AND a
 * measurable palette to derive the floor from. Absent, empty or any other
 * value matches nothing here and `#terminal` stays exactly as
 * `styles.css` defined it - fully opaque, full legibility, never
 * translucent over nothing.
 *
 * REPAINT COST. `background-attachment` is left at its default, NEVER
 * `fixed`: a fixed attachment re-rasterises the image against the viewport
 * on every scroll, which is precisely the per-frame cost a terminal
 * streaming output must not pay. The container does not scroll (xterm
 * scrolls its own inner viewport), the url is only re-assigned when it
 * actually changes, and terminal output repaints xterm's canvas above this
 * layer without invalidating it.
 * =========================================================================== */
/* THE GATE IS ON THE HOST, NOT ON THE DOCUMENT.
 *
 * `client/js/terminal-background.js` stamps `data-terminal-bg="on"` onto
 * each terminal's OWN host box - `.terminal-container` for the page's pane,
 * `.oc-tl-pane` for a cell - and only when that session actually resolved a
 * picture it could measure a scrim for. It used to go on `<html>`, which is
 * one flag for a page that now shows several sessions at once: a cell with
 * no picture was being told a picture was behind it.
 *
 * THE PICTURE CANNOT LEAVE ITS OWN FRAME. A background is painted inside
 * the element's own box, so a cell's image is clipped to that cell by
 * construction: it never bleeds across a gutter, and resizing a neighbour
 * re-rasterises only the box that actually changed size.
 *
 * `cover` IS MEASURED AGAINST THE CELL, not the page, which is what makes
 * two cells of different widths each show a sensibly framed picture rather
 * than two windows onto one page-sized raster. */
[data-terminal-bg="on"] {
    background-size: cover;
    background-position: center center;
    background-repeat: no-repeat;
}

/* WHY `#terminal` HAS TO GO TRANSPARENT. `styles.css` declares
 * `#terminal { background: var(--color-bg) }`, opaque, and `#terminal` is a
 * child of the page pane's host - so without this it paints a solid
 * rectangle straight over the picture. Scoped as a DESCENDANT of the gated
 * host, so it applies exactly when that host has a picture. A cell's xterm
 * host carries no background of its own and needs no equivalent. */
[data-terminal-bg="on"] #terminal {
    /* `background-color`, NOT the `background` shorthand. The shorthand
     * resets `background-size` and `background-repeat` to their initial
     * values, and on the page's own pane this element can be a DESCENDANT
     * of the gated box - so a shorthand here silently undid the `cover`
     * set above and the picture tiled at its natural size. Measured in a
     * real browser: `background-size: auto, auto`, two tiles across one
     * pane. */
    background-color: transparent;
}