Skip to content

feat(apidocs): static API reference pages from the apidocs/1 model - #28

Merged
Sam Gammon (sgammon) merged 36 commits into
mainfrom
feat/apidocs
Nov 22, 2026
Merged

Sam Gammon (sgammon) merged 36 commits into
mainfrom
feat/apidocs

Conversation

@sgammon

Copy link
Copy Markdown
Member

Adds @elide/apidocs: a package that renders a JSON model of a Java or Kotlin module's public API (apidocs/1) into static HTML and Markdown. Komodo's Javadoc doclet writes the model today; a Dokka plugin will follow. This is a draft: the design is still being iterated with the owner.

What it produces

  • One HTML page and one Markdown page for the module overview, each package, each type and each guide, plus index pages (packages, all types, A to Z, deprecated).
  • llms.txt, llms-full.txt, the model as api.json, a search index, element-list, and sitemap.xml when the theme has a base URL.
  • Pages are prerendered with Preact and work from file://, inside a -javadoc.jar and with JavaScript off. One classic script adds search, the theme switch, filters and copy.
  • Branding is a theme input. The Elide preset maps @elide/tokens and @elide/brand; the default theme is neutral.

How to try it

bun install
bun run apidocs:dev       # hot-reload server with the Java and Kotlin sample models
bun run apidocs:sample    # the static output, as the doclet writes it
bun run apidocs:audit     # Lighthouse, agent-readiness and good-css checks (see packages/apidocs/AUDITS.md)

Verified

  • bun test in packages/apidocs: 165 pass, including the browser tests from file:// with JavaScript on and off and the accessibility checks. They need PLAYWRIGHT_BROWSERS_PATH to point at an installed Chromium.
  • tsc --noEmit is clean for the package.

Known gaps

  • The first audit run (before the last design changes) scored Lighthouse 100 except accessibility at 96 to 97 for one target-size finding, which is since fixed but not re-measured. The local agent-readiness approximation scored 93 to 94. Ten good-css rules do not pass yet (logical properties, OKLCH colors, hover and press states).
  • Doc content is untrusted input: raw HTML goes through an allowlist and every URL through a scheme check, with tests. This has not had an independent security review.
  • No changeset yet; the package is private.

@elide/apidocs turns the apidocs/1 model that Elide's Javadoc doclet and
Dokka plugin write into static HTML and Markdown pages that work from
file:// and inside a -javadoc.jar.

This commit holds the parts that do not depend on the page layout:

- schema/apidocs-1.schema.json, with src/model.ts generated from it
  (scripts/gen-types.ts, no dependencies). It adds an extension receiver
  and Kotlin default arguments beside the doclet's Java model.
- render(model, theme): the site as a file map, and markdown.ts for the
  Markdown twins, llms.txt, llms-full.txt, api.json, element-list, the
  search index script and sitemap.xml. It also has the render-time
  highlighter, signature layout, sanitizer for raw nodes, link
  resolution, and the documentation-tree and declaration components.
- Vite library builds of two classic IIFE scripts: dist/render.js
  (global ApiDocs) and assets/apidocs.js (client islands). Preact is
  inlined in both.
- dist/runner.mjs, which runs render.js in Bun or Node over files and
  writes the site. The JVM tools ship it in their jars.
- Hand-written Java and Kotlin sample models that cover every feature
  (samples/FEATURES.md maps each one to a page), including a generated
  type with hundreds of members.
- `bun run dev`: a Vite dev server on 127.0.0.1:5180 that renders the
  samples, or a real model given with --model, through the same
  render() and reloads on edits. `bun run sample` builds a model through
  the runner and serves it or opens it from file://. The repository
  root exposes both as apidocs:dev and apidocs:sample.
- Tests: schema validation of the samples and the doclet's fixture,
  snapshots, an output checker (absolute URLs, module scripts, fetch,
  missing files and anchors), and Playwright from file:// with
  JavaScript on and off plus axe in light and dark.

The layout files (page shell and navigation, pages, groupings, client
islands, stylesheet, theme and Elide preset) are being redesigned
separately and land in a following commit, so this commit does not
build or test on its own.

Checks run before splitting, with every file in place:
`bunx turbo run lint test --filter=@elide/apidocs` (tsc clean, 40
tests pass); `bun run build`; the runner on Bun and on Node gives
byte-identical output for the fixture.
Documentation comments are untrusted input once the renderer documents
third-party code, and its pages are served from the publisher's origin.
Two paths let comment content execute.

Raw HTML nodes went through a regex blocklist that entity-encoded
schemes, unquoted or malformed attributes, srcdoc, data: URLs and
svg/iframe content could bypass. sanitize() now parses the markup with a
small tokenizer (the render bundle has no DOM) and rebuilds it from an
allowlist: the inline and block tags Javadoc uses, title on any of them,
href on a, colspan and rowspan as numbers, and scope from its four
values. Values are entity-decoded, then escaped. Script-like elements
(script, style, iframe, svg, math, object, template, ...) are dropped
with their content. Other unknown tags keep their text. Unterminated
tags and attributes end the input. Open tags are closed.

Link URLs from the model or the theme went into href unchecked.
safeUrl() decodes character references, strips the control characters
and whitespace that browsers ignore, and allows only http:, https:,
mailto: and relative URLs. It applies in resolve() (refs, signature
tokens, externals), in documentation links, in source links and in the
Markdown output. An unsafe link renders its label as plain text. The
theme's header and footer links, base URL and source-link template pass
the same check before rendering.

The output checker also fails on any on*= attribute and on any href or
src that safeUrl rejects.

Checks run: `bun test test/security.test.ts` (62 pass). It covers
javascript: in mixed case, with entity, tab, newline and control-character
obfuscation, data:text/html, vbscript:, file:, event handlers in every
quoting style, <script>, <img onerror>, <svg onload>, <iframe srcdoc>,
<a href="jav&#x61;script:...">, unclosed tags and attributes, and a
hostile model and theme rendered end to end. `bun test test/render.test.ts`
passes except the HTML snapshot test, which the layout redesign in
progress changes. tsc is clean.
safeUrl() decoded character references once, checked the scheme, and
returned the decoded value. A doubly encoded URL such as
jav&amp;#x61;script:alert(1) therefore passed the check, and a later
consumer decoded it again. The Markdown output is such a consumer:
Markdown renderers decode entities in link destinations.

- safeUrl() decodes until the value stops changing (at most five
  rounds), rejects a URL that still holds a character reference, and
  checks the scheme on the fully decoded value. It also knows the named
  references for backslash, grave, percent, question mark and the other
  URL punctuation, besides colon, tab and newline.
- markdown.ts writes every link destination through
  markdownDestination(). It percent-encodes &, <, >, backslash,
  backtick, quotes, parentheses, spaces, controls and non-ASCII. Existing
  percent escapes stay as they are, so anchors such as %3Cinit%3E keep
  working. The destination never uses the angle-bracket form.
- The Markdown snapshots move to test/markdown.test.ts, with their own
  snapshot file. That file also checks the fixed section order and the
  Kotlin receiver, default-argument and type-alias output. The HTML
  snapshots stay with the layout work in progress.

Checks run: `bun test test/security.test.ts` (72 pass). It adds doubly
and triply encoded javascript:, &amp;colon;, &Tab; and &NewLine; forms,
a reference left after five rounds, and a Markdown destination with &,
parentheses, quotes, angle brackets, a backtick, a backslash and a space.
`bun test test/markdown.test.ts` (3 pass). tsc is clean.
The layout was redesigned at the owner's direction, over three review
rounds of the dev pages. This commit adds the layout files as they stand
(page shell and navigator, pages, groupings, client islands, stylesheet,
theme and Elide preset), and adapts and extends the tests to them.

Layout changes:
- Navigator: two flat lists with no disclosure widgets. Packages are
  listed by the part of the name that differs, under a shared-prefix row
  (sharedPrefix). Then the current package's types are listed by kind,
  with one-letter kind tiles (kindGlyph). Rows are one line, truncate,
  and carry a title.
- "On this page" rail: sections with counts. A section with more than 12
  entries is folded into <details class="toc-more">. Members can be
  filtered.
- One Callout component for API notes, implementation requirements,
  implementation notes and deprecations, each with an icon tile and a
  label. There are no left bars; the large signature has a hairline
  border.
- Controls that need the script carry data-js-only. A head script marks
  <html data-js> before first paint, so those controls show at once with
  script and never without it.
- A checkbox toggles the navigator without script: it hides it on wide
  screens and shows it on narrow ones. localStorage remembers "closed",
  and [ toggles it. The checkbox sits inside the header landmark.
- Fonts use font-display: optional and metric-adjusted local fallbacks.
  Font preloads are added at run time only off file://, where
  crossorigin font preloads fail.
- @view-transition, content-visibility on member cards, and
  scrollbar-gutter: stable.

Tests:
- render.test.ts: callout classes; sharedPrefix (one package, several,
  one equal to the prefix, the default package); no <details> in the
  navigator; a rail section over 12 entries folded and a short one not;
  data-js-only controls and the head script; the navigator checkbox;
  preloads absent from static HTML and listed for upright faces only.
  The checker allows inline classic scripts and JSON-LD, and still
  rejects module scripts, fetch, on* attributes and unsafe URLs. HTML
  snapshots refreshed.
- browser.test.ts: from file:// with JavaScript off, script-only controls
  stay hidden. With it on, they show before the deferred bundle runs.
  Also covered: search, the theme switch, copy, table-of-contents
  tracking, and the navigator toggle on wide and narrow screens. On wide
  screens the choice survives a reload and [ toggles it. Font preloads
  appear over HTTP (3) and not on file:// (0), with no console errors.
  Cumulative layout shift is 0 on load for a type page, both with fonts
  and with font requests blocked. axe reports nothing in light or dark.

Checks run: `bunx turbo run lint test --filter=@elide/apidocs --force`
(tsc clean, 127 tests pass); the layout files' checksums did not change
between the test run and this commit.
…et the source ref

- The schema's module gains javaModule, the named JPMS module the
  packages belong to. element-list then starts with a module: line, as
  javadoc -link expects for a named module. Without one it lists only
  packages, as before.
- runner.mjs takes --source-ref, which sets the theme's sourceRef (the
  {ref} in its source-link template). The JVM tools pass the ref they
  document without rewriting the theme file.

Checks run: `bun test test/render.test.ts` (35 pass). It covers both
element-list forms, and a runner run with --source-ref whose source link
carries the ref. tsc is clean.
The output checker matched "fetch(" and "import(" anywhere in HTML and JS
files. On the real komodo-api reference it flagged the prose "Modules
that programs import (the prelinked stdlib)" in four files, including
the search index data. It now reads only inline scripts (not JSON-LD)
and script files, with string literals removed. A regression test covers
prose and string data that must pass, and script code that must fail.

Checks run: `bun test test/render.test.ts test/security.test.ts` (108
pass). The checker over the unzipped komodo-api-javadoc.jar (802 files)
reports no problems.
…uage marks and metadata

Design changes made at the owner's direction.

Typography: prose and headings use the reader's system fonts, through stacks that end in symbol and emoji fonts; JetBrains Mono is kept for code and for type and member names, and is the only font file the Elide preset ships. Every font size is a token. The preset's sizes make a JetBrains Mono character a whole number of pixels wide, so code sits on the pixel grid at 1x.

Page: one split button gives the page's other forms (copy as Markdown, the Markdown file, llms.txt, llms-full.txt, api.json). Callouts have no side bar and gain the tones prose needs. The navigator can be hidden and remembers it. Java and Kotlin have marks drawn for these pages; they lead the line under a title and mark rows when a module mixes languages. A load bar and a short content transition cover moves between pages. Labels, counts and controls are not selectable. Links in running text are underlined.

Metadata: keywords, Open Graph, apidocs:* meta, alternates for the Markdown page, llms.txt, llms-full.txt and api.json, and JSON-LD as a graph with the page, its breadcrumbs and the machine-readable files.

symbols.ts holds one vocabulary of Unicode symbol, emoji and label for everything the pages express; a theme picks the set with symbols.

Verified: tsc is clean for these files; bun test passes for render (36, snapshots refreshed), security and Markdown (75). The browser tests were not run: the Playwright browser was missing from the cache at the time. doc.tsx's admonition case is left to the commit that adds the admonition block to the model.
A module can now carry narrative guides beside its API reference. All
schema additions are optional, so an older model still validates and
renders the same bytes.

Schema:
- module.guides[]: Guide { id, slug, title, summary?, group?, order?,
  body?, source? }. The body is the existing block tree, so guides reuse
  the documentation renderer. Pages list ungrouped guides first, then
  each group in the order of its first guide; inside each, guides with
  an order come first, lowest first, and the rest keep model order.
- Ref.section: an anchor on the target's page. Links to a guide use the
  guide's id; links to a guide section add the section's anchor. This
  works from API doc comments and from guides, in HTML and Markdown.
- Heading.anchor: an explicit anchor, when the author sets one.
- A new block kind, admonition { tone, title?, children }, with tones
  note, tip, important, warning, caution, apiNote, implSpec, implNote.

Rendering:
- guides/<slug>.html and .md. The slug becomes a file path, so it is
  slugified segment by segment, and a page already taken (compared
  without case) gets a -2 suffix.
- Every heading in a guide gets a readable anchor: its own or one from
  its text, deduplicated with -2, -3, never one of the shell's ids.
  Level-2 and level-3 headings are the page's sections and fill its
  "On this page" rail.
- src/narrative.tsx has the guide page (sections, heading self-links,
  admonitions through Callout, previous and next guides), a GuideIndex
  for the overview, and re-exports guideNav(site, page) from site.ts.
- llms.txt lists the guides before the reference pages, llms-full.txt
  puts them right after the overview, the search index has an entry
  per guide and per section, the sitemap lists them, and index.md gets
  a Guides list. An unresolved guide link renders as plain text.
- doc.tsx renders admonitions in doc comments (the main session's edit,
  committed here because it needs the model change).

Checks run: tsc is clean for these files; render, markdown and security
tests pass (111). Rendering the fixture and both samples (guides
removed) with the previous site, structure, markdown, render, model and
doc files and with these gave identical bytes for all 286 files, with
the neutral theme and with the Elide theme and a base URL.
The Java (geo) and Kotlin (kgeo) samples each get a set of guides that
exercises the new model:

- Getting started: install snippets and a first example.
- Concepts: h2 sections and h3 subsections, a duplicate heading, a
  table, nested and ordered lists, an admonition of every tone (with
  and without a title), links to types, members, an overload, a nested
  type and a package, a link to a section of another guide, an
  external link, and two unresolved links (a declaration and a guide).
- Migrating from 1.x: links to the deprecated declarations.
- One group (Advanced in Java, Coroutines in Kotlin) with a nested
  slug. In Java, the migration guide has no order and the group's
  second guide is listed first, to show how pages order guides.

Doc comments link back: the module overview, a package description, a
deprecation and an @see to a guide section. samples/build.ts gains
guide() and ADMON() builders, and md() reads [[guide:slug#section|label]].
FEATURES.md lists each feature and its page.

Checks run: both samples validate against the schema, and the output
checker passes for both with the Elide theme. The only unresolved
links are the deliberate ones (plus an existing JDK member link).
… and style them

Guides lead the navigator, with their groups; the overview lists them as cards before the packages; search ranks a guide with packages and a guide section with members. Guide pages get a kicker, section links that show on hover or focus, previous and next cards, and a reading-progress line driven by scrolling alone where the browser supports scroll timelines. The rail's filter is labelled for sections on a guide and appears only on a page with more than eight entries.

Verified: bun test passes for render (36, snapshots refreshed), security and Markdown (75); the guide page was checked by eye in Chromium. The browser tests were not run.
`bun run audit` (root alias `apidocs:audit`) builds the samples (or a
--model) with dist/runner.mjs, serves each site on its own localhost port
with compression and cache headers, and runs three audits:

- Lighthouse 13.6.0 (pinned), programmatically, in Playwright's Chromium,
  mobile and desktop, on the overview, the largest package page, a small
  type page and the largest type page. Failing weighted audits are
  recorded with their values; server-dependent audits are marked "host".
- Agent readiness: the checks Is Agentic (is-agentic.com, scanned by Ora)
  scores for a documentation site, implemented locally from Ora's public
  rules (version 2), with Ora's layer-weighted formula. Is Agentic only
  scans public URLs, so nothing is submitted to it.
- good-css.com: its skill's nine rules for all CSS, checked over the
  shipped stylesheets, plus a review checklist of its 47 entries.

It prints a table, writes full reports to a temporary directory, and
exits 1 below the thresholds (default 100, set by flags). AUDITS.md says
where each rule comes from and what cannot be tested locally.

Checks run: `bun test test/audit.test.ts` (8 pass); tsc clean for the
new files; `bun run audit` over both samples and presets.
…e sample signatures

Markdown and llms.txt:
- The theme's symbol set (default utf) marks page titles with their kind
  (module, package, type kind, guide), note and deprecation labels,
  Throws and Returns, API-kind admonitions, and each llms.txt entry
  before its link text. Mode "none" writes no symbols.
- Each .md page has a location line under its title: links up to the
  module overview and, for a type, its package, then llms.txt. The
  overview links llms.txt and llms-full.txt. llms.txt's intro says
  llms-full.txt has every page in one file and api.json is the model,
  and its Overview list adds llms-full.txt. llms.txt escapes [ ] < > in
  titles.
- The Markdown tests render with symbols "none"; the fixture snapshots
  change only by the location line and the llms.txt intro.

Samples: transform and a new ShapeReader.readAll (Java), and new
Geometry.transformShapes and nearest (Kotlin), carry signatures laid out
as google-java-format (+8 parameters, throws on its own line) and ktfmt
(+4 parameters, closing parenthesis and return type on their own line)
lay them out. compactTokens turns such newlines into single spaces, so
summaries and member titles stay on one line.

Known gap: layoutSignature (src/signature.ts) re-breaks a signature
that already has newlines, adding blank lines in HTML; it should leave
such a signature as it is.

Checks run: bun test for render, markdown, security and narrative suites
(128 pass, 0 fail); tsc clean outside scripts/audit.
…alues

test/narrative.test.ts covers: both samples with guides validate; an
admonition without a tone or with an unknown one is rejected; a model
without guides writes no guide file or link, and an empty list renders
the same pages; guide ordering; slugs as safe, deduplicated paths;
anchors that are readable, deduplicated, never a shell id, with explicit
anchors winning; guide and section links in HTML and Markdown, and an
unresolved guide link as plain text; the checker reporting a missing
section; llms.txt and llms-full.txt order; search entries for guides and
sections; the sitemap; every admonition tone in HTML and Markdown; HTML
and Markdown snapshots of guide pages; one-line compact tokens; and
hostile titles, summaries, anchors, sections, URLs and raw HTML.

The output checker found on* attributes by scanning tags up to the first
>, so escaped text such as onerror= inside a meta content value counted
as an attribute. It now scans tags to the first > outside a quoted
value and reads attribute names with the values blanked.

README gains a Guides section.

Checks run: bun test test/narrative.test.ts test/render.test.ts
test/markdown.test.ts test/security.test.ts: 128 pass, 0 fail.
Javadoc's four index pages, each with a Markdown twin and written only
when it has content. The module overview (index.html) stays the module
reference.

- packages.html: every package with its summary and counts of types by
  kind.
- types.html: every type, nested ones too, in one list by simple name,
  with kind, package and summary.
- index-all.html: every type and member, grouped by first letter, with
  a letter bar linking each group. Each entry shows the name linked to
  its anchor, what it is and where ("method in Shapes"), and the
  summary. Overloads are listed separately by their compact parameter
  types. Guides, if any, come first under their own heading.
- deprecated.html: deprecated packages, types and members, grouped by
  kind, for removal first, with the deprecation text.

src/index-data.ts holds the lists, sorted with a locale-independent
comparison: case-insensitive first, then by code point. src/indexes.tsx
holds the pages, which use Shell and the existing classes plus the new
nav.letter-bar, section.index-letter, ul.index-list > li.index-entry,
a.index-name, span.index-where and span.index-summary (no CSS here).
src/site.ts exports PACKAGES_PAGE, TYPES_PAGE, INDEX_ALL_PAGE,
DEPRECATED_PAGE, hasDeprecated(site) and indexPages(site), which a top
bar can link. llms.txt lists the pages under "Indexes", and sitemap.xml
includes them.

Checks run: `bun test test/indexes.test.ts` (11 pass, 4 snapshots). For
both samples it covers: every page and its Markdown twin; checker clean
on the index pages; letters sorted and linked. It also covers separate
overloads, removal first, guides first, no deprecated.html when nothing
is deprecated, and no index pages for an empty model.
`bun test test/render.test.ts` (36 pass). tsc clean. Over the whole
sample sites, the checker also reports the page shell's skip link
href="#content" without a file name on every page. That comes from the
uncommitted chrome.tsx in the working tree, so this test leaves it to
the shell's own tests.
A member is now one disclosure: closed, a row of its compact signature and summary sentence; open, the full entry. This replaces the separate member summary tables, so a type page says each thing once and is much shorter. The anchor is inside the folded part, so a link to a member and the browser's find-in-page open the entry with no script; a small script covers browsers that do not. Rows mark a member that has an API note or is deprecated. A group can be expanded or folded at once, and a theme can start members expanded (memberDetails).

Also from web.dev's current guidance: the search box is a search element; speculation rules prerender a page of the same site when its link is hovered or pressed; first paint waits for the content element, so page transitions start from real content; where the browser can trim a line box to the letters, a title is aligned to its kind tile exactly.

From the first audit run: both halves of the formats control meet the 24px target size; the load bar animates only when the reader has not asked for less motion; inputs show focus with :focus-visible. A signature that already has line breaks is shown as the formatter laid it out.

Verified: tsc clean; bun test passes for render, security, Markdown and audit, and for narrative except one hostile-guide assertion that fails on output from the index pages being added in parallel. Folding, opening by link and the markers were checked by eye in Chromium. The browser tests were not run.
The top bar links the overview and each index page that exists (packages, all types, A to Z, deprecated), and the index pages get their letter bar and entry lists styled. A guide's title on the A-Z Markdown page is escaped as prose, not written as a code span.

Verified: tsc clean; bun test passes all 165 tests, including the browser tests from file:// with JavaScript on and off and the accessibility checks (PLAYWRIGHT_BROWSERS_PATH set to the shared browser cache).
@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

React Doctor found 306 new issues in 18 files · 3 errors & 303 warnings · score 43 / 100 (Critical) · 0 fixed · vs main

Errors

303 warnings

samples/index.ts

  • ⚠️ L6 JSON parse/stringify deep clone no-json-parse-stringify-clone

scripts/audit.ts

  • ⚠️ L86 Array lookup inside a loop js-set-map-lookups
  • ⚠️ L108 await inside a loop async-await-in-loop
  • ⚠️ L131 await inside a loop async-await-in-loop

scripts/audit/agentic.ts

  • ⚠️ L357 Array lookup inside a loop js-set-map-lookups
  • ⚠️ L499 fetch Response consumed without status check no-fetch-response-used-without-status-check
  • ⚠️ L509 await inside a loop async-await-in-loop

scripts/audit/css.ts

  • ⚠️ L177 Array lookup inside a loop js-set-map-lookups

scripts/audit/html.ts

  • ⚠️ L160 Array lookup inside a loop js-set-map-lookups

scripts/audit/remote.ts

  • ⚠️ L48 await inside a loop async-await-in-loop
  • ⚠️ L55 await inside a loop async-await-in-loop

src/astro/Search.tsx

  • ⚠️ L42 Data fetching inside an effect no-fetch-in-effect
  • ⚠️ L90 Unknown DOM property no-unknown-property
  • ⚠️ L91 Label missing associated control label-has-associated-control
  • ⚠️ L91 Unknown DOM property no-unknown-property
  • ⚠️ L91 Unknown DOM property no-unknown-property
  • ⚠️ L92 Unknown DOM property no-unknown-property
  • ⚠️ L92 Unknown DOM property no-unknown-property
  • ⚠️ L99 Unknown DOM property no-unknown-property
  • ⚠️ L100 Unknown DOM property no-unknown-property

src/astro/render.tsx

  • ⚠️ L61 Unstable context provider value jsx-no-constructed-context-values

src/astro/text.ts

  • ⚠️ L62 Unsafe JSON.parse dereference no-unsafe-json-parse

src/client/behaviors.tsx

  • ⚠️ L120 Unknown DOM property no-unknown-property
  • ⚠️ L125 Interactive control contains another focusable control html-no-nested-interactive
  • ⚠️ L126 Unknown DOM property no-unknown-property
  • ⚠️ L127 Unknown DOM property no-unknown-property
  • ⚠️ L128 Unknown DOM property no-unknown-property
  • ⚠️ L414 Unguarded call to a throwing parse API no-unguarded-throwing-parse-call

src/components/callout.tsx

  • ⚠️ L27 Unknown DOM property no-unknown-property
  • ⚠️ L28 Unknown DOM property no-unknown-property
  • ⚠️ L31 Unknown DOM property no-unknown-property
  • ⚠️ L32 Unknown DOM property no-unknown-property

src/components/chrome.tsx

  • ⚠️ L285 Unknown DOM property no-unknown-property
  • ⚠️ L286 Unknown DOM property no-unknown-property
  • ⚠️ L287 Unknown DOM property no-unknown-property
  • ⚠️ L289 Unknown DOM property no-unknown-property
  • ⚠️ L292 Unknown DOM property no-unknown-property
  • ⚠️ L309 Unknown DOM property no-unknown-property
  • ⚠️ L320 Unknown DOM property no-unknown-property
  • ⚠️ L322 Unknown DOM property no-unknown-property
  • ⚠️ L330 Unknown DOM property no-unknown-property
  • ⚠️ L331 Label missing associated control label-has-associated-control
  • ⚠️ L331 Unknown DOM property no-unknown-property
  • ⚠️ L331 Unknown DOM property no-unknown-property
  • ⚠️ L332 Unknown DOM property no-unknown-property
  • ⚠️ L332 Unknown DOM property no-unknown-property
  • ⚠️ L334 Unknown DOM property no-unknown-property
  • ⚠️ L335 Unknown DOM property no-unknown-property
  • ⚠️ L352 Unknown DOM property no-unknown-property
  • ⚠️ L353 Unknown DOM property no-unknown-property

253 more warnings not shown.

Reviewed by React Doctor for commit fb0eba5. See inline comments for fixes.

import { javaSample } from "./java";
import { kotlinSample } from "./kotlin";

const plain = (model: Model): Model => JSON.parse(JSON.stringify(model));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-json-parse-stringify-clone (warning)

JSON.parse(JSON.stringify(x)) deep-clones by re-serializing: it is slow on large objects and silently drops undefined, functions, Date/Map/Set, and cyclic references. Use structuredClone(x).

Fix → Replace JSON.parse(JSON.stringify(value)) with structuredClone(value). It is faster and preserves Dates, Maps, Sets, and cyclic references.

Docs

const dir = join(reportDir, "sites", input.name);
const server = serve(dir, host);
servers.push(server);
const theme = { ...extraTheme, extends: extraTheme.extends ?? input.preset, ...(args.includes("--no-base-url") ? {} : { baseUrl: server.url }) };

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/js-set-map-lookups (warning)

This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.

Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time

Docs

results.push({ audit: "css", target: `${site.name} stylesheets`, score: css.score, threshold: threshold.css, failures: css.rules.filter(r => r.status !== "pass").map(r => `${r.rule} (${r.evidence.split(" ")[0]})`), findings: [...css.rules, ...css.checklist], report });
}
if (only.has("agentic")) {
const agentic = await agenticAudit(site);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/async-await-in-loop (warning)

This for…of loop waits before starting the next iteration. If iterations perform independent asynchronous work, consider bounded concurrency; await syntax alone does not establish a speedup.

Fix → Consider concurrent calls only for independent asynchronous work. Shared queues or synchronous work may not benefit. Preserve resource limits, transaction ordering, and failure/cancellation semantics; observe all callback promises.

Docs

Comment thread packages/apidocs/scripts/audit.ts Outdated
const t = Date.now();
let run: LighthouseRun;
try {
run = await lh.run(site.url + page, formFactor, base);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/async-await-in-loop (warning)

This for…of loop waits before starting the next iteration. If iterations perform independent asynchronous work, consider bounded concurrency; await syntax alone does not establish a speedup.

Fix → Consider concurrent calls only for independent asynchronous work. Shared queues or synchronous work may not benefit. Preserve resource limits, transaction ordering, and failure/cancellation semantics; observe all callback promises.

Docs

set("ax-document-structure", {
score: s1, max: 3, status: statusOf(s1, 3),
evidence: `${structureOk.length}/${rows.length} pages have one main, one h1 and no heading skip over 1. Landmarks (header, nav, main, footer) present on average: ${landmarkAvg.toFixed(1)}/4.`,
where: rows.filter(r => !structureOk.includes(r)).slice(0, 5).map(({ page, f }) => `${page}: main ${f.landmarks.main}, h1 ${f.h1}, skip ${f.maxHeadingSkip}`),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/js-set-map-lookups (warning)

This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.

Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time

Docs

<button type="button" class="theme-switch" data-theme-switch data-js-only aria-label="Color theme: system">
{/* The drawn icon everywhere; a sun or a moon where the platform's emoji are good (data-emoji). */}
<span aria-hidden="true" class="theme-icon" />
<span aria-hidden="true" class="theme-emoji" />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

</button>
</div>
</header>
<div class="layout">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<div class="layout">
<Navigation />
<script dangerouslySetInnerHTML={{ __html: NAV_BOOT }} />
<main id="content" class="content">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<script dangerouslySetInnerHTML={{ __html: NAV_BOOT }} />
<main id="content" class="content">
{/* For programs that read the page as text: where the other forms are. Not shown, not read aloud. */}
<p class="visually-hidden" aria-hidden="true" data-agent-note>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<p class="visually-hidden" aria-hidden="true" data-agent-note>
{`Machine-readable versions of this page. Markdown: ${formats.markdown} . Index of every page (llms.txt): ${formats.llms} . The whole reference in one Markdown file: ${formats.full} . The API model as JSON (apidocs/1): ${formats.model} .`}
</p>
<div class="page-tools">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

@codecov

codecov Bot commented Nov 21, 2026

Copy link
Copy Markdown

Bundle Report

Bundle size has no change ✅

… compose

Shell was one component that rendered the whole document. It is now a
composition of exported parts: headData (the head metadata as data),
HeadMeta and JsonLd (that data as elements), TopBar, ModuleVersion,
SearchField, Navigation, AgentNote, PageTools, Breadcrumbs, PageActions,
Toc and Footer.

Shell also gains an "astro" variant, chosen through ShellVariantContext,
for the Astro integration that follows: it leaves out what only a static
site needs (the stylesheet links, the deferred client bundle, the
speculation rules and the script font preload), marks the top bar and the
navigator with the attribute Astro's client router persists elements by,
and puts named holes where the Astro component adds its own content (a
top-bar slot, the search island, a notice above the page). The static
variant is the default, so nothing that renders a page changes.

Verified: render() output for the Java, Kotlin and fixture models, with
the neutral and Elide presets, with and without a baseUrl (12 sites), is
byte-identical to the previous commit. tsc is clean.
…sk lists

A model whose module has guides and no packages now renders as a complete
documentation site, so a Markdown suite can use the same components and
outputs as an API reference.

Schema (backward compatible, all optional):
- Module.overview: the id of a guide that is the overview page itself
  (index.html, index.md) instead of a page under guides/.
- Guide.navTitle: a shorter navigator label (Starlight's sidebar.label).
- Inlines: image (src from the site root, alt required, width and height
  when known), strikethrough, and check (a task-list item's box).
The schema already allowed a model without packages; nothing was relaxed.

Rendering:
- The overview guide renders on index.html with its sections, no kicker or
  breadcrumbs; when packages exist their lists follow it.
- Guides-only: no Packages block, nav filter or All-types fallback, no
  index-all or element-list, search labelled for guides, llms.txt without
  an empty Pages list. Without an overview guide the overview lists the
  guides and no empty package tables.
- Breadcrumbs: a group crumb links to the group's first guide when that
  guide has the group's title; ungrouped guides drop the "Guides" crumb
  on a guides-only site. Markdown twins use the same trail.
- llms.txt escapes the module name and summaries like titles.
- "packages" and "all-types" are reserved anchors for guide headings.
- CSS: images fit the column; task items show their box, not a bullet.

Verified: tsc clean; bun test over render, narrative, markdown, indexes and
security: 139 pass, existing snapshots unchanged.
src/import/markdown.ts turns a suite of Markdown files with Starlight-style
frontmatter into apidocs/1 guides, so whole documentation suites render
with the same components and outputs as the API reference.

- Parser: mdast-util-from-markdown 2.1.0 with micromark-extension-gfm
  3.0.0 and mdast-util-gfm 3.1.0; yaml 2.9.1 for frontmatter; all exact
  dev dependencies. mdast was chosen over marked because every node has a
  position, so diagnostics carry file and line, and the model is built
  from the tree; no generated HTML is ever used.
- Frontmatter: title, description, sidebar.label (navTitle),
  sidebar.order, draft (left out unless included). Unknown keys are
  errors naming file, line and key unless listed as extra keys.
- Structure: the root index.md is the overview guide; directories are
  groups titled by their index.md, nested ones "Parent › Child"; order by
  sidebar.order then file name; ids guide:<suite>/<path>.
- Markdown: CommonMark and GFM tables, task lists, strikethrough,
  autolinks, fenced code (no language is "text"), GitHub alerts as
  admonitions, {#id} heading anchors, comments dropped (sync blocks
  included), raw HTML as raw nodes (an inline element kept whole for the
  sanitizer), images copied beside the pages with their size read from
  PNG, GIF, JPEG, WebP or SVG headers. Footnotes and MDX are reported.
- Links: .md links become guide references with sections checked at
  import (renderer anchors, {#id} and GitHub slugs all match); links
  outside the suite go through prefix mappings or are errors; links to
  left-out drafts are warnings and render as text; unsafe URLs are
  reported and dropped.
- CLI: `apidocs guides --src --id --title --out [--theme] [--version]
  [--base-url] [--source-link] [--source-root] [--link p=t ...]
  [--include-drafts] [--warn-only] [--assets]`, with `guides` and
  `apidocs:guides` scripts. Diagnostics print as file:line: message; any
  error exits 1 and writes nothing unless --warn-only.
- Programmatic use: the "./import" subpath export; the root export, the
  render bundle and the client bundle stay free of it.
- Dev: `bun run dev --guides <dir>` serves a suite with reload on edits,
  and the dev bar offers the Markdown sample suite (samples/guides).

Tests: importer unit tests per construct, the diagnostics fixture
(test/fixtures/guides-errors), hostile Markdown, the sample site through
the output checker, snapshots, the CLI, Komodo's suites when present, and
a Chromium test from file:// with JavaScript on and off plus axe.
A suite's other files were copied beside the pages unless they ended in
.html or .htm, so a suite could ship active content (an SVG with script,
.xhtml, .xml with a stylesheet, .mht, .shtml) that runs on the site's
origin when opened directly.

- An allowlist replaces the blocklist: png, jpg, jpeg, gif, webp, avif
  and svg, matched on the final extension without case. A name with a
  second document-like extension (shot.html.png) or ending in a dot or a
  space is refused. Everything else is an error with file and line (a
  warning under --warn-only) and is not copied. Komodo's two suites link
  no files at all, so no download types are allowed.
- SVG is rebuilt on copy by src/import/svg.ts from an allowlist of
  drawing elements and presentation attributes. script, style,
  foreignObject, image, a, animation elements and event handlers are
  dropped with their content; href survives only as #fragment on use,
  textPath, gradients and patterns; url() only as url(#fragment). A
  DOCTYPE, CDATA, an unknown entity or unparseable markup refuses the
  file.
- CopiedFile now carries the bytes read with the suite (the sanitized SVG);
  the CLI and the dev server write those, never a fresh read of the
  path, and readSuite already skips symbolic links. The dev server sends
  nosniff with them.

Tests: each refused type gets its diagnostic and stays out of the output;
a hostile SVG (script, onload, foreignObject with HTML, external use,
data: and javascript: hrefs, @import, external url()) comes out as inert
shapes; a DOCTYPE SVG is refused; symbolic links into and out of the
suite are not followed; the sample diagram and PNG still work. bun test
test/import.test.ts: 43 pass.
Theme header links went into href as written, so a relative link to a
sibling site (../developer/index.html) worked only from root pages. They
now go through hrefFor, the existing helper that resolves a theme path
from the site's root.

With four sibling links (User guide, Developer guide, API reference,
GitHub) the top bar overflowed a 390px phone by 150px and pushed the
theme switch off a 1024px screen. The links now hide below 1100px, where
the index links already hide.

Checked by measuring the top bar's overflow on Komodo's user suite and the
Java sample with four header links at 1440, 1280, 1180, 1101, 1024 and
390px: none on the guides site; the API site still overflows by 31 to
78px between 1101 and 1180px, where its five index links and four header
links do not fit (open).
The README gains a Markdown suites section: the apidocs guides command and
its options, the exit status and diagnostics format, programmatic use
through @elide/apidocs/import, the dev loop, the files, frontmatter,
Markdown, links and images the importer reads, which files are copied and
how SVG is sanitized, the headers a host should send for copied files
(nosniff, and CSP sandbox for anything that is not an embedded image), and
what is not supported. The Guides section describes module.overview,
guides-only sites, navTitle and group crumbs; Tests lists the new suites.
FEATURES.md lists the Markdown sample suite, page by page.
The SVG sanitizer removed backslashes and controls from a presentation
value and then searched the rest for javascript:, url( and the like. A
browser decodes CSS escapes instead of removing them, so an escaped form
(\75 rl(, \6a avascript:) read one way to the check and another way to
the browser.

Nothing is removed now. A presentation or geometry value with a
backslash or a control character is dropped. A value that mentions url
must be exactly one same-document url(#id); expression, @import,
javascript:, vbscript: and data: drop it, tested on the lowercased value
as written. Names and prose (id, class, role, aria-*, lang) only refuse
control characters, so an aria-label may say "curl". The style attribute
and the style element were already dropped. Literal tabs and newlines in
an attribute become spaces first, as XML itself normalizes them, so path
data written over several lines keeps working; the same characters
written as references are refused, and &#0; refuses the file.

Tests: hex and single-character escapes of url, javascript and
expression, an escape followed by whitespace, escapes inside url, literal
null bytes, a &#1; reference, several url() forms that are not exactly
one #id, and url(#gradient) that must pass. bun test
test/import.test.ts: 44 pass.
A member's row is the summary of a disclosure, which is itself a control, so it may hold no links: axe reported nested-interactive on every row, and the JavaScript-off test still looked for the old member sections. The row's signature and summary sentence are now text; the full, linked signature and description are in the entry it opens. The JavaScript-off test checks that every entry is in the page and that one opens with a click and no script.

These five browser tests had been failing since the members were folded into rows; that commit's message said the browser tests were not run.

Verified: bun run build, then bun test: 221 pass, 0 fail, including the browser and accessibility tests.
The static bundle's behaviors move from islands.tsx into behaviors.tsx,
as exported functions with no side effects at import. Each takes an
optional AbortSignal and ties every listener and observer to it, so a
caller can start them for a page and stop them all at once. That is what
a client router needs: the Astro integration starts them on each
astro:page-load and stops them on astro:before-swap, so page swaps never
stack listeners.

islands.tsx is now only the static entry: it starts the behaviors once,
as before. The site root is read when used rather than once at load,
since an Astro page's root can change without a document load. Two small
generalizations: the menu closer also closes a version menu, and a list
filter that kept its text applies to the new page's rows when it starts.

Verified: bun test passes (221 tests, including the Chromium tests of the
static site from file:// and HTTP); tsc is clean.
…and server islands

@elide/apidocs/astro serves the same pages as the static renderer from an
Astro app, rendered on request or from models the app has at build time,
with the same components and stylesheet. The static renderer is
unchanged.

- resolvePage(model, path, theme?) says what a path under a site's base
  is: a page, a page's Markdown twin, a text file, a redirect from the
  static form (x.html, x/index.html) to the canonical one, or missing.
  Canonical URLs drop .html; packages and the overview are directory URLs.
- <ApidocsPage model page theme base> renders the whole document: Shell's
  astro variant (head metadata, top bar, navigator, content, rail,
  footer) with every link mapped to a root-absolute URL in that form,
  Astro's <ClientRouter fallback="swap" />, the stylesheet bundled by
  Astro, the theme's tokens inline on :root:root, the Elide fonts bundled
  with hashed names and preloaded, and slots for the top bar, a notice
  and the head.
- renderText(model, path, theme?) gives the Markdown twins, llms.txt,
  llms-full.txt, api.json, element-list, the search index, theme.css,
  the theme's artwork and an Astro-form sitemap.xml.
- Search is a Preact island (client:idle) that fetches a JSON index on
  first use and opens results through the router. The other behaviors
  start on astro:page-load and stop on astro:before-swap. The top bar and
  the navigator persist across pages of one site (transition:persist,
  keyed by the base); before each swap the client moves the new page's
  index links and navigator rows into them, keeping the filter field and
  the scroll position. The load bar runs from astro:before-preparation
  and finishes on arrival. An Astro-only stylesheet turns the browser's
  cross-document view transitions off, so they never run alongside the
  router's.
- <VersionSelect> and <VersionNotice> render a version menu and a
  "not the latest release" line, each a fixed box so a server island can
  replace a fallback of itself without moving anything.
- apidocs(options) injects a route per site for apps with build-time
  models, adds the Preact renderer, dedupes Preact, and puts the version
  menu and notice in server islands that call the app's loadVersions.

apps/apidocs-astro is a sample on the Cloudflare adapter: the Java
sample at /java/2.0/ and /java/main/, the Kotlin sample, and the
Markdown sample suite. Root scripts: apidocs:astro:dev, :build and
:preview (port 5190).

Verified: bun test passes, including the new test/astro.test.ts (every
page and text file of the Java, Kotlin, fixture and Markdown-suite
models resolves in both URL forms, the Markdown and text files equal
render()'s, and each page's head metadata equals the static page's apart
from the URL form). tsc is clean in the package and the app. The sample
builds and serves under wrangler dev; static output is unchanged.
A security review found that mapUrl appended a resolved link to the base
without checking its shape, and that documentation comments, which are
untrusted, could steer it: a target that began with "/" or "\", or held a
backslash or a control character, could come out as "//host" or "/\host",
which browsers read as another origin. resolvePage's redirect targets,
which an app writes into a Location header as base + to, had the same
gap through names in the model (a package named ".host.x" gives a page
path that starts with "/").

- mapUrl runs the URL through safeUrl first and drops the attribute when
  safeUrl rejects it, so the link renders as text. A URL with a backslash
  or a control character, or whose target resolves to a path starting
  with "/", is not rewritten: it keeps the static page's form, relative
  to the page, with backslashes percent-encoded, and is dropped when
  safeUrl's removal of tabs and newlines would turn it into "//...". A
  rewritten URL must start with the base (or baseUrl) it was mapped
  under, must not start with "//" or "/\", and must pass safeUrl
  unchanged; otherwise the static form is kept.
- assertBase rejects a base that is not an absolute path with a single
  leading "/", a trailing "/", and plain segments, at configuration time
  in apidocs() and on every render. "/" is a valid base.
- resolvePage returns missing instead of a redirect whose target is not
  base-relative (isBaseRelative: no scheme, no leading "/" or "\", no
  backslash or control character, no empty, "." or ".." segment).

Tests cover links and request paths of the forms //host, /\host,
\\host, \/host, %5C%5Chost, %2F%2Fhost, ..//host, ....//, tabs and
newlines in the path, with a base of "/" and of "/docs/", a model whose
package name would escape the base, and a normal relative link that
still maps. bun test passes; tsc is clean.
The package declared "sideEffects": false, so when Astro bundled ApidocsPage's script, whose only statement is `import "./client"`, the bundler dropped the import as unused and Astro emitted no script: the router ran, but no behavior started and the persisted navigator never followed the page. The package now lists the files that do have side effects: its stylesheets, the Astro client and the static client entry.

Verified: the production build of the sample app has the client chunk again, and the navigator shows the new page as current after a client-side navigation.
…aceholder

Folded member rows use content-visibility: auto with a 41px placeholder, but a closed row is 38px tall (and 39px with the elide preset's type scale). Rows inside the first viewport were laid out at the placeholder size first and shrank once rendered, moving everything below: a cumulative layout shift of 0.0003 on the Java sample's Circle page, in the static output and in Astro alike, with or without web fonts.

The first 24 rows of each group now render as usual; 24 rows fill any screen, so only rows that start off screen keep the placeholder. Long pages stay cheap: ShapeCatalog's hundreds of rows are still skipped until they come near.

Verified: Circle reports no layout shift in Chromium on the static dev server and in the Astro sample; bun test passes (259 tests, including the static layout-stability tests). No HTML changes.
test/browser.test.ts builds the sample, serves it with wrangler dev on port 5191 (or uses APIDOCS_ASTRO_URL), and checks: link, back and forward navigation without a document load; scroll restored on back; the route announced; keyboard focus kept on a followed navigator row; prefetch on hover; the navigator keeping its scroll position and filter text and marking the new page; the top bar's index links following the page; every behavior working once after ten navigations; listener, node and document counts flat over twenty; no layout shift on first load (with the version islands arriving) or across a navigation; the version menu opening the same page in another version; complete pages and working links with JavaScript off; no animation under reduced motion; axe in light and dark on a type page, guides, an index page, a package page and the Markdown suite; and head metadata equal to the static renderer's apart from the URL form.

Verified: 27 pass. Listeners 215 and nodes 1058, after 4 and after 24 navigations.
…4 from Astro

Astro serves the response itself, so it can do what a static host cannot: a request for a page that prefers text/markdown gets the page's Markdown twin at the same URL (Vary: Accept), every page sends a Link header naming its twin, llms.txt and api.json, and a missing page answers 404 in Markdown or HTML, pointing at the overview and llms.txt. The helpers (prefersMarkdown, linkHeader, notFound) are exported for apps with their own route. The integration's route also gives renderText the site's absolute URL from the request, so sitemap.xml exists.

The Link header names no canonical URL: the page declares its own, and Lighthouse reads a second one in a different form as a conflict (its canonical check failed, SEO 92, until it was dropped).

Verified: bun test passes; the sample's browser suite passes (27); bun run audit --url on the served Java sample scores Lighthouse 100 in every category on four pages, mobile and desktop, and agent readiness 96.
bun run audit --url <base URL> runs Lighthouse and agent readiness on a site that is already served, such as the Astro sample app, instead of building one. It reads the site's llms.txt for its pages, fetches each at its Astro URL, and saves it in the static layout with its links mapped back to the static form, for the checks that read files; the checks that make requests, and Lighthouse, go to the server, through a new Site.urlOf.

The agent user-agent check now compares the main text of the responses rather than their byte length: a page with server islands differs in every response, since each render encrypts the islands' props anew, while its content is the same.

Verified: on the static Java sample the agent-readiness score is unchanged (93); on the served Astro sample it is 96. bun test passes (test/audit.test.ts included).
On a cold start, and after anything that changed the dev server's dependencies, the first page request failed with Preact's "Cannot read properties of null (reading '__H')": Vite found preact/jsx-dev-runtime and the other entry points only while serving that request, optimized again, and the request ran with two copies of Preact. apidocs() now lists Preact's entry points for optimization in the client and server environments.

Verified: with the app's Vite cache removed, the first requests to /java/2.0/com/example/geo/Circle, /kotlin/ and /guides/ answer 200, and the log has no __H error. Hot reload checked in Chromium: editing apidocs-astro.css updates the page in place without a reload; touching chrome.tsx, samples/java.ts or a file of the Markdown suite reloads the page.
A README section for @elide/apidocs/astro: when to use it and when the static renderer, the URL form and its redirects, the contract (resolvePage, ApidocsPage and its slots, renderText, the serving helpers, VersionSelect and VersionNotice, apidocs(), assertBase), an on-request example and a build-time one, the server-island pattern with a fallback that reserves the island's box and the ASTRO_KEY caveat, caching guidance, each behavior and how it starts on an Astro page, and the sample app's scripts.
preact-render-to-string is a dependency of @elide/apidocs, not of the app, so Vite could not resolve it from the app's root and warned in both environments. Preact's own entry points are what the first request was missing; the list now has only those.

Verified: a cold astro dev start answers 200 on its first requests with no warning and no __H error; astro sync is clean.
import { javaSample } from "./java";
import { kotlinSample } from "./kotlin";

const plain = (model: Model): Model => JSON.parse(JSON.stringify(model));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-json-parse-stringify-clone (warning)

JSON.parse(JSON.stringify(x)) deep-clones by re-serializing: it is slow on large objects and silently drops undefined, functions, Date/Map/Set, and cyclic references. Use structuredClone(x).

Fix → Replace JSON.parse(JSON.stringify(value)) with structuredClone(value). It is faster and preserves Dates, Maps, Sets, and cyclic references.

Docs

const dir = join(reportDir, "sites", input.name);
const server = serve(dir, host);
servers.push(server);
const theme = { ...extraTheme, extends: extraTheme.extends ?? input.preset, ...(args.includes("--no-base-url") ? {} : { baseUrl: server.url }) };

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/js-set-map-lookups (warning)

This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.

Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time

Docs

results.push({ audit: "css", target: `${site.name} stylesheets`, score: css.score, threshold: threshold.css, failures: css.rules.filter(r => r.status !== "pass").map(r => `${r.rule} (${r.evidence.split(" ")[0]})`), findings: [...css.rules, ...css.checklist], report });
}
if (only.has("agentic")) {
const agentic = await agenticAudit(site);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/async-await-in-loop (warning)

This for…of loop waits before starting the next iteration. If iterations perform independent asynchronous work, consider bounded concurrency; await syntax alone does not establish a speedup.

Fix → Consider concurrent calls only for independent asynchronous work. Shared queues or synchronous work may not benefit. Preserve resource limits, transaction ordering, and failure/cancellation semantics; observe all callback promises.

Docs

const t = Date.now();
let run: LighthouseRun;
try {
run = await lh.run(at(site, page), formFactor, base);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/async-await-in-loop (warning)

This for…of loop waits before starting the next iteration. If iterations perform independent asynchronous work, consider bounded concurrency; await syntax alone does not establish a speedup.

Fix → Consider concurrent calls only for independent asynchronous work. Shared queues or synchronous work may not benefit. Preserve resource limits, transaction ordering, and failure/cancellation semantics; observe all callback promises.

Docs

set("ax-document-structure", {
score: s1, max: 3, status: statusOf(s1, 3),
evidence: `${structureOk.length}/${rows.length} pages have one main, one h1 and no heading skip over 1. Landmarks (header, nav, main, footer) present on average: ${landmarkAvg.toFixed(1)}/4.`,
where: rows.filter(r => !structureOk.includes(r)).slice(0, 5).map(({ page, f }) => `${page}: main ${f.landmarks.main}, h1 ${f.h1}, skip ${f.maxHeadingSkip}`),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/js-set-map-lookups (warning)

This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.

Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time

Docs

const product = theme.productName ?? site.model.module.name;
return (
<header class="topbar" {...persistAttr(variant, "apidocs-topbar")}>
<input type="checkbox" id="apidocs-nav-toggle" class="nav-toggle visually-hidden" aria-label="Toggle navigation" autocomplete="off" />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<header class="topbar" {...persistAttr(variant, "apidocs-topbar")}>
<input type="checkbox" id="apidocs-nav-toggle" class="nav-toggle visually-hidden" aria-label="Toggle navigation" autocomplete="off" />
<script dangerouslySetInnerHTML={{ __html: NAV_STATE_BOOT }} />
<label class="nav-button" for="apidocs-nav-toggle" title="Toggle navigation" aria-hidden="true">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/label-has-associated-control (warning)

Blind users can't identify this field because screen readers find no label text, so add visible text, aria-label, or aria-labelledby.

Fix → Tie every label to a control with htmlFor, or by nesting the input.

Docs

<header class="topbar" {...persistAttr(variant, "apidocs-topbar")}>
<input type="checkbox" id="apidocs-nav-toggle" class="nav-toggle visually-hidden" aria-label="Toggle navigation" autocomplete="off" />
<script dangerouslySetInnerHTML={{ __html: NAV_STATE_BOOT }} />
<label class="nav-button" for="apidocs-nav-toggle" title="Toggle navigation" aria-hidden="true">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<label class="nav-button" for="apidocs-nav-toggle" title="Toggle navigation" aria-hidden="true">
<svg viewBox="0 0 16 16" width="16" height="16"><rect x="2" y="2.75" width="12" height="10.5" rx="2.25" /><path d="M6.25 2.75v10.5" /></svg>
</label>
<a class="brand" href={relative(page, INDEX, ".html")}>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<a class="brand" href={relative(page, INDEX, ".html")}>
{theme.logo?.light && (
<>
<img class="logo logo-light" src={`${root}assets/logo-light.svg`} alt={theme.logo.alt ?? ""} height={22} width={logoWidth(theme.logo.light, 22)} />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

…'s counts

Lint: `@elide/apidocs#lint` had no `dependsOn: ["^build"]`, unlike the other
packages that import workspace packages. On a clean CI checkout `tsc` could
not resolve `@elide/tokens` (TS2307 in src/presets/elide.ts). Linting now
builds the package's dependencies first. Reproduced by deleting
packages/tokens/dist and running `bunx turbo run lint --filter=@elide/apidocs`;
it passes after the change.

Test: "twenty navigations leave listener and node counts flat" sampled the
page once, 300 ms after the last navigation. The router keeps the outgoing
page alive until its transition ends, so on the slower CI runner the sample
caught a transient (218 listeners, 1408 nodes before; 480 and 5006 after),
and a full-file run here showed 215 then 218 with an extra document. The test
now samples until three reads in a row agree. The assertions are unchanged, so
a real leak, which never settles lower, still fails. Passes in two full runs
of apps/apidocs-astro (27 tests each), also with the CPU throttled 8x.

Signed-off-by: Sam Gammon <sam@elide.dev>
import { javaSample } from "./java";
import { kotlinSample } from "./kotlin";

const plain = (model: Model): Model => JSON.parse(JSON.stringify(model));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-json-parse-stringify-clone (warning)

JSON.parse(JSON.stringify(x)) deep-clones by re-serializing: it is slow on large objects and silently drops undefined, functions, Date/Map/Set, and cyclic references. Use structuredClone(x).

Fix → Replace JSON.parse(JSON.stringify(value)) with structuredClone(value). It is faster and preserves Dates, Maps, Sets, and cyclic references.

Docs

const dir = join(reportDir, "sites", input.name);
const server = serve(dir, host);
servers.push(server);
const theme = { ...extraTheme, extends: extraTheme.extends ?? input.preset, ...(args.includes("--no-base-url") ? {} : { baseUrl: server.url }) };

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/js-set-map-lookups (warning)

This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.

Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time

Docs

results.push({ audit: "css", target: `${site.name} stylesheets`, score: css.score, threshold: threshold.css, failures: css.rules.filter(r => r.status !== "pass").map(r => `${r.rule} (${r.evidence.split(" ")[0]})`), findings: [...css.rules, ...css.checklist], report });
}
if (only.has("agentic")) {
const agentic = await agenticAudit(site);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/async-await-in-loop (warning)

This for…of loop waits before starting the next iteration. If iterations perform independent asynchronous work, consider bounded concurrency; await syntax alone does not establish a speedup.

Fix → Consider concurrent calls only for independent asynchronous work. Shared queues or synchronous work may not benefit. Preserve resource limits, transaction ordering, and failure/cancellation semantics; observe all callback promises.

Docs

const t = Date.now();
let run: LighthouseRun;
try {
run = await lh.run(at(site, page), formFactor, base);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/async-await-in-loop (warning)

This for…of loop waits before starting the next iteration. If iterations perform independent asynchronous work, consider bounded concurrency; await syntax alone does not establish a speedup.

Fix → Consider concurrent calls only for independent asynchronous work. Shared queues or synchronous work may not benefit. Preserve resource limits, transaction ordering, and failure/cancellation semantics; observe all callback promises.

Docs

set("ax-document-structure", {
score: s1, max: 3, status: statusOf(s1, 3),
evidence: `${structureOk.length}/${rows.length} pages have one main, one h1 and no heading skip over 1. Landmarks (header, nav, main, footer) present on average: ${landmarkAvg.toFixed(1)}/4.`,
where: rows.filter(r => !structureOk.includes(r)).slice(0, 5).map(({ page, f }) => `${page}: main ${f.landmarks.main}, h1 ${f.h1}, skip ${f.maxHeadingSkip}`),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/js-set-map-lookups (warning)

This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.

Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time

Docs

const product = theme.productName ?? site.model.module.name;
return (
<header class="topbar" {...persistAttr(variant, "apidocs-topbar")}>
<input type="checkbox" id="apidocs-nav-toggle" class="nav-toggle visually-hidden" aria-label="Toggle navigation" autocomplete="off" />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<header class="topbar" {...persistAttr(variant, "apidocs-topbar")}>
<input type="checkbox" id="apidocs-nav-toggle" class="nav-toggle visually-hidden" aria-label="Toggle navigation" autocomplete="off" />
<script dangerouslySetInnerHTML={{ __html: NAV_STATE_BOOT }} />
<label class="nav-button" for="apidocs-nav-toggle" title="Toggle navigation" aria-hidden="true">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/label-has-associated-control (warning)

Blind users can't identify this field because screen readers find no label text, so add visible text, aria-label, or aria-labelledby.

Fix → Tie every label to a control with htmlFor, or by nesting the input.

Docs

<header class="topbar" {...persistAttr(variant, "apidocs-topbar")}>
<input type="checkbox" id="apidocs-nav-toggle" class="nav-toggle visually-hidden" aria-label="Toggle navigation" autocomplete="off" />
<script dangerouslySetInnerHTML={{ __html: NAV_STATE_BOOT }} />
<label class="nav-button" for="apidocs-nav-toggle" title="Toggle navigation" aria-hidden="true">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<label class="nav-button" for="apidocs-nav-toggle" title="Toggle navigation" aria-hidden="true">
<svg viewBox="0 0 16 16" width="16" height="16"><rect x="2" y="2.75" width="12" height="10.5" rx="2.25" /><path d="M6.25 2.75v10.5" /></svg>
</label>
<a class="brand" href={relative(page, INDEX, ".html")}>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<a class="brand" href={relative(page, INDEX, ".html")}>
{theme.logo?.light && (
<>
<img class="logo logo-light" src={`${root}assets/logo-light.svg`} alt={theme.logo.alt ?? ""} height={22} width={logoWidth(theme.logo.light, 22)} />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

@codecov

codecov Bot commented Nov 22, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@sgammon

Copy link
Copy Markdown
Member Author

CI fixes are in fb0eba5: ESLint failed because @elide/apidocs#lint did not build its workspace dependencies first (@elide/tokens unresolved), and the astro leak test sampled before the router's transition settled; it now samples until three reads agree, with the assertions unchanged.

React Doctor's three "Hook called conditionally" errors (narrative.tsx, pages.tsx) are false positives: usePage() is this package's context getter, called from plain helper functions during a static Preact render, not a Preact hook. The 303 warnings (audit scripts, samples) are informational and left as they are; the check itself passes.

Still open: Chromatic's "UI Tests" status is pending because 1 visual change needs to be accepted as a baseline by a person.

@sgammon
Sam Gammon (sgammon) marked this pull request as ready for review November 22, 2026 01:04
import { javaSample } from "./java";
import { kotlinSample } from "./kotlin";

const plain = (model: Model): Model => JSON.parse(JSON.stringify(model));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-json-parse-stringify-clone (warning)

JSON.parse(JSON.stringify(x)) deep-clones by re-serializing: it is slow on large objects and silently drops undefined, functions, Date/Map/Set, and cyclic references. Use structuredClone(x).

Fix → Replace JSON.parse(JSON.stringify(value)) with structuredClone(value). It is faster and preserves Dates, Maps, Sets, and cyclic references.

Docs

const dir = join(reportDir, "sites", input.name);
const server = serve(dir, host);
servers.push(server);
const theme = { ...extraTheme, extends: extraTheme.extends ?? input.preset, ...(args.includes("--no-base-url") ? {} : { baseUrl: server.url }) };

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/js-set-map-lookups (warning)

This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.

Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time

Docs

results.push({ audit: "css", target: `${site.name} stylesheets`, score: css.score, threshold: threshold.css, failures: css.rules.filter(r => r.status !== "pass").map(r => `${r.rule} (${r.evidence.split(" ")[0]})`), findings: [...css.rules, ...css.checklist], report });
}
if (only.has("agentic")) {
const agentic = await agenticAudit(site);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/async-await-in-loop (warning)

This for…of loop waits before starting the next iteration. If iterations perform independent asynchronous work, consider bounded concurrency; await syntax alone does not establish a speedup.

Fix → Consider concurrent calls only for independent asynchronous work. Shared queues or synchronous work may not benefit. Preserve resource limits, transaction ordering, and failure/cancellation semantics; observe all callback promises.

Docs

const t = Date.now();
let run: LighthouseRun;
try {
run = await lh.run(at(site, page), formFactor, base);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/async-await-in-loop (warning)

This for…of loop waits before starting the next iteration. If iterations perform independent asynchronous work, consider bounded concurrency; await syntax alone does not establish a speedup.

Fix → Consider concurrent calls only for independent asynchronous work. Shared queues or synchronous work may not benefit. Preserve resource limits, transaction ordering, and failure/cancellation semantics; observe all callback promises.

Docs

set("ax-document-structure", {
score: s1, max: 3, status: statusOf(s1, 3),
evidence: `${structureOk.length}/${rows.length} pages have one main, one h1 and no heading skip over 1. Landmarks (header, nav, main, footer) present on average: ${landmarkAvg.toFixed(1)}/4.`,
where: rows.filter(r => !structureOk.includes(r)).slice(0, 5).map(({ page, f }) => `${page}: main ${f.landmarks.main}, h1 ${f.h1}, skip ${f.maxHeadingSkip}`),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/js-set-map-lookups (warning)

This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.

Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time

Docs

const product = theme.productName ?? site.model.module.name;
return (
<header class="topbar" {...persistAttr(variant, "apidocs-topbar")}>
<input type="checkbox" id="apidocs-nav-toggle" class="nav-toggle visually-hidden" aria-label="Toggle navigation" autocomplete="off" />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<header class="topbar" {...persistAttr(variant, "apidocs-topbar")}>
<input type="checkbox" id="apidocs-nav-toggle" class="nav-toggle visually-hidden" aria-label="Toggle navigation" autocomplete="off" />
<script dangerouslySetInnerHTML={{ __html: NAV_STATE_BOOT }} />
<label class="nav-button" for="apidocs-nav-toggle" title="Toggle navigation" aria-hidden="true">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/label-has-associated-control (warning)

Blind users can't identify this field because screen readers find no label text, so add visible text, aria-label, or aria-labelledby.

Fix → Tie every label to a control with htmlFor, or by nesting the input.

Docs

<header class="topbar" {...persistAttr(variant, "apidocs-topbar")}>
<input type="checkbox" id="apidocs-nav-toggle" class="nav-toggle visually-hidden" aria-label="Toggle navigation" autocomplete="off" />
<script dangerouslySetInnerHTML={{ __html: NAV_STATE_BOOT }} />
<label class="nav-button" for="apidocs-nav-toggle" title="Toggle navigation" aria-hidden="true">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<label class="nav-button" for="apidocs-nav-toggle" title="Toggle navigation" aria-hidden="true">
<svg viewBox="0 0 16 16" width="16" height="16"><rect x="2" y="2.75" width="12" height="10.5" rx="2.25" /><path d="M6.25 2.75v10.5" /></svg>
</label>
<a class="brand" href={relative(page, INDEX, ".html")}>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

<a class="brand" href={relative(page, INDEX, ".html")}>
{theme.logo?.light && (
<>
<img class="logo logo-light" src={`${root}assets/logo-light.svg`} alt={theme.logo.alt ?? ""} height={22} width={logoWidth(theme.logo.light, 22)} />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React Doctor · react-doctor/no-unknown-property (warning)

React ignores this prop because it doesn't recognize the name.

Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.

Docs

@sgammon
Sam Gammon (sgammon) merged commit 7910dc1 into main Nov 22, 2026
10 of 11 checks passed
@sgammon
Sam Gammon (sgammon) deleted the feat/apidocs branch November 22, 2026 01:05

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 4 potential issues.

9 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

Devin Review

if (!existsSync(model)) throw new Error(`No model at ${model}`);
const theme = flag("theme") ? resolve(cwd, flag("theme")!) : join(work, "theme.json");
if (!flag("theme")) writeFileSync(theme, JSON.stringify({ extends: preset }));
rmSync(out, { recursive: true, force: true });

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Sample build deletes unrelated files

Running the sample build with an existing --out directory deletes its entire contents, not just previously generated docs. That includes any input model or theme stored there, which the runner opens only after deletion.

Learn more

The sample command resolves --out to the caller's chosen directory and gives the runner the model and theme by path. It removes the directory before the runner opens either file. It does not check whether the directory belongs to a previous sample build.

Example: Run the sample command with --out docs --model docs/api.json. The command deletes docs/api.json and everything else in docs, then the runner fails to open the model.

Recommended fix: Only clean the managed default sample directory automatically. For explicit output directories, require an empty directory or overwrite only files tracked as generated output; check for input/output collisions before writing.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

* percent escapes stay as they are, so anchors such as %3Cinit%3E keep working.
*/
export function markdownDestination(url: string): string {
return url.replace(/[&<>\\`"'() \u0000-\u001f\u007f]|[^\u0000-\u007f]/g, c => encodeURIComponent(c).replace(/[!'()*]/g, x => `%${x.charCodeAt(0).toString(16).toUpperCase()}`));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Unicode links abort documentation builds

When a link destination contains an emoji, markdownDestination passes each surrogate half separately to encodeURIComponent, which throws. render builds HTML and Markdown together, so the entire static build fails.

Suggested change
return url.replace(/[&<>\\`"'() \u0000-\u001f\u007f]|[^\u0000-\u007f]/g, c => encodeURIComponent(c).replace(/[!'()*]/g, x => `%${x.charCodeAt(0).toString(16).toUpperCase()}`));
return url.replace(/[&<>\\`"'() \u0000-\u001f\u007f]|[^\u0000-\u007f]/gu, c => encodeURIComponent(c).replace(/[!'()*]/g, x => `%${x.charCodeAt(0).toString(16).toUpperCase()}`));

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Comment on lines +27 to +29
`<${base}${page}.md>; rel="alternate"; type="text/markdown"`,
`<${base}llms.txt>; rel="alternate"; type="text/markdown"; title="llms.txt"`,
`<${base}api.json>; rel="alternate"; type="application/json"; title="api.json"`,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Astro pages fail for Unicode identifiers

Opening a type named 形 makes linkHeader put the raw identifier in an HTTP header. The Astro route sets that header for both formats, and the header API rejects it.

Learn more

The Astro route resolves the URL to a decoded model page path. It then constructs a Link header for both the HTML and Markdown response using that path. Fetch header values must fit in a ByteString, so a raw path containing a character above U+00FF throws before the response is sent.

Example: Opening the reference page for Java class p.形 resolves the percent-encoded request URL correctly. The response then fails while setting the Link header for p/形.md.

Recommended fix: Percent-encode the individual path segments used in linkHeader, preserving the directory separators. Test both HTML and Markdown negotiation for an encoded request to a non-Latin type name.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Comment on lines +31 to +35
const pages = new Set([...llms.matchAll(/\]\(([^)#]+)\.md\)/g)].map(m => m[1]!).filter(p => !/^[a-z]+:/i.test(p)));
pages.add("index");
const write = (path: string, body: string) => {
mkdirSync(dirname(join(dir, path)), { recursive: true });
writeFileSync(join(dir, path), body);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟥 Remote audits write outside report directories

When an operator audits a remote site, mirrorSite uses that site’s Markdown link paths as local filenames. A site operator can direct writes outside the report directory and overwrite files accessible to the auditor.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

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