@qontinui/ui-bridge 0.3.0 → 0.3.1

package/dist/annotations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/annotations/types.ts","../../src/annotations/store.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Annotation Types\n *\n * Types for the semantic annotation system that allows developers\n * to attach rich human-authored context to UI elements.\n */\n\n/**\n * Annotation for a single UI element.\n *\n * All fields are optional - annotate only what's useful.\n * Annotations provide human-authored semantic context that enriches\n * the UI Bridge's understanding of elements beyond what can be\n * inferred from the DOM alone.\n *\n * @example Basic annotation for a button\n * ```ts\n * const annotation: ElementAnnotation = {\n *   description: 'Primary login button',\n *   purpose: 'Submits the login form and authenticates the user',\n *   tags: ['auth', 'primary-action'],\n * };\n * store.set('login-btn', annotation);\n * ```\n *\n * @example Detailed annotation with relationships and metadata\n * ```ts\n * const annotation: ElementAnnotation = {\n *   description: 'Email input field',\n *   purpose: 'Collects the user email for authentication',\n *   notes: 'Validates email format on blur. Shows inline error below the field.',\n *   tags: ['auth', 'form-input', 'required'],\n *   relatedElements: ['email-label', 'email-error', 'login-btn'],\n *   metadata: { validationPattern: '^[^@]+@[^@]+\\\\.[^@]+$' },\n *   author: 'design-team',\n * };\n * ```\n */\nexport interface ElementAnnotation {\n  /** Human-readable description of what this element is */\n  description?: string;\n  /** Why this element exists / what it's for */\n  purpose?: string;\n  /** Behavioral notes, edge cases, or caveats */\n  notes?: string;\n  /** Searchable tags for categorization */\n  tags?: string[];\n  /** IDs of related elements (e.g., a label and its input) */\n  relatedElements?: string[];\n  /** Arbitrary key-value metadata */\n  metadata?: Record<string, unknown>;\n  /** Timestamp of last update (auto-set by store) */\n  updatedAt?: number;\n  /** Author of this annotation */\n  author?: string;\n}\n\n/**\n * Annotation configuration file format.\n *\n * This is the import/export format - a JSON file with version and annotations map.\n * Use `AnnotationStore.exportConfig()` to generate this object, and\n * `AnnotationStore.importConfig()` to load it back.\n *\n * @example JSON file format (`annotations.json`)\n * ```json\n * {\n *   \"version\": \"1.0.0\",\n *   \"annotations\": {\n *     \"login-btn\": {\n *       \"description\": \"Primary login button\",\n *       \"purpose\": \"Submits the login form\",\n *       \"tags\": [\"auth\", \"primary-action\"]\n *     },\n *     \"email-input\": {\n *       \"description\": \"Email address input\",\n *       \"purpose\": \"Collects user email for authentication\",\n *       \"relatedElements\": [\"email-label\", \"email-error\"]\n *     }\n *   },\n *   \"metadata\": {\n *     \"appName\": \"MyApp\",\n *     \"description\": \"Annotations for the login page\"\n *   }\n * }\n * ```\n */\nexport interface AnnotationConfig {\n  /** Config format version */\n  version: string;\n  /** Map of element ID to annotation */\n  annotations: Record<string, ElementAnnotation>;\n  /** Optional file-level metadata */\n  metadata?: {\n    appName?: string;\n    exportedAt?: number;\n    description?: string;\n  };\n}\n\n/**\n * Annotation coverage statistics.\n */\nexport interface AnnotationCoverage {\n  /** Total elements known to the system */\n  totalElements: number;\n  /** Elements that have annotations */\n  annotatedElements: number;\n  /** Coverage as a percentage (0-100) */\n  coveragePercent: number;\n  /** IDs of annotated elements */\n  annotatedIds: string[];\n  /** IDs of unannotated elements */\n  unannotatedIds: string[];\n  /** When this coverage was computed */\n  timestamp: number;\n}\n\n/**\n * Event types emitted by the annotation store.\n */\nexport type AnnotationEventType =\n  | 'annotation:set'\n  | 'annotation:deleted'\n  | 'annotation:imported'\n  | 'annotation:cleared';\n\n/**\n * Event payload for annotation store events.\n */\nexport interface AnnotationEvent {\n  type: AnnotationEventType;\n  elementId?: string;\n  annotation?: ElementAnnotation;\n  count?: number;\n  timestamp: number;\n}\n\n/** Current annotation config version */\nexport const ANNOTATION_CONFIG_VERSION = '1.0.0';\n","/**\n * Annotation Store\n *\n * In-memory store for element annotations with CRUD operations,\n * import/export, coverage tracking, and event emission.\n */\n\nimport type {\n  ElementAnnotation,\n  AnnotationConfig,\n  AnnotationCoverage,\n  AnnotationEvent,\n} from './types';\nimport { ANNOTATION_CONFIG_VERSION } from './types';\n\n/**\n * Listener function for annotation events.\n */\nexport type AnnotationListener = (event: AnnotationEvent) => void;\n\n/**\n * Annotation Store\n *\n * Stores element annotations in memory with event-driven updates.\n * Provides CRUD operations, import/export, coverage tracking, and\n * an event system for reacting to annotation changes.\n *\n * @example Basic CRUD usage\n * ```ts\n * const store = new AnnotationStore();\n *\n * // Set an annotation\n * store.set('login-btn', {\n *   description: 'Primary login button',\n *   purpose: 'Submits the login form',\n *   tags: ['auth', 'primary-action'],\n * });\n *\n * // Read it back\n * const annotation = store.get('login-btn');\n * console.log(annotation?.description); // 'Primary login button'\n *\n * // Check existence\n * store.has('login-btn'); // true\n *\n * // Delete it\n * store.delete('login-btn'); // true\n * ```\n *\n * @example Import/export workflow\n * ```ts\n * const store = new AnnotationStore();\n *\n * // Import from a config file\n * const config = JSON.parse(fs.readFileSync('annotations.json', 'utf-8'));\n * const count = store.importConfig(config);\n * console.log(`Imported ${count} annotations`);\n *\n * // Export current state\n * const exported = store.exportConfig({ appName: 'MyApp' });\n * fs.writeFileSync('annotations.json', JSON.stringify(exported, null, 2));\n * ```\n *\n * @example Listening for changes\n * ```ts\n * const store = new AnnotationStore();\n *\n * const unsubscribe = store.on((event) => {\n *   switch (event.type) {\n *     case 'annotation:set':\n *       console.log(`Updated: ${event.elementId}`);\n *       break;\n *     case 'annotation:deleted':\n *       console.log(`Deleted: ${event.elementId}`);\n *       break;\n *     case 'annotation:imported':\n *       console.log(`Imported ${event.count} annotations`);\n *       break;\n *     case 'annotation:cleared':\n *       console.log('All annotations cleared');\n *       break;\n *   }\n * });\n *\n * // Later, stop listening\n * unsubscribe();\n * ```\n */\nexport class AnnotationStore {\n  private store = new Map<string, ElementAnnotation>();\n  private listeners = new Set<AnnotationListener>();\n\n  /**\n   * Get an annotation by element ID.\n   */\n  get(elementId: string): ElementAnnotation | undefined {\n    return this.store.get(elementId);\n  }\n\n  /**\n   * Get all annotations as a record.\n   */\n  getAll(): Record<string, ElementAnnotation> {\n    const result: Record<string, ElementAnnotation> = {};\n    for (const [id, annotation] of this.store) {\n      result[id] = annotation;\n    }\n    return result;\n  }\n\n  /**\n   * Set an annotation for an element. Auto-sets `updatedAt`.\n   */\n  set(elementId: string, annotation: ElementAnnotation): void {\n    const updated: ElementAnnotation = {\n      ...annotation,\n      updatedAt: Date.now(),\n    };\n    this.store.set(elementId, updated);\n    this.emit({\n      type: 'annotation:set',\n      elementId,\n      annotation: updated,\n      timestamp: Date.now(),\n    });\n  }\n\n  /**\n   * Delete an annotation by element ID.\n   *\n   * @returns true if the annotation existed and was deleted\n   */\n  delete(elementId: string): boolean {\n    const existed = this.store.delete(elementId);\n    if (existed) {\n      this.emit({\n        type: 'annotation:deleted',\n        elementId,\n        timestamp: Date.now(),\n      });\n    }\n    return existed;\n  }\n\n  /**\n   * Check if an annotation exists for an element.\n   */\n  has(elementId: string): boolean {\n    return this.store.has(elementId);\n  }\n\n  /**\n   * Get the number of stored annotations.\n   */\n  get count(): number {\n    return this.store.size;\n  }\n\n  /**\n   * Clear all annotations.\n   */\n  clear(): void {\n    this.store.clear();\n    this.emit({\n      type: 'annotation:cleared',\n      timestamp: Date.now(),\n    });\n  }\n\n  /**\n   * Import annotations from a config object.\n   *\n   * Merges with existing annotations (new values overwrite per element ID).\n   *\n   * @returns Number of annotations imported\n   *\n   * @example\n   * ```ts\n   * const config: AnnotationConfig = {\n   *   version: '1.0.0',\n   *   annotations: {\n   *     'btn-1': { description: 'Submit button', tags: ['form'] },\n   *     'input-1': { description: 'Name field' },\n   *   },\n   * };\n   * const count = store.importConfig(config); // 2\n   * ```\n   */\n  importConfig(config: AnnotationConfig): number {\n    let count = 0;\n    for (const [id, annotation] of Object.entries(config.annotations)) {\n      this.store.set(id, {\n        ...annotation,\n        updatedAt: annotation.updatedAt ?? Date.now(),\n      });\n      count++;\n    }\n    this.emit({\n      type: 'annotation:imported',\n      count,\n      timestamp: Date.now(),\n    });\n    return count;\n  }\n\n  /**\n   * Export all annotations as a config object.\n   *\n   * The returned object can be serialized to JSON and saved to a file,\n   * then later re-imported with {@link importConfig}.\n   *\n   * @param metadata - Optional metadata to include (appName, description, etc.)\n   * @returns AnnotationConfig with all current annotations\n   *\n   * @example\n   * ```ts\n   * const config = store.exportConfig({ appName: 'MyApp' });\n   * // config.version === '1.0.0'\n   * // config.annotations === { 'btn-1': { ... }, 'input-1': { ... } }\n   * // config.metadata === { appName: 'MyApp', exportedAt: 1706900000000 }\n   *\n   * // Save to file\n   * fs.writeFileSync('annotations.json', JSON.stringify(config, null, 2));\n   * ```\n   */\n  exportConfig(metadata?: AnnotationConfig['metadata']): AnnotationConfig {\n    return {\n      version: ANNOTATION_CONFIG_VERSION,\n      annotations: this.getAll(),\n      metadata: {\n        ...metadata,\n        exportedAt: Date.now(),\n      },\n    };\n  }\n\n  /**\n   * Compute annotation coverage against a set of known element IDs.\n   *\n   * Compares the store's annotations against the provided list of element IDs\n   * to determine what percentage of elements have been annotated.\n   *\n   * @param allElementIds - Array of all known element IDs in the UI\n   * @returns Coverage statistics including percentages and lists of annotated/unannotated IDs\n   *\n   * @example\n   * ```ts\n   * store.set('btn-1', { description: 'Submit' });\n   * store.set('input-1', { description: 'Name' });\n   *\n   * const coverage = store.getCoverage(['btn-1', 'input-1', 'input-2', 'link-1']);\n   * // coverage.totalElements === 4\n   * // coverage.annotatedElements === 2\n   * // coverage.coveragePercent === 50\n   * // coverage.annotatedIds === ['btn-1', 'input-1']\n   * // coverage.unannotatedIds === ['input-2', 'link-1']\n   * ```\n   */\n  getCoverage(allElementIds: string[]): AnnotationCoverage {\n    const annotatedIds: string[] = [];\n    const unannotatedIds: string[] = [];\n\n    for (const id of allElementIds) {\n      if (this.store.has(id)) {\n        annotatedIds.push(id);\n      } else {\n        unannotatedIds.push(id);\n      }\n    }\n\n    const total = allElementIds.length;\n    return {\n      totalElements: total,\n      annotatedElements: annotatedIds.length,\n      coveragePercent: total > 0 ? (annotatedIds.length / total) * 100 : 0,\n      annotatedIds,\n      unannotatedIds,\n      timestamp: Date.now(),\n    };\n  }\n\n  /**\n   * Subscribe to annotation events.\n   *\n   * The listener is called whenever annotations are set, deleted, imported,\n   * or cleared. Returns an unsubscribe function to stop listening.\n   *\n   * @param listener - Callback function receiving {@link AnnotationEvent} objects\n   * @returns Unsubscribe function - call it to remove the listener\n   *\n   * @example\n   * ```ts\n   * const unsubscribe = store.on((event) => {\n   *   if (event.type === 'annotation:set') {\n   *     console.log(`Element ${event.elementId} annotated:`, event.annotation);\n   *   }\n   * });\n   *\n   * store.set('btn-1', { description: 'Submit' });\n   * // Logs: \"Element btn-1 annotated: { description: 'Submit', updatedAt: ... }\"\n   *\n   * unsubscribe(); // Stop listening\n   * ```\n   */\n  on(listener: AnnotationListener): () => void {\n    this.listeners.add(listener);\n    return () => {\n      this.listeners.delete(listener);\n    };\n  }\n\n  /**\n   * Emit an event to all listeners.\n   */\n  private emit(event: AnnotationEvent): void {\n    for (const listener of this.listeners) {\n      try {\n        listener(event);\n      } catch {\n        // Don't let listener errors break the store\n      }\n    }\n  }\n}\n\n// Global singleton\nlet globalStore: AnnotationStore | null = null;\n\n/**\n * Get the global annotation store singleton.\n */\nexport function getGlobalAnnotationStore(): AnnotationStore {\n  if (!globalStore) {\n    globalStore = new AnnotationStore();\n  }\n  return globalStore;\n}\n\n/**\n * Reset the global annotation store (primarily for testing).\n */\nexport function resetGlobalAnnotationStore(): void {\n  globalStore = null;\n}\n"]}

package/dist/annotations/index.mjs

@@ -0,0 +1,241 @@
+// src/annotations/types.ts
+var ANNOTATION_CONFIG_VERSION = "1.0.0";
+
+// src/annotations/store.ts
+var AnnotationStore = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Get an annotation by element ID.
+   */
+  get(elementId) {
+    return this.store.get(elementId);
+  }
+  /**
+   * Get all annotations as a record.
+   */
+  getAll() {
+    const result = {};
+    for (const [id, annotation] of this.store) {
+      result[id] = annotation;
+    }
+    return result;
+  }
+  /**
+   * Set an annotation for an element. Auto-sets `updatedAt`.
+   */
+  set(elementId, annotation) {
+    const updated = {
+      ...annotation,
+      updatedAt: Date.now()
+    };
+    this.store.set(elementId, updated);
+    this.emit({
+      type: "annotation:set",
+      elementId,
+      annotation: updated,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Delete an annotation by element ID.
+   *
+   * @returns true if the annotation existed and was deleted
+   */
+  delete(elementId) {
+    const existed = this.store.delete(elementId);
+    if (existed) {
+      this.emit({
+        type: "annotation:deleted",
+        elementId,
+        timestamp: Date.now()
+      });
+    }
+    return existed;
+  }
+  /**
+   * Check if an annotation exists for an element.
+   */
+  has(elementId) {
+    return this.store.has(elementId);
+  }
+  /**
+   * Get the number of stored annotations.
+   */
+  get count() {
+    return this.store.size;
+  }
+  /**
+   * Clear all annotations.
+   */
+  clear() {
+    this.store.clear();
+    this.emit({
+      type: "annotation:cleared",
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Import annotations from a config object.
+   *
+   * Merges with existing annotations (new values overwrite per element ID).
+   *
+   * @returns Number of annotations imported
+   *
+   * @example
+   * ```ts
+   * const config: AnnotationConfig = {
+   *   version: '1.0.0',
+   *   annotations: {
+   *     'btn-1': { description: 'Submit button', tags: ['form'] },
+   *     'input-1': { description: 'Name field' },
+   *   },
+   * };
+   * const count = store.importConfig(config); // 2
+   * ```
+   */
+  importConfig(config) {
+    let count = 0;
+    for (const [id, annotation] of Object.entries(config.annotations)) {
+      this.store.set(id, {
+        ...annotation,
+        updatedAt: annotation.updatedAt ?? Date.now()
+      });
+      count++;
+    }
+    this.emit({
+      type: "annotation:imported",
+      count,
+      timestamp: Date.now()
+    });
+    return count;
+  }
+  /**
+   * Export all annotations as a config object.
+   *
+   * The returned object can be serialized to JSON and saved to a file,
+   * then later re-imported with {@link importConfig}.
+   *
+   * @param metadata - Optional metadata to include (appName, description, etc.)
+   * @returns AnnotationConfig with all current annotations
+   *
+   * @example
+   * ```ts
+   * const config = store.exportConfig({ appName: 'MyApp' });
+   * // config.version === '1.0.0'
+   * // config.annotations === { 'btn-1': { ... }, 'input-1': { ... } }
+   * // config.metadata === { appName: 'MyApp', exportedAt: 1706900000000 }
+   *
+   * // Save to file
+   * fs.writeFileSync('annotations.json', JSON.stringify(config, null, 2));
+   * ```
+   */
+  exportConfig(metadata) {
+    return {
+      version: ANNOTATION_CONFIG_VERSION,
+      annotations: this.getAll(),
+      metadata: {
+        ...metadata,
+        exportedAt: Date.now()
+      }
+    };
+  }
+  /**
+   * Compute annotation coverage against a set of known element IDs.
+   *
+   * Compares the store's annotations against the provided list of element IDs
+   * to determine what percentage of elements have been annotated.
+   *
+   * @param allElementIds - Array of all known element IDs in the UI
+   * @returns Coverage statistics including percentages and lists of annotated/unannotated IDs
+   *
+   * @example
+   * ```ts
+   * store.set('btn-1', { description: 'Submit' });
+   * store.set('input-1', { description: 'Name' });
+   *
+   * const coverage = store.getCoverage(['btn-1', 'input-1', 'input-2', 'link-1']);
+   * // coverage.totalElements === 4
+   * // coverage.annotatedElements === 2
+   * // coverage.coveragePercent === 50
+   * // coverage.annotatedIds === ['btn-1', 'input-1']
+   * // coverage.unannotatedIds === ['input-2', 'link-1']
+   * ```
+   */
+  getCoverage(allElementIds) {
+    const annotatedIds = [];
+    const unannotatedIds = [];
+    for (const id of allElementIds) {
+      if (this.store.has(id)) {
+        annotatedIds.push(id);
+      } else {
+        unannotatedIds.push(id);
+      }
+    }
+    const total = allElementIds.length;
+    return {
+      totalElements: total,
+      annotatedElements: annotatedIds.length,
+      coveragePercent: total > 0 ? annotatedIds.length / total * 100 : 0,
+      annotatedIds,
+      unannotatedIds,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Subscribe to annotation events.
+   *
+   * The listener is called whenever annotations are set, deleted, imported,
+   * or cleared. Returns an unsubscribe function to stop listening.
+   *
+   * @param listener - Callback function receiving {@link AnnotationEvent} objects
+   * @returns Unsubscribe function - call it to remove the listener
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = store.on((event) => {
+   *   if (event.type === 'annotation:set') {
+   *     console.log(`Element ${event.elementId} annotated:`, event.annotation);
+   *   }
+   * });
+   *
+   * store.set('btn-1', { description: 'Submit' });
+   * // Logs: "Element btn-1 annotated: { description: 'Submit', updatedAt: ... }"
+   *
+   * unsubscribe(); // Stop listening
+   * ```
+   */
+  on(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Emit an event to all listeners.
+   */
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+};
+var globalStore = null;
+function getGlobalAnnotationStore() {
+  if (!globalStore) {
+    globalStore = new AnnotationStore();
+  }
+  return globalStore;
+}
+function resetGlobalAnnotationStore() {
+  globalStore = null;
+}
+
+export { ANNOTATION_CONFIG_VERSION, AnnotationStore, getGlobalAnnotationStore, resetGlobalAnnotationStore };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/annotations/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/annotations/types.ts","../../src/annotations/store.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Annotation Types\n *\n * Types for the semantic annotation system that allows developers\n * to attach rich human-authored context to UI elements.\n */\n\n/**\n * Annotation for a single UI element.\n *\n * All fields are optional - annotate only what's useful.\n * Annotations provide human-authored semantic context that enriches\n * the UI Bridge's understanding of elements beyond what can be\n * inferred from the DOM alone.\n *\n * @example Basic annotation for a button\n * ```ts\n * const annotation: ElementAnnotation = {\n *   description: 'Primary login button',\n *   purpose: 'Submits the login form and authenticates the user',\n *   tags: ['auth', 'primary-action'],\n * };\n * store.set('login-btn', annotation);\n * ```\n *\n * @example Detailed annotation with relationships and metadata\n * ```ts\n * const annotation: ElementAnnotation = {\n *   description: 'Email input field',\n *   purpose: 'Collects the user email for authentication',\n *   notes: 'Validates email format on blur. Shows inline error below the field.',\n *   tags: ['auth', 'form-input', 'required'],\n *   relatedElements: ['email-label', 'email-error', 'login-btn'],\n *   metadata: { validationPattern: '^[^@]+@[^@]+\\\\.[^@]+$' },\n *   author: 'design-team',\n * };\n * ```\n */\nexport interface ElementAnnotation {\n  /** Human-readable description of what this element is */\n  description?: string;\n  /** Why this element exists / what it's for */\n  purpose?: string;\n  /** Behavioral notes, edge cases, or caveats */\n  notes?: string;\n  /** Searchable tags for categorization */\n  tags?: string[];\n  /** IDs of related elements (e.g., a label and its input) */\n  relatedElements?: string[];\n  /** Arbitrary key-value metadata */\n  metadata?: Record<string, unknown>;\n  /** Timestamp of last update (auto-set by store) */\n  updatedAt?: number;\n  /** Author of this annotation */\n  author?: string;\n}\n\n/**\n * Annotation configuration file format.\n *\n * This is the import/export format - a JSON file with version and annotations map.\n * Use `AnnotationStore.exportConfig()` to generate this object, and\n * `AnnotationStore.importConfig()` to load it back.\n *\n * @example JSON file format (`annotations.json`)\n * ```json\n * {\n *   \"version\": \"1.0.0\",\n *   \"annotations\": {\n *     \"login-btn\": {\n *       \"description\": \"Primary login button\",\n *       \"purpose\": \"Submits the login form\",\n *       \"tags\": [\"auth\", \"primary-action\"]\n *     },\n *     \"email-input\": {\n *       \"description\": \"Email address input\",\n *       \"purpose\": \"Collects user email for authentication\",\n *       \"relatedElements\": [\"email-label\", \"email-error\"]\n *     }\n *   },\n *   \"metadata\": {\n *     \"appName\": \"MyApp\",\n *     \"description\": \"Annotations for the login page\"\n *   }\n * }\n * ```\n */\nexport interface AnnotationConfig {\n  /** Config format version */\n  version: string;\n  /** Map of element ID to annotation */\n  annotations: Record<string, ElementAnnotation>;\n  /** Optional file-level metadata */\n  metadata?: {\n    appName?: string;\n    exportedAt?: number;\n    description?: string;\n  };\n}\n\n/**\n * Annotation coverage statistics.\n */\nexport interface AnnotationCoverage {\n  /** Total elements known to the system */\n  totalElements: number;\n  /** Elements that have annotations */\n  annotatedElements: number;\n  /** Coverage as a percentage (0-100) */\n  coveragePercent: number;\n  /** IDs of annotated elements */\n  annotatedIds: string[];\n  /** IDs of unannotated elements */\n  unannotatedIds: string[];\n  /** When this coverage was computed */\n  timestamp: number;\n}\n\n/**\n * Event types emitted by the annotation store.\n */\nexport type AnnotationEventType =\n  | 'annotation:set'\n  | 'annotation:deleted'\n  | 'annotation:imported'\n  | 'annotation:cleared';\n\n/**\n * Event payload for annotation store events.\n */\nexport interface AnnotationEvent {\n  type: AnnotationEventType;\n  elementId?: string;\n  annotation?: ElementAnnotation;\n  count?: number;\n  timestamp: number;\n}\n\n/** Current annotation config version */\nexport const ANNOTATION_CONFIG_VERSION = '1.0.0';\n","/**\n * Annotation Store\n *\n * In-memory store for element annotations with CRUD operations,\n * import/export, coverage tracking, and event emission.\n */\n\nimport type {\n  ElementAnnotation,\n  AnnotationConfig,\n  AnnotationCoverage,\n  AnnotationEvent,\n} from './types';\nimport { ANNOTATION_CONFIG_VERSION } from './types';\n\n/**\n * Listener function for annotation events.\n */\nexport type AnnotationListener = (event: AnnotationEvent) => void;\n\n/**\n * Annotation Store\n *\n * Stores element annotations in memory with event-driven updates.\n * Provides CRUD operations, import/export, coverage tracking, and\n * an event system for reacting to annotation changes.\n *\n * @example Basic CRUD usage\n * ```ts\n * const store = new AnnotationStore();\n *\n * // Set an annotation\n * store.set('login-btn', {\n *   description: 'Primary login button',\n *   purpose: 'Submits the login form',\n *   tags: ['auth', 'primary-action'],\n * });\n *\n * // Read it back\n * const annotation = store.get('login-btn');\n * console.log(annotation?.description); // 'Primary login button'\n *\n * // Check existence\n * store.has('login-btn'); // true\n *\n * // Delete it\n * store.delete('login-btn'); // true\n * ```\n *\n * @example Import/export workflow\n * ```ts\n * const store = new AnnotationStore();\n *\n * // Import from a config file\n * const config = JSON.parse(fs.readFileSync('annotations.json', 'utf-8'));\n * const count = store.importConfig(config);\n * console.log(`Imported ${count} annotations`);\n *\n * // Export current state\n * const exported = store.exportConfig({ appName: 'MyApp' });\n * fs.writeFileSync('annotations.json', JSON.stringify(exported, null, 2));\n * ```\n *\n * @example Listening for changes\n * ```ts\n * const store = new AnnotationStore();\n *\n * const unsubscribe = store.on((event) => {\n *   switch (event.type) {\n *     case 'annotation:set':\n *       console.log(`Updated: ${event.elementId}`);\n *       break;\n *     case 'annotation:deleted':\n *       console.log(`Deleted: ${event.elementId}`);\n *       break;\n *     case 'annotation:imported':\n *       console.log(`Imported ${event.count} annotations`);\n *       break;\n *     case 'annotation:cleared':\n *       console.log('All annotations cleared');\n *       break;\n *   }\n * });\n *\n * // Later, stop listening\n * unsubscribe();\n * ```\n */\nexport class AnnotationStore {\n  private store = new Map<string, ElementAnnotation>();\n  private listeners = new Set<AnnotationListener>();\n\n  /**\n   * Get an annotation by element ID.\n   */\n  get(elementId: string): ElementAnnotation | undefined {\n    return this.store.get(elementId);\n  }\n\n  /**\n   * Get all annotations as a record.\n   */\n  getAll(): Record<string, ElementAnnotation> {\n    const result: Record<string, ElementAnnotation> = {};\n    for (const [id, annotation] of this.store) {\n      result[id] = annotation;\n    }\n    return result;\n  }\n\n  /**\n   * Set an annotation for an element. Auto-sets `updatedAt`.\n   */\n  set(elementId: string, annotation: ElementAnnotation): void {\n    const updated: ElementAnnotation = {\n      ...annotation,\n      updatedAt: Date.now(),\n    };\n    this.store.set(elementId, updated);\n    this.emit({\n      type: 'annotation:set',\n      elementId,\n      annotation: updated,\n      timestamp: Date.now(),\n    });\n  }\n\n  /**\n   * Delete an annotation by element ID.\n   *\n   * @returns true if the annotation existed and was deleted\n   */\n  delete(elementId: string): boolean {\n    const existed = this.store.delete(elementId);\n    if (existed) {\n      this.emit({\n        type: 'annotation:deleted',\n        elementId,\n        timestamp: Date.now(),\n      });\n    }\n    return existed;\n  }\n\n  /**\n   * Check if an annotation exists for an element.\n   */\n  has(elementId: string): boolean {\n    return this.store.has(elementId);\n  }\n\n  /**\n   * Get the number of stored annotations.\n   */\n  get count(): number {\n    return this.store.size;\n  }\n\n  /**\n   * Clear all annotations.\n   */\n  clear(): void {\n    this.store.clear();\n    this.emit({\n      type: 'annotation:cleared',\n      timestamp: Date.now(),\n    });\n  }\n\n  /**\n   * Import annotations from a config object.\n   *\n   * Merges with existing annotations (new values overwrite per element ID).\n   *\n   * @returns Number of annotations imported\n   *\n   * @example\n   * ```ts\n   * const config: AnnotationConfig = {\n   *   version: '1.0.0',\n   *   annotations: {\n   *     'btn-1': { description: 'Submit button', tags: ['form'] },\n   *     'input-1': { description: 'Name field' },\n   *   },\n   * };\n   * const count = store.importConfig(config); // 2\n   * ```\n   */\n  importConfig(config: AnnotationConfig): number {\n    let count = 0;\n    for (const [id, annotation] of Object.entries(config.annotations)) {\n      this.store.set(id, {\n        ...annotation,\n        updatedAt: annotation.updatedAt ?? Date.now(),\n      });\n      count++;\n    }\n    this.emit({\n      type: 'annotation:imported',\n      count,\n      timestamp: Date.now(),\n    });\n    return count;\n  }\n\n  /**\n   * Export all annotations as a config object.\n   *\n   * The returned object can be serialized to JSON and saved to a file,\n   * then later re-imported with {@link importConfig}.\n   *\n   * @param metadata - Optional metadata to include (appName, description, etc.)\n   * @returns AnnotationConfig with all current annotations\n   *\n   * @example\n   * ```ts\n   * const config = store.exportConfig({ appName: 'MyApp' });\n   * // config.version === '1.0.0'\n   * // config.annotations === { 'btn-1': { ... }, 'input-1': { ... } }\n   * // config.metadata === { appName: 'MyApp', exportedAt: 1706900000000 }\n   *\n   * // Save to file\n   * fs.writeFileSync('annotations.json', JSON.stringify(config, null, 2));\n   * ```\n   */\n  exportConfig(metadata?: AnnotationConfig['metadata']): AnnotationConfig {\n    return {\n      version: ANNOTATION_CONFIG_VERSION,\n      annotations: this.getAll(),\n      metadata: {\n        ...metadata,\n        exportedAt: Date.now(),\n      },\n    };\n  }\n\n  /**\n   * Compute annotation coverage against a set of known element IDs.\n   *\n   * Compares the store's annotations against the provided list of element IDs\n   * to determine what percentage of elements have been annotated.\n   *\n   * @param allElementIds - Array of all known element IDs in the UI\n   * @returns Coverage statistics including percentages and lists of annotated/unannotated IDs\n   *\n   * @example\n   * ```ts\n   * store.set('btn-1', { description: 'Submit' });\n   * store.set('input-1', { description: 'Name' });\n   *\n   * const coverage = store.getCoverage(['btn-1', 'input-1', 'input-2', 'link-1']);\n   * // coverage.totalElements === 4\n   * // coverage.annotatedElements === 2\n   * // coverage.coveragePercent === 50\n   * // coverage.annotatedIds === ['btn-1', 'input-1']\n   * // coverage.unannotatedIds === ['input-2', 'link-1']\n   * ```\n   */\n  getCoverage(allElementIds: string[]): AnnotationCoverage {\n    const annotatedIds: string[] = [];\n    const unannotatedIds: string[] = [];\n\n    for (const id of allElementIds) {\n      if (this.store.has(id)) {\n        annotatedIds.push(id);\n      } else {\n        unannotatedIds.push(id);\n      }\n    }\n\n    const total = allElementIds.length;\n    return {\n      totalElements: total,\n      annotatedElements: annotatedIds.length,\n      coveragePercent: total > 0 ? (annotatedIds.length / total) * 100 : 0,\n      annotatedIds,\n      unannotatedIds,\n      timestamp: Date.now(),\n    };\n  }\n\n  /**\n   * Subscribe to annotation events.\n   *\n   * The listener is called whenever annotations are set, deleted, imported,\n   * or cleared. Returns an unsubscribe function to stop listening.\n   *\n   * @param listener - Callback function receiving {@link AnnotationEvent} objects\n   * @returns Unsubscribe function - call it to remove the listener\n   *\n   * @example\n   * ```ts\n   * const unsubscribe = store.on((event) => {\n   *   if (event.type === 'annotation:set') {\n   *     console.log(`Element ${event.elementId} annotated:`, event.annotation);\n   *   }\n   * });\n   *\n   * store.set('btn-1', { description: 'Submit' });\n   * // Logs: \"Element btn-1 annotated: { description: 'Submit', updatedAt: ... }\"\n   *\n   * unsubscribe(); // Stop listening\n   * ```\n   */\n  on(listener: AnnotationListener): () => void {\n    this.listeners.add(listener);\n    return () => {\n      this.listeners.delete(listener);\n    };\n  }\n\n  /**\n   * Emit an event to all listeners.\n   */\n  private emit(event: AnnotationEvent): void {\n    for (const listener of this.listeners) {\n      try {\n        listener(event);\n      } catch {\n        // Don't let listener errors break the store\n      }\n    }\n  }\n}\n\n// Global singleton\nlet globalStore: AnnotationStore | null = null;\n\n/**\n * Get the global annotation store singleton.\n */\nexport function getGlobalAnnotationStore(): AnnotationStore {\n  if (!globalStore) {\n    globalStore = new AnnotationStore();\n  }\n  return globalStore;\n}\n\n/**\n * Reset the global annotation store (primarily for testing).\n */\nexport function resetGlobalAnnotationStore(): void {\n  globalStore = null;\n}\n"]}

package/dist/assertions-BSR3afVr.d.ts

@@ -0,0 +1,161 @@
+import { D as DiscoveredElement } from './types-C7gVYRnF.js';
+import { A as AIDiscoveredElement, d as AssertionRequest, e as AssertionResult, B as BatchAssertionRequest, g as BatchAssertionResult, a8 as SearchCriteria } from './types-CebMQj76.js';
+
+/**
+ * Assertions Module
+ *
+ * Provides verification/assertion API for AI agents to validate
+ * page state without writing Playwright tests.
+ */
+
+/**
+ * Configuration for assertions
+ */
+interface AssertionConfig {
+    /** Default timeout for wait-based assertions */
+    defaultTimeout: number;
+    /** Polling interval for wait-based assertions */
+    pollInterval: number;
+    /** Default fuzzy threshold for element search */
+    fuzzyThreshold: number;
+    /** Include suggestions in failure messages */
+    includeSuggestions: boolean;
+}
+/**
+ * Default assertion configuration
+ */
+declare const DEFAULT_ASSERTION_CONFIG: AssertionConfig;
+/**
+ * Assertion executor class
+ */
+declare class AssertionExecutor {
+    private config;
+    private searchEngine;
+    private elements;
+    constructor(config?: Partial<AssertionConfig>);
+    /**
+     * Update available elements for assertions
+     */
+    updateElements(elements: Array<DiscoveredElement | AIDiscoveredElement>): void;
+    /**
+     * Execute a single assertion
+     */
+    assert(request: AssertionRequest): Promise<AssertionResult>;
+    /**
+     * Execute multiple assertions
+     */
+    assertBatch(request: BatchAssertionRequest): Promise<BatchAssertionResult>;
+    /**
+     * Convenience method: assert element is visible
+     */
+    assertVisible(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element is hidden
+     */
+    assertHidden(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element is enabled
+     */
+    assertEnabled(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element is disabled
+     */
+    assertDisabled(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element has text
+     */
+    assertHasText(target: string | SearchCriteria, text: string, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element contains text
+     */
+    assertContainsText(target: string | SearchCriteria, text: string, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element has value
+     */
+    assertHasValue(target: string | SearchCriteria, value: string, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element exists
+     */
+    assertExists(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element does not exist
+     */
+    assertNotExists(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert checkbox is checked
+     */
+    assertChecked(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert checkbox is unchecked
+     */
+    assertUnchecked(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element count
+     */
+    assertCount(target: SearchCriteria, expectedCount: number, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Find element by target with full search metadata.
+     * Returns the SearchResult (including confidence, matchReasons, scores)
+     * or null if no match above the fuzzy threshold.
+     */
+    private findElementDetailed;
+    /**
+     * Find element by target (string or criteria).
+     * Public for use by condition evaluation in SpecExecutor.
+     */
+    findElement(target: string | SearchCriteria, fuzzy?: boolean): Promise<AIDiscoveredElement | null>;
+    /**
+     * Execute the actual assertion
+     */
+    private executeAssertion;
+    /**
+     * Assert visibility state
+     */
+    private assertVisibility;
+    /**
+     * Assert enabled state
+     */
+    private assertEnabledState;
+    /**
+     * Assert focused state
+     */
+    private assertFocused;
+    /**
+     * Assert checked state
+     */
+    private assertCheckedState;
+    /**
+     * Assert text content
+     */
+    private assertTextMatch;
+    /**
+     * Assert input value
+     */
+    private assertValue;
+    /**
+     * Assert element count
+     */
+    private assertElementCount;
+    /**
+     * Assert attribute value (placeholder for DOM attribute assertions)
+     */
+    private assertAttribute;
+    /**
+     * Assert element has CSS class
+     */
+    private assertHasClass;
+    /**
+     * Assert CSS property value
+     */
+    private assertCssProperty;
+    /**
+     * Create an assertion result
+     */
+    private createResult;
+}
+/**
+ * Create a default assertion executor
+ */
+declare function createAssertionExecutor(config?: Partial<AssertionConfig>): AssertionExecutor;
+
+export { type AssertionConfig as A, DEFAULT_ASSERTION_CONFIG as D, AssertionExecutor as a, createAssertionExecutor as c };

package/dist/assertions-CTw1hfOx.d.mts

@@ -0,0 +1,161 @@
+import { D as DiscoveredElement } from './types-CJGrBEhC.mjs';
+import { A as AIDiscoveredElement, d as AssertionRequest, e as AssertionResult, B as BatchAssertionRequest, g as BatchAssertionResult, a8 as SearchCriteria } from './types-D_ypYl3T.mjs';
+
+/**
+ * Assertions Module
+ *
+ * Provides verification/assertion API for AI agents to validate
+ * page state without writing Playwright tests.
+ */
+
+/**
+ * Configuration for assertions
+ */
+interface AssertionConfig {
+    /** Default timeout for wait-based assertions */
+    defaultTimeout: number;
+    /** Polling interval for wait-based assertions */
+    pollInterval: number;
+    /** Default fuzzy threshold for element search */
+    fuzzyThreshold: number;
+    /** Include suggestions in failure messages */
+    includeSuggestions: boolean;
+}
+/**
+ * Default assertion configuration
+ */
+declare const DEFAULT_ASSERTION_CONFIG: AssertionConfig;
+/**
+ * Assertion executor class
+ */
+declare class AssertionExecutor {
+    private config;
+    private searchEngine;
+    private elements;
+    constructor(config?: Partial<AssertionConfig>);
+    /**
+     * Update available elements for assertions
+     */
+    updateElements(elements: Array<DiscoveredElement | AIDiscoveredElement>): void;
+    /**
+     * Execute a single assertion
+     */
+    assert(request: AssertionRequest): Promise<AssertionResult>;
+    /**
+     * Execute multiple assertions
+     */
+    assertBatch(request: BatchAssertionRequest): Promise<BatchAssertionResult>;
+    /**
+     * Convenience method: assert element is visible
+     */
+    assertVisible(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element is hidden
+     */
+    assertHidden(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element is enabled
+     */
+    assertEnabled(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element is disabled
+     */
+    assertDisabled(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element has text
+     */
+    assertHasText(target: string | SearchCriteria, text: string, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element contains text
+     */
+    assertContainsText(target: string | SearchCriteria, text: string, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element has value
+     */
+    assertHasValue(target: string | SearchCriteria, value: string, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element exists
+     */
+    assertExists(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element does not exist
+     */
+    assertNotExists(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert checkbox is checked
+     */
+    assertChecked(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert checkbox is unchecked
+     */
+    assertUnchecked(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element count
+     */
+    assertCount(target: SearchCriteria, expectedCount: number, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Find element by target with full search metadata.
+     * Returns the SearchResult (including confidence, matchReasons, scores)
+     * or null if no match above the fuzzy threshold.
+     */
+    private findElementDetailed;
+    /**
+     * Find element by target (string or criteria).
+     * Public for use by condition evaluation in SpecExecutor.
+     */
+    findElement(target: string | SearchCriteria, fuzzy?: boolean): Promise<AIDiscoveredElement | null>;
+    /**
+     * Execute the actual assertion
+     */
+    private executeAssertion;
+    /**
+     * Assert visibility state
+     */
+    private assertVisibility;
+    /**
+     * Assert enabled state
+     */
+    private assertEnabledState;
+    /**
+     * Assert focused state
+     */
+    private assertFocused;
+    /**
+     * Assert checked state
+     */
+    private assertCheckedState;
+    /**
+     * Assert text content
+     */
+    private assertTextMatch;
+    /**
+     * Assert input value
+     */
+    private assertValue;
+    /**
+     * Assert element count
+     */
+    private assertElementCount;
+    /**
+     * Assert attribute value (placeholder for DOM attribute assertions)
+     */
+    private assertAttribute;
+    /**
+     * Assert element has CSS class
+     */
+    private assertHasClass;
+    /**
+     * Assert CSS property value
+     */
+    private assertCssProperty;
+    /**
+     * Create an assertion result
+     */
+    private createResult;
+}
+/**
+ * Create a default assertion executor
+ */
+declare function createAssertionExecutor(config?: Partial<AssertionConfig>): AssertionExecutor;
+
+export { type AssertionConfig as A, DEFAULT_ASSERTION_CONFIG as D, AssertionExecutor as a, createAssertionExecutor as c };