Skip to content

Group and restyle product API references; steady players on load - #267

Merged
tony merged 13 commits into
mainfrom
fix/product-api-style
Nov 8, 2026
Merged

tony merged 13 commits into
mainfrom
fix/product-api-style

Conversation

@tony

@tony tony commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Three reader-facing fixes from review of the live site after the wave at c5b56f2.

Summary

  • Set workspace and MCP reference pages in the core API style.
  • Group every product API reference into sections a reader can scan.
  • Stop the Core player and the MCP replay from jumping on load.

Product reference pages in the core style

https://libtmux.org/en/rs/latest/workspace/reference/src-builderror-refused/ drew "Fields" and "Member details" at 32px, where the same heading on a core page such as https://libtmux.org/en/rs/latest/reference/options-optionvaluerefusal/ is 18px, and repeated each field as a full bordered entry under a bordered bar.

  • ProductApiPage rendered inside DocsLayout's <article class="prose">; Tailwind Typography's .prose h2 { font-size: 2em } outranks the heading's text-lg, and not-prose on the wrapper does not stop it. DocsLayout takes a reference prop that keeps the title and product notice in the prose column and puts the body outside .prose.
  • ApiMemberList.astro holds the compact member rows, moved out of ApiReference, so core and product pages list members the same way: the field or variant table, then the other members as linked rows. Each member keeps its old entry id, and the section and parameter ids its entry carried, as an anchor target.

Sections in the product API references

https://libtmux.org/en/rs/latest/mcp/reference/mcp-views-branch/ listed 83 symbols A to Z in one bucket. site/src/lib/product-api-sections.ts assigns each symbol of a product with eight or more public roots to a section, by ordered rules (kind, name pattern, module, the MCP tool catalog) with a few per-port overrides, and feeds the sidebar tree, the documentation sidebar's API group and the reference index. It reuses the core references' TreeBucket shape; URLs are unchanged.

  • MCP: Tools, Resources and URIs, Views and results, Server and setup, Configuration and environment, Errors, Utilities (rs: 22, 5, 36, 6, 12, 2, 0).
  • Workspace: Workspace files, Building and freezing, Command line, Plugins and shell, Errors, Utilities.
  • Products under eight roots stay flat.

Players draw their first frame on the server

On a cold load of https://libtmux.org/en/ruby/latest/ the server HTML drew the Core player at its last call (16/16) and the script reset it to step 0 about 0.3 s later, while the controls bar appeared and pushed the player from 627 to 676px. The MCP replay did the same: the whole chat with every result open, then the bare prompt (531 to 571px).

  • CorePlayer.astro and McpReplay.astro draw the step the script first shows; ReplayControls.astro is in the markup from the first paint. core-player.css and mcp-replay.css show the finished frame and chat to readers without the script, and to reduced-motion readers until the script binds; out-of-view calls use data-off instead of hidden, which preflight hides with !important.
  • A reduced-motion reader's replay stays finished and keeps its results open at bind; its controls bar holds its place and appears at bind with the finished count.
  • Autoplay is unchanged: the player still plays from the first call once it is on screen.

Test plan

  • product-api-style, product-api-sections, and the new "binding the script changes nothing on screen" cases in core-player and mcp-replay: each fails on main and passes here
  • Full vitest: 270 files, 8706 tests pass (assembled-site suites skipped locally)
  • astro check: 0 errors
  • Chromium, Rust product and core pages, light and dark: section headings 18px on both, no bar over a bordered entry
  • CDP screencast of cold loads (cache disabled) of a production Ruby build, before and after: landing player and MCP overview show the same frame before and after the script binds, no height change
  • The full test workflow, including the assembled-site suites (product-docs.test.ts, check-type-links)
  • The preview deploy: a workspace and an MCP reference page of a few ports with their sidebar sections, and a landing and MCP page from a cold load

tony added 6 commits November 7, 2026 18:43
why: A workspace or MCP symbol page sat inside the article's prose
styles, so its section headings computed to 32px against the core
page's 18px, and under a field table it repeated every member as a
full entry beneath a bordered Members bar: border on border, with the
table's rows shown twice.

what:
- Add ApiMemberList, the linked member rows ApiReference drew inline,
  and draw them through it from both pages
- List a product type's members as the table, then the rest as those
  rows; link each to its own page and keep every entry anchor as an
  empty target so existing links still land
- Take the rows' type repeat flag from the core rule: C# properties
  and variants only
- Add DocsLayout reference mode: the title and notice keep the prose
  column, the page body sits outside it; ProductApiPage uses it
why: The product page's members and heading size were only
checked against the old stacked entries.

what:
- Add product-api-style.test.ts: reference mode keeps the body out of
  prose, both pages share ApiMemberList, members are rows with anchors
- Update the product page tests in api-headings, enum-variants and
  field-table-pages to the table, rows and repeat rule of a core page
- List ApiMemberList in the prose-link reader inventory
why: The MCP and workspace API sidebars listed every declaration in one
A-Z list, mixing structs, functions, constants and enums, so a reader could
not find a tool, a URI constant or an error type without scanning 83 rows.

what:
- Add product-api-sections.ts: one section vocabulary for MCP (Tools,
  Prompts, Resources and URIs, Views and results, Server and setup,
  Configuration and environment, Errors, Utilities) and workspace
  (Workspace files, Building and freezing, Command line, Plugins and shell,
  Errors, Utilities), assigned by ordered rules over kind, name, source
  file and the MCP tool catalog, with a small per-port override table
- Feed the sections through the core TreeBucket shape to the sidebar tree,
  the documentation navigation and the reference index; products under
  eight roots stay flat; every URL is unchanged, A-Z kept inside a section
- Test the assignment for rs, go, py, csharp and ts, determinism, no
  symbol lost or duplicated, and the tree and navigation counts
- Nest the Julia extension-function namespaces inside their section
why: A landing page's Core API player was drawn at its last call and
then jumped to the state before the first call when the script bound
(about 300 ms after first paint), while the controls bar, hidden until
then, pushed the page 49px down. Go's player also redrew its dots and
count for one call fewer, since its short program plays 15 of the 16
recorded calls. The jump was visible as a flash of steps before the
autoplay began.

what:
- Draw the player's frame and result at the state before the first
  call; a page with no script, and a reduced-motion reader's page until
  the script binds, still show the final frame and result (CSS swap)
- Draw the controls bar in the markup, with the dots, fill and count
  for the first view's calls; the stylesheet hides it with no script
- Pass the step the page is drawn at from the MCP replay, which keeps
  drawing its finished chat
- Test that binding the script changes nothing on screen
…n test

why: The core page's member rows now come from ApiMemberList, which
this test's template loader stubbed as an empty component, so the
Members list it reads rendered nothing. The core markup is unchanged.

what:
- List ApiMemberList among the real components the test renders
why: The MCP overview's worked example, the first thing on every MCP
page, was drawn as the finished chat with every result open and then
reset to the bare prompt when the script bound: the chat collapsed,
the header appeared and each call's padding grew for the pin button,
so text rewrapped. For a reader who asked for less motion the results
also folded shut at bind, though the replay stays finished.

what:
- Draw the calls and frames out of view as data-off, not [hidden]
  (preflight hides [hidden] with !important), and draw the prompt alone
  with the empty tmux; the stylesheet shows the whole chat and the last
  frame where there is no script, and until bind for reduced motion
- Draw the header from the first paint, hidden with no script, and give
  each call its pin button's room from the first paint
- Keep a finished replay's results open at bind
- Keep the controls bar's place but hide it until bind for a reader who
  asked for less motion, so its 0/N count and dots never show against a
  finished replay
- Test that binding the script changes nothing on screen
@tony tony changed the title Set workspace and MCP reference pages in the core API style Group and restyle product API references; steady players on load Nov 8, 2026
tony added 5 commits November 7, 2026 20:59
…y the shape

why: Product members are linked rows now, so the per-member
disclosure of other ports is gone. check-dev found nothing to open on
ClassicWorkspaceBuilder, and check-native-layout still asked product
pages for a disclosure and a facts paragraph only their member
entries drew.

what:
- Measure overflow in check-dev on the py Freezer.freeze and java
  WorkspaceBuilder.build pages, which carry their own In other ports
  table, and require that table to be present
- Ask check-native-layout's py and java workspace pages for their own
  examples and description, and Ruby ConfigError for its bases
…tion

why: The assembled-site suite read every MCP reference page's sidebar
trail and required its top row to be "API reference". A product
reference with eight or more roots is now grouped into sections, whose
labels are the top-level rows, as the core references' groups are; the
breadcrumb keeps the section after "API reference". Eight ports' MCP
pages failed on that one assertion in CI (run 42440820229).

what:
- Accept a product section label as the tree's top row and keep it in
  the returned trail, so the breadcrumb comparison includes it
- Keep requiring "API reference" for a flat reference
why: Shared pages such as every port's /mcp/ page linked to each port's
same-product page even where the port has no page for it, giving broken
links in the assembled check. The product match also missed the bare
`mcp` and `workspace` routes. Guarding on productAvailable would drop an
unpublished overview that does exist (Lua's MCP).

what:
- Add an 'excluded' product availability and productExcluded(), which
  productAvailable now also honours; 'unpublished' keeps its pages
- Match the bare product route in pagePortLinks and drop a port's links
  only when it excludes the product
- Test a synthetic excluded port, Lua's unpublished MCP overview and the
  bare route
why: A sectioned reference's tree row links to the page of its first
entry, but the section group in the documentation navigation had no
href, so the breadcrumb crumb for the section had none (assembled-site
check "ancestor destination", run 42452517353).

what:
- Give each section group the href of the first entry the tree row uses,
  computed with the same firstEntry rule
- Match a group's own rows before its link in sidebarBreadcrumbs, so a
  page that is both a section target and a row keeps its row crumb
- Test every grouped product: section href equals the tree row target
why: The excluded-product fix widened the product match to the bare
`workspace` and `mcp` routes for every use. The bare `workspace` page
then required the port's workspace to be available before linking its
overview, so Lua's and Elixir's unpublished workspace overviews lost
their links, and a bare product page's home link moved to the product.
The Perl port's review found it in the source.

what:
- Match the bare product root only for the exclusion check; the
  product used for eligibility and the home link keeps its prior,
  slash-only match
- Test the shared workspace overview: Lua's and Elixir's unpublished
  roots keep their link, an excluded port's is dropped; the test fails
  with the widened match
tony added 2 commits November 8, 2026 06:48
why: Product API pages now list a type's members as rows linking to
each member's own page, instead of repeating every member's full entry
under the type. The mentions inside those repeated entries were counted
a second time. CI run 42472628116 counted the drop against main's push
run 42421548678 in exactly the ports with an MCP or Workspace Manager
reference: py -446, ruby -131, powershell -545, ts -12, rs -1028,
go -94, java -64, csharp -633, cxx -115, swift -451; lua, elixir,
kotlin, scala and fsharp, which have none, are unchanged, and julia
rose by 159. Each member's mentions still resolve on its own page.
PowerShell's floor (4752) sat above its new count (4663); every other
port stays above its floor.

what:
- Lower the powershell floor in scripts/xref-floor.json to 4663; the
  other floors are unchanged
why: Product API pages now list a type's members as rows that show each
member's type through ApiType, the same renderer the entries used. CI
run 42481976006 counted 110 Julia type names rendered plain against a
ceiling of 108; the most frequent are Base names that stay plain by
design (Exception, show, validated, N, var). Every other port stayed at
or under its ceiling, and Julia's resolved cross-references rose by 159
in the same change, so the two extra plain names come from the new rows
rather than from a resolution regression.

what:
- Raise the julia ceiling in scripts/type-links-ceiling.json from 108
  to 110; the other ceilings are unchanged
@tony
tony merged commit 0d0a2d1 into main Nov 8, 2026
3 checks passed
@tony
tony temporarily deployed to docs-preview-cleanup November 8, 2026 19:05 — with GitHub Actions Inactive

This branch was previously deployed

2 inactive deployments
docs-preview-cleanup — c9820784 Deployed Nov 8, 2026 by tony via cleanup #215
docs-preview — c9820784 Deployed Nov 8, 2026 by tony via publish-preview / publish #1293
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant