Example style guide, oxfmt, and a code font that fits 80 columns

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Format source with oxfmt
+449d17627fc405743130964a45b184b2fb6c6af0

.github/example-width.toml

@@ -0,0 +1,49 @@
+width = 80
+markdown = ["**/*.md"]
+shared_digest = "28b74bae1f7a06731fea5a150cbde4430179b7788b7564ea1644c3951df8531b"
+checker_digest = "eb87afceb3fc8f11ef5a478cd38f901ef3950e89ff94fbe0ca281c0cfc1a0e2e"
+allow_ceiling = 8
+
+[[exclude]]
+glob = "notes/research/**"
+reason = "dated research notes with pasted tool output and probes, kept as written; no reader copies code from them"
+
+[[allow]]
+path = "site/src/content/docs/ports/py/examples/capture-pane-output.md"
+line = "    --with 'libtmux @ git+https://github.com/tmux-python/libtmux@9fdd083a8181a827889337b63cd4e6daea661a8c' \\"
+reason = "one quoted PEP 508 requirement pinning libtmux to a commit; the URL and revision cannot break"
+
+[[allow]]
+path = "site/src/content/docs/ports/py/guides/attaching-to-tmux.md"
+line = "    --with 'libtmux @ git+https://github.com/tmux-python/libtmux@9fdd083a8181a827889337b63cd4e6daea661a8c' \\"
+reason = "one quoted PEP 508 requirement pinning libtmux to a commit; the URL and revision cannot break"
+
+[[allow]]
+path = "WRITING.md"
+line = "Session session = await server.CreateSessionAsync(new NewSessionRequest(name: \"work\"));"
+reason = "the Bad example in the port block; it shows the width problem the Good example fixes"
+
+[[allow]]
+path = "site/src/content/docs/ports/julia/examples/observe-output.md"
+line = "with_server(; tmux=get(ENV, \"LIBTMUX_TEST_TMUX\", \"tmux\"), env=environment) do server"
+reason = "a copy of libtmux-julia's examples/output_stream.jl at the revision site/test/fixtures/program-examples.json pins (6f62bd7), checked by sha256; libtmux-julia#7 fits the source, and this line follows when the pin moves"
+
+[[allow]]
+path = "site/src/content/docs/ports/julia/examples/owned-capture.md"
+line = "        println(\"Captured \", string(pane.id), \": \", ncodeunits(screen), \" screen bytes\")"
+reason = "a copy of libtmux-julia's examples/owned_capture.jl at the revision site/test/fixtures/program-examples.json pins (6f62bd7), checked by sha256; libtmux-julia#7 fits the source, and this line follows when the pin moves"
+
+[[allow]]
+path = "site/src/content/docs/ports/julia/examples/shared-windows.md"
+line = "            only(windows(onlymatch(SessionWhere(name=\"ops\"), sessions(captured)))).ref"
+reason = "a copy of libtmux-julia's examples/shared_windows.jl at the revision site/test/fixtures/program-examples.json pins (6f62bd7), checked by sha256; libtmux-julia#7 fits the source, and this line follows when the pin moves"
+
+[[allow]]
+path = "site/src/content/docs/ports/julia/examples/shared-windows.md"
+line = "    selected = filter(PaneWhere(active=true, window=WindowWhere(name=\"api\")), panes(snap))"
+reason = "a copy of libtmux-julia's examples/shared_windows.jl at the revision site/test/fixtures/program-examples.json pins (6f62bd7), checked by sha256; libtmux-julia#7 fits the source, and this line follows when the pin moves"
+
+[[allow]]
+path = "site/src/content/docs/ports/julia/examples/shared-windows.md"
+line = "            only(Iterators.filter(p -> p.active && p.window.name == \"api\", panes(snap))).ref"
+reason = "a copy of libtmux-julia's examples/shared_windows.jl at the revision site/test/fixtures/program-examples.json pins (6f62bd7), checked by sha256; libtmux-julia#7 fits the source, and this line follows when the pin moves"

.github/workflows/shared-examples.yml

@@ -0,0 +1,36 @@
+name: shared-examples
+
+# The example rules are one text and one checker in every libtmux port. This
+# job compares them with each port's default branch, so it needs the network
+# and stays out of the local test loops. It runs on a change to the shared
+# files or this gate, and weekly; a port that drifts on its own surfaces in
+# the weekly run instead of failing unrelated pull requests here.
+
+on:
+  push:
+    branches: [main]
+    paths: &shared
+      - WRITING.md
+      - scripts/check_example_width.py
+      - scripts/check_shared_examples.py
+      - .github/workflows/shared-examples.yml
+  pull_request:
+    paths: *shared
+  schedule:
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - run: python3 scripts/check_shared_examples.py --self-test
+      - run: python3 scripts/check_shared_examples.py
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

.oxfmtrc.json

@@ -0,0 +1,21 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 120,
+  "ignorePatterns": [
+    "pnpm-lock.yaml",
+    "site/src/data/**",
+    "site/public/**",
+    "_site/**",
+    "dist/**",
+    ".port-sources/**",
+    "infra/**",
+    "**/*.json",
+    "**/*.yml",
+    "**/*.yaml",
+    "**/*.cff",
+    "**/*.css",
+    "**/*.md",
+    "**/*.mdx"
+  ]
+}

AGENTS.md

@@ -11,7 +11,10 @@ requested work.
 
 - Environment, Oxlint, formatting, tests, and pull requests:
   [CONTRIBUTING.md](CONTRIBUTING.md).
-- Documentation, user-facing text, comments, and commits: [WRITING.md](WRITING.md).
+- Documentation, user-facing text, comments, commits, and any code example
+  (example programs, console recipes, Markdown code blocks):
+  [WRITING.md](WRITING.md), and its [Documented examples that
+  run](WRITING.md#documented-examples-that-run) section for code a reader sees.
 
 Each guide is the single home for its subject.
 

CONTRIBUTING.md

@@ -47,15 +47,68 @@ Run lint across the workspace and build scripts:
 $ pnpm run lint
 ```
 
-The theme package retains Biome in its formatting script; it is not the
-workspace lint gate. This command writes changes, so review its diff:
+`oxfmt` formats the site's own TypeScript, JavaScript, and Astro source at
+120 columns, with no semicolons and single quotes. It is pinned in the pnpm
+catalog; `.oxfmtrc.json` lists what it skips. Markdown stays out because
+`site/test/complete-examples.test.ts` pins fenced programs by hash. Check
+formatting, or rewrite files in place and review the diff:
 
 ```console
-$ pnpm --filter @libtmux/theme format
+$ pnpm run format:check
+```
+
+```console
+$ pnpm run format
 ```
 
 ## Checks
 
+Hold hand-written code fences to 80 columns. The check reads
+`.github/example-width.toml`, which lists the surfaces it covers and each
+line allowed to stay wider, with its reason:
+
+```console
+$ python3 scripts/check_example_width.py
+```
+
+The `--self-test` flag plants a failure for every rule the check enforces,
+plus clean controls.
+The medium loop and the publication audit run both.
+
+The checker and the shared section of `WRITING.md` must match every other
+libtmux port. CI compares them with each port's default branch weekly, and
+on pushes to `main` and pull requests that change them or the comparison
+itself. The comparison needs the network, so it is not part of the local
+loops:
+
+```console
+$ python3 scripts/check_shared_examples.py
+```
+
+A port with no checker or shared section fails, unless the script's
+`PENDING` list names it with a reason and the date it was listed. Every
+port is pending until its example-style change merges; a pending port that
+already has both files fails until it leaves the list, and an entry older
+than 30 days fails until it is merged or given a new reason and date.
+To roll out a change to the shared text or checker, record the digests
+the ports still carry in the script's `PREVIOUS` with the last day they
+are accepted, so ports can merge one at a time.
+
+A port the script cannot read, such as a private repository, goes in
+`NOT_FETCHED` with the place it is compared instead, and the script
+prints a notice for it; every port is public, so the list is empty. The
+script also lists the public, non-archived repositories of the `libtmux`
+organisation through the GitHub REST API, and fails for any repository
+outside `PORTS` whose `WRITING.md` carries the shared section, so a new
+port cannot adopt it unseen. Set `GITHUB_TOKEN` to avoid the
+unauthenticated rate limit.
+
+The script's `--self-test` runs without the network. It plants checker
+and text drift, a missing file, a stale pending entry, an entry for an
+unknown port, a pending port with drift or with both files, a previous
+digest inside and past its window, a port it must not fetch, an unlisted
+adopter, and an unlisted repository without the markers.
+
 Run workspace type checks:
 
 ```console
@@ -118,6 +171,12 @@ 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.
 
+`site/test/code-block-width.outer.test.ts` opens a built page at 1024 and
+1280 pixels and checks that its code blocks fit 80 columns. It measures in
+Chrome, because the bundled Chromium draws the code font narrower than the
+browsers readers use. It reads the assembled `_site`, so only the
+publication audit runs it; the loops skip it.
+
 Keep the complete assembly, all output suites, link audits, source/model
 freshness, and full browser matrix in the publication audit:
 

WRITING.md

@@ -167,10 +167,92 @@ project and `main.cpp`, installs the library with its public testing component,
 and builds against that installed prefix. The native source suite checks the
 same files against private tmux servers, including operation failure and cleanup.
 
-Put explanatory comments on separate lines above the code they describe.
-Limit example comments to 100 columns, including indentation; prefer shorter
-lines that fit the code panel. Put long source links and attribution in prose
-outside the code block.
+Put long source links and attribution in prose outside the code block.
+
+<!-- shared:examples -->
+
+An example is code written for a reader: a program under `examples/`, code in
+a doc comment or docstring, and every fenced block in a README or docs page.
+Shell blocks also follow [Code blocks](#code-blocks).
+
+The text between the shared markers is the same in every libtmux port.
+Change it in all of them together.
+
+### Width
+
+- **Examples stay within 80 columns.** They render in fixed-width boxes that
+  scroll sideways, and 80 columns fits a libtmux.org code block in a
+  laptop-width window. Comments inside examples wrap at 80 too.
+- **The width check enforces it.** It reads the tracked files that
+  `.github/example-width.toml` names and fails on a wider line. It measures
+  the whole source line, so code in a doc comment counts its indent and
+  comment marker. It skips output (a fence tagged `text`, and what a
+  `console` block prints), hidden setup lines, and a line that is only a URL;
+  an untagged fence counts as code.
+- **A line that must stay wider is listed there with its reason.** An entry
+  that no longer matches a line fails the check, so no stale entry stays.
+- **The formatter's width is the hard limit for all other source.** Example
+  directories set their formatter to 80 where the formatter takes a width.
+
+### Reaching 80
+
+- **Change the code, not the line breaks.** A formatter rejoins any line that
+  fits its width. Name a sub-expression, use a short example name, hide setup
+  the reader does not need, or print less.
+- **Break at the outermost level when a break is still needed:** after an
+  opening parenthesis with one argument per line, one call per line in a
+  chain, one field per line in a literal.
+- **Put a comment on its own line above the code it explains.** Never trail
+  one after code in an example, unless the repository's example runner reads
+  it there, as with an assertion marker.
+- **Break a long string at a word boundary,** never inside a tmux format
+  (`#{...}`) or an escape sequence; the joined text stays the same.
+- **Continue a long command in a `console` block the way its shell does:**
+  `\` after a `$ ` prompt, a backtick after `PS> `, one flag per continuation
+  line.
+
+### What never breaks
+
+- **Output a test compares.** Wrapping it changes what the test expects.
+- **A block copied from a source file.** Fix the width in the source, then
+  refresh the copy with the sync command the port block names, or by hand
+  where it names none; never fix the copy alone.
+- **Marker lines and URLs,** which tools and readers take whole.
+
+<!-- /shared:examples -->
+
+### In this repository
+
+- **Hard limit:** oxfmt (`.oxfmtrc.json`, `printWidth`) formats the site's
+  own source and has no example directory to hold to 80. The width check is
+  `python3 scripts/check_example_width.py`.
+- **Not formatted:** Markdown, which oxfmt skips because
+  `site/test/complete-examples.test.ts` pins fenced programs by sha256. Hold
+  every fence to 80 by hand.
+- **Runs, compiles, exempt:**
+  [Documented examples that run](#documented-examples-that-run) decides how
+  each kind of fence runs; every kind is held to the width, including blocks
+  quoted by hand and plain fences that do not run.
+- **Compared output and copied blocks:** output a program's run compares
+  never breaks. A program or console recipe pinned in
+  `site/test/fixtures/*-examples.json` changes only together with its new
+  hash or `shellRecipe` and a new native run on both recorded tmux versions.
+  Fix a quoted block in its port source, never on the page, and refresh the
+  `file=` quotes with `node scripts/gen-example-sources.mjs` once the port's
+  pinned revision moves.
+
+Bad, over 80:
+
+```csharp
+Session session = await server.CreateSessionAsync(new NewSessionRequest(name: "work"));
+```
+
+Good, the request named in its own statement:
+
+```csharp
+NewSessionRequest request = new(name: "work");
+Session session = await server.CreateSessionAsync(request);
+```
 
 ### Examples across ports
 
@@ -322,6 +404,8 @@ Reserve GitHub alert syntax for GitHub-only material and only when a warning
 is necessary; the warning's text must stand alone. Put blank lines around
 lists and headings, and preserve existing anchors when restructuring prose.
 
+### Code blocks
+
 Code blocks are paste-and-run units:
 
 - Put one command in each block. An explicit `&&`, `;`, or `\` chain counts

docs/ci.md

@@ -228,7 +228,8 @@ jobs:
     uses: libtmux/docs/.github/workflows/port-docs.yml@<sha>
     with:
       port: rs
-      tag-prefix: libtmux@  # stripped from a release tag; omit when tags are bare
+      # stripped from a release tag; omit when tags are bare
+      tag-prefix: libtmux@
       source-ref: ${{ inputs.source-ref }}
       version: ${{ inputs.version }}
       version-kind: ${{ inputs.version-kind }}

notes/upstream/libtmux-cxx-doxygen-comments.md

@@ -19,7 +19,9 @@ $ python3 -c "
 import re, glob
 tot = empty = 0
 for f in glob.glob('xml/*.xml'):
-    for m in re.finditer(r'<briefdescription>(.*?)</briefdescription>', open(f).read(), re.S):
+    text = open(f).read()
+    pattern = r'<briefdescription>(.*?)</briefdescription>'
+    for m in re.finditer(pattern, text, re.S):
         tot += 1
         empty += not m.group(1).strip()
 print(tot, empty)"

package.json

@@ -9,6 +9,8 @@
     "preview": "pnpm --filter @libtmux/site preview",
     "build:site": "./scripts/build-site.sh",
     "type-check": "pnpm run --recursive type-check",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
     "lint": "pnpm run --recursive lint && oxlint scripts",
     "test": "node scripts/test-loop.mjs outer",
     "test:inner": "node scripts/test-loop.mjs inner",
@@ -21,11 +23,11 @@
   },
   "packageManager": "pnpm@12.7.0",
   "devDependencies": {
-    "@biomejs/biome": "catalog:",
     "entities": "catalog:",
     "happy-dom": "catalog:",
     "mdast-util-from-markdown": "2.0.3",
     "mdast-util-to-markdown": "2.1.3",
+    "oxfmt": "catalog:",
     "oxlint": "catalog:",
     "typescript": "catalog:"
   }