@honeydeck/honeydeck 0.3.0 → 0.5.0

package/docs/skills.md

@@ -31,9 +31,9 @@ npx skills add <honeydeck-repo-url> --copy --skill slidev-migration
 
 | Skill | Use it for |
 | --- | --- |
-| `honeydeck` | Honeydeck-specific guidance for MDX decks, layouts, CSS imports, presenter notes, reveals, code steps, PDF export, and package docs. |
+| `honeydeck` | Honeydeck-specific guidance for MDX decks, layouts, CSS imports, presenter notes, reveals, code steps, Magic Code, PDF export, and package docs. |
 | `presentation-writing` | Framework-agnostic help with audience, storyline, slide headlines, speaker notes, timing, and review heuristics. |
-| `slidev-migration` | Migrating Slidev decks to Honeydeck while preserving source files until you approve cleanup. |
+| `slidev-migration` | Migrating Slidev decks to Honeydeck, including rewriting Slidev `md magic-move` blocks to Honeydeck `md magic-code`, while preserving source files until you approve cleanup. |
 
 The `honeydeck` and `presentation-writing` skills work well together: one keeps the agent inside Honeydeck conventions, while the other improves the story and delivery. Add `slidev-migration` when you are converting an existing Slidev project.
 
@@ -48,7 +48,7 @@ For example, an agent with the `honeydeck` skill should prefer:
 - slide frontmatter for layouts
 - explicit imports from `@honeydeck/honeydeck`
 - `<Notes>` for speaker notes
-- `<Reveal>`, `<RevealGroup>`, and code metadata for steps
+- `<Reveal>`, `<RevealGroup>`, code metadata, and Magic Code for steps
 - `honeydeck pdf` for PDF export
 
 The skills also point agents back to the packaged docs and specs, so generated deck changes can stay aligned with the installed Honeydeck version.

package/docs/slidev-migration.md

@@ -36,7 +36,10 @@ The skill guides an agent through the common Slidev-to-Honeydeck mapping:
 | `components/*.vue` | React `components/*.tsx` |
 | `layouts/*.vue` or Slidev themes | Honeydeck layouts, layout maps, React components, and CSS |
 | `<v-click>` / `<v-clicks>` | `<Reveal>` / `<RevealGroup>` |
+| Slidev Magic Move code blocks (`md magic-move`) | Honeydeck Magic Code blocks (`md magic-code`) |
 | trailing note comments | `<Notes>` |
 | `slidev`, `slidev build`, `slidev export` | `honeydeck dev`, `honeydeck build`, `honeydeck pdf` |
 
+The migration skill rewrites Slidev `md magic-move` code animation blocks to Honeydeck's canonical `md magic-code` syntax. Honeydeck still accepts `md magic-move` as a compatibility alias.
+
 Advanced Slidev features such as Vue directives, `$clicks`, custom theme internals, Monaco/live-code blocks, and complex click positioning may need React-specific follow-up after the first migration pass.

package/docs/steps-and-reveals.md

@@ -1,16 +1,17 @@
 # Steps & Reveals
 
-Honeydeck has a first-class step concept. Each slide has a timeline built from `Reveal`/`RevealGroup` components, custom component step blocks, and code highlight ranges, counted in document order.
+Honeydeck has a first-class step concept. Each slide has a timeline built from `Reveal`/`RevealGroup`/`Fade`/`FadeGroup` components, `RevealWith`/`FadeWith` synchronized content, custom component step blocks, code highlight ranges, and Magic Code states, counted in document order.
 
 ## Timeline Model
 
 - Slides start at **step 0** — no reveals or custom component steps active.
 - Stepped code blocks show their first highlight group immediately whenever the block is visible.
-- Each `Reveal`, `RevealGroup` child, `TimelineSteps` block, or code highlight group after the first adds a step.
+- Magic Code blocks show their first inner code fence and first highlight group immediately whenever the block is visible.
+- Each `Reveal`, `Fade`, `RevealGroup`/`FadeGroup` child, `TimelineSteps` block, code highlight group after the first, or Magic Code state after the first adds a step.
+- `RevealWith` and `FadeWith` add no steps. They watch existing steps by `target` or numeric `at`.
 - All step-producing elements share one slide-local timeline.
-- Nested step-producing elements are flattened into that same timeline. A parent
-  reveal target appears first; nested reveals, reveal groups, and code highlight
-  ranges appear after the parent and before the next sibling target.
+- Nested step-producing elements are flattened into that same timeline for reveal targets. A parent reveal target appears first; nested reveal/fade groups and code highlight ranges appear after the parent and before the next sibling target.
+- Fade targets must not contain nested timeline producers because a faded parent would hide later nested steps. Put fades inside reveals instead.
 
 ## Reveal
 
@@ -31,13 +32,74 @@ import { Reveal } from '@honeydeck/honeydeck'
 ### Behavior
 
 - **Cumulative** — once visible, content stays visible for the rest of the slide.
-- **Layout-stable** — hidden content reserves space (`opacity: 0` / `visibility: hidden`, not `display: none`).
+- **Layout-stable by default** — hidden content reserves space (`opacity: 0` / `visibility: hidden`, not `display: none`).
+- **Ephemeral when requested** — add `ephemeral` to render hidden content as `null`, so it reserves no layout space. Presenter previews still show a muted ghost.
 - **Default effect** — fade-in. Customize with `className` and Tailwind/CSS.
+- Optional `name="..."` gives a reveal a slide-local target for `RevealWith`.
+
+## RevealWith
+
+Use `RevealWith` when content should appear at the same step as another reveal,
+code highlight, group item, Magic Code state, or custom `TimelineSteps` state.
+It never adds a new step.
+
+````mdx
+import { Reveal, RevealWith } from '@honeydeck/honeydeck'
+
+<Reveal name="headline">Headline appears first</Reveal>
+<RevealWith target="headline">Supporting detail appears with it</RevealWith>
+
+```ts {1|2|3}
+const answer = 42
+console.log(answer)
+```
+
+<RevealWith at={2}>This appears with the second slide step</RevealWith>
+````
+
+Rules:
+
+- Use exactly one of `target="name"` or `at={n}`.
+- `target` points to a same-slide `<Reveal name="name">`; forward references work.
+- `at` is a 1-based slide-local step and can target any existing timeline step.
+- `name`, `target`, and `at` must be literal values so Honeydeck can validate them at build time.
+
+## Fade
+
+`Fade` is the inverse of `Reveal`: content starts visible and fades out at its timeline step.
+
+```mdx
+import { Fade } from '@honeydeck/honeydeck'
+
+<Fade>Visible at step 0, gone at step 1</Fade>
+<Fade ephemeral>Gone at step 2 and no longer reserves space</Fade>
+```
+
+Behavior:
+
+- Visible while `stepIndex < at`.
+- Hidden while `stepIndex >= at`.
+- Hidden content reserves layout space by default.
+- With `ephemeral`, hidden content renders `null` and reserves no layout space.
+- Fade content must not contain nested timeline producers. Put `Fade` inside `Reveal`, not `Reveal` inside `Fade`.
+
+## FadeWith
+
+Use `FadeWith` for a fade-out controlled by an explicit target step or named reveal target without adding its own timeline step:
+
+```mdx
+import { FadeWith } from '@honeydeck/honeydeck'
+
+<FadeWith target={3}>Disappears when step 3 is active</FadeWith>
+<FadeWith at={2}>Disappears with slide step 2</FadeWith>
+```
+
+`FadeWith` never increments the slide step count. It uses the same `target`/`at` validation rules as `RevealWith`.
 
 ## RevealGroup
 
 Reveals each direct child as its own step. If a direct child is a list, each
-list item is revealed as its own step:
+top-level list item is revealed as its own step:
 
 ```mdx
 import { RevealGroup } from '@honeydeck/honeydeck'
@@ -49,7 +111,20 @@ import { RevealGroup } from '@honeydeck/honeydeck'
 </RevealGroup>
 ```
 
-To reveal multiple elements together, wrap them in a single `Reveal` instead.
+Set `listRevealMode="nested"` to reveal nested list items depth-first:
+
+```mdx
+<RevealGroup listRevealMode="nested">
+  - Parent
+    - Child A
+    - Child B
+  - Sibling
+</RevealGroup>
+```
+
+Timeline: parent → child A → child B → sibling. The default `"direct"` mode keeps nested items grouped with their parent.
+
+To reveal multiple elements together, wrap them in a single `Reveal` instead. Add `ephemeral` to the group when hidden generated children should not reserve layout space.
 
 Nested reveals and code walkthroughs work inside group items:
 
@@ -76,6 +151,20 @@ Timeline:
 3. Code item appears with line 1 highlighted
 4. Code highlights line 2
 
+## FadeGroup
+
+`FadeGroup` is the inverse of `RevealGroup`: each meaningful direct child starts visible and fades out one by one. Direct lists are preserved, and each list item gets its own fade-out step. Fade group targets must not contain nested timeline producers.
+
+```mdx
+import { FadeGroup } from '@honeydeck/honeydeck'
+
+<FadeGroup ephemeral>
+  - Remove this at step 1
+  - Remove this at step 2
+  - Remove this at step 3
+</FadeGroup>
+```
+
 ## Custom Component Steps
 
 Use `TimelineSteps` when an imported React component should control part of
@@ -141,6 +230,52 @@ console.log(c)
 - **Dim approach:** Non-highlighted lines are dimmed (controlled by `--honeydeck-code-line-dim-opacity: 0.4`).
 - **Shiki at build time:** No runtime JS cost for syntax highlighting.
 
+## Magic Code
+
+Magic Code animates between multiple code states while keeping the same Honeydeck timeline model. It builds on Shiki Magic Code / Shiki Magic Move and uses build-time precompiled highlighting data.
+
+`````mdx
+````md magic-code {duration:500}
+```ts
+const count = 1
+```
+
+```ts
+const count = 2
+```
+````
+`````
+
+- The canonical Honeydeck syntax is `md magic-code`.
+- `md magic-move` is accepted as a Slidev compatibility alias.
+- Use `{duration:500}` to override the animation duration for one block.
+- Set a deck-wide default with `magicCodeDuration: 500` in deck-level frontmatter.
+- Content inside a Magic Code block that is not a fenced code block is ignored.
+- Magic Code looks and copies like a normal Honeydeck code block. Copying always copies the currently visible code text.
+
+Inner code fences keep normal code step metadata:
+
+`````mdx
+````md magic-code
+```ts {1|2}
+const a = 1
+const b = 2
+```
+
+```ts {all}
+const sum = a + b
+```
+````
+`````
+
+Timeline:
+
+1. First code state, line 1 highlighted
+2. First code state, line 2 highlighted
+3. Morph to second code state, all lines highlighted
+
+Magic Code states may use different languages, but animations usually look best when all states use the same language.
+
 ## Mixed Timeline Example
 
 ````mdx

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@honeydeck/honeydeck",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"description": "MDX and React-based presentation framework for AI-friendly slide decks.",
 	"license": "MIT",
 	"publishConfig": {
@@ -80,6 +80,8 @@
 		"./themes/bee.css": "./src/theme/bee.css",
 		"./components": "./src/runtime/components/index.ts",
 		"./components/code-block": "./src/runtime/components/CodeBlock.tsx",
+		"./components/code-block/normal": "./src/runtime/components/NormalCodeBlock.tsx",
+		"./components/code-block/magic": "./src/runtime/components/MagicCodeBlock.tsx",
 		"./remark/shiki-code-blocks": "./src/remark/shiki-code-blocks.ts"
 	},
 	"imports": {
@@ -103,6 +105,7 @@
 		"@clack/prompts": "^1.3.0",
 		"@mdx-js/mdx": "^3.1.1",
 		"@mdx-js/rollup": "^3.1.1",
+		"@shikijs/magic-move": "^4.2.0",
 		"@tailwindcss/vite": "^4.3.0",
 		"lucide-react": "^1.16.0",
 		"pdf-lib": "^1.17.1",

package/skills/SPEC.md

@@ -8,7 +8,7 @@ Honeydeck ships installable agent skills:
 
 - `skills/honeydeck/SKILL.md` (`honeydeck`) helps AI agents use Honeydeck correctly: MDX entrypoint, deck frontmatter, exact `---` slide separators, slide frontmatter, built-in layouts, explicit theme/CSS imports, presenter notes, steps/reveals, code blocks, PDF export, custom React components, customization, canonical package docs, and runtime reference pages.
 - `skills/presentation-writing/SKILL.md` (`presentation-writing`) gives opinionated guidance for writing great slides and delivering good presentations: audience/goal/duration discovery, storyline, one idea per slide, strong headlines, sparse visuals, speaker notes, timing, narrative flow, progressive disclosure, and review heuristics.
-- `skills/slidev-migration/SKILL.md` (`slidev-migration`) helps AI agents migrate presentations from Slidev/sli.dev to Honeydeck: initialize a Honeydeck project when needed, convert `slides.md` to `deck.mdx`, map Slidev frontmatter/layouts/assets/notes/reveals/scripts to Honeydeck equivalents, and flag Vue/theme features that need manual React follow-up.
+- `skills/slidev-migration/SKILL.md` (`slidev-migration`) helps AI agents migrate presentations from Slidev/sli.dev to Honeydeck: initialize a Honeydeck project when needed, convert `slides.md` to `deck.mdx`, map Slidev frontmatter/layouts/assets/notes/reveals/scripts/Magic Move code blocks to Honeydeck equivalents, and flag Vue/theme features that need manual React follow-up.
 
 Expected behavior:
 
@@ -16,7 +16,7 @@ Expected behavior:
 - The `honeydeck` skill instructs agents to use Honeydeck documentation (`Readme.md` for package overview, `docs/getting-started.md` for first-run guidance, package/root `SPEC.md`, linked colocated `SPEC.md` files, `docs/deeper-dive.md`, `docs/slides.md`, `docs/steps-and-reveals.md`, `docs/customization.md`, `docs/configuration.md`, and related docs) as the source of truth when available.
 - The `honeydeck` skill documents a local docs discovery order: current project's `node_modules/@honeydeck/honeydeck`, monorepo checkout `packages/honeydeck`, package-root checkout docs, then the public docs URL.
 - The `presentation-writing` skill is framework-agnostic enough to help with presentation quality, while still working well alongside the Honeydeck skill.
-- The `slidev-migration` skill instructs agents to inspect existing Slidev projects, preserve source files until the user approves cleanup, initialize or merge Honeydeck starter files, migrate common Slidev syntax to Honeydeck MDX/React, and document unsupported or approximated features.
+- The `slidev-migration` skill instructs agents to inspect existing Slidev projects, preserve source files until the user approves cleanup, initialize or merge Honeydeck starter files, migrate common Slidev syntax to Honeydeck MDX/React, rewrite `md magic-move` blocks to Honeydeck's canonical `md magic-code` syntax, and document unsupported or approximated features.
 - `honeydeck init` should offer to open the interactive skills installer for the generated project and make clear that accepting runs `npx skills add`.
 - `honeydeck init` and `honeydeck skill` should delegate bundled skill selection, scope selection, and agent selection to the same `npx skills add <honeydeck-package-source> --copy` flow.
 - `docs/skills.md` should document why and how to install the bundled skills, list the `honeydeck`, `presentation-writing`, and `slidev-migration` skills, and link to the Slidev migration guide for migration-specific details.

package/skills/honeydeck/SKILL.md

@@ -25,7 +25,7 @@ Important docs:
 - `docs/deeper-dive.md` for CLI details, feature overview, architecture, exports, and agent skills
 - root/package `SPEC.md` and linked colocated `SPEC.md` files for expected behavior
 - `docs/slides.md` for deck structure, slide separators, and multi-file decks
-- `docs/steps-and-reveals.md` for step-by-step reveals and code steps
+- `docs/steps-and-reveals.md` for step-by-step reveals, code steps, and Magic Code
 - `docs/customization.md` for themes, layouts, custom React components, layout maps, demos, and design tokens
 - `docs/configuration.md` for frontmatter options
 - `docs/navigation.md`, `docs/mobile.md`, `docs/presenter-mode.md`, and `docs/pdf-export.md` for presenting/exporting
@@ -42,7 +42,7 @@ If the user is inside a generated Honeydeck project and package docs are not nea
 - Frontmatter may provide additional properties for the selected layout. Check layout source or docs for available properties.
 - Built-in layouts include `Blank`, `Cover`, `Default`, `Section`, `TwoCol`, `Image`, `ImageLeft`, and `ImageRight`.
 - Built-in styling is explicit: generated decks import `./styles.css`, and that file imports Honeydeck/Tailwind theme CSS.
-- MDX can mix Markdown, JSX, imported React components, Honeydeck components, and code blocks.
+- MDX can mix Markdown, JSX, imported React components, Honeydeck components, code blocks, and Magic Code blocks.
 - Presenter notes belong in slide frontmatter when useful for narrative, timing, and delivery cues.
 - Use reveals/steps for progressive disclosure, not for every bullet by default.
 - PDF export is available with `npx honeydeck pdf`; use `--steps all` when revealed states matter.

package/skills/slidev-migration/SKILL.md

@@ -99,6 +99,7 @@ import { Reveal, RevealGroup, TimelineSteps, Notes, BrowserFrame } from '@honeyd
 
 - Keep normal fenced code blocks.
 - Convert common Slidev stepped highlights like `{1|2|3}` to Honeydeck-supported code step metadata when possible. If unsure, preserve the fence and leave a TODO comment near the block.
+- Convert Slidev Magic Move code blocks (`md magic-move`) to Honeydeck's canonical Magic Code syntax (`md magic-code`). Preserve inner fenced code blocks and their line-highlight metadata. Honeydeck accepts `md magic-move` as a compatibility alias, but migrated decks should use `md magic-code`.
 - Slidev Monaco/live-code features need manual React components or simplified static code.
 
 ### Vue to React conversion

package/src/SPEC.md

@@ -8,7 +8,7 @@
 
 ```ts
 // Core components
-import { Reveal, RevealGroup, TimelineSteps, ListStyle, Keyboard, BrowserFrame, Notes, ColorModeImage } from '@honeydeck/honeydeck'
+import { Reveal, RevealWith, RevealGroup, Fade, FadeWith, FadeGroup, TimelineSteps, ListStyle, Keyboard, BrowserFrame, Notes, ColorModeImage } from '@honeydeck/honeydeck'
 
 // Types for kit authors
 import type { LayoutProps, LayoutMap, LayoutDemo } from '@honeydeck/honeydeck/types'
@@ -45,7 +45,11 @@ import {
 // Public component barrel
 import {
   Reveal as BarrelReveal,
+  RevealWith as BarrelRevealWith,
   RevealGroup as BarrelRevealGroup,
+  Fade as BarrelFade,
+  FadeWith as BarrelFadeWith,
+  FadeGroup as BarrelFadeGroup,
   TimelineSteps as BarrelTimelineSteps,
   ListStyle as BarrelListStyle,
   Keyboard as BarrelKeyboard,
@@ -55,8 +59,9 @@ import {
 } from '@honeydeck/honeydeck/components'
 import type { ColorMode } from '@honeydeck/honeydeck/components'
 
-// Reserved injected component (generated by Honeydeck remark plugins; not intended for manual slide author use)
-import { HoneydeckCodeBlock } from '@honeydeck/honeydeck/components/code-block'
+// Reserved injected components (generated by Honeydeck remark plugins; not intended for manual slide author use)
+import { HoneydeckCodeBlock } from '@honeydeck/honeydeck/components/code-block/normal'
+import { HoneydeckMagicCodeBlock } from '@honeydeck/honeydeck/components/code-block/magic'
 ```
 
 ### Type Definitions

package/src/cli/SPEC.md

@@ -214,8 +214,9 @@ PDF color mode resolves in this order:
 
 ### Step Handling
 
-- `pdfSteps: final` — each slide appears once, all reveals visible, code at final highlight
-- `pdfSteps: all` — step `0` through final step state are separate PDF pages
+- `pdfSteps: final` — each slide appears once, all reveals visible, code at final highlight, and Magic Code at final code state/final highlight
+- `pdfSteps: all` — step `0` through final step state are separate PDF pages, including Magic Code line-highlight states and morph states
+- Magic Code is captured at the requested state, not mid-transition; PDF export disables Magic Move animation while preserving the selected timeline state
 - Capture order is slide order first; in `pdfSteps: all`, step states ascend within each slide. Parallel capture must not change this final PDF page order.
 - During `pdfSteps: final`, `useTimeline()` and `useTimelineSteps()` expose
   `isPdfFinalRender: true` so custom step-driven components can render an

package/src/cli/pdf.ts

@@ -86,6 +86,10 @@ const __dirname = dirname(__filename);
 const FINAL_STEP_INDEX = 999;
 const MAX_PDF_CAPTURE_CONCURRENCY = 16;
 
+function buildPdfRenderQuery(isPdfFinalRender: boolean): string {
+	return `?honeydeckPdfRender=${isPdfFinalRender ? "final" : "step"}`;
+}
+
 // ---------------------------------------------------------------------------
 // Arg parsing
 // ---------------------------------------------------------------------------
@@ -342,7 +346,7 @@ function startStaticServer(dir: string): Promise<StaticServer> {
  * counts are identical to what the runtime reports.
  */
 async function getStepCounts(entryPath: string): Promise<number[]> {
-	const { slides } = loadDeck(entryPath);
+	const { deckFrontmatter, slides } = loadDeck(entryPath);
 
 	const counts: number[] = [];
 
@@ -353,7 +357,10 @@ async function getStepCounts(entryPath: string): Promise<number[]> {
 					remarkFrontmatter,
 					remarkH1Extract,
 					remarkStepNumbering,
-					remarkShikiCodeBlocks,
+					[
+						remarkShikiCodeBlocks,
+						{ magicCodeDuration: deckFrontmatter.magicCodeDuration },
+					],
 				],
 				jsxImportSource: "react",
 				outputFormat: "program",
@@ -498,7 +505,7 @@ async function captureSlide(
 	getPageError: () => Error | null,
 ): Promise<Buffer> {
 	if (firstLoad) {
-		const pdfRenderQuery = isPdfFinalRender ? "?honeydeckPdfRender=final" : "";
+		const pdfRenderQuery = buildPdfRenderQuery(isPdfFinalRender);
 
 		// Full navigation: boots the SPA and waits for network to settle.
 		await page.goto(`${serverUrl}/${pdfRenderQuery}#/${slide}/${step}`, {
@@ -537,7 +544,7 @@ async function prepareCapturePage(
 	isPdfFinalRender: boolean,
 	getPageError: () => Error | null,
 ): Promise<void> {
-	const pdfRenderQuery = isPdfFinalRender ? "?honeydeckPdfRender=final" : "";
+	const pdfRenderQuery = buildPdfRenderQuery(isPdfFinalRender);
 
 	await page.goto(`${serverUrl}/${pdfRenderQuery}#/1/0`, {
 		waitUntil: "networkidle",

package/src/layouts/SPEC.md

@@ -180,7 +180,7 @@ Building the future of presentations.`,
 }
 ```
 
-`mdx` is required on `LayoutDemo` and is the single source for both the live visual preview and the copyable snippet shown in the layouts docs tab. Honeydeck compiles this MDX with the same slide MDX compiler family, extracts frontmatter/title/steps from it, and renders the resulting slide through the active layout map. Honeydeck statically crawls analyzable active layout maps at build time and discovers colocated `demo` exports from layout modules. Dynamic maps, computed entries, non-static imports, and demos whose `mdx` value is not a static string may be skipped with warnings. If no static MDX demo is discovered, the layout still appears in the reference pages with a "No demo MDX provided" hint.
+`mdx` is required on `LayoutDemo` and is the single source for both the live visual preview and the copyable snippet shown in the layouts docs tab. Honeydeck compiles this MDX with the same slide MDX compiler family, extracts frontmatter/title/steps from it, and renders the resulting slide through the active layout map. Honeydeck statically crawls analyzable active layout maps at build time and discovers colocated `demo` exports from layout modules. Analyzable map entries include direct static imports, named imports from layout barrels, spread static default imports, and static member references into an imported layout map such as `Default: defaultLayouts.Default`. Dynamic maps, computed entries, non-static imports, and demos whose `mdx` value is not a static string may be skipped with warnings. If no static MDX demo is discovered, the layout still appears in the reference pages with a "No demo MDX provided" hint.
 
 ### TwoCol Slot Components
 

package/src/remark/SPEC.md

@@ -1,6 +1,22 @@
 # Honeydeck Remark Transform Specification
 
-> Observable behavior for code highlighting transforms.
+> Observable behavior for timeline annotation and code highlighting transforms.
+
+## Timeline Step Annotation
+
+Honeydeck's remark pipeline assigns slide-local timeline metadata to built-in components before MDX is compiled.
+
+Behavior:
+
+- `<Reveal>` consumes one timeline step in document order and receives an internal `at` prop for runtime visibility. Author-authored `at` on `<Reveal>` is a compile error; use `<RevealWith at={n}>` for same-step synchronization.
+- `<RevealGroup>` consumes one step per meaningful direct child/list item, including nested timeline gaps, and receives internal `at`/target metadata for runtime visibility. Author-authored `at` on `<RevealGroup>` is a compile error; use `<RevealWith at={n}>` for same-step synchronization.
+- `<RevealWith>` consumes no timeline steps. It receives an internal resolved `at` prop based on either a same-slide `<Reveal name="...">` target or a literal numeric `at={n}` target.
+- Named reveal targets are slide-local. Duplicate `<Reveal name="...">` values on the same slide are compile errors; reuse across slides is allowed.
+- `<RevealWith target="...">` supports forward references to named reveals anywhere on the same slide.
+- `<RevealWith>` requires exactly one of `target` or `at`; both and neither are compile errors.
+- `Reveal` `name`, `RevealWith` `target`, and `RevealWith` `at` must be literal values. Empty names/targets, non-positive numeric `at`, and numeric `at` values greater than the slide's final step count are compile errors.
+- `RevealWith at={n}` can target any existing slide timeline step, including code, Magic Code, `RevealGroup`, and `TimelineSteps` steps.
+- Flow/block usages of `<Reveal>` and `<RevealWith>` receive an internal block wrapper marker; text/inline usages receive an internal inline wrapper marker so compiled HTML remains valid.
 
 ## Code Highlighting
 
@@ -34,15 +50,99 @@ Syntax:
 - Each active code group highlights only the specified lines (non-cumulative)
 - Non-highlighted lines are dimmed (`--honeydeck-code-line-dim-opacity`)
 - Dimming is applied by Honeydeck runtime markup/styles independently of Tailwind utility generation
-- Code steps participate in the same slide timeline as `Reveal` components
+- Code steps participate in the same slide timeline as `Reveal`, `Fade`, `RevealGroup`, and `FadeGroup` components
+- `RevealWith` and `FadeWith` never add timeline steps; they only watch existing steps through `target`
+- `RevealWith`, `FadeWith`, `Fade`, and `FadeGroup` targets reject nested timeline producers
 - Unsupported/failed languages render as plain code using Honeydeck CSS tokens
 - Code blocks expose a hover/focus copy control that copies the original fenced code text, not the highlighted HTML
 
+## Magic Code
+
+Honeydeck supports **Magic Code** as built-in Markdown syntax for animated transitions between code states. Magic Code builds on Shiki Magic Code / Shiki Magic Move, but Honeydeck precompiles the highlighted token data at build time.
+
+Canonical syntax:
+
+`````mdx
+````md magic-code {duration:500}
+```ts
+const count = 1
+```
+
+```ts
+const count = 2
+```
+````
+`````
+
+Compatibility alias:
+
+`````mdx
+````md magic-move
+```ts
+const count = 1
+```
+
+```ts
+const count = 2
+```
+````
+`````
+
+Rules:
+
+- Magic Code is triggered only by an outer `md` fence whose first metadata token is `magic-code` or `magic-move`.
+- `magic-code` is Honeydeck's canonical syntax. `magic-move` is a silent compatibility alias for Slidev migration.
+- Documentation and generated examples use `magic-code`.
+- The only supported block option is `{duration:<number>}` in milliseconds.
+- Duration resolution is block option, then deck-level `magicCodeDuration`, then Honeydeck default `800`.
+- Slide-level frontmatter does not configure Magic Code.
+- Unknown outer extras/options are ignored. An explicit invalid `duration` is a compile error.
+- Only inner fenced code blocks produce output. Other Markdown inside the Magic Code block is ignored.
+- Zero inner code fences render nothing and add no timeline steps.
+- One inner code fence renders one code state with normal Honeydeck code highlighting/step behavior.
+- Two or more inner code fences render one animated code block backed by build-time precompiled Shiki Magic Move token data for Honeydeck's built-in light and dark syntax themes.
+- Inner code fences keep normal Honeydeck code fence behavior, including language selection and line-highlight metadata.
+- Inner code fences may use different languages, though animations are expected to look best when states use the same language.
+- Magic Code uses the same visual treatment and copy affordance as normal Honeydeck code blocks.
+- Copying copies the currently visible code text. Highlight-only steps copy the same code text; morph steps copy the active state's code text.
+
+Timeline behavior:
+
+- Each inner code fence contributes its normal line-highlight states.
+- Magic Code advances through the current code state's line-highlight groups before morphing to the next code state.
+- The target state's baseline line highlight is active immediately when the morph state becomes current.
+- `total timeline states = sum(inner fence highlight groups)`.
+- `timeline steps added = total timeline states - 1`.
+
+Example:
+
+`````mdx
+````md magic-code
+```ts {1|2}
+const a = 1
+const b = 2
+```
+
+```ts {all}
+const sum = a + b
+```
+````
+`````
+
+Timeline:
+
+1. First code state, line 1 highlighted
+2. First code state, line 2 highlighted
+3. Morph to second code state, all lines highlighted
+
 ### Visual Style
 
 - Highlighted lines: normal brightness
 - Non-highlighted lines: dimmed (reduced opacity)
 - No background stripe
+- Magic Code uses the same code block surface, syntax colors, typography, light/dark behavior, and copy button as normal code blocks
+- Honeydeck ships the Shiki Magic Move transition CSS through its base theme CSS; deck authors do not import Magic Move CSS manually
+- Magic Code does not render filename/title chrome in v1
 
 ### Theme