Skip to content

fix(docs): align guides with generated api#95

Merged
Exoridus merged 1 commit into
mainfrom
fix/docs-api-consistency
Jun 6, 2026
Merged

fix(docs): align guides with generated api#95
Exoridus merged 1 commit into
mainfrom
fix/docs-api-consistency

Conversation

@Exoridus
Copy link
Copy Markdown
Owner

@Exoridus Exoridus commented Jun 6, 2026

Problem

Guides and committed API docs carried pre-existing naming/link drift that PR #94 made highly visible:

  • Guides taught a MeshShader class the engine no longer exports — the current API is ShaderSource + MeshMaterial.
  • Four prose links pointed at the non-existent /api/mesh-shader/ page.
  • core-concepts/application.mdx linked four options interfaces that get no generated API pages.
  • SourceSnippet.astro had two pre-existing astro check type errors.
  • Running the API generator changed ~12 committed API MDX files (committed output had drifted from source).
  • The spine's curated apiLinks were validated but never shown in the chapter UI.

Solution

  • MeshShader → MeshMaterial migration. Reworked the canonical custom-mesh-shaders chapter onto the real ShaderSource + MeshMaterial + new Mesh({ material }) API (its construction/attach blocks are now standalone-typechecked instead of no-check), and fixed every prose/table/label reference in custom-mesh-shaders, backend-comparison, custom-renderers, filters, and render-pipeline-debugging (the WebGPU debug label now matches the real MeshMaterial (custom)). Prose now distinguishes shader source / material / renderer correctly; detectUniformDrift() is attributed to ShaderSource.
  • API link strategy. Dead /api/mesh-shader/ links now resolve to /api/mesh-material/ (and ShaderSource.detectUniformDrift()/api/shader-source/#methods). The four *ApplicationOptions / LoaderOptions links are demoted to inline code: the generator documents only classes/enums, so interfaces never get pages, and a four-type generator special case is explicitly out of scope (Option C).
  • Astro typecheck cleanup. SourceSnippet.astro derives the language prop from the <Code> component's own lang type (no any, no deep import) and uses Astro.url.pathname for error context instead of the untyped Astro.self.moduleId. astro check is now 0 errors.
  • Deterministic API regeneration. Ran the official generator; the ~12-file diff is real source drift (corrected source-line anchors plus new Gradient value-object members and Graphics fill/stroke styles), is byte-identical across runs, and is committed so a fresh build leaves the tree clean.
  • Visible spine API links. The chapter layout now renders a compact, keyboard-accessible, focus-visible "Related API" chip row from apiLinks (build-validated against the api collection, only when present); curated TryIt blocks stay for playground + API combos.
  • Stronger link validation. New test/site/guide-prose-links.test.ts validates internal /api/ and /guide/ links in MDX prose, NextStep hrefs, and TryIt slugs — with locale / base / trailing-slash / hash / query normalization — and guards against the removed mesh-shader and options-interface pages.

Scope

Docs / site / tooling only. No runtime features, no API changes, no new examples or templates, no playground redesign, no versioning or release.

Validation

All green from a clean tree, and the tree stays clean after API regeneration + build + site build:

  • pnpm typecheck · typecheck:guides (28 extracted / 20 no-check, up from 26 / 22) · typecheck:examples — pass
  • pnpm lint:strict — pass
  • pnpm test — 1846 pass (incl. the new link-drift test)
  • pnpm build · verify:exports · verify:package · verify:create-exo-app (45 pass) — pass
  • pnpm site:build (572 pages) · test:examples:smoke (118 pass) · astro check (0 errors) — pass
  • API regeneration is deterministic; git status --short is clean after generate + build + site:build (only the intended 21 files)
  • ⚠️ pnpm format:check flags 6 files (rollup.config.ts, scripts/extract-guide-snippets.ts, scripts/verify-create-exo-app.ts, test/site/example-search.test.ts, test/site/source-snippets.test.ts, tsconfig.guides.json) — all unmodified by this PR and pre-existing on main (prettier drift). Left untouched to avoid mixing unrelated reformatting into a docs PR; recommend a dedicated formatting/prettier-pin PR.

Release note

Release preparation must be recreated fresh from main after this PR. The stale release-prep PR #93 is superseded by #94 and this PR and can then be closed. This PR intentionally does not touch versioning or the changelog.

@Exoridus Exoridus merged commit 7607ea6 into main Jun 6, 2026
10 checks passed
@Exoridus Exoridus deleted the fix/docs-api-consistency branch June 6, 2026 13:37
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