yo-bug 0.1.0

package/src/client/core/i18n.ts

@@ -0,0 +1,83 @@
+const zhCN: Record<string, string> = {
+  // Floating button
+  'hint.firstTime': '\u53D1\u73B0\u95EE\u9898\uFF1F\u70B9\u6211\u6216\u6309 Alt+Q \u5FEB\u901F\u6807\u8BB0',
+  // Mode bar
+  'mode.quick': '\u5FEB\u901F\u6807\u8BB0',
+  'mode.quick.hint': '\u70B9\u51FB\u95EE\u9898\u5143\u7D20',
+  'mode.detail': '\u8BE6\u7EC6\u63CF\u8FF0',
+  'mode.detail.hint': '\u70B9\u51FB + \u586B\u5199',
+  'mode.screenshot': '\u622A\u56FE\u6807\u6CE8',
+  'mode.screenshot.hint': '\u6846\u9009\u533A\u57DF + \u753B',
+  // Feedback panel
+  'panel.element.title': '\u5143\u7D20\u53CD\u9988',
+  'panel.annotation.title': '\u622A\u56FE\u53CD\u9988',
+  'panel.type': '\u95EE\u9898\u7C7B\u578B',
+  'panel.description': '\u95EE\u9898\u63CF\u8FF0',
+  'panel.description.placeholder': '\u63CF\u8FF0\u4F60\u53D1\u73B0\u7684\u95EE\u9898...',
+  'panel.cancel': '\u53D6\u6D88',
+  'panel.submit': '\u63D0\u4EA4',
+  // Toast
+  'toast.flagged': '\u5DF2\u6807\u8BB0',
+  'toast.submitted': '\u53CD\u9988\u5DF2\u63D0\u4EA4',
+  'toast.failed': '\u63D0\u4EA4\u5931\u8D25',
+  'toast.screenshotFailed': '\u622A\u56FE\u5931\u8D25',
+  'toast.clickToFlag': '\u70B9\u51FB\u95EE\u9898\u5143\u7D20\u6765\u6807\u8BB0',
+  // Region selector
+  'region.hint': '\u62D6\u62FD\u9009\u62E9\u533A\u57DF \xB7 ESC \u53D6\u6D88',
+  // Verify
+  'verify.title': '\u9A8C\u8BC1\u4FEE\u590D',
+  'verify.fixed': '\u5DF2\u4FEE\u590D',
+  'verify.broken': '\u672A\u4FEE\u590D',
+  // Problem types
+  'type.bug': 'Bug',
+  'type.ui-issue': 'UI',
+  'type.performance': 'Performance',
+  'type.feature-request': 'Feature',
+  'type.other': 'Other',
+};
+
+const en: Record<string, string> = {
+  'hint.firstTime': 'Found a problem? Click me or press Alt+Q to flag it.',
+  'mode.quick': 'Quick',
+  'mode.quick.hint': 'Tap problem',
+  'mode.detail': 'Describe',
+  'mode.detail.hint': 'Tap + fill form',
+  'mode.screenshot': 'Screenshot',
+  'mode.screenshot.hint': 'Select area + draw',
+  'panel.element.title': 'Element Feedback',
+  'panel.annotation.title': 'Annotation Feedback',
+  'panel.type': 'Problem Type',
+  'panel.description': 'Description',
+  'panel.description.placeholder': 'Describe the issue...',
+  'panel.cancel': 'Cancel',
+  'panel.submit': 'Submit',
+  'toast.flagged': 'Flagged!',
+  'toast.submitted': 'Feedback submitted',
+  'toast.failed': 'Submit failed',
+  'toast.screenshotFailed': 'Screenshot failed',
+  'toast.clickToFlag': 'Click the problem element to flag it',
+  'region.hint': 'Drag to select area \xB7 ESC to cancel',
+  'verify.title': 'Verify Fix',
+  'verify.fixed': 'Fixed',
+  'verify.broken': 'Still broken',
+  'type.bug': 'Bug',
+  'type.ui-issue': 'UI',
+  'type.performance': 'Performance',
+  'type.feature-request': 'Feature',
+  'type.other': 'Other',
+};
+
+let currentLang: Record<string, string> = en;
+
+export function initI18n(): void {
+  const htmlLang = document.documentElement.lang?.toLowerCase() || '';
+  if (htmlLang.startsWith('zh')) {
+    currentLang = zhCN;
+  } else {
+    currentLang = en;
+  }
+}
+
+export function t(key: string): string {
+  return currentLang[key] || en[key] || key;
+}

package/src/client/core/sdk.ts

@@ -0,0 +1,373 @@
+import { ShadowHost } from './shadow-host.js';
+import { EventBus } from './event-bus.js';
+import { FloatingButton } from '../ui/floating-button.js';
+import { FeedbackPanel, type PanelResult } from '../ui/feedback-panel.js';
+import { showToast } from '../ui/toast.js';
+import { ChecklistPanel } from '../ui/checklist-panel.js';
+import { VerifyPanel } from '../ui/verify-panel.js';
+import { Highlighter } from '../element-mode/highlighter.js';
+import { inspectElement, type ElementInfo } from '../element-mode/inspector.js';
+import { captureScreenshot } from '../annotation-mode/screenshot.js';
+import { RegionSelector } from '../annotation-mode/region-selector.js';
+import { CanvasEditor } from '../annotation-mode/canvas-editor.js';
+import { ContextBuffer } from '../capture/context-buffer.js';
+import { ConsoleInterceptor, type ConsoleEntry } from '../capture/console-interceptor.js';
+import { NetworkInterceptor, type NetworkEntry } from '../capture/network-interceptor.js';
+import { ErrorInterceptor, type ErrorEntry } from '../capture/error-interceptor.js';
+import { ApiClient, type FeedbackPayload } from '../api/client.js';
+import { ActionRecorder } from '../capture/action-recorder.js';
+import { t } from './i18n.js';
+
+type Mode = 'flag' | 'detail' | 'annotate';
+
+export class VibeFeedback {
+  private shadowHost: ShadowHost;
+  private eventBus: EventBus;
+  private fab: FloatingButton;
+  private panel: FeedbackPanel;
+  private highlighter: Highlighter;
+  private apiClient: ApiClient;
+
+  private actionRecorder = new ActionRecorder();
+  private consoleBuffer = new ContextBuffer<ConsoleEntry>(50);
+  private networkBuffer = new ContextBuffer<NetworkEntry>(50);
+  private errorBuffer = new ContextBuffer<ErrorEntry>(50);
+  private consoleInterceptor: ConsoleInterceptor;
+  private networkInterceptor: NetworkInterceptor;
+  private errorInterceptor: ErrorInterceptor;
+
+  private checklistPanel: ChecklistPanel | null = null;
+  private verifyPanel: VerifyPanel | null = null;
+  private active = false;
+  private mode: Mode | null = null;
+  private modeBar: HTMLDivElement | null = null;
+  private selectedElement: ElementInfo | null = null;
+  private annotationDataUrl: string | null = null;
+  private activeChecklistItemId: number | null = null;
+  private keyHandler: (e: KeyboardEvent) => void;
+
+  constructor() {
+    this.shadowHost = new ShadowHost();
+    this.eventBus = new EventBus();
+    this.apiClient = new ApiClient();
+
+    // Context capture
+    this.consoleInterceptor = new ConsoleInterceptor(this.consoleBuffer);
+    this.networkInterceptor = new NetworkInterceptor(this.networkBuffer);
+    this.errorInterceptor = new ErrorInterceptor(this.errorBuffer);
+    this.consoleInterceptor.install();
+    this.networkInterceptor.install();
+    this.errorInterceptor.install();
+    this.actionRecorder.start();
+
+    // Checklist + Verify panels
+    this.checklistPanel = new ChecklistPanel(
+      this.shadowHost.shadow,
+      (itemId) => this.onChecklistFail(itemId)
+    );
+    this.checklistPanel.startPolling();
+    this.verifyPanel = new VerifyPanel(this.shadowHost.shadow);
+    this.verifyPanel.startPolling();
+
+    // UI
+    this.fab = new FloatingButton(this.shadowHost.shadow, () => this.toggleModeBar());
+    this.highlighter = new Highlighter((el) => this.onElementSelected(el));
+    this.panel = new FeedbackPanel(
+      this.shadowHost.shadow,
+      (result) => this.onSubmit(result),
+      () => this.cancelFeedback()
+    );
+
+    // Global keyboard shortcuts — always active
+    this.keyHandler = (e: KeyboardEvent) => this.onKeyDown(e);
+    document.addEventListener('keydown', this.keyHandler);
+  }
+
+  // ──────── Keyboard shortcuts ────────
+  private onKeyDown(e: KeyboardEvent): void {
+    // Don't intercept when typing in inputs
+    const tag = (e.target as HTMLElement)?.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+    // Don't intercept inside our SDK panels
+    if (this.isSDKElement(e.target as Element)) return;
+
+    // All shortcuts use Alt+key (or Option+key on Mac) to avoid conflicts
+    if (e.altKey) {
+      switch (e.key) {
+        case 'q': case 'Q':
+          e.preventDefault();
+          this.enterMode('flag');
+          return;
+        case 'd': case 'D':
+          e.preventDefault();
+          this.enterMode('detail');
+          return;
+        case 's': case 'S':
+          e.preventDefault();
+          this.enterMode('annotate');
+          return;
+        case 'x': case 'X':
+          e.preventDefault();
+          if (this.active) this.exitTestMode();
+          else this.toggleModeBar();
+          return;
+      }
+    }
+    // Esc always exits test mode (universal convention)
+    if (e.key === 'Escape' && this.active) {
+      e.preventDefault();
+      this.exitTestMode();
+    }
+  }
+
+  private isSDKElement(el: Element | null): boolean {
+    while (el) {
+      if (el.id === 'vibe-feedback-host') return true;
+      el = el.parentElement;
+    }
+    return false;
+  }
+
+  // ──────── Mode management ────────
+
+  /** Enter a specific mode directly — skips mode bar */
+  private enterMode(mode: Mode): void {
+    if (!this.active) {
+      this.active = true;
+      this.fab.setActive(true);
+    }
+    this.mode = mode;
+    this.hideModeBar();
+    this.showModeBar();
+    // Highlight active button
+    const idx = mode === 'flag' ? 0 : mode === 'detail' ? 1 : 2;
+    this.modeBar?.querySelectorAll('.vf-mode-btn').forEach((btn, i) => {
+      btn.classList.toggle('active', i === idx);
+    });
+    this.activateMode();
+  }
+
+  /** Toggle mode bar visibility (FAB click) */
+  private toggleModeBar(): void {
+    if (this.active) {
+      this.exitTestMode();
+    } else {
+      this.active = true;
+      this.fab.setActive(true);
+      this.mode = null;
+      this.showModeBar();
+    }
+  }
+
+  private exitTestMode(): void {
+    this.active = false;
+    this.fab.setActive(false);
+    this.deactivateAll();
+  }
+
+  private showModeBar(): void {
+    if (this.modeBar) return;
+
+    this.modeBar = document.createElement('div');
+    this.modeBar.className = 'vf-mode-bar';
+
+    const modes: { mode: Mode; label: string; hint: string; key: string }[] = [
+      { mode: 'flag', label: t('mode.quick'), hint: t('mode.quick.hint'), key: 'Alt+Q' },
+      { mode: 'detail', label: t('mode.detail'), hint: t('mode.detail.hint'), key: 'Alt+D' },
+      { mode: 'annotate', label: t('mode.screenshot'), hint: t('mode.screenshot.hint'), key: 'Alt+S' },
+    ];
+
+    for (const m of modes) {
+      const btn = document.createElement('button');
+      btn.className = `vf-mode-btn${this.mode === m.mode ? ' active' : ''}`;
+      btn.innerHTML = `
+        <div style="display:flex;align-items:center;gap:6px;font-size:13px">
+          ${m.label}
+          <span style="font-size:10px;opacity:0.4;background:rgba(255,255,255,0.1);padding:1px 5px;border-radius:3px;">${m.key}</span>
+        </div>
+        <div style="font-size:10px;opacity:0.5;margin-top:1px">${m.hint}</div>
+      `;
+      btn.addEventListener('click', () => {
+        this.mode = m.mode;
+        this.modeBar!.querySelectorAll('.vf-mode-btn').forEach((b) => b.classList.remove('active'));
+        btn.classList.add('active');
+        this.activateMode();
+      });
+      this.modeBar.appendChild(btn);
+    }
+
+    this.shadowHost.append(this.modeBar);
+  }
+
+  private hideModeBar(): void {
+    this.modeBar?.remove();
+    this.modeBar = null;
+  }
+
+  private activateMode(): void {
+    this.highlighter.deactivate();
+    if (!this.mode) return;
+
+    if (this.mode === 'flag' || this.mode === 'detail') {
+      this.highlighter.activate();
+    } else {
+      this.startAnnotation();
+    }
+  }
+
+  private deactivateAll(): void {
+    this.highlighter.deactivate();
+    this.panel.hide();
+    this.hideModeBar();
+    this.selectedElement = null;
+    this.annotationDataUrl = null;
+    this.activeChecklistItemId = null;
+  }
+
+  // ──────── Element selected ────────
+  private onElementSelected(el: Element): void {
+    this.selectedElement = inspectElement(el);
+
+    if (this.mode === 'flag') {
+      this.quickFlag();
+    } else {
+      this.highlighter.deactivate();
+      this.hideModeBar();
+      this.panel.showForElement(this.selectedElement);
+    }
+  }
+
+  // ──────── Quick flag ────────
+  private async quickFlag(): Promise<void> {
+    const payload = this.buildPayload('bug', '');
+    try {
+      const { id } = await this.apiClient.submitFeedback(payload);
+      showToast(this.shadowHost.shadow, `${t('toast.flagged')} (${id})`);
+
+      if (this.activeChecklistItemId !== null) {
+        await this.linkFeedbackToChecklist(id, this.activeChecklistItemId);
+        this.activeChecklistItemId = null;
+      }
+    } catch {
+      showToast(this.shadowHost.shadow, t('toast.failed'), true);
+    }
+    this.selectedElement = null;
+  }
+
+  // ──────── Checklist integration ────────
+  private onChecklistFail(itemId: number): void {
+    this.activeChecklistItemId = itemId;
+    this.enterMode('flag');
+    showToast(this.shadowHost.shadow, t('toast.clickToFlag'));
+  }
+
+  private async linkFeedbackToChecklist(feedbackId: string, checklistItemId: number): Promise<void> {
+    try {
+      await fetch(`${window.location.origin}/api/checklist/${checklistItemId}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ status: 'failed', feedback: `[linked:${feedbackId}]` }),
+      });
+    } catch {}
+  }
+
+  // ──────── Annotation ────────
+  private async startAnnotation(): Promise<void> {
+    this.hideModeBar();
+    this.fab.setActive(false);
+
+    try {
+      const fullScreenshot = await captureScreenshot();
+      const selector = new RegionSelector(
+        (rect) => {
+          const dpr = Math.min(window.devicePixelRatio, 2);
+          const cropCanvas = document.createElement('canvas');
+          cropCanvas.width = rect.w * dpr;
+          cropCanvas.height = rect.h * dpr;
+          const cropCtx = cropCanvas.getContext('2d')!;
+          cropCtx.drawImage(fullScreenshot,
+            rect.x * dpr, rect.y * dpr, rect.w * dpr, rect.h * dpr,
+            0, 0, rect.w * dpr, rect.h * dpr
+          );
+          const editor = new CanvasEditor(
+            cropCanvas,
+            (dataUrl) => {
+              this.annotationDataUrl = dataUrl;
+              this.fab.setActive(true);
+              this.panel.showForAnnotation(dataUrl);
+            },
+            () => { this.fab.setActive(true); this.showModeBar(); }
+          );
+          editor.show();
+        },
+        () => { this.fab.setActive(true); this.showModeBar(); }
+      );
+      selector.show();
+    } catch {
+      showToast(this.shadowHost.shadow, t('toast.screenshotFailed'), true);
+      this.fab.setActive(true);
+      this.showModeBar();
+    }
+  }
+
+  // ──────── Payload ────────
+  private buildPayload(problemType: string, description: string): FeedbackPayload {
+    return {
+      mode: this.selectedElement ? 'element' : 'annotation',
+      problemType, description,
+      element: this.selectedElement || undefined,
+      pageUrl: window.location.href,
+      pageTitle: document.title,
+      viewport: { width: window.innerWidth, height: window.innerHeight },
+      userAgent: navigator.userAgent,
+      timestamp: Date.now(),
+      consoleErrors: this.consoleBuffer.getAll(),
+      networkErrors: this.networkBuffer.getAll(),
+      unhandledErrors: this.errorBuffer.getAll(),
+      actionSteps: this.actionRecorder.getSteps(),
+    };
+  }
+
+  // ──────── Submit ────────
+  private async onSubmit(result: PanelResult): Promise<void> {
+    const payload = this.buildPayload(result.problemType, result.description);
+    try {
+      const { id } = await this.apiClient.submitFeedback(payload, this.annotationDataUrl || undefined);
+      showToast(this.shadowHost.shadow, `${t('toast.submitted')} (${id})`);
+      if (this.activeChecklistItemId !== null) {
+        await this.linkFeedbackToChecklist(id, this.activeChecklistItemId);
+        this.activeChecklistItemId = null;
+      }
+    } catch {
+      showToast(this.shadowHost.shadow, t('toast.failed'), true);
+    }
+    this.panel.hide();
+    this.selectedElement = null;
+    this.annotationDataUrl = null;
+    this.showModeBar();
+    this.activateMode();
+  }
+
+  private cancelFeedback(): void {
+    this.panel.hide();
+    this.selectedElement = null;
+    this.annotationDataUrl = null;
+    this.activeChecklistItemId = null;
+    this.showModeBar();
+    this.activateMode();
+  }
+
+  // ──────── Cleanup ────────
+  destroy(): void {
+    document.removeEventListener('keydown', this.keyHandler);
+    this.deactivateAll();
+    this.consoleInterceptor.uninstall();
+    this.networkInterceptor.uninstall();
+    this.errorInterceptor.uninstall();
+    this.actionRecorder.stop();
+    this.checklistPanel?.destroy();
+    this.verifyPanel?.destroy();
+    this.fab.destroy();
+    this.shadowHost.destroy();
+  }
+}

package/src/client/core/shadow-host.ts

@@ -0,0 +1,27 @@
+import { SDK_CSS } from '../styles/sdk.css.js';
+
+export class ShadowHost {
+  readonly host: HTMLDivElement;
+  readonly shadow: ShadowRoot;
+
+  constructor() {
+    this.host = document.createElement('div');
+    this.host.id = 'vibe-feedback-host';
+    this.host.style.cssText =
+      'position:fixed;z-index:2147483647;top:0;left:0;width:0;height:0;pointer-events:none;';
+    document.body.appendChild(this.host);
+    this.shadow = this.host.attachShadow({ mode: 'open' });
+
+    const style = document.createElement('style');
+    style.textContent = SDK_CSS;
+    this.shadow.appendChild(style);
+  }
+
+  append(el: HTMLElement): void {
+    this.shadow.appendChild(el);
+  }
+
+  destroy(): void {
+    this.host.remove();
+  }
+}

package/src/client/element-mode/highlighter.ts

@@ -0,0 +1,79 @@
+export class Highlighter {
+  private overlay: HTMLDivElement;
+  private currentTarget: Element | null = null;
+  private moveHandler: (e: MouseEvent) => void;
+  private clickHandler: (e: MouseEvent) => void;
+  private active = false;
+
+  constructor(private onSelect: (element: Element) => void) {
+    this.overlay = document.createElement('div');
+    this.overlay.style.cssText = `
+      position: fixed;
+      pointer-events: none;
+      z-index: 2147483646;
+      background: rgba(59,130,246,0.12);
+      border: 2px solid rgba(59,130,246,0.7);
+      border-radius: 3px;
+      transition: all 0.06s ease-out;
+      display: none;
+    `;
+
+    this.moveHandler = (e: MouseEvent) => this.onMouseMove(e);
+    this.clickHandler = (e: MouseEvent) => this.onClick(e);
+  }
+
+  activate(): void {
+    if (this.active) return;
+    this.active = true;
+    document.body.appendChild(this.overlay);
+    document.addEventListener('mousemove', this.moveHandler, true);
+    document.addEventListener('click', this.clickHandler, true);
+    document.body.style.cursor = 'crosshair';
+  }
+
+  deactivate(): void {
+    if (!this.active) return;
+    this.active = false;
+    this.overlay.style.display = 'none';
+    this.overlay.remove();
+    document.removeEventListener('mousemove', this.moveHandler, true);
+    document.removeEventListener('click', this.clickHandler, true);
+    document.body.style.cursor = '';
+    this.currentTarget = null;
+  }
+
+  private onMouseMove(e: MouseEvent): void {
+    const target = document.elementFromPoint(e.clientX, e.clientY);
+    if (!target || this.isSDKElement(target) || target === this.currentTarget) return;
+
+    this.currentTarget = target;
+    const rect = target.getBoundingClientRect();
+    this.overlay.style.display = 'block';
+    this.overlay.style.top = `${rect.top}px`;
+    this.overlay.style.left = `${rect.left}px`;
+    this.overlay.style.width = `${rect.width}px`;
+    this.overlay.style.height = `${rect.height}px`;
+  }
+
+  private onClick(e: MouseEvent): void {
+    const target = document.elementFromPoint(e.clientX, e.clientY);
+    if (!target || this.isSDKElement(target)) return;
+
+    e.preventDefault();
+    e.stopPropagation();
+    e.stopImmediatePropagation();
+
+    this.onSelect(target);
+  }
+
+  private isSDKElement(el: Element): boolean {
+    // Check if element is part of our SDK
+    let current: Element | null = el;
+    while (current) {
+      if (current.id === 'vibe-feedback-host') return true;
+      if ((current as HTMLElement).style?.zIndex === '2147483646') return true;
+      current = current.parentElement;
+    }
+    return false;
+  }
+}

package/src/client/element-mode/inspector.ts

@@ -0,0 +1,73 @@
+import { generateSelector } from './selector.js';
+
+export interface ElementInfo {
+  selector: string;
+  tagName: string;
+  textContent: string;
+  rect: { x: number; y: number; width: number; height: number };
+  computedStyles: Record<string, string>;
+  attributes: Record<string, string>;
+  componentName: string | null;
+  componentFile: string | null;
+}
+
+const STYLE_PROPS = [
+  'display', 'position', 'width', 'height', 'margin', 'padding',
+  'color', 'background-color', 'font-size', 'font-weight',
+  'border', 'opacity', 'cursor', 'visibility', 'overflow',
+  'flex-direction', 'align-items', 'justify-content', 'gap',
+];
+
+export function inspectElement(el: Element): ElementInfo {
+  const rect = el.getBoundingClientRect();
+  const computed = window.getComputedStyle(el);
+
+  const styles: Record<string, string> = {};
+  for (const prop of STYLE_PROPS) {
+    styles[prop] = computed.getPropertyValue(prop);
+  }
+
+  const attrs: Record<string, string> = {};
+  for (const attr of el.attributes) {
+    if (attr.name.startsWith('data-') || ['class', 'href', 'src', 'type', 'name', 'placeholder'].includes(attr.name)) {
+      attrs[attr.name] = attr.value.slice(0, 100);
+    }
+  }
+
+  return {
+    selector: generateSelector(el),
+    tagName: el.tagName.toLowerCase(),
+    textContent: (el.textContent || '').trim().slice(0, 200),
+    rect: { x: Math.round(rect.x), y: Math.round(rect.y), width: Math.round(rect.width), height: Math.round(rect.height) },
+    computedStyles: styles,
+    attributes: attrs,
+    componentName: getComponentName(el),
+    componentFile: null, // Source file detection is unreliable
+  };
+}
+
+function getComponentName(el: Element): string | null {
+  // React: __reactFiber$ or __reactInternalInstance$
+  const fiberKey = Object.keys(el).find(
+    (k) => k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$')
+  );
+  if (fiberKey) {
+    let fiber = (el as any)[fiberKey];
+    while (fiber) {
+      if (typeof fiber.type === 'function') {
+        return fiber.type.displayName || fiber.type.name || null;
+      }
+      fiber = fiber.return;
+    }
+  }
+
+  // Vue 2
+  const vue2 = (el as any).__vue__;
+  if (vue2) return vue2.$options?.name || vue2.$options?._componentTag || null;
+
+  // Vue 3
+  const vue3 = (el as any).__vueParentComponent;
+  if (vue3) return vue3.type?.name || vue3.type?.__name || null;
+
+  return null;
+}

package/src/client/element-mode/selector.ts

@@ -0,0 +1,22 @@
+export function generateSelector(el: Element): string {
+  // Priority: data-testid > id > nth-child path
+  const testId = el.getAttribute('data-testid');
+  if (testId) return `[data-testid="${testId}"]`;
+
+  if (el.id) return `#${CSS.escape(el.id)}`;
+
+  const parts: string[] = [];
+  let current: Element | null = el;
+  while (current && current !== document.body && current !== document.documentElement) {
+    const parent = current.parentElement;
+    if (!parent) break;
+    const children = Array.from(parent.children);
+    const index = children.indexOf(current) + 1;
+    const tag = current.tagName.toLowerCase();
+    parts.unshift(`${tag}:nth-child(${index})`);
+    current = parent;
+    // Keep path reasonable
+    if (parts.length > 5) break;
+  }
+  return parts.join(' > ');
+}

package/src/client/index.ts

@@ -0,0 +1,10 @@
+import { initI18n } from './core/i18n.js';
+import { VibeFeedback } from './core/sdk.js';
+
+// Detect language before anything renders
+initI18n();
+
+const instance = new VibeFeedback();
+
+// Expose globally for potential programmatic use
+(window as any).__vibeFeedback = instance;