Skip to content

Show each port picker row's matched API, cut at its separators - #333

Merged
tony merged 9 commits into
mainfrom
feat/picker-api-lines
Nov 19, 2026
Merged

tony merged 9 commits into
mainfrom
feat/picker-api-lines

Conversation

@tony

@tony tony commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

On an API page, each port picker row now names the API it goes to, and a name too long for its row is cut at its separators, keeping the end that names the API: a Kotlin row reads …kotlin.Pane.capture, Swift Server.capture(…).

Why

Until now the picker named only the language and, on some rows, what differs; the matched API showed only as name (kind) when a port had several. Design records 0030 and 0068 (libtmux/design) put the matched API on one line under each row, and record 0069 cuts a name that does not fit at its separators rather than at its end, where the method name is.

What changes

  • page-port-links.ts: every symbol exit carries api, the target symbol's qualified name.
  • PagePortSwitcher.astro: the API line leads a row's muted lines in mono at 0.75rem; the row's accessible name and title keep its label, or the full API name where it has none; rows with an API line widen the panel to 32rem; the row's text fills the row so a name is measured against the room it has.
  • qualified-name.ts: abbreviateQualifiedName cuts at ., ::, #, / and :, never inside a component, keeps brackets, backticks and arity whole, prefers the right end, keeps an owner such as io.github.libtmux whole or drops it, prefers a form no other row shares, and drops a call's arguments before its owner; fitQualifiedNames measures with the label's own font.
  • documentation-navigation.ts: fits the names when a picker opens and on resize.
  • documentation-picker.css: a row's differences take the caution ink at weight 500, on hover too, as the design system draws them; they were plain muted grey.
  • global.css: on touch screens the left-column drawer's head links take a 44px hit area without growing the head, and the outline drawer's links become 44px rows (design record 0071). The drawers were already full-height side sheets with the scrim and scroll lock; these links were the only ones under 44px on a phone and a landscape phone.
  • Page content on touch screens (16 components and styles): member filter chips, "In other ports" chips, declaration badges, permalinks, copy and pin buttons, the release notice, install-bar segments, replay controls, breadcrumbs, footer lists, summaries and search inputs give a 44px tap. Every rule is under pointer: coarse; desktop geometry is unchanged.
  • third-party-notices.md: rows for the Julia, Perl, Haskell, Clojure, Elixir, Erlang and PowerShell icons (Devicon, MIT), so all 23 icons the picker shows are credited.
  • api-tree.ts: a changed Directory.Packages.props in libtmux-powershell warns (a ::warning annotation in Actions) and keeps the pinned .NET navigation, instead of failing the port's docs build. A missing or malformed declaration still fails. Fixes A PowerShell dependency bump fails its docs build until ports.ts is updated #188.
  • build-site.sh: the shell cache key includes the site origin and LIBTMUX_DOCS_ROOT, so builds that differ only in those no longer share a cached shell. Refs Reduce repeated docs builds, S3 uploads, and retained output #210 (its measurement items stay open).
  • powershell.mjs and powershell.json: the PowerShell Core player says Get-TmuxSnapshot returns a Server and labels the lookup Server.Panes, as the cmdlet's [OutputType(typeof(Server))] declares; the recording was made again and core-apis.test.ts drops its Snapshot.Panes exemption, so every PowerShell step label must link into the API model. Fixes PowerShell Core recipe types Get-TmuxSnapshot as Snapshot, not Server #259.
  • version-bookkeeping.sh and build-site.sh: the Python Sphinx tree under /en/py/latest/api/ names libtmux.org in its canonical link, og:url, sitemap and llms.txt, through sphinx-build -D settings with upstream's conf.py untouched; the reference cache is keyed on origin, root and default version. Seo.astro names the libtmux.org Python home as the structured-data url, keeping the legacy host in sameAs. Fixes Point the Python Sphinx tree's canonical, og:url and sitemap at libtmux.org #168.

Verification

  • Dev server (LIBTMUX_DOCS_PORT=rs, pane.Pane.capture, 1280px): rows have 182px for the name. Python, Ruby, Lua, TypeScript, Go, C++, Clojure, C# and Erlang show their names whole; Java …libtmux.Pane.capture, Kotlin …kotlin.Pane.capture, Scala …scaladsl.Pane.capture, Swift Server.capture(…), OCaml …Client.capture_text, Perl …Server::capture_pane, Raku LibTmux…PaneRef.capture, F# LibTmux…Pane.capture; each row's title and accessible name carry the full name.
  • vitest: qualified-name, documentation-picker-interaction, page-port-links, api-equivalents, complete-examples, design-tokens, chrome-context, header-links-interaction and the workspace picker outer suite: 470 passed. pnpm lint in site passes.
  • vitest after the rebase onto Show the new Session, Window and Pane directories on perl, raku, erlang and ocaml #331: design-tokens, qualified-name, api-dependency-navigation, documentation-picker-interaction, versions and core-apis: 198 passed. A Sphinx build of the libtmux docs at gp-sphinx 0.1.0a39 carries canonical and og:url under https://libtmux.org/en/py/latest/api/, and its sitemap.xml, llms.txt and docs.json name no legacy host.
  • Drawers (Chromium, touch, 390 × 844 and 844 × 390): every outline link and 8 of 9 left-column links take a 44px tap; the ninth is the up link, whose lower strip goes to the title 20px below it. The left column's rows were already 44px.
  • Touch audit (Chromium, touch, 1024 × 768 and 390 × 844, five pages): controls under 44px fell from 95, 165, 465, 47 and 96 to 2, 1, 1, 2 and 2 on the tablet, and to 0 or 1 on the phone.

tony added 7 commits November 18, 2026 17:09
…eparators

why: On an API page the port picker named only the language and, for some
rows, its differences; the matched API appeared only as `name (kind)` when a
port had several. Design records 0030 and 0068 put the matched API on one
line under each row, and record 0069 cuts a name that does not fit at its
separators, keeping the right end, so a Java or Kotlin row reads
`…kotlin.Pane.capture` rather than `io.github.libtmux.Pan…`.
what:
- page-port-links: every symbol exit carries `api`, the target's qualified
  name
- PagePortSwitcher: the API line (mono, 0.75rem) leads a row's muted
  lines; a row's accessible name and title keep its label, or the full API
  name where it has none; such rows widen the panel to 32rem; the row's
  text fills the row so a name is measured against the room it has
- lib/qualified-name.ts: abbreviateQualifiedName (separator-aware
  candidates scored for right-end context, owner and distinctness from the
  other rows; a call's arguments go first; a grapheme fallback) and
  fitQualifiedNames, measured with the label's font
- documentation-navigation: fits the names on open and on resize
- Tests: the cut rule on fixed-width cases, the row's API line and
  accessible name, the exit link's `api`; the workspace picker page
  inlines lib/qualified-name.ts
…e caution ink

why: The design system draws a picker row's differences ("3 overloads",
"on Server") in the caution ink at weight 500; the site drew them in
plain muted grey, and the hover rule for a row's small text would have
greyed them again.
what:
- documentation-picker.css: the differences line takes
  --aside-caution-ink at 500, on hover too
- design-tokens test pins the rule
why: Design record 0071 asks for touch-target rows under pointer: coarse at
every width. In the left-column and outline drawers, measured on a phone
and a landscape phone, the sidebar head's up link (28px) and title (20px)
and the outline's links (28px) were the only links under 44px.
what:
- The sidebar head's up link and title take the same hit-area pseudo
  element as the header's chips, so the head keeps its height
- The outline drawer's links become touch-target-tall rows
- design-tokens test pins both rules
why: The port picker shows an icon for all 23 ports, but the
Programming-language artwork table credited 16. The Julia, Perl,
Haskell, Clojure, Elixir, Erlang and PowerShell icons are Devicon
copies with a local MIT notice and no row, so the page omitted their
copyright holder and terms.

what:
- Add rows for Julia, Perl, Haskell, Clojure, Elixir, Erlang and
  PowerShell, each crediting the Devicon collection (copyright (c)
  2015 konpa), linking its local LICENSE.txt and provenance.json
- Take the credit text from each provenance record: the language
  marks belong to their respective projects, and no other terms are
  recorded, so none are added
- Place each row after the nearest earlier port in port-families.ts
  order; existing rows keep their positions
- Leave the modified-SVG sentence as is: only Scala, Common Lisp and
  Rust record modifications
why: Design record 0071 asks every row, tab, chip and button to be at
  least touch-target (2.75rem) tall under `pointer: coarse` at every
  width, through its hit area where the drawn control stays smaller. The
  header, sidebar head, outline drawer, pickers and API tree already do;
  the page content did not. Measured in Chromium with touch emulation,
  counting each control's tap height as the run of `elementFromPoint`
  hits from its centre, and leaving out links inside running text:

  page                           1024x768     390x844
  /reference/pane-pane-capture/  95 -> 2      93 -> 0
  /reference/pane-pane/          165 -> 1     163 -> 0
  /reference/                    465 -> 1     465 -> 0
  /guides/capturing-output/      47 -> 2      44 -> 1
  /                              96 -> 2      92 -> 1

  Pages at 1280x800 with a mouse lay out identically before and after:
  every rule is inside `@media (pointer: coarse)`.

what:
- Hit areas (a `::before` or `::after` of `calc((100% - var(--touch-target)) / 2)`
  insets) for the member filter chips, the equivalents table's chips, the
  kind, modifier and source badge links, heading permalinks and `¶`
  anchors, the qualified-name copy button, the page-actions chip, the
  context bar's buttons, the release notice's dismiss and More, the footer
  icon links, the header's scheme switch, the port chips, the install
  bar's segments and facts link, the copy and pin buttons, the status
  badge toggle, and the replay's buttons and dots.
- Badge and external-link hit areas use `::before`, because the shell
  draws an external link's mark in `::after`. The kind and modifier tabs
  drop `overflow: hidden` so the area is not clipped; the kind mark rounds
  its own corners instead. The replay track grows to the touch target so
  it does not clip its dots' areas.
- Real `min-height` for list-like rows: breadcrumbs, footer links, the
  page-end up row and related lists, member names, guide, definition and
  tmux-usage links, the equivalents table's cell links, summaries, the
  member search input, section search, product tabs, the example
  toolbar's labels, and the Core showcase options and links.
- The code frame's copy button grows from 2.5rem to the touch target with
  its icon kept at the same size.
- Chip rows get a row gap that keeps one row's hit areas off the next.
- One test in design-tokens.test.ts pins the rules and that each sits
  under a coarse media query.

Not covered: the sidebar head's up link (its title link sits 8px below
it, so it gets 31.5px; the head would have to grow), the Core player's
step dots (20px to 24px apart down the program's margin), and links
inside running text (WCAG 2.5.8 inline exemption). The API tree's group
labels read as 20px in the probe, but their 44px row forwards a tap to
the link.
why: #210 found that build_shell() reuses one cached shell
for builds that differ only in LIBTMUX_DOCS_SITE or LIBTMUX_DOCS_ROOT.
The cache key omitted both, yet the Astro build receives them: the
origin sets canonical URLs and the sitemap, the root sets where links
resolve. A second build with a different origin or root silently
returned the first build's output.

what:
- Add site_origin and LIBTMUX_DOCS_ROOT to the build_shell cache key.
  The root defaults to "/" exactly as the build invocation does.
- Leave the measurement items in the issue alone.

The script has no test for its cache key, and sourcing it runs a whole
assembly. Verified by extracting the real build_shell() and driving it
with a stub renderer that writes the origin and root it receives. Four
calls (default, new origin, new root, default again) gave
miss, hit, hit, hit before the change, and miss, miss, miss, hit after:
differing builds now miss, and an identical repeat still hits.
why: #188 reported that any change to libtmux-powershell's
Directory.Packages.props turns that port's docs build red.
validateNavigationDependency threw when the file's sha256 differed from
the pin in ports.ts, so a routine LibTmux package bump could not pass
its own docs job, and the fix had to land here first.

The guard exists so borrowed .NET navigation is reviewed when the
declaration changes. Deriving the LibTmux version from the declaration
would keep that without a pin, but the port's API model records only the
file's digest, not its contents, so the version is not available here
without a change to the port's exporter. Keeping the pin and warning
keeps the review prompt and stops blocking a build the port cannot fix
from its own repository.

what:
- Warn once per changed digest, naming the new sha256, the pinned
  version and revision still in effect, and what to record in ports.ts.
  Under GitHub Actions the warning is a ::warning annotation, as in
  verify-destinations.mjs, so it shows on the run summary.
- Throw clearly when the declaration is missing from the native
  provenance or its sha256 is not a 64-digit hex digest.
- Keep throwing when the .NET model this repository ships differs from
  the pinned package version or source revision: that is this
  repository's own data, not the port's declaration.
- Replace the changed-declaration assertion in the existing test with a
  test that a changed digest warns once and does not throw, and that a
  missing or malformed one still throws.

Verified in site/: api-dependency-navigation and five neighbouring
api-tree, sidebar, glossary and search suites pass; the new test fails
against the previous implementation; oxlint reports no findings in
api-tree.ts; astro check reports 0 errors.
@tony
tony force-pushed the feat/picker-api-lines branch from c52cb99 to e20fca8 Compare November 18, 2026 23:09
tony added 2 commits November 18, 2026 17:10
…Server.Panes

why: #259. The PowerShell landing page and Core overview on
libtmux.org print `Snapshot.Panes` five times, and the player says
`Get-TmuxSnapshot` returned a `Snapshot`. The cmdlet declares
`[OutputType(typeof(Server))]` and the library has no `Snapshot` type, so
`$snapshot.Panes` reads `LibTmux.Server.Panes`. The C# recipe already
names this step `Server.Panes`. The wrong label also needed an exemption
in the Core player's links test, which hid the broken link.

what:
- scripts/lib/core-recipes/powershell.mjs: the `snapshot` step's type is
  `Server`, and the `pane-lookup` step's label is `Server.Panes`.
- site/src/data/core-recordings/powershell.json: recorded again with
  `scripts/gen-core-recording.mjs --port powershell` against
  libtmux-powershell at 2c30121 (the recorded revision), tmux 3.8a and
  PowerShell 7.4.20. The program hash is unchanged. The type and label
  are the only semantic changes. The other lines are per-run values: the
  library's version-probe and field-separator nonces, server pids and
  start times, and the order of two control-mode lines (`%exit` and
  `%client-detached`).
- site/test/core-apis.test.ts: drop the `Snapshot.Panes` exemption, so
  every PowerShell step label must link into the API models. The test
  fails against the old recording.

Source: https://github.com/libtmux/libtmux-powershell/blob/2c30121b7733bf772d17140231a49332e5a470ab/src/LibTmux.PowerShell/GetTmuxSnapshotCommand.cs#L7-L8
…x tree

why: #168. The Sphinx tree under /en/py/latest/api/ still
advertised the legacy host. Probed 2026-10-18, /api/libtmux.pane/ carried
og:url https://libtmux.git-pull.com/api/libtmux.pane/ and no
rel="canonical", and api/sitemap.xml listed only libtmux.git-pull.com
URLs. Redirecting the legacy host to pages whose own signals name it
undoes the redirect.

The cause is upstream's conf.py, which the build passed through
unchanged. It sets docs_url to the legacy host; gp-sphinx 0.1.0a39
derives ogp_site_url, site_url (sitemap, llms.txt) from it; and gp-furo
emits a canonical only when html_baseurl is set, which nothing set.

what:
- version-bookkeeping.sh: add sphinx_url_settings, which builds the four
  settings with canonicalUrl from versions.ts. html_baseurl and
  ogp_canonical_url (canonical link, og:url) name the port's default
  version, as an Astro page does; site_url and ogp_site_url (sitemap,
  llms.txt, images) name the version being built
- build-site.sh: pass them to sphinx-build as -D, so conf.py stays
  untouched, and fail the reference build if they cannot be computed
- build-site.sh: key the reference cache on origin, root and default
  version, which now change the output
- Seo.astro: name the libtmux.org Python home, under the port's default
  version, as the structured-data url instead of libtmux.git-pull.com;
  sameAs keeps the legacy host as an alias of the same project
- versions.test.ts: assert the four settings for the default version
  and for a non-default build

Verified with a Sphinx build of the libtmux docs at gp-sphinx
0.1.0a39: pages carry canonical and og:url under
https://libtmux.org/en/py/latest/api/, and sitemap.xml, llms.txt and
docs.json name no legacy host. Tagged versions follow versions.ts and
canonicalise to the default version; whether that default is latest is
#167.
@tony
tony merged commit a626ef8 into main Nov 19, 2026
3 checks passed
@tony
tony deployed to docs-preview-cleanup November 19, 2026 04:23 — with GitHub Actions Active
tony added a commit that referenced this pull request Nov 19, 2026
)

why: #333 landed on main as a626ef8 while this branch was in review.
The design owner asked for design-tokens.test.ts to run against this
branch merged onto that main before it merges, and the docs test should
run on the combined tree.

what:
- Take main at a626ef8: port picker rows show the API they matched,
  and touch screens get 44px tap targets
- No conflicts; the tree equals git merge-tree of main and this branch

This branch was successfully deployed

1 active and 1 inactive deployments
docs-preview-cleanup — 8910b25a Deployed Nov 19, 2026 by tony via cleanup #259
docs-preview — 8910b25a Deployed Nov 19, 2026 by tony via publish-preview / publish #1488
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant