npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

slidev-addon-review-annotations

v0.3.1

Published

Leave review annotations on a Slidev deck in the browser and hand them to an AI coding agent

Readme

slidev-addon-review-annotations

Leave review annotations directly on a Slidev deck in the browser, and let an AI coding agent pick them up. (These are different from Slidev's built-in drawing annotations, which are for presenting.)

Formerly slidev-addon-annotate.

You click an element on a slide, type an annotation, and the annotation is stored together with the slide number, click step, slide title and source line. An agent reads the annotations over MCP, edits the slides, and marks each annotation as resolved.

Status: experimental (0.x; the API may change between minor versions). It works with a local slidev dev server and with PR previews served by a Cloudflare Worker, as in whitphx/slides.

How it fits together

 Browser: deck + toolbar (agent-ui-annotation, MIT)
    │  Agentation-compatible HTTP API, same origin (/__review-annotations/api)
    ▼
 Handler (src/server.ts, Fetch API) + store
    ├─ dev:     Vite middleware, annotations in <deck>/.review-annotations/annotations.json
    └─ preview: Cloudflare Worker (worker.js), annotations in D1
    ▲
    │  agentation-mcp server --mcp-only --http-url <API>   (agent reads, acknowledges, resolves)
 Agent ──► Slidev MCP (/__mcp): get/update slides, go to slide
  • Toolbar: agent-ui-annotation's framework-agnostic createAnnotation.
  • Annotation format: Agentation's AFS v1.1 annotations. The slide context goes into sourceFile and slidev-* keys in attributes, because agentation-mcp passes those two fields through to the agent.
  • HTTP API: the part of Agentation's API that its MCP server calls, so the unmodified agentation-mcp works as the agent-side client. agentation-mcp is licensed under PolyForm Shield 1.0.0 and is run with npx, not bundled; this addon implements Agentation's HTTP API so that it can talk to it, without including any Agentation code.

Use it in a deck

Install the addon (Slidev 52.19 or later) and list it in the deck's headmatter:

npm i -D slidev-addon-review-annotations
---
addons:
  - slidev-addon-review-annotations
---

Run slidev as usual. The toolbar appears at the bottom right of the audience view and of the presenter view. It is not shown in print/export or in embedded slides.

To give feedback on a slide's speaker notes, open the presenter view (/presenter/<n>) and annotate the notes panel. Those annotations carry slidev-target: notes, the PR comment labels them "speaker notes", and the agent edits the notes rather than the slide. Only the current slide (and, in the presenter view, its notes) can be annotated. Slidev's navigation controls and menus and the presenter view's next-slide preview are left out of annotating entirely: hovering doesn't highlight them, and they keep working, so you can change slides without leaving annotate mode.

Register both MCP servers with your agent, e.g. for Claude Code:

claude mcp add --transport http slidev http://localhost:3030/__mcp
claude mcp add review-annotations -- npx -y agentation-mcp server --mcp-only --http-url http://localhost:3030/__review-annotations/api

Then ask the agent to "address the pending slide annotations". It reads them with agentation_get_all_pending, edits the slide (slidev-update-slide), shows you the result (slidev-goto-slide) and calls agentation_resolve. For hands-free use, ask it to loop on agentation_watch_annotations.

An annotation as the agent sees it:

{
  "comment": "Make this bold",
  "element": "li",
  "elementPath": "ul > li:nth-of-type(1)",
  "url": "http://localhost:3030/2?clicks=1",
  "nearbyText": "First point",
  "sourceFile": "packages/review-annotations-playground/slides.md:13",
  "attributes": {
    "slidev-deck": "review-annotations-playground",
    "slidev-revision": "4ddd53fbefa1706f3e5a645fb82ff0daecefa263",
    "slidev-slide": "2",
    "slidev-click": "1",
    "slidev-clicks-total": "2",
    "slidev-title": "Clicks",
    "slidev-position": "50% 6.4%"
  }
}

Authentication

The handler takes an auth option, so each host decides who may call the API (src/auth.ts). Who wrote an annotation or a reply, and who resolved an annotation, is taken from the credential, never from the request body.

| Authenticator | For | How | |---|---|---| | localDev() | the slidev dev server | Every same-origin request is the local user; cross-site requests from other pages in the browser are refused. | | apiKey({ key, role: 'agent' }) | agents | Shared key in x-api-key (what agentation-mcp --api-key sends) or Authorization: Bearer. | | signedCookie({ secret, home?, trustOrigin? }) | reviewers in a browser | <api>/login shows a form for the reviewer key (a password field, so password managers fill it; the key is posted, never put in a URL) and sets a signed, expiring HttpOnly cookie that the toolbar's same-origin requests carry. With home, other hosts that trustOrigin accepts hand logins off to the home host: one login there covers them all (see below). <api>/logout clears it. | | chain(...) | combining the above | The first authenticator that accepts the request wins. |

Roles (defaultAuthorize; pass authorize to replace it):

  • reviewer: read, create, edit and delete their own annotations, change status, reply. With one shared reviewer key (as in worker.js), all reviewers are the same principal.
  • agent: read, change status (acknowledge, resolve, dismiss, reopen), reply. It cannot create, edit or delete annotations, so a leaked agent key can't plant or rewrite annotations; it can still add replies and change status.
  • admin: everything.

Before each new annotation the toolbar asks the API (GET <api>/whoami) whether this browser may add annotations, and refuses the annotation with a notice if this browser's login may not (e.g. the agent key). Annotations made before logging in are kept: they wait in the browser, the deck asks you to log in, and they are saved once you have. If a save is rejected later, the deck also shows a notice at the top of the page.

Sending annotations to an agent

With a dispatcher configured, a logged-in reviewer sees Send N annotations to agent at the top right of the deck. It sends the session's pending annotations that haven't been sent yet (POST <api>/sessions/<id>/dispatch); each annotation is sent once, and again only if its text is edited. Ticking Send automatically sends on its own once no annotation has been added for a while (SLIDEV_REVIEW_ANNOTATIONS_AUTO_DISPATCH_SECONDS, default 120); the choice is remembered per browser, and SLIDEV_REVIEW_ANNOTATIONS_AUTO_DISPATCH=1 makes it the default. Only reviewers can dispatch, at most once a minute per session.

githubComment() (src/github.ts) is the dispatcher worker.js uses: it posts the batch as one comment on the PR the session belongs to (pr-<number>.<deck>), listing each annotation with its slide, click step, title, source line and id. An agent session watching that PR is woken by the comment, applies the annotations, pushes, and resolves them by id. Any function (batch) => Promise<{ url? }> can be passed as dispatch instead, e.g. to call a Claude Code Routine's API trigger.

Reviewing offline

You can open a deck online, go offline, keep annotating, and send the annotations once you are back online:

  • When the deck loads, it asks the server whether this browser may add annotations and remembers the answer. Offline, that remembered answer is used. So log in and open the deck once while online.
  • Every change (new annotation, edit, delete) first goes into an outbox in localStorage. It is sent to the server right away, again when the browser comes back online, every 30 seconds while changes are waiting, and on the next page load. Only the latest change to each annotation is sent. Tabs of the same deck share the outbox and take turns sending (with the browser's Web Locks API), so an older version never overwrites a newer one.
  • While changes are waiting, the deck says so. Send to agent saves them before sending, and doesn't send while any are still waiting. With Send automatically on, sending starts once they are saved.
  • If the login expired meanwhile, the changes stay in the outbox until you log in again.

The deck's own files need the network: a slide or image the browser hasn't loaded yet may not show offline, and reloading the page offline fails unless something like a service worker caches the deck. Such a service worker must not cache or answer requests under the annotation API (/__review-annotations/api), or the outbox would count changes as saved that never reached the server.

Host the API in your own Worker

slidev-addon-review-annotations/worker sets the API up from a Worker's bindings, so another repository's Worker needs only a few lines (this repo's worker.js is the same thing):

import { createReviewAnnotationsWorker } from 'slidev-addon-review-annotations/worker'

const reviewAnnotations = createReviewAnnotationsWorker({
  repo: 'owner/slides', // PRs that get "Send to agent" comments
  // Hosts the home host may log in, e.g. this Worker's preview hosts.
  trustOrigin: origin => /^https:\/\/[a-z0-9-]+-slides\.owner\.workers\.dev$/.test(origin),
})

export default {
  async fetch(request, env) {
    // The API's response under /__review-annotations/api, undefined for anything else.
    return (await reviewAnnotations(request, env)) ?? env.ASSETS.fetch(request)
  },
}

| Binding | Needed for | |---|---| | REVIEW_ANNOTATIONS_DB (D1) | storing annotations; without it the API answers 503 | | REVIEW_ANNOTATIONS_AGENT_KEY | agents (x-api-key) | | REVIEW_ANNOTATIONS_REVIEWER_KEY | reviewer login; also signs the login cookie | | REVIEW_ANNOTATIONS_HOME_ORIGIN | optional: one login for every host trustOrigin accepts | | REVIEW_ANNOTATIONS_GITHUB_TOKEN | optional: Send to agent as a PR comment (with repo) |

Options: basePath (default /__review-annotations/api; match SLIDEV_REVIEW_ANNOTATIONS_ENDPOINT), repo, prNumber (session id to PR number; default pr-<number>.<deck>) and trustOrigin. Build the decks with the settings under Settings, as this repo's CI does.

For other hosts, or to change the parts, use the building blocks directly. They use only the Fetch API and Web Crypto (except file-store), so they run in Cloudflare Workers and Node 20+, and should in other runtimes with those APIs:

| Import | Exports | |---|---| | slidev-addon-review-annotations/server | createReviewAnnotationsHandler({ store, basePath, auth, authorize?, dispatch? }) and the AnnotationStore and Dispatcher interfaces | | slidev-addon-review-annotations/auth | apiKey, signedCookie, localDev, chain, defaultAuthorize | | slidev-addon-review-annotations/d1 | createD1Store(db) | | slidev-addon-review-annotations/file-store | createFileStore(path) (Node) | | slidev-addon-review-annotations/github | githubComment({ token, repo }) | | slidev-addon-review-annotations/afs | the AFS Annotation and Session types |

Inside this workspace these resolve to the TypeScript sources; the published package points them at compiled JavaScript with type declarations (pnpm run build, run on pack). Releases are described in the repository's RELEASING.md.

Set up the PR-preview Worker (this repo)

worker.js serves the API at /__review-annotations/api with annotations in D1, agents via REVIEW_ANNOTATIONS_AGENT_KEY and reviewers via REVIEW_ANNOTATIONS_REVIEWER_KEY. One-time setup:

  1. The slides-annotations D1 database is bound as REVIEW_ANNOTATIONS_DB in wrangler.jsonc. To set it up on another account, create a database and put its id in that entry:

    pnpm dlx [email protected] d1 create slides-annotations

    Tables are created on first use. Preview versions share the production Worker's bindings and secrets, so this covers every PR.

  2. Set the two secrets (long random strings; openssl rand -hex 32 gives ones that need no URL encoding):

    pnpm dlx [email protected] versions secret put REVIEW_ANNOTATIONS_AGENT_KEY
    pnpm dlx [email protected] versions secret put REVIEW_ANNOTATIONS_REVIEWER_KEY

    Use versions secret put, not secret put: PR previews upload versions without deploying them, so the latest version is never the deployed one and secret put refuses. Later versions, previews and the next production deploy alike, inherit the secrets. Don't "deploy the latest version first" as wrangler suggests; that is a PR preview build. For Send to agent, also create a fine-grained GitHub token limited to this repository with Pull requests: Read and write, and store it the same way:

    pnpm dlx [email protected] versions secret put REVIEW_ANNOTATIONS_GITHUB_TOKEN

    Without it the button doesn't appear. Comments are posted as the token's owner.

  3. To log in, press Log in to review at the top right of a preview deck (or open <host>/__review-annotations/api/login) and enter REVIEW_ANNOTATIONS_REVIEWER_KEY; your password manager can save it for the host. Each PR preview has its own *.workers.dev host, and cookies aren't shared between them, so by default that is once per preview.

    Log in once for all previews: once this Worker's API is deployed to production, add the production host as the home host in wrangler.jsonc:

    "vars": { "REVIEW_ANNOTATIONS_HOME_ORIGIN": "https://slides.whitphx.workers.dev" }

    Previews then send the login to the home host (only hosts that trustOrigin in worker.js accepts), which asks for the key once and hands back a pass signed for that preview, valid for a minute and tied to a one-time cookie. Later previews log in with one click and no key. Don't set it before production serves the API, or the hand-off lands on a page that doesn't exist.

  4. For a cloud agent session, add the agent key to the environment as a secret named AGENTATION_API_KEY (which agentation-mcp reads), allow the Worker's host in its network policy, and register the MCP server. Once this is deployed to production, use the stable production host (all previews share the same database); before that, use the PR's preview host:

    claude mcp add review-annotations -- \
      npx -y agentation-mcp server --mcp-only --http-url https://<production host>/__review-annotations/api

CI builds PR previews with SLIDEV_REVIEW_ANNOTATIONS=1, SLIDEV_REVIEW_ANNOTATIONS_SESSION=pr-<number> and the PR head commit, so annotations from different PRs are kept apart by session id. Decks opt in by listing the addon in their headmatter.

Agent skill

skills/slidev-review-annotations/ is an Agent Skill that tells an agent how to apply these annotations: when a dispatch comment counts as an instruction (only from the person it works for, and only about the slides), how to find each annotation's slide, and how to resolve the annotations afterwards. In this repository it is linked into .claude/skills/, so every session here has it, cloud sessions included.

To use it in another project with Claude Code:

/plugin install slidev-addon-review-annotations --marketplace whitphx/slides

(or /plugin marketplace add whitphx/slides, then /plugin install slidev-addon-review-annotations@whitphx-slides). For other agents, npx skills add whitphx/slides --skill slidev-review-annotations copies it into the project's skills folder.

Settings

Environment variables read when slidev starts:

| Variable | Default | Meaning | |---|---|---| | SLIDEV_REVIEW_ANNOTATIONS | on in dev, off in builds | 1 includes the toolbar in slidev build; 0 turns it off in dev. Builds without it contain no toolbar code. | | SLIDEV_REVIEW_ANNOTATIONS_ENDPOINT | /__review-annotations/api | Base URL of the annotation API. | | SLIDEV_REVIEW_ANNOTATIONS_SESSION | local | Session name, e.g. pr-12. The session id is <session>.<deck directory>. | | SLIDEV_REVIEW_ANNOTATIONS_REVISION | git rev-parse HEAD | Commit recorded on each annotation. | | SLIDEV_REVIEW_ANNOTATIONS_AUTO_DISPATCH | off | 1 turns Send automatically on by default (each browser can change it). | | SLIDEV_REVIEW_ANNOTATIONS_AUTO_DISPATCH_SECONDS | 120 | Quiet time after the last annotation before an automatic send. |

What the spike showed

Checked in Chromium with Playwright against packages/review-annotations-playground, in dev mode and as a static build served with the same handler:

  • Typing in the annotation box (including arrow keys, Space, PageDown) does not move the slides. With the box closed, arrow keys still navigate.
  • Annotations record the slide number, click step, title, source line and position on the slide.
  • agentation-mcp, unmodified, lists, acknowledges and resolves the annotations, and its watch mode picks up new annotations.
  • Slidev's MCP reads the slide and moves the browser to it.
  • Through worker.js under wrangler dev with a local D1: requests without a credential get 401; the agent key reads, acknowledges and resolves but gets 403 on creating, editing or deleting annotations; the login form sets the cookie and only redirects within the same origin; the home-host hand-off logs a second origin in (one key entry, then one click); forged or cross-site cookies are refused; before login the deck shows the notice, after it annotations save with the reviewer as author; agentation-mcp --api-key works, watch mode included.

Limitations found:

  • Markers on other slides. agent-ui-annotation keeps a marker visible while its element is in the document, and Slidev keeps neighbouring slides mounted. The addon hides other slides' markers with a style rule in the toolbar's shadow root (createMarkerFilter). An upstream option to scope markers by route would remove this workaround.
  • Toolbar storage. The toolbar keeps its own copy of the annotations in localStorage, one list per origin, and has no API to load annotations from a server. So it doesn't show that the agent resolved an annotation, and annotations made in another browser don't appear.
  • Source path in builds. Slidev drops slide file paths from builds, so built decks report the entry file for every slide. That is wrong only for slides imported with src:.