@honeydeck/honeydeck 0.4.0 → 0.6.0

package/docs/slidev-migration.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(advanced)/slidev-migration.mdx. Do not edit by hand. -->
+
 # Slidev migration
 
 Coming from [Slidev](https://sli.dev)? Honeydeck ships an optional `slidev-migration` agent skill that can help an AI coding agent initialize a Honeydeck project and migrate a Slidev deck.
@@ -36,7 +38,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,19 @@
+<!-- Generated from packages/docs/content/docs/(core)/steps-and-reveals.mdx. Do not edit by hand. -->
+
 # 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 +34,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 +113,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 +153,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 +232,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/docs/timeline-steps.md

@@ -0,0 +1,50 @@
+<!-- Generated from packages/docs/content/docs/(components)/timeline-steps.mdx. Do not edit by hand. -->
+
+# TimelineSteps
+
+Use `<TimelineSteps>` when an imported React component should control part of a slide timeline.
+
+```mdx
+import { Reveal, TimelineSteps } from '@honeydeck/honeydeck'
+import { AccordionDemo } from './AccordionDemo'
+
+<Reveal>Before the custom component</Reveal>
+
+<TimelineSteps steps={3}>
+  <AccordionDemo />
+</TimelineSteps>
+
+<Reveal>After the custom component</Reveal>
+```
+
+Inside the custom component, read local step state with `useTimelineSteps()`:
+
+```tsx
+import { useTimelineSteps } from '@honeydeck/honeydeck'
+
+export function AccordionDemo() {
+  const { phase, stepIndex, stepCount, isPdfFinalRender } = useTimelineSteps()
+
+  return <div>Step {stepIndex} of {stepCount}</div>
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `steps` | `number` | Required | Literal positive integer number of reserved timeline steps. |
+| `children` | `ReactNode` | — | Custom component content. |
+
+`useTimelineSteps()` returns `{ phase, stepIndex, stepCount, startAt, endAt, isPdfFinalRender }`.
+
+- `phase` is `"before"`, `"active"`, or `"after"`.
+- `stepIndex` is `0` before start, `1..stepCount` while active, and `stepCount` after end.
+- `isPdfFinalRender` is `true` only for one-page final-state PDF export.
+
+## Rules
+
+- `steps` must be a literal positive integer in slide MDX, for example `steps={3}`.
+- `<TimelineSteps>` must appear at the usage site in slide MDX. Imported TSX components cannot register steps by rendering `<TimelineSteps>` internally.
+- Nested Honeydeck timeline producers inside `<TimelineSteps>` are not supported.
+- In `isPdfFinalRender`, allows custom components to controll how they appear in PDFs.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@honeydeck/honeydeck",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"description": "MDX and React-based presentation framework for AI-friendly slide decks.",
 	"license": "MIT",
 	"publishConfig": {
@@ -35,8 +35,8 @@
 		"!src/**/*.test.tsx",
 		"!src/**/fixtures",
 		"!src/**/fixtures/**",
-		"docs",
 		"skills",
+		"docs",
 		"Readme.md",
 		"SPEC.md",
 		"DEVELOPMENT.md",
@@ -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": {
@@ -93,6 +95,7 @@
 		"dev:init": "node --import tsx ./src/cli/index.ts dev --deck src/cli/templates/starter/deck.mdx",
 		"format": "biome check --write",
 		"lint": "biome check",
+		"prepack": "npm -w @honeydeck/docs run export:package-docs",
 		"pack:dry-run": "npm pack --dry-run",
 		"pack:smoke": "node ./scripts/packed-smoke.mjs",
 		"release:plan": "node ./scripts/release-plan.mjs",
@@ -103,6 +106,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

@@ -6,17 +6,17 @@
 
 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/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, public docs, specs, 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:
 
 - All skills are discoverable by the `skills` CLI when users run `npx skills add <honeydeck-repo-url> --copy` or explicit `npx skills add <honeydeck-repo-url> --copy --skill honeydeck` / `--skill presentation-writing` / `--skill slidev-migration`.
-- 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 `honeydeck` skill instructs agents to use installed Honeydeck package documentation (`node_modules/@honeydeck/honeydeck/docs/*.md`, `node_modules/@honeydeck/honeydeck/docs/index.json`, `Readme.md`, package `SPEC.md`, linked colocated `SPEC.md` files, and the public docs site) as the source of truth when available.
+- The `honeydeck` skill documents a consumer-focused local docs discovery order: current project's `node_modules/@honeydeck/honeydeck/docs` package docs first, then installed package specs, then package-root checkout docs/specs, then the public docs URL. It must not require monorepo-only `packages/docs` paths for normal installed-package use.
 - 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.
+- `packages/docs/content/docs/(advanced)/skills.mdx` 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

@@ -9,28 +9,28 @@ You help the user work with Honeydeck presentations. Honeydeck decks are MDX fil
 
 ## Source of truth
 
-Before giving Honeydeck-specific syntax or changing a deck, prefer repository/package docs when available.
+Before giving Honeydeck-specific syntax or changing a deck, prefer the installed package docs and package specs when available. This skill is for consumers of the `@honeydeck/honeydeck` package, so do not depend on monorepo-only paths.
 
 Docs discovery order:
 
-1. Current project dependency docs: `node_modules/@honeydeck/honeydeck/Readme.md`, `node_modules/@honeydeck/honeydeck/SPEC.md`, and `node_modules/@honeydeck/honeydeck/docs/*.md`.
-2. Monorepo checkout docs: `packages/honeydeck/Readme.md`, `packages/honeydeck/SPEC.md`, and `packages/honeydeck/docs/*.md`.
-3. Fresh app or package-root docs: `Readme.md`, `SPEC.md`, and `docs/*.md`.
-4. Public docs URL when local docs are unavailable: `/docs` on the Honeydeck marketing site.
+1. Current project dependency docs: `node_modules/@honeydeck/honeydeck/docs/index.json`, `node_modules/@honeydeck/honeydeck/docs/*.md`, `node_modules/@honeydeck/honeydeck/Readme.md`, `node_modules/@honeydeck/honeydeck/SPEC.md`, and linked colocated `SPEC.md` files.
+2. Package-root checkout docs: `docs/index.json`, `docs/*.md`, `Readme.md`, `SPEC.md`, and linked colocated `SPEC.md` files.
+3. Public docs URL when local docs are unavailable: `https://honeydeck.dev/docs`.
 
 Important docs:
 
 - `Readme.md` for the compact package overview and documentation index
+- `docs/index.json` for the installed docs page list and order
 - `docs/getting-started.md` for quick start and first-run orientation
 - `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
+- 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
 
-If the user is inside a generated Honeydeck project and package docs are not nearby, tell them they can use the public docs site for prose docs and run `npx honeydeck dev` to open runtime reference pages for active theme tokens, layouts, and built-in components.
+If local package docs are unavailable, tell the user they can use the public docs site for prose docs and run `npx honeydeck dev` to open runtime reference pages for active theme tokens, layouts, and built-in components.
 
 ## Honeydeck basics to remember
 
@@ -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

@@ -11,15 +11,15 @@ Start by reading all Honeydeck related skills available. Alternatively you can c
 
 ## Source of truth
 
-Before changing files, read the available project/package docs:
+Before changing files, read the available project docs and package specs:
 
-- `Readme.md`, `docs/getting-started.md`, root `SPEC.md`, linked colocated `SPEC.md` files, and `docs/slides.md` for Honeydeck deck structure
-- `docs/configuration.md` for Honeydeck frontmatter
-- `docs/steps-and-reveals.md` for Reveal/RevealGroup/code steps
-- `docs/customization.md` for layouts, themes, components, layout maps, and design tokens
+- `Readme.md`, public docs content under `packages/docs/content/docs` when in the monorepo, root `SPEC.md`, linked colocated `SPEC.md` files, and the Slides guide for Honeydeck deck structure
+- The Configuration guide for Honeydeck frontmatter
+- The Steps and reveals guide for Reveal/RevealGroup/code steps
+- The Customization guide for layouts, themes, components, layout maps, and design tokens
 - Existing Slidev files: `slides.md`, `pages/**/*.md`, `components/**/*.vue`, `layouts/**/*.vue`, `styles/**`, `public/**`, `package.json`, `vite.config.*`, and local theme/addon packages
 
-If Honeydeck docs are not nearby, package docs may be in `node_modules/@honeydeck/honeydeck`, or the user can use the public docs site. A migrated deck's runtime reference pages cover active theme tokens, layouts, and built-in components.
+If Honeydeck docs are not nearby, package specs may be in `node_modules/@honeydeck/honeydeck`, or the user can use the public docs site. A migrated deck's runtime reference pages cover active theme tokens, layouts, and built-in components.
 
 ## Migration goal
 
@@ -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/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