AGENTS.md

1# React Wrapper Notes
2 
3This directory contains the `@revealjs/react` wrapper. Keep the guidance here high level and update it when the public API, source layout, or Reveal/React synchronization model changes.
4 
5## Current Layout
6 
7- Source lives under `react/src/`.
8- Components live in `react/src/components/` and use kebab-case filenames.
9- Shared helpers live in `react/src/utils/`.
10- Public exports are defined in `react/src/index.ts`.
11- Shared types live in `react/src/types.ts`.
12- The Reveal instance context lives in `react/src/reveal-context.ts`.
13- Component tests are colocated with their components as `*.test.tsx`.
14- Test setup remains in `react/src/__tests__/setup.ts`.
15- The demo app lives in `react/demo/src/`.
16 
17## Source Of Truth
18 
19- Implementation:
20  - `react/src/components/deck.tsx`
21  - `react/src/components/slide.tsx`
22  - `react/src/components/stack.tsx`
23  - `react/src/components/fragment.tsx`
24  - `react/src/components/code.tsx`
25  - `react/src/components/markdown.tsx`
26- Shared helpers:
27  - `react/src/utils/slide-attributes.ts`
28  - `react/src/utils/markdown.ts`
29- Behavioral tests:
30  - `react/src/components/deck.test.tsx`
31  - `react/src/components/slide.test.tsx`
32  - `react/src/components/fragment.test.tsx`
33  - `react/src/components/code.test.tsx`
34  - `react/src/components/markdown.test.tsx`
35- Public-facing behavior summary:
36  - `react/README.md`
37 
38## Deck Lifecycle Invariants
39 
40- `Deck` creates one `Reveal` instance on mount and destroys it on unmount.
41- `Deck` must remain safe under React `StrictMode`; do not reintroduce double initialization.
42- Event props are wired with `deck.on()` after initialization and cleaned up with `deck.off()` when callbacks change or the component unmounts.
43 
44## Sync Policy
45 
46- `Reveal.sync()` is expensive. Call it rarely.
47- `Deck` should only call `sync()` when the rendered slide structure changes.
48  - Example: slides added, removed, reordered, or regrouped into or out of vertical stacks.
49- Ordinary React content updates inside an existing slide must not trigger a full deck sync.
50- One deck-level sync is still expected once the deck is ready.
51 
52## Configure Policy
53 
54- `config` is shallow-compared.
55- Recreating a config object with the same shallow values must not call `configure()`.
56- `configure()` should only run after the deck is initialized and ready.
57- `configure()` performs its own Reveal-side sync, so the wrapper must avoid an immediate redundant `sync()` afterward.
58 
59## Component Responsibilities
60 
61- `Deck` owns Reveal lifecycle, config application, event wiring, and structure-level sync.
62- `Slide` owns slide-local attribute mapping and calls `syncSlide()` only when the effective slide `data-*` attributes change after mount.
63- `Markdown` mirrors the core Reveal Markdown plugin behavior in React.
64  - It is responsible for markdown parsing, separator support, notes support, and comment-based `.slide:` and `.element:` attributes.
65  - It should keep markdown-specific DOM post-processing local rather than expanding deck-wide sync behavior.
66- `Code` owns explicit code block rendering and Reveal highlight integration for non-markdown code blocks.
67- `Stack` and `Fragment` should stay lightweight unless there is a strong reason otherwise.
68 
69## Markdown And Highlighting Notes
70 
71- Markdown behavior should stay aligned with the core Reveal Markdown plugin unless the React API intentionally diverges.
72- Markdown slide parsing and comment-based attribute helpers belong in `react/src/utils/markdown.ts`.
73- Markdown code highlighting should recover on rerender and after Reveal becomes available, without requiring a full deck sync.
74 
75## When Changing Behavior
76 
77- If sync, configure, markdown, or highlight behavior changes, update the relevant colocated tests in the same change.
78- If the public React API or documented behavior changes, update `react/README.md`.
79- Prefer focused regression tests over broad snapshots.
80 
81## Validation
82 
83Run these after React wrapper changes:
84 
85- `npm test --prefix react`
86- `npm run build --prefix react`
87