@nuniapp/widget 0.1.3 → 0.1.5

package/README.md

@@ -29,6 +29,7 @@ Steps:
 6. Do not add Nuni to server-only code, and do not load it more than once.
 7. If the site sends a Content-Security-Policy, allow connect-src https://*.convex.cloud wss://*.convex.cloud https://*.convex.site (and script-src cdn.jsdelivr.net for the script tag).
 8. Start the dev server, open the site, and confirm the Nuni button appears in the bottom-right corner.
+9. Tell the user they can let you read and resolve comments later: run npx @nuniapp/cli@latest login once, then add the MCP server (for Claude Code: claude mcp add nuni -- npx -y @nuniapp/cli@latest mcp). Do not run login yourself unless asked.
 
 Docs: https://nuni.praveenjuge.com/quickstart
 ```
@@ -60,17 +61,23 @@ Using React? Use [`@nuniapp/react`](https://www.npmjs.com/package/@nuniapp/react
 
 ## Options
 
-| Option                                 | Description                                                                                |
-| -------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `project`                              | Your public project ID. Commit it; it is not a secret.                                     |
-| `getPageKey(url)`                      | Optional. Decide which URLs share comments. Defaults to the path, ignoring query and hash. |
-| `convexUrl`, `convexSiteUrl`, `appUrl` | Optional. For self-hosting or local development.                                           |
+| Option                                 | Description                                                                                                |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `project`                              | Your public project ID. Commit it; it is not a secret.                                                     |
+| `getPageKey(url)`                      | Optional. Decide which URLs share comments. Defaults to the path, ignoring query and hash.                 |
+| `convexUrl`, `convexSiteUrl`, `appUrl` | Optional. For self-hosting or local development.                                                           |
+| `capture`                              | Optional. Owner-only page context per comment: `{ console, network, dom, screenshot }`, all on by default. |
+| `pageKey`                              | Optional. `"path"` (default), `"path+search"` or `"path+hash"`, when `getPageKey` is not set.              |
+| `position`, `accentColor`, `theme`     | Optional. Toolbar corner, brand color (any CSS color), and `"auto"`, `"light"` or `"dark"`.                |
+| `label`, `hotkey`, `zIndex`            | Optional. Comment button text, shortcut key (`false` turns it off) and stacking order.                     |
+| `locale`, `messages`                   | Optional. Language for times and counts, and replacements for any of the widget's words.                   |
 
 `init` returns `{ destroy() }`.
 
 ## Using it
 
-- Press **C** (or the Comment button), click any element and write your comment.
+- Press **C** (or the Comment button), click any element and write your comment. Select text to comment on the words, or drag a box to comment on an area.
+- Everything works from the keyboard: while adding, the arrow keys move between elements and Enter comments.
 - Pins follow their element through layout changes, responsive breakpoints and content edits. If an element is removed, its comment is listed as "Couldn't find on this page" instead of pinned to the wrong thing.
 - Your name is remembered in this browser. You can edit and delete your own comments.
 - The site owner claims the project from the widget ("Claim Nuni", GitHub sign-in) and can then resolve, reopen and delete comments.

package/dist/index.d.ts

@@ -1,4 +1,113 @@
+//#region src/i18n.d.ts
+/**
+ * Every word the widget shows. Override any of them with the `messages`
+ * option; `locale` sets how times and counts are written.
+ *
+ * `{name}` is filled in. A message with forms (`one`, `other`, and `zero`,
+ * `two`, `few`, `many` where a language has them) is picked by `{count}`.
+ */
+declare const EN: {
+  toolbar: string;
+  comment: string;
+  addComment: string;
+  addCommentKey: string;
+  cancelAdding: string;
+  pickElement: string;
+  allComments: string;
+  openCount: string;
+  commentSelection: string;
+  commentSelectionKey: string;
+  pickHint: string;
+  pickHintMobile: string;
+  pickHintKeys: string;
+  picked: string;
+  comments: string;
+  close: string;
+  tabOpen: string;
+  tabResolved: string;
+  loading: string;
+  noOpen: string;
+  noOpenKey: string;
+  noResolved: string;
+  notFoundHere: string;
+  otherPages: string;
+  openOnPage: string;
+  replyCount: {
+    one: string;
+    other: string;
+  };
+  edited: string;
+  ownSite: string;
+  claim: string;
+  yourName: string;
+  leaveComment: string;
+  notYou: string;
+  screenshotAlt: string;
+  screenshotNote: string;
+  remove: string;
+  cancel: string;
+  post: string;
+  posting: string;
+  save: string;
+  send: string;
+  pinLabel: string;
+  commentBy: string;
+  openScreenshot: string;
+  screenshotTaken: string;
+  resolved: string;
+  leftOn: string;
+  approximate: string;
+  approximateHint: string;
+  notFound: string;
+  originallyOn: string;
+  resolve: string;
+  reopen: string;
+  copyForAgent: string;
+  copyForAgentHint: string;
+  loadingContext: string;
+  edit: string;
+  delete: string;
+  owner: string;
+  addReaction: string;
+  reactions: string;
+  reactWith: string;
+  reply: string;
+  replyFirst: string;
+  sendReply: string;
+  editReply: string;
+  deleteReply: string;
+  confirmDeleteComment: string;
+  confirmDeleteReply: string;
+  added: string;
+  saved: string;
+  deleted: string;
+  replyDeleted: string;
+  reopened: string;
+  copied: string;
+  copyFailed: string;
+  signedIn: string;
+  linkGone: string;
+  enterName: string;
+  writeFirst: string;
+  commentTooLong: string;
+  replyTooLong: string;
+  postFailed: string;
+  replyFailed: string;
+  reactFailed: string;
+  failed: string;
+  justNow: string;
+};
+type Plural = {
+  other: string;
+} & Partial<Record<Intl.LDMLPluralRule, string>>;
+type MessageKey = keyof typeof EN;
+type Messages = { [K in MessageKey]: string | Plural; };
+//#endregion
 //#region src/config.d.ts
+type Position = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+type Theme = "auto" | "light" | "dark";
+/** Built-in page keys, for when `getPageKey` is not set. */
+type PageKey = "path" | "path+search" | "path+hash";
 interface NuniOptions {
   /** Public project ID, e.g. "nuni_4Hk9...". Safe to commit. */
   project: string;
@@ -10,13 +119,82 @@ interface NuniOptions {
   appUrl?: string;
   /** Custom page key. Comments are matched by this; defaults to the normalized path. */
   getPageKey?: (url: URL) => string;
+  /**
+   * Which part of the URL tells pages apart, when `getPageKey` is not set:
+   * the path (default), the path and query string, or the path and hash.
+   */
+  pageKey?: PageKey;
+  /** Corner for the toolbar. Default "bottom-right". */
+  position?: Position;
+  /** Brand color for buttons, pins and highlights (any CSS color). */
+  accentColor?: string;
+  /** "auto" follows the visitor's system (default). */
+  theme?: Theme;
+  /** Text on the toolbar's comment button. Default "Comment". */
+  label?: string;
+  /** Key that starts a comment. Default "c"; `false` turns it off. */
+  hotkey?: string | false;
+  /** Stacking order of the widget. Default 2147483646. */
+  zIndex?: number;
+  /** Language for dates and counts, e.g. "de". Defaults to the browser's. */
+  locale?: string;
+  /** Replace any of the widget's words. See the `EN` messages. */
+  messages?: Partial<Messages>;
+  /**
+   * Extra context attached to each comment for the project owner and their
+   * coding agent. Everything is on by default; set a key to `false` to stop
+   * capturing it.
+   */
+  capture?: {
+    /** Recent console errors and warnings. */
+    console?: boolean;
+    /** Recent failed requests (method, origin + path, status). */
+    network?: boolean;
+    /** The element's markup (form values removed) and key styles. */
+    dom?: boolean;
+    /** An image of the element and its surroundings. */
+    screenshot?: boolean;
+  };
 }
 export declare const VERSION: string;
 //#endregion
-//#region src/index.d.ts
-export interface NuniInstance {
+//#region src/screenshot.d.ts
+/**
+ * Screenshots are loaded lazily (a separate chunk for npm users, a separate
+ * script for the CDN build), so the widget itself stays small.
+ */
+interface ScreenshotOptions {
+  /** Nuni's own host element, left out of the image. */
+  exclude: Element;
+  /** Outline color drawn around the commented element. */
+  accent: string;
+  /**
+   * The part of the element that was commented on (selected text, an
+   * area), in viewport coordinates. The image is cropped around it and it
+   * is outlined instead of the whole element.
+   */
+  focus?: () => Box;
+}
+type CaptureScreenshot = (el: Element, options: ScreenshotOptions) => Promise<Blob | null>;
+declare global {
+  interface Window {
+    /** Set by nuni-screenshot.global.js (the CDN build). */
+    __nuniScreenshot?: CaptureScreenshot;
+  }
+}
+interface Box {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+//#endregion
+//#region src/mount.d.ts
+interface NuniInstance {
   destroy(): void;
 }
+//#endregion
+//#region src/index.d.ts
 /**
  * Mount Nuni on the page. Call once on the client. Calling it again with the
  * same project shares the mounted widget; it is removed when every handle is
@@ -25,4 +203,4 @@ export interface NuniInstance {
  */
 export declare function init(options: NuniOptions): NuniInstance;
 //#endregion
-export type { NuniOptions };
+export { type Messages, type NuniInstance, type NuniOptions, type PageKey, type Position, type Theme, EN as messages };