interactive-chapter - SKILL.md Agent Skill

name: interactive-chapter description: Plan and implement interactive chapter or playground pages for this Docusaurus repo. Use when Codex needs to port AI-generated JSX into JoyRL Book, add a standalone interactive route under `src/pages/`, wire a chapter into interactive mode, or extend the current left-reading/right-playground interaction pattern.

Interactive Chapter

Overview

Build interactive chapters in joyrl-book using the repo's current integration pattern instead of re-inventing chapter routing, TOC entry points, or page layout each time.

Favor the existing chapter workflow first:

docs chapter stays under docs/...
interactive UI lives under src/components/interactive/<slug>/
route page lives under src/pages/.../playground.jsx
chapter-to-interactive mapping lives in src/components/interactive/interactiveRoutes.ts

Current Repo Pattern

These pieces already exist in this repo and should be reused unless the user explicitly asks to replace them:

src/components/interactive/interactiveRoutes.ts Maps docs to interactive routes, exposes reading-mode helpers, and stores RL chapter order for chapter switching.
src/theme/DocItem/index.tsx Redirects supported docs into interactive mode on the client unless ?view=read is present.
src/theme/DocItem/TOC/Desktop/index.tsx Injects the desktop right-rail 交互模式 button above the TOC.

Treat those as real infrastructure, not hypothetical future work.

Default UX To Preserve

For full interactive chapters, prefer this desktop pattern unless the user asks for a different design:

top toolbar for 阅读模式, chapter switcher, previous chapter, next chapter
left column for reading-mode-style explanation and controls
right column for interactive panels only
page-level previous/next navigation inside the left column
avoid duplicating explanatory copy on both left and right

For control-heavy pages such as a console page:

keep the explanation on the left
keep formulas, charts, or playground panels on the right
use a two-column control grid on desktop when the controls are numerous

Workflow

1. Confirm the scope

Prefer a normal docs edit for a small inline visualization.
Prefer the existing interactive-chapter pattern for full-screen, stateful, multi-step teaching UIs.
Reuse the current repo pattern before inventing a new shared framework.

2. Normalize incoming React or JSX

Treat AI-generated JSX as source material, not drop-in code.
Rewrite styling into CSS modules or existing repo CSS patterns.
Do not assume Tailwind, tw- classes, PlaygroundHeader, or source-repo globals exist.

3. Place files deliberately

Put reusable chapter UI in src/components/interactive/<slug>/
Put the user-facing route in src/pages/<doc path>/playground.jsx
Keep names aligned between doc slug, component folder, and route

Typical page wrapper:

import React from 'react';
import Layout from '@theme/Layout';
import Demo from '@site/src/components/interactive/<slug>/Demo';

export default function DemoPage() {
  return (
    <Layout title="Interactive Demo" description="Interactive chapter demo">
      <Demo />
    </Layout>
  );
}

4. Register the chapter

When a docs page should support interactive mode:

Add an entry to INTERACTIVE_DOC_MAP in src/components/interactive/interactiveRoutes.ts
Reuse getReadingModeHref(...) for the reading-mode link
If the chapter participates in the RL chapter switcher, keep RL_BASIC_CHAPTERS accurate

Do not add a redundant inline Markdown link by default when the chapter already has:

TOC 交互模式 button
default redirect into interactive mode

Only add explicit in-doc links when the user wants visible duplication.

5. Preserve the reading/interactive split

When refining an interactive page, prefer these heuristics:

left side owns narrative copy, bullets, and operation hints
right side owns metrics and visual/interactive state
if the same title already appears in the page-level pager, remove extra duplicates
if the same explanation appears on both sides, keep it on the left

6. Validate before finishing

Run npm run typecheck when changing typed config or shared routing helpers
Run npm run build after adding pages, links, or layout integration
Confirm the docs route and interactive route both still build

Current File Landmarks

interactive route registry: src/components/interactive/interactiveRoutes.ts
doc redirect: src/theme/DocItem/index.tsx
desktop TOC button: src/theme/DocItem/TOC/Desktop/index.tsx
current reference implementation: src/components/interactive/dqn/DqnPlayground.jsx

Guardrails

Do not add Tailwind or another styling system silently.
Do not claim automatic TOC button, redirect, or chapter switching unless they are actually wired.
Do not preserve source-repo file paths without checking they exist here.
Do not create a second routing pattern when the current interactiveRoutes.ts setup already solves the task.