angular-grab 0.1.1 → 0.1.3

package/packages/angular-grab/src/core/toolbar/theme-manager.ts

@@ -0,0 +1,188 @@
+import type { ThemeMode, Theme } from '../types';
+
+const STYLE_ID = '__ag-theme-vars__';
+const OVERRIDE_STYLE_ID = '__ag-theme-overrides__';
+
+const DARK_VARS = `
+  :root {
+    --ag-bg: #0f172a;
+    --ag-text: #e2e8f0;
+    --ag-text-muted: #64748b;
+    --ag-accent: #3b82f6;
+    --ag-accent-hover: #2563eb;
+    --ag-surface: #1e293b;
+    --ag-border: #334155;
+    --ag-overlay-border: #3b82f6;
+    --ag-overlay-bg: rgba(59, 130, 246, 0.1);
+    --ag-label-bg: #3b82f6;
+    --ag-label-text: #fff;
+    --ag-toast-bg: #0f172a;
+    --ag-toast-text: #e2e8f0;
+    --ag-toast-title: #fff;
+    --ag-toast-label: #64748b;
+    --ag-toast-shadow: rgba(0, 0, 0, 0.4);
+    --ag-toolbar-bg: #0f172a;
+    --ag-toolbar-text: #94a3b8;
+    --ag-toolbar-hover: #1e293b;
+    --ag-toolbar-active: #3b82f6;
+    --ag-toolbar-border: #1e293b;
+    --ag-toolbar-shadow: rgba(0, 0, 0, 0.5);
+    --ag-popover-bg: #0f172a;
+    --ag-popover-text: #e2e8f0;
+    --ag-popover-border: #1e293b;
+    --ag-popover-hover: #1e293b;
+    --ag-popover-shadow: rgba(0, 0, 0, 0.5);
+  }
+`;
+
+const LIGHT_VARS = `
+  :root {
+    --ag-bg: #ffffff;
+    --ag-text: #334155;
+    --ag-text-muted: #94a3b8;
+    --ag-accent: #2563eb;
+    --ag-accent-hover: #1d4ed8;
+    --ag-surface: #f1f5f9;
+    --ag-border: #e2e8f0;
+    --ag-overlay-border: #2563eb;
+    --ag-overlay-bg: rgba(37, 99, 235, 0.08);
+    --ag-label-bg: #2563eb;
+    --ag-label-text: #fff;
+    --ag-toast-bg: #ffffff;
+    --ag-toast-text: #334155;
+    --ag-toast-title: #0f172a;
+    --ag-toast-label: #94a3b8;
+    --ag-toast-shadow: rgba(0, 0, 0, 0.12);
+    --ag-toolbar-bg: #ffffff;
+    --ag-toolbar-text: #64748b;
+    --ag-toolbar-hover: #f1f5f9;
+    --ag-toolbar-active: #2563eb;
+    --ag-toolbar-border: #e2e8f0;
+    --ag-toolbar-shadow: rgba(0, 0, 0, 0.12);
+    --ag-popover-bg: #ffffff;
+    --ag-popover-text: #334155;
+    --ag-popover-border: #e2e8f0;
+    --ag-popover-hover: #f1f5f9;
+    --ag-popover-shadow: rgba(0, 0, 0, 0.12);
+  }
+`;
+
+/** Maps Theme interface fields to CSS variable names. */
+const THEME_TO_VAR: Record<keyof Theme, string> = {
+  overlayBorderColor: '--ag-overlay-border',
+  overlayBgColor: '--ag-overlay-bg',
+  labelBgColor: '--ag-label-bg',
+  labelTextColor: '--ag-label-text',
+  toastBgColor: '--ag-toast-bg',
+  toastTextColor: '--ag-toast-text',
+  toolbarBgColor: '--ag-toolbar-bg',
+  toolbarTextColor: '--ag-toolbar-text',
+  toolbarAccentColor: '--ag-toolbar-active',
+  popoverBgColor: '--ag-popover-bg',
+  popoverTextColor: '--ag-popover-text',
+  popoverBorderColor: '--ag-popover-border',
+};
+
+export interface ThemeManager {
+  apply(mode: ThemeMode): void;
+  applyOverrides(theme: Partial<Theme>): void;
+  clearOverrides(): void;
+  dispose(): void;
+}
+
+export function createThemeManager(): ThemeManager {
+  let styleEl: HTMLStyleElement | null = null;
+  let overrideEl: HTMLStyleElement | null = null;
+  let currentMode: ThemeMode = 'dark';
+  let mediaQuery: MediaQueryList | null = null;
+  let mediaHandler: ((e: MediaQueryListEvent) => void) | null = null;
+
+  function getOrCreateStyle(): HTMLStyleElement {
+    if (styleEl) return styleEl;
+
+    const existing = document.getElementById(STYLE_ID) as HTMLStyleElement | null;
+    if (existing) {
+      styleEl = existing;
+      return styleEl;
+    }
+
+    styleEl = document.createElement('style');
+    styleEl.id = STYLE_ID;
+    document.head.appendChild(styleEl);
+    return styleEl;
+  }
+
+  function getOrCreateOverrideStyle(): HTMLStyleElement {
+    if (overrideEl) return overrideEl;
+
+    overrideEl = document.createElement('style');
+    overrideEl.id = OVERRIDE_STYLE_ID;
+    document.head.appendChild(overrideEl);
+    return overrideEl;
+  }
+
+  function resolveMode(mode: ThemeMode): 'dark' | 'light' {
+    if (mode !== 'system') return mode;
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  }
+
+  function applyResolved(resolved: 'dark' | 'light'): void {
+    const el = getOrCreateStyle();
+    el.textContent = resolved === 'dark' ? DARK_VARS : LIGHT_VARS;
+  }
+
+  function detachMediaListener(): void {
+    if (mediaQuery && mediaHandler) {
+      mediaQuery.removeEventListener('change', mediaHandler);
+    }
+    mediaQuery = null;
+    mediaHandler = null;
+  }
+
+  return {
+    apply(mode: ThemeMode): void {
+      currentMode = mode;
+      detachMediaListener();
+
+      applyResolved(resolveMode(mode));
+
+      if (mode === 'system') {
+        mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+        mediaHandler = () => applyResolved(resolveMode('system'));
+        mediaQuery.addEventListener('change', mediaHandler);
+      }
+    },
+
+    applyOverrides(theme: Partial<Theme>): void {
+      const vars: string[] = [];
+      for (const [key, varName] of Object.entries(THEME_TO_VAR)) {
+        const value = theme[key as keyof Theme];
+        if (value) {
+          vars.push(`    ${varName}: ${value};`);
+        }
+      }
+
+      if (vars.length === 0) {
+        this.clearOverrides();
+        return;
+      }
+
+      const el = getOrCreateOverrideStyle();
+      el.textContent = `  :root {\n${vars.join('\n')}\n  }`;
+    },
+
+    clearOverrides(): void {
+      overrideEl?.remove();
+      document.getElementById(OVERRIDE_STYLE_ID)?.remove();
+      overrideEl = null;
+    },
+
+    dispose(): void {
+      detachMediaListener();
+      styleEl?.remove();
+      document.getElementById(STYLE_ID)?.remove();
+      styleEl = null;
+      this.clearOverrides();
+    },
+  };
+}

package/packages/angular-grab/src/core/toolbar/toolbar-icons.ts

@@ -0,0 +1,29 @@
+// All icons are 16x16, stroke-based with currentColor for theme compatibility
+
+export const ICON_GRAB = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><path d="M5.5 7V3.5a1 1 0 0 1 2 0V7"/><path d="M7.5 6.5V2.5a1 1 0 0 1 2 0v4"/><path d="M9.5 7V3.5a1 1 0 0 1 2 0V8"/><path d="M5.5 7V5.5a1 1 0 0 0-2 0V9a4 4 0 0 0 4 4h1.5a4 4 0 0 0 4-4V6a1 1 0 0 0-2 0"/></svg>`;
+
+export const ICON_HISTORY = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><circle cx="8" cy="8" r="6"/><path d="M8 4.5V8l2.5 1.5"/></svg>`;
+
+export const ICON_ELLIPSIS = `<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><circle cx="4" cy="8" r="1.25"/><circle cx="8" cy="8" r="1.25"/><circle cx="12" cy="8" r="1.25"/></svg>`;
+
+export const ICON_SUN = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" xmlns="http://www.w3.org/2000/svg"><circle cx="8" cy="8" r="3"/><path d="M8 1.5v1M8 13.5v1M1.5 8h1M13.5 8h1M3.4 3.4l.7.7M11.9 11.9l.7.7M3.4 12.6l.7-.7M11.9 4.1l.7-.7"/></svg>`;
+
+export const ICON_MOON = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><path d="M13.5 8.5a5.5 5.5 0 0 1-7-7 5.5 5.5 0 1 0 7 7z"/></svg>`;
+
+export const ICON_SYSTEM = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><rect x="2" y="2" width="12" height="9" rx="1"/><path d="M5.5 14h5"/><path d="M8 11v3"/></svg>`;
+
+export const ICON_POWER = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><path d="M8 2v5"/><path d="M4.5 4a5.5 5.5 0 1 0 7 0"/></svg>`;
+
+export const ICON_DISMISS = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" xmlns="http://www.w3.org/2000/svg"><path d="M4 4l8 8M12 4l-8 8"/></svg>`;
+
+export const ICON_COPY = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><rect x="5.5" y="5.5" width="7" height="8" rx="1"/><path d="M3.5 10.5v-7a1 1 0 0 1 1-1h5"/></svg>`;
+
+export const ICON_STYLES = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><path d="M13 1.5l-1.3 4.3a1 1 0 0 1-.7.7L6.7 7.8a1 1 0 0 0-.7.7L4.7 12.8a1 1 0 0 1-.7.7L1.5 14"/><path d="M7.5 5.5l3 3"/></svg>`;
+
+export const ICON_CODE = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><path d="M5 4.5L1.5 8 5 11.5"/><path d="M11 4.5l3.5 3.5-3.5 3.5"/><path d="M9.5 2.5l-3 11"/></svg>`;
+
+export const ICON_COMMENT = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><path d="M2 3a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H5l-3 3V3z"/></svg>`;
+
+export const ICON_TRASH = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><path d="M2.5 4.5h11"/><path d="M5.5 4.5V3a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1v1.5"/><path d="M4 4.5l.5 8.5a1 1 0 0 0 1 1h5a1 1 0 0 0 1-1l.5-8.5"/></svg>`;
+
+export const ICON_FREEZE = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg"><path d="M8 1v14"/><path d="M1 8h14"/><path d="M8 1l2 2M8 1L6 3"/><path d="M8 15l2-2M8 15l-2-2"/><path d="M1 8l2 2M1 8l2-2"/><path d="M15 8l-2 2M15 8l-2-2"/></svg>`;

package/packages/angular-grab/src/core/toolbar/toolbar-renderer.ts

@@ -0,0 +1,239 @@
+import type { GrabState } from '../store';
+import { Z_INDEX_TOOLBAR } from '../constants';
+import { ICON_GRAB, ICON_HISTORY, ICON_ELLIPSIS, ICON_FREEZE, ICON_SUN, ICON_MOON, ICON_SYSTEM, ICON_POWER, ICON_DISMISS } from './toolbar-icons';
+
+const TOOLBAR_ID = '__ag-toolbar__';
+const STYLE_ID = '__ag-toolbar-styles__';
+
+export interface ToolbarCallbacks {
+  onSelectionMode: () => void;
+  onHistory: () => void;
+  onActions: () => void;
+  onFreeze: () => void;
+  onThemeToggle: () => void;
+  onEnableToggle: () => void;
+  onDismiss: () => void;
+}
+
+export interface ToolbarRenderer {
+  show(): void;
+  hide(): void;
+  update(state: GrabState): void;
+  isToolbarElement(el: Element): boolean;
+  dispose(): void;
+}
+
+export function createToolbarRenderer(callbacks: ToolbarCallbacks): ToolbarRenderer {
+  let container: HTMLDivElement | null = null;
+  let leftGroup: HTMLDivElement | null = null;
+  let buttons: Record<string, HTMLButtonElement> = {};
+  let allElements = new Set<Element>();
+
+  function injectStyles(): void {
+    if (document.getElementById(STYLE_ID)) return;
+
+    const style = document.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = `
+      #${TOOLBAR_ID} {
+        position: fixed;
+        bottom: 20px;
+        left: 50%;
+        transform: translateX(-50%);
+        z-index: ${Z_INDEX_TOOLBAR};
+        display: flex;
+        align-items: center;
+        gap: 2px;
+        padding: 4px 6px;
+        background: var(--ag-toolbar-bg, #0f172a);
+        border: 1px solid var(--ag-toolbar-border, #1e293b);
+        border-radius: 24px;
+        box-shadow: 0 4px 16px var(--ag-toolbar-shadow, rgba(0, 0, 0, 0.5));
+        pointer-events: auto;
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+        transition: opacity 0.2s ease, transform 0.2s ease;
+      }
+      #${TOOLBAR_ID}.ag-toolbar-hidden {
+        opacity: 0;
+        transform: translateX(-50%) translateY(20px);
+        pointer-events: none;
+      }
+      #${TOOLBAR_ID} button {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: 32px;
+        height: 32px;
+        border: none;
+        border-radius: 8px;
+        background: transparent;
+        color: var(--ag-toolbar-text, #94a3b8);
+        cursor: pointer;
+        padding: 0;
+        transition: background 0.15s ease, color 0.15s ease;
+      }
+      #${TOOLBAR_ID} button:hover {
+        background: var(--ag-toolbar-hover, #1e293b);
+        color: var(--ag-accent, #3b82f6);
+      }
+      #${TOOLBAR_ID} button.ag-btn-active {
+        color: var(--ag-toolbar-active, #3b82f6);
+      }
+      #${TOOLBAR_ID} button.ag-btn-disabled {
+        opacity: 0.4;
+        color: var(--ag-toolbar-text, #94a3b8);
+      }
+      #${TOOLBAR_ID} .ag-toolbar-divider {
+        width: 1px;
+        height: 20px;
+        background: var(--ag-toolbar-border, #1e293b);
+        margin: 0 4px;
+        flex-shrink: 0;
+      }
+      #${TOOLBAR_ID} .ag-toolbar-left {
+        display: flex;
+        align-items: center;
+        gap: 2px;
+        overflow: hidden;
+        max-width: 240px;
+        opacity: 1;
+        transition: max-width 0.25s ease, opacity 0.2s ease, margin 0.25s ease;
+      }
+      #${TOOLBAR_ID} .ag-toolbar-left.ag-toolbar-left-hidden {
+        max-width: 0;
+        opacity: 0;
+        pointer-events: none;
+      }
+    `;
+    document.head.appendChild(style);
+  }
+
+  function createButton(name: string, icon: string, title: string, onClick: () => void): HTMLButtonElement {
+    const btn = document.createElement('button');
+    btn.innerHTML = icon;
+    btn.title = title;
+    btn.setAttribute('aria-label', title);
+    btn.setAttribute('data-ag-btn', name);
+    btn.addEventListener('click', (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      onClick();
+    });
+    return btn;
+  }
+
+  function ensureContainer(): void {
+    if (container) return;
+
+    injectStyles();
+
+    container = document.createElement('div');
+    container.id = TOOLBAR_ID;
+    container.setAttribute('role', 'toolbar');
+    container.setAttribute('aria-label', 'Angular Grab toolbar');
+
+    buttons.selection = createButton('selection', ICON_GRAB, 'Selection mode', callbacks.onSelectionMode);
+    buttons.history = createButton('history', ICON_HISTORY, 'History', callbacks.onHistory);
+    buttons.actions = createButton('actions', ICON_ELLIPSIS, 'Actions', callbacks.onActions);
+    buttons.freeze = createButton('freeze', ICON_FREEZE, 'Freeze page (F)', callbacks.onFreeze);
+    buttons.theme = createButton('theme', ICON_SUN, 'Toggle theme', callbacks.onThemeToggle);
+    buttons.enable = createButton('enable', ICON_POWER, 'Enable/Disable', callbacks.onEnableToggle);
+    buttons.dismiss = createButton('dismiss', ICON_DISMISS, 'Dismiss toolbar', callbacks.onDismiss);
+
+    const divider = document.createElement('span');
+    divider.className = 'ag-toolbar-divider';
+
+    leftGroup = document.createElement('div');
+    leftGroup.className = 'ag-toolbar-left';
+    leftGroup.appendChild(buttons.selection);
+    leftGroup.appendChild(buttons.history);
+    leftGroup.appendChild(buttons.actions);
+    leftGroup.appendChild(buttons.freeze);
+    leftGroup.appendChild(divider);
+    container.appendChild(leftGroup);
+    container.appendChild(buttons.theme);
+    container.appendChild(buttons.enable);
+    container.appendChild(buttons.dismiss);
+
+    document.body.appendChild(container);
+
+    // Track all elements for isToolbarElement checks
+    allElements.clear();
+    allElements.add(container);
+    allElements.add(leftGroup);
+    allElements.add(divider);
+    for (const btn of Object.values(buttons)) {
+      allElements.add(btn);
+    }
+  }
+
+  return {
+    show(): void {
+      ensureContainer();
+      container!.classList.remove('ag-toolbar-hidden');
+    },
+
+    hide(): void {
+      if (container) {
+        container.classList.add('ag-toolbar-hidden');
+      }
+    },
+
+    update(state: GrabState): void {
+      if (!container) return;
+
+      // Selection mode active state
+      if (state.active) {
+        buttons.selection.classList.add('ag-btn-active');
+      } else {
+        buttons.selection.classList.remove('ag-btn-active');
+      }
+
+      // Theme icon
+      const mode = state.toolbar.themeMode;
+      const themeIcon = mode === 'dark' ? ICON_SUN : mode === 'light' ? ICON_MOON : ICON_SYSTEM;
+      const themeLabel = mode === 'dark' ? 'Switch to light mode' : mode === 'light' ? 'Switch to system theme' : 'Switch to dark mode';
+      buttons.theme.innerHTML = themeIcon;
+      buttons.theme.title = themeLabel;
+      buttons.theme.setAttribute('aria-label', themeLabel);
+
+      // Freeze button active state
+      if (state.frozen) {
+        buttons.freeze.classList.add('ag-btn-active');
+      } else {
+        buttons.freeze.classList.remove('ag-btn-active');
+      }
+
+      // Enable/disable — hide/show left side
+      if (state.options.enabled) {
+        buttons.enable.classList.add('ag-btn-active');
+        leftGroup?.classList.remove('ag-toolbar-left-hidden');
+      } else {
+        buttons.enable.classList.remove('ag-btn-active');
+        leftGroup?.classList.add('ag-toolbar-left-hidden');
+      }
+    },
+
+    isToolbarElement(el: Element): boolean {
+      if (allElements.has(el)) return true;
+
+      // Walk up to check if el is inside the toolbar (e.g. SVG children)
+      let current: Element | null = el;
+      while (current) {
+        if (current === container) return true;
+        if (current.id === TOOLBAR_ID) return true;
+        current = current.parentElement;
+      }
+      return false;
+    },
+
+    dispose(): void {
+      container?.remove();
+      document.getElementById(STYLE_ID)?.remove();
+      container = null;
+      leftGroup = null;
+      buttons = {};
+      allElements.clear();
+    },
+  };
+}

package/packages/angular-grab/src/core/types.ts

@@ -0,0 +1,139 @@
+export type ThemeMode = 'dark' | 'light' | 'system';
+
+export type PendingAction =
+  | { type: 'copy-element' }
+  | { type: 'copy-styles' }
+  | { type: 'copy-html' }
+  | { type: 'comment' };
+
+/** Serializable subset of ElementContext — no live DOM reference. */
+export interface HistoryContext {
+  html: string;
+  componentName: string | null;
+  filePath: string | null;
+  line: number | null;
+  column: number | null;
+  componentStack: ComponentStackEntry[];
+  selector: string;
+  cssClasses: string[];
+}
+
+export interface HistoryEntry {
+  id: string;
+  context: HistoryContext;
+  snippet: string;
+  timestamp: number;
+}
+
+export interface ToolbarState {
+  visible: boolean;
+  themeMode: ThemeMode;
+  history: HistoryEntry[];
+  pendingAction: PendingAction | null;
+}
+
+export interface AngularGrabOptions {
+  /** Keyboard shortcut to activate. Default: "Meta+C" (Mac) / "Ctrl+C" (Win) */
+  activationKey: string;
+  /** Whether activation requires hold or toggle. Default: 'hold' */
+  activationMode: 'hold' | 'toggle';
+  /** Milliseconds to hold before activating in hold mode. Default: 0 */
+  keyHoldDuration: number;
+  /** Max lines of HTML to include in copied context. Default: 20 */
+  maxContextLines: number;
+  /** Master on/off switch. Default: true */
+  enabled: boolean;
+  /** Allow activation while focused in input/textarea. Default: false */
+  enableInInputs: boolean;
+  /** Only activate in dev mode. Default: true */
+  devOnly: boolean;
+  /** Show the floating mini toolbar. Default: true */
+  showToolbar: boolean;
+  /** Theme mode for all UI. Default: 'dark' */
+  themeMode: ThemeMode;
+}
+
+export interface ComponentStackEntry {
+  name: string;
+  filePath: string | null;
+  line: number | null;
+  column: number | null;
+}
+
+export interface ElementContext {
+  element: Element;
+  html: string;
+  componentName: string | null;
+  filePath: string | null;
+  line: number | null;
+  column: number | null;
+  componentStack: ComponentStackEntry[];
+  selector: string;
+  cssClasses: string[];
+}
+
+export interface PluginHooks {
+  onActivate?: () => void;
+  onDeactivate?: () => void;
+  onElementHover?: (element: Element) => void;
+  onElementSelect?: (context: ElementContext) => void;
+  onBeforeCopy?: (context: ElementContext) => void;
+  onCopySuccess?: (text: string, context: ElementContext, prompt?: string) => void;
+  onCopyError?: (error: Error) => void;
+  transformCopyContent?: (text: string, context: ElementContext) => string;
+}
+
+export interface Theme {
+  overlayBorderColor: string;
+  overlayBgColor: string;
+  labelBgColor: string;
+  labelTextColor: string;
+  toastBgColor: string;
+  toastTextColor: string;
+  toolbarBgColor: string;
+  toolbarTextColor: string;
+  toolbarAccentColor: string;
+  popoverBgColor: string;
+  popoverTextColor: string;
+  popoverBorderColor: string;
+}
+
+export interface Plugin {
+  name: string;
+  hooks?: PluginHooks;
+  theme?: Partial<Theme>;
+  options?: Partial<AngularGrabOptions>;
+  setup?: (api: AngularGrabAPI) => PluginCleanup | void;
+}
+
+export type PluginCleanup = () => void;
+
+export type ComponentResolver = (element: Element) => {
+  name: string | null;
+  hostElement: Element | null;
+  stack?: Array<{ name: string; hostElement: Element | null }>;
+} | null;
+
+export type SourceResolver = (element: Element) => {
+  filePath: string | null;
+  line: number | null;
+  column: number | null;
+} | null;
+
+export interface AngularGrabAPI {
+  activate(): void;
+  deactivate(): void;
+  toggle(): void;
+  isActive(): boolean;
+  setOptions(opts: Partial<AngularGrabOptions>): void;
+  registerPlugin(plugin: Plugin): void;
+  unregisterPlugin(name: string): void;
+  setComponentResolver(resolver: ComponentResolver): void;
+  setSourceResolver(resolver: SourceResolver): void;
+  showToolbar(): void;
+  hideToolbar(): void;
+  setThemeMode(mode: ThemeMode): void;
+  getHistory(): HistoryEntry[];
+  clearHistory(): void;
+  dispose(): void;
+}

package/packages/angular-grab/src/core/utils.ts

@@ -0,0 +1,16 @@
+export function escapeHtml(text: string): string {
+  const div = document.createElement('div');
+  div.textContent = text;
+  return div.innerHTML;
+}
+
+export function filterAngularClasses(classList: DOMTokenList): string[] {
+  return Array.from(classList).filter(c => !c.startsWith('ng-') && !c.startsWith('_ng'));
+}
+
+const NG_ATTR_RE = /\s_ng(host|content)-[a-z0-9-]+="[^"]*"/gi;
+const NG_ATTR_EMPTY_RE = /\s_ng(host|content)-[a-z0-9-]+/gi;
+
+export function cleanAngularAttrs(html: string): string {
+  return html.replace(NG_ATTR_RE, '').replace(NG_ATTR_EMPTY_RE, '');
+}