/* The /document/ manual. Third layer of the stack, over app.css and glass.css —
   both of which this page links, which is where the tokens, the nav, the footer
   and the buttons come from. This file adds the manual: the two-column shell,
   the sidebar, and prose on top of the glass.

   Two notes for whoever edits it:

   1. The page is hand-written static HTML served by the assets layer, so it
      cannot call html.ts's head()/brand(). The nav and footer markup in
      index.html is a hand copy of what those functions emit. Change one and
      check the other.

   2. NO backdrop-filter anywhere in this file. glass.css's header comment
      explains why: blur is for a handful of purpose-chosen surfaces, and a
      documentation page is one long repeating surface. The prose sits on an
      opaque-enough fill instead, which is also what makes it readable. */

/* The nav's height, needed in two places: the sticky offset of the sidebar, and
   the narrow-screen strip that parks directly under the nav. Measured, not
   guessed — glass.css only promises a 64px *minimum*. */
:root { --doc-nav-h: 64px; }

/* ---------- the shell ---------- */

/* 1120px, the same as .hero and .sec — and matching them means matching their
   padding too, which is what actually puts the two in line. The nav's rule is
   `(100% - 1120px)/2 + gutter`, and .hero/.sec are 1120 wide with the gutter
   *inside*; both land their contents on the same 1040px line. A 1120px box with
   the same gutter here reproduces it. (Measured: 432px from the left edge at
   1904px wide — the manual was 40px left of the nav before this.)
   The top padding is the gap the sticky nav needs under it. It is a flat 24px
   rather than a vh-based clamp on purpose: it is exactly the sidebar's sticky
   offset below, so the sidebar does not move as it pins. */
.docwrap {
  max-width: 1120px;
  margin: 0 auto clamp(40px, 6vh, 72px);
  padding: 24px clamp(16px, 4vw, 40px) 0;
  display: grid;
  grid-template-columns: 220px minmax(0, 1fr);
  gap: clamp(20px, 3vw, 40px);
  /* Not cosmetic: a stretched grid item is as tall as the column, and a sticky
     box that is already its container's height has nothing to stick within. */
  align-items: start;
}

/* `body.glassy main` (glass.css) zeroes main's own column and padding — which is
   what this page wants, since the grid above positions it. Everything that turns
   main into a card therefore has to out-specify that rule rather than sit on a
   bare `.docs`. */
body.glassy main.docs {
  max-width: none;
  /* A grid item's automatic minimum is its min-content size, and the prose in
     here has a wide one (the field tables). Without this the card refuses to
     shrink below ~719px and the whole page scrolls sideways on a phone, however
     small the grid track gets. The track being minmax(0,1fr) does not do this on
     its own — that governs the track, not the item inside it. */
  min-width: 0;
  padding: clamp(22px, 2.6vw, 38px);
  background: var(--glass-strong);
  border: 1px solid var(--glass-line);
  border-radius: 20px;
  box-shadow: inset 0 1px 0 var(--glass-hi);
}

/* ---------- the sidebar ---------- */

.docside {
  position: sticky;
  top: calc(var(--doc-nav-h) + 24px);
  max-height: calc(100vh - var(--doc-nav-h) - 48px);
  overflow-y: auto;
  /* The panel is not decoration. The links are --dim, and on a wide screen the
     sidebar would otherwise sit straight on the aurora — measured at 2.7:1 in
     light mode, over a genuinely saturated patch of it, because the blobs are
     placed as a percentage of the viewport and land there at this width.
     --glass-strong is the surface --dim was actually measured against for this
     site, and it makes the sidebar read as the card's partner. No blur, for the
     same reason the cards have none. */
  padding: 10px;
  background: var(--glass-strong);
  border: 1px solid var(--glass-line);
  border-radius: 16px;
  box-shadow: inset 0 1px 0 var(--glass-hi);
}

.docside nav { position: relative; display: flex; flex-direction: column; gap: 1px; }

.docside a {
  display: block;
  padding: 7px 11px;
  border-radius: 9px;
  font-size: 13.5px;
  line-height: 1.45;
  color: var(--dim);
  text-decoration: none;
}

.docside a:hover {
  color: var(--fg);
  background: color-mix(in srgb, var(--fg) 6%, transparent);
}

/* Both copies of "you are here": the current section, and — set by doc.js as you
   scroll past the sub-headings — the current heading within it. */
.docside a.on {
  color: var(--accent);
  background: color-mix(in srgb, var(--accent) 12%, transparent);
  font-weight: 600;
}

/* Sub-entries. Indented and a step smaller so the seven top-level items still
   read as the outline and these as the detail underneath them. */
.docside a[data-sub] {
  padding-left: 22px;
  font-size: 12.5px;
}

/* ---------- the head of the document ---------- */

.dochead {
  margin: 0 0 clamp(24px, 3vw, 34px);
  padding-bottom: clamp(16px, 2vw, 22px);
  border-bottom: 1px solid var(--glass-line);
}

.dochead h1 { margin: 0 0 7px; font-size: clamp(22px, 3vw, 30px); }
.dochead .docsub { margin: 0; color: var(--dim); font-size: 14px; }

/* ---------- prose ---------- */

/* The 1120px shell gives the card 780px at its widest (1040 minus the 220px
   sidebar and the 40px gap), so this cap only binds while the gap is still
   shrinking — at full width the card lands on it exactly. The prose inside is
   780 minus the card's 38px padding, i.e. 704. Wider than a Chinese paragraph
   wants on its own, but the tables and code samples in here need the room. */
.doc { max-width: 780px; }

/* The rule between sections is what replaces the old "one section at a time"
   switcher: the page is one scroll now, and these are the seams in it. */
.doc + .doc {
  margin-top: clamp(34px, 5vh, 48px);
  padding-top: clamp(28px, 4vh, 40px);
  border-top: 1px solid var(--glass-line);
}

/* Sized against body.glassy's 16px base, not app.css's 14px. An h3 below the
   body size would read as a caption. */
.doc h2 { font-size: 22px; margin: 30px 0 12px; }
.doc h2:first-child { margin-top: 0; }
.doc h3 { font-size: 17px; margin: 26px 0 9px; }
.doc p { margin: 10px 0; line-height: 1.75; }
.doc ul, .doc ol { margin: 10px 0; padding-left: 22px; }
.doc li { margin: 6px 0; line-height: 1.7; }
.doc hr { border: 0; border-top: 1px solid var(--glass-line); margin: 26px 0; }

/* Code blocks. Inline `code` is app.css's chip; only the block is restyled here,
   and both use the glass hairline rather than app.css's opaque --line. */
.doc pre {
  background: color-mix(in srgb, var(--fg) 5%, transparent);
  border: 1px solid var(--glass-line);
  border-radius: 10px;
  padding: 13px 15px;
  margin: 13px 0;
  overflow-x: auto;
  font-family: var(--mono);
  font-size: 12.5px;
  line-height: 1.65;
}

.doc pre code { background: none; padding: 0; font-size: 12.5px; }

/* Callouts. */
.note {
  border-left: 3px solid var(--accent);
  background: color-mix(in srgb, var(--accent) 8%, transparent);
  border-radius: 0 10px 10px 0;
  padding: 10px 13px;
  margin: 15px 0;
  font-size: 13.5px;
}

.note.warn {
  border-left-color: var(--danger);
  background: color-mix(in srgb, var(--danger) 8%, transparent);
}

.note p { margin: 5px 0; }
.note p:first-child { margin-top: 0; }
.note p:last-child { margin-bottom: 0; }

/* The field / option tables. app.css gives every table an opaque --card fill and
   a --line border; over the aurora that reads as a white slab, so the fill comes
   down to a wash and the borders move to the glass hairline. The radius and the
   overflow:hidden that clips the corners stay app.css's. */
.doc table {
  background: color-mix(in srgb, var(--fg) 4%, transparent);
  border-color: var(--glass-line);
  font-size: 13.5px;
  margin: 13px 0;
}

.doc th, .doc td { border-bottom-color: var(--glass-line); }
.doc th { background: color-mix(in srgb, var(--fg) 5%, transparent); }
.doc td:first-child { white-space: nowrap; }
.doc td { line-height: 1.6; }
.doc td code { white-space: nowrap; }

kbd {
  font-family: var(--mono);
  font-size: 11.5px;
  border: 1px solid var(--glass-line);
  border-bottom-width: 2px;
  border-radius: 5px;
  padding: 1px 5px;
  background: color-mix(in srgb, var(--fg) 7%, transparent);
}

/* Each type page ends with a one-line "what does this need" — and so does the
   page itself, which is why the page footer is .site-foot and not this. */
.docfoot {
  color: var(--dim);
  font-size: 13px;
  border-top: 1px solid var(--glass-line);
  margin-top: 30px;
  padding-top: 14px;
}

/* Smooth only for people who have not asked for less motion. */
@media (prefers-reduced-motion: no-preference) {
  html { scroll-behavior: smooth; }
}

/* ---------- narrow: the sidebar becomes a strip under the nav ---------- */

@media (max-width: 960px) {
  /* display:block, not a one-column grid. A grid item still has to honour an
     automatic minimum, and neither minmax(0,1fr) on the track nor an explicit
     min-width:0 on the item defeated it here — measured at 320px the track was
     273px while the card laid out at 719px, with the page scrolling sideways at
     every phone width. A block-level box has no such floor: its width is
     fill-available, and anything too wide inside it overflows the box rather than
     the page. The two shells then just stack in source order, which is the order
     they are written in. */
  .docwrap { display: block; }

  /* Full-bleed and parked directly under the nav, so it reads as a second bar
     rather than as a card that happens to be stuck. */
  .docside {
    position: sticky;
    top: var(--doc-nav-h);
    z-index: 9;
    max-height: none;
    overflow: visible;
    margin: 0 calc(-1 * clamp(16px, 4vw, 40px));
    padding: 9px clamp(16px, 4vw, 40px);
    /* Back to a bar: the wide-screen panel's box is undone here rather than
       inherited, since the strip is meant to read as part of the nav. */
    background: var(--glass);
    border: 0;
    border-bottom: 1px solid var(--glass-line);
    border-radius: 0;
    box-shadow: none;
  }

  .docside nav {
    flex-direction: row;
    gap: 8px;
    overflow-x: auto;
    /* The strip scrolls sideways; the page must not. */
    overscroll-behavior-x: contain;
    scrollbar-width: none;
  }

  .docside nav::-webkit-scrollbar { display: none; }

  .docside a {
    white-space: nowrap;
    padding: 6px 13px;
    border-radius: 999px;
    background: color-mix(in srgb, var(--fg) 5%, transparent);
  }

  .docside a[data-sub] { padding-left: 13px; font-size: 12.5px; }

  body.glassy main.docs { padding: clamp(18px, 4vw, 26px); }
}

/* ---------- narrow: tables wrap instead of widening the page ---------- */

@media (max-width: 720px) {
  /* The overview table is the widest thing here — four columns, and its first
     column and every <code> in it are nowrap on a wide screen because that is
     what makes them scannable. At this width that same rule is what would push
     the page into a horizontal scrollbar, so both relax. anywhere rather than
     break-word: only the former also relaxes the min-content size, and a
     table's width is computed from exactly that. */
  .doc td:first-child { white-space: normal; }
  .doc td { overflow-wrap: anywhere; }
  /* Inline code, in prose and in cells alike. A long unbreakable token — a
     command, a host name — is the last thing here that can still widen the page,
     because it is one word and nothing else will break it. `:not(pre) > code`
     leaves code *blocks* alone: those scroll sideways on purpose. This is where
     the remaining 10px of overflow at 320px came from. */
  .doc :not(pre) > code { overflow-wrap: anywhere; white-space: normal; }
  .doc table { font-size: 13px; }
  .doc h2 { font-size: 20px; }
}

/* ---------- print ---------- */

/* The whole point of rendering every section at once is that the manual can be
   printed or saved as one document, so this block is load-bearing rather than
   decorative: without it a printout is a dark aurora with a sidebar down it. */
@media print {
  .aurora, .nav, .docside, .site-foot { display: none !important; }

  body.glassy { background: #fff; color: #000; font-size: 11pt; }

  .docwrap { display: block; max-width: none; margin: 0; padding: 0; }

  body.glassy main.docs {
    padding: 0;
    background: none;
    border: 0;
    box-shadow: none;
    border-radius: 0;
  }

  .doc, .doc + .doc { max-width: none; border-top: 0; margin-top: 0; padding-top: 0; }
  .dochead { border-bottom: 0; }

  .doc pre, .doc table, .note, .docfoot { break-inside: avoid; }
  .doc pre { background: #f6f7f9; border-color: #ccc; }
  .doc table { background: none; border-color: #ccc; }
  .doc th, .doc td { border-bottom-color: #ccc; }
  a { color: #000; }
}