# CLAUDE.md

Guidance for Claude Code working in this repository. Keep this current
when the architecture shifts — out-of-date orientation is worse than no
orientation.

## Development Commands

Two tasks, defined in the workspace root `deno.json`:

- `deno task dev <source.md>` — Dev server on `:8000` with `--watch`,
  live-reload websocket, esbuild-bundled runtime served at
  `/static/bundle.js`. Reloads core changes via Deno's `--watch`;
  reloads the bundle by re-fetching on hard-reload (the bundle is
  rebuilt per request).
- `deno task build <source.md> [--output dist/]` — One-shot static
  build. Writes `<output>/index.html`. The build's mermaid renderer
  needs `--allow-net` because it talks to a headless Chrome via
  WebSocket; that's already in the task definition.

Both expect a path to a Markdown file.

## Workspace Layout

This is a Deno workspace with six packages. Each package has its own
`deno.json` and `README.md`. Cross-package imports use `@morkdeck/*`
specifiers resolved by the workspace root.

```
morkdeck/
├── deno.json                  workspace root, two tasks, root imports (lit, xstate)
├── examples/
│   └── showcase.md            the canonical demo deck; exercises every layout
└── packages/
    ├── cli/                   @morkdeck/cli — Cliffy commands
    │   ├── main.ts            entry: dev + build subcommands
    │   ├── dev.ts             delegates to @morkdeck/server
    │   └── build.ts           one-shot renderPresentationHtml + write file
    ├── core/                  @morkdeck/core — the render pipeline
    │   ├── renderer.ts        renderPresentationHtml(): Markdown → HTML
    │   ├── highlight.ts       dynamic Shiki language loader (AST walk)
    │   ├── mermaid.ts         headless Chromium pool + disk cache
    │   ├── layout.ts          slide-shape detection (title/focus/full/...)
    │   ├── icons.ts           inline SVG icon set (Tabler) for colophon socials
    │   ├── favicon.ts         per-deck color-hashed favicon generation
    │   ├── types.ts           RenderOptions, Includes
    │   └── templates/
    │       ├── presentation.eta    HTML shell
    │       └── partials/
    │           ├── favicon.eta
    │           ├── live-reload.eta
    │           └── slide-styles.eta   inline CSS for slotted slide content
    ├── runtime/               @morkdeck/runtime — xstate state machine
    │   ├── morkdeck.ts        bundle entry; imports @morkdeck/wc which
    │                          registers all custom elements
    │   └── actor/
    │       ├── types.ts       Context + Events + Tool + Stroke + ...
    │       ├── setup.ts       all xstate actions (assign reducers)
    │       └── machine.ts     wires actions to events, initial context
    ├── server/                @morkdeck/server — dev server
    │   └── dev.ts             Deno.serve + WebSocket live-reload +
    │                          esbuild bundle on demand
    ├── theme/                 @morkdeck/theme — design tokens
    │   ├── stylesheet.ts      compileCss() — Terrazzo CSS variable output
    │   ├── typescript.ts      TS helpers exporting token references
    │   └── tokens/            Terrazzo token JSON files
    └── wc/                    @morkdeck/wc — Lit web components
        ├── element.ts         MorkdeckElement base class (@subscribe decorator)
        ├── context.ts         @lit/context tokens for the xstate actor + IO
        ├── density.ts         density auto-fit (Tier 2): predicted heights
        └── components/
            ├── presentation/wc.ts   the big one: presentation host
            ├── slide.ts             individual slide; container queries
            ├── toolbar.ts           audience-mode toolbar
            └── qr.ts                <morkdeck-qr> via @levischuck/tiny-qr
```

## Render Pipeline (build-time)

`renderPresentationHtml(path, options?)` in `core/renderer.ts`:

1. **Frontmatter** — `extractFrontmatter()` peels off optional leading
   `---\n...\n---` YAML block, returns `{meta, body}` where `meta` is the
   typed `DeckMeta`.
2. **Comark parse** with the mermaid plugin only. The mermaid plugin
   rewrites `` ```mermaid `` fences into `<mermaid content="...">`
   elements; the highlight plugin is run separately (see below).
3. **highlightTree** (`core/highlight.ts`) — walks the parsed AST,
   collects every `<pre>`'s language attribute, normalizes aliases
   (`py` → `python`, `ts` → `typescript`, ...), dynamically imports
   only those Shiki language modules, then calls Comark's exported
   `highlightCodeBlocks`. A deck with one Python block doesn't pay for
   Rust/Go/SQL. Modules are cached across parses so the dev server
   pays each import cost once per process.
4. **Slide splitting** — the tree is split into groups on `<hr>`
   elements; each group becomes one slide.
5. **Layout detection** (`core/layout.ts`) — structural inference (no
   author-facing DSL):
   - `title` — first slide led by `h1`
   - `outro` — last slide containing only a single `h1`
   - `section` — heading-only mid-deck slide
   - `code-focus` / `diagram-focus` / `image-focus` — heading + lone
     media block, optionally with trailing blockquote (becomes
     `<figcaption>`)
   - `code-full` / `diagram-full` / `image-full` — no heading + lone
     media block (full-bleed variants of the above)
   - `two-column` — `:::columns` directive
   - `content` — default
6. **Component handlers** in `renderHTML()` emit final HTML for custom
   tags: `morkdeck-presentation`, `morkdeck-slide`, `columns`, `col`,
   `mermaid` (calls `renderMermaid` → SVG), and the colophon for
   title/outro slides (when meta is set).
7. **Eta template** wraps body in the HTML shell with the inline
   stylesheet (`compileCss()` from `@morkdeck/theme`), favicon, and
   live-reload script (dev only).

## Static Mermaid Rendering

`core/mermaid.ts` runs every `<mermaid>` source through a headless
Chromium pool (via `@astral/astral`) and inlines the resulting SVG
during render. This eliminates the runtime mermaid library entirely —
no client-side JS, no font race, no foreignObject measurement bugs.

- **Cache**: SHA-256 of (format | theme version | mermaid version |
  source). Stored per-machine under `%LOCALAPPDATA%\morkdeck\mermaid\`
  (Windows) or `~/.cache/morkdeck/mermaid/` (XDG / Unix). Cache hit
  skips Chrome entirely; typical incremental rebuilds spawn no
  subprocess.
- **Browser selection**: prefers a system-installed Chrome/Edge over
  Astral's bundled snapshot (which often fails to start on Windows
  due to missing VC++ runtimes). Honors `MORKDECK_CHROME_PATH` env
  var.
- **Error policy**: dev mode emits an inline `<div class="mermaid
  mermaid-error">` block showing message + source; build mode
  re-throws so the build bails.
- **Font handling**: the renderer page explicitly loads the deck's
  weights via `document.fonts.load('400 20px Recursive')` etc. before
  signaling ready — earlier versions had a measurement race where
  mermaid sized foreignObjects against a fallback font and labels
  later clipped when the audience painted with Recursive.
- **Cleanup**: `shutdownMermaidRenderer()` called from `cli/build.ts`
  in a `finally` block so the Chrome subprocess doesn't outlive a
  build.

## State Machine (xstate)

`runtime/actor/` defines a single xstate machine that drives both
audience and presenter modes. Two tabs share one machine *via the
cross-tab bridge* (see below), so navigation done in one tab plays out
in the other.

### Context (`actor/types.ts`)

Key fields beyond the obvious `currentIndex` / `slides`:

- `role: "audience" | "presenter"` — current tab's identity
- `presentationId` / `sessionId` — uuid pairs for tab matching
- `channel` — BroadcastChannel keyed off `presentationId`
- Drawing: `strokes` (per-slide), `cursor`, `laser`, `activeTool`,
  `penColor`
- Timer: `startedAt`, `countdownTargetMs`, `timerRunning`,
  `pausedElapsedMs`, `pausedAt`
- Overview: `overview: boolean` (per-tab UI; not relayed)
- Jump-back: `jumpReturnSlideId: string | null` (per-tab UI; cleared
  by `navigate.next`/`previous`; consumed by `navigate.jumpBack`)

### Events

Major event families:

- `navigate.*` — `next`, `previous`, `scroll` (IO-driven),
  `setReturn`, `jumpBack` (carries `slideId` so the audience tab can
  follow without a local return)
- `presentation.start` — initial registration
- `timer.*` — start, toggle, reset, setTarget
- `role.set` — flip between audience/presenter
- `overview.*` — toggle, set
- `draw.*` — stroke start/point/erase, clear, cursor, laser, tool,
  color

### Cross-Tab Bridge

`presentation/wc.ts` wraps `this.presentation.send` in a relay
function. Events in the static `#RELAYED_EVENTS` set are
`postMessage`'d to a BroadcastChannel keyed by `presentationId` before
being processed locally. A `suppressBroadcast` flag prevents echo
loops when the bridge receives a remote event and forwards it to
`originalSend`.

Currently relayed: navigation (`next`/`previous`/`scroll`/`jumpBack`)
and drawing events. Not relayed: role, timer, overview, drawing tool
selection — all per-tab UI state.

## Web Component Architecture

Three main custom elements registered by `@morkdeck/wc/mod.ts`
(imported transitively via the runtime bundle entry):

### `<morkdeck-presentation>`

The container. Provides the xstate actor via `@lit/context` so
descendants can consume it without prop drilling. Hosts the
audience-mode toolbar (slotted at host level) or the presenter
chrome (rendered into the shadow root template).

Layout switches based on host attributes:

- `data-role="presenter"` — grid layout with stage + sidebar + chrome
- `data-overview` — slide grid; audience version is host-level,
  presenter version wraps the slot in `.presenter-overview` so the
  chrome strip stays at the bottom
- presenter chrome stays clickable via
  `:host([data-role="presenter"]:not([data-overview])) ::slotted(...)
  { pointer-events: none }` — the `:not` makes the rule disengage
  in overview so slides become clickable

Drawing canvases live on each slide (see slide.ts); the presenter
has an additional transparent input-capture canvas overlaid on
`.stage`.

### `<morkdeck-slide>`

Container-query host for each slide. Shadow DOM `<section>` is the
16:9 letterbox (`width: min(100cqi, 100cqb * 16/9)`). Renders an
annotation `<canvas>` inside the section that the presentation's
render loop draws strokes/cursor/laser onto.

Sizing variables consumed from the cascade so the presentation can
override them in overview mode without `::slotted` specificity
fights:

- `--morkdeck-slide-host-height` (default `100%`, overview `auto`)
- `--morkdeck-slide-host-aspect` (default `auto`, overview `16/9`)
- `--morkdeck-slide-host-snap` (default `center`, overview `none`)

Density auto-fit (`wc/density.ts`) picks `roomy` / `balanced` /
`dense` per slide by predicting the total content height at each
tier using pretext text measurement (no DOM mutation per tier).

### `<morkdeck-toolbar>`

Audience-only toolbar at the bottom of the viewport. Buttons:
fullscreen, slide overview toggle, prev/next/counter, share (TODO),
presenter mode (opens new tab with `?role=presenter&uuid=...`).

### `<morkdeck-qr>`

QR code generator using `@levischuck/tiny-qr` +
`@levischuck/tiny-qr-svg`. Generates client-side from `document.URL`
(or an explicit `value` attribute) so the QR always points to where
the deck is actually being viewed. Used on the outro slide when
`qr: true` is in frontmatter.

## Frontmatter / Deck Metadata

Optional leading YAML in the source `.md`:

```yaml
---
event: Bryophyta Society Spring Meeting
date: May 2026
location: Portland, Oregon
speaker: Graham Barber
pronouns: he/him
handle: "@graham.systems"
avatar: https://.../avatar.jpg
qr: true                                    # or a fixed URL
links:
  github: gambarber
  bluesky: graham.bsky.social
  mastodon: "@graham@botany.social"
  website: grahambarber.com
---
```

The renderer:

- Reads `meta` once, threads through the title/outro slide handlers.
- Emits a marquee strip (top) and a colophon block on title slides
  with avatar + name + byline (pronouns + handle) + context line +
  social icons.
- The outro slide uses a two-column grid: wordmark left, colophon
  stack right, optional QR bottom-left.

URL generation for social platforms is per-platform (`socialHref` in
`renderer.ts`): GitHub → `github.com/handle`, Mastodon parses
`@user@host` → `https://host/@user`, website prepends `https://` if
missing, email becomes `mailto:`, etc. Extend the `SOCIAL_ICONS` map
in `core/icons.ts` and add a case to `socialHref` for new platforms.

## Slide Layouts

Detected structurally (no DSL); each gets specific CSS in `slide.ts`
(host-level) and `slide-styles.eta` (slotted content).

| Layout | Trigger | Notes |
|---|---|---|
| `title` | First slide led by `h1` | Marquee + wordmark + colophon |
| `outro` | Last slide, lone `h1` | Two-column with optional QR |
| `section` | Heading-only mid-deck | Centered headline |
| `content` | Default | Asymmetric editorial column |
| `code-focus` | Heading + lone code fence | Figure with code |
| `code-full` | No heading + lone code fence | Full-bleed code |
| `diagram-focus` | Heading + lone mermaid fence | Figure with SVG |
| `diagram-full` | No heading + lone mermaid fence | Full-bleed diagram |
| `image-focus` | Heading + lone image | Figure with image |
| `image-full` | No heading + lone image | `object-fit: cover` |
| `two-column` | `:::columns` directive | Two `:::col` children |

Caption (trailing blockquote on a focus/full slide) is rendered as
`<figcaption>` styled per-layout in `slide-styles.eta`.

## Presenter Mode

Opened via the audience toolbar's chalkboard icon — opens a new tab
with `?role=presenter&uuid=...`. The two tabs share the
BroadcastChannel; navigation events relay both directions.

Chrome strip at the bottom:
- Left: elapsed timer + optional countdown
- Center: prev / counter / next / **overview toggle** / **jump-back**
  (conditional)
- Right: countdown target input, timer toggle/reset, wall clock, exit

Keyboard shortcuts (presenter only, ignored when typing into the
target input):
- `Esc` — exit presenter (closes tab if opened via toolbar, else
  flips role.set to audience)
- `g` — toggle slide overview
- `b` — jump back to the slide the presenter was on before their
  last overview navigation (no-op if no return stored)

### Drawing Tools

Tool palette in the stage's top-right (pen / laser / eraser / clear).
Pen and laser use `lazy-brush` for smoothed strokes; pen at radius 20
(deliberate lag), laser at radius 8 (responsive). All coords
normalized 0..1 against the slide's section rect so the audience
canvas (different pixel dimensions) renders the same stroke geometry.

Right-click is always laser regardless of active tool — quick gesture
without leaving pen mode. Eraser does whole-stroke hit-testing in
normalized space (point-to-polyline distance, tolerance 0.025).

Audience-side cursor is smoothed (frame-rate-independent exponential
lerp toward the wire-cursor position, tau ≈ 55ms) so it glides between
the 30Hz wire updates instead of stepping.

### Slide Overview (both modes)

Toolbar (audience) or chrome button + `g` (presenter) toggles a
2-column grid of slide previews. CSS variables make slides
aspect-ratio'd cells; container queries auto-scale their content.

Click any slide → navigates to it + exits overview. The presenter
also records the from-slide into `jumpReturnSlideId`, which surfaces
the jump-back button in the chrome until either consumed or invalidated
by a `next`/`previous` (presenter resumed natural flow).

IntersectionObserver is guarded with `if (this.overview) return` so
the grid layout's mass slide-crossings don't fire spurious
`navigate.scroll` events and overwrite `currentIndex`.

Scroll re-anchoring on overview toggle is deferred to
`requestAnimationFrame` — reading `slide.offsetTop` synchronously in
`updated()` raced with the browser's scroll-snap settling after the
attribute swap.

## Theme

`@morkdeck/theme` ships Rose Pine (dark) tokens compiled via Terrazzo
into CSS variables (`compileCss()` returns the CSS string the
renderer inlines into `<head>`). Container-query units (`cqi`,
`cqmin`, `cqb`) drive most sizing so every slide proportionally
scales with its container — the same deck renders correctly at a
projector, in a presenter preview, and in an overview grid cell.

Recursive is the single typeface, used across its variable axes
(`wght`, `slnt`, `CASL`, `MONO`) instead of pairing with a separate
mono / italic. See PRODUCT.md / DESIGN.md (in repo root if present)
for the brand and design system definitions.

## Extending

**Add a slide layout**: extend the `Layout` union in
`core/layout.ts`, add a branch to `detectLayout()`, then style it in
`slide.ts` (host-level for the section box) and
`slide-styles.eta` (slotted content). Existing layouts are good
references — pattern is "detect structurally, style via attribute
selector".

**Add a Comark component**: add an entry to the `components` map in
`renderHTML()` (in `core/renderer.ts`). Handler receives
`[tag, attrs, ...children]` and a `{ render }` context.

**Add an xstate event**: declare in `actor/types.ts` (extend the
`Events` union), add the reducer in `actor/setup.ts`
(`assign(...)`), wire it in `actor/machine.ts`. If it should cross
the tab boundary, add to `#RELAYED_EVENTS` in
`presentation/wc.ts`.

**Add a presenter keyboard shortcut**: edit `#onKeyDown` in
`presentation/wc.ts`. Always guard on `role === "presenter"` and
skip when `target` is an `INPUT` / `TEXTAREA` so the shortcut doesn't
eat into form fields.

**Add a Shiki language**: nothing to do — `core/highlight.ts` walks
the AST and dynamically imports whatever languages appear in fence
strings, falling through to plain-text rendering for ones Shiki
doesn't ship. To add a non-obvious alias (e.g. `py` → `python`),
extend the `ALIASES` map in `highlight.ts`.

**Add a social platform**: extend `SOCIAL_ICONS` in `core/icons.ts`
with the SVG path, then add a `case` to `socialHref` /
`socialLabel` in `core/renderer.ts` for the URL convention.