@honeydeck/honeydeck 0.3.0 → 0.5.0

package/DEVELOPMENT.md

@@ -211,7 +211,10 @@ honeydeck
 │   └── bee/               → src/layouts/bee/*
 └── ./components/
     ├── .                  → src/runtime/components/index.ts
-    └── code-block         → src/runtime/components/CodeBlock.tsx
+    ├── code-block         → src/runtime/components/CodeBlock.tsx
+    └── code-block/
+        ├── normal         → src/runtime/components/NormalCodeBlock.tsx
+        └── magic          → src/runtime/components/MagicCodeBlock.tsx
 ```
 
 ---

package/Readme.md

@@ -22,8 +22,8 @@ Decks are plain MDX files separated into slides with `---`; see the first deck e
 - [Deeper dive](docs/deeper-dive.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills
 - [Slides](docs/slides.md) - separators, multiple files, layouts, and assets
 - [Configuration](docs/configuration.md) - deck-level and slide-level frontmatter
-- [Steps and reveals](docs/steps-and-reveals.md) - timeline, reveal groups, code steps, and PDF behavior
-- [Components](docs/components.md) - core Honeydeck components such as `BrowserFrame` and `Keyboard`
+- [Steps and reveals](docs/steps-and-reveals.md) - timeline, reveal groups, code steps, Magic Code, and PDF behavior
+- [Components](docs/components.md) - core Honeydeck components such as `Reveal`, `RevealWith`, `BrowserFrame`, and `Keyboard`
 - [Customization](docs/customization.md) - themes, layout sets, Tailwind tokens, custom layouts, and layout demos
 - [Navigation](docs/navigation.md) - keyboard, touch, overview mode, and URL state
 - [Mobile and touch](docs/mobile.md) - mobile controls, touch gestures, and pinch zoom

package/SPEC.md

@@ -33,7 +33,7 @@ The Honeydeck specification is distributed:
 | Styling | Explicit CSS imports, Tailwind-compatible utilities, and CSS custom properties | [`src/theme/SPEC.md`](src/theme/SPEC.md) |
 | Markdown | MDX with GitHub-flavored Markdown tables; canonical docs use `docs/*.md` | [`src/vite-plugin/SPEC.md`](src/vite-plugin/SPEC.md), [`src/remark/SPEC.md`](src/remark/SPEC.md) |
 | PDF | Rasterized slide pages matching browser rendering | [`src/cli/SPEC.md`](src/cli/SPEC.md) |
-| Syntax highlighting | Built-in code highlighting with runtime step dimming | [`src/remark/SPEC.md`](src/remark/SPEC.md) |
+| Syntax highlighting | Built-in code highlighting, runtime step dimming, and Magic Code transitions | [`src/remark/SPEC.md`](src/remark/SPEC.md) |
 | Icons | `lucide-react` suffixed `...Icon` component imports | [`src/SPEC.md`](src/SPEC.md) |
 | Public imports | Explicit import subpaths for components, layouts, themes, and types | [`src/SPEC.md`](src/SPEC.md) |
 
@@ -55,9 +55,9 @@ The Honeydeck specification is distributed:
 | Starter templates | [`src/cli/templates/SPEC.md`](src/cli/templates/SPEC.md) | generated project tree, starter `deck.mdx`, `styles.css`, demo component |
 | Agent skills | [`skills/SPEC.md`](skills/SPEC.md) | bundled installable skills and installer expectations |
 | Deck loading / frontmatter | [`src/vite-plugin/SPEC.md`](src/vite-plugin/SPEC.md) | deck entry, slide separators, MDX imports, assets, Markdown features, frontmatter |
-| Remark transforms | [`src/remark/SPEC.md`](src/remark/SPEC.md) | code highlighting and step-through code metadata |
+| Remark transforms | [`src/remark/SPEC.md`](src/remark/SPEC.md) | timeline annotation, code highlighting, step-through code metadata, and Magic Code syntax |
 | Runtime | [`src/runtime/SPEC.md`](src/runtime/SPEC.md) | timeline semantics, keyboard/touch navigation, SPA/build behavior, runtime errors |
-| Runtime components | [`src/runtime/components/SPEC.md`](src/runtime/components/SPEC.md) | `Reveal`, `RevealGroup`, `TimelineSteps`, `ListStyle`, `Keyboard`, `BrowserFrame`, `Notes` |
+| Runtime components | [`src/runtime/components/SPEC.md`](src/runtime/components/SPEC.md) | `Reveal`, `RevealWith`, `RevealGroup`, `Fade`, `FadeWith`, `FadeGroup`, `TimelineSteps`, `ListStyle`, `Keyboard`, `BrowserFrame`, `Notes` |
 | Runtime views | [`src/runtime/views/SPEC.md`](src/runtime/views/SPEC.md) | presenter mode, overview mode, theme/layout/component reference pages |
 | Layouts and customization | [`src/layouts/SPEC.md`](src/layouts/SPEC.md) | custom theme/layout/component model, built-in layouts, layout props, demos, layout resolution |
 | Theme | [`src/theme/SPEC.md`](src/theme/SPEC.md) | design tokens, base theme CSS, Tailwind mapping, color mode behavior |

package/docs/components-browser-frame.md

@@ -0,0 +1,34 @@
+# BrowserFrame
+
+Use `<BrowserFrame>` to show a live iframe inside a macOS-style browser window.
+
+```mdx
+import { BrowserFrame } from '@honeydeck/honeydeck'
+
+<BrowserFrame
+  src="https://example.com"
+  addressBar="example.com"
+  fallbackImage="/example-fallback-light.png"
+  fallbackDarkImage="/example-fallback-dark.png"
+/>
+```
+
+The component renders browser chrome with macOS traffic-light controls and an optional address bar. It can show a light or dark fallback screenshot when the iframe cannot be loaded. It uses Honeydeck theme tokens for the frame, border, typography, and iframe surface.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` | `string` | Required | URL loaded by the iframe. Use an external `https://` URL or a local Vite-served route like `/demo.html`. |
+| `addressBar` | `ReactNode` | — | Optional content shown in the address-bar field. Omit it to hide the input-like address field. |
+| `fallbackImage` | `string` | — | Light/default screenshot shown when iframe loading fails or fallback mode is toggled on. |
+| `fallbackDarkImage` | `string` | — | Dark-mode screenshot shown when fallback mode is active. Falls back to `fallbackImage` when omitted. |
+| `fallbackAlt` | `string` | `Fallback preview` | Accessible alt text for fallback images. |
+| `defaultFallback` | `boolean` | `false` | Starts in fallback mode instead of loading the iframe. Useful for deterministic demos, final-state screenshots, and PDF-friendly decks. |
+| `aspectRatio` | `CSSProperties["aspectRatio"]` | `16 / 9` | Aspect ratio for the full browser window, including chrome. Accepts values such as `16 / 9`, `"4 / 3"`, or `1.6`. |
+| `className` | `string` | — | Additional CSS class for the outer browser frame. |
+| `iframeClassName` | `string` | — | Additional CSS class for the iframe element. Only applies while live iframe content is rendered. |
+
+Standard iframe attributes such as `allow`, `sandbox`, `loading`, and `referrerPolicy` are forwarded.
+
+When fallback mode is active, the browser frame shows a badge in the top chrome, visually aligned with the address bar. A fourth round control sits beside the macOS traffic-light controls and only becomes visible when the control itself is hovered or keyboard-focused; it toggles fallback mode.

package/docs/components-keyboard.md

@@ -0,0 +1,31 @@
+# Keyboard
+
+Use `<Keyboard>` to show one key or a shortcut in slide prose.
+
+```mdx
+import { Keyboard } from '@honeydeck/honeydeck'
+
+Press <Keyboard>Esc</Keyboard> to close overview.
+
+Advance with <Keyboard keys="Space" />.
+
+Open command palette with <Keyboard keys={["Ctrl", "Shift", "P"]} />.
+```
+
+`keys` accepts a single value or an ordered array. When `keys` is omitted, `children` is rendered as one key. Array values render one `<kbd>` per key, separated by `+` by default:
+
+```mdx
+<Keyboard keys={["⌘", "K"]} />
+<Keyboard keys={["Ctrl", "Alt", "Delete"]} separator=" " />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `keys` | `ReactNode \| ReactNode[]` | — | Key label or ordered shortcut key labels. |
+| `children` | `ReactNode` | — | Single key label when `keys` is omitted. |
+| `separator` | `ReactNode` | `+` | Separator rendered between array entries. |
+| `className` | `string` | — | Custom class for the outer wrapper. |
+
+The component uses semantic `<kbd>` markup, is inline by default, uses Honeydeck theme styling, and does not add timeline steps.

package/docs/components-list-style.md

@@ -0,0 +1,49 @@
+# ListStyle
+
+Use `<ListStyle>` to style Markdown, HTML, or JSX lists inside a wrapper.
+
+By default it removes native markers:
+
+```mdx
+import { ListStyle } from '@honeydeck/honeydeck'
+
+<ListStyle>
+  - No marker
+  - Still aligned
+</ListStyle>
+```
+
+Pass `bullets` to render custom markers:
+
+```mdx
+import { ListStyle } from '@honeydeck/honeydeck'
+import { CheckIcon, CircleIcon } from 'lucide-react'
+
+<ListStyle bullets={[<CheckIcon />, <CircleIcon />]}>
+  - Level one uses a check icon
+    - Level two uses a circle icon
+</ListStyle>
+
+<ListStyle bullets={["→", "–", "·"]}>
+  - Level one
+    - Level two
+      - Level three
+</ListStyle>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | List content to style. |
+| `bullets` | `ReactNode \| ReactNode[] \| false \| "none" \| null` | `undefined` | Marker config. Omit it, pass `false`, `"none"`, or `null` for markerless lists. |
+| `className` | `string` | — | Custom class for the wrapper. |
+| `style` | `CSSProperties` | — | Inline style for the wrapper. |
+
+## Behavior
+
+- Native list markers are removed for all nested lists in the wrapper.
+- A single `bullets` value is reused for every nesting level.
+- An array uses one marker per nesting level.
+- Deeper levels reuse the last configured marker.
+- Custom markers apply to authored list elements passed as children.

package/docs/components-notes.md

@@ -0,0 +1,36 @@
+# Notes
+
+Use `<Notes>` to add presenter-only speaker notes to a slide.
+
+```mdx
+import { Notes } from '@honeydeck/honeydeck'
+
+# Launch plan
+
+- What changed
+- Why it matters
+
+<Notes>
+  # Demo cue
+
+  - Demo the interactive component.
+  - Mention PDF export.
+</Notes>
+```
+
+Notes render nothing in audience view, overview thumbnails, and normal PDF output. In presenter mode, Markdown inside `<Notes>` renders as formatted speaker notes, including headings, paragraphs, lists, links, inline code, code blocks, and block quotes.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Speaker-note content collected by presenter mode. |
+
+## Behavior
+
+- `<Notes>` is a no-op outside presenter mode.
+- Notes are collected from the current slide preview in presenter mode.
+- Updating the slide notes updates the presenter notes panel.
+- You can use Markdown inside Notes.
+
+See [Presenter mode](presenter-mode.md) for the full presenter workflow.

package/docs/components-reveal-group.md

@@ -0,0 +1,58 @@
+# RevealGroup
+
+Use `<RevealGroup>` when a short sequence should appear one item at a time.
+
+```mdx
+import { RevealGroup } from '@honeydeck/honeydeck'
+
+<RevealGroup>
+  - First point
+  - Second point
+  - Third point
+</RevealGroup>
+```
+
+Each meaningful direct child becomes one timeline step. Whitespace-only text children are ignored. Markdown, HTML, and JSX lists are special: each top-level list item is revealed one after another while preserving the list container.
+
+Use `listRevealMode="nested"` when nested list items should also become individual steps:
+
+```mdx
+<RevealGroup listRevealMode="nested">
+  - Parent
+    - Child A
+    - Child B
+  - Sibling
+</RevealGroup>
+```
+
+Timeline: parent → child A → child B → sibling. The default mode is `"direct"`, which keeps nested items grouped with their parent.
+
+To reveal multiple elements together, wrap them in one direct child:
+
+```mdx
+<RevealGroup>
+  <div>
+    <h3>One idea</h3>
+    <p>Supporting context appears with it.</p>
+  </div>
+  <div>Next idea</div>
+</RevealGroup>
+```
+
+Nested timeline entries inside a group target are flattened after that target and before the following group target:
+
+```mdx
+<RevealGroup>
+  <div>
+    Parent item
+    <Reveal>Nested detail</Reveal>
+  </div>
+  <div>Sibling item</div>
+</RevealGroup>
+```
+
+**Timeline:**
+
+1. Parent item appears
+2. Nested detail appears
+3. Sibling item appears

package/docs/components-reveal-with.md

@@ -0,0 +1,37 @@
+# RevealWith
+
+Use `<RevealWith>` when content should appear at the same timeline step as a named `<Reveal>` or any existing numeric slide step. It never adds a new step.
+
+````mdx
+import { Reveal, RevealWith } from '@honeydeck/honeydeck'
+
+<Reveal name="intro">Intro appears first</Reveal>
+<RevealWith target="intro">This appears with the intro reveal</RevealWith>
+
+```ts {1|2|3}
+const answer = 42
+console.log(answer)
+```
+
+<RevealWith at={2}>This appears with step 2</RevealWith>
+````
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `target` | `string` | — | Same-slide `<Reveal name="...">` target. Must be a literal non-empty string. Use exactly one of `target` or `at`. |
+| `at` | `number` | resolved/injected | Existing 1-based slide-local timeline step. Must be a literal positive integer when authored. Use exactly one of `target` or `at`. |
+| `children` | `ReactNode` | — | Content to reveal with the target step. |
+| `className` | `string` | — | Custom class for styling or transitions. |
+| `as` | `"div" | "span"` | injected | Wrapper element. Honeydeck injects this to keep valid MDX/HTML around block or inline content. |
+
+## Behavior
+
+- `RevealWith` is cumulative like `Reveal`: once visible, it stays visible.
+- `target` supports forward references to named reveals later on the same slide.
+- `at` can target any existing slide step, including a `RevealGroup` item, code highlight, Magic Code state, or `TimelineSteps` state.
+- Hidden content reserves layout space and uses the same fade/future-preview behavior as `Reveal`.
+- Invalid targets, duplicate reveal names, non-literal values, and out-of-range numeric steps are build errors.
+
+See [Steps and reveals](steps-and-reveals.md#revealwith) for timeline ordering examples.

package/docs/components-reveal.md

@@ -0,0 +1,33 @@
+# Reveal
+
+Use `<Reveal>` when content should appear at the next timeline step.
+
+```mdx
+import { Reveal } from '@honeydeck/honeydeck'
+
+<Reveal>Start with Markdown</Reveal>
+<Reveal>Enhance with React</Reveal>
+<Reveal>Export to PDF</Reveal>
+```
+
+Reveals are cumulative: once visible, they stay visible while you advance through the slide. Hidden reveal content reserves layout space, so the slide does not jump when the content appears.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Content to reveal. |
+| `name` | `string` | — | Optional slide-local target for [`RevealWith target="..."`](components-reveal-with.md). Must be a literal non-empty string. |
+| `className` | `string` | — | Custom class for styling or transitions. |
+| `at` | `number` | injected | Timeline step. Honeydeck injects this during compilation; author-authored values are build errors. Use [`RevealWith`](components-reveal-with.md) to sync with an existing step. |
+| `as` | `"div" \| "span"` | injected | Wrapper element. Honeydeck injects this to keep valid MDX/HTML around block or inline content. |
+
+## Behavior
+
+- Reveals fade in.
+- Hidden content uses `visibility: hidden` plus `opacity: 0`, not `display: none`.
+- Nested reveals are supported.
+- Inline reveals inside paragraphs render inline wrappers.
+- Optional `name="..."` creates a slide-local target for [`RevealWith`](components-reveal-with.md).
+
+See [Steps and reveals](steps-and-reveals.md) for timeline ordering examples.

package/docs/components-timeline-steps.md

@@ -0,0 +1,48 @@
+# 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/docs/components.md

@@ -3,61 +3,20 @@
 Honeydeck core components are explicit imports from `@honeydeck/honeydeck`. They are also exported from `@honeydeck/honeydeck/components`.
 
 ```mdx
-import { Keyboard } from '@honeydeck/honeydeck'
+import { Reveal, RevealWith, RevealGroup, TimelineSteps, ListStyle, Keyboard, BrowserFrame, Notes } from '@honeydeck/honeydeck'
 ```
 
-## BrowserFrame
+Use these pages as the component reference:
 
-Use `<BrowserFrame>` to show a live iframe inside a macOS-style browser window.
+| Component | Use it for |
+| --- | --- |
+| [`Reveal`](components-reveal.md) | Show content at a specific slide timeline step. |
+| [`RevealWith`](components-reveal-with.md) | Show content with an existing reveal or numeric slide step without adding another step. |
+| [`RevealGroup`](components-reveal-group.md) | Reveal each direct child or list item one after another, with optional nested-list reveals. |
+| [`TimelineSteps`](components-timeline-steps.md) | Reserve timeline steps for an imported custom React component. |
+| [`ListStyle`](components-list-style.md) | Style Markdown, HTML, or JSX lists with no markers or custom markers. |
+| [`Keyboard`](components-keyboard.md) | Render semantic inline keyboard keys and shortcuts. |
+| [`BrowserFrame`](components-browser-frame.md) | Show a live iframe or fallback screenshot inside browser chrome. |
+| [`Notes`](components-notes.md) | Add formatted speaker notes for presenter mode. |
 
-```mdx
-import { BrowserFrame } from '@honeydeck/honeydeck'
-
-<BrowserFrame
-  src="https://example.com"
-  addressBar="example.com"
-  fallbackImage="/example-fallback-light.png"
-  fallbackDarkImage="/example-fallback-dark.png"
-/>
-```
-
-The component renders browser chrome with macOS traffic-light controls and an optional address bar. It can show a light or dark fallback screenshot when the iframe cannot be loaded. It uses Honeydeck theme tokens for the frame, border, typography, and iframe surface.
-
-Props:
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `src` | `string` | Required | URL loaded by the iframe. Use an external `https://` URL or a local Vite-served route like `/demo.html`. |
-| `addressBar` | `ReactNode` | — | Optional content shown in the address-bar field. Omit it to hide the input-like address field. |
-| `fallbackImage` | `string` | — | Light/default screenshot shown when iframe loading fails or fallback mode is toggled on. |
-| `fallbackDarkImage` | `string` | — | Dark-mode screenshot shown when fallback mode is active. Falls back to `fallbackImage` when omitted. |
-| `fallbackAlt` | `string` | `Fallback preview` | Accessible alt text for fallback images. |
-| `defaultFallback` | `boolean` | `false` | Starts in fallback mode instead of loading the iframe. Useful for deterministic demos, final-state screenshots, and PDF-friendly decks. |
-| `aspectRatio` | `CSSProperties["aspectRatio"]` | `16 / 9` | Aspect ratio for the full browser window, including chrome. Accepts values such as `16 / 9`, `"4 / 3"`, or `1.6`. |
-| `className` | `string` | — | Additional CSS class for the outer browser frame. |
-| `iframeClassName` | `string` | — | Additional CSS class for the iframe element. Only applies while live iframe content is rendered. |
-
-Standard iframe attributes such as `allow`, `sandbox`, `loading`, and `referrerPolicy` are forwarded.
-
-When fallback mode is active, the browser frame shows a badge in the top chrome, visually aligned with the address bar. A fourth round control sits beside the macOS traffic-light controls and only becomes visible when the control itself is hovered or keyboard-focused; it toggles fallback mode.
-
-## Keyboard
-
-Use `<Keyboard>` to show one key or a shortcut in slide prose.
-
-```mdx
-Press <Keyboard>Esc</Keyboard> to close overview.
-
-Advance with <Keyboard keys="Space" />.
-
-Open command palette with <Keyboard keys={["Ctrl", "Shift", "P"]} />.
-```
-
-`keys` accepts a single value or an ordered array. When `keys` is omitted, `children` is rendered as one key. Array values render one `<kbd>` per key, separated by `+` by default:
-
-```mdx
-<Keyboard keys={["⌘", "K"]} />
-<Keyboard keys={["Ctrl", "Alt", "Delete"]} separator=" " />
-```
-
-The component is inline by default, uses Honeydeck theme styling, supports `className`, and does not add timeline steps.
+For broader timing concepts, see [Steps and reveals](steps-and-reveals.md). For custom components and layouts, see [Customization](customization.md).

package/docs/configuration.md

@@ -15,6 +15,7 @@ Defined in the first frontmatter block of the deck entry file (before any slide
 | `pdfColorMode` | `"light" \| "dark"` | unset | Optional PDF color mode; when unset, falls back to pinned `colorMode`, then `light` |
 | `pdfSteps` | `"final" \| "all"` | `"final"` | PDF includes all steps or final state |
 | `transition` | `boolean` | `true` | Enable crossfade between slides |
+| `magicCodeDuration` | `number` | `800` | Default Magic Code animation duration in milliseconds |
 | `layouts` | `string` | `""` (built-in) | Layout map module path |
 | `defaultLayout` | `string` | `"Default"` | Layout used when slide has no `layout:` |
 | `showSlideNumbers` | `boolean` | `false` | Show the current slide number in the bottom-right corner of slides |
@@ -50,6 +51,16 @@ transition: true    # default
 transition: false   # disable
 ```
 
+### Magic Code Duration
+
+Magic Code animations default to 800ms. Set a deck-wide default with `magicCodeDuration`:
+
+```yaml
+magicCodeDuration: 500
+```
+
+A Magic Code block can override this locally with `{duration:500}`. Slide-level frontmatter does not configure Magic Code; the same key in slide frontmatter is treated as a layout prop.
+
 ## Slide-Level Settings
 
 Per-slide frontmatter (after `---`):

package/docs/deeper-dive.md

@@ -128,7 +128,7 @@ For the full reference, see [Configuration](configuration.md).
 Core runtime components are explicit imports from `honeydeck`.
 
 ```mdx
-import { Reveal, RevealGroup, TimelineSteps, BrowserFrame, Notes } from '@honeydeck/honeydeck'
+import { Reveal, RevealWith, RevealGroup, TimelineSteps, BrowserFrame, Notes } from '@honeydeck/honeydeck'
 ```
 
 ### Reveal steps
@@ -136,11 +136,18 @@ import { Reveal, RevealGroup, TimelineSteps, BrowserFrame, Notes } from '@honeyd
 `<Reveal>` reveals content at the next timeline step. Hidden content keeps its layout space so the slide does not jump.
 
 ```mdx
-<Reveal>Appears at step 1</Reveal>
+<Reveal name="first">Appears at step 1</Reveal>
 <Reveal>Appears at step 2</Reveal>
 ```
 
-`<RevealGroup>` wraps each direct child in a reveal step. Markdown and HTML lists are special: each list item reveals one after another.
+`<RevealWith>` syncs extra content to an existing step without adding a step:
+
+```mdx
+<RevealWith target="first">Appears with step 1</RevealWith>
+<RevealWith at={2}>Appears with step 2</RevealWith>
+```
+
+`<RevealGroup>` wraps each direct child in a reveal step. Markdown and HTML lists are special: each top-level list item reveals one after another. Use `listRevealMode="nested"` to reveal nested list items depth-first.
 
 ```mdx
 <RevealGroup>
@@ -202,6 +209,22 @@ console.log(b)
 - `{2-3|5|all}` starts with lines 2-3 active, then steps to line 5, then all lines.
 - Highlight groups after the first interleave with `<Reveal>` in document order.
 
+Magic Code animates between multiple code states. It builds on Shiki Magic Code / Shiki Magic Move while keeping Honeydeck's build-time highlighting and timeline behavior:
+
+`````mdx
+````md magic-code {duration:500}
+```ts
+const count = 1
+```
+
+```ts
+const count = 2
+```
+````
+`````
+
+Each inner code fence is a state. Inner code fence line metadata still works, so Honeydeck advances through a state's highlight groups before morphing to the next code state. Content inside a Magic Code block that is not a fenced code block is ignored. `md magic-move` is accepted as a Slidev compatibility alias, but Honeydeck docs and examples use `md magic-code`.
+
 ## Navigation, presenting, and PDF
 
 Keyboard shortcuts:
@@ -213,7 +236,7 @@ Keyboard shortcuts:
 | `down` / `s` | Next slide |
 | `up` / `w` | Previous slide |
 | `o` | Toggle overview mode |
-| `p` | Open presenter mode |
+| `p` | Open presenter mode in the current tab |
 | `f` | Toggle fullscreen |
 | `Escape` | Exit overview or fullscreen |
 
@@ -236,7 +259,7 @@ Presenter mode opens with `p` and includes:
 - speaker notes from `<Notes>`
 - slide/step counter and wall clock
 - an "Open audience view" button
-- audience sync through `BroadcastChannel`
+- audience sync through `BroadcastChannel`, with Presentation API casting when supported
 
 See [Navigation](navigation.md), [Mobile and touch](mobile.md), [Presenter mode](presenter-mode.md), and [PDF export](pdf-export.md).
 
@@ -328,7 +351,7 @@ Package Markdown guides live on the Honeydeck docs site and in the package `docs
 | Layouts | Runtime dynamic import of the layout map |
 | Tailwind | v4 CSS-first; Honeydeck adds the Vite plugin internally |
 | Shiki | Dual-theme CSS variables with build-time highlighting |
-| Presenter sync | `BroadcastChannel`, unidirectional, no server needed |
+| Presenter sync | `BroadcastChannel` fallback + Presentation API casting, no server needed |
 | Scaling | `transform: scale()` from the configured aspect ratio |
 | Build | `tsc` only, ESM, no bundler |
 | Testing | `node:test` plus fixture files |
@@ -336,7 +359,7 @@ Package Markdown guides live on the Honeydeck docs site and in the package `docs
 ## Types and exports
 
 ```ts
-import { Reveal, RevealGroup, Notes } from '@honeydeck/honeydeck'
+import { Reveal, RevealWith, RevealGroup, Notes } from '@honeydeck/honeydeck'
 import type { LayoutProps, LayoutMap, LayoutDemo } from '@honeydeck/honeydeck/types'
 
 import defaultLayouts from '@honeydeck/honeydeck/layouts'

package/docs/getting-started.md

@@ -70,7 +70,7 @@ Use `layout:` to choose a slide layout. Built-in layouts include `Blank`, `Defau
 - Vite dev/build with hot reload
 - Built-in layouts and theme tokens
 - Tailwind v4-friendly styling
-- Reveal steps and code step-through
+- Reveal steps, code step-through, and Magic Code transitions
 - Presenter mode with speaker notes
 - Overview mode, keyboard/touch navigation, and URL state
 - PDF export through headless Chromium
@@ -102,7 +102,7 @@ honeydeck skill               # install optional Honeydeck agent skills
 - [Slides](slides.md) - separators, multiple files, layouts, and assets
 - [Configuration](configuration.md) - deck-level and slide-level frontmatter
 - [Steps and reveals](steps-and-reveals.md) - timeline, reveal groups, code steps, and PDF behavior
-- [Components](components.md) - core Honeydeck components such as `BrowserFrame` and `Keyboard`
+- [Components](components.md) - core Honeydeck components such as `Reveal`, `RevealWith`, `TimelineSteps`, `BrowserFrame`, and `Keyboard`
 - [Customization](customization.md) - themes, layout sets, Tailwind tokens, custom layouts, and layout demos
 - [Navigation](navigation.md) - keyboard, touch, overview mode, and URL state
 - [Mobile and touch](mobile.md) - mobile controls, touch gestures, and pinch zoom

package/docs/navigation.md

@@ -9,7 +9,7 @@
 | `↓` / `s` | Next slide |
 | `↑` / `w` | Previous slide |
 | `o` | Toggle overview mode |
-| `p` | Open presenter mode (new window) |
+| `p` | Open presenter mode (same tab) |
 | `f` | Toggle fullscreen |
 | `Escape` | Exit overview / exit fullscreen |
 

package/docs/pdf-export.md

@@ -51,14 +51,16 @@ Honeydeck builds an ordered capture plan before taking screenshots. The final PD
 
 When `pdfSteps: all`:
 
-- Each `Reveal`/`RevealGroup` step becomes a separate page.
+- Each `Reveal`/`RevealGroup` step becomes a separate page. `RevealWith` appears on the page for its target step and adds no extra page.
 - Stepped code blocks show their first highlight group on the baseline page; each later code highlight group becomes a separate page.
-- Both use the same underlying timeline.
+- Magic Code blocks show their first inner code fence on the baseline page; later line-highlight states and code morph states become separate pages according to the same timeline.
+- Reveals, stepped code blocks, Magic Code, and custom `TimelineSteps` blocks use the same underlying timeline.
 
 When `pdfSteps: final` (default):
 
 - All reveals shown in final (visible) state.
 - Code blocks shown with final highlight applied.
+- Magic Code blocks shown at their final code state with final highlight applied.
 - `useTimeline()` and `useTimelineSteps()` expose `isPdfFinalRender: true`, so
   custom step-driven components can render an all-open/all-visible PDF state.
 

package/docs/presenter-mode.md

@@ -29,6 +29,7 @@ Includes:
 - Slide number / step counter
 - Wall clock
 - Button to open audience view in a new tab/window
+- Button to cast the audience view to a secondary display when supported; the same control becomes a stop button while casting and is disabled with a hint when unsupported
 - Navigation buttons that move through the timeline while staying in presenter mode
 
 ## Speaker Notes
@@ -58,11 +59,11 @@ Content here.
 
 ## Opening Presenter Mode
 
-- Keyboard shortcut `p` from normal presentation → opens in a new window/tab.
+- Keyboard shortcut `p` from normal presentation → opens presenter mode in the current tab.
 - Navigation controls button in normal presentation.
 - Direct URL: `/#/presenter/1/0`
 
-Pressing `p` opens presenter mode in a **new window** so the audience view stays on the projector.
+Pressing `p` opens presenter mode in the **current tab**.
 
 ## Navigation
 
@@ -85,10 +86,12 @@ When no next timeline state exists, the `Next` preview shows an end-of-deck plac
 
 ## Presenter/Audience Sync
 
-Presenter mode and audience view synchronize navigation via `BroadcastChannel` in the same browser/profile.
+Presenter mode and audience view synchronize navigation via `BroadcastChannel` and, when supported, the Presentation API.
 
 - Presenter mode acts as the controller.
 - Audience view (opened from presenter mode) listens for navigation updates.
+- The cast audience sends a `sync-request` as soon as the receiver connection appears; the presenter replies with the current slide/step in a `sync-response` so late connections resync immediately.
+- The cast audience follows presenter navigation through Presentation API receiver messages.
 - No server, internet, WebSocket, or device pairing required.
 - If `BroadcastChannel` is unavailable, both views function independently.