slidev-theme-kotlin 0.0.9 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # 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
+
+- Bundle `DrawnAnnotation`, a click-aware, Rough.js-powered annotation component for marking elements or exact code text with circles, underlines, boxes, and strike-throughs.
+- Support leader lines, target marks, automatic non-overlapping labels, sequential nested reveals, temporary click ranges, and Magic Move-aware tracking.
+- Add complete component documentation and interactive examples to the theme showcase.
+
+### Packaging
+
+- Add `roughjs` as a runtime dependency required by `DrawnAnnotation`.
+
+## 0.0.10
+
+### Added
+
+- Allow decks to enable Kodee once with `themeConfig.kodee`. A shared per-slide layer supports every layout: regular slides use a small bottom-right mascot, while cover and intro layouts use a large featured mascot.
+- Support concise per-slide overrides such as `kodee: wink` and `kodee: false`, while retaining the full object configuration.
+- Implement the documented `medium` Kodee size.
+- Bundle `DrawnAnnotation`, a click-aware, Rough.js-powered annotation component for marking elements or exact code text with circles, underlines, boxes, and strike-throughs.
+- Support leader lines, target marks, automatic non-overlapping labels, sequential nested reveals, temporary click ranges, and Magic Move-aware tracking.
+- Add complete component documentation and interactive examples to the theme showcase.
+
+### Packaging
+
+- Add `roughjs` as a runtime dependency required by `DrawnAnnotation`.
+
 ## 0.0.9
 
 ### Fixed

package/README.md

@@ -12,6 +12,8 @@ This theme provides a professional presentation template tailored for Kotlin dev
 - **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
+- **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
 
@@ -41,9 +43,98 @@ 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
 
-Add Kodee to any slide by including the `kodee` configuration in the slide's frontmatter:
+Enable Kodee once for the whole deck with `themeConfig`:
+
+```yaml
+---
+theme: kotlin
+themeConfig:
+  kodee: greeting
+---
+```
+
+Kodee then uses layout-aware defaults: `small` in the bottom-right corner on regular slides, and `large`/`featured` on `cover` and `intro` slides. Override only the variant when a slide needs a different expression:
+
+```yaml
+---
+kodee: wink
+---
+```
+
+Use `kodee: false` to hide the mascot on one slide. The original object form remains available when you need complete control:
 
 ```yaml
 ---
@@ -52,8 +143,6 @@ kodee:
   size: large
   position: featured
 ---
-
-# Your Slide Content
 ```
 
 #### Kodee Configuration Options
@@ -72,13 +161,13 @@ kodee:
   - `tiny` - Tiny Kodee
 
 - **size**: Control Kodee's size
-  - `small` - 200x200px (default)
-  - `large` - 600x600px (500x500px for wave variant)
-  - `medium` - TODO: Not yet implemented
+  - `small` - 200x200px (regular-layout default)
+  - `medium` - 320x320px
+  - `large` - 600x600px (500x500px for wave variant; cover/intro default)
 
 - **position**: Control Kodee's placement
-  - `corner` - Bottom right corner (default)
-  - `featured` - Prominently displayed on slide
+  - `corner` - Bottom right corner (regular-layout default)
+  - `featured` - Prominently displayed (cover/intro default)
   - `custom` - Use with `x` and `y` coordinates
 
 #### Custom Positioning
@@ -96,6 +185,58 @@ 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.
+
+````md
+<DrawnAnnotation type="circle" text="fun main" label="program entry point" :on="1">
+
+```kotlin
+fun main() = println("Hello, Kotlin!")
+```
+
+</DrawnAnnotation>
+````
+
+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:
+
+```ini
+# .editorconfig
+[*.md]
+ij_formatter_tags_enabled = true
+```
+
+```md
+---
+theme: kotlin
+---
+
+<!-- @formatter:off -->
+```
+
+The theme's example deck includes this guard.
+
 ## Development
 
 ### Available Scripts
@@ -110,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:
@@ -128,9 +292,12 @@ 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
 │   ├── default.vue     # Default slide layout
@@ -144,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
@@ -156,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
+
+# 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:
 
-<!-- TODO: Add test setup and instructions -->
+```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
 
@@ -204,6 +407,7 @@ layout: cover
 
 ### Runtime Dependencies
 - `@slidev/types` (^52.2.5) - Slidev type definitions
+- `roughjs` (^4.6.6) - Hand-drawn SVG paths for `DrawnAnnotation`
 
 ### Development Dependencies
 - `@slidev/cli` (^52.2.5) - Slidev command-line interface