@peaske7/readit 0.1.8 → 0.2.1

package/e2e/perf/utils/metrics.ts

@@ -0,0 +1,350 @@
+import type { Page, TestInfo } from "@playwright/test";
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface LoadMetrics {
+  fcp: number | null;
+  domContentLoaded: number;
+  allHighlightsPainted: number;
+  pageReady: number | null;
+  highlightCount: number;
+}
+
+export interface ScrollMetrics {
+  totalTimeMs: number;
+  longTaskCount: number;
+  longTaskDurations: number[];
+  p50: number;
+  p95: number;
+  p99: number;
+}
+
+export interface InteractionMetrics {
+  durationMs: number;
+}
+
+// ─── Wait for highlights ─────────────────────────────────────────────
+
+/**
+ * Polls the DOM for comment highlights until either:
+ * - The expected count is reached, OR
+ * - The count stabilizes (no change for `stableMs` milliseconds)
+ *
+ * Returns the timestamp when highlights finished painting.
+ * Not all comments may resolve to highlights (anchor failures, overlaps).
+ */
+export async function waitForHighlightCount(
+  page: Page,
+  expectedCount: number,
+  timeoutMs = 60_000,
+): Promise<number> {
+  return page.evaluate(
+    ({ expected, timeout, stableWindow }) => {
+      return new Promise<number>((resolve, reject) => {
+        const deadline = performance.now() + timeout;
+        let lastCount = 0;
+        let lastChangeTime = performance.now();
+
+        const check = () => {
+          // Use the CSS Custom Highlight API observability hook
+          const highlights = (window as unknown as Record<string, unknown>)
+            .__readitHighlights as { commentIds: string[] } | undefined;
+          const count = highlights?.commentIds?.length ?? 0;
+
+          // Exact target reached
+          if (count >= expected) {
+            resolve(performance.now());
+            return;
+          }
+
+          // Track changes for stabilization
+          if (count !== lastCount) {
+            lastCount = count;
+            lastChangeTime = performance.now();
+          }
+
+          // Stabilized: count hasn't changed for stableWindow ms and we have > 0 highlights
+          if (count > 0 && performance.now() - lastChangeTime > stableWindow) {
+            resolve(performance.now());
+            return;
+          }
+
+          if (performance.now() > deadline) {
+            reject(
+              new Error(
+                `Timed out: expected ${expected} highlights, found ${count}`,
+              ),
+            );
+            return;
+          }
+
+          requestAnimationFrame(check);
+        };
+
+        requestAnimationFrame(check);
+      });
+    },
+    { expected: expectedCount, timeout: timeoutMs, stableWindow: 2000 },
+  );
+}
+
+// ─── Wait for positions ─────────────────────────────────────────────
+
+/**
+ * Waits until Positions.cache() has run AFTER highlights were painted.
+ * The `afterTimestamp` ensures we don't capture the initial empty cache()
+ * that runs before highlights exist.
+ */
+async function waitForPositionsReady(
+  page: Page,
+  afterTimestamp: number,
+  timeoutMs = 60_000,
+): Promise<number> {
+  return page.evaluate(
+    ({ after, timeout }) => {
+      return new Promise<number>((resolve, reject) => {
+        const deadline = performance.now() + timeout;
+
+        const check = () => {
+          const ts = (window as unknown as Record<string, unknown>)
+            .__readitPositionsReady as number | undefined;
+
+          // Only resolve if positions were computed AFTER highlights painted
+          if (ts !== undefined && ts > after) {
+            resolve(ts);
+            return;
+          }
+
+          if (performance.now() > deadline) {
+            reject(new Error("Timed out waiting for positions to be ready"));
+            return;
+          }
+
+          requestAnimationFrame(check);
+        };
+
+        requestAnimationFrame(check);
+      });
+    },
+    { after: afterTimestamp, timeout: timeoutMs },
+  );
+}
+
+// ─── Collect load metrics ────────────────────────────────────────────
+
+/**
+ * Navigates to the URL and collects load + highlight timing metrics.
+ */
+export async function collectLoadMetrics(
+  page: Page,
+  url: string,
+  expectedComments: number,
+): Promise<LoadMetrics> {
+  await page.goto(url);
+
+  const highlightTimestamp = await waitForHighlightCount(
+    page,
+    expectedComments,
+  );
+
+  // Wait for positions to be computed AFTER highlights
+  // (captures the forced reflow cost from getBoundingClientRect)
+  let pageReadyTimestamp: number | null;
+  try {
+    pageReadyTimestamp = await waitForPositionsReady(
+      page,
+      highlightTimestamp,
+      10_000,
+    );
+  } catch (error) {
+    if (
+      !(error instanceof Error) ||
+      !error.message.includes("Timed out waiting for positions")
+    ) {
+      throw error;
+    }
+    // Positions may not fire in all configurations
+    pageReadyTimestamp = null;
+  }
+
+  const navMetrics = await page.evaluate(() => {
+    const nav = performance.getEntriesByType(
+      "navigation",
+    )[0] as PerformanceNavigationTiming;
+    const paintEntries = performance.getEntriesByType("paint");
+    const fcp = paintEntries.find((e) => e.name === "first-contentful-paint");
+    // Use CSS Custom Highlight API observability hook
+    const highlights = (window as unknown as Record<string, unknown>)
+      .__readitHighlights as { commentIds: string[] } | undefined;
+    const actualCount = highlights?.commentIds?.length ?? 0;
+
+    return {
+      fcp: fcp ? fcp.startTime : null,
+      domContentLoaded: nav.domContentLoadedEventEnd,
+      actualCount,
+    };
+  });
+
+  return {
+    fcp: navMetrics.fcp,
+    domContentLoaded: navMetrics.domContentLoaded,
+    allHighlightsPainted: highlightTimestamp,
+    pageReady: pageReadyTimestamp,
+    highlightCount: navMetrics.actualCount,
+  };
+}
+
+// ─── Collect scroll metrics ──────────────────────────────────────────
+
+/**
+ * Scrolls programmatically from top to bottom, collecting Long Task entries.
+ */
+export async function collectScrollMetrics(
+  page: Page,
+  stepPx = 600,
+  intervalMs = 150,
+): Promise<ScrollMetrics> {
+  return page.evaluate(
+    ({ step, interval }) => {
+      return new Promise<{
+        totalTimeMs: number;
+        longTaskCount: number;
+        longTaskDurations: number[];
+        p50: number;
+        p95: number;
+        p99: number;
+      }>((resolve) => {
+        const longTasks: number[] = [];
+
+        // Observe Long Tasks during scroll only (no buffered — excludes page load jank)
+        const obs = new PerformanceObserver((list) => {
+          for (const entry of list.getEntries()) {
+            longTasks.push(entry.duration);
+          }
+        });
+        obs.observe({ type: "longtask" });
+
+        const totalHeight = document.documentElement.scrollHeight;
+        const start = performance.now();
+        let currentY = 0;
+
+        const scrollStep = () => {
+          currentY += step;
+          window.scrollTo(0, currentY);
+
+          if (currentY < totalHeight) {
+            setTimeout(scrollStep, interval);
+          } else {
+            // Wait a beat for final Long Tasks to fire
+            setTimeout(() => {
+              obs.disconnect();
+              const elapsed = performance.now() - start;
+
+              const sorted = [...longTasks].sort((a, b) => a - b);
+              const pct = (p: number) => {
+                if (sorted.length === 0) return 0;
+                const idx = Math.ceil((p / 100) * sorted.length) - 1;
+                return sorted[Math.max(0, idx)];
+              };
+
+              resolve({
+                totalTimeMs: elapsed,
+                longTaskCount: sorted.length,
+                longTaskDurations: sorted,
+                p50: pct(50),
+                p95: pct(95),
+                p99: pct(99),
+              });
+            }, 500);
+          }
+        };
+
+        // Start scrolling
+        window.scrollTo(0, 0);
+        setTimeout(scrollStep, interval);
+      });
+    },
+    { step: stepPx, interval: intervalMs },
+  );
+}
+
+// ─── Measure interaction timing ──────────────────────────────────────
+
+/**
+ * Sets a performance mark, runs the trigger, waits for condition, returns duration.
+ */
+export async function measureInteraction(
+  page: Page,
+  name: string,
+  trigger: () => Promise<void>,
+  waitFor: () => Promise<void>,
+): Promise<number> {
+  await page.evaluate((n) => performance.mark(`${n}-start`), name);
+
+  await trigger();
+  await waitFor();
+
+  return page.evaluate((n) => {
+    performance.mark(`${n}-end`);
+    const measure = performance.measure(n, `${n}-start`, `${n}-end`);
+    return measure.duration;
+  }, name);
+}
+
+// ─── Reporting ───────────────────────────────────────────────────────
+
+export function reportLoadMetrics(
+  testInfo: TestInfo,
+  label: string,
+  metrics: LoadMetrics,
+): void {
+  const lines = [
+    `--- ${label} ---`,
+    `  FCP:                    ${metrics.fcp !== null ? `${Math.round(metrics.fcp)}ms` : "N/A"}`,
+    `  DOM Content Loaded:     ${Math.round(metrics.domContentLoaded)}ms`,
+    `  All highlights painted: ${Math.round(metrics.allHighlightsPainted)}ms`,
+    `  Page ready (+ layout):  ${metrics.pageReady !== null ? `${Math.round(metrics.pageReady)}ms` : "N/A (positions timed out)"}`,
+    `  Highlights found:       ${metrics.highlightCount}`,
+  ];
+  console.log(lines.join("\n"));
+
+  testInfo.annotations.push({
+    type: "perf-metric",
+    description: JSON.stringify({ label, ...metrics }),
+  });
+}
+
+export function reportScrollMetrics(
+  testInfo: TestInfo,
+  label: string,
+  metrics: ScrollMetrics,
+): void {
+  const lines = [
+    `--- ${label} ---`,
+    `  Total scroll time:    ${Math.round(metrics.totalTimeMs)}ms`,
+    `  Long tasks (>50ms):   ${metrics.longTaskCount}`,
+    `  P50 long task:        ${Math.round(metrics.p50)}ms`,
+    `  P95 long task:        ${Math.round(metrics.p95)}ms`,
+    `  P99 long task:        ${Math.round(metrics.p99)}ms`,
+  ];
+  console.log(lines.join("\n"));
+
+  testInfo.annotations.push({
+    type: "perf-metric",
+    description: JSON.stringify({ label, ...metrics }),
+  });
+}
+
+export function reportInteraction(
+  testInfo: TestInfo,
+  label: string,
+  durationMs: number,
+): void {
+  console.log(`--- ${label} ---`);
+  console.log(`  Duration: ${Math.round(durationMs)}ms`);
+
+  testInfo.annotations.push({
+    type: "perf-metric",
+    description: JSON.stringify({ label, durationMs }),
+  });
+}

package/e2e/perf/utils/perf-cli.ts

@@ -0,0 +1,86 @@
+import type { ChildProcess } from "node:child_process";
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+
+interface SpawnPerfCliResult {
+  url: string;
+  process: ChildProcess;
+  cleanup: () => Promise<void>;
+}
+
+interface SpawnPerfCliOptions {
+  port?: number;
+}
+
+const CLI_PATH = resolve(import.meta.dirname, "../../../dist/cli.js");
+
+/**
+ * Start the readit CLI with one or more fixture files for perf testing.
+ * Uses --no-open (no --clean, so pre-seeded comments are loaded).
+ */
+export async function spawnPerfCli(
+  fixturePaths: string | string[],
+  options: SpawnPerfCliOptions = {},
+): Promise<SpawnPerfCliResult> {
+  const { port = 4600 } = options;
+
+  const paths = Array.isArray(fixturePaths) ? fixturePaths : [fixturePaths];
+  const args = [CLI_PATH, ...paths, "--no-open", "--port", String(port)];
+
+  const cliProcess = spawn("bun", args, {
+    cwd: resolve(import.meta.dirname, "../../.."),
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  const url = await waitForServerReady(cliProcess);
+
+  return {
+    url,
+    process: cliProcess,
+    cleanup: async () => {
+      cliProcess.kill("SIGTERM");
+      await new Promise<void>((resolve) => {
+        cliProcess.once("exit", () => resolve());
+        setTimeout(resolve, 2000);
+      });
+    },
+  };
+}
+
+function waitForServerReady(cliProcess: ChildProcess): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let output = "";
+
+    const timeout = setTimeout(() => {
+      reject(
+        new Error(`Server did not start within timeout. Output: ${output}`),
+      );
+    }, 30_000);
+
+    cliProcess.stdout?.on("data", (data: Buffer) => {
+      output += data.toString();
+
+      const urlMatch = output.match(/URL:\s+(http:\/\/[^\s]+)/);
+      if (urlMatch) {
+        clearTimeout(timeout);
+        resolve(urlMatch[1]);
+      }
+    });
+
+    cliProcess.stderr?.on("data", (data: Buffer) => {
+      output += data.toString();
+    });
+
+    cliProcess.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    cliProcess.on("exit", (code) => {
+      if (code !== 0 && code !== null) {
+        clearTimeout(timeout);
+        reject(new Error(`CLI exited with code ${code}: ${output}`));
+      }
+    });
+  });
+}

package/e2e/persistence-file.spec.ts

@@ -57,7 +57,7 @@ test.describe("File-Based Comment Persistence", () => {
       await page.goto(url);
 
       // Wait for document to load
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article).toBeVisible();
 
       // Add a comment
@@ -96,7 +96,7 @@ test.describe("File-Based Comment Persistence", () => {
     try {
       await page.goto(url);
 
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article).toBeVisible();
 
       // Add a comment
@@ -119,8 +119,14 @@ test.describe("File-Based Comment Persistence", () => {
       await expect(page.locator("body")).toContainText(commentText);
 
       // Verify highlight still exists
-      const highlight = article.locator("mark[data-comment-id]").first();
-      await expect(highlight).toBeVisible();
+      await page.waitForFunction(
+        () => {
+          const h = (window as unknown as Record<string, unknown>)
+            .__readitHighlights as { commentIds: string[] } | undefined;
+          return h && h.commentIds.length > 0;
+        },
+        { timeout: 10_000 },
+      );
     } finally {
       await cleanup();
     }
@@ -140,7 +146,7 @@ test.describe("File-Based Comment Persistence", () => {
     try {
       await page.goto(url1);
 
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article).toBeVisible();
 
       await selectTextInArticle(page, "testing text selection");
@@ -164,15 +170,21 @@ test.describe("File-Based Comment Persistence", () => {
     try {
       await page.goto(url2);
 
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article).toBeVisible();
 
       // Comment should still exist from previous session
       await expect(page.locator("body")).toContainText(commentText);
 
       // Highlight should still exist
-      const highlight = article.locator("mark[data-comment-id]").first();
-      await expect(highlight).toBeVisible();
+      await page.waitForFunction(
+        () => {
+          const h = (window as unknown as Record<string, unknown>)
+            .__readitHighlights as { commentIds: string[] } | undefined;
+          return h && h.commentIds.length > 0;
+        },
+        { timeout: 10_000 },
+      );
     } finally {
       await cleanup2();
     }
@@ -214,15 +226,19 @@ Pre-existing comment to be cleared.
     try {
       await page.goto(url);
 
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article).toBeVisible();
 
       // Wait for clean operation to complete
       await page.waitForTimeout(500);
 
-      // Verify no comments in UI
-      const highlight = article.locator("mark[data-comment-id]");
-      await expect(highlight).toHaveCount(0);
+      // Verify no highlights via observability hook
+      const highlightCount = await page.evaluate(() => {
+        const h = (window as unknown as Record<string, unknown>)
+          .__readitHighlights as { commentIds: string[] } | undefined;
+        return h?.commentIds?.length ?? 0;
+      });
+      expect(highlightCount).toBe(0);
     } finally {
       await cleanup();
     }
@@ -237,7 +253,7 @@ Pre-existing comment to be cleared.
     try {
       await page.goto(url);
 
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article).toBeVisible();
 
       // Add initial comment
@@ -256,26 +272,25 @@ Pre-existing comment to be cleared.
       let fileContent = readFileSync(commentPath, "utf-8");
       expect(fileContent).toContain(initialComment);
 
-      // Find the margin note containing the selected text (stable identifier)
-      const marginNote = page
-        .locator(".group")
-        .filter({ hasText: textToSelect })
-        .first();
-      await marginNote.hover();
+      // Find the margin note by data-comment-id (first one)
+      const marginNote = page.locator("[data-comment-id]").first();
 
-      // Find and click edit button
-      const editButton = marginNote.locator('button:has-text("Edit")');
-      await editButton.click();
+      // Force-click edit button (may be hidden behind opacity-0 group-hover)
+      const editButton = marginNote.getByText("Edit").first();
+      await editButton.click({ force: true });
 
-      // Wait for edit mode to activate
-      const textarea = marginNote.locator("textarea");
+      // Wait for edit mode — find textarea globally since hasText filter breaks in edit mode
+      const textarea = page.locator("[data-comment-id] textarea");
       await expect(textarea).toBeVisible();
 
       // Clear and type new text
       await textarea.fill("Updated comment text");
 
       // Save edit
-      const saveButton = marginNote.locator('button:has-text("Save")');
+      const saveButton = page
+        .locator("[data-comment-id]")
+        .getByText("Save")
+        .first();
       await saveButton.click();
 
       // Wait for file to be updated
@@ -298,7 +313,7 @@ Pre-existing comment to be cleared.
     try {
       await page.goto(url);
 
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article).toBeVisible();
 
       // Add a comment

package/e2e/utils/selection.ts

@@ -1,4 +1,15 @@
-import type { FrameLocator, Page } from "@playwright/test";
+import type { Page } from "@playwright/test";
+
+/**
+ * Wait for the Svelte app to be fully mounted and interactive.
+ * The app sets data-readit-ready="true" on <html> after onMount.
+ */
+export async function waitForAppReady(page: Page): Promise<void> {
+  await page.waitForFunction(
+    () => document.documentElement.dataset.readitReady === "true",
+    { timeout: 10_000 },
+  );
+}
 
 /**
  * Select text within an article element (for markdown documents)
@@ -8,9 +19,12 @@ export async function selectTextInArticle(
   page: Page,
   textToSelect: string,
 ): Promise<void> {
+  // Ensure the Svelte app is fully mounted before dispatching events
+  await waitForAppReady(page);
+
   // Find text and calculate offsets, then dispatch custom event
   await page.evaluate((text) => {
-    const article = document.querySelector("article");
+    const article = document.querySelector("article#document-content");
     if (!article) throw new Error("Article element not found");
 
     const walker = document.createTreeWalker(article, NodeFilter.SHOW_TEXT);
@@ -39,78 +53,10 @@ export async function selectTextInArticle(
     throw new Error(`Text "${text}" not found in article`);
   }, textToSelect);
 
-  // Wait for React to process the selection
+  // Wait for Svelte to process the selection
   await page.waitForTimeout(100);
 }
 
-/**
- * Select text within an iframe (for HTML documents)
- * Uses custom event to trigger selection handler (same as markdown)
- */
-export async function selectTextInIframe(
-  page: Page,
-  _iframe: FrameLocator,
-  textToSelect: string,
-): Promise<void> {
-  // Get the actual frame object for evaluation
-  const frame = page.frame({ url: /^about:srcdoc/ }) || page.frames()[1];
-  if (!frame) throw new Error("Could not find iframe frame");
-
-  // Calculate offsets in iframe, then dispatch custom event to parent
-  const offsets = await frame.evaluate((text) => {
-    const body = document.body;
-    const walker = document.createTreeWalker(body, NodeFilter.SHOW_TEXT);
-    let currentOffset = 0;
-
-    while (walker.nextNode()) {
-      const textNode = walker.currentNode as Text;
-      const content = textNode.textContent || "";
-      const index = content.indexOf(text);
-
-      if (index !== -1) {
-        const startOffset = currentOffset + index;
-        const endOffset = startOffset + text.length;
-        return { text, startOffset, endOffset };
-      }
-
-      currentOffset += content.length;
-    }
-
-    throw new Error(`Text "${text}" not found in iframe`);
-  }, textToSelect);
-
-  // Dispatch custom event to parent window (IframeContainer listens for this)
-  await page.evaluate((detail) => {
-    const event = new CustomEvent("test:select-text", { detail });
-    window.dispatchEvent(event);
-  }, offsets);
-
-  // Wait for React to process state update
-  await page.waitForTimeout(200);
-
-  // Manually send applyHighlights to iframe (workaround for isReadyRef timing)
-  // This ensures the iframe gets the highlight even if React's useEffect hasn't fired
-  await page.evaluate(
-    (selection) => {
-      const iframe = document.querySelector("iframe");
-      if (iframe?.contentWindow) {
-        iframe.contentWindow.postMessage(
-          {
-            type: "applyHighlights",
-            comments: [],
-            pendingSelection: selection,
-          },
-          "*",
-        );
-      }
-    },
-    { startOffset: offsets.startOffset, endOffset: offsets.endOffset },
-  );
-
-  // Wait for iframe to apply highlights
-  await page.waitForTimeout(200);
-}
-
 /**
  * Add a comment to the current selection
  * Assumes CommentInputArea is visible
@@ -119,8 +65,6 @@ export async function addComment(
   page: Page,
   commentText: string,
 ): Promise<void> {
-  // Wait for the comment input textarea to appear
-  // Give more time for iframe postMessage round-trip
   const textarea = page.locator('textarea[placeholder="Add your comment..."]');
   await textarea.waitFor({ state: "visible", timeout: 10000 });