Reference page fixes: sticky headings, parameters, tmux links and alignment

CONTRIBUTING.md

@@ -89,10 +89,11 @@ $ pnpm test
 The outer loop includes the `*.outer.test.ts` integration suites, which seed
 the full API catalog or exercise subprocess shutdown. It also adds type
 checks and starts its own Astro development server
-from current source. Browser checks cover prose, an MCP table, API equivalents,
-and phone dropdown placement at 1440, 768, and 390 pixels. The sampled renderer
-also checks homepage choices and uses `node site/scripts/check-dev.mjs --sample`.
-It does not reuse `_site`. The runtime budgets are under 2, 10, and 60 seconds for inner,
+from current source. Browser checks cover prose, an MCP table, row permalinks,
+API equivalents, and phone dropdown placement at 1440, 768, and 390 pixels. The
+sampled renderer also checks homepage choices and uses
+`node site/scripts/check-dev.mjs --sample`. It does not reuse `_site`. The
+runtime budgets are under 2, 10, and 60 seconds for inner,
 medium, and outer respectively; measure the complete pnpm command when
 changing a loop. `test:fast` aliases medium. The runner stops an over-budget
 loop and fails.
@@ -131,6 +132,36 @@ Install the pinned Chromium build for local browser checks with
 that build and its system dependencies before the publication audit.
 The standard ten-second browser timeout increases to twenty seconds on CI.
 
+Each engine aligns the sticky Members and group headings of a reference page
+differently. The publication audit checks them in Chromium; install Firefox
+and WebKit to check all three:
+
+```console
+$ pnpm --filter @libtmux/site exec playwright install firefox webkit
+```
+
+Then run the sticky heading check, which starts its own server and drives
+focus, link, repeated link and typed hash arrivals in each engine:
+
+```console
+$ node site/scripts/check-dev.mjs --api-sticky
+```
+
+Kind marks centre their ink by measurement, and a legend chip, split chip or
+modifier chip is one line of text. The badge gate reads the pixels of real pages
+at 1x and at a real 2x device scale factor (Chromium launched with the factor,
+because the emulated factor snaps text to CSS pixels), in light and dark. It
+measures the mark that leads a name in cards and lists, the related-APIs
+chips, the group headings, the MCP sidebar's rule (a mark only in a group that
+mixes kinds, and no gutter) and that the API tree keeps its gutter, and it
+checks that only the first mention of a name in a section carries a mark. Each
+check ends with a negative control that breaks what it holds and requires the
+gate to notice:
+
+```console
+$ node site/scripts/check-dev.mjs --badge-centring
+```
+
 Keep the complete assembly, all output suites, link audits, source/model
 freshness, and full browser matrix in the publication audit:
 
@@ -177,6 +208,21 @@ the index:
 $ node scripts/gen-mentions.mjs
 ```
 
+Workspace prose links a code span that names a CLI command, option or
+configuration key to its entry in the port's CLI Manual or Configuration
+reference. Those destinations come from an index of the workspace pages. After
+adding or renaming a CLI page, a table of options, or a table of keys,
+regenerate it:
+
+```console
+$ node scripts/gen-workspace-entities.mjs
+```
+
+A bare name links only on a user-facing workspace page, where it outranks a
+library symbol or tmux name of the same spelling. `<program> <command>` links
+on any page of a port that ships the program. Internals pages and the language
+API index keep their library symbols.
+
 The publication audit checks index freshness, rendered links, navigation targets,
 and table layout at desktop, tablet, and phone widths.
 

WRITING.md

@@ -339,6 +339,16 @@ Run the workspace linter:
 $ pnpm run lint
 ```
 
+### tmux keys
+
+Write a tmux key in tmux's notation, in backticks: `C-b d` for a sequence,
+`M-x`, `C-c`. The site renders it as a key cap; Markdown and agent exports
+keep the backticks. A modified key, and any key in a list with one, always
+qualifies. A bare name or character such as `Enter` or `q` qualifies beside the
+word "key" ("the `Enter` key") or "press". Text typed into a pane, like the
+word `Enter`, stays code. [`tmux-keys.ts`](site/src/lib/tmux-keys.ts) holds the
+rule, and the manual pages apply it to the manual's own key tables and bindings.
+
 ### Durable links
 
 Link to repository-relative files for local guidance. For external source

notes/gp-sphinx-parity.md

@@ -96,6 +96,30 @@ per-language table is in `packages/api-model/src/doc/roles.ts`; adding a
 syntax means adding a matcher, not widening an existing one, because the
 guards are what keep `[see below]` from becoming a link.
 
+**Badges: kind is a filled chip, a modifier is an outline on the same box.**
+gp-sphinx draws a modifier as a monospace outline pill at 0.68rem, with its hue
+scoped to `dl.py`. This site draws a kind as the legend chip (the mark and the
+word in one filled token) and a modifier on that chip's geometry: the same
+snapped height, radius, sans 600 word and baseline, so a declaration row reads
+as one family and an entry has one loud thing. Where it differs:
+
+- The modifier keeps gp-sphinx's hue for the same word (async violet, abstract
+  indigo, classmethod and static amber, final and readonly green, the rest a
+  readable grey) from the same `--gp-sphinx-badge-mod-*` tokens, but applies
+  it wherever a modifier sits, not only inside `dl.py`. The member list's
+  `inherited` and a card's context badge are modifiers too.
+- The light amber ink is five percent darker than the token. The token is
+  under 4.5:1 on the declaration band, and the darker ink keeps the hue. Dark
+  mode takes the token as it is.
+- `package` is an outline in the types hue, no longer a second filled badge.
+- `deprecated` is a status and takes the warning ink and border, which the
+  vendored `dl.py` default would otherwise repaint grey.
+- The word is not lowercased by CSS: a package name keeps its case.
+
+`check-style-parity.mjs` compares the eight treatments above and none of them
+is a badge, so this divergence is held by `test/modifier-chips.test.ts` and the
+modifier chips in `check-badge-centring.mjs`, not by that check.
+
 **The page shell is this site's, not Furo's.** Header, footer, search, version
 switcher and port switcher are shared with the rest of libtmux.org. Only the
 reference *content* is held to parity. Under reduced motion the API surface

notes/status.md

@@ -162,7 +162,7 @@ field at all) — resolves every ledger's cited evidence against that port's
 own checkout (a test file for .NET, a test function for Go, a contract
 test class for Java), and classifies each row `test-verified` / `claimed`
 / `unknown` by what actually resolves, not by how confident the ledger's
-prose sounds. `site/src/pages/parity.astro` renders the result:
+prose sounds. `site/src/pages/meta/parity.astro` renders the result:
 per-port summaries, a cross-port module table, and an explicit note that
 the four ledgers are not pinned to the same Python revision (.NET and Java
 pin `c4a980b`, Swift pins `988b02a`, Go records none). Spot-checked: Java's

notes/tmux-catalog.md

@@ -0,0 +1,104 @@
+# tmux catalog: options, hooks and format variables
+
+Prose across the site names tmux options (`destroy-unattached`), hooks
+(`session-created`) and format variables (`session_attached`) that the
+CLI Manual and the C source reference do not index. The catalog is a browser
+for those names, built from the same data tmux uses, so any page can link to
+the entry for the tmux release it describes.
+
+## Entry kinds
+
+| Kind | Fields | Source in the tmux tree |
+| ---- | ------ | ----------------------- |
+| `option` | scope (`server`, `session`, `window`, `pane`), type, default, minimum, maximum, unit, choices, array and style flags, accepted spellings | A row of `options_table[]` in `options-table.c`; choice lists, symbolic defaults and ranges resolve through the same file and `tmux.h`. |
+| `hook` | scope, the command an `after-` hook follows, control mode notification of the same name, firing sites | `OPTIONS_TABLE_*HOOK` rows of `options_table[]`; firing sites are the literal names passed to `notify_*` and `cmdq_insert_hook` in `*.c`. |
+| `format` | type (`string` or `time`), the object it describes, short form, callback | `format_table[]` in `format.c`, plus names the manual documents that are set elsewhere (`format_add`, `cmdq_add_format`, `%s_suffix` patterns). The object is the first `ft->` member the callback reads. |
+
+Descriptions come from the tmux.1 of the same release: the `OPTIONS` list, the
+`HOOKS` list (a hook without its own text falls back to its `%name` entry in
+`CONTROL MODE`, and an `after-` hook to the shared after-hook paragraph) and
+the `Variable name` tables. An option the manual omits keeps the `.text` from
+the option table and says so. A format variable the manual omits is listed as
+undocumented rather than dropped.
+
+Other tables would justify more kinds (control mode notifications, layouts,
+key tables). They are not part of this change.
+
+## Extraction
+
+`scripts/gen-tmux-catalog.mjs` reads the pinned commit of each release in
+`site/src/data/tmux/versions.json` and writes
+`site/src/data/tmux/catalog/<version>.json`. Output is sorted and
+deterministic. Every entry carries `file:line` at that commit.
+
+The script refuses to guess: an unresolved symbol in a table cell, a format
+variable with no source location, or a manual snapshot whose `manualSha256`
+differs from `tmux.1` at the commit stops the run. `--check` verifies digests
+and shape without a checkout, and with `--source` regenerates and compares.
+`gen-tmux-catalog.negative.mjs` shows each failure.
+
+## Pages and URLs
+
+```text
+/tmux/<version>/catalog/                      index
+/tmux/<version>/catalog/options/              kind page, grouped like the tree
+/tmux/<version>/catalog/options/<name>/       entry page
+/tmux/<version>/catalog/hooks/<name>/
+/tmux/<version>/catalog/formats/<name>/
+/tmux/<version>/catalog/tree.json             sidebar tree and search inventory
+/tmux/<version>/catalog/<kind>/<name>.preview.json
+```
+
+`<version>` is a pinned release or `latest`. The page uses the C reference's
+layout: a sidebar tree with search and All, Options, Hooks and Formats tabs, kind
+badges, and an entry page with facts, description, releases, source and
+"Used by". A name missing from another release links that release's section.
+
+The picker and the tmux sidebar list it as "Options, hooks and formats", a
+third section beside "CLI Manual" and "C source reference".
+
+## Linking
+
+`tmuxEntityHref(kind, name, version)` in `site/src/lib/tmux-links.ts` is the one
+place a tmux name becomes a destination. A command resolves to its CLI Manual
+page; an option, hook or format variable resolves to its catalog entry, and an
+entry page links back to the manual text through `tmuxManualEntityHref`.
+`tmuxMentions` finds the names in a run of text, and every surface uses it: API
+docstrings (`ApiDoc`), guides and topics (`rehype-api-links`), their Markdown
+exports (`prose-markdown`, `symbol-markdown`) and the CLI Manual HTML
+(`tmux-catalog-html.ts`). Hover cards for catalog links come from
+`<entry>.preview.json`.
+
+Which options, hooks and variables count as a mention is decided in
+`tmux-catalog-links.ts`, in this order:
+
+1. Only code literals link. Prose names an entry without being a reference to
+   it.
+2. A language API link wins. A name the library documents as its own symbol
+   links there; the catalog link is the fallback, and a command claims a span
+   that holds one.
+3. A whole literal links, quoted or not, with an array index
+   (`after-new-window[0]`). A hyphenated option or hook links as a separate word
+   of a longer run, and an underscored variable links inside `#{...}`.
+4. A single word (`status`, `host`) links only beside the word `option`, `hook`
+   or `variable`, as the argument of `set-option`, `set-hook` and their read
+   forms, or as `#{word}`. A name more than one kind uses, or a command's name,
+   links only when a neighbouring word picks the kind; otherwise it stays plain.
+5. Inside `#{...}` only the variable position links (after `#{`, `#{?` or
+   `E:`, `T:`, `t:` and similar); words after a comparison stay literal.
+6. Displayed examples, flags (`--status-left`), control notifications
+   (`%session-renamed`), user options (`@name`) and paths never link.
+7. A name absent from the selected release stays plain.
+
+Library members that wrap a family (`set_hook`, `show_hooks`, `Hooks`) link to
+the matching catalog section through the concepts in
+`packages/api-model/src/concepts.ts` and the wrapper types listed in
+`tmux-catalog.ts`. An entry page lists, per port, the members whose
+documentation names it, and a C declaration (`options_table`, `format_cb_*`,
+`notify_*`) links to its catalog entries.
+
+## Open questions
+
+- The URL plural (`options`, `hooks`, `formats`) against the singular used for
+  kinds in code.
+- Whether single-word names should ever link without a context word.

packages/api-model/src/doc/csharp.ts

@@ -77,6 +77,8 @@ function prose(xml: string): string {
 export interface ParsedXmlDoc {
   doc: DocBlock
   params: Map<string, string>
+  /** `<typeparam name="T">`, by parameter name. */
+  typeParams: Map<string, string>
   returnsDoc?: string
   raises: { type: string; doc?: string }[]
 }
@@ -95,6 +97,13 @@ export function parseXmlDoc(raw: string): ParsedXmlDoc {
     if (name && text) params.set(name, text)
   }
 
+  const typeParams = new Map<string, string>()
+  for (const s of sections(raw, 'typeparam')) {
+    const name = attr(s.attrs, 'name')
+    const text = prose(s.body)
+    if (name && text) typeParams.set(name, text)
+  }
+
   const returnsDoc = prose(sections(raw, 'returns')[0]?.body ?? '') || undefined
 
   const raises = sections(raw, 'exception')
@@ -136,6 +145,7 @@ export function parseXmlDoc(raw: string): ParsedXmlDoc {
       examples: examples.length ? examples : undefined,
     },
     params,
+    typeParams,
     returnsDoc,
     raises,
   }

packages/api-model/src/doc/go.ts

@@ -71,5 +71,5 @@ export function parseGoDoc(raw: string, parser: Parser): ParsedMarkdownDoc {
   }
   const first = blocks[0]?.kind === 'prose' ? blocks.shift()!.text : ''
   return { doc: { summary: first.replace(/\s+/g, ' ').trim(), body: blocks.map((block) => block.text).join('\n\n') || undefined },
-    params: new Map(), raises: [] }
+    params: new Map(), typeParams: new Map(), raises: [] }
 }

packages/api-model/src/doc/javadoc.ts

@@ -26,7 +26,7 @@ import { parseMarkdownDocFull, type ParsedMarkdownDoc } from './markdown.ts'
  * the block's spelling rather than an inline literal, and an inline pass that
  * reached it first would leave the fence holding a stray brace.
  */
-const PRE_BLOCK = /<pre>\s*(?:\{@code\b)?\s*\n?([\s\S]*?)\n?\s*\}?\s*<\/pre>/g
+const PRE_BLOCK = /<pre>\s*(?:\{@code\b)?[ \t]*\n?([\s\S]*?)\n?\s*\}?\s*<\/pre>/g
 
 /** Inline formatting, as `[tag, markdown]`. `<code>` is javadoc's `{@code}`. */
 const INLINE: [RegExp, string][] = [
@@ -35,11 +35,16 @@ const INLINE: [RegExp, string][] = [
   [/<code>([\s\S]*?)<\/code>/g, '`$1`'],
 ]
 
+const indentation = (line: string): number => /^[ \t]*/.exec(line)![0].length
+
 /** Translate one javadoc comment body into Markdown. */
 export function javadocToMarkdown(raw: string): string {
   let text = raw.replace(PRE_BLOCK, (_, code: string) => {
-    const lines = code.split('\n').map((l) => l.replace(/^\s*/, ''))
-    return `\n\`\`\`java\n${lines.join('\n')}\n\`\`\`\n`
+    const lines = code.split('\n')
+    const margin = Math.min(...lines.filter((line) => line.trim()).map(indentation))
+    // Only the block's common margin comes off; the rest is the code's own indentation.
+    const body = lines.map((line) => (line.trim() ? line.slice(margin) : '')).join('\n')
+    return `\n\`\`\`java\n${body}\n\`\`\`\n`
   })
 
   // `<p>` opens a paragraph in javadoc and closes nothing; every one of

packages/api-model/src/doc/markdown.ts

@@ -66,7 +66,7 @@ const HEADING = /^\s*#{1,3}\s+(Examples?|Panics|Errors|Safety|Notes?|Returns?|Ar
  * and none of them reached a field list, because this parser treated the
  * whole comment as prose.
  */
-const BLOCK_TAG = /^\s*@(param|arg|argument|returns?|throws|exception|deprecated|since)\b\s*(.*)$/
+const BLOCK_TAG = /^\s*@(param|arg|argument|returns?|throws|exception|deprecated|since|typeParam|typeparam|template|tparam)\b\s*(.*)$/
 
 /**
  * A Markdown link definition: `` [`Window`]: crate::Window ``.
@@ -124,6 +124,8 @@ function callout(quoted: string[]): { kind: string; text: string } | undefined {
 export interface ParsedMarkdownDoc {
   doc: DocBlock
   params: Map<string, string>
+  /** `@typeParam T`, `@template T`, `@tparam T`, and Javadoc's `@param <T>`, by parameter name. */
+  typeParams: Map<string, string>
   returnsDoc?: string
   raises: { type: string; doc?: string }[]
 }
@@ -157,6 +159,7 @@ export function parseMarkdownDocFull(raw: string, defaultLang = 'text'): ParsedM
   let inExamples = false
 
   const params = new Map<string, string>()
+  const typeParams = new Map<string, string>()
   const raises: { type: string; doc?: string }[] = []
   const admonitions: { kind: string; text: string }[] = []
   /** The blockquote currently collecting lines, callout or not. */
@@ -177,7 +180,10 @@ export function parseMarkdownDocFull(raw: string, defaultLang = 'text'): ParsedM
   const closeTag = () => {
     if (!tag) return
     const text = tag.text.join(' ').replace(/\s+/g, ' ').trim()
-    if (tag.kind === 'param' && tag.name) params.set(tag.name, text)
+    const javadocTypeParam = tag.kind === 'param' ? /^<(\w+)>$/.exec(tag.name ?? '')?.[1] : undefined
+    if (tag.kind === 'typeparam' && tag.name) typeParams.set(tag.name, text.replace(/^-\s*/, ''))
+    else if (javadocTypeParam) typeParams.set(javadocTypeParam, text)
+    else if (tag.kind === 'param' && tag.name) params.set(tag.name, text)
     else if (tag.kind === 'returns') returnsDoc = text || undefined
     else if (tag.kind === 'throws' && tag.name) raises.push({ type: tag.name, doc: text || undefined })
     tag = undefined
@@ -224,15 +230,17 @@ export function parseMarkdownDocFull(raw: string, defaultLang = 'text'): ParsedM
       closeTag()
       const kind = /^(param|arg|argument)$/.test(block[1])
         ? 'param'
-        : /^returns?$/.test(block[1])
-          ? 'returns'
-          : /^(throws|exception)$/.test(block[1])
-            ? 'throws'
-            : block[1]
+        : /^(typeParam|typeparam|template|tparam)$/.test(block[1])
+          ? 'typeparam'
+          : /^returns?$/.test(block[1])
+            ? 'returns'
+            : /^(throws|exception)$/.test(block[1])
+              ? 'throws'
+              : block[1]
       // `@param name description` — the name is the first word for param and
       // throws, and absent for the rest.
       const rest = block[2] ?? ''
-      const needsName = kind === 'param' || kind === 'throws'
+      const needsName = kind === 'param' || kind === 'throws' || kind === 'typeparam'
       const [first, ...tail] = rest.split(/\s+/)
       tag = needsName
         ? { kind, name: first || undefined, text: tail }
@@ -278,6 +286,7 @@ export function parseMarkdownDocFull(raw: string, defaultLang = 'text'): ParsedM
       admonitions: admonitions.length ? admonitions : undefined,
     },
     params,
+    typeParams,
     returnsDoc,
     raises,
   }