fix(docs): the tidying sweep in the code-example subsystem (#139b)

[IgorShevchik]

The remaining seven items from #139, plus everything in its follow-up comment. #393 took the four correctness items; this is the rest.

Two of them turned out to be real bugs rather than tidying, and one reported item turned out not to be a bug at all.

For the mirror maintainer: four files are deleted here — docs/app/composables/cachedParseMarkdown.ts, docs/app/composables/useDocs.ts, docs/server/utils/extractSections.ts, docs/server/utils/normalizeComponentName.ts — along with HOOK_PLACEHOLDER and b24Config from useB24.ts. All six are unreferenced in this tree, checked by grepping the bare identifiers across docs/app and docs/server rather than just import lines, since Nuxt auto-imports mean a symbol can be used without one. If anything downstream layers on those exports, that is the diff to look at. upperName was reported as unused too and is not — it stays.

---

Two bug fixes (not tidying)

The prettier worker could hang the page

app/plugins/prettier.ts parks a [resolve, reject] pair under each message's uid and clears it only when a reply arrives. So a message that produces no reply is not a failed format — it is a promise that never settles, and CodeExample.vue awaits it forever. The worker had no error handling anywhere: a throw in prettier.format (an ordinary thing while a snippet is being edited) or a blocked CDN wedged the component.

Worth noting where the fix came from: upstream nuxt/ui, which this file was forked from, has already fixed this, and its shape is better than what I wrote first. I had built a message queue with manual draining on load failure; upstream has no queue at all — loading is lazy inside the format path, and one try/catch around the whole handler covers both a load failure and a format failure. Adopted rather than reinvented, and pinned to the upstream commit compared against (b751eae, 2026-08-25) so the claim stays checkable.

CodeExample.vue already falls back to unformatted code on a rejection, so the visible effect is: hangs forever → renders unformatted.

The dedent assumed two-space indentation

.slice(2) per line is right only while every example is written with exactly two spaces. A four-space example would have stayed indented; a tab-indented one would have had characters eaten. It is now measured from the region's non-blank lines (blank lines skipped — an empty line has no indentation and would drag the minimum to zero).

Output is byte-identical on all 11 shipped examples, checked by running the old and new implementations side by side.

Also fixed: the two prettier versions had drifted

The worker hard-coded 3.7.4 from the CDN; the server prerenders with the installed ^3.9.6. The same snippet could come out formatted one way before hydration and another way after.

The version is now substituted at build time from the resolved package, so pnpm up moves both sides together. Verified on a clean rebuild (.output and the vite cache removed first): the emitted bundle asks for prettier@3.9.6 and no __PRETTIER_VERSION__ placeholder survives anywhere in the output. Upstream still carries this drift — 3.8.2 against ^3.9.6 — so this part is a deliberate divergence, recorded in #400.

One reported item was wrong

upperName is not unused — chat/Chat.vue calls it four times. Left alone.

The tidying

• The 'tip' branch in processLinks was dead: callouts are rewritten to blockquotes earlier in the same pass, so it could never match.
• processLinks was typed with the global DOM Node, but it walks MDC [tag, attrs, ...children] tuples. It type-checked only because every access is an index inside an Array.isArray branch.
• The class on category nav entries tested 'restApiVersion' in category, but no entry in the categories map has that field — always false, always undefined, while reading as though category-level version badges were supported. Removed, with the reasoning left in place; the real per-page filtering in filterChildrenByRestapiVersion is untouched.
• await useCodeExample() added a Suspense barrier for a synchronous function.
• b24Config was an empty untyped {} passed to two functions whose parameter is optional — dropped rather than typed, since an empty object configures nothing and the untyped literal was the actual risk.
• _configResolved: any is now a structural type for the single field read. Not Vite's own ResolvedConfig: Vite is not a direct dependency here — it arrives through Nuxt — so that import does not resolve.
• The wildcard Access-Control-Allow-Origin came off code-examples.get.ts; every caller is same-origin (the fetchCodeExample composable and the server-side MCP b24-jssdk-get-example tool). Upstream keeps it, which is why the reason for diverging is written down next to the handler.
• prepareHref's reported empty-path case is not currently reachable — every branch requires a /docs/ segment first — but the guard is what lets the non-null assertions go away, so it is in. Said plainly rather than claimed as a fix.
• .github/contributing/documentation.md told contributors that body lines are "dedented by exactly two spaces, so keep the wrapper at one level of indentation" — the behaviour this PR removes. Updated, so the guide stops describing a limitation that no longer exists.

Tests

The message routing moved out of app/plugins/prettier.ts, which cannot be imported outside Vite because of its ?worker&inline specifier, into app/utils/prettierWorkerApi.ts — the same split codeTransform.ts got in #393. Six tests pin what the page does with each reply shape, including the one that never used to arrive.

Five more cover the dedent: four-space, tab, minimum-taken-from-every-line, the blank-line case, and one pinning a known quirk (the trailing .trim() eats the first line's remaining indent when that line is deeper than the minimum — no example opens on a nested line, so nothing shipped is affected).

Both specs state what they do not cover rather than leaving a green run to be over-read: the worker tests cannot prove the worker sends { uid, error } on every failure path (that half needs a browser), and cannot see whether a settled entry is removed from handlers, since a promise cannot settle twice — deleting that line leaves the file green, confirmed by mutation.

Checks

• pnpm run typecheck — all eight passes, 0 errors
• jsSdk:unit + jsSdk:types + skills:unit — 661 tests, no type errors
• pnpm run docs:build from a cleaned .output — used to verify the version substitution reaches the bundle
• lint (1 pre-existing unrelated warning in docs/server/api/ai.post.ts, untouched), docs-lint --strict, lint:md, md-internal-links

Follow-ups filed

• docs site: the prettier worker executes third-party CDN code with no SRI and no CSP #399 — the worker executes six third-party modules from a CDN with no SRI, and the site sets no CSP. Pre-existing and inherited from the fork; separated out by the security review rather than smuggled in here.
• Record where the docs app deliberately diverges from upstream nuxt/ui #400 — record the fork's deliberate divergences from upstream nuxt/ui somewhere more durable than three separate file comments.

Closes #139

🤖 Generated with Claude Code

https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr