nvim-doc-reader 0.1.0__py3-none-any.whl

doc_reader/nvim.py

@@ -0,0 +1,215 @@
+"""Jumps into running Neovim instances, the last-target state file, and nvimd.
+
+Every Neovim (0.9+) listens on a socket of its own, `$XDG_RUNTIME_DIR/nvim.
+<pid>.0`, without `--listen`. The server talks to each one with
+`nvim --server <sock> --remote-expr`, so nothing needs installing in the
+editor. The Lua that runs there is fixed text in this module; the target
+(path, line, section) goes in as one JSON string argument, never spliced into
+code.
+
+A jump moves EVERY instance that has the file:
+  - shown in a window (any tab): the cursor moves there now;
+  - loaded but hidden: a one-shot BufWinEnter moves it when you `:b` to it;
+  - not loaded: nothing -- `nvimd` opens the last target instead.
+"""
+import asyncio
+import glob
+import json
+import os
+import shutil
+import sys
+import tempfile
+import time
+
+from doc_reader import model
+
+RPC_TIMEOUT_S = 1.0
+
+# Lua run inside the editor. Kept free of newlines-in-strings and of `--`
+# comments so it can travel as one Vim string literal.
+_INSPECT = r"""
+local a = vim.json.decode(_A)
+local out = {}
+for _, b in ipairs(vim.api.nvim_list_bufs()) do
+  local name = vim.api.nvim_buf_get_name(b)
+  if vim.api.nvim_buf_is_loaded(b) and name ~= "" and vim.loop.fs_realpath(name) == a.path then
+    table.insert(out, {
+      buf = b,
+      tick = vim.api.nvim_buf_get_changedtick(b),
+      text = table.concat(vim.api.nvim_buf_get_lines(b, 0, -1, false), "\n"),
+    })
+  end
+end
+return vim.json.encode(out)
+"""
+
+# A hidden buffer's jump runs on BufWinEnter, when the entering window is
+# current; by the time the scheduled move runs another might be, so it keeps
+# that window and falls back to wherever the buffer is shown.
+_MOVE = r"""
+local a = vim.json.decode(_A)
+local b = a.buf
+if not vim.api.nvim_buf_is_valid(b) then return "gone" end
+if vim.api.nvim_buf_get_changedtick(b) ~= a.tick then return "stale" end
+local function clamp(l) return math.max(1, math.min(l, vim.api.nvim_buf_line_count(b))) end
+local function show(win, l)
+  vim.api.nvim_win_call(win, function()
+    vim.api.nvim_win_set_cursor(win, {clamp(l), 0})
+    vim.cmd("normal! zv")
+    vim.cmd("normal! zt")
+  end)
+end
+local wins = vim.fn.win_findbuf(b)
+if #wins > 0 then
+  for _, w in ipairs(wins) do pcall(show, w, a.line) end
+  vim.cmd("redraw")
+  return "moved"
+end
+local group = vim.api.nvim_create_augroup("doc_reader_jump_" .. b, {clear = true})
+vim.api.nvim_create_autocmd("BufWinEnter", {
+  group = group, buffer = b, once = true,
+  callback = function()
+    local l = a.line
+    if vim.api.nvim_buf_get_changedtick(b) ~= a.tick and a.resolve ~= false then
+      local text = table.concat(vim.api.nvim_buf_get_lines(b, 0, -1, false), "\n")
+      local r = vim.fn.system(a.resolve, text)
+      if vim.v.shell_error == 0 and tonumber(r) then l = tonumber(r) end
+    end
+    local win = vim.api.nvim_get_current_win()
+    vim.schedule(function()
+      local targets = {win}
+      if not (vim.api.nvim_win_is_valid(win) and vim.api.nvim_win_get_buf(win) == b) then
+        targets = vim.fn.win_findbuf(b)
+      end
+      for _, w in ipairs(targets) do pcall(show, w, l) end
+    end)
+  end,
+})
+return "armed"
+"""
+
+
+def _vim_str(s):
+  """A single-quoted Vim string literal (only `'` needs escaping)."""
+  return "'" + s.replace("'", "''") + "'"
+
+
+def _expr(lua, data):
+  # luaeval takes an expression, so the statements go in a function body.
+  code = " ".join(line.strip() for line in lua.strip().splitlines())
+  code = f"(function() {code} end)()"
+  return f"luaeval({_vim_str(code)}, {_vim_str(json.dumps(data))})"
+
+
+def sockets(pattern):
+  return sorted(p for p in glob.glob(pattern) if not os.path.isdir(p))
+
+
+async def rpc(nvim_bin, sock, lua, data, timeout=RPC_TIMEOUT_S):
+  """Run `lua` in the instance at `sock`; its return value as a string, or
+  None when the instance does not answer (dead socket, blocked editor)."""
+  proc = await asyncio.create_subprocess_exec(
+      nvim_bin, "--server", sock, "--remote-expr", _expr(lua, data),
+      stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE,
+      stderr=asyncio.subprocess.PIPE)
+  try:
+    out, _ = await asyncio.wait_for(proc.communicate(), timeout)
+  except asyncio.TimeoutError:
+    proc.kill()
+    await proc.wait()
+    return None
+  return out.decode() if proc.returncode == 0 else None
+
+
+async def jump_instance(nvim_bin, sock, path, section_id, fallback_line,
+                        resolve_cmd):
+  """Move one instance. Returns a list of per-buffer results ("moved",
+  "armed", "gone"), or None when the instance did not answer."""
+  for _ in range(2):  # once more if the buffer changes between the two calls
+    raw = await rpc(nvim_bin, sock, _INSPECT, {"path": path})
+    if raw is None:
+      return None
+    results, stale = [], False
+    for buf in json.loads(raw or "[]"):
+      line = (model.line_of(model.parse(buf["text"]), section_id)
+              if section_id else None) or fallback_line
+      r = await rpc(nvim_bin, sock, _MOVE, {
+          "buf": buf["buf"], "tick": buf["tick"], "line": line,
+          "resolve": resolve_cmd})
+      if r == "stale":
+        stale = True
+        break
+      results.append(r or "failed")
+    if not stale:
+      return results
+  return ["stale"]
+
+
+async def jump_all(cfg, path, section_id, fallback_line, resolve_cmd):
+  nvim_bin = cfg.nvim
+  socks = sockets(cfg.nvim_socket_glob)
+  per = await asyncio.gather(*(
+      jump_instance(nvim_bin, s, path, section_id, fallback_line, resolve_cmd)
+      for s in socks))
+  moved = sum(1 for r in per if r and "moved" in r)
+  armed = sum(1 for r in per if r and "armed" in r and "moved" not in r)
+  dead = sum(1 for r in per if r is None)
+  return {"instances": len(socks), "moved": moved, "armed": armed,
+          "unreachable": dead}
+
+
+def message(result):
+  if not result["moved"] and not result["armed"]:
+    return "Not open in any Neovim — run nvimd"
+  parts = []
+  if result["moved"]:
+    parts.append(f"moved {result['moved']} Neovim"
+                 + ("s" if result["moved"] > 1 else ""))
+  if result["armed"]:
+    parts.append(f"{result['armed']} with it hidden: :b to it")
+  return ", ".join(parts)
+
+
+# ------------------------------------------------------------ state, nvimd
+
+def write_state(state_file, path, section_id, line):
+  os.makedirs(os.path.dirname(state_file), exist_ok=True)
+  record = {"path": path, "section_id": section_id, "line": line,
+            "ts": time.time()}
+  fd, tmp = tempfile.mkstemp(dir=os.path.dirname(state_file), prefix=".last.")
+  with os.fdopen(fd, "w") as f:
+    json.dump(record, f)
+  os.replace(tmp, state_file)
+
+
+def read_state(state_file):
+  try:
+    with open(state_file) as f:
+      return json.load(f)
+  except (FileNotFoundError, json.JSONDecodeError):
+    return None
+
+
+def nvimd_argv(cfg, args):
+  """The nvim command line nvimd runs, and a note to print (or None)."""
+  if args:
+    return [cfg.nvim] + list(args), None
+  state = read_state(cfg.state_file)
+  if not state:
+    return [cfg.nvim], "nvimd: no target yet (press n in the reader first)"
+  path = state["path"]
+  if not os.path.exists(path):
+    return [cfg.nvim], f"nvimd: last target is gone: {path}"
+  line = state.get("line") or 1
+  if state.get("section_id"):
+    with open(path, encoding="utf-8") as f:
+      line = model.line_of(model.parse(f.read()), state["section_id"]) or line
+  return [cfg.nvim, f"+{line}", "-c", "normal! zvzt", path], None
+
+
+def nvimd(cfg, args):
+  argv, note = nvimd_argv(cfg, args)
+  if note:
+    print(note, file=sys.stderr)
+  exe = shutil.which(argv[0]) or argv[0]
+  os.execv(exe, argv)

doc_reader/serve.py

@@ -0,0 +1,235 @@
+"""The reader server: pages, live-reload fragments, and raw files under the
+configured roots.
+
+HTML is rendered on every request from the Markdown on disk; nothing is
+cached or written out. Change detection polls (mtime_ns, size) because the
+documents live on NFS, where inotify does not see writes made from other
+hosts.
+"""
+import asyncio
+import html
+import json
+import mimetypes
+import os
+import sys
+import time
+from importlib import resources
+from urllib.parse import unquote, urlsplit
+
+from aiohttp import web
+
+from doc_reader import model, nvim
+from doc_reader.urls import PREFIX, Roots
+
+KATEX = "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9"
+MERMAID = "https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js"
+HEARTBEAT_S = 15
+# Raw files are served with no script and an opaque origin: an .html or .svg
+# under a root must not be able to call this server's API as the reader.
+RAW_HEADERS = {"Content-Security-Policy": "sandbox",
+               "X-Content-Type-Options": "nosniff"}
+
+
+def version(path):
+  st = os.stat(path)
+  return f"{st.st_mtime_ns}-{st.st_size}"
+
+
+def render_file(roots, real):
+  """{version, html, warnings, title, error}; a failure fills `error` and
+  leaves `html` None, so the page keeps what it last showed."""
+  try:
+    ver = version(real)
+    with open(real, encoding="utf-8") as f:
+      text = f.read()
+    doc = model.parse(text)
+    task_href = None
+    if os.path.basename(real) == "Project.md":
+      def task_href(n):
+        task = os.path.join(os.path.dirname(real), "tasks", str(n), "Task.md")
+        return task if os.path.exists(task) else None  # mapped by rewrite
+    body = model.render(doc, roots.link_rewriter(real), task_href)
+    return {"version": ver, "html": body, "warnings": doc.warnings,
+            "title": doc.title, "error": None}
+  except Exception as e:  # noqa: BLE001 -- shown in the page, not swallowed
+    return {"version": None, "html": None, "warnings": [], "title": "",
+            "error": f"{type(e).__name__}: {e}"}
+
+
+def _static(name):
+  return resources.files("doc_reader").joinpath("static", name).read_text()
+
+
+def _page(title, body, data):
+  # `</` cannot appear inside the inline <script>; escaped outside the f-string
+  # because 3.10 allows no backslash inside one.
+  blob = json.dumps(data).replace("</", "<\\/")
+  return f"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{html.escape(title)}</title>
+<link rel="stylesheet" href="{KATEX}/katex.min.css">
+<link rel="stylesheet" href="/_static/reader.css">
+<script defer src="{KATEX}/katex.min.js"></script>
+<script defer src="{MERMAID}"></script>
+<script defer src="/_static/reader.js"></script>
+</head><body>
+<script type="application/json" class="dr-doc-data">{blob}</script>
+<div class="dr-banner" hidden></div>
+<nav class="dr-outline" aria-label="Outline"></nav>
+<main class="dr-doc">{body}</main>
+<div class="dr-toast" role="status" aria-live="polite"></div>
+</body></html>"""
+
+
+def _listing(roots, real, url):
+  rows = []
+  if url.count("/") > 3:
+    rows.append('<li><a href="../">../</a></li>')
+  for name in sorted(os.listdir(real), key=str.lower):
+    if name.startswith("."):
+      continue
+    full = os.path.join(real, name)
+    if os.path.isdir(full) or name.endswith(".md"):
+      href = roots.url_path(full)
+      if href:
+        label = name + ("/" if os.path.isdir(full) else "")
+        rows.append(f'<li><a href="{html.escape(href)}">{html.escape(label)}</a></li>')
+  return (f"<h1>{html.escape(url)}</h1>\n<ul class=\"listing\">\n"
+          + "\n".join(rows) + "\n</ul>")
+
+
+def make_app(cfg):
+  roots = Roots(cfg.roots)
+  routes = web.RouteTableDef()
+
+  def lookup(request, prefix):
+    """Map /<prefix>/<root>/<rel> to (real path, canonical /v/ url)."""
+    raw = request.raw_path.split("?", 1)[0]
+    real = roots.resolve(PREFIX + raw[len(prefix):])
+    if real is None or not os.path.exists(real):
+      raise web.HTTPNotFound(text=f"not found under any root: {request.path}")
+    return real, roots.url_path(real)
+
+  @routes.get("/")
+  async def index(request):
+    rows = "\n".join(
+        f'<li><a href="{PREFIX}{name}/">{html.escape(name)}</a> '
+        f"<code>{html.escape(path)}</code></li>"
+        for name, path in roots.roots.items())
+    return web.Response(content_type="text/html", text=_page(
+        "doc-reader", f"<h1>Roots</h1>\n<ul class=\"listing\">{rows}</ul>",
+        {"kind": "listing"}))
+
+  @routes.get(PREFIX + "{tail:.*}")
+  async def view(request):
+    real, canonical = lookup(request, PREFIX)
+    raw = request.raw_path.split("?", 1)[0]
+    # Compare decoded: aiohttp re-normalises a Location's escapes (%28 back to
+    # "("), so an encoded-only difference would redirect to itself for ever.
+    if unquote(canonical) != unquote(raw):
+      qs = "?" + request.query_string if request.query_string else ""
+      raise web.HTTPFound(canonical + qs)
+    if os.path.isdir(real):
+      return web.Response(content_type="text/html", text=_page(
+          canonical, _listing(roots, real, canonical), {"kind": "listing"}))
+    if not real.endswith(".md"):
+      ctype = mimetypes.guess_type(real)[0] or "application/octet-stream"
+      return web.FileResponse(real, headers={**RAW_HEADERS,
+                                             "Content-Type": ctype})
+    r = await asyncio.to_thread(render_file, roots, real)
+    data = {"kind": "doc", "path": real, "url": canonical,
+            "version": r["version"], "warnings": r["warnings"],
+            "error": r["error"]}
+    return web.Response(content_type="text/html", text=_page(
+        r["title"] or os.path.basename(real), r["html"] or "", data))
+
+  @routes.get("/frag/{tail:.*}")
+  async def frag(request):
+    real, _ = lookup(request, "/frag/")
+    return web.json_response(await asyncio.to_thread(render_file, roots, real),
+                             headers={"Cache-Control": "no-store"})
+
+  @routes.get("/events/{tail:.*}")
+  async def events(request):
+    real, _ = lookup(request, "/events/")
+    resp = web.StreamResponse(headers={
+        "Content-Type": "text/event-stream", "Cache-Control": "no-cache",
+        "X-Accel-Buffering": "no"})
+    await resp.prepare(request)
+    sent = candidate = None
+    last_write = time.monotonic()
+    try:
+      while True:
+        try:
+          ver = await asyncio.to_thread(version, real)
+        except FileNotFoundError:
+          ver = None  # mid atomic-replace; look again next poll
+        if ver is not None:
+          if sent is None:
+            sent = ver  # on (re)connect, so a missed change is caught
+            await resp.write(f"data: {ver}\n\n".encode())
+            last_write = time.monotonic()
+          elif ver != sent:
+            # Report a change once it holds for two polls, so a write in
+            # progress is not rendered half-done.
+            if ver == candidate:
+              sent = ver
+              await resp.write(f"data: {ver}\n\n".encode())
+              last_write = time.monotonic()
+            candidate = ver
+        if time.monotonic() - last_write > HEARTBEAT_S:
+          await resp.write(b": hb\n\n")
+          last_write = time.monotonic()
+        await asyncio.sleep(cfg.poll_interval_s)
+    except (ConnectionResetError, asyncio.CancelledError):
+      pass
+    return resp
+
+  @routes.post("/api/open")
+  async def api_open(request):
+    # Only the reader page may move editors. A JSON content type cannot be
+    # sent cross-site without a CORS preflight (which nothing here answers),
+    # and the Origin check covers browsers that send one anyway.
+    origin = request.headers.get("Origin")
+    if request.content_type != "application/json" or (
+            origin and urlsplit(origin).netloc != request.host):
+      raise web.HTTPForbidden(text="same-origin JSON only")
+    body = await request.json()
+    path = os.path.realpath(str(body.get("path") or ""))
+    # Checked before anything is read, written or sent to an editor.
+    if roots.canonical(path) is None or not os.path.isfile(path):
+      return web.json_response({"message": f"not under a root: {path}"},
+                               status=400)
+    sid = body.get("section_id") or None
+    with open(path, encoding="utf-8") as f:
+      disk_line = model.line_of(model.parse(f.read()), sid) if sid else None
+    resolved = disk_line is not None
+    line = disk_line or int(body.get("line") or 1)
+    nvim.write_state(cfg.state_file, path, sid, line)
+    resolve_cmd = ([sys.executable, os.path.abspath(sys.argv[0]), "section",
+                    "--stdin", path, sid] if sid else False)
+    result = await nvim.jump_all(cfg, path, sid, line, resolve_cmd)
+    result.update(line=line, resolved=resolved, message=nvim.message(result))
+    return web.json_response(result)
+
+  @routes.get("/_static/{name}")
+  async def static(request):
+    name = request.match_info["name"]
+    if name not in ("reader.js", "reader.css"):
+      raise web.HTTPNotFound()
+    ctype = "text/javascript" if name.endswith(".js") else "text/css"
+    return web.Response(text=_static(name), content_type=ctype,
+                        headers={"Cache-Control": "no-cache"})
+
+  app = web.Application()
+  app.add_routes(routes)
+  app["cfg"] = cfg
+  app["roots"] = roots
+  return app
+
+
+def serve(cfg):
+  web.run_app(make_app(cfg), host=cfg.bind, port=cfg.port,
+              print=lambda *_: print(f"doc-reader on {cfg.base_url} "
+                                     f"(bind {cfg.bind}:{cfg.port})"))

doc_reader/skills/doc-authoring/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: doc-authoring
+description: Rules for writing or editing any Markdown document for the user (research notes, reports, plans, explainers) so it reads well in doc-reader: stable section IDs, nested depth, figures, honest data, and how to answer questions about a document without editing it. Load before creating or changing such a document.
+---
+
+# Document Authoring
+
+The user reads these documents in doc-reader (`pip install nvim-doc-reader`): a browser
+page where sections fold, `j`/`k` walk headings, and `n` jumps every open
+Neovim to the section being read. That shapes the rules below.
+
+## Source
+
+- Markdown is the only source. Never write or commit generated HTML.
+- Raw HTML in the Markdown is shown as text, so don't use it.
+
+## Structure
+
+- Headings are the navigation. Each section starts with a short overview
+  paragraph; deeper material goes in nested subsections (intuition, worked
+  example, mechanism, derivation, evidence, caveats) that the reader can
+  leave folded.
+- Don't skip heading levels, and don't put headings inside lists or quotes:
+  those don't become sections.
+- A heading's ID is its GitHub slug, or an explicit `{#id}` at the end of the
+  heading. Give an explicit ID to any section other documents or messages
+  link to, so a rename doesn't break the link.
+- When editing, keep every existing `{#id}` and the heading hierarchy. Change
+  only the section you were asked to change, and keep concurrent edits by the
+  user or other agents intact (re-read the file right before writing).
+
+## Figures, charts, math
+
+Add them where they help understanding, not for decoration.
+
+- Concepts and flows: a ```` ```mermaid ```` block.
+- Illustrations: SVG in `figures/` next to the document.
+- Charts from data: a Python script and its data file in `figures/`, beside
+  the generated SVG/PNG it writes (e.g. `figures/perf.py`, `figures/perf.csv`,
+  `figures/perf.svg`), so the chart can be regenerated and checked.
+- Math: `$...$` inline, `$$...$$` on their own lines for display (KaTeX).
+- Reference assets with relative paths, give images alt text, and say in the
+  prose what the figure shows.
+
+## Honesty
+
+- Never fabricate empirical results. Numbers come from a run you can point
+  to; illustrative data is labelled synthetic, in the prose and the figure.
+
+## Questions about a document
+
+The user often pastes a question from the reader's `q` key, naming the file
+and section. Then:
+
+1. Answer in the conversation. Do not edit any file.
+2. Offer three follow-ups: integrate the answer into the section, attach it
+   as a new nested subsection, or keep it as a note only.
+3. Edit only after the user picks one, and only that section.
+
+## Linking the user to a document
+
+`docread url <file> <line>` prints the reader link for the section containing
+that line. Give that link plus the file path (for editing). If `docread`
+isn't available or the file is outside the served roots, give the path alone.

doc_reader/static/reader.css

@@ -0,0 +1,167 @@
+:root {
+  --bg: #fdfdfc;
+  --fg: #1f2328;
+  --dim: #6a737d;
+  --rule: #e3e5e8;
+  --code-bg: #f3f4f6;
+  --accent: #2f6fdd;
+  --cur-bg: #eaf1fd;
+  --banner-bg: #fff4d6;
+  --banner-fg: #5c4400;
+  --outline-w: 270px;
+  color-scheme: light;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --bg: #16181c;
+    --fg: #e3e5e8;
+    --dim: #9aa3ad;
+    --rule: #2d3138;
+    --code-bg: #22252b;
+    --accent: #7aa7ff;
+    --cur-bg: #1f2a3d;
+    --banner-bg: #3d3216;
+    --banner-fg: #f3dc9b;
+    color-scheme: dark;
+  }
+}
+:root[data-theme="dark"] {
+  --bg: #16181c; --fg: #e3e5e8; --dim: #9aa3ad; --rule: #2d3138;
+  --code-bg: #22252b; --accent: #7aa7ff; --cur-bg: #1f2a3d;
+  --banner-bg: #3d3216; --banner-fg: #f3dc9b; color-scheme: dark;
+}
+
+* { box-sizing: border-box; }
+html { scroll-padding-top: 15vh; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font: 16px/1.6 system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+a { color: var(--accent); }
+a.unreachable { color: var(--dim); text-decoration: underline dotted; }
+
+/* ---------------------------------------------------------------- layout */
+.dr-doc {
+  max-width: 820px;
+  margin: 0 auto;
+  padding: 24px 16px 60vh;
+}
+.dr-outline {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: var(--outline-w);
+  height: 100vh;
+  overflow-y: auto;
+  padding: 20px 12px 20px 16px;
+  border-right: 1px solid var(--rule);
+  font-size: 13px;
+  line-height: 1.45;
+}
+.dr-outline ul { list-style: none; margin: 0; padding-left: 12px; }
+.dr-outline > ul { padding-left: 0; }
+.dr-outline a { display: block; padding: 2px 6px; border-radius: 4px; color: var(--dim);
+             text-decoration: none; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.dr-outline a:hover { color: var(--fg); }
+.dr-outline a.cur { color: var(--fg); background: var(--cur-bg); font-weight: 600; }
+/* Hidden until `o`. Wide screens dock it beside the text; narrow ones lay
+   it over the text. */
+.dr-outline { display: none; background: var(--bg); z-index: 5; }
+body.show-outline .dr-outline { display: block; }
+@media (min-width: 1180px) {
+  body.show-outline .dr-doc { margin-left: calc(var(--outline-w) + max(24px, (100vw - var(--outline-w) - 820px) / 2)); }
+}
+
+/* ---------------------------------------------------------------- sections */
+section { position: relative; }
+.sec-h { cursor: pointer; position: relative; border-radius: 4px; margin-left: -8px; padding-left: 8px; }
+.sec-h::before {
+  content: "\25BE";
+  position: absolute;
+  left: -14px;
+  color: var(--dim);
+  font-size: 0.7em;
+  top: 50%;
+  transform: translateY(-50%);
+}
+section.collapsed > .sec-h::before { content: "\25B8"; }
+section.collapsed > .sec-h::after { content: " \2026"; color: var(--dim); font-weight: 400; }
+section.collapsed > :not(.sec-h) { display: none; }
+section.cur > .sec-h { background: var(--cur-bg); box-shadow: -3px 0 0 var(--accent); }
+
+h1, h2, h3, h4, h5, h6 { line-height: 1.25; margin: 1.4em 0 0.5em; }
+h1 { font-size: 1.9em; }
+h2 { font-size: 1.45em; border-bottom: 1px solid var(--rule); padding-bottom: 0.2em; }
+h3 { font-size: 1.2em; }
+h4 { font-size: 1.05em; }
+h5, h6 { font-size: 0.95em; color: var(--dim); }
+
+/* ---------------------------------------------------------------- content */
+p, ul, ol, table, pre, blockquote { margin: 0 0 1em; }
+code { background: var(--code-bg); padding: 0.1em 0.35em; border-radius: 4px; font-size: 0.9em;
+       font-family: ui-monospace, "Cascadia Code", Menlo, Consolas, monospace; }
+pre { background: var(--code-bg); padding: 12px 14px; border-radius: 6px; overflow-x: auto; }
+pre code { background: none; padding: 0; }
+pre.mermaid { background: none; text-align: center; }
+blockquote { border-left: 3px solid var(--rule); margin-left: 0; padding-left: 14px; color: var(--dim); }
+table { border-collapse: collapse; display: block; overflow-x: auto; }
+th, td { border: 1px solid var(--rule); padding: 5px 10px; text-align: left; }
+img { max-width: 100%; height: auto; }
+div.math { overflow-x: auto; margin: 0 0 1em; }
+ul.listing { list-style: none; padding: 0; }
+ul.listing li { padding: 3px 0; }
+
+/* ---------------------------------------------------------------- chrome */
+.dr-banner {
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  background: var(--banner-bg);
+  color: var(--banner-fg);
+  padding: 8px 16px;
+  font-size: 14px;
+}
+.dr-toast {
+  position: fixed;
+  right: 16px;
+  bottom: 16px;
+  max-width: calc(100vw - 32px);
+  background: var(--fg);
+  color: var(--bg);
+  padding: 8px 14px;
+  border-radius: 6px;
+  font-size: 14px;
+  opacity: 0;
+  transition: opacity 0.2s;
+  pointer-events: none;
+  z-index: 20;
+}
+.dr-toast.show { opacity: 0.95; }
+.overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.45);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 30;
+  padding: 16px;
+}
+.overlay .panel {
+  background: var(--bg);
+  color: var(--fg);
+  border-radius: 8px;
+  padding: 18px 22px;
+  max-width: 560px;
+  width: 100%;
+  max-height: 90vh;
+  overflow: auto;
+}
+.overlay h2 { margin-top: 0; border: 0; }
+.overlay td { border: 0; padding: 3px 10px 3px 0; }
+.overlay textarea { width: 100%; font: 13px ui-monospace, monospace; }
+kbd { background: var(--code-bg); border: 1px solid var(--rule); border-radius: 4px;
+      padding: 1px 6px; font: 13px ui-monospace, monospace; white-space: nowrap; }
+.dim { color: var(--dim); font-size: 13px; }