Reconcile planning browser contracts and seed SAM frontend parity

Closes #198

Closes #199

Author: alexeygrigorev

backend/e2e/calendar-seams.spec.js

@@ -172,7 +172,8 @@ test("production portal calendar covers month/week, layers, overlay, dismiss/rea
     path: path.join(shots, "production-month-populated.png"),
   });
   await surface.locator("select[data-view]").selectOption("week");
-  await expect(surface.locator(".calendar-grid section.calendar-day")).toHaveCount(7);
+  await expect(surface.locator(".calendar-weeks > .calendar-week")).toHaveCount(1);
+  await expect(surface.locator(".calendar-weeks > .calendar-week > section.calendar-day")).toHaveCount(7);
   await surface.screenshot({ path: path.join(shots, "production-week.png") });
   await surface.locator('[data-layer="school"]').uncheck();
   await expect(surface.getByText("Summer holidays")).toHaveCount(0);
@@ -258,7 +259,8 @@ test("production calendar renders cross-year ISO weeks and Berlin DST boundary d
   await surface.locator("select[data-view]").selectOption("week");
   await expect(surface.getByText("Cross-year activity").first()).toBeVisible();
   await expect(surface.locator('time[datetime="2027-01-01"]')).toBeVisible();
-  await expect(surface.locator(".calendar-grid section.calendar-day")).toHaveCount(7);
+  await expect(surface.locator(".calendar-weeks > .calendar-week")).toHaveCount(1);
+  await expect(surface.locator(".calendar-weeks > .calendar-week > section.calendar-day")).toHaveCount(7);
   await expect(surface.locator(".iso-week")).toContainText(["ISO 53"]);
   await surface.screenshot({
     path: path.join(shots, "production-year-boundary.png"),

backend/e2e/frontend-module-characterization.spec.js

@@ -7,7 +7,7 @@ const { createDocsCacheRoot } = require("./helpers/docs-content-root");
 const { resolveTestServerCommand } = require("./helpers/tsx-launcher");
 
 const ROOT = path.resolve(__dirname, "..", "..");
-const SCREENSHOT_DIR = path.join(ROOT, ".tmp", "screenshots", "issue-190");
+const SCREENSHOT_DIR = path.join(ROOT, ".tmp", "screenshots", "issue-198");
 const FIXTURE_DOC_PATH = "content/overview/reference/schedule.md";
 const FIXTURE_DOC_TITLE = "Synthetic Characterization Schedule";
 const FIXTURE_DOC_SUMMARY = "Synthetic reference used only by browser characterization tests.";
@@ -335,11 +335,29 @@ test.describe("pre-refactor frontend module characterization", () => {
       await expect(page.locator("body")).toBeVisible();
       await expectNoHorizontalOverflow(page, route);
       if (route === "/users") {
-        const tableOverflow = await page.locator(".ops-users-table-wrap").evaluate((wrapper) => ({
-          clientWidth: wrapper.clientWidth,
-          scrollWidth: wrapper.scrollWidth,
-        }));
-        expect(tableOverflow.scrollWidth).toBeLessThanOrEqual(tableOverflow.clientWidth);
+        const userRow = page.locator(".ops-user-row").first();
+        await expect(userRow).toBeVisible();
+        const stackedRow = await userRow.evaluate((row) => {
+          const rect = row.getBoundingClientRect();
+          return {
+            display: getComputedStyle(row).display,
+            height: rect.height,
+            viewportWidth: document.documentElement.clientWidth,
+            width: rect.width,
+          };
+        });
+        expect(stackedRow.display).toBe("grid");
+        expect(stackedRow.height).toBeGreaterThan(48);
+        expect(stackedRow.width).toBeLessThanOrEqual(stackedRow.viewportWidth);
+        await expect(userRow.locator(".ops-user-name")).toBeVisible();
+        await expect(userRow.locator(".ops-user-email")).toBeVisible();
+        await expect(userRow.locator(".ops-user-role")).toBeVisible();
+        await expect(userRow.locator(".ops-user-created")).toBeVisible();
+        await expect(userRow.locator(".ops-user-actions .quiet-button").first()).toBeVisible();
+        await page.screenshot({
+          path: path.join(SCREENSHOT_DIR, "users-mobile-stacked.png"),
+          fullPage: true,
+        });
       }
     }
     expect(errors).toEqual([]);

backend/e2e/global-setup.js

@@ -4,7 +4,7 @@ const path = require('path');
 const fs = require('fs');
 const { resolveTestServerCommand } = require('./helpers/tsx-launcher');
 
-const TEST_SERVER_PORT = 3001;
+const { TEST_SERVER_PORT } = require('./test-server-port');
 const READY_TIMEOUT_MS = 30000;
 const POLL_INTERVAL_MS = 300;
 const READY_PATH = '/api/health';
@@ -26,14 +26,14 @@ const GRACE_USER = {
   createdAt: '2026-01-01T00:00:00.000Z',
 };
 
-function writeDefaultAuthState() {
+function writeDefaultAuthState(port = TEST_SERVER_PORT) {
   fs.writeFileSync(
     AUTH_STATE_PATH,
     JSON.stringify({
       cookies: [],
       origins: [
         {
-          origin: `http://localhost:${TEST_SERVER_PORT}`,
+          origin: `http://localhost:${port}`,
           localStorage: [
             { name: 'dataops_token', value: 'e2e-bypass-token' },
             { name: 'dataops_user', value: JSON.stringify(GRACE_USER) },
@@ -44,13 +44,13 @@ function writeDefaultAuthState() {
   );
 }
 
-function buildTestServerEnvironment(parentEnvironment = process.env) {
+function buildTestServerEnvironment(parentEnvironment = process.env, port = TEST_SERVER_PORT) {
   return {
     ...parentEnvironment,
     NODE_ENV: 'test',
     IS_LOCAL: 'true',
     SKIP_AUTH: 'true',
-    PORT: String(TEST_SERVER_PORT),
+    PORT: String(port),
     FRONTEND_ROOT: path.resolve(__dirname, '..', '..', 'frontend'),
     // Server-owned actor for template-admin tests only. Other route permission
     // tests retain their existing explicit actor/no-actor behavior.
@@ -146,7 +146,139 @@ function waitForServer(port, timeoutMs, options = {}) {
   });
 }
 
-async function globalSetup() {
+/**
+ * A health response proves that *a* server owns the fixed port, not that the
+ * child just spawned owns it. Require that child's successful listen log before
+ * probing health so a foreign listener cannot satisfy bootstrap.
+ */
+function waitForOwnedServer(child, port, timeoutMs) {
+  const readyMarker = `Test server listening at http://localhost:${port}`;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let retryTimer;
+    let activeRequest;
+    const deadline = Date.now() + timeoutMs;
+
+    function cleanup() {
+      clearTimeout(retryTimer);
+      if (activeRequest) activeRequest.destroy();
+      child.stdout?.off('data', onOutput);
+      child.stderr?.off('data', onErrorOutput);
+      child.off('error', onError);
+      child.off('exit', onExit);
+    }
+
+    function settle(operation) {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      operation();
+    }
+
+    function fail(message) {
+      settle(() => reject(new Error(message)));
+    }
+
+    function succeeded() {
+      settle(resolve);
+    }
+
+    function childStatus() {
+      return `code=${child.exitCode ?? 'none'}, signal=${child.signalCode ?? 'none'}`;
+    }
+
+    function scheduleProbe(delayMs) {
+      if (settled) return;
+      if (child.exitCode !== null || child.signalCode !== null) {
+        fail(`Test server child exited before readiness (${childStatus()}).`);
+        return;
+      }
+
+      const waitMs = Math.min(delayMs, Math.max(0, deadline - Date.now()));
+      if (waitMs <= 0 && retryTimer === undefined) {
+        fail(
+          `The spawned test server announced ${readyMarker}, but /api/health `
+          + `did not return HTTP 200 within ${timeoutMs}ms.`
+        );
+        return;
+      }
+      retryTimer = setTimeout(() => {
+        retryTimer = undefined;
+        probe();
+      }, waitMs);
+    }
+
+    function probe() {
+      if (settled) return;
+      let completed = false;
+      const request = http.get(`http://localhost:${port}${READY_PATH}`, (response) => {
+        if (completed || settled) {
+          response.resume();
+          return;
+        }
+        completed = true;
+        activeRequest = undefined;
+        response.resume();
+        if (response.statusCode === 200) {
+          succeeded();
+          return;
+        }
+        scheduleProbe(POLL_INTERVAL_MS);
+      });
+      request.on('error', () => {
+        if (completed || settled) return;
+        completed = true;
+        activeRequest = undefined;
+        scheduleProbe(POLL_INTERVAL_MS);
+      });
+      request.setTimeout(Math.min(1000, Math.max(1, deadline - Date.now())), () => {
+        if (completed || settled) return;
+        completed = true;
+        activeRequest = undefined;
+        request.destroy();
+        scheduleProbe(POLL_INTERVAL_MS);
+      });
+      activeRequest = request;
+    }
+
+    function onOutput(chunk) {
+      if (settled) return;
+      if (String(chunk).includes(readyMarker)) probe();
+    }
+
+    function onErrorOutput() {}
+
+    function onError(error) {
+      fail(`Test server child failed before readiness: ${error.message}`);
+    }
+
+    function onExit() {
+      fail(`Test server child exited before readiness (${childStatus()}).`);
+    }
+
+    if (child.exitCode !== null || child.signalCode !== null) {
+      fail(`Test server child had already exited (${childStatus()}).`);
+      return;
+    }
+
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', onOutput);
+    child.stderr?.on('data', onErrorOutput);
+    child.once('error', onError);
+    child.once('exit', onExit);
+    retryTimer = setTimeout(() => {
+      retryTimer = undefined;
+      fail(
+        `Test server child did not announce ${readyMarker} within ${timeoutMs}ms; `
+        + 'refusing to use another listener.'
+      );
+    }, timeoutMs);
+  });
+}
+
+async function globalSetup({ port = TEST_SERVER_PORT } = {}) {
   // Playwright specs also launch isolated test-server children. Keep every
   // process in this test-only tree on the same explicit dark rollout state.
   Object.assign(process.env, DARK_ROLLOUT_ENVIRONMENT);
@@ -156,7 +288,7 @@ async function globalSetup() {
   const child = spawn(
     ...resolveTestServerCommand(),
     {
-      env: buildTestServerEnvironment(),
+      env: buildTestServerEnvironment(undefined, port),
       stdio: ['ignore', 'pipe', 'pipe'],
       detached: true,
     }
@@ -178,18 +310,20 @@ async function globalSetup() {
   // Store the child process so teardown can kill it
   globalThis.__testServerProcess = child;
 
-  // Wait for the server to be ready before returning control to Playwright
-  await waitForServer(TEST_SERVER_PORT, READY_TIMEOUT_MS);
+  // Wait for this spawned process to own the port before returning control to
+  // Playwright. A foreign HTTP 200 must never satisfy global setup.
+  await waitForOwnedServer(child, port, READY_TIMEOUT_MS);
 
-  console.log(`[global-setup] Test server is ready on port ${TEST_SERVER_PORT}`);
+  console.log(`[global-setup] Test server is ready on port ${port}`);
 
   // UI tests do not need a server-side session while SKIP_AUTH=true. Use a
   // deterministic localStorage session so auth/logout tests cannot invalidate
   // the shared browser storage state for unrelated UI tests.
-  writeDefaultAuthState();
+  writeDefaultAuthState(port);
   console.log('[global-setup] Auth state saved with test bypass token for Grace');
 }
 
 module.exports = globalSetup;
 module.exports.buildTestServerEnvironment = buildTestServerEnvironment;
 module.exports.waitForServer = waitForServer;
+module.exports.waitForOwnedServer = waitForOwnedServer;

backend/e2e/global-teardown.js

@@ -6,8 +6,14 @@ module.exports = async function globalTeardown() {
     return;
   }
 
+  if (child.exitCode !== null || child.signalCode !== null) {
+    console.log('[global-teardown] Test server already stopped.');
+    return;
+  }
+
   await new Promise((resolve) => {
     let settled = false;
+    let forceKillTimer;
 
     function done() {
       if (settled) return;
@@ -29,7 +35,7 @@ module.exports = async function globalTeardown() {
     }
 
     // Force-kill after 5 seconds if SIGTERM is not enough
-    const forceKillTimer = setTimeout(() => {
+    forceKillTimer = setTimeout(() => {
       if (!settled) {
         console.warn('[global-teardown] Force-killing test server process group after timeout.');
         try {

backend/e2e/planning-surfaces-design.spec.js

@@ -7,7 +7,7 @@ const path = require("path");
 const { createDocsCacheRoot } = require("./helpers/docs-content-root");
 const { resolveTestServerCommand } = require("./helpers/tsx-launcher");
 
-const screenshots = path.resolve(__dirname, "..", "..", ".tmp", "screenshots", "planning-surfaces");
+const screenshots = path.resolve(__dirname, "..", "..", ".tmp", "screenshots", "issue-198");
 const PORT = 3197;
 const BASE = `http://localhost:${PORT}`;
 let server;
@@ -135,6 +135,7 @@ test("Newsletter is a readable, responsive planning queue in light and dark them
   await expect(surface.getByText("An open slot needs booking soon")).toBeVisible();
   await expect(surface.getByText("near-term-open-unbooked")).toHaveCount(0);
   await expectNoPageOverflow(page, 1440);
+  await expect(surface).toHaveCSS("gap", "20px");
   await expectExactPalette(page, false);
   const accessibility = await new AxeBuilder({ page }).include(".newsletter-surface").analyze();
   expect(accessibility.violations.filter((violation) => ["critical", "serious"].includes(violation.impact))).toEqual([]);
@@ -151,9 +152,14 @@ test("Newsletter is a readable, responsive planning queue in light and dark them
   await page.setViewportSize({ width: 820, height: 900 });
   await expect(surface).toHaveCSS("gap", "16px");
   await expectNoPageOverflow(page, 820);
+  await page.screenshot({ path: path.join(screenshots, "newsletter-820-dark.png"), animations: "disabled" });
   await page.setViewportSize({ width: 620, height: 844 });
   expect(await surface.locator(".planner-filter-fields").evaluate((element) => getComputedStyle(element).gridTemplateColumns.split(" ").length)).toBe(2);
   await expectNoPageOverflow(page, 620);
+  await page.setViewportSize({ width: 420, height: 844 });
+  expect(await surface.locator(".planner-filter-fields").evaluate((element) => getComputedStyle(element).gridTemplateColumns.split(" ").length)).toBe(1);
+  await expectNoPageOverflow(page, 420);
+  await page.screenshot({ path: path.join(screenshots, "newsletter-420-dark.png"), animations: "disabled" });
 
   await page.setViewportSize({ width: 390, height: 844 });
   expect(await surface.locator(".planner-filter-fields").evaluate((element) => getComputedStyle(element).gridTemplateColumns.split(" ").length)).toBe(1);
@@ -174,8 +180,10 @@ test("Calendar keeps planner hierarchy and becomes a one-column agenda on mobile
   await expect(surface.getByText("Community webinar").first()).toBeVisible();
   await expect(surface.getByText("Activity overlaps a school holiday")).toBeVisible();
   await expect(surface.getByText("school-holiday-overlap")).toHaveCount(0);
-  await expect(surface.locator(".calendar-grid .calendar-day")).toHaveCount(42);
+  await expect(surface.locator(".calendar-weeks > .calendar-week")).toHaveCount(6);
+  await expect(surface.locator(".calendar-weeks > .calendar-week > section.calendar-day")).toHaveCount(42);
   await expectNoPageOverflow(page, 1440);
+  await expect(surface).toHaveCSS("gap", "20px");
   await expectExactPalette(page, false);
   const accessibility = await new AxeBuilder({ page }).include(".calendar-surface").analyze();
   expect(accessibility.violations.filter((violation) => ["critical", "serious"].includes(violation.impact))).toEqual([]);
@@ -188,20 +196,45 @@ test("Calendar keeps planner hierarchy and becomes a one-column agenda on mobile
   await page.screenshot({ path: path.join(screenshots, "calendar-1440-dark.png"), animations: "disabled" });
 
   await page.setViewportSize({ width: 820, height: 900 });
+  await expect(surface).toHaveCSS("gap", "16px");
   expect(await surface.locator(".calendar-grid").evaluate((element) => getComputedStyle(element).gridTemplateColumns.split(" ").length)).toBe(1);
   await expectNoPageOverflow(page, 820);
+  await page.screenshot({ path: path.join(screenshots, "calendar-820-dark.png"), animations: "disabled" });
   await page.setViewportSize({ width: 620, height: 844 });
   expect(await surface.locator(".planner-filter-fields").evaluate((element) => getComputedStyle(element).gridTemplateColumns.split(" ").length)).toBe(2);
   await expectNoPageOverflow(page, 620);
+  await page.setViewportSize({ width: 420, height: 844 });
+  expect(await surface.locator(".planner-filter-fields").evaluate((element) => getComputedStyle(element).gridTemplateColumns.split(" ").length)).toBe(1);
+  await expectNoPageOverflow(page, 420);
+  await page.screenshot({ path: path.join(screenshots, "calendar-420-dark.png"), animations: "disabled" });
 
   await page.setViewportSize({ width: 390, height: 844 });
   expect(await surface.locator(".planner-filter-fields").evaluate((element) => getComputedStyle(element).gridTemplateColumns.split(" ").length)).toBe(1);
   await surface.locator("select[data-view]").selectOption("week");
-  await expect(surface.locator(".calendar-grid .calendar-day")).toHaveCount(7);
+  await expect(surface.locator(".calendar-weeks > .calendar-week")).toHaveCount(1);
+  await expect(surface.locator(".calendar-weeks > .calendar-week > section.calendar-day")).toHaveCount(7);
+  const swipeHint = surface.locator(".calendar-mobile-hint");
+  await expect(swipeHint).toBeVisible();
+  await expect(swipeHint).toContainText("Swipe each week horizontally");
+  const weekScroll = await surface.locator(".calendar-week").first().evaluate((element) => ({
+    clientWidth: element.clientWidth,
+    overflowX: getComputedStyle(element).overflowX,
+    scrollWidth: element.scrollWidth,
+  }));
+  expect(weekScroll.overflowX).toBe("auto");
+  expect(weekScroll.scrollWidth).toBeGreaterThan(weekScroll.clientWidth);
   await page.evaluate(() => window.scrollTo(0, 0));
   await useTheme(page, false);
   await expectNoPageOverflow(page, 390);
-  await page.screenshot({ path: path.join(screenshots, "calendar-390-light.png"), animations: "disabled" });
+  await page.screenshot({
+    path: path.join(screenshots, "calendar-390-light.png"),
+    animations: "disabled",
+    fullPage: true,
+  });
   await useTheme(page, true);
-  await page.screenshot({ path: path.join(screenshots, "calendar-390-dark.png"), animations: "disabled" });
+  await page.screenshot({
+    path: path.join(screenshots, "calendar-390-dark.png"),
+    animations: "disabled",
+    fullPage: true,
+  });
 });