slidev-theme-kotlin 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 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

@@ -13,6 +13,7 @@ This theme provides a professional presentation template tailored for Kotlin dev
 - **Kotlin Branding**: Official Kotlin logos for both light and dark modes
 - **JetBrains Fonts**: Uses Inter for sans-serif and JetBrains Mono for code
 - **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
 
@@ -42,6 +43,77 @@ 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` modifier
+uses the Gradle icon. `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;
+}
+
+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`.
+
 ### Using Kodee Mascot
 
 Enable Kodee once for the whole deck with `themeConfig`:
@@ -129,6 +201,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 +251,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 +292,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 +311,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 +323,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.
+
+```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
 
-<!-- TODO: Add test setup and instructions -->
+# 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