@perpetio/redline 2.1.1

package/redline.d.mts

@@ -0,0 +1,280 @@
+// Generated from redline.d.ts. Do not edit directly.
+export interface RedlineConfig {
+  /** Storage namespace shared by pages in one project. */
+  project?: string;
+  /** Fixed page key. By default Redline follows location.pathname. */
+  page?: string;
+  accent?: string;
+  theme?: 'auto' | 'light' | 'dark';
+  position?: 'bottom-right' | 'bottom-left';
+  blocks?: string;
+  startOpen?: boolean;
+  note?: string;
+  /** Email address or issue URL template. {page}, {count}, {summary} are URL encoded. */
+  shareEmail?: string;
+  /** Watch History API navigation and popstate. */
+  spa?: boolean;
+  /** HTTP endpoint receiving the JSON export on an explicit Send feedback action. */
+  postUrl?: string;
+  /**
+   * Retries for postUrl, 0 to 5, default 3, on network errors, timeouts, 408,
+   * 429 and 5xx. Waits 1 s, 2 s, 4 s…, or the receiver's Retry-After (up to 30 s)
+   * when the browser can read it.
+   */
+  postRetries?: number;
+  /** Redline Cloud review to sync with, or "local" for the coding agent's redline-mcp (localhost and 127.0.0.1 pages only). */
+  reviewId?: string;
+  /**
+   * Redline Cloud workspace id (ws_…). The Cloud names the review this site
+   * uses in the workspace; reviewId, when set, pins the page instead.
+   */
+  workspace?: string;
+  /** Query parameter carrying the invite token. Default "an_invite". */
+  inviteParam?: string;
+  /** Poll interval in milliseconds for remote reads. Default 20000, minimum 500. */
+  pollInterval?: number;
+  /** Fetch credentials mode for postUrl requests. Default "omit". Requests to Redline Cloud and the local agent never carry cookies. */
+  credentials?: 'omit' | 'same-origin' | 'include';
+  /**
+   * Extras each new comment records besides the element description:
+   * "styles", "components", both comma-separated (default), or "off".
+   */
+  capture?: string | Array<'styles' | 'components'>;
+  /**
+   * "Open in editor" link template. {path}, {line}, {column} come from the
+   * comment's component source, e.g. "vscode://file/Users/me/app/{path}:{line}".
+   */
+  editorUrl?: string;
+}
+
+export interface ResolvedRedlineConfig {
+  project: string;
+  page: string;
+  accent: string;
+  theme: 'auto' | 'light' | 'dark';
+  position: 'bottom-right' | 'bottom-left';
+  blocks: string;
+  startOpen: boolean;
+  note: string;
+  share: string;
+  spa: boolean;
+  postUrl: string;
+  postRetries: number;
+  reviewId: string;
+  workspace: string;
+  inviteParam: string;
+  pollInterval: number;
+  credentials: 'omit' | 'same-origin' | 'include';
+  capture: 'styles,components' | 'styles' | 'components' | 'off';
+  editorUrl: string;
+}
+
+export type RedlineStatus = 'open' | 'in_progress' | 'resolved' | 'wont_fix';
+
+export type RedlineGeom =
+  | { kind: 'rect' | 'circle'; selector: string; x: number; y: number; w: number; h: number; vw?: number; vh?: number }
+  | { kind: 'pin'; selector?: string; x: number; y: number; vw?: number; vh?: number }
+  | { kind: 'pen'; selector: string; points: Array<[number, number]>; vw?: number; vh?: number }
+  | { kind: 'block'; selector: string }
+  | { kind: 'group'; selectors: string[]; vw?: number; vh?: number };
+
+export interface RedlineAssignee {
+  id: string | null;
+  name: string;
+}
+
+export interface RedlineReply {
+  id: string;
+  author: string;
+  authorId: string | null;
+  text: string;
+  createdAt: string;
+  editedAt: string | null;
+  /** Member ids mentioned (synced reviews). */
+  mentions?: string[];
+}
+
+export type RedlineStyleKey =
+  | 'display' | 'position' | 'width' | 'height' | 'margin' | 'padding' | 'gap' | 'font-family' | 'font-size'
+  | 'font-weight' | 'line-height' | 'color' | 'background-color' | 'border' | 'border-radius' | 'box-shadow'
+  | 'opacity' | 'object-fit';
+
+/** The element a comment is about, recorded once when it is made (1.6+). */
+export interface RedlineTarget {
+  label: string;
+  tag: string;
+  role: string | null;
+  name: string | null;
+  id: string | null;
+  testId: string | null;
+  classes: string[];
+  selector: string;
+  heading: string | null;
+  box: { x: number; y: number; w: number; h: number };
+  styles: Partial<Record<RedlineStyleKey, string>> | null;
+  component: { framework: 'react' | 'vue' | 'svelte'; chain: string[]; source: string | null } | null;
+}
+
+export interface RedlineMarkdownOptions {
+  detail?: 'compact' | 'standard' | 'detailed';
+  scope?: 'page' | 'site';
+  /** Include resolved and won't-fix comments. Default false. */
+  includeClosed?: boolean;
+  /** Only these comment ids. */
+  ids?: string[];
+}
+
+export interface RedlineCopyOptions {
+  format?: 'markdown' | 'json';
+  detail?: 'compact' | 'standard' | 'detailed';
+  scope?: 'page' | 'site';
+}
+
+/** Record schema v2 (docs/backlog/wire-protocol.md). */
+export interface RedlineComment {
+  schema: 2;
+  id: string;
+  page: string;
+  url: string;
+  type: 'highlight' | 'shape' | 'pin' | 'pen' | 'note' | 'block' | 'group';
+  author: string;
+  authorId: string | null;
+  text: string;
+  color: string;
+  anchor: { exact: string; prefix: string; suffix: string } | null;
+  geom: RedlineGeom | null;
+  /** Absent on comments made before 1.6 or where nothing could be described. */
+  target?: RedlineTarget;
+  /** Group comments only: one entry per `geom.selectors` item, `null` where nothing could be described. Create-only. */
+  targets?: (RedlineTarget | null)[];
+  visibility: 'shared' | 'private';
+  status: RedlineStatus;
+  /** Derived: true when status is "resolved" or "wont_fix". */
+  resolved: boolean;
+  resolvedBy: string | null;
+  resolvedAt: string | null;
+  assignee: RedlineAssignee | null;
+  /** Member ids mentioned (synced reviews). */
+  mentions?: string[];
+  assignedAt: string | null;
+  replies: RedlineReply[];
+  createdAt: string;
+  updatedAt: string;
+  editedAt: string | null;
+}
+
+export interface RedlineSyncState {
+  state: 'local' | 'idle' | 'pending' | 'offline' | 'error';
+  pending: number;
+}
+
+export interface FeedbackExport {
+  annotate: string;
+  schema: 2;
+  kind: 'annotate-export';
+  exportedAt: string;
+  page: string;
+  url: string;
+  project: string;
+  exportedViewport: { vw: number; vh: number; dpr: number };
+  /** "site" when the file holds every page of the project; absent for a page export. */
+  scope?: 'site';
+  comments: RedlineComment[];
+  /** Set when the body was POSTed to postUrl; the same value on every retry of one submit. */
+  deliveryId?: string;
+}
+
+export interface RedlineAPI {
+  readonly version: string;
+  readonly config: ResolvedRedlineConfig | null;
+  init(config?: RedlineConfig): RedlineAPI;
+  destroy(): void;
+  open(): void;
+  close(): void;
+  toggle(): void;
+  enable(): void;
+  disable(): void;
+  setTool(tool: 'cursor' | 'highlight' | 'rect' | 'circle' | 'pen' | 'pin'): void;
+  refresh(): void;
+  comments(): RedlineComment[];
+  focus(id: string): void;
+  toast(message: string, options?: { kind?: 'info' | 'error' | 'success'; duration?: number }): void;
+  /** Download this page's comments, or every page's with { scope: 'site' } (local mode). */
+  export(options?: { scope?: 'page' | 'site' }): void;
+  import(): void;
+  /**
+   * Local mode: sends the current page's export JSON to postUrl; rejects on failure.
+   * In a synced review: resolves once every queued change is acknowledged by the backend
+   * (then also POSTs to postUrl when set).
+   */
+  submit(): Promise<FeedbackExport>;
+  /** Moves a comment through its lifecycle. The creator and review authors may do this. */
+  setStatus(id: string, status: RedlineStatus): RedlineComment | null;
+  /** Assigns a comment to someone, or clears the assignee with null. Review authors only; the backend rejects a reviewer's change. */
+  assign(id: string, assignee: RedlineAssignee | null): RedlineComment | null;
+  /** Remote sync status; "local" when no backend is configured. */
+  syncState(): RedlineSyncState;
+  /** Markdown made for AI coding agents. "" when no comment qualifies. */
+  markdown(options?: RedlineMarkdownOptions): string;
+  /** Copies Markdown (default) or the JSON export to the clipboard. */
+  copy(options?: RedlineCopyOptions): Promise<void>;
+  /** Pauses page animations, transitions and media while reviewers comment. Refused (returns false) while the tools are hidden. Returns the new state. */
+  setFrozen(on: boolean): boolean;
+  /** Whether motion is currently frozen. */
+  isFrozen(): boolean;
+  /** Local mode: removes this page's comments. In a synced review: removes only your own. */
+  clear(): void;
+}
+
+declare const Redline: RedlineAPI;
+export function init(config?: RedlineConfig): RedlineAPI;
+export function destroy(): void;
+export default Redline;
+
+export interface RedlineEventMap {
+  'annotate:sync': CustomEvent<RedlineSyncState>;
+  'annotate:freeze': CustomEvent<{ frozen: boolean }>;
+  'annotate:auth': CustomEvent<{ reviewer: { id: string; name: string; role: 'reviewer' | 'author' } | null }>;
+}
+
+// annotate.js's type names, kept as aliases so code written for it compiles.
+/** @deprecated Use {@link RedlineAPI}. */
+export type AnnotateAPI = RedlineAPI;
+/** @deprecated Use {@link RedlineAssignee}. */
+export type AnnotateAssignee = RedlineAssignee;
+/** @deprecated Use {@link RedlineComment}. */
+export type AnnotateComment = RedlineComment;
+/** @deprecated Use {@link RedlineConfig}. */
+export type AnnotateConfig = RedlineConfig;
+/** @deprecated Use {@link RedlineCopyOptions}. */
+export type AnnotateCopyOptions = RedlineCopyOptions;
+/** @deprecated Use {@link RedlineEventMap}. */
+export type AnnotateEventMap = RedlineEventMap;
+/** @deprecated Use {@link RedlineGeom}. */
+export type AnnotateGeom = RedlineGeom;
+/** @deprecated Use {@link RedlineMarkdownOptions}. */
+export type AnnotateMarkdownOptions = RedlineMarkdownOptions;
+/** @deprecated Use {@link RedlineReply}. */
+export type AnnotateReply = RedlineReply;
+/** @deprecated Use {@link RedlineStatus}. */
+export type AnnotateStatus = RedlineStatus;
+/** @deprecated Use {@link RedlineStyleKey}. */
+export type AnnotateStyleKey = RedlineStyleKey;
+/** @deprecated Use {@link RedlineSyncState}. */
+export type AnnotateSyncState = RedlineSyncState;
+/** @deprecated Use {@link RedlineTarget}. */
+export type AnnotateTarget = RedlineTarget;
+/** @deprecated Use {@link ResolvedRedlineConfig}. */
+export type ResolvedAnnotateConfig = ResolvedRedlineConfig;
+
+declare global {
+  interface WindowEventMap extends RedlineEventMap {}
+  interface Window {
+    Redline?: RedlineAPI;
+    RedlineConfig?: RedlineConfig;
+    /** @deprecated annotate.js's name; the same object as window.Redline. */
+    Annotate?: RedlineAPI;
+    /** @deprecated annotate.js's name; use window.RedlineConfig. */
+    AnnotateConfig?: RedlineConfig;
+  }
+}

package/redline.d.ts

@@ -0,0 +1,279 @@
+export interface RedlineConfig {
+  /** Storage namespace shared by pages in one project. */
+  project?: string;
+  /** Fixed page key. By default Redline follows location.pathname. */
+  page?: string;
+  accent?: string;
+  theme?: 'auto' | 'light' | 'dark';
+  position?: 'bottom-right' | 'bottom-left';
+  blocks?: string;
+  startOpen?: boolean;
+  note?: string;
+  /** Email address or issue URL template. {page}, {count}, {summary} are URL encoded. */
+  shareEmail?: string;
+  /** Watch History API navigation and popstate. */
+  spa?: boolean;
+  /** HTTP endpoint receiving the JSON export on an explicit Send feedback action. */
+  postUrl?: string;
+  /**
+   * Retries for postUrl, 0 to 5, default 3, on network errors, timeouts, 408,
+   * 429 and 5xx. Waits 1 s, 2 s, 4 s…, or the receiver's Retry-After (up to 30 s)
+   * when the browser can read it.
+   */
+  postRetries?: number;
+  /** Redline Cloud review to sync with, or "local" for the coding agent's redline-mcp (localhost and 127.0.0.1 pages only). */
+  reviewId?: string;
+  /**
+   * Redline Cloud workspace id (ws_…). The Cloud names the review this site
+   * uses in the workspace; reviewId, when set, pins the page instead.
+   */
+  workspace?: string;
+  /** Query parameter carrying the invite token. Default "an_invite". */
+  inviteParam?: string;
+  /** Poll interval in milliseconds for remote reads. Default 20000, minimum 500. */
+  pollInterval?: number;
+  /** Fetch credentials mode for postUrl requests. Default "omit". Requests to Redline Cloud and the local agent never carry cookies. */
+  credentials?: 'omit' | 'same-origin' | 'include';
+  /**
+   * Extras each new comment records besides the element description:
+   * "styles", "components", both comma-separated (default), or "off".
+   */
+  capture?: string | Array<'styles' | 'components'>;
+  /**
+   * "Open in editor" link template. {path}, {line}, {column} come from the
+   * comment's component source, e.g. "vscode://file/Users/me/app/{path}:{line}".
+   */
+  editorUrl?: string;
+}
+
+export interface ResolvedRedlineConfig {
+  project: string;
+  page: string;
+  accent: string;
+  theme: 'auto' | 'light' | 'dark';
+  position: 'bottom-right' | 'bottom-left';
+  blocks: string;
+  startOpen: boolean;
+  note: string;
+  share: string;
+  spa: boolean;
+  postUrl: string;
+  postRetries: number;
+  reviewId: string;
+  workspace: string;
+  inviteParam: string;
+  pollInterval: number;
+  credentials: 'omit' | 'same-origin' | 'include';
+  capture: 'styles,components' | 'styles' | 'components' | 'off';
+  editorUrl: string;
+}
+
+export type RedlineStatus = 'open' | 'in_progress' | 'resolved' | 'wont_fix';
+
+export type RedlineGeom =
+  | { kind: 'rect' | 'circle'; selector: string; x: number; y: number; w: number; h: number; vw?: number; vh?: number }
+  | { kind: 'pin'; selector?: string; x: number; y: number; vw?: number; vh?: number }
+  | { kind: 'pen'; selector: string; points: Array<[number, number]>; vw?: number; vh?: number }
+  | { kind: 'block'; selector: string }
+  | { kind: 'group'; selectors: string[]; vw?: number; vh?: number };
+
+export interface RedlineAssignee {
+  id: string | null;
+  name: string;
+}
+
+export interface RedlineReply {
+  id: string;
+  author: string;
+  authorId: string | null;
+  text: string;
+  createdAt: string;
+  editedAt: string | null;
+  /** Member ids mentioned (synced reviews). */
+  mentions?: string[];
+}
+
+export type RedlineStyleKey =
+  | 'display' | 'position' | 'width' | 'height' | 'margin' | 'padding' | 'gap' | 'font-family' | 'font-size'
+  | 'font-weight' | 'line-height' | 'color' | 'background-color' | 'border' | 'border-radius' | 'box-shadow'
+  | 'opacity' | 'object-fit';
+
+/** The element a comment is about, recorded once when it is made (1.6+). */
+export interface RedlineTarget {
+  label: string;
+  tag: string;
+  role: string | null;
+  name: string | null;
+  id: string | null;
+  testId: string | null;
+  classes: string[];
+  selector: string;
+  heading: string | null;
+  box: { x: number; y: number; w: number; h: number };
+  styles: Partial<Record<RedlineStyleKey, string>> | null;
+  component: { framework: 'react' | 'vue' | 'svelte'; chain: string[]; source: string | null } | null;
+}
+
+export interface RedlineMarkdownOptions {
+  detail?: 'compact' | 'standard' | 'detailed';
+  scope?: 'page' | 'site';
+  /** Include resolved and won't-fix comments. Default false. */
+  includeClosed?: boolean;
+  /** Only these comment ids. */
+  ids?: string[];
+}
+
+export interface RedlineCopyOptions {
+  format?: 'markdown' | 'json';
+  detail?: 'compact' | 'standard' | 'detailed';
+  scope?: 'page' | 'site';
+}
+
+/** Record schema v2 (docs/backlog/wire-protocol.md). */
+export interface RedlineComment {
+  schema: 2;
+  id: string;
+  page: string;
+  url: string;
+  type: 'highlight' | 'shape' | 'pin' | 'pen' | 'note' | 'block' | 'group';
+  author: string;
+  authorId: string | null;
+  text: string;
+  color: string;
+  anchor: { exact: string; prefix: string; suffix: string } | null;
+  geom: RedlineGeom | null;
+  /** Absent on comments made before 1.6 or where nothing could be described. */
+  target?: RedlineTarget;
+  /** Group comments only: one entry per `geom.selectors` item, `null` where nothing could be described. Create-only. */
+  targets?: (RedlineTarget | null)[];
+  visibility: 'shared' | 'private';
+  status: RedlineStatus;
+  /** Derived: true when status is "resolved" or "wont_fix". */
+  resolved: boolean;
+  resolvedBy: string | null;
+  resolvedAt: string | null;
+  assignee: RedlineAssignee | null;
+  /** Member ids mentioned (synced reviews). */
+  mentions?: string[];
+  assignedAt: string | null;
+  replies: RedlineReply[];
+  createdAt: string;
+  updatedAt: string;
+  editedAt: string | null;
+}
+
+export interface RedlineSyncState {
+  state: 'local' | 'idle' | 'pending' | 'offline' | 'error';
+  pending: number;
+}
+
+export interface FeedbackExport {
+  annotate: string;
+  schema: 2;
+  kind: 'annotate-export';
+  exportedAt: string;
+  page: string;
+  url: string;
+  project: string;
+  exportedViewport: { vw: number; vh: number; dpr: number };
+  /** "site" when the file holds every page of the project; absent for a page export. */
+  scope?: 'site';
+  comments: RedlineComment[];
+  /** Set when the body was POSTed to postUrl; the same value on every retry of one submit. */
+  deliveryId?: string;
+}
+
+export interface RedlineAPI {
+  readonly version: string;
+  readonly config: ResolvedRedlineConfig | null;
+  init(config?: RedlineConfig): RedlineAPI;
+  destroy(): void;
+  open(): void;
+  close(): void;
+  toggle(): void;
+  enable(): void;
+  disable(): void;
+  setTool(tool: 'cursor' | 'highlight' | 'rect' | 'circle' | 'pen' | 'pin'): void;
+  refresh(): void;
+  comments(): RedlineComment[];
+  focus(id: string): void;
+  toast(message: string, options?: { kind?: 'info' | 'error' | 'success'; duration?: number }): void;
+  /** Download this page's comments, or every page's with { scope: 'site' } (local mode). */
+  export(options?: { scope?: 'page' | 'site' }): void;
+  import(): void;
+  /**
+   * Local mode: sends the current page's export JSON to postUrl; rejects on failure.
+   * In a synced review: resolves once every queued change is acknowledged by the backend
+   * (then also POSTs to postUrl when set).
+   */
+  submit(): Promise<FeedbackExport>;
+  /** Moves a comment through its lifecycle. The creator and review authors may do this. */
+  setStatus(id: string, status: RedlineStatus): RedlineComment | null;
+  /** Assigns a comment to someone, or clears the assignee with null. Review authors only; the backend rejects a reviewer's change. */
+  assign(id: string, assignee: RedlineAssignee | null): RedlineComment | null;
+  /** Remote sync status; "local" when no backend is configured. */
+  syncState(): RedlineSyncState;
+  /** Markdown made for AI coding agents. "" when no comment qualifies. */
+  markdown(options?: RedlineMarkdownOptions): string;
+  /** Copies Markdown (default) or the JSON export to the clipboard. */
+  copy(options?: RedlineCopyOptions): Promise<void>;
+  /** Pauses page animations, transitions and media while reviewers comment. Refused (returns false) while the tools are hidden. Returns the new state. */
+  setFrozen(on: boolean): boolean;
+  /** Whether motion is currently frozen. */
+  isFrozen(): boolean;
+  /** Local mode: removes this page's comments. In a synced review: removes only your own. */
+  clear(): void;
+}
+
+declare const Redline: RedlineAPI;
+export function init(config?: RedlineConfig): RedlineAPI;
+export function destroy(): void;
+export default Redline;
+
+export interface RedlineEventMap {
+  'annotate:sync': CustomEvent<RedlineSyncState>;
+  'annotate:freeze': CustomEvent<{ frozen: boolean }>;
+  'annotate:auth': CustomEvent<{ reviewer: { id: string; name: string; role: 'reviewer' | 'author' } | null }>;
+}
+
+// annotate.js's type names, kept as aliases so code written for it compiles.
+/** @deprecated Use {@link RedlineAPI}. */
+export type AnnotateAPI = RedlineAPI;
+/** @deprecated Use {@link RedlineAssignee}. */
+export type AnnotateAssignee = RedlineAssignee;
+/** @deprecated Use {@link RedlineComment}. */
+export type AnnotateComment = RedlineComment;
+/** @deprecated Use {@link RedlineConfig}. */
+export type AnnotateConfig = RedlineConfig;
+/** @deprecated Use {@link RedlineCopyOptions}. */
+export type AnnotateCopyOptions = RedlineCopyOptions;
+/** @deprecated Use {@link RedlineEventMap}. */
+export type AnnotateEventMap = RedlineEventMap;
+/** @deprecated Use {@link RedlineGeom}. */
+export type AnnotateGeom = RedlineGeom;
+/** @deprecated Use {@link RedlineMarkdownOptions}. */
+export type AnnotateMarkdownOptions = RedlineMarkdownOptions;
+/** @deprecated Use {@link RedlineReply}. */
+export type AnnotateReply = RedlineReply;
+/** @deprecated Use {@link RedlineStatus}. */
+export type AnnotateStatus = RedlineStatus;
+/** @deprecated Use {@link RedlineStyleKey}. */
+export type AnnotateStyleKey = RedlineStyleKey;
+/** @deprecated Use {@link RedlineSyncState}. */
+export type AnnotateSyncState = RedlineSyncState;
+/** @deprecated Use {@link RedlineTarget}. */
+export type AnnotateTarget = RedlineTarget;
+/** @deprecated Use {@link ResolvedRedlineConfig}. */
+export type ResolvedAnnotateConfig = ResolvedRedlineConfig;
+
+declare global {
+  interface WindowEventMap extends RedlineEventMap {}
+  interface Window {
+    Redline?: RedlineAPI;
+    RedlineConfig?: RedlineConfig;
+    /** @deprecated annotate.js's name; the same object as window.Redline. */
+    Annotate?: RedlineAPI;
+    /** @deprecated annotate.js's name; use window.RedlineConfig. */
+    AnnotateConfig?: RedlineConfig;
+  }
+}