Harden review session lifecycle, fix annotation-mode UX drift/misfires, and add Plan→Draft→Refine + reveal extensibility hooks

[Copilot]

Hands-on usage surfaced four gaps: repeated start_review leaked servers, annotation interactions were error-prone (pin drift + accidental captures + no light-dismiss), the reveal pipeline was too rigid to extend, and workflow guidance skipped narrative planning before drafting.

• Review server lifecycle

  • start_review now closes any existing running server for the same deckDir before starting a new one.
  • Prevents orphan Fastify instances from accumulating across iteration rounds.

• Overlay annotation UX correctness

  • Pins are now rendered in a per-slide layer inside the active <section> and positioned in section-relative coordinates (instead of viewport/scroll absolute positioning), so they stay aligned under reveal scaling/transforms.
  • Annotation capture now ignores reveal navigation UI (.controls, .progress, etc.) and applies mis-tap filtering (movement threshold + primary-click/modifier guard).
  • Popovers now support light-dismiss via outside pointer interaction.

• Rendering pipeline extensibility (minimal surface area)

  • Added optional buildDeck hooks:
    • customCssPath (append user CSS),
    • templatePath (custom HTML template with {{DECKMARK_*}} placeholders),
    • markedPlugins (load local modules exporting default/register(marked)).
  • Exposed via MCP build_deck inputs: customCss, template, markedPlugins.

• Workflow guidance: add planning phase

  • Updated deck skill/docs to explicit Plan → Draft → Refine flow.
  • Planning now calls out audience/goal alignment, core arguments, arc, and one-key-point-per-slide outline before content.md drafting.

• Coverage updates

  • Integration test now verifies repeated start_review replaces prior session for same deck.
  • Engine unit tests cover custom template/CSS rendering and marked plugin loading.

// mcp/tools/build.ts (new optional inputs)
await buildDeck({
  contentPath,
  outDir,
  customCssPath: opts.customCss ? resolve(cwd, opts.customCss) : undefined,
  templatePath: opts.template ? resolve(cwd, opts.template) : undefined,
  markedPlugins: opts.markedPlugins?.map(p => resolve(cwd, p))
});

[Copilot]

Pull request overview

This PR hardens the deck review lifecycle, improves annotation UX, and adds extensibility hooks for reveal deck rendering while updating workflow guidance toward Plan → Draft → Refine.

Changes:

• Replaces existing review sessions for the same deck before starting a new review.
• Improves overlay annotation behavior with section-local pins, ignored reveal UI targets, mis-tap filtering, and popover light-dismiss.
• Adds custom CSS/template/marked plugin build hooks plus tests and documentation updates.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
mcp/tools/review.ts	Adds replacement behavior for existing review servers for the same deck.
mcp/tools/build.ts	Exposes custom CSS, template, and marked plugin inputs to build_deck.
runtime/engines/reveal.ts	Adds rendering extensibility hooks and per-build marked renderer support.
runtime/overlay/pin.ts	Moves annotation pins into per-slide layers with section-relative placement.
runtime/overlay/annotation-mode.ts	Adds mis-tap filtering and ignores reveal navigation/chrome targets.
runtime/overlay/popover.ts	Adds outside-pointer light-dismiss behavior.
test/unit/engines-reveal.test.ts	Adds coverage for custom CSS/template rendering and marked plugin loading.
test/integration/mcp-flow.test.ts	Verifies repeated start_review replaces the prior session.
skills/deckmark/SKILL.md	Updates workflow guidance to Plan → Draft → Refine.
README.md	Documents planning flow and new build tool inputs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.