web-remarq 0.5.0 → 0.7.0

package/dist/core/index.d.cts

@@ -26,6 +26,16 @@ interface ElementFingerprint {
     detectedSource: string | null;
     detectedComponent: string | null;
 }
+type AnnotationStatus = 'pending' | 'in_progress' | 'fixed_unverified' | 'verified' | 'dismissed';
+type Actor = 'designer' | 'agent' | 'developer';
+type AnnotationEventType = 'created' | 'acknowledged' | 'fix_claimed' | 'verified' | 'rejected' | 'dismissed' | 'reopened' | 'migrated';
+interface AnnotationEvent {
+    type: AnnotationEventType;
+    actor: Actor | null;
+    actorName?: string;
+    timestamp: number;
+    reason?: string;
+}
 interface Annotation {
     id: string;
     comment: string;
@@ -34,7 +44,8 @@ interface Annotation {
     viewport: string;
     viewportBucket: number;
     timestamp: number;
-    status: 'pending' | 'resolved';
+    status: AnnotationStatus;
+    lifecycle: AnnotationEvent[];
 }
 interface AnnotationStore {
     version: 1;
@@ -47,6 +58,7 @@ interface WebRemarqOptions {
     dataAttribute?: string;
     position?: ToolbarPosition;
     shortcuts?: boolean;
+    storage?: StorageAdapter;
 }
 type SearchConfidence = 'high' | 'medium' | 'low';
 interface GrepQuery {
@@ -66,14 +78,21 @@ interface AgentAnnotationSource {
     column: number;
     component: string | null;
 }
+interface AgentLifecycleEvent {
+    type: AnnotationEventType;
+    actor: Actor | null;
+    timestamp: number;
+    reason?: string;
+}
 interface AgentAnnotation {
     id: string;
     route: string;
     comment: string;
-    status: 'pending' | 'resolved';
+    status: AnnotationStatus;
     timestamp: number;
     source: AgentAnnotationSource | null;
     searchHints: AgentSearchHints;
+    lifecycle: AgentLifecycleEvent[];
 }
 interface AgentExport {
     version: 1;
@@ -81,27 +100,54 @@ interface AgentExport {
     viewportBucket: number;
     annotations: AgentAnnotation[];
 }
+interface StorageChangeEvent {
+    type: 'add' | 'update' | 'remove' | 'clear';
+    annotation?: Annotation;
+    id?: string;
+}
+interface StorageAdapter {
+    load(): Promise<AnnotationStore | null>;
+    save(annotation: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    subscribe?(callback: (event: StorageChangeEvent) => void): () => void;
+    readonly isMemoryOnly?: boolean;
+}
 
 declare function createFingerprint(el: HTMLElement, options?: Pick<WebRemarqOptions, 'classFilter' | 'dataAttribute'>): ElementFingerprint;
 
 declare function matchElement(fp: ElementFingerprint, options?: Pick<WebRemarqOptions, 'dataAttribute'>): HTMLElement | null;
 
+declare function migrateAnnotation(legacy: any): Annotation;
 declare class AnnotationStorage {
-    private annotations;
-    private extraFields;
-    isMemoryOnly: boolean;
-    constructor();
+    private adapter;
+    private cache;
+    readonly ready: Promise<void>;
+    constructor(adapter: StorageAdapter);
+    get isMemoryOnly(): boolean;
     getAll(): Annotation[];
     getByRoute(route: string): Annotation[];
-    add(annotation: Annotation): void;
-    remove(id: string): void;
-    update(id: string, changes: Partial<Annotation>): void;
-    clearAll(): void;
+    getById(id: string): Annotation | undefined;
+    add(annotation: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    update(id: string, changes: Partial<Annotation>): Promise<void>;
+    clearAll(): Promise<void>;
     exportJSON(): AnnotationStore;
-    importJSON(data: AnnotationStore): void;
+    importJSON(data: AnnotationStore): Promise<void>;
+    private init;
     private migrateViewportBuckets;
-    private load;
-    private save;
+}
+
+declare class LocalStorageAdapter implements StorageAdapter {
+    isMemoryOnly: boolean;
+    private extraFields;
+    private memoryStore;
+    load(): Promise<AnnotationStore | null>;
+    save(annotation: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    private ensureStore;
+    private persist;
 }
 
 /**
@@ -116,4 +162,20 @@ declare function detectSource(el: HTMLElement): SourceDetectionResult;
 
 declare function generateAgentExport(annotations: Annotation[], viewportBucket: number): AgentExport;
 
-export { type AgentAnnotation, type AgentAnnotationSource, type AgentExport, type AgentSearchHints, type Annotation, AnnotationStorage, type AnnotationStore, type CSSModuleClass, type ElementFingerprint, type GrepQuery, type SearchConfidence, type SourceDetectionResult, type ToolbarPosition, createFingerprint, detectRemarqPlugin, detectSource, generateAgentExport, matchElement };
+type LifecycleAction = 'acknowledge' | 'claimFix' | 'verify' | 'reject' | 'dismiss' | 'reopen';
+declare class InvalidTransitionError extends Error {
+    constructor(from: AnnotationStatus, action: LifecycleAction);
+}
+interface EventOpts {
+    actor?: Actor;
+    actorName?: string;
+    reason?: string;
+    timestamp?: number;
+}
+declare function createEvent(type: AnnotationEventType, opts?: EventOpts): AnnotationEvent;
+declare function transition(annotation: Annotation, action: LifecycleAction, opts?: EventOpts): {
+    status: AnnotationStatus;
+    event: AnnotationEvent;
+};
+
+export { type Actor, type AgentAnnotation, type AgentAnnotationSource, type AgentExport, type AgentLifecycleEvent, type AgentSearchHints, type Annotation, type AnnotationEvent, type AnnotationEventType, type AnnotationStatus, AnnotationStorage, type AnnotationStore, type CSSModuleClass, type ElementFingerprint, type EventOpts, type GrepQuery, InvalidTransitionError, type LifecycleAction, LocalStorageAdapter, type SearchConfidence, type SourceDetectionResult, type StorageAdapter, type StorageChangeEvent, type ToolbarPosition, createEvent, createFingerprint, detectRemarqPlugin, detectSource, generateAgentExport, matchElement, migrateAnnotation, transition };

package/dist/core/index.d.ts

@@ -26,6 +26,16 @@ interface ElementFingerprint {
     detectedSource: string | null;
     detectedComponent: string | null;
 }
+type AnnotationStatus = 'pending' | 'in_progress' | 'fixed_unverified' | 'verified' | 'dismissed';
+type Actor = 'designer' | 'agent' | 'developer';
+type AnnotationEventType = 'created' | 'acknowledged' | 'fix_claimed' | 'verified' | 'rejected' | 'dismissed' | 'reopened' | 'migrated';
+interface AnnotationEvent {
+    type: AnnotationEventType;
+    actor: Actor | null;
+    actorName?: string;
+    timestamp: number;
+    reason?: string;
+}
 interface Annotation {
     id: string;
     comment: string;
@@ -34,7 +44,8 @@ interface Annotation {
     viewport: string;
     viewportBucket: number;
     timestamp: number;
-    status: 'pending' | 'resolved';
+    status: AnnotationStatus;
+    lifecycle: AnnotationEvent[];
 }
 interface AnnotationStore {
     version: 1;
@@ -47,6 +58,7 @@ interface WebRemarqOptions {
     dataAttribute?: string;
     position?: ToolbarPosition;
     shortcuts?: boolean;
+    storage?: StorageAdapter;
 }
 type SearchConfidence = 'high' | 'medium' | 'low';
 interface GrepQuery {
@@ -66,14 +78,21 @@ interface AgentAnnotationSource {
     column: number;
     component: string | null;
 }
+interface AgentLifecycleEvent {
+    type: AnnotationEventType;
+    actor: Actor | null;
+    timestamp: number;
+    reason?: string;
+}
 interface AgentAnnotation {
     id: string;
     route: string;
     comment: string;
-    status: 'pending' | 'resolved';
+    status: AnnotationStatus;
     timestamp: number;
     source: AgentAnnotationSource | null;
     searchHints: AgentSearchHints;
+    lifecycle: AgentLifecycleEvent[];
 }
 interface AgentExport {
     version: 1;
@@ -81,27 +100,54 @@ interface AgentExport {
     viewportBucket: number;
     annotations: AgentAnnotation[];
 }
+interface StorageChangeEvent {
+    type: 'add' | 'update' | 'remove' | 'clear';
+    annotation?: Annotation;
+    id?: string;
+}
+interface StorageAdapter {
+    load(): Promise<AnnotationStore | null>;
+    save(annotation: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    subscribe?(callback: (event: StorageChangeEvent) => void): () => void;
+    readonly isMemoryOnly?: boolean;
+}
 
 declare function createFingerprint(el: HTMLElement, options?: Pick<WebRemarqOptions, 'classFilter' | 'dataAttribute'>): ElementFingerprint;
 
 declare function matchElement(fp: ElementFingerprint, options?: Pick<WebRemarqOptions, 'dataAttribute'>): HTMLElement | null;
 
+declare function migrateAnnotation(legacy: any): Annotation;
 declare class AnnotationStorage {
-    private annotations;
-    private extraFields;
-    isMemoryOnly: boolean;
-    constructor();
+    private adapter;
+    private cache;
+    readonly ready: Promise<void>;
+    constructor(adapter: StorageAdapter);
+    get isMemoryOnly(): boolean;
     getAll(): Annotation[];
     getByRoute(route: string): Annotation[];
-    add(annotation: Annotation): void;
-    remove(id: string): void;
-    update(id: string, changes: Partial<Annotation>): void;
-    clearAll(): void;
+    getById(id: string): Annotation | undefined;
+    add(annotation: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    update(id: string, changes: Partial<Annotation>): Promise<void>;
+    clearAll(): Promise<void>;
     exportJSON(): AnnotationStore;
-    importJSON(data: AnnotationStore): void;
+    importJSON(data: AnnotationStore): Promise<void>;
+    private init;
     private migrateViewportBuckets;
-    private load;
-    private save;
+}
+
+declare class LocalStorageAdapter implements StorageAdapter {
+    isMemoryOnly: boolean;
+    private extraFields;
+    private memoryStore;
+    load(): Promise<AnnotationStore | null>;
+    save(annotation: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    private ensureStore;
+    private persist;
 }
 
 /**
@@ -116,4 +162,20 @@ declare function detectSource(el: HTMLElement): SourceDetectionResult;
 
 declare function generateAgentExport(annotations: Annotation[], viewportBucket: number): AgentExport;
 
-export { type AgentAnnotation, type AgentAnnotationSource, type AgentExport, type AgentSearchHints, type Annotation, AnnotationStorage, type AnnotationStore, type CSSModuleClass, type ElementFingerprint, type GrepQuery, type SearchConfidence, type SourceDetectionResult, type ToolbarPosition, createFingerprint, detectRemarqPlugin, detectSource, generateAgentExport, matchElement };
+type LifecycleAction = 'acknowledge' | 'claimFix' | 'verify' | 'reject' | 'dismiss' | 'reopen';
+declare class InvalidTransitionError extends Error {
+    constructor(from: AnnotationStatus, action: LifecycleAction);
+}
+interface EventOpts {
+    actor?: Actor;
+    actorName?: string;
+    reason?: string;
+    timestamp?: number;
+}
+declare function createEvent(type: AnnotationEventType, opts?: EventOpts): AnnotationEvent;
+declare function transition(annotation: Annotation, action: LifecycleAction, opts?: EventOpts): {
+    status: AnnotationStatus;
+    event: AnnotationEvent;
+};
+
+export { type Actor, type AgentAnnotation, type AgentAnnotationSource, type AgentExport, type AgentLifecycleEvent, type AgentSearchHints, type Annotation, type AnnotationEvent, type AnnotationEventType, type AnnotationStatus, AnnotationStorage, type AnnotationStore, type CSSModuleClass, type ElementFingerprint, type EventOpts, type GrepQuery, InvalidTransitionError, type LifecycleAction, LocalStorageAdapter, type SearchConfidence, type SourceDetectionResult, type StorageAdapter, type StorageChangeEvent, type ToolbarPosition, createEvent, createFingerprint, detectRemarqPlugin, detectSource, generateAgentExport, matchElement, migrateAnnotation, transition };

package/dist/core/index.js

@@ -351,79 +351,151 @@ function toBucket(width) {
 }
 
 // src/core/storage.ts
-var STORAGE_KEY = "remarq:annotations";
+function migrateAnnotation(legacy) {
+  const rawStatus = legacy.status;
+  const status = rawStatus === "resolved" ? "verified" : rawStatus;
+  if (Array.isArray(legacy.lifecycle) && legacy.lifecycle.length > 0) {
+    return __spreadProps(__spreadValues({}, legacy), { status, lifecycle: legacy.lifecycle });
+  }
+  const createdTs = typeof legacy.timestamp === "number" ? legacy.timestamp : Date.now();
+  const lifecycle = [
+    { type: "created", actor: "designer", timestamp: createdTs }
+  ];
+  if (rawStatus === "resolved") {
+    lifecycle.push({ type: "migrated", actor: null, timestamp: Date.now() });
+  }
+  return __spreadProps(__spreadValues({}, legacy), { status, lifecycle });
+}
 var AnnotationStorage = class {
-  constructor() {
-    this.annotations = [];
-    this.extraFields = {};
-    this.isMemoryOnly = false;
-    this.load();
+  constructor(adapter) {
+    this.adapter = adapter;
+    this.cache = [];
+    this.ready = this.init();
+  }
+  get isMemoryOnly() {
+    var _a;
+    return (_a = this.adapter.isMemoryOnly) != null ? _a : false;
   }
   getAll() {
-    return [...this.annotations];
+    return [...this.cache];
   }
   getByRoute(route) {
-    return this.annotations.filter((a) => a.route === route);
+    return this.cache.filter((a) => a.route === route);
   }
-  add(annotation) {
-    this.annotations.push(annotation);
-    this.save();
+  getById(id) {
+    return this.cache.find((a) => a.id === id);
   }
-  remove(id) {
-    this.annotations = this.annotations.filter((a) => a.id !== id);
-    this.save();
+  async add(annotation) {
+    this.cache.push(annotation);
+    await this.adapter.save(annotation);
   }
-  update(id, changes) {
-    const idx = this.annotations.findIndex((a) => a.id === id);
-    if (idx !== -1) {
-      this.annotations[idx] = __spreadValues(__spreadValues({}, this.annotations[idx]), changes);
-      this.save();
-    }
+  async remove(id) {
+    this.cache = this.cache.filter((a) => a.id !== id);
+    await this.adapter.remove(id);
+  }
+  async update(id, changes) {
+    const idx = this.cache.findIndex((a) => a.id === id);
+    if (idx === -1) return;
+    const updated = __spreadValues(__spreadValues({}, this.cache[idx]), changes);
+    this.cache[idx] = updated;
+    await this.adapter.save(updated);
   }
-  clearAll() {
-    this.annotations = [];
-    this.save();
+  async clearAll() {
+    this.cache = [];
+    await this.adapter.clear();
   }
   exportJSON() {
     return {
       version: 1,
-      annotations: [...this.annotations]
+      annotations: [...this.cache]
     };
   }
-  importJSON(data) {
-    this.annotations = [...data.annotations];
+  async importJSON(data) {
+    this.cache = data.annotations.map(migrateAnnotation);
     this.migrateViewportBuckets();
-    this.save();
+    await this.adapter.clear();
+    for (const ann of this.cache) {
+      await this.adapter.save(ann);
+    }
+  }
+  async init() {
+    const data = await this.adapter.load();
+    if (data) {
+      this.cache = data.annotations.map(migrateAnnotation);
+      this.migrateViewportBuckets();
+    }
   }
   migrateViewportBuckets() {
-    for (const ann of this.annotations) {
+    for (const ann of this.cache) {
       if (ann.viewportBucket == null && ann.viewport) {
         const width = parseInt(ann.viewport.split("x")[0], 10);
         ann.viewportBucket = toBucket(width);
       }
     }
   }
-  load() {
+};
+
+// src/core/local-storage-adapter.ts
+var STORAGE_KEY = "remarq:annotations";
+var LocalStorageAdapter = class {
+  constructor() {
+    this.isMemoryOnly = false;
+    this.extraFields = {};
+    this.memoryStore = null;
+  }
+  async load() {
+    if (this.isMemoryOnly) return this.memoryStore;
     try {
       const raw = localStorage.getItem(STORAGE_KEY);
-      if (raw) {
-        const parsed = JSON.parse(raw);
-        const _a = parsed, { version, annotations } = _a, rest = __objRest(_a, ["version", "annotations"]);
-        this.annotations = annotations != null ? annotations : [];
-        this.extraFields = rest;
-        this.migrateViewportBuckets();
-      }
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      const _a = parsed, { version, annotations } = _a, rest = __objRest(_a, ["version", "annotations"]);
+      this.extraFields = rest;
+      const store = {
+        version: 1,
+        annotations: Array.isArray(annotations) ? annotations : []
+      };
+      this.memoryStore = store;
+      return store;
     } catch (e) {
       this.isMemoryOnly = true;
+      return this.memoryStore;
     }
   }
-  save() {
+  async save(annotation) {
+    const store = await this.ensureStore();
+    const idx = store.annotations.findIndex((a) => a.id === annotation.id);
+    if (idx === -1) {
+      store.annotations.push(annotation);
+    } else {
+      store.annotations[idx] = annotation;
+    }
+    this.persist(store);
+  }
+  async remove(id) {
+    const store = await this.ensureStore();
+    store.annotations = store.annotations.filter((a) => a.id !== id);
+    this.persist(store);
+  }
+  async clear() {
+    const store = await this.ensureStore();
+    store.annotations = [];
+    this.persist(store);
+  }
+  async ensureStore() {
+    if (this.memoryStore) return this.memoryStore;
+    const loaded = await this.load();
+    if (loaded) return loaded;
+    this.memoryStore = { version: 1, annotations: [] };
+    return this.memoryStore;
+  }
+  persist(store) {
     if (this.isMemoryOnly) return;
     try {
       const data = __spreadProps(__spreadValues({
         version: 1
       }, this.extraFields), {
-        annotations: this.annotations
+        annotations: store.annotations
       });
       localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
     } catch (e) {
@@ -504,7 +576,16 @@ function generateAgentExport(annotations, viewportBucket) {
     status: ann.status,
     timestamp: ann.timestamp,
     source: resolveSource(ann.fingerprint),
-    searchHints: buildSearchHints(ann.fingerprint)
+    searchHints: buildSearchHints(ann.fingerprint),
+    lifecycle: ann.lifecycle.map((ev) => {
+      const out = {
+        type: ev.type,
+        actor: ev.actor,
+        timestamp: ev.timestamp
+      };
+      if (ev.reason !== void 0) out.reason = ev.reason;
+      return out;
+    })
   }));
   return {
     version: 1,
@@ -513,12 +594,78 @@ function generateAgentExport(annotations, viewportBucket) {
     annotations: agentAnnotations
   };
 }
+
+// src/core/lifecycle.ts
+var InvalidTransitionError = class extends Error {
+  constructor(from, action) {
+    super(`Cannot ${action} from status "${from}"`);
+    this.name = "InvalidTransitionError";
+  }
+};
+var ACTION_TO_EVENT = {
+  acknowledge: "acknowledged",
+  claimFix: "fix_claimed",
+  verify: "verified",
+  reject: "rejected",
+  dismiss: "dismissed",
+  reopen: "reopened"
+};
+var DEFAULT_ACTOR_BY_EVENT = {
+  created: "designer",
+  acknowledged: "developer",
+  fix_claimed: "agent",
+  verified: "developer",
+  rejected: "developer",
+  dismissed: "developer",
+  reopened: "developer",
+  migrated: null
+};
+function createEvent(type, opts = {}) {
+  var _a, _b;
+  const event = {
+    type,
+    actor: (_a = opts.actor) != null ? _a : DEFAULT_ACTOR_BY_EVENT[type],
+    timestamp: (_b = opts.timestamp) != null ? _b : Date.now()
+  };
+  if (opts.actorName !== void 0) event.actorName = opts.actorName;
+  if (opts.reason !== void 0) event.reason = opts.reason;
+  return event;
+}
+function nextStatus(from, action) {
+  switch (action) {
+    case "acknowledge":
+      return from === "pending" ? "in_progress" : null;
+    case "claimFix":
+      return from === "pending" || from === "in_progress" ? "fixed_unverified" : null;
+    case "verify":
+      return from === "fixed_unverified" || from === "in_progress" ? "verified" : null;
+    case "reject":
+      return from === "fixed_unverified" ? "pending" : null;
+    case "dismiss":
+      return from === "pending" || from === "in_progress" || from === "fixed_unverified" ? "dismissed" : null;
+    case "reopen":
+      return from === "dismissed" || from === "verified" ? "pending" : null;
+  }
+}
+function transition(annotation, action, opts = {}) {
+  const next = nextStatus(annotation.status, action);
+  if (next === null) {
+    throw new InvalidTransitionError(annotation.status, action);
+  }
+  const event = createEvent(ACTION_TO_EVENT[action], opts);
+  return { status: next, event };
+}
 export {
   AnnotationStorage,
+  InvalidTransitionError,
+  LocalStorageAdapter,
+  createEvent,
   createFingerprint,
   detectRemarqPlugin,
   detectSource,
   generateAgentExport,
-  matchElement
+  matchElement,
+  migrateAnnotation,
+  transition
 };
 //# sourceMappingURL=index.js.map