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

devnotation

v1.2.0

Published

The visual feedback tool for AI coding agents (Claude Code, Cursor, Codex, Grok, Windsurf). Pointing beats describing.

Readme

Devnotation


💡 Why Devnotation?

Communicating UI bugs and design tweaks to an AI coding agent in chat is tedious and error-prone:

"In the sidebar under Bookings, the third action button is misaligned, change its padding to 12px, font to semi-bold, and make the icon 16px."

This approach wastes tokens, creates ambiguity, and forces the model to guess which file, line, and component hierarchy to touch.

Devnotation eliminates the friction:

  1. Click or drag on any element in your running localhost application.
  2. Devnotation extracts the underlying React Fiber source file and line number, semantic DOM selectors, sibling context, route metadata, and computed design tokens.
  3. Devnotation bundles your notes into machine-readable punchlists or feeds them directly into your agent via the Two-Way Model Context Protocol (MCP) server on localhost:4747.

📸 Visual Showcase (Snaps in Action)

1. In-Page Element Inspection & React Fiber Source (_debugSource)

Point to any UI element to lock its exact CSS selector, React component name, and source file:line location without opening browser DevTools.

2. Snapshot Studio Suite (21 Vector & Privacy Annotation Tools)

Capture your screen with GPU acceleration (zero layout distortion) or paste with Ctrl+V. Mark up UI with dimension rulers (176px), privacy blur masks, auto-incrementing badges, and red vector pointers.

3. Feedback Punchlist Drawer & Token Optimization

Review open visual issues in a slide-out drawer, choose from 4 output schemas, and copy structured prompt payloads for Claude Code, Cursor, or Windsurf.


⚡ Flagship Features

1. 🎯 React Fiber _debugSource Code Inspection

Devnotation queries internal React Fiber nodes (fiber._debugSource and fiber._debugOwner) to pinpoint the exact component source file, line number, and column:

Source: src/components/reservation/AddReservationModal.tsx:64:18
Component: <AddReservationModal> -> <DialogBody> -> <Button>

Your AI coding agent jumps straight to the exact line in your editor with zero searching or file-tree guesswork.

2. 📸 Full-Featured Snapshot Studio (21 Annotation Tools)

Take screenshots of your app or paste images directly from your clipboard (Ctrl+V) into an interactive annotation canvas equipped with 21 precision tools:

| Category | Tools & Capabilities | | :--- | :--- | | Selection & Crop | Pointer (Move/Select), Crop (Resize canvas bounds) | | Pointers & Vectors | Arrow (Single-head vector), 2-Way Arrow (Bi-directional vector), Line (Straight segment) | | Measurement | Measure (Dimension lines with live pixel distance readout, e.g. 124px) | | Shapes | Rectangle (Border or filled), Ellipse (Round containers or badges) | | Freehand & Mark | Pencil (Smooth freehand curve), Highlighter (Semi-transparent overlay) | | Text & Dialogue | Text (Multi-line typography), Callout (Speech bubble pointer with text) | | Badging & Sequence | Numbered Badges (Auto-incrementing step indicators: ①, ②, ③...) | | Privacy & Security | Pixelate Blur (Scramble PII / API keys), Redact Blackout (Solid mask) | | Inspection & Zoom | Eyedropper (Sample any screen pixel & copy HEX to clipboard), Magnifier (2x loupe zoom circle) | | Attention & Review | Spotlight (Darken canvas around a highlighted focal area), Emoji Stamp (Reaction icons), Comment Pin (Marker pin with note) |

  • Zero Layout Breakage (Native GPU Capture): Captures your screen cleanly using the browser's native navigator.mediaDevices.getDisplayMedia API. No html2canvas iframe mutations, no responsive layout collapse, and no frozen video streams.
  • Image Adjustments: Fine-tune brightness, contrast, saturation, invert colors, sepia, grayscale, or apply blur.
  • Canvas Zoom & Pan: Zoom - 67% +, Fit to Screen, and 1:1 Pixel Match.
  • Export Anywhere: Download as PNG/JPEG/WEBP, copy to clipboard, or embed into Devnotation Markdown payloads.

3. 📝 Precision Text Mode (T Text)

  • Single-Click Extraction: Click any button, heading, or paragraph to immediately capture its raw text string.
  • Drag-to-Select: Highlight exact substrings to flag typos, microcopy revisions, or internationalization keys.
  • Visual Hover Outline: Amber focus border (#f59e0b) confirms the targeted text range before you click.

4. 🧊 Live Animation & Transition Freezer

Click the Pause icon on the toolbar to freeze all running CSS keyframe animations, CSS transitions, and HTML5 video loops on that exact frame. Inspect transient hover states, modal entrances, and timing regressions with zero rush.

5. 📐 Area Box Selector

Drag a bounding box over any arbitrary layout area, multi-column grid, or empty space. Perfect for reporting whitespace defects, missing elements, or structural alignment issues.

6. 📑 4 Agent-Optimized Output Formats

Generate the exact level of detail your workflow requires:

  • Compact Mode (~45 tokens/item): Single-line bulleted punchlist for fast minor edits.
  • Standard Mode (~120 tokens/item — Recommended): Component hierarchy, source file:line, user directive, and essential computed styles.
  • Detailed Mode (~210 tokens/item): Exact bounding box coordinates (x, y, w, h), parent-child paths, and complete stylesheet dumps.
  • Forensic YAML (~340 tokens/item): Machine-structured schema with raw HTML snippets, sibling context, and theme tokens for autonomous multi-agent loops.

7. 🔌 Two-Way Model Context Protocol (MCP) Server

Run the local MCP daemon to connect Devnotation directly to Claude Code, Cursor, or Windsurf:

npx -y devnotation-mcp

Your agent reads pending visual feedback annotations directly from http://localhost:4747, implements code changes, and marks issues as resolved autonomously.

8. 🛡️ Bulletproof Stacking Context & Max 32-bit Z-Index (2,147,483,647)

Devnotation renders directly into document.body via React Portals, completely escaping host application stacking contexts (transform, filter, isolation: isolate). Using the browser engine's maximum 32-bit signed integer z-index (2147483647), Devnotation is guaranteed to never be covered by host modals, sweetalerts, sticky headers, or toast notifications.

9. ⏱️ Smart Inactivity Auto-Collapse

When not in use, Devnotation automatically collapses after 10 seconds into a sleek, unobtrusive floating micro-pill ([D]), keeping your screen clutter-free during normal development. Hovering or clicking instantly expands the toolbar. Safe-guards prevent auto-collapse while you are actively annotating or inspecting.

10. ⚙️ Interactive Preferences & Settings Suite

Click the ⚙️ Settings icon on the toolbar to open the multi-tab preferences modal:

  • 🎨 Theme & Style: Dark, Light, or System mode; 6 custom brand accent colors (Electric Blue, Royal Violet, Emerald, Amber, Rose, Cyan); UI translucency slider.
  • ⚙️ General Options: Configurable idle timeout (5s, 10s, 15s, 30s, 60s), audio feedback cues, default severity tag, and output format.
  • 🔌 MCP Server Management: Live port configuration (default 4747), connection test ping, 1-click CLI launch command, and Cursor .cursor/mcp.json snippet generator.

11. 🎨 Ultra-Compact Draggable UI

  • 34px Sleek Toolbar: Draggable anywhere on the screen with pointer capture, live MCP sync indicator, and collapse toggle.
  • 328px Inspector Popover: Compact, floating inspection card that automatically stays within viewport bounds.
  • Custom 5px Rounded Scrollbars: Modern, minimalist scrollbars across all modals and code blocks (border-radius: 9999px). Zero clunky browser defaults.

🔄 Zero-Touch Auto-Update (Evergreen Mode)

Want Devnotation to always run the latest version automatically without typing npm update or asking your AI agent to update it? Choose any of these 3 zero-maintenance methods:

Option 1: Universal Evergreen CDN (100% Zero-Touch — Recommended)

Add this single script tag to your index.html (works with React, Next.js, Django, FastAPI, Flask, Laravel, Rails, or plain HTML):

<!-- Always runs the latest version from CDN on every page refresh -->
<script src="https://cdn.jsdelivr.net/npm/devnotation/dist/devnotation.standalone.js"></script>

Whenever a new version is released, your browser immediately runs the latest code upon refresh with zero terminal commands and zero build steps.

Option 2: React Component Evergreen Mode

If installed via npm, simply pass the evergreen flag:

import { Devnotation } from 'devnotation';

export default function App() {
  return (
    <>
      <MainApp />
      <Devnotation evergreen />
    </>
  );
}

Devnotation checks the NPM registry on mount and seamlessly hot-upgrades to the latest release in development.

Option 3: Vite Background Auto-Updater Plugin

Automatically keep your local node_modules on the latest release every time you run npm run dev:

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { devnotation } from 'devnotation/vite';

export default defineConfig({
  plugins: [
    react(),
    devnotation({ autoUpdate: true }) // Silently checks NPM & auto-executes npm/pnpm/yarn/bun update
  ]
});

📦 Installation

Install Devnotation as a development dependency:

# npm
npm install -D devnotation

# pnpm
pnpm add -D devnotation

# yarn
yarn add -D devnotation

# bun
bun add -d devnotation

🚀 Quick Start

Next.js (App Router)

Create a client-side wrapper or render conditionally inside app/layout.tsx:

// app/layout.tsx
import type { Metadata } from 'next';
import { Devnotation } from 'devnotation';
import 'devnotation/style.css'; // Optional: bundled styles are included automatically

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        {process.env.NODE_ENV === 'development' && <Devnotation />}
      </body>
    </html>
  );
}

Tip for React Server Components: If your root layout is a Server Component, import Devnotation inside a client component with 'use client' or load it via next/dynamic with { ssr: false }.

'use client';
import dynamic from 'next/dynamic';

export const DevTools = dynamic(
  () => import('devnotation').then((mod) => mod.Devnotation),
  { ssr: false }
);

Vite + React

Drop <Devnotation /> directly into src/App.tsx:

// src/App.tsx
import { Devnotation } from 'devnotation';

export function App() {
  return (
    <>
      <MainApplication />
      {import.meta.env.DEV && <Devnotation />}
    </>
  );
}

Remix

Add Devnotation inside app/root.tsx:

// app/root.tsx
import { Devnotation } from 'devnotation';

export default function App() {
  return (
    <html lang="en">
      <head />
      <body>
        <Outlet />
        {process.env.NODE_ENV === 'development' && <Devnotation />}
      </body>
    </html>
  );
}

Python Projects (Django, Flask, FastAPI, Streamlit, FastHTML)

Devnotation is 100% compatible with Python web projects! You can load the self-contained standalone script directly into your HTML templates or Python frontend without needing any npm build step or Node.js runtime:

Django Templates (templates/base.html)

{% if debug %}
<!-- Injects Devnotation toolbar & inspector automatically in development -->
<script src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js"></script>
{% endif %}

Flask Jinja2 (templates/layout.html)

{% if config['DEBUG'] %}
<script src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js"></script>
{% endif %}

FastAPI (HTMLResponse / Jinja2Templates)

<script src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js"></script>

Streamlit Apps (app.py)

import streamlit as st
import streamlit.components.v1 as components

# Embed Devnotation floating toolbar in development mode
components.html(
    '<script src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js"></script>',
    height=0,
    width=0,
)

FastHTML

from fasthtml.common import *

app, rt = fast_app(
    hdrs=[Script(src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js")]
)

Full-Stack Python (FastAPI / Django + React / Vite / Next.js)

If your Python backend serves a React/Next.js frontend, install the npm package in your frontend folder:

npm install -D devnotation

and import <Devnotation /> in your root component.


⌨️ Keyboard Shortcuts

| Shortcut | Action | | :--- | :--- | | A / Ctrl+Shift+A | Toggle Annotate Click Mode | | Ctrl+Enter / Cmd+Enter | Save Active Annotation Note | | Escape | Dismiss Popover / Cancel Current Selection / Close Modals | | Ctrl+V | Paste Clipboard Image into Snapshot Studio | | Delete / Backspace | Delete Selected Canvas Annotation Shape | | Space + Drag | Pan Snapshot Studio Canvas | | Ctrl+Z / Ctrl+Shift+Z | Undo / Redo Canvas Annotation Edits |


🤖 MCP (Model Context Protocol) Integration

Devnotation includes first-class support for the Model Context Protocol, enabling zero-copy agent workflows.

1. Start the MCP Server

npx -y devnotation-mcp

This spins up a local server listening on http://localhost:4747.

2. Configure Your AI Coding Agent

Claude Code CLI

Run your task directly:

claude "Read all open visual annotations from the local Devnotation MCP server at localhost:4747. Inspect each component path and CSS selector, implement the design changes in the codebase, and verify the resulting layout."

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "devnotation": {
      "command": "npx",
      "args": ["-y", "devnotation-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "devnotation": {
      "command": "npx",
      "args": ["-y", "devnotation-mcp"]
    }
  }
}

📑 Output Formats Showcase

Standard Format (Default)

### 1. [HIGH] `button#btn-checkout.bg-emerald-600`

> **Instruction:** Increase button padding from 8px to 14px and add subtle drop shadow.

- **Source File:** `src/components/cart/CheckoutButton.tsx:42:15`
- **React Component:** `<CartDrawer> -> <CheckoutFooter> -> <CheckoutButton>`
- **Page Route:** `/checkout` (URL: `http://localhost:3000/checkout`)
- **Viewport:** `1440x900` (DPR: 2)
- **Full DOM Path:** `body > div#root > aside.cart-drawer > div.footer > button#btn-checkout`
- **Sibling Context:** [before: "Subtotal: $49.00"] [current: "Complete Order"] [after: "Secure 256-bit SSL"]
- **Computed Styles:** `padding: 8px 16px; font-weight: 600; background-color: rgb(5, 150, 105)`

Forensic YAML Format

# Forensic Node [1] -> button#btn-checkout.bg-emerald-600
index: 1
id: "ann_1793132002789"
severity: "high"
type: "element"
selector: "button#btn-checkout.bg-emerald-600"
sourceLocation: "src/components/cart/CheckoutButton.tsx:42:15"
componentTree: "<CartDrawer> -> <CheckoutFooter> -> <CheckoutButton>"
fullDomPath: "body > div#root > aside.cart-drawer > div.footer > button#btn-checkout"
environment:
  routeUrl: "/checkout"
  fullUrl: "http://localhost:3000/checkout"
  viewport: "1440x900"
  devicePixelRatio: 2
siblingContext:
  before: "Subtotal: $49.00"
  current: "Complete Order"
  after: "Secure 256-bit SSL"
directive: "Increase button padding from 8px to 14px and add subtle drop shadow."
boundingBox:
  x: 1040
  y: 680
  width: 320
  height: 48
rawHtmlSnippet: |
  <button id="btn-checkout" class="bg-emerald-600 px-4 py-2 font-semibold text-white rounded-lg">Complete Order</button>
computedStyleTokens:
  padding: "8px 16px"
  font-weight: "600"
  background-color: "rgb(5, 150, 105)"

📊 Feature Comparison

| Feature | Devnotation | Agentation | Traditional Screenshot | Browser DevTools | | :--- | :---: | :---: | :---: | :---: | | React Fiber _debugSource (File:Line:Col) | ✅ Native | ✅ | ❌ | ❌ | | Snapshot Studio Suite | ✅ 21 Tools | ❌ (Basic) | ❌ | ❌ | | Native GPU Screen Capture | ✅ (Zero DOM mutation) | ❌ (html2canvas) | Manual OS | ❌ | | Instant Clipboard Paste (Ctrl+V) | ✅ | ❌ | ❌ | ❌ | | Two-Way MCP Server Sync (:4747) | ✅ Native | Partial | ❌ | ❌ | | Live Animation Freezer | ✅ | ❌ | ❌ | Complex pause | | Single-Click Text Extraction | ✅ | ❌ | ❌ | Manual copy | | Area / Multi-Component Box Selection | ✅ | ❌ | ❌ | ❌ | | 4 Agent Output Formats | ✅ (Compact to YAML) | Standard only | Unstructured | Raw styles | | Draggable UI & Compact Cards | ✅ (34px Toolbar / 328px Card) | Fixed | N/A | Full pane | | Bundle Footprint | ~36 kB gzipped | ~80 kB | N/A | Built-in |


🛠 Local Development & Showcase

To run the Devnotation showcase and development playground locally:

git clone https://github.com/cmtimran/Devnotation.git
cd Devnotation
npm install
npm run dev

To build both the showcase application and the standalone npm library bundle:

npm run build

📄 License

MIT © Imran Hossain