Merge pull request #31 from spencerkit/develop

Merge develop into main

Author: pallyoung

.changeset/swift-hounds-divide.md

@@ -0,0 +1,5 @@
+---
+"@spencer-kit/coder-studio": patch
+---
+
+Fix terminal websocket recovery so buffered PTY output is replayed after silent disconnects, including probe-based recovery and keepalive handling.

.gitignore

@@ -56,6 +56,8 @@ data-wl
 # E2E test runner scripts (ad-hoc)
 e2e/playwright.session.config.ts
 e2e/run-session-tests.*
+e2e-ui/output/
+e2e-ui/test-results/
 .playwright-cli/
 /superpowers/
 /.superpowers/

docs/help/assets/screenshot-workspace-overview.png

@@ -0,0 +1,41 @@
+import type { Locator, Page } from "@playwright/test";
+
+export async function disableAnimations(page: Page) {
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await page.addStyleTag({
+    content: `
+      *,
+      *::before,
+      *::after {
+        animation: none !important;
+        transition: none !important;
+        caret-color: transparent !important;
+      }
+    `,
+  });
+}
+
+export async function waitForFonts(page: Page) {
+  await page.evaluate(async () => {
+    if (!document.fonts?.ready) {
+      return;
+    }
+    await document.fonts.ready;
+  });
+}
+
+export async function waitForStableScene(page: Page) {
+  await disableAnimations(page);
+  await waitForFonts(page);
+  await page.waitForTimeout(80);
+}
+
+export async function resolveCaptureTarget(page: Page, selector?: string): Promise<Locator | Page> {
+  if (!selector) {
+    return page;
+  }
+
+  const target = page.locator(selector).first();
+  await target.waitFor({ state: "visible" });
+  return target;
+}

e2e-ui/fixtures/capture.ts

@@ -0,0 +1,37 @@
+import type { Page } from "@playwright/test";
+
+export interface OpenPreviewSceneArgs {
+  sceneId: string;
+  device: "desktop" | "mobile";
+  theme: "dark" | "light";
+  locale: "zh" | "en";
+}
+
+async function seedPreviewPreferences(
+  page: Page,
+  args: Pick<OpenPreviewSceneArgs, "theme" | "locale">
+) {
+  await page.goto("/ui-preview.html", {
+    waitUntil: "domcontentloaded",
+  });
+
+  await page.evaluate(({ theme, locale }) => {
+    window.localStorage.setItem("ui.theme", JSON.stringify(theme));
+    window.localStorage.setItem("ui.locale", JSON.stringify(locale));
+  }, args);
+}
+
+export async function openPreviewScene(page: Page, args: OpenPreviewSceneArgs) {
+  await seedPreviewPreferences(page, args);
+
+  const params = new URLSearchParams({
+    scene: args.sceneId,
+    device: args.device,
+    theme: args.theme,
+    locale: args.locale,
+  });
+
+  await page.goto(`/ui-preview.html?${params.toString()}`, {
+    waitUntil: "networkidle",
+  });
+}

e2e-ui/fixtures/prefs.ts

@@ -0,0 +1,88 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Page } from "@playwright/test";
+import type { UiCaptureScene, UiCaptureVariant } from "../scenes";
+import { resolveCaptureTarget, waitForStableScene } from "./capture";
+import { openPreviewScene } from "./prefs";
+
+const OUTPUT_ROOT = path.resolve(process.cwd(), "output");
+const SCREENSHOT_ROOT = path.join(OUTPUT_ROOT, "screenshots");
+
+export interface CaptureSceneVariantArgs {
+  scene: UiCaptureScene;
+  variant: UiCaptureVariant;
+}
+
+export function buildScreenshotPath(scene: UiCaptureScene, variant: UiCaptureVariant) {
+  return path.join(
+    SCREENSHOT_ROOT,
+    scene.category,
+    scene.id,
+    `${variant.device}__${variant.theme}__${variant.locale}.png`
+  );
+}
+
+export async function ensureParentDir(filePath: string) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+}
+
+async function openSettingsSection(
+  page: Page,
+  section: NonNullable<UiCaptureScene["settingsSection"]>,
+  device: UiCaptureVariant["device"]
+) {
+  const sectionOrder = {
+    general: 0,
+    providers: 1,
+    appearance: 2,
+    shortcuts: 3,
+  } as const;
+
+  const index = sectionOrder[section];
+
+  if (device === "mobile") {
+    await page.locator(".settings-mobile-item").nth(index).click();
+    await page.locator(".settings-content--mobile, .settings-content").first().waitFor();
+    return;
+  }
+
+  if (section !== "general") {
+    await page.locator(".settings-nav-item").nth(index).click();
+  }
+}
+
+export async function captureSceneVariant(page: Page, args: CaptureSceneVariantArgs) {
+  await openPreviewScene(page, {
+    sceneId: args.scene.id,
+    device: args.variant.device,
+    theme: args.variant.theme,
+    locale: args.variant.locale,
+  });
+
+  await waitForStableScene(page);
+
+  if (args.scene.settingsSection) {
+    await openSettingsSection(page, args.scene.settingsSection, args.variant.device);
+    await waitForStableScene(page);
+  }
+
+  const filePath = buildScreenshotPath(args.scene, args.variant);
+  await ensureParentDir(filePath);
+
+  if (args.scene.fullPage) {
+    await page.screenshot({
+      path: filePath,
+      animations: "disabled",
+      fullPage: true,
+      scale: "device",
+    });
+    return;
+  }
+
+  const target = await resolveCaptureTarget(page, args.scene.targetSelector);
+  await target.screenshot({
+    path: filePath,
+    animations: "disabled",
+    scale: "device",
+  });
+}

e2e-ui/fixtures/scene-runner.ts

@@ -0,0 +1,11 @@
+{
+  "name": "@coder-studio/e2e-ui",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "@playwright/test": "^1.59.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  }
+}

e2e-ui/package.json

@@ -0,0 +1,48 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const HOST = "127.0.0.1";
+const PORT = 4174;
+const BASE_URL = `http://${HOST}:${PORT}`;
+const iPhone14 = devices["iPhone 14"];
+
+export default defineConfig({
+  testDir: "./specs",
+  fullyParallel: false,
+  workers: 1,
+  retries: 0,
+  timeout: 60000,
+  reporter: [["list"]],
+  outputDir: "./test-results",
+  use: {
+    baseURL: BASE_URL,
+    trace: "off",
+    screenshot: "off",
+    video: "off",
+  },
+  projects: [
+    {
+      name: "desktop",
+      use: {
+        viewport: { width: 1440, height: 960 },
+      },
+    },
+    {
+      name: "mobile",
+      use: {
+        ...iPhone14,
+        browserName: "chromium",
+      },
+    },
+  ],
+  webServer: {
+    command: `pnpm --dir ../packages/web exec vite --host ${HOST} --port ${PORT}`,
+    cwd: ".",
+    url: `${BASE_URL}/ui-preview.html`,
+    reuseExistingServer: false,
+    timeout: 30000,
+    env: {
+      ...process.env,
+      NODE_ENV: "development",
+    },
+  },
+});

e2e-ui/playwright.config.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { buildManifestEntry, renderReportHtml } from "./build-report";
+
+describe("build-report", () => {
+  it("builds a manifest entry from a screenshot path", () => {
+    const entry = buildManifestEntry({
+      scene: {
+        id: "welcome",
+        title: "Welcome",
+        category: "page",
+        source: "real-route",
+        description: "Welcome page",
+      },
+      screenshotPath: "screenshots/page/welcome/desktop__dark__zh.png",
+      variant: {
+        device: "desktop",
+        theme: "dark",
+        locale: "zh",
+      },
+    });
+
+    expect(entry).toMatchObject({
+      id: "welcome",
+      category: "page",
+      path: "screenshots/page/welcome/desktop__dark__zh.png",
+      device: "desktop",
+      theme: "dark",
+      locale: "zh",
+    });
+  });
+
+  it("renders a report html shell with filters and grouped scenes", () => {
+    const html = renderReportHtml([
+      {
+        id: "welcome",
+        title: "Welcome",
+        category: "page",
+        source: "real-route",
+        device: "desktop",
+        theme: "dark",
+        locale: "zh",
+        path: "screenshots/page/welcome/desktop__dark__zh.png",
+        description: "Welcome page",
+      },
+    ]);
+
+    expect(html).toContain("UI Preview Report");
+    expect(html).toContain("screenshots/page/welcome/desktop__dark__zh.png");
+    expect(html).toContain('data-category="page"');
+  });
+});