slidev-theme-kotlin 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## Unreleased
+
+## 0.12.0
+
+### Added
+
+- Support Magic Move between slides: a `magic-move` separator (or `magicMove: true` frontmatter) links consecutive slides, and their top-level code fences morph across the slide boundary in both navigation directions. Code windows pair up by position, so parallel snippets (for example Kotlin next to SQL) animate independently, and decks using `transition: view-transition` pair the code windows through the View Transitions API instead of cross-fading them.
+- Support per-click line highlighting (`{1|2-3}`) and fence options (`{lines:true, at:2}`) on chained fences: the ranges register as clicks on their slide and step through before navigation moves on, matching classic Magic Move behaviour.
+- Add a development-only visual annotation editor: `drawnAnnotationEditor()` (exported as `slidev-theme-kotlin/annotation-editor`) injects transient source locators while serving, and persists dragged label, width, and connector geometry as a normalized `:geometry` binding on exactly the edited `DrawnAnnotation` tag — with keyboard nudging, undo, revision-conflict detection, and reset controls. Builds and exports carry no editor code.
+- Add the `geometry` prop to `DrawnAnnotation`: normalized source-local label and connector geometry, including quadratic Bézier connectors, that overrides automatic placement.
+- Add `DrawnAnnotation`'s passive mode for observing a click already owned by nearby `v-click` / `v-clicks` content without registering an extra click step.
+- Add JDBC and R2DBC identity badges and border colours for Kotlin code fences with the `jdbc` and `r2dbc` modifiers.
+
+### Changed
+
+- Make automatic `DrawnAnnotation` label placement deterministic: candidates prefer the requested side and stay clear of the slide's laid-out content (including still-hidden v-click content, so a label never sits where the slide is about to grow), of the annotation's own mark, of labels placed by earlier annotations, and of `avoid-selector` matches (kept at `clearance` distance), wrapping into free space when needed.
+- **Breaking**: replace `DrawnAnnotation`'s `label-x` / `label-y` / `label-width` props with the normalized `geometry.label` binding.
+- **Breaking**: a `DrawnAnnotation` without `at`/`on` is now part of the initial slide state instead of taking the next automatic click; give `at` or `on` for a reveal.
+- Render `DrawnAnnotation` labels as safe Markdown; inline code and block quotes use the theme's local-first JetBrains Mono stack.
+
+### Fixed
+
+- Persist curved-connector edits: the source writer no longer rejects the `type: 'quadratic'` connector shape its own serializer emits.
+- Ship `slidev-theme-kotlin/annotation-editor` as plain JavaScript with type declarations, so a consuming deck's `vite.config.ts` can load it under Node instead of failing on raw TypeScript inside node_modules.
+- Keep a save conflict recoverable: after a 409 the write client no longer adopts the other author's revision, so a continuing drag cannot silently overwrite their edit.
+- Persist a width-only first edit by materializing the label's current position, instead of silently dropping the width while reporting "Annotation saved".
+- Translate a quadratic connector's control point with arrow-key body nudges, matching pointer body drags instead of distorting the saved curve.
+- Match the Alt+Shift+A editor shortcut by physical key so it works on macOS, where Option+Shift+A composes "Å".
+- Escape quotes in cross-slide Magic Move fence titles and options, so titles like `[Bob's file.kt]` and options like `{at:"+2"}` no longer break the slide markup.
+- Morph cross-slide Magic Move from the correct step when a chain slide contributes no fence at a position, and give duplicate identical fences on one slide their own animation identity.
+- Decode annotation source locators as UTF-8 in the browser, so decks with non-ASCII filenames can save geometry.
+- Do not apply the code-chip background to inline Markdown code in `DrawnAnnotation` labels.
+
+## 0.11.0
+
+### Added
+
+- Bundle `InlineCompilerError`, a click-aware inline diagnostic component that marks source lines or exact code text in static Shiki and Magic Move blocks.
+- Add IntelliJ-style identity icons to code windows for Kotlin, Gradle, Amper, Java, terminal, Maven, and PostgreSQL fences, including Kotlin and Gradle fence aliases.
+- Add `export:slide` for exporting an individual slide at an exact click state.
+- Add visual regression review and check scripts for comparing the theme and consumer decks across revisions.
+
+### Changed
+
+- Make code-window icon border colours and column-based code sizing customizable through CSS variables.
+- Improve `DrawnAnnotation` tracking, label placement, obstacle detection, and animation timing across Magic Move and view transitions.
+- Update Slidev dependencies to 52.19.1 and require Node.js 20.12 or newer.
+
+### Documentation
+
+- Document inline compiler diagnostics, code-window icons and sizing, single-slide export, and visual regression review workflows.
+
 ## 0.10.0
 
 ### Added

package/README.md

@@ -8,15 +8,17 @@ This theme provides a professional presentation template tailored for Kotlin dev
 
 - **Kodee Mascot Integration**: Animated Kodee character with multiple variants (greeting, wink, wave, jumping, sitting, drinking, heart, in-love, welcome, winter, tiny)
 - **Magic Move Animations**: Smooth transitions for Kodee between slides with configurable size and position
+- **Magic Move between slides**: Link slides with a `magic-move` separator and their code windows morph across the slide boundary, including several parallel snippets per slide
 - **Kotlin Syntax Highlighting**: Custom Shiki configuration optimized for Kotlin code
 - **Multiple Layouts**: Pre-built layouts including default, cover, and intro
 - **Kotlin Branding**: Official Kotlin logos for both light and dark modes
-- **JetBrains Fonts**: Uses Inter for sans-serif and JetBrains Mono for code
+- **JetBrains Fonts**: Prefers locally installed JetBrains Sans and JetBrains Mono, with Inter and Google-hosted JetBrains Mono fallbacks
 - **Drawn annotations**: Click-aware, hand-drawn marks, labels, and connectors for elements and code
+- **Inline compiler diagnostics**: IntelliJ-style squiggles and messages for static and Magic Move code blocks
 
 ## Requirements
 
-- **Node.js**: >= 18.0.0
+- **Node.js**: >= 20.12.0
 - **Package Manager**: npm (or pnpm with shamefully-hoist=true)
 
 ## Installation
@@ -29,6 +31,29 @@ npm install slidev-theme-kotlin
 
 ## Usage
 
+### Visual annotation editor (development)
+
+Enable the optional, development-only source writer in the consuming deck's
+`vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite'
+import { drawnAnnotationEditor } from 'slidev-theme-kotlin/annotation-editor'
+
+export default defineConfig({
+  plugins: [drawnAnnotationEditor()],
+})
+```
+
+Open Slidev's annotation editor (or press **Alt+Shift+A**) and drag a visible
+label, its width handle, or a connector control. The editor persists normalized
+`:geometry` on exactly that `DrawnAnnotation` tag. **Cmd/Ctrl+Z** undoes a
+saved edit; reset controls restore label, connector, or all geometry. Source
+revisions are checked, so a conflict preserves the local draft until **Reload
+saved geometry** is chosen. The locator, toolbar, and write endpoint exist only
+while Vite serves the deck; builds and exports render saved geometry without
+editor code.
+
 ### Basic Setup
 
 Add the theme to your slides' frontmatter:
@@ -42,6 +67,129 @@ transition: view-transition
 # Your Presentation Title
 ```
 
+### Code icons
+
+Code fences are rendered as one IntelliJ Light/Darcula editor surface without a
+title bar. A compact identity icon is placed in its top-right corner and follows
+the presentation color scheme:
+
+````md
+```kotlin
+fun main() = println("Hello")
+```
+
+```kts gradle
+plugins { kotlin("jvm") }
+```
+
+```yaml toolchain
+product: jvm/app
+```
+
+```xml maven
+<artifactId>demo</artifactId>
+```
+
+```sql
+SELECT * FROM presentations;
+```
+````
+
+`kotlin`, `kt`, and `kts` use the Kotlin icon; each with a `gradle`, `jdbc`,
+or `r2dbc` modifier uses the Gradle, JDBC, or R2DBC identity respectively.
+`yaml toolchain`, `java`, `bash`, `xml maven`, and `sql` use the Amper, Java,
+Terminal, Maven, and PostgreSQL icons respectively. All other fences remain plain
+code surfaces.
+
+The identity border colours are exposed as theme variables and can be
+customized from a deck stylesheet. Each variable has a light and dark-mode
+value:
+
+```css
+:root {
+  --code-window-kotlin-color: #834df0;
+  --code-window-gradle-color: #6c707e;
+  --code-window-amper-color: #087cfa;
+  --code-window-java-color: #e66d17;
+  --code-window-terminal-color: #6c707e;
+  --code-window-maven-color: #3574f0;
+  --code-window-postgresql-color: #336791;
+  --code-window-jdbc-color: #f59e0b;
+  --code-window-r2dbc-color: #06b6d4;
+}
+
+html.dark {
+  --code-window-kotlin-color: #a571e6;
+  /* Override any of the other dark-mode values as needed. */
+}
+```
+
+### Code sizing
+
+Every code window uses one font size calculated from the slide canvas width. By
+default, a full-width window fits 68 monospace characters. Override the column
+count once in the deck's stylesheet:
+
+```css
+:root {
+  --code-window-columns: 72;
+}
+```
+
+The calculation accounts for the standard layout and code padding. A custom
+layout with different horizontal spacing can override
+`--code-window-inline-space`. To bypass column-based sizing entirely, set an
+explicit `--code-window-font-size`, for example `1.25rem`.
+
+### Magic Move between slides
+
+Slidev's classic Magic Move animates code inside one slide, on clicks. This
+theme additionally supports morphing code **across slides**: put `magic-move`
+in the separator between two slides and their code windows animate from one to
+the next when you navigate.
+
+````md
+# My Slide
+
+```kotlin
+class Person
+```
+
+---
+magic-move
+---
+
+# My Slide
+
+```kotlin
+class Person(val name: String)
+```
+````
+
+Details:
+
+- The separator links the slide it precedes to the one before it, so the last
+  slide of a chain needs no marker. Any number of slides can be chained by
+  repeating the `magic-move` separator.
+- Code windows pair up **by position**: the first fence of a slide morphs into
+  the first fence of the next, the second into the second, and so on. Several
+  parallel snippets (say Kotlin next to SQL) each animate independently.
+- Everything outside the code fences is a normal slide — headings, prose, and
+  layout can change freely and follow the deck's regular slide transition.
+- With `transition: view-transition`, the code windows of both slides are
+  paired through the View Transitions API, so the window glides to its new
+  position while the tokens morph, instead of cross-fading with the page.
+- Navigating backward plays the animation in reverse. Deep links, the
+  overview, and PDF/PNG exports render each slide's own step statically.
+- Fence metadata still works: the code-window identity icons, `[Title]`
+  labels, and `{lines:true}` line numbers apply per chain. Per-click line
+  highlighting works too — `` ```kotlin {1|2-3} `` registers clicks on that
+  slide and steps through the ranges before navigation moves on, exactly like
+  one step of a classic Magic Move block. Snippet imports (`<<< @/...`) do
+  not participate in chains.
+- `magicMove: true` in the slide's YAML frontmatter is equivalent to the bare
+  `magic-move` separator and can be combined with other frontmatter keys.
+
 ### Using Kodee Mascot
 
 Enable Kodee once for the whole deck with `themeConfig`:
@@ -115,7 +263,7 @@ kodee:
 
 ### Using DrawnAnnotation
 
-`<DrawnAnnotation>` is auto-registered for every deck using the theme. It can mark an element with a selector or exact text inside a Shiki or Magic Move code block, then connect that mark to a label or another element.
+`<DrawnAnnotation>` is auto-registered for every deck using the theme. It can mark an element with a selector or exact text inside a Shiki or Magic Move code block, then connect that mark to a label or another element. Labels accept safe Markdown: backticked inline code and `>` quotes use the local-first JetBrains Mono stack.
 
 ````md
 <DrawnAnnotation type="circle" text="fun main" label="program entry point" :on="1">
@@ -129,6 +277,22 @@ fun main() = println("Hello, Kotlin!")
 
 The full prop reference, timing behavior, and troubleshooting guide are in [`components/README.md`](components/README.md). The bundled [`slides.md`](slides.md) includes working examples of code annotations, connectors, labels, sequential reveals, and Magic Move integration.
 
+### Using InlineCompilerError
+
+`<InlineCompilerError>` is auto-registered for every deck using the theme. Wrap one code block to underline a source line or exact text with an IntelliJ-style diagnostic; it follows both static Shiki blocks and Magic Move steps.
+
+````md
+<InlineCompilerError text="userName" message="Unresolved reference: userName" :on="1">
+
+```kotlin
+println(userName)
+```
+
+</InlineCompilerError>
+````
+
+See [`components/README.md`](components/README.md#inlinecompilererror) for the target and click-timing props.
+
 #### IntelliJ formatting
 
 IntelliJ recognizes only the first YAML block in a Markdown file as frontmatter. To keep later Slidev frontmatter intact when using **Reformat Code**, enable formatter tags and stop formatting after the deck headmatter:
@@ -163,10 +327,33 @@ npm run build
 # Export presentation to PDF
 npm run export
 
-# Export presentation as PNG screenshots
+# Export every slide and click state as PNG screenshots
 npm run screenshot
+
+# Export one slide; --click is zero-based (0 is the initial state)
+npm run export:slide -- --slide 12 --click 3
+
+# Render this working tree against HEAD and open the generated visual review
+npm run visual:review
+```
+
+### Exporting One Slide
+
+`npm run export:slide` is an AI-agent-friendly wrapper around `slidev export`. It writes one PNG rather than a directory of all exported pages:
+
+```bash
+# Initial state of slide 12
+npm run export:slide -- --slide 12
+
+# State after the third click of slide 12
+npm run export:slide -- --slide 12 --click 3 --output artifacts/slide-12-click-3.png
+
+# Use another deck entry
+npm run export:slide -- --entry path/to/talk.md --slide 4 --click 0
 ```
 
+`--slide` is one-based. `--click` is optional and zero-based, so `--click 0` is the initial slide state, `--click 1` is the state after one click, and so on. Without `--output`, screenshots are written under `.slidev/exports/`, which is ignored by Git. Run `npm run export:slide -- --help` for timeout, wait, and dark-mode options.
+
 ### Running the Slides
 
 The repository includes `slides.md`, a compact presentation demonstrating the theme's layouts, Kotlin highlighting, Kodee animations, magic moves, and click animations:
@@ -181,9 +368,11 @@ This will open the example presentation in your browser with hot-reload enabled.
 
 ```
 .
-├── components/          # Vue components
-│   ├── Kodee.vue       # Main Kodee mascot component with animations
-│   └── KodeeWrapper.vue # Wrapper component for Kodee integration
+├── components/                   # Vue components
+│   ├── DrawnAnnotation.vue        # Hand-drawn marks, labels, and connectors
+│   ├── InlineCompilerError.vue    # Inline code diagnostics
+│   ├── Kodee.vue                  # Main Kodee mascot component with animations
+│   └── KodeeWrapper.vue           # Wrapper component for Kodee integration
 ├── slide-bottom.vue     # Per-slide Kodee layer shared by every layout
 ├── layouts/            # Slidev layout templates
 │   ├── cover.vue       # Cover slide layout
@@ -198,7 +387,7 @@ This will open the example presentation in your browser with hot-reload enabled.
 ├── styles/             # Theme styles
 │   ├── index.ts        # Style entry point
 │   └── layout.css      # Layout styles
-├── debug.js            # Utility script for enumerating Shiki Kotlin tokens
+├── .pi/extensions/inspect-shiki-token-scopes.ts # Local Pi tool for inspecting Shiki token scopes
 ├── slides.md           # Example presentation used for local development and GitHub Pages
 ├── package.json        # Package configuration and dependencies
 └── LICENSE             # Apache License 2.0
@@ -210,11 +399,47 @@ This will open the example presentation in your browser with hot-reload enabled.
 
 No environment variables are currently required for this theme.
 
-## Testing
+## Visual regression review
+
+Visual review starts a temporary Slidev server and uses Playwright Chromium to
+capture every settled click state from Slidev's normal presenter/player route
+(`/<slide>?clicks=<click>`), rather than the print-export `?print=clicks` route.
+It renders the current working tree and a Git revision with the same browser,
+compares every PNG with `pixelmatch`, and writes a three-column
+base/current/diff page. When the local
+`~/Developer/kotlin-fundamentals` consumer deck is available, its baseline is
+rendered from its clean `HEAD` and its current capture includes its working-tree
+changes, with each capture linked to the corresponding theme revision.
+Screenshots are not committed: the chosen Git revision is the baseline, so
+accepting an intentional visual change is simply reviewing it and committing
+that change.
 
-<!-- TODO: Add test setup and instructions -->
+```bash
+# Compare the working tree with the last commit.
+npm run visual:review
+
+# Compare a branch with its integration base.
+npm run visual:review -- --base origin/main
+
+# Use in automation when any visual difference should fail the command.
+npm run visual:check -- --base origin/main
+```
+
+Open the `file://.../.visual/review/index.html` path printed by the command.
+The `.visual/` directory contains disposable base/current captures and diffs
+and is ignored by Git. `npm run screenshot` is the non-comparison escape hatch
+when raw PNGs are all that is needed.
+
+The visual exporter requires the Chromium binary supplied by
+`playwright-chromium`. If dependency installation is configured not to run
+package install scripts, download it once with:
+
+```bash
+npx playwright install chromium
+```
 
-No automated tests are currently configured for this theme.
+`npm run lint` validates the deck's frontmatter and Kodee configuration; `npm
+run build` runs that lint before building the Slidev deck.
 
 ## Configuration
 
@@ -257,11 +482,12 @@ layout: cover
 ## Dependencies
 
 ### Runtime Dependencies
-- `@slidev/types` (^52.2.5) - Slidev type definitions
-- `roughjs` (^4.6.6) - Hand-drawn SVG paths for `DrawnAnnotation`
+- `@shikijs/magic-move` (4.4.3) - Code-token morphing for Magic Move
+- `@slidev/types` (52.19.1) - Slidev type definitions
+- `roughjs` (4.6.6) - Hand-drawn SVG paths for `DrawnAnnotation`
 
 ### Development Dependencies
-- `@slidev/cli` (^52.2.5) - Slidev command-line interface
+- `@slidev/cli` (52.19.1) - Slidev command-line interface
 
 ## Contributing
 

package/annotation-editor.d.ts

@@ -0,0 +1,2 @@
+export { drawnAnnotationEditor } from './plugins/drawn-annotation-editor'
+export type { DrawnAnnotationEditorOptions, DrawnAnnotationGeometryPatch, DrawnAnnotationLabelGeometry } from './plugins/drawn-annotation-editor'

package/annotation-editor.mjs

@@ -0,0 +1,5 @@
+// Loaded by Node itself when a consuming deck's `vite.config.ts` imports
+// `slidev-theme-kotlin/annotation-editor`, so this entry must be plain
+// JavaScript: Vite's config bundler externalizes resolved node_modules
+// imports, and Node refuses raw TypeScript under node_modules.
+export { drawnAnnotationEditor } from './plugins/drawn-annotation-editor.mjs'

package/assets/edit-3-svgrepo-com.svg

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg width="800px" height="800px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M19.767 3.33517L22.5484 6.2099L12.4869 15.9447L8.94013 16.5933L9.70549 13.0699L19.767 3.33517Z" stroke="#333333" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M20 14V17C20 18.6569 18.6569 20 17 20H7C5.34315 20 4 18.6569 4 17V7C4 5.34315 5.34315 4 7 4H12" stroke="#333333" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>