slidev-theme-kotlin 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 ## Unreleased
 
+### Removed
+
+- The three Kotlin logo files under `public/`: nothing in the theme referenced them, and the README no longer lists them as a feature.
+
+### Fixed
+
+- The text on `cover` and `intro` slides no longer runs under the featured Kodee: the layouts keep it in a column of `--cover-text-width` (48% of the content box by default, clear of the mascot's arm) and wrap it there. The showcase's own cover subtitle, intro bullets, and closing title had been partly hidden behind the mascot since the deck was written. A deck widens the column from its stylesheet, or sets `100%` on the class of a slide that hides the mascot.
+- `SmartCast` and `Warning` follow the colour scheme: in dark mode the token background is Darcula's smart-cast green (`#294436`) and warning olive (`#52503a`) instead of the IntelliJ Light tints, which left Darcula's grey code nearly unreadable on a pastel bar, and the messages brighten to `#7bc47f` and `#d4b44a`. The same variables (`--smart-cast-color`, `--warning-color`, and the `-message-color` pair) still override both schemes, as `TypeHint` already did.
+
+## 0.13.0
+
+### Added
+
+- `InlineCompilerError` underlines a diagnostic that spans several lines: `\n` in `text` (or a real newline in a bound string) continues the match on the next source line, indentation included, every line of the match gets its own squiggle, and the message sits after the line the match starts on, as IntelliJ places its inline diagnostics. `line` then names the first line of the match. `SmartCast` and `DrawnAnnotation` accept the same `\n` in `text`.
+- `DrawnAnnotation` takes `line`, like `InlineCompilerError` and `SmartCast`: the one-based source line of a code block to search `text` on, with `occurrence` counted on that line only. A repeated token is reached by naming its line instead of counting its occurrences. A slide with several code blocks numbers each from one, and a match never straddles two blocks.
+- The text search the three components share lives in `code-text-match.ts`: one segmenter for static Shiki and Magic Move blocks that stamps every segment with its source line, line-scoped and multi-line matching, the trimmed range of a line, and the merge of a range's client rects into visual lines. `InlineCompilerError` and `SmartCast` no longer carry their own copies, and the module has unit tests.
+- `Warning` paints IntelliJ's warning yellow (`#faf4d7`, `--warning-color`) behind an exact piece of code, for the `Array` property of a data class or a parameter nobody reads. It takes `SmartCast`'s props (`text`, `line`, `occurrence`, `at` / `until` / `on`) and follows Magic Move the same way. An optional `message` sits after the end of the match's first line, where `InlineCompilerError` puts its diagnostics, in `--warning-message-color` and `--warning-message-size`; `SmartCast` accepts the same `message`. The mechanism both share now lives in `code-highlight.ts`, and each component only names its class and colours. The Kotlin snippet CLI keeps generating a fence under `Warning`, unlike one under `InlineCompilerError`.
+- `InlineCompilerError`, `Warning`, and `SmartCast` render `message` as the same safe Markdown as a `DrawnAnnotation` label: `` `Int` `` is inline code in the mono stack, `\n` breaks the line as before, and HTML stays escaped. `annotation-label-markdown.ts` now renders all four, and the label CSS moved from `DrawnAnnotation`'s scoped styles into the theme stylesheet so every component shares it.
+- `TypeHint` draws IntelliJ's inlay hint for a lambda with receiver: the grey `this: HTML` pill after the `{` on `line`, for DSL slides. `text` defaults to `{`, `receiver` names the type, `context` instead renders a `context(...)` block's hint as `context(Clock)` without `this:`, and the click props are `SmartCast`'s. It is the shared `code-highlight.ts` mechanism with painting turned off (`highlightClass` is now optional), so the pill follows Magic Move the way a `Warning` message does and sits after the line's last token when code follows the brace. Colours and size come from `--type-hint-color`, `--type-hint-background`, and `--type-hint-size`, with Darcula values under `html.dark`.
+- A ```` ```console ```` fence renders as program output instead of a second editor window: a flat panel in the colours of IntelliJ's Run tool window (`--code-window-output-background`, `--code-window-output-color`, with new-UI dark values under `html.dark`), without the editor's outline and shadow, marked with the green run icon (`run.svg`) where a Kotlin fence shows its logo. Shiki's shell-session colouring is neutralised so output is one colour. Decks that already put a `console` fence under their Kotlin fences get the panel without a slide change.
+- `InlineValue` draws IntelliJ's debugger inline value: the grey `numbers: [1, 2, 3]` after the line named by `text` (and `line` / `occurrence`), for output slides where each line has its own result. `value` is shown as written, and the click props are `SmartCast`'s. It is the shared `code-highlight.ts` mechanism with painting turned off, like `TypeHint`, in the code font at the code's size; `--inline-value-color` and `--inline-value-size` restyle it.
+- `themeConfig.drawnAnnotation.connect: false` hides every `DrawnAnnotation` leader line in a deck, for decks that place their labels by hand; a slide's `drawnAnnotation.connect` frontmatter overrides the deck and a tag's `:connect` binding overrides both. The editor's **Hide connector** / **Show connector** toggle knows that default: it writes `:connect="true"` or `:connect="false"` only where the wanted state differs from it, and removes the binding when it matches. The source writer accepts `connect: null` to remove the binding; it owns that binding next to `:geometry`, and a tag's locator ignores both. The routing and curve controls are disabled while the connector is hidden.
+- Folded imports: a leading block of `import` lines in a Kotlin, Java, or Scala fence leaves the code window on the slide, on ordinary fences, cross-slide Magic Move chains, and classic Magic Move blocks alike. Line numbers, highlight ranges, and annotation targets count from the first line of real code. `show-imports` on a fence or `themeConfig.foldImports: false` keeps imports visible. A `// Example` comment line (optionally `// Example: description`) folds everything above it instead, helper declarations included; the marker line leaves the slide too. The handout, `llms-full.txt`, and generated Kotlin sources keep the fence complete.
+- Static content on every `slidev build`: a crawlable `handout/` (one page per source file, with highlighted code, Open Graph tags, the deck's `lang`, and links back to each slide), `llms.txt` and `llms-full.txt`, plus `sitemap.xml` when `themeConfig.siteUrl` is set and `robots.txt` when that URL is the root of its host (elsewhere the build prints the `Sitemap:` line to add to the host's own `robots.txt`). Slide headings sit below their slide's title, so the handout and `llms-full.txt` read as one outline. The built `index.html` links to the handout and `llms-full.txt` (`rel="alternate"`, a paragraph of visible links that the app hides once mounted, a plain-text description in place of Slidev's, and the canonical URL and sitemap once `siteUrl` is known), so crawlers that render no JavaScript find the content from the root URL. `themeConfig.handout: false` disables it; `handout.notes: false` leaves presenter notes out.
+- `slidev-kotlin-snippets`, a CLI that writes one compilable Kotlin file per Kotlin fence of a deck (in the spirit of KotlinX Knit): each file gets its own package, the fence's imports plus the `themeConfig.snippets.imports` a deck shares, top-level declarations as written, and bare statements wrapped in `suspend fun main()`. `--check` fails when the files are stale, for CI. `no-compile` on a fence skips it, as does an `InlineCompilerError` wrapper; the flag is stripped from the rendered fence like `show-imports`, whether or not imports fold. `@slidev/parser` and `jiti`, which the CLI runs on, are now dependencies of the theme.
+- Java fences now generate compilable `.java` files under `themeConfig.snippets.javaDir` (default `src/main/java/snippets`). Java and Kotlin fences on the same slide use the same generated package so interop examples compile together. A later slide of the same section that declares a public type an earlier slide already declared (two interop slides each showing `public class Person`) gets a directory named after the slide, `Person.java` inside, instead of a numbered file javac rejects.
+- GoatCounter analytics: `themeConfig.analytics.goatcounter` (an endpoint or a site code) adds `count.js` to the built deck and its handout pages, and the theme sends one pageview per slide (`<base>/<slide number>` with the slide's title) instead of one per load, skipping clicks, presenter, overview, notes, print, and export views.
+- Hash-mode builds (`slidev build --router-mode hash`) get a script forwarding old history-mode deep links such as `/deck/12` to `/deck/#/12`, so links shared before the switch keep working on hosts without a single-page-app rewrite.
+- Development-only problem chips: while Vite serves the deck, a `DrawnAnnotation` whose `text`, `selector`, `occurrence`, or `target` matches nothing, an `InlineCompilerError` whose diagnostic is not shown, and a `SmartCast`, `Warning`, `TypeHint`, or `InlineValue` whose `text` is not found, put a red chip in the top-left corner of their slide next to the console warning they already print. The chip follows the warning's timing (current slide, settled, click reached), withdraws when the target turns up, and never appears in builds, exports, the presenter view, or print mode. `InlineCompilerError`'s console warnings now gate on Vite's explicit development mode like `DrawnAnnotation`'s editor, instead of `import.meta.env.DEV`.
+- Annotation editing is a frozen session: entering the editor locks Slidev navigation (shortcuts, click-to-navigate, nav controls, swipes) on the current slide and click, every drag and arrow-key nudge stays a local draft, and **Done editing annotations** commits all changed drafts in one write phase; a failed write keeps the drafts and the session. **Esc** cancels in stages (drag, selection, then the session after a confirmation).
+- Quadratic connector editing: the first edit of an automatic leader keeps its visible curve as a persisted control point, which renders as a draggable, keyboard-nudgeable handle with a dashed control-polygon guide. **Curve connector** and **Straighten connector** add or remove the control point from the toolbar, and the connector's hit target follows the rendered curve.
+- **Reset slide** in the editor toolbar removes the saved geometry of every annotation on the current slide, after a confirmation.
+
+### Fixed
+
+- `DrawnAnnotation` settles only on the slide on screen when it mounts. Slidev mounts every slide of the deck, and a whole-show remount mounts them all again, so each annotation walked the document's running animations twice at mount time for slides nobody was looking at — on a deck with a few hundred annotations, that many document-wide walks per remount. Becoming current settles as before.
+- `DrawnAnnotation` marks on text are trimmed to the font's ink, cap height to descender, instead of the line's full content area. JetBrains Mono reserves 1.32em per line while its glyphs span about 0.9em, so a mark drawn from the text rect floated away from the letters and, in a code block, into the neighbouring lines; automatically placed labels and routed leaders measure from the trimmed box too, so they sit a little closer to the code.
+- A committed annotation draft is dropped once Slidev has recompiled the Markdown that holds it. The commit re-seeded the draft with what the writer saved, and nothing ever cleared it, so a later hand edit of the tag's `:geometry` binding stayed invisible in the browser and **Reload saved geometry** asked to discard changes that were already saved.
+- The static handout and `llms-full.txt` translate `SmartCast`, `Warning`, `TypeHint`, and `InlineValue` into notes, as they already did `DrawnAnnotation` and `InlineCompilerError`. The four fell through to the generic tag strip, which cannot cross the `<` of a generic inside an attribute, so `<Warning text="names: List<String>">` left half a tag in the prose; a `message` or `value` was dropped either way.
+- The JDBC and R2DBC code-window badges read `--font-sans`, which Slidev's UnoCSS preset never defines, and rendered in the browser's generic sans-serif; they read `--slidev-font-sans`. The slide's bottom rule hard-coded a purple one shade off the theme primary and now uses `--slidev-theme-primary`.
+- A `console` fence inside a cross-slide Magic Move chain renders as the output panel like a static one; the panel's rules only matched the class on a static fence's `<code>`, not the one the chain transformer puts on the wrapper.
+- `scripts/lint-slides.mjs` calls `@slidev/parser`'s `load` with its current signature and registers the theme's preparser, so a deck with root-absolute `src:` entries lints and chain slides' frontmatter is read as written; `scripts/visual-review.mjs` looks for the kotlin-fundamentals deck next to the theme instead of at an old path.
+- `Kodee`'s unknown-variant warning gates on Vite's explicit development mode like every other development-only message.
+- The npm tarball no longer ships the theme's test files.
+- `Warning` and `SmartCast` no longer eat the last glyph of a token when a match spans several Shiki tokens: each painted token reached `0.15em` into its neighbour through a negative margin, and the later token's background painted over the earlier one's text (`println` read `printlr`, `String?` read `Strinq`). The highlight now sits flush with the text and square, as IntelliJ paints it, so adjacent tokens join into one bar.
+- `InlineCompilerError` resolves its target once per DOM state instead of once per animation frame, the way `DrawnAnnotation` already did: while Magic Move moves retained tokens, or a resize or font load moves boxes, the range found before is reused and only its client rects are read again; a replaced child or edited text drops it. The search itself was already cheap (tens of microseconds on a deck-sized code window), so this removes work rather than a visible stutter — on the kotlin-fundamentals deck a Magic Move step spends about 25 ms of scripting in the annotation components over its whole transition, and the frame a key press drops is spent in Slidev's navigation and Shiki's per-token measurements, not in the text search.
+- Kodee is drawn once for the whole slideshow, in a `global-bottom` layer that follows the current slide's `kodee` frontmatter, instead of once per slide. Under a slide transition such as `fade`, a per-slide mascot faded out with the old page while an identical one faded in with the new, a blink on every navigation; the deck-wide mascot stays put and only remounts (replaying its entrance) when the slide asks for a different picture, size or place. Print and export render the layer per printed slide; the overview and the presenter's next-slide preview keep a per-slide mascot. `Kodee` now takes `viewTransition` as a prop instead of reading the slide context, and the `kodee` value resolution lives in `kodee-props.ts`.
+- Cross-slide Magic Move renders through a renderer that gathers the running animations once per step instead of asking the browser once per token. Shiki's renderer waits for every token with `getAnimations()`, which the browser answers by walking every running animation in the document, so a window of 138 tokens with three transitions each cost about 50 ms of one frame; the theme's `BatchedMagicMoveRenderer` (a subclass of the public `MagicMoveRenderer`) brings that to about 5 ms. On the kotlin-fundamentals deck the longest frame gap on a chain step went from 134 ms to 67 ms and no keypress stalls for 100 ms any more.
+- Cross-slide Magic Move under a slide transition such as `fade`: the departing slide's copy of the code window is hidden for the length of the transition instead of cross-fading over the arriving window's morph, and the arriving window's box resizes from the first frame instead of after Shiki's default delay. The fade itself no longer touches the morphing window: Slidev's `fade` transitions the opacity of the whole slide root, so the window blinked out with the departing slide and faded back in halfway through its own animation. On a slide whose window is morphing, the root now stays opaque and only the content around the window cross-fades (the heading, annotations, Kodee, and any code window without a counterpart on the neighbouring slide); slides outside a chain fade as before. The README now recommends `fade` over `view-transition`, which makes Slidev 52 remount every preloaded slide whenever a click is followed by a slide change.
+- Cross-slide Magic Move ships its precompiled steps as plain JSON (`steps-json`) instead of an lz-string payload. The lz string was already compressed, so gzip could not shrink it, and every slide of a chain carries the whole chain: on the kotlin-fundamentals deck the 173 payloads made up 1.1 MB of the 1.7 MB the built deck's JavaScript transferred, where the same steps as entity-escaped JSON gzip to a third of that. `JSON.parse` is also about ten times faster than the decode was (10 ms against 100 ms for every payload of that deck), so `MagicMoveBetween` parses each instance's own copy instead of sharing decoded steps, which also keeps `syncTokenKeys`'s in-place key rewrites from leaking between the windows of a chain. `lz-string` is no longer a dependency of the theme.
+- The transformer highlights each step of a chain once per build or dev server instead of once per fence of the chain: every chain slide compiles all N steps, so a chain of N slides asked Shiki N² times, on every reload of a chain slide as well.
+- `DrawnAnnotation` labels and the `message` of `InlineCompilerError`, `SmartCast`, and `Warning` are rendered by a small renderer of their own instead of markdown-it. The parser and its linkifier were the largest thing the theme added to the browser bundle (88 KB of JavaScript, 35 KB gzipped), loaded by every slide with an annotation, to render a label of a few words. The subset is what labels used: paragraphs, `>` quotes, fenced code, backticked inline code, `**strong**` or `__strong__`, `*emphasis*` or `_emphasis_` (an underscore inside a word stays text), and `\n` line breaks, with embedded HTML escaped. What markdown-it also accepted and no label in the decks used is now plain text: lists, headings, links and bare URLs, thematic breaks, backslash escapes, and HTML entities. The output keeps markdown-it's shape, so the label CSS is unchanged too. markdown-it remains a build-time dependency for the static handout.
+- `DrawnAnnotation` imports only rough.js's generator, from `roughjs/bin/generator`, which is the copy Slidev's own `v-mark` already ships. `import rough from 'roughjs'` resolved to the library's separate bundled file, so built decks carried rough.js twice, together with the canvas and SVG renderers the component never uses.
+- Code-window icons moved from the theme's `public/` directory to `assets/code-window/` and the stylesheet references them relatively. `url('/kotlin.svg')` only worked in a deck that had copied the icons into its own `public/`: Slidev copies a theme's `public/` to `dist/theme/`, never to the root, and Vite does not apply `--base` to a root-absolute URL it cannot find in the deck's public directory. Vite now bundles the icons like the Kodee artwork (see 0.0.9).
+- `InlineCompilerError` skips its sync on slides that are not current. Every slide of the deck stays mounted, and each sync scanned the document's animations before checking whether anything was visible, so a whole-slideshow remount ran that scan once per diagnostic in the deck. Becoming current already schedules a full sync. `DrawnAnnotation` and `InlineCompilerError` also ask the document for its animations once per pass instead of once for the slide's subtree and once for the view transition's pseudo-elements, since the browser answers a subtree query by walking every animation in the document anyway.
+- `SmartCast`, `Warning`, `TypeHint`, and `InlineValue` coalesce mutation and resize observer bursts into one sync per frame, as `InlineCompilerError` does: a Magic Move step flips classes on every token in several batches, and each sync walked the block, wrote classes, and forced a layout for the message.
+- The theme's `index.html` opens connections to Google Fonts (`preconnect`) before the stylesheet Slidev links to is requested.
+- `@slidev/parser` and `@slidev/types` accept any 52.x release (`^52.19.1`) instead of one exact version. A deck on a newer Slidev otherwise installed a second parser, whose slide slicing the preparser then had to agree with.
+- The preparser no longer parses every slide's YAML to find slide boundaries; the boundaries come from the line scan, and Slidev parses the frontmatter itself right after.
+- The published package includes `global-bottom.vue`, which draws the deck-wide Kodee, and the new `index.html`.
+- The Shiki `v-mark` transformer and the development source transform skip fences and slide modules without a mark or an annotation before running their regexes; the static handout compiles its component regexes once.
+- `scripts/test-annotation-editor.mjs` finds its fixture slide by its label instead of a hard-coded page number, which a slide added above it kept moving; `scripts/visual-review.mjs` reads the base revision's archive with a buffer large enough for the repository.
+- `DrawnAnnotation` no longer re-searches the slide's text on every animation frame. While a Magic Move step or a slide transition moves the annotated text, the match found before the step is reused and only its client rects are read again; the search runs once per click, resize, or code-block mutation instead. The search itself no longer walks every text node's ancestors: an ignored subtree (the overlay, a token on its way out) is pruned once at its root. On a slide with three annotations over a cross-slide Magic Move this took the scripting of one navigation from about 150 ms to about 20 ms, most of which is Magic Move itself. Each measurement pass also reads the overlay's and the slide's client rects once, rather than once per coordinate conversion.
+- `DrawnAnnotation` registered two window `keydown` listeners per mounted annotation, in built decks too, so every key press on a large deck ran several hundred handlers. One listener now serves the annotations of an open edit session, and only while it is open.
+- `MagicMoveBetween` added its three `::view-transition-*` rules to the document once per code window; the windows of a chain now share one style element.
+- `InlineCompilerError` walked a Magic Move block one TreeWalker per token span on every mutation; it walks the block once.
+- `DrawnAnnotation` marks and `InlineCompilerError` diagnostics no longer redraw when Slidev rebuilds the slide they are on. Slidev's slideshow container changes shape on the first click after a view transition (and back on the next slide-to-slide navigation), which unmounts and remounts every loaded slide, so ink that was already on screen fell off the slide and animated in again on a click that changed nothing, and the slide being left rebuilt just before the browser snapshotted it. An instance that is unmounted while its ink is visible now hands that ink to the instance replacing it, through the same hand-off that already carries ink across a cross-slide Magic Move, and the replacement shows it complete in the same render pass, with no entrance animation. Ink that was not on screen before still animates in as usual.
+- The development-only **Edit annotations** launcher no longer appears in PNG exports: `slidev export` renders through a development server, and the launcher only hid itself for print media. It now also stays out of the presenter view.
+- A `DrawnAnnotation` tag that is byte-identical to one on another slide (the same `text` and `label`, as on the "before" and "after" slides of a cross-slide Magic Move chain) is editable again. The editor plugin used to receive slides only after Slidev had rendered their Markdown, so no line of the file could be found again and a tag was located by its identity alone, which such duplicates do not have. The plugin now runs ahead of Slidev's Markdown rendering, receives a slide as written, and locates a tag by the widest run of verbatim lines around it, which normally takes in the slide title; the identity fallback remains for a tag those lines cannot pin down.
+- The launcher drops keyboard focus after a click: Slidev ignores its shortcuts while a button is focused, so leaving the editor with **Esc** used to leave the arrow keys dead until the author clicked somewhere else.
+- A Kotlin `${...}` template reads as code, as IntelliJ shows it: the `${` and `}` take the escape colour that `$name` already had, and the expression between them the editor foreground. The grammar scopes the template as `meta.template.expression` with its own begin and end punctuation, and neither palette had a rule for those, so the whole template stayed string green while `$name` next to it turned blue. Both palettes now name the three scopes.
+
+### Changed
+
+- Default code windows to 80 monospace columns instead of 68. Decks keep overriding `--code-window-columns` from their stylesheet.
+- The annotation editor has no undo any more: the per-gesture history, its **Undo** button and **Cmd/Ctrl+Z** are gone. Re-drag what went wrong, or reset. A cancelled drag (Esc, or a pointer the browser interrupts) still snaps back to where it started.
+- The editor toolbar's **Reset label** and **Reset label & connector** buttons are replaced by one **Reset annotation**, which removes the selected tag's whole `:geometry` binding; **Use automatic connector** is the one way back to the automatic route and removes the whole `connector` geometry, control point included. Resets, **Use automatic connector**, **Straighten connector** on a saved control point, and the connector toggle write immediately, since a draft cannot remove saved geometry.
+
 ## 0.12.1
 
 ### Fixed

package/README.md

@@ -11,7 +11,6 @@ This theme provides a professional presentation template tailored for Kotlin dev
 - **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**: 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
@@ -45,14 +44,36 @@ export default defineConfig({
 })
 ```
 
-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.
+Click the theme's **Edit annotations** launcher (or press **Alt+Shift+A**) to start a frozen
+edit session on the current slide and click state: Slidev navigation — arrow
+keys, space, page keys, click-to-navigate, swipes — is paused until you leave
+the editor. Drag a visible label, its width handle, or a connector control, or
+nudge the selected control with the arrow keys (**Shift** for larger steps);
+every change stays a local draft, so nothing is written mid-gesture. **Done
+editing annotations** commits all changed drafts as normalized `:geometry`
+bindings on exactly the edited `DrawnAnnotation` tags, then exits. **Esc**
+cancels in stages — an active drag, then the selection, then (after a
+confirmation) the whole session, discarding its drafts. One toolbar control
+hides or shows the connector (writing `:connect` into the tag where the
+deck's default differs, see `themeConfig.drawnAnnotation.connect`), one
+switches it between manual and automatic routing, another curves or
+straightens it with a draggable quadratic control point, and **Reset
+annotation** or **Reset slide** removes the saved geometry of one annotation
+or of every annotation on the slide. Source revisions are checked, so a
+conflicting commit fails without overwriting anyone: the drafts stay visible,
+and you either fix and press Done again or choose **Reload saved geometry** to
+discard them. The locator, toolbar, and write endpoint exist only while Vite
+serves the deck; builds and exports render saved geometry without editor code.
+
+While serving, an annotation that cannot find what it should mark (a `text`
+that no longer matches the fence, an unmatched `selector` or `target`, an
+`occurrence` past the last match, or an `InlineCompilerError`, `SmartCast`, `Warning`,
+`TypeHint`, or `InlineValue` whose target is not found) also puts a red chip in the top-left corner of its slide, next to
+the warning it prints on the console. Hover the chip for the full message. The
+chip appears only once the annotation's click has been reached and the slide
+has settled, so a Magic Move step that does not yet contain the text never
+flags one, and it disappears again when the target turns up. Builds, exports,
+the presenter view, and print mode never render it.
 
 ### Basic Setup
 
@@ -61,7 +82,7 @@ Add the theme to your slides' frontmatter:
 ```yaml
 ---
 theme: kotlin
-transition: view-transition
+transition: fade
 ---
 
 # Your Presentation Title
@@ -101,6 +122,28 @@ or `r2dbc` modifier uses the Gradle, JDBC, or R2DBC identity respectively.
 Terminal, Maven, and PostgreSQL icons respectively. All other fences remain plain
 code surfaces.
 
+A `console` fence is program output, not code: it renders as a flat panel in
+the colours of IntelliJ's Run tool window, without the editor's outline and
+shadow, marked with the green run icon. Put it under the Kotlin fence whose
+output it shows:
+
+````md
+```kotlin
+println([1, 2, 3].map { it + 1 })
+```
+
+```console
+[2, 3, 4]
+```
+````
+
+To show a value next to the line that produces it instead, as the debugger
+does, wrap the fence in [`InlineValue`](components/README.md#inlinevalue).
+The other IntelliJ decorations have a component each: [`SmartCast`](components/README.md#smartcast)
+paints the green smart-cast background behind exact code, [`Warning`](components/README.md#warning)
+the yellow warning background with an optional message, and [`TypeHint`](components/README.md#typehint)
+the grey `this: HTML` inlay hint after a lambda's brace.
+
 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:
@@ -116,19 +159,81 @@ value:
   --code-window-postgresql-color: #336791;
   --code-window-jdbc-color: #f59e0b;
   --code-window-r2dbc-color: #06b6d4;
+
+  /* The `console` output panel. */
+  --code-window-output-background: #f7f8fa;
+  --code-window-output-color: #2b2d30;
 }
 
 html.dark {
   --code-window-kotlin-color: #a571e6;
+  --code-window-output-background: #1e1f22;
+  --code-window-output-color: #bcbec4;
   /* Override any of the other dark-mode values as needed. */
 }
 ```
 
+### Folded imports
+
+A snippet on a slide reads best without its imports, but a snippet that
+carries them is complete: it compiles as written, a snippet checker such as
+Knit can verify it, and the deck's handout (see below) shows a reader which
+package every symbol comes from. So write the imports, and the theme folds
+them away:
+
+````md
+```kotlin
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.flowOf
+
+fun numbers(): Flow<Int> = flowOf(1, 2, 3)
+```
+````
+
+On the slide, the code window shows only `fun numbers()…`; the handout and
+`llms-full.txt` print the fence in full.
+
+When an example needs more than imports — a table definition, a helper the
+example calls — put a `// Example` comment where the example starts.
+Everything above it leaves the slide, and so does the marker line itself:
+
+````md
+```kotlin
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.flowOf
+import kotlinx.coroutines.flow.map
+
+fun numbers(): Flow<Int> = flowOf(1, 2, 3)
+
+// Example: reuse the flow above without showing it
+fun doubled(): Flow<Int> = numbers().map { it * 2 }
+```
+````
+
+The window shows `fun doubled()…`. The comment is ordinary Kotlin, so the
+fence still compiles as written (see the snippet checker below), and the
+handout keeps it. A description after the colon is optional.
+
+Details:
+
+- Kotlin, Java, and Scala fences (`kotlin`, `kt`, `kts`, `java`, `scala`)
+  fold. Without a marker, only a block of `import` lines at the top of the
+  fence counts, and a `package` line or `@file:` annotation before it stays
+  visible. With a marker, everything above it folds. Only the first
+  `// Example` line in a fence counts, and only when there is code above it.
+- Line numbers, `{1|2-3}` highlight ranges, and annotation targets all
+  count from the first line of real code, so folding never shifts them.
+- Cross-slide Magic Move chains and classic ````md magic-move```` blocks fold
+  too, step by step.
+- Add `show-imports` to a fence (`` ```kotlin show-imports ``) when the slide
+  is about the imports themselves, or set `themeConfig: { foldImports: false }`
+  in the headmatter to keep every import visible.
+
 ### 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:
+default, a full-width window fits 80 monospace characters. Override the column
+count once in the deck's stylesheet, or narrower on a single slide class:
 
 ```css
 :root {
@@ -139,7 +244,13 @@ count once in the deck's stylesheet:
 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`.
+explicit `--code-window-font-size`, for example `1.25rem`. The font's advance
+width and the line height the calculation assumes are
+`--code-window-character-width` (`0.61`, JetBrains Mono's) and
+`--code-window-line-height` (`1.42`); a deck on another monospace font sets the
+first to that font's ratio. The editor surface itself reads `--editor-bg`,
+`--editor-fg`, `--editor-border`, and `--editor-shadow`, and one window's
+border colour can be overridden with `--code-window-border`.
 
 ### Magic Move between slides
 
@@ -176,9 +287,16 @@ Details:
   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.
+- With a slide transition such as `fade`, the departing slide's copy of the
+  window is hidden for the length of the transition, so only the arriving
+  window is visible while its tokens morph and its box resizes to the new
+  code. Prefer `fade` over `view-transition`: with `transition:
+  view-transition`, Slidev 52 switches its slideshow container between a
+  `div` and a `TransitionGroup` whenever a click is followed by a slide
+  change, which remounts every preloaded slide of the deck and stalls the
+  frame for 150 ms or more on each such navigation. If you do use
+  `view-transition`, the code windows of both slides are paired through the
+  View Transitions API instead.
 - 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]`
@@ -221,6 +339,18 @@ kodee:
 ---
 ```
 
+On `cover` and `intro` slides the text sits in a column beside the featured
+mascot and wraps inside it instead of running under Kodee. The column is
+`--cover-text-width`, 48% of the content box by default, which clears the
+mascot's arm. Widen it in the deck's stylesheet when the titles are short, or
+give a slide that hides the mascot the full width:
+
+```css
+.slidev-layout.cover.no-mascot {
+  --cover-text-width: 100%;
+}
+```
+
 #### Kodee Configuration Options
 
 - **variant**: Choose from available Kodee images
@@ -246,6 +376,8 @@ kodee:
   - `featured` - Prominently displayed (cover/intro default)
   - `custom` - Use with `x` and `y` coordinates
 
+- **scale**: Multiply the size, `1.2` for a fifth larger. Defaults to `1`.
+
 #### Custom Positioning
 
 For precise control, use custom positioning:
@@ -263,7 +395,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. Labels accept safe Markdown: backticked inline code and `>` quotes use the local-first JetBrains Mono stack.
+`<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 a small, safe Markdown subset (backticked inline code, `>` quotes, `**strong**` or `__strong__`, `*emphasis*` or `_emphasis_`, and line breaks; HTML is escaped): inline code and quotes use the local-first JetBrains Mono stack.
 
 ````md
 <DrawnAnnotation type="circle" text="fun main" label="program entry point" :on="1">
@@ -313,6 +445,167 @@ theme: kotlin
 
 The theme's example deck includes this guard.
 
+## Static handout, `llms.txt`, and hash-mode links
+
+A Slidev build is a single-page app: without JavaScript its `index.html`
+contains nothing but the title. Search engines render JavaScript for the root
+URL at best, and AI crawlers (GPTBot, ClaudeBot, CCBot, …) render none, so the
+code on your slides never reaches them. Every `slidev build` on this theme
+therefore also writes, next to the app:
+
+- `handout/index.html` and `handout/<section>.html` — one page per source
+  file (`src:` lesson), with every slide's title, prose, and highlighted code,
+  each linking back to the live slide. A single-file deck gets one page.
+- `llms.txt` and `llms-full.txt` — the [llmstxt.org](https://llmstxt.org)
+  convention that coding agents and AI crawlers look for: an index, and the
+  full Markdown of the deck with complete code snippets (folded imports
+  expanded).
+- `sitemap.xml` — only when the deck's public URL is known.
+- `robots.txt` — only when that URL is the root of its host and `public/`
+  ships none. Crawlers read `robots.txt` at the host root alone, so a deck
+  served from a sub-path (a GitHub project page, a folder of your blog) gets
+  no file; add `Sitemap: <siteUrl>sitemap.xml` to the host's own
+  `robots.txt` instead, as the build reminds you.
+
+The handout and `llms-full.txt` form one outline: the deck, then each
+section, then each slide, with a slide's own headings placed below its
+title. The handout pages carry a description, canonical URL, Open Graph
+tags, and the deck's `lang` from the headmatter (`en` when unset).
+
+The built `index.html` (and the `404.html` copied from it) is made
+self-describing too: `rel="alternate"` links to the handout and
+`llms-full.txt`, a plain-text `<meta name="description">` from the headmatter
+`info` (replacing the one Slidev renders from the raw Markdown), and a short
+paragraph linking to the same files as visible text, hidden as soon as the
+app has mounted. That paragraph is ordinary markup rather than `<noscript>`,
+which many text extractors drop, so a crawler that renders no JavaScript
+still finds the content from the root URL. With `siteUrl` set the page also
+carries the canonical URL and a `rel="sitemap"` link.
+
+Theme markup is translated, not dropped: a `DrawnAnnotation` with a `label`
+becomes a quoted note about the code it points at, an `InlineCompilerError`
+becomes its diagnostic, Magic Move blocks become their steps, and
+`<<< @/file#region` snippet imports are inlined.
+
+Give the deck its public URL so links, the sitemap, and `llms.txt` are
+absolute, and opt out of notes or the whole feature if you need to:
+
+```yaml
+themeConfig:
+  siteUrl: https://example.github.io/my-deck/
+  handout:
+    notes: false   # leave presenter notes out (default: included)
+  # handout: false # disable the static content entirely
+```
+
+## Analytics
+
+Decks can count pageviews with [GoatCounter](https://www.goatcounter.com),
+which sets no cookies and stores no personal data, so it needs no consent
+banner. Give the headmatter the endpoint of your GoatCounter site, or just
+its code:
+
+```yaml
+themeConfig:
+  analytics:
+    goatcounter: https://mysite.goatcounter.com/count   # or: mysite
+```
+
+Every `slidev build` then adds `count.js` to the deck, and the theme sends
+one pageview per slide, recorded as `<base>/<slide number>` with the slide's
+title, so the dashboard's path list doubles as a per-slide drop-off curve.
+Clicks within a slide, the presenter and overview views, notes, print, and
+export are never counted. Handout pages carry the tag too and count under
+their own URL. `slidev dev`, exports, and screenshots send nothing:
+`count.js` ignores localhost and headless browsers by itself.
+
+Every deck on one host can share one GoatCounter site, since paths carry the
+deck's base. Add `#toggle-goatcounter` to a deck's URL to stop counting your
+own visits in that browser.
+
+## Compiling the snippets
+
+A Kotlin fence on a slide is a fragment: it carries its imports (folded away,
+see above) but no package, and it may mix declarations with bare statements.
+`slidev-kotlin-snippets` turns Kotlin and Java fences into source files, in the
+spirit of [KotlinX Knit](https://github.com/Kotlin/kotlinx-knit), so a Gradle
+module can compile the deck's code against the real libraries and a stale slide
+fails the build instead of the talk.
+
+Turn it on in the headmatter and run the CLI from the deck:
+
+```yaml
+themeConfig:
+  snippets:
+    dir: src/main/kotlin/presentation/snippets   # default: src/main/kotlin/snippets
+    javaDir: src/main/java/presentation/snippets  # default: src/main/java/snippets
+    package: presentation.snippets               # default: snippets
+    imports:                                     # added to every file
+      - presentation.support.*
+```
+
+```bash
+npx slidev-kotlin-snippets            # writes the files, removes stale ones
+npx slidev-kotlin-snippets --check    # exits 1 when they are out of date (CI)
+npx slidev-kotlin-snippets talk.md    # another entry than slides.md
+```
+
+Each Kotlin fence becomes `<dir>/<section>/<slide>-<title>.kt`; each Java
+fence becomes `<javaDir>/<section>/<slide>-<title>.java`. Files have a package,
+`<package>.<section>.slide<n>`, so every step of a Magic Move chain can declare
+its own `object Talks`. A Java and Kotlin fence on the same slide deliberately
+share that package, allowing Java ↔ Kotlin interop examples to compile. Inside
+the file:
+
+- the fence's imports come first, after the `imports` from the config. Keep
+  the tables, types, and values the slides use without defining them in a
+  hand-written package and star-import it; a fence that defines its own
+  `Talks` shadows the shared one, because a declaration in the file's own
+  package wins over a star import.
+- Kotlin top-level declarations (`fun`, `val`, `object`, `class`, ... with
+  their annotations, modifiers, and `context(...)` lines) stay top-level, and
+  bare statements such as `Talks.selectAll()` are wrapped in `suspend fun main()`.
+  A Kotlin `package` line is dropped; `@file:` annotations move above the package.
+- Java fences are emitted as Java compilation units with the generated package
+  and imports; they must therefore contain declarations rather than bare
+  statements. Their own `package` line is replaced. A fence declaring a public
+  top-level Java type is named after that type (as Java requires); otherwise it
+  uses the slide-based filename. When a later slide of the same section declares
+  a public type an earlier slide already declared, its file goes in a directory
+  named after the slide, so both compile.
+- a slide with several fences in the same language tells them apart by their
+  first meta word (`jdbc`, `r2dbc`) or a letter.
+
+Not every fence is meant to compile. Add `no-compile` to a fence that sketches
+library internals or an intermediate step (`` ```kotlin no-compile ``); the flag
+is stripped before Slidev sees it. Fences inside an `InlineCompilerError` are
+skipped automatically, since the slide shows the diagnostic on purpose, and so
+are `gradle` build-script fences.
+
+Wire it into Gradle so `./gradlew check` also fails on stale sources:
+
+```kotlin
+val snippetsCheck by tasks.registering(Exec::class) {
+    commandLine("npx", "slidev-kotlin-snippets", "--check")
+}
+tasks.check { dependsOn(snippetsCheck) }
+```
+
+### Deep links on GitHub Pages
+
+GitHub Pages has no single-page-app rewrite, so a history-mode deep link such
+as `/my-deck/12` is answered by the copied `404.html` with a 404 status. Build
+with Slidev's hash router instead:
+
+```bash
+slidev build --base /my-deck/ --router-mode hash
+```
+
+Links then look like `/my-deck/#/12` and always resolve. The theme adds a small
+script to hash-mode builds that forwards old `/my-deck/12` links (and
+`presenter/…`, `overview`, `notes`, `print`, `export`) to their hash
+equivalent, so links shared before the switch keep working.
+
 ## Development
 
 ### Available Scripts
@@ -370,20 +663,44 @@ This will open the example presentation in your browser with hot-reload enabled.
 .
 ├── components/                   # Vue components
 │   ├── DrawnAnnotation.vue        # Hand-drawn marks, labels, and connectors
+│   ├── DrawnAnnotationEditor*.vue # Development-only editor launcher and toolbar
+│   ├── DrawnAnnotationProblems.vue # Development-only problem chips
+│   ├── drawn-annotation/          # Editor store, geometry, and browser writer
 │   ├── InlineCompilerError.vue    # Inline code diagnostics
+│   ├── SmartCast.vue              # Smart-cast background behind exact code
+│   ├── Warning.vue                # Warning background with an optional message
+│   ├── TypeHint.vue               # Inlay hint after a lambda's brace
+│   ├── InlineValue.vue            # Debugger inline value after a line
+│   ├── code-highlight.ts          # The mechanism the four above share
+│   ├── code-text-match.ts         # Text search shared with DrawnAnnotation
+│   ├── MagicMoveBetween.vue       # Cross-slide Magic Move code window
 │   ├── 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
+├── global-top.vue       # Development-only editor toolbar and problem chips
+├── global-bottom.vue    # Deck-wide Kodee layer that follows the current slide
+├── slide-bottom.vue     # Per-slide Kodee for the overview and presenter preview
+├── plugins/             # Development-only source writer (`slidev-theme-kotlin/annotation-editor`)
+├── bin/                 # `slidev-kotlin-snippets` CLI
 ├── layouts/            # Slidev layout templates
 │   ├── cover.vue       # Cover slide layout
 │   ├── default.vue     # Default slide layout
 │   └── intro.vue       # Introduction slide layout
 ├── assets/             # Bundled theme assets
-│   └── kodee-*.svg     # Kodee mascot variants (11 variants)
-├── public/             # Static assets
-│   └── kotlin-logo*.svg # Kotlin logos (light/dark modes)
+│   ├── kodee-*.svg     # Kodee mascot variants (11 variants)
+│   └── code-window/    # Code-window identity icons, referenced from layout.css
+├── index.html          # Head tags merged into every deck (font preconnect)
 ├── setup/              # Slidev setup files
-│   └── shiki.ts        # Syntax highlighting configuration for Kotlin
+│   ├── main.ts         # App setup: per-slide analytics pageviews
+│   ├── preparser.ts    # The bare `magic-move` slide separator
+│   ├── shiki.ts        # Syntax highlighting configuration for Kotlin
+│   ├── transformers.ts # Cross-slide Magic Move and import folding passes
+│   ├── magic-move-between.ts   # Precompiled Magic Move steps
+│   ├── analytics.ts    # GoatCounter tag and per-slide pageviews
+│   ├── code-imports.ts # Folded imports: fence scanning and source edits
+│   ├── kotlin-snippets.ts      # Compilable snippet files per fence
+│   ├── static-content.ts       # Handout, llms.txt, sitemap generation
+│   ├── hash-route-redirect.ts  # Old history-mode links → hash routes
+│   └── vite-plugins.ts # Registers the three build plugins above
 ├── styles/             # Theme styles
 │   ├── index.ts        # Style entry point
 │   └── layout.css      # Layout styles
@@ -407,7 +724,7 @@ capture every settled click state from Slidev's normal presenter/player 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
+`../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
@@ -453,8 +770,11 @@ The theme is configured with the following defaults in `package.json`:
     "colorSchema": "both",
     "defaults": {
       "fonts": {
-        "sans": "Inter",
-        "mono": "JetBrains Mono"
+        "sans": "JetBrains Sans,Inter",
+        "mono": "JetBrains Mono Local,JetBrains Mono",
+        "local": "JetBrains Sans,JetBrains Mono Local",
+        "weights": "400,700,800",
+        "italic": true
       }
     }
   }
@@ -483,7 +803,10 @@ layout: cover
 
 ### Runtime Dependencies
 - `@shikijs/magic-move` (4.4.3) - Code-token morphing for Magic Move
-- `@slidev/types` (52.19.1) - Slidev type definitions
+- `@slidev/parser` (^52.19.1) - Deck parsing for the snippets CLI and lint script
+- `@slidev/types` (^52.19.1) - Slidev type definitions
+- `jiti` (2.7.0) - Runs the theme's TypeScript setup modules from the CLI
+- `markdown-it` (14.3.0) - Renders the static handout
 - `roughjs` (4.6.6) - Hand-drawn SVG paths for `DrawnAnnotation`
 
 ### Development Dependencies
@@ -509,7 +832,7 @@ This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE
 
 - [Slidev Documentation](https://sli.dev)
 - [Kotlin Official Website](https://kotlinlang.org)
-- [Package on npm](https://www.npmjs.com/package/@nomisrev/slidev-theme-kotlin)
+- [Package on npm](https://www.npmjs.com/package/slidev-theme-kotlin)
 
 ---