dev-annotate 0.1.0

package/dist/types-BzKl2hyk.d.ts

@@ -0,0 +1,19 @@
+interface SizePreset {
+    label: string;
+    pen: number;
+    font: number;
+}
+interface DevAnnotationOptions {
+    /** Upload endpoint. Default '/api/dev/save-annotation'. */
+    endpoint?: string;
+    /** Color palette. */
+    colors?: string[];
+    /** Size presets (S/M/L). */
+    sizes?: SizePreset[];
+    /** Keyboard shortcut to toggle the panel. Default 'a'. */
+    shortcutKey?: string;
+    /** Base z-index for the UI layers. Default 100000. */
+    zIndexBase?: number;
+}
+
+export type { DevAnnotationOptions as D };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "dev-annotate",
+  "version": "0.1.0",
+  "description": "Dev-only on-screen annotation tool: scribble on the live page, take an OS screenshot, upload it for an AI agent to read.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["annotation", "screenshot", "dev-tool", "design-review", "ai", "nuxt"],
+  "engines": { "node": ">=20" },
+  "bin": { "dev-annotate": "dist/cli.js" },
+  "exports": {
+    ".": { "import": "./dist/core/client.js", "types": "./dist/core/client.d.ts" },
+    "./server": { "import": "./dist/server/index.js", "types": "./dist/server/index.d.ts" },
+    "./nuxt": { "import": "./dist/nuxt/module.js", "types": "./dist/nuxt/module.d.ts" }
+  },
+  "files": ["dist", "templates", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "tsup"
+  },
+  "peerDependencies": { "h3": "*", "@nuxt/kit": "*" },
+  "peerDependenciesMeta": {
+    "h3": { "optional": true },
+    "@nuxt/kit": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4",
+    "jsdom": "^25.0.0",
+    "h3": "^1.13.0",
+    "@nuxt/kit": "^3.14.0"
+  }
+}

package/templates/agent-instructions.md

@@ -0,0 +1,31 @@
+# Reviewing on-screen annotations (for AI agents)
+
+This project uses `dev-annotate`. A human scribbles on the live page in the
+browser, takes an OS screenshot, and uploads it. Your job is to read that
+annotated screenshot and act on it.
+
+## Workflow
+
+1. Get the latest annotated screenshot path:
+   ```
+   npx dev-annotate latest
+   ```
+   For several recent ones: `npx dev-annotate latest -n 3`
+2. Open/read that image file. The red pen / text / numbered pins are the
+   human's instructions on the real UI.
+3. Locate the corresponding code, make the fix, and verify (build / run /
+   screenshot) before reporting.
+4. After the change is confirmed, clean up processed screenshots:
+   ```
+   npx dev-annotate clean --all --yes
+   ```
+5. To wait for the next annotation in a long-running loop:
+   ```
+   npx dev-annotate watch
+   ```
+
+## Notes
+- Screenshots live under `.playwright-mcp/design-review/annotated-*.{png,jpg,webp}`
+  by default (override with `--dir`).
+- Treat an annotation as intent, not pixels: confirm the underlying cause
+  before changing how something looks.