Add a designed, CI-verified sdk-js cookbook (69 recipes) + agent on-ramp

[lamentierschweinchen]

What this is

A structured, browsable replacement for docs/sdk-and-tools/sdk-js/sdk-js-cookbook-v15.md (the ~128 KB single-file cookbook): 69 atomic, copy-paste recipes across 13 sections, each solving one concrete task and showing every file it needs. It covers sdk-core, sdk-dapp v5, and the sdk-rs contract framework where that is the right tool.

Three things make it more than a reorganization:

1. Every recipe's code is CI-verified. A new TypeScript verification harness extracts the code fences from each page and runs tsc --noEmit --strict over them. The teal Verified badge on a recipe means that check passed on the date shown. What a reader copies is what compiles.
2. It is designed. A small set of React components renders a per-recipe meta strip (difficulty, estimated time, verified badge, SDK versions) and a browsable card index, styled on the MultiversX design tokens.
3. It has an agent on-ramp. A "Agent or agentic engineer? Start here" page routes human developers to recipes and coding agents to the machine-readable surface (llms.txt / llms-full.txt), which now includes every recipe.

Why

The current sdk-js-cookbook-v15.md is a single 128 KB file. This restructures the same intent into a per-recipe, navigable, verifiable cookbook. It is a strict superset: a coverage diff against the existing v15 (and v14 where still relevant) confirmed that every topic it covers is present here, and gaps were filled before this PR. Nothing the current cookbook has is dropped.

The CI harness (mirrors your existing Rust tutorial CI)

The repo already verifies tutorial code for Rust: testing/extract-tutorial-code extracts fenced code from the crowdfunding tutorial and runs cargo test (testing/rust-tutorial-ci.sh, .github/workflows/rust-tutorial-ci.yml). There was no equivalent for JS/TS, so the sdk-js cookbook's code was untested.

This PR adds the TS mirror of that exact pattern:

Existing (Rust)	Added (TypeScript)
testing/extract-tutorial-code/	testing/cookbook-ts/
testing/rust-tutorial-ci.sh	testing/cookbook-ts-ci.sh
.github/workflows/rust-tutorial-ci.yml	.github/workflows/cookbook-ts-ci.yml
cargo run → cargo test	npm run extract → tsc --noEmit --strict

Only titled fences (```ts title="src/foo.ts") are extracted and type-checked; untitled fences and bash/text blocks are illustrative. testing/cookbook-ts/CONVENTION.md documents the authoring rule ("what is shown is what is compiled").

Footprint (deliberately small)

• src/components/cookbook/ — a handful of plain React + CSS-module components (RecipeCard, the meta chips, the verified badge, the index grid).
• src/theme/DocItem/Content/index.js — one guarded swizzle that renders the meta strip only on cookbook pages (frontmatter-gated); all other docs are untouched.
• src/css/cookbook.css — a scoped Infima reskin on the MultiversX tokens; no global chrome is changed.
• scripts/generate-cookbook-manifest.js — build-time index manifest from recipe frontmatter.
• scripts/generate-llms-txt.js — extended (not forked) so recipes appear in llms.txt / llms-full.txt.

Verification

• testing/cookbook-ts-ci.sh (npm ci → extract → tsc --noEmit --strict): green.
• docusaurus build: green; zero broken links originate from or point into the cookbook.
• codespell (your .codespell config): clean.
• markdownlint (your .markdownlint.jsonc): clean except one MD033/no-inline-html on the index page's <CookbookIndex> grid component (intrinsic to rendering the card grid; markdownlint is not a CI gate here and does not scan .mdx by default).

Decisions for the maintainer

1. Replaces sdk-js-cookbook-v15.md. This PR removes the v15 monolith and adds a client redirect from its URL (/sdk-and-tools/sdk-js/sdk-js-cookbook) to the new cookbook index, and repoints the five in-repo links that pointed into it (the three anchored ones now target the specific new recipes). Coverage was diffed first, so nothing the old cookbook covered is lost. The v14 legacy file is untouched. If you would rather keep v15 around for a deprecation window, that is a one-line revert.
2. The TS CI workflow. New for JS/TS docs. It mirrors your Rust one and keeps the cookbook honest, but it is a workflow your team would own. If you would rather not add JS CI, the recipes still stand as designed pages.
3. One superset tsconfig compiles all recipes together (a small strictness relaxation for maintainability); per-recipe configs are the alternative.
4. MD033 on the index (the <CookbookIndex> grid) — kept, since suppressing it via an HTML comment would break MDX parsing.
5. Agent stack references are conservative: the on-ramp links the existing learn/ai-agents page and the served llms.txt, and does not feature emerging/devnet-preview items to avoid overclaiming on a docs surface.

Credit

Recipes were authored and verified against the live network and the installed SDKs (sdk-core 15.4.1, sdk-dapp v5). Verification surfaced a handful of real SDK issues along the way, which are being reported to the sdk-js team separately.

---

Round 3 — reviewer findings addressed

All nine findings from the 2026-07-27 audit are fixed on 8890854d.

F1 (blocker), advisory gate. next pins postcss@8.4.31 as an exact dependency, and so does next@latest, so no Next release resolves the two PostCSS advisories. @multiversx/sdk-dapp and @multiversx/sdk-dapp-ui are already at their latest published versions, so the brace-expansion chain has no upstream bump either. Overrides were therefore the only available mechanism: postcss now resolves to 8.5.25 and brace-expansion to 5.0.8. Both packages disappear from the audit output rather than being suppressed. The allowlist is unchanged at a single sharp entry, and the two remaining high entries are sharp and next, where next.via is exactly ["sharp"]. The overrides are applied to the ten recipe manifests that pull the affected packages, not only to the test harness, so a reader copying any starter gets the patched tree.

F2 (blocker), transaction lifecycle. sign-and-send no longer reports completion before confirmation. done is set only from sdk-dapp's session-specific onSuccess callback; the state moves to tracking when the send promise resolves, and submission stays disabled for the whole signing/tracking window. A synchronous guard rejects a same-tick second submission before React renders disabled=true, and an early-terminal path covers the callback landing before the send promise resolves. The dead sending state is removed. Three runtime lifecycle tests cover success, failure, and a rejected rapid second submission.

F5. audit-project.mjs accepts --directory, and each of the five freshly installed dependency environments is audited before its projects build, so the gate now covers the trees actually built rather than only the committed lock.

F3 browser-only scope corrected and the useGetPendingTransactions arity fixed. F4 static/llms*.txt untracked and ignored, matching the manifest's existing generate-and-ignore policy; a clean build no longer dirties the tree. F6 stray fence removed. F7 expected-output count corrected to four. F8 clientName added across all entrypoint constructions.

Non-cookbook work included in this comparison

The reviewer comparison starts at 11e23b17, while this branch was created from
the merged main snapshot 0fa8ec03. That starting snapshot already contained
three documentation changes unrelated to the cookbook:

• docs/sdk-and-tools/rest-api/gateway-overview.md: adds public Gateway rate
  limits. This round also removes the stray final code fence found during
  review.
• docs/sdk-and-tools/rest-api/multiversx-api.md: expands REST and WebSocket
  rate-limit guidance.
• docs/welcome/terminology.md: rewrites glossary headings, cross-links, and
  source labels across the full terminology page.

They remain in the branch because they were inherited from its merged base, not
introduced by a cookbook commit, and the round-3 decision is to avoid a late
history split. Review ownership for those three files therefore remains
explicitly separate from cookbook ownership.

The branch also changes these files outside the cookbook directory as required
cookbook integration work:

• docs/developers/relayed-transactions.md,
  docs/developers/sc-calls-format.md,
  docs/developers/signing-transactions/signing-programmatically.md,
  docs/sdk-and-tools/overview.md, and
  docs/sdk-and-tools/sdk-js/writing-and-running-sdk-js-snippets.md retarget
  inbound links from the deleted v15 monolith to the relevant recipe or index.
• docusaurus.config.js redirects the former v15 cookbook URL, and
  sidebars.js replaces the monolith entry with the categorized recipe tree.

Those cross-link, redirect, and navigation edits are kept with the cookbook so
the replacement does not ship dead inbound routes.

[lamentierschweinchen]

Reply to Alexandru — review round 3

Post as a PR comment when the branch is pushed.

---

Thanks for the round-3 pass, and for running the whole matrix yourself. Both blockers are fixed, along with F3 through F9. Everything below was re-verified from the repository root on Node 20.19.0.

F1 — advisory gate is green.

next pins postcss@8.4.31 as an exact dependency, and so does next@latest, so no Next release resolves the two PostCSS advisories. @multiversx/sdk-dapp@5.7.1 and @multiversx/sdk-dapp-ui@0.1.24 are already the latest published versions, so the brace-expansion chain has no upstream bump either. Overrides were the only mechanism available.

postcss now resolves to 8.5.25 and brace-expansion to 5.0.8. Both packages have disappeared from the audit output entirely rather than being suppressed. The allowlist is unchanged at a single entry, and the only remaining high findings are sharp and next, where next.via is exactly ["sharp"] — it inherits the one documented exception.

The overrides are applied to the ten recipe manifests that actually pull the affected packages, not only to the test harness. A reader copying any starter gets the patched tree. The other 51 projects are unaffected and were left alone.

F5 — the gate now audits what is built. audit-project.mjs takes a --directory argument, and each of the five freshly installed dependency environments is audited before its projects build. The --ignore-scripts limitation is documented.

F2 — lifecycle and nonce reuse.

'done' is now set only from sdk-dapp's session-specific onSuccess callback. When sendEgld() returns, the state moves to 'tracking', and submission stays disabled for the whole signing/tracking window. A synchronous guard rejects a second submission in the same tick, before React has rendered disabled=true, and an early-terminal path handles the case where the callback fires before the send promise resolves. The dead 'sending' state is gone.

Three runtime tests cover it: sent to pending to confirmed success, sent to pending to confirmed failure, and a rapid second submission rejected until the first session reaches a terminal state.

F3. Re-described as React-independent, browser-side sdk-dapp code, with server and CLI use pointed at sdk-core with its own signer and network provider. The useGetPendingTransactions(sessionId) references are corrected.

F4. Both static/llms*.txt are untracked and ignored, matching the recipe manifest's existing generate-and-ignore policy, and generation is wired into build, start and deploy. A clean build no longer dirties the tree.

F6. Stray fence removed. F7. Corrected to four. F8. clientName added across all 45 entrypoint constructions; no bare new DevnetEntrypoint() remains.

F9. The pull-request description now has a labelled section listing the non-cookbook changes carried by the branch, so ownership is explicit rather than implied.

Verification: advisory gate green, 11/11 extractor tests, 3/3 lifecycle tests, strict TypeScript, 5/5 fresh environments audited, 61/61 projects built across five dependency sets, 8/8 Vite and 2/2 Next production builds, clean Docusaurus build with no new broken links, six offline runtime examples and ten live read-only examples. No transaction was broadcast.

Happy to walk through any of it.