docs: an API index of every export, and contributor docs that match the repository by dgesteves · Pull Request #222 · dgesteves/signoff-ui

dgesteves · 2026-10-28T09:11:33Z

Roadmap item SU2-54. Part of #186.

What was wrong

39 of the package's 104 unique runtime exports were named nowhere in the docs (a TypeScript listing of dist/*.d.ts on main, against content/docs, content/components and lib/components.ts). Some are API the changelog announced: evaluateRules, matchesGlob, ruleFromDecision, ruleMatches, toToolApprovalResponse, isSubagentPart, createAgUiRun, fromAgUiUsage. The site's API tables read only index.d.ts and ag-ui.d.ts.
CONTRIBUTING's checks list ("CI runs all of these") left out pnpm perf, pnpm test:site, pnpm registry:build, pnpm smoke:assistant-ui and the CopilotKit build and smoke, which ci.yml runs on every pull request. It didn't say how to run the WebKit and Firefox checks either. It pointed at scripts/kit-scope.mjs, which is really packages/signoff-ui/scripts/kit-scope.mjs, and it didn't point newcomers to the good first issues or to Discussions.
CONTRIBUTING (Changesets) and RELEASING (step 1) said the version step moves only examples/coding-agent. scripts/example-versions.mjs moves every example that asks for a published range: assistant-ui, coding-agent, copilotkit and nextjs-minimal.
ROADMAP listed feat(core): riskFromMcpAnnotations; docs: an organization's policy before a person's rules #172 and fix(ag-ui, acp): make ai an optional peer; the two entries declare the AI SDK types they return #173 (released in 0.10.1) and fix(approval-card, diff-review): accessibility and touch: Approve all's focus, what a card runs, code left to right, 16px fields #174 (released in 0.11.0) as in review or in the next release, and fix(examples): each message starts nextjs-minimal's run again; pin signoff-ui to ^0.10.0 #171, docs: define support tiers and hold new integrations until four weeks after launch #175 and ci: run pnpm audit on every pull request and daily #211 there too, though all three have merged. Its Good first issues still listed Sources: lay out cards by the container's width, not the screen's #191 (fixed by fix(sources): use container queries instead of viewport breakpoints #209, released in 0.10.2) and Tests for Reasoning: following the stream, the toggle, the time #193 (closed by test: cover reasoning stream and duration #207), and nothing listed 0.10.2.

What changed

API index, /docs/api. It lists every export of each entry point in package.json's exports, read from the built .d.ts files when the site builds (lib/api.ts, getApiIndex). The page is an ordinary guide. content/docs/api.md has the prose for each entry point and one  line under it. readGuide replaces that line with the entry point's exports, so the page, /docs/api.md ("Copy page"), the docs search, Ask, the MCP server and llms-full.txt all get the exports with no new route. If an entry point has no line, if the page has no line at all, or if a line names an entry point that doesn't exist, the site build fails. The page is in the sidebar under Resources, so it is linked from every docs page, the component pages included.
- An export that a component page documents (76 of the 222: the components, the hooks and the types their tables cover) gets no section here. Each entry point has one line of links to them instead: "On the component pages: ApprovalCard, …". A section of their own only repeated the declaration's first line, and it took places in Ask's and the MCP server's results that the component page's own sections should get (see "Ask and the MCP server" below).
- Every other export (146) has a heading, its declaration, its doc comment, and up to 4 pages that use it in code. A declaration of one line (82) is inline code. One of several lines (64), or one with a backtick in it, is a code block. A declaration is printed from the .d.ts without its comments, and a destructured parameter reads props, as an editor's hover shows it. Any declaration over 30 lines shows only its first line.
- An export that several entry points share is listed once: under signoff-ui/core when it is there, otherwise under the first entry point that has it. The other entry points link to it ("It also exports everything in signoff-ui/core", or a list of names for signoff-ui/acp and signoff-ui/custom-markdown). Those links go to the component page when one documents the export.
- /docs/api.md and llms-full.txt write the page's links to its own headings as absolute URLs, as they already did for links to other pages.
- getApiIndex throws, saying what to do, on a default export or one renamed on the way out (export { a as b }), which the page would print under the wrong name. The package has neither today.
- lib/api.ts now loads every entry point. The component pages still look an export up by name in the first entry point that has it, so AgentMessage is still the main entry's.
CONTRIBUTING.md. A "Where to start" section: good first issues, the roadmap's list, Discussions, ARCHITECTURE.md. The commands CI runs that the checks list was missing. A paragraph on running the browser checks in WebKit and Firefox (pnpm exec playwright-core install webkit firefox, then BROWSER=webkit or BROWSER=firefox). The kit-scope path. Step 2 of "Adding a component" now asks for a doc comment on each export, since the component page or the index shows it. The version step: "every example but the playground". The Checks list and the audit paragraph from ci: run pnpm audit on every pull request and daily #211 are unchanged apart from the added lines.
RELEASING.md, step 1: the same wording about the version step.
ARCHITECTURE.md (new): the package's layers (pure helpers, components and hooks, styles), a table of its entry points, the build and its checks, the registry, the site (and how the API index is made), the examples, and where the tests and browser checks are. A module with hooks, state or event handlers starts with 'use client'; the icons (src/lib/icons.tsx) only render markup and have none.
ROADMAP.md. A Released section lists fix(approval-card, diff-review): accessibility and touch: Approve all's focus, what a card runs, code left to right, 16px fields #174 under 0.11.0, fix(sources): use container queries instead of viewport breakpoints #209 under 0.10.2, and feat(core): riskFromMcpAnnotations; docs: an organization's policy before a person's rules #172 and fix(ag-ui, acp): make ai an optional peer; the two entries declare the AI SDK types they return #173 under 0.10.1. Below them are docs: define support tiers and hold new integrations until four weeks after launch #175, fix(examples): each message starts nextjs-minimal's run again; pin signoff-ui to ^0.10.0 #171, ci: run pnpm audit on every pull request and daily #211, ci: submit the lockfile's packages to the dependency graph #219, test: cover reasoning stream and duration #207 and docs(acp): connect with the SDK's app API, and test on @agentclientprotocol/sdk 2 #223, which merged and needed no release of the package. docs: define support tiers and hold new integrations until four weeks after launch #175's line now names the date: Thursday 2026-11-19. Good first issues no longer lists Sources: lay out cards by the container's width, not the screen's #191 and Tests for Reasoning: following the stream, the toggle, the time #193; the three open issues labelled good first issue (Docs tables: join the tab order only while they scroll #192, Drop tailwind-merge, or teach it the kit's classes #47, Document ESM-only for Jest users #48) are on it. "In review" now says nothing from the roadmap is in review, and "Merged, in the next release" is gone.

No changeset: this changes docs, the site and tests only.

Page weight

The built page is 761,986 bytes of HTML (71,710 gzipped), down from 1,400,548 (97,482) before this round. The next largest are labels.html at 712,782 (41,546 gzipped) and getting-started.html at 613,089 (64,120). /docs/api.md is 59,280 bytes and /llms-full.txt 424,939.

In Chrome through Playwright, at 1280 by 800 with the GPU off and the CPU slowed down by CDP (Emulation.setCPUThrottlingRate), the median of 3 loads each. Total blocking time is the long tasks after first contentful paint, until 5 seconds pass without one. The theme tap is the Event Timing duration of a click on Dark in the header. The machine was shared, so I ran it twice; both runs are below (load average 6 to 16, then 8 to 22).

	Elements	TBT, 4x	TBT, 10x	Theme tap, 4x	Theme tap, 10x
`/docs/api`	5,026	45 ms, 35 ms	193 ms, 292 ms	152 ms, 144 ms	304 ms, 440 ms
`/docs/labels`	4,494	31 ms, 38 ms	275 ms, 338 ms	80 ms, 104 ms	136 ms, 168 ms

Loading the page now blocks no longer than the labels page. A theme tap still takes about twice as long. A trace of the tap at 4x shows why: the style recalculation after it covers 6,758 nodes on /docs/api (49 ms) and 682 on /docs/labels (15 ms), where 3,879 of the page's 4,035 code tokens sit in a folded block. Then 643 links on the API page restyle on each frame of their colour transition, against 107. Laying the page out in fewer nodes would take a change to the site's CSS (content-visibility: auto on each entry point's section) or one page per entry point, so I left it out of this PR (see the follow-ups).

Ask and the MCP server

The site's Ask index is 24 pages and 627 sections (main: 23 pages, 468; this branch before this round: 697). The API index is 159 of them, 51,628 characters (before: 229, 60,733).

With ondocs' own retrieval (retrieve, keyword-only, the top 6, as /api/ask and /api/mcp search), over an index built as scripts/ask-index.ts builds it:

Question	main	before this round	now
What props does ApprovalCard take?	6 sections of the ApprovalCard and useApprovalPolicy pages, 3,725 characters, with the ApprovalCard props table	3 of the 6 from the index, 2,965 characters, without the props table	the same 6 sections as main, 3,725 characters (the last two swap places)
How do I use evaluateRules on the server?	1 section, `ApprovalRuleLimits`, 728 characters	`evaluateRules`, `ruleMatches` and that section, 2,433 characters	the same 3, 2,417 characters
What options does useApprovalPolicy take?	6 sections of the useApprovalPolicy and ACP pages, 4,580 characters	the index's `UseApprovalPolicyOptions` and `useApprovalPolicy` first, 3,453 characters	the useApprovalPolicy page's API reference first, then `toToolApproval` and `decisionsFromAcpOptions` from the index among its own sections, 4,126 characters

How it was tested

New tests, each written to fail first:

packages/signoff-ui/test/contributor-docs.test.ts (9 tests; all 9 failed against main's docs):
- every one-line command of ci.yml's pull-request jobs is in CONTRIBUTING's Checks section;
- the BROWSER values CI uses (webkit, firefox) and the install command are there;
- every path CONTRIBUTING.md and ARCHITECTURE.md name in inline code exists;
- "Where to start" links the good first issues, the roadmap's list, Discussions and ARCHITECTURE.md;
- ARCHITECTURE names every entry point;
- the playground is the only example with a workspace link, and RELEASING's step 1 and CONTRIBUTING's Changesets say "every example but the playground";
- no PR under ROADMAP's "Merged, in the next release" or "In review" is in CHANGELOG.md, and each item under Released is in that version's changelog entry.
examples/playground/test/api-index.test.ts (11 tests; 4 of them new in this round, which fail against the branch's previous site code):
- the test lists each entry point's exports with TypeScript on its own, not with the page's generator;
- each export is on the page under its entry point, in that section's "On the component pages" line with a link to a component page, or in its "It also exports" line;
- an export a component page documents (ApprovalCard, ApprovalCardProps, useApprovalPolicy) links to its section there and has no heading here, and signoff-ui/custom-markdown's links go to the component page too;
- a one-line declaration is inline code (evaluateRules), a longer one a code block (computeReviewResult), and no code block holds one line without a backtick;
- each listed export has its declaration (function|const|interface|type <name>) and the first line of its doc comment;
- the helpers the finding names (including evaluateRules, memoryRuleStorage, formatCost, createAgUiRun) have headings and declarations;
- heading ids are unique, and every link on the page lands on a heading, a guide section or a component section that exists;
- /docs/api.md has the exports, no <!-- exports: line left, and no relative link (assert.doesNotMatch(served, /\]\((?!https?:)/));
- the build fails when api.md has no line for an entry point, no exports line at all, or a line for an entry point that doesn't exist.

Gate, after merging main (#219, #223) into the branch: pnpm install --frozen-lockfile --prefer-offline, pnpm format:check, pnpm lint, pnpm lint:registry, pnpm build:lib, pnpm size, pnpm typecheck, pnpm test (96 files, 1,584 tests), pnpm test:site (95 tests), pnpm registry:build and pnpm build:playground (Ask's index: 24 pages, 627 sections) all pass. With the built site on next start, pnpm smoke:playground passes in Chrome (75 checks), WebKit (74) and Firefox (75), /llms-full.txt: plain markdown with absolute links included.

I also loaded /docs/api in Chrome:

axe-core with the audit's options found 0 violations, in dark and in light, at 1440 and 390 px wide;
at 390 px wide, the page doesn't scroll sideways, and a long inline declaration wraps;
the docs search index has 152 sections for the page (6 entry points and 146 exports; evaluateRules goes to /docs/api#evaluaterules);
/llms-full.txt has the exports and no ](# link.

Follow-ups (outside this PR's files)

Component pages. They could link each export to its entry in the index. That needs components/docs/component-page.tsx. For now, every page reaches the index through the sidebar.
Internal helpers. Decide which helpers to mark @internal and stop exporting before 1.0, with a changeset. Candidates the finding names: cn, useHydrated, usePrefersReducedMotion, AgentStatusDot, ToolCallDetails, inferLanguage.
Types no entry point exports. The index's declarations name kit types that no entry point exports: ActivityWindow, LineRange, DiffSegment, DiffLineType and DeepPartial; useAgUiAgent's second parameter is UseAgUiAgentOptions, which isn't exported either.
a11y audit. Add /docs/api to the list of docs pages in scripts/a11y-audit.mjs.
The theme tap on /docs/api. If it should cost what it does on other pages, try content-visibility: auto on each entry point's section in app/globals.css, or one page per entry point.
Templates. In .github/ISSUE_TEMPLATE/bug_report.yml, add an integration field for ACP and the other adapters, add styles.layered.css to the install options, and make the ai version optional. Point the roadmap link in feature_request.yml to Roadmap #49. Add a "docs page updated" box to pull_request_template.md.
The rest of the item's evaluation row is in other files:
- the label counts in labels.md (SU2-43 edits that file);
- the English fallbacks in the ACP and AG-UI adapters ("Failed", "Cancelled", "Run failed");
- an optional theme.auto.css line in the Tailwind snippet;
- the ACP install line and the labels-pt.ts code block title;
- a README for examples/playground, and the pnpm-workspace.yaml comment about examples running when copied out;
- a check of the styles.css figure on the limits page.
Changelog. The changelog formatter is tracked separately.

…he repository - /docs/api lists every export of each entry point in package.json, with its declaration and doc comment, read from dist/*.d.ts when the site builds (lib/api.ts, getApiIndex). content/docs/api.md holds the prose and one `` line per entry point, which readGuide fills in, so the page, its .md, the docs search, Ask and llms-full.txt all have the exports. An export several entry points share is listed once, under signoff-ui/core when it is there. An export a component page documents links that page; the others link the pages that use them. In the sidebar under Resources. - CONTRIBUTING.md: a Where to start section. The checks list adds pnpm perf, test:site, registry:build, smoke:assistant-ui and the CopilotKit smoke, which CI runs, and says how to run the browser checks in WebKit and Firefox. The kit-scope path is packages/signoff-ui/scripts. The version step moves every example but the playground, not only examples/coding-agent. - RELEASING.md: the same for the version pull request. - ARCHITECTURE.md: the package's layers and entry points, the build, the registry, the site, the examples and the checks. - ROADMAP.md: #172 and #173 (0.10.1) and #174 (0.11.0) move to a Released section, with #171, #175 and #211, which merged with no release. In review is empty. - test/api-index.test.ts (site) reads each entry point's exports with TypeScript and checks the page lists each, with its declaration and doc comment, and that its links land. test/contributor-docs.test.ts (library) checks CONTRIBUTING's checks against ci.yml, the paths CONTRIBUTING and ARCHITECTURE name, what the version step moves, and the roadmap against the changelog.

…-contributing

… absolute links in the .md - The exports a component page documents (76 of 222) get no section of their own: each entry point has one line of links to them, "On the component pages". Their sections only repeated a first line, and took places in Ask's and the MCP server's results: for "What props does ApprovalCard take?" the ApprovalCard props table had dropped out of the top 6. custom-markdown's "It also exports" links go to the same component sections. - A one-line declaration is inline code; a longer one, or one with a backtick, stays a code block. - toMarkdown makes links to the page's own headings absolute, so /docs/api.md and llms-full.txt have no relative links (smoke:playground). - The regex that finds an export's mentions escapes every metacharacter. - readGuide fails the build for the API index even when it has no exports line at all, and getApiIndex throws on a default or renamed export, which the page would print under the wrong name. - ARCHITECTURE: a module needs 'use client' when it has hooks, state or event handlers; the icons have none. - ROADMAP: #191 and #193 leave Good first issues; 0.10.2 (#209) is under Released; #207, #219 and #223 merged without a release.

dgesteves added 2 commits October 28, 2026 09:08

Merge remote-tracking branch 'origin/main' into docs/su2-54-api-index…

cb2491b

…-contributing

github-advanced-security Bot found potential problems Oct 28, 2026

View reviewed changes

Comment thread examples/playground/lib/docs.ts Fixed

dgesteves added 2 commits October 28, 2026 09:48

Merge remote-tracking branch 'origin/main' into docs/su2-54-api-index…

439274c

…-contributing

dgesteves merged commit d038757 into main Oct 28, 2026
13 checks passed

dgesteves deleted the docs/su2-54-api-index-contributing branch October 28, 2026 10:30

dgesteves mentioned this pull request Oct 30, 2026

docs(roadmap): own diff renderer done, and the releases since 0.11.0 #242

Merged

Navigation Menu

Repository navigation

docs: an API index of every export, and contributor docs that match the repository - #222

docs: an API index of every export, and contributor docs that match the repository#222
dgesteves merged 4 commits into
mainfrom
docs/su2-54-api-index-contributing

dgesteves commented Oct 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

dgesteves commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was wrong

What changed

Page weight

Ask and the MCP server

How it was tested

Follow-ups (outside this PR's files)

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dgesteves commented Oct 28, 2026 •

edited

Loading