feat: add ai explain buttons to code block

[colbywhite]

Summary

This PR adds AI-powered code explanation functionality to the documentation site. Users can now click an "Explain Code"
button on code blocks with 10+ lines to get AI-generated explanations in a side panel.

Screenshots

Note: These screenshots may not be up-to-date. See the preview env for more.

TODOs

• Tweak button styling so the button expects a title in the code block based on Update default-titles.js #29581

Feature Implementation

Core Components

1. Expressive Code Plugin (src/plugins/expressive-code/explain-code.js)

   • Automatically adds "Explain Code" buttons to code blocks with 10+ lines
   • Injects button HTML with sparkle icon and tooltip into pre elements
   • Adds has-explain-button class for CSS styling coordination

2. Sheet Web Component (src/components/sheet/)

   • New reusable <cfdocs-sheet> component for slide-in side panels
   • Slides in from right with smooth animations
   • Handles backdrop clicks, close button, and cleanup
   • Follows new cfdocs- prefix convention for web components
   • Includes comprehensive tests (sheet.node.test.ts)

3. Explain Code Sheet (src/components/explain-code-sheet/)

   • <cfdocs-explain-code> component orchestrates the explanation flow
   • Shows loading skeleton while fetching
   • Displays error state on failure
   • Renders explanation with disclaimer about experimental nature
   • Fetches from /explain/{path}?codeBlock={position} API endpoint
   • Overridable via PUBLIC_EXPLAIN_CODE_API_URL environment variable (intended for local development only)
   • Includes comprehensive tests (explain-code-sheet.node.test.ts)

4. Client Script (src/scripts/explain-code.ts)

   • Attaches click handlers to all [data-explain-code] buttons
   • Calculates code block position on page for API request
   • Creates and mounts sheet component on demand
   • Handles Astro page transitions (cleanup/reinit)
   • Security: Code block content is NOT sent to the API to prevent prompt injection attacks. The server retrieves the code block content directly from the documentation source using the provided path and position.

Styling

• Code Block Styles (src/styles/code.css)
  • Button positioning and appearance (dark/light mode)
  • Tooltip on hover showing "Explain Code"
  • Adjusts copy button position when explain button present
• Backdrop Styles (src/styles/backdrop.css)
  • Semi-transparent black backdrop for dialog elements

Integration

• Plugin registered in ec.config.mjs
• Script loaded in src/components/overrides/Head.astro
• Works with Astro's view transitions

Documentation & Tooling Updates

AGENTS.md Documentation

Added new Web Components section documenting:

• Naming convention: cfdocs- prefix for new components
• Class naming: PascalCase with Element suffix
• File organization: src/components/{component-name}/ directories
• Exemption for existing components without prefix

Testing Infrastructure

This PR introduces a new testing pattern for vanilla web components, which we haven't extensively tested in this project before:

• Added @testing-library/dom and happy-dom dependencies for DOM testing in Node.js
• Created Node.js test environment for web components using vitest.workspace.ts
• Tests validate DOM behavior, custom element lifecycle, accessibility attributes, and error handling
• Establishes a pattern for testing future vanilla web components (non-Astro, non-framework components)
• Examples in sheet.node.test.ts and explain-code-sheet.node.test.ts demonstrate testing custom elements, shadow DOM, event handling, and async behavior

Other Changes

• Updated .gitignore to ignore all .env* files (was only .env)

Separate: GitHub Actions Updates

The Node.js version pinning changes in GitHub Actions workflows are unrelated to this feature and were part of separate
maintenance work:

• Pinned Node.js version to 24.14.0 across all workflows
• Changed from 24.x or node-version-file to explicit version
• Affects: ci.yml, bonk.yml, bigbonk.yml, anchor-link-audit.yml, publish-production.yml

API Expectations

The feature expects an API endpoint at:

{API_BASE_URL}/explain/{page-path}?codeBlock={position}

Request details:

• Path: The documentation page path (e.g., workers/examples/return-json)
• Query parameter: codeBlock - 1-indexed position of the code block on the page
• Security: Code block content is NOT included in the request. The server must retrieve the code block from the documentation source based on the path and position, then verify it exists before generating an explanation. This prevents prompt injection attacks.

Response requirements:

• Content-Type: text/html
• Header: cf-docs-finish-reason: stop (indicates successful completion)
• Body: HTML-formatted explanation

Default API base URL: https://docs-ai-production.cloudflare-docs.workers.dev

Infrastructure: The API endpoint leverages Cloudflare's AI Gateway for caching, rate limiting, and request management to ensure reliable and cost-effective AI-powered explanations.

User Experience

1. User views a page with code blocks ≥10 lines
2. Sparkle icon button appears in top-right of code block (next to copy button)
3. On hover, "Explain Code" tooltip displays
4. On click:
   • Side panel slides in from right
   • Loading skeleton displays
   • API request sent with page path and code block position
   • Explanation rendered with disclaimer about experimental nature
5. User can close via backdrop click, close button, or ESC key
6. Panel auto-removes from DOM on close

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/.github/	@cloudflare/content-engineering, @kodster28, @mvvmm, @colbywhite, @ahaywood, @MohamedH1998
*	@cloudflare/pcx-technical-writing
package.json	@cloudflare/content-engineering
*.ts	@cloudflare/content-engineering, @kodster28
*.astro	@cloudflare/content-engineering, @kodster28
*.js	@cloudflare/content-engineering, @kodster28

[github-actions]

Preview URL: https://9102463b.preview.developers.cloudflare.com
Preview Branch URL: https://ai-code-block.preview.developers.cloudflare.com